VERSION FOUR

www.discreet.com 4

MAXSCRIPT REFERENCE

January 2001
 Copyright © 2001 Autodesk, Inc.
All Rights Reserved

This publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose.
AUTODESK, INC. MAKES NO WARRANTY, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, REGARDING THESE MATERIALS AND MAKES
SUCH MATERIALS AVAILABLE SOLELY ON AN "AS-IS" BASIS.
IN NO EVENT SHALL AUTODESK, INC. BE LIABLE TO ANYONE FOR SPECIAL, COLLATERAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES IN CONNECTION WITH OR ARISING OUT OF PURCHASE OR USE OF THESE MATERIALS. THE SOLE AND EXCLUSIVE
LIABILITY TO AUTODESK, INC., REGARDLESS OF THE FORM OF ACTION, SHALL NOT EXCEED THE PURCHASE PRICE OF THE
MATERIALS DESCRIBED HEREIN.
Autodesk, Inc. reserves the right to revise and improve its products as it sees fit. This publication describes the state of this product at
the time of its publication, and may not reflect the product at all times in the future.
Autodesk Trademarks
The following are registered trademarks of Autodesk, Inc., in the USA and/or other countries: 3D Plan, 3D Props, 3D Studio, 3D Studio
MAX, 3D Studio VIZ, 3DSurfer, ActiveShapes, ActiveShapes (logo), Actrix, ADE, ADI, Advanced Modeling Extension, AEC Authority
(logo), AEC-X, AME, Animator Pro, Animator Studio, ATC, AUGI, AutoCAD, AutoCAD Data Extension, AutoCAD Development System,
AutoCAD LT, AutoCAD Map, Autodesk, Autodesk Animator, Autodesk (logo), Autodesk MapGuide, Autodesk University, Autodesk View,
Autodesk WalkThrough, Autodesk World, AutoLISP, AutoShade, AutoSketch, AutoSurf, AutoVision, Biped, bringing information down
to earth, CAD Overlay, Character Studio, Design Companion, Drafix, Education by Design, Generic, Generic 3D Drafting, Generic
CADD, Generic Software, Geodyssey, Heidi, HOOPS, Hyperwire, Inside Track, Kinetix, MaterialSpec, Mechanical Desktop, Multimedia
Explorer, NAAUG, ObjectARX, Office Series, Opus, PeopleTracker, Physique, Planix, Powered with Autodesk Technology, Powered with
Autodesk Technology (logo), RadioRay, Rastation, Softdesk, Softdesk (logo), Solution 3000, Tech Talk, Texture Universe, The AEC
Authority, The Auto Architect, TinkerTech, VISION*, WHIP!, WHIP! (logo), Woodbourne, WorkCenter, and World-Creating Toolkit.
The following are trademarks of Autodesk, Inc., in the USA and/or other countries: 3D on the PC, 3ds max, ACAD, Advanced User
Interface, AEC Office, AME Link, Animation Partner, Animation Player, Animation Pro Player, A Studio in Every Computer, ATLAST, Auto-
Architect, AutoCAD Architectural Desktop, AutoCAD Architectural Desktop Learning Assistance, AutoCAD Learning Assistance, AutoCAD
LT Learning Assistance, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface, Autodesk Animator Clips, Autodesk
Animator Theatre, Autodesk Device Interface, Autodesk Inventor, Autodesk PhotoEDIT, Autodesk Point A (logo), Autodesk Software
Developer's Kit, Autodesk View DwgX, AutoFlix, AutoPAD, AutoSnap, AutoTrack, Built with ObjectARX (logo), ClearScale, Colour
Warper, Combustion, Concept Studio, Content Explorer, cornerStone Toolkit, Dancing Baby (image), Design 2000 (logo),
DesignCenter, Design Doctor, Designer's Toolkit, DesignProf, DesignServer, Design Your World, Design Your World (logo), Discreet,
DWG Linking, DWG Unplugged, DXF, Extending the Design Team, FLI, FLIC, GDX Driver, Generic 3D, Heads-up Design, Home Series,
i-drop, Jobnet, Kinetix (logo), Lightscape, ObjectDBX, onscreen onair online, Ooga-Chaka, Photo Landscape, Photoscape, Plugs and
Sockets, PolarSnap, Pro Landscape, QuickCAD, Real-Time Roto, Render Queue, SchoolBox, Simply Smarter Diagramming, SketchTools,
Sparks, Suddenly Everything Clicks, Supportdesk, The Dancing Baby, Transform Ideas Into Reality, Visual LISP, Visual Syllabus, VIZable,
Volo, Where Design Connects, and Whereware.

Third-Party Trademarks
All other brand names, product names, or trademarks belong to their respective holders.

Third-Party Software Program Credits

ACIS® Copyrighted © 2000, SPATIAL TECHNOLOGY INC.
© 2000 Microsoft Corporation. All rights reserved.
License management portions of the product Copyrighted © 2000 C-Dilla Ltd. All rights reserved.
Portions Copyrighted © 2000 Intel Corporation
Portions Copyrighted © 2000 Blur Studio, Inc.
Portions Copyrighted © 1989-2000 mental images GmbH & Co. KG Berlin, Germany
Portions developed by Digimation, Inc. for the exclusive use of Autodesk, Inc.
Portions developed by Lyric Media, Inc. for the exclusive use of Autodesk, Inc.
Portions of this software are based on the copyrighted work of the Independent JPEG Group.
Wise for Installation System for Windows Installer © 2000 Wise Solutions, Inc. All rights reserved.
AnswerWorks® Copyright © 1997-2000 WexTech Systems, Inc. Portions of this software © Lernout & Hauspie, Inc. All rights reserved.
GOVERNMENT USE

Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in FAR 12.212 (Commercial Computer
Software-Restricted Rights) and DFAR 227.7202 (Rights in Technical Data and Computer Software), as applicable.
Contents

Introduction........................................................................................................xxxi
3ds max 4 MAXScript Online Reference ................................................................................. xxxi
MAXScript Overview .............................................................................................................. xxxii
Using the MAXScript Documentation .................................................................................. xxxiii
The MAXScript Utility Panel ...................................................................................................... xxxiv
The MAXScript Listener Window ......................................................................................... xxxvi
Using the MAXScript Listener .............................................................................................. xxxvii
Listener Commands ............................................................................................................ xxxviii
Using the ‘?’ Symbol................................................................................................................... xli
Turning On the Listener Log...................................................................................................... xli
Controlling the Listener Contents and the Insertion Point ..................................................... xlii
The MAXScript Editor Windows .............................................................................................. xliv
MAXScript Editor Commands.................................................................................................. xlvi
Running Scripts ........................................................................................................................ xlix
Accessing Scripted Utilities............................................................................................................ l
The Macro Recorder....................................................................................................................... l
General MAXScript Topics...............................................................................................................lii
Error Messages ............................................................................................................................ liii
Aborting Execution with the ESC Key ........................................................................................ lv
MAXScript Desktop State ........................................................................................................... lvi
Startup Scripts............................................................................................................................. lvi
Running Scripts from the Command Line................................................................................ lvii
Source Code Layout and Continuation Lines ........................................................................... lvii
Including Scripts Within Scripts ................................................................................................ lix
Encrypting Script Files ................................................................................................................. lx
Syntax Definitions in This Document ..............................................................................................lx
Objects and Classes in Object-Oriented Programming ................................................................lxii
Inheritance and Polymorphism ............................................................................................... lxiii
Properties, Methods, Operators, and Literals ........................................................................... lxiv
iv Contents

Chapter 1 What’s New in 3ds max 4 MAXScript .................................................... 1

What’s New in 3ds max 4 MAXScript......................................................................................... 1
version 4 MAXScript New Features ................................................................................................. 9
Action Manager ............................................................................................................................... 9
ActiveX Controls in MAXScript Rollouts........................................................................................ 10
Asset Browser................................................................................................................................. 22
Asset Browser enhancements ..................................................................................................... 22
Bones.............................................................................................................................................. 23
Access to the node bone properties and methods ..................................................................... 23
Bone Creation............................................................................................................................. 25
Cache Modifiers ............................................................................................................................. 26
Point Cache Modifier ..................................................................................................................... 26
CallBack Notification Codes........................................................................................................... 27
Notify Callbacks for Animate button on and off Transitions.................................................... 27
RenderEffects Progress Callback Mechanism ............................................................................ 28
General Event Callback Mechanism .......................................................................................... 29
Color Manager ............................................................................................................................... 35
Combustion.................................................................................................................................... 38
Constraints ..................................................................................................................................... 39
Path Constraint .......................................................................................................................... 39
LookAt Constraint ...................................................................................................................... 40
Orientation Constraint Controller............................................................................................. 40
Position Constraint .................................................................................................................... 41
Link Controller for Constraints ................................................................................................. 42
Controller Functions for use with Constraint Assignments ...................................................... 42
Context Filters................................................................................................................................ 43
Custom Attributes.......................................................................................................................... 45
Scripted Custom Attributes ........................................................................................................ 45
Depth of Field ................................................................................................................................ 54
Edit Mesh ....................................................................................................................................... 54
ApplyOperation function ........................................................................................................... 54
Editable Patch ................................................................................................................................ 55
Patches ........................................................................................................................................ 55
Filters.............................................................................................................................................. 59
class id filter ................................................................................................................................ 59
Selection Filter ............................................................................................................................ 61
i-drop - drag and drop................................................................................................................... 62
Interfaces........................................................................................................................................ 67
Core Interfaces............................................................................................................................ 70
Other Interfaces .......................................................................................................................... 71
Inverse Kinematics ......................................................................................................................... 73
HD IK controller chains can be assigned to existing hierarchies .............................................. 73
IKLimb Solver ............................................................................................................................. 74
Materials ........................................................................................................................................ 75
Multi/Sub Material......................................................................................................................... 75
Menu Manager .............................................................................................................................. 75
 Contents v

Mesher ........................................................................................................................................... 82
Network Render Interface ............................................................................................................. 82
Node Handles................................................................................................................................. 83
Node vertexColorType................................................................................................................... 83
OLE Automation............................................................................................................................. 84
MAXScript.reg - Registery file..................................................................................................... 84
Parameter Wiring........................................................................................................................... 85
Plug-In Manager ............................................................................................................................ 86
Portable Licence Manager ............................................................................................................. 87
maxOps....................................................................................................................................... 87
Quad Menu .................................................................................................................................... 90
Reactors.......................................................................................................................................... 91
Reactor controller ....................................................................................................................... 91
Render Element Manager .............................................................................................................. 92
Scripted Plug-Ins ............................................................................................................................ 93
type:#integer parameters in scripted plug-in parameter blocks ................................................ 93
Scripted Plug-in Events............................................................................................................... 93
Scripted Cameras ........................................................................................................................... 94
Scripted Controllers ....................................................................................................................... 95
dependsOn For Scripted Controllers .......................................................................................... 95
Matrix3 Scripted Controller ....................................................................................................... 96
Scripted Manipulators ................................................................................................................... 97
Scripted Objects........................................................................................................................... 106
on detachedFromNode For Object Scripted Plug-ins ............................................................... 106
Scripted RenderEffects................................................................................................................. 107
RenderEffects Progress Callback Mechanism .......................................................................... 107
Scripted Rollouts .......................................................................................................................... 108
Multi-line editText UI items in Scripted Rollouts .................................................................... 108
Skin............................................................................................................................................... 109
Joint Angle Morph ....................................................................................................................... 109
Spring Controller ......................................................................................................................... 109
SubObject Mode .......................................................................................................................... 112
System Tools ................................................................................................................................ 112
Trackbar Interface ........................................................................................................................ 113
Trackviews.................................................................................................................................... 114
Visual MAXScript ......................................................................................................................... 117
Xref Objects ................................................................................................................................. 120
Zip-file Script Packages ................................................................................................................ 122
version 4 MAXScript Language Improvements .......................................................................... 127
Additional Keyword Parameter On pickObject() forceListenerFocus: ..................................... 127
Affect Region Function............................................................................................................. 127
“Apropos” and “ShowProperties” and now “Help” and “Show” ............................................ 128
BinStream for Binary Reading and Writing ............................................................................. 128
By Reference Parameter Passing ............................................................................................... 129
C++-style bracketing comments ............................................................................................... 131
Coercion of bitArray to array and integer arrays to bitArrays ................................................. 132
Command line -U MAXScript startup scripts .......................................................................... 133
vi Contents

Detecting Deleted Nodes .......................................................................................................... 133

Dereferencing Operator ............................................................................................................ 133
forceUpdate Function added to UVWUnwrap......................................................................... 134
hasProperty() function ............................................................................................................. 135
Improved the Performance of Iterating and Indexing the ‘selection’ and ‘$’ Object Sets ...... 135
Readable/Writable Checks........................................................................................................ 135
isValidNode .............................................................................................................................. 136
RubberBanding in pickObject() Function ................................................................................ 136
SetDir ........................................................................................................................................ 136
Shortcut system replaced.......................................................................................................... 137
startObjectCreation()................................................................................................................ 138
Subanim Indexing Operator, [], on MAX Objects Now Takes Subanim Names...................... 139
superclasses read-only global variable...................................................................................... 139
Symbolic Pathnames ................................................................................................................ 140
System Information.................................................................................................................. 141
The Super Class ID and the Class ID ........................................................................................ 141
validModifier() function........................................................................................................... 142
Visible Class For ‘&’ Reference Values...................................................................................... 142
Controllers ................................................................................................................................... 143
List Controller .......................................................................................................................... 143
mapKeys() method ................................................................................................................... 144
moveKeys function................................................................................................................... 145
Geometry, Modifiers, Space Warps............................................................................................. 146
Hose - superclass: GeometryClass ............................................................................................ 146
Drag - superclass: SpacewarpObject ......................................................................................... 149
MultiRes - superclass: modifier................................................................................................. 153
Vortex - superclass: SpacewarpObject ...................................................................................... 156
Keys .............................................................................................................................................. 158
Object Inspector Functions .......................................................................................................... 159
Class and Object Inspector Functions Enhanced..................................................................... 159
Renderer....................................................................................................................................... 160
render() Function Re-entrant ................................................................................................... 160
SuperClasses................................................................................................................................. 161
Bitmap Manager – Function Published BMM control ............................................................. 161
Utilities, Global Utilities and Render Element plug-ins........................................................... 161
Renderer.................................................................................................................................... 162
2 New Scripted Plug-in Superclasses on apply handlers for scripted RenderEffects ................ 162
Globals and Locals ....................................................................................................................... 162
Definition Constructs Can Include Global Variable Declarations At Top Level ..................... 162
Changes to Undeclared Implicit Global Variables ................................................................... 163
Material Editor, Material and Textures ....................................................................................... 163
Accessing The Material Editor Active Slot................................................................................ 163
BitmapTex Reload and viewImage ........................................................................................... 164
BMP, PNG, JPEG and TGA I/O Interfaces ................................................................................ 164
Material Editor Access .............................................................................................................. 165
Material Level Show-in-viewport State .................................................................................... 166
showTextureMap() function .................................................................................................... 167
 Contents vii

User Interface............................................................................................................................... 168

Angle UI element...................................................................................................................... 168
CreateDialog ............................................................................................................................. 169
Curve Control........................................................................................................................... 170
getTextExtent ........................................................................................................................... 175
isActive ..................................................................................................................................... 176
keyboard.escPressed.................................................................................................................. 176
macroScript Localization Support for CUI and menu files...................................................... 176
MAX Open & Save Dialogs....................................................................................................... 177
Menu and CUI Loading............................................................................................................ 178
mtlBrowser................................................................................................................................ 180
SetBackground Method ............................................................................................................ 180
mouseTrack() Function ............................................................................................................ 180
snapMode ................................................................................................................................. 182
Spinner UI Item setKeyBrackets ............................................................................................... 182
Timer UI element ..................................................................................................................... 183
TimeSlider on/off toggle........................................................................................................... 183
Undo/Redo Dropdown Labels .................................................................................................. 184
Zoom to Bounds ....................................................................................................................... 184
Command Panels and Rollout Pages........................................................................................... 185
Customize The Order of Rollup Pages...................................................................................... 185
MAXScript Dialogs and Rollout Floaters as Extended viewports............................................. 186
Rollout .Controls Property ....................................................................................................... 187
Rollout Systems ‘category’ Mechanism .................................................................................... 188
version 4 All Const and MAXScript Functions............................................................................. 188
Definitions for MAXScript internal organization .................................................................... 188
MAXScriptFunction List ........................................................................................................... 190
Const Class ............................................................................................................................... 191
Const Generic ........................................................................................................................... 195
Const MappedGeneric.............................................................................................................. 207
Const NodeGeneric .................................................................................................................. 209
Const Primitives ....................................................................................................................... 213
Const StructDef ........................................................................................................................ 231
Const StructDef Pages ................................................................................................................. 232
AttachCtrl const StructDef ....................................................................................................... 232
autoBackup const StructDef ..................................................................................................... 232
bit const StructDef.................................................................................................................... 233
boolObj const StructDef ........................................................................................................... 233
callbacks const StructDef.......................................................................................................... 233
cui const StructDef ................................................................................................................... 234
custAttributes const StructDef.................................................................................................. 234
DOF const StructDef................................................................................................................. 234
fileProperties const StructDef ................................................................................................... 235
flexOps const StructDef............................................................................................................ 235
gw const StructDef.................................................................................................................... 235
ik const StructDef ..................................................................................................................... 237
keyboard const StructDef ......................................................................................................... 237
viii Contents

LE const StructDef .................................................................................................................... 237

LinkCtrl const StructDef........................................................................................................... 238
ListCtrl const StructDef ............................................................................................................ 238
ListCtrl const StructDef ............................................................................................................ 238
logsystem const StructDef ........................................................................................................ 239
macros const StructDef............................................................................................................. 239
mapPaths const StructDef ........................................................................................................ 239
meshop const StructDef ........................................................................................................... 239
meshOps const StructDef ......................................................................................................... 243
modPanel const StructDef ........................................................................................................ 244
mouse const StructDef.............................................................................................................. 244
mtlBrowser const StructDef...................................................................................................... 244
options const StructDef ............................................................................................................ 245
patch const StructDef ............................................................................................................... 245
patchOps const StructDef......................................................................................................... 247
persistents const StructDef ....................................................................................................... 247
polyop const StructDef............................................................................................................. 248
polyOps const StructDef........................................................................................................... 251
preferences const StructDef ...................................................................................................... 252
refs const StructDef .................................................................................................................. 252
scanlineRender const StructDef ............................................................................................... 252
schematicView const StructDef ................................................................................................ 252
skinOps const StructDef ........................................................................................................... 253
snapMode const StructDef ....................................................................................................... 254
splineOps const StructDef ........................................................................................................ 255
sysInfo const StructDef............................................................................................................. 255
systemTools const StructDef .................................................................................................... 256
terrainOps const StructDef ....................................................................................................... 256
timeConfiguration const StructDef.......................................................................................... 256
toolMode const StructDef ........................................................................................................ 257
trackbar const StructDef ........................................................................................................... 257
trackView const StructDef ........................................................................................................ 257
units const StructDef ................................................................................................................ 258
viewport const StructDef .......................................................................................................... 258
WAVsound const StructDef...................................................................................................... 258
xrefPaths const StructDef ......................................................................................................... 259
xrefs const Structdef ................................................................................................................. 259
version 4 New Classes .................................................................................................................. 259
New Classes in version 4 .......................................................................................................... 259
New Classes in version 4 Pages ................................................................................................... 262
Additive_Euler_XYZ - superclass: RotationController ............................................................. 262
Alpha - superclass: MAXObject ................................................................................................ 262
alphaRenderElement - superclass: MAXObject ........................................................................ 263
Atmosphere - superclass: MAXObject ...................................................................................... 264
atmosphereRenderElement - superclass: MAXObject .............................................................. 265
AutomaticAdaptiveExposureControl - superclass: MAXObject ............................................... 267
Automatic_Exposure_Control - superclass: MAXObject.......................................................... 268
 Contents ix

BackgroundRenderElement - superclass: MAXObject.............................................................. 269

bgndRenderElement - superclass: MAXObject......................................................................... 270
BlendRenderElement - superclass: MAXObject........................................................................ 271
clrShadowRenderElement - superclass: MAXObject ................................................................ 272
Colored_Shadow - superclass: MAXObject .............................................................................. 273
Combustion.coordinates - superclass: MAXObject.................................................................. 274
Cone_Angle - superclass: helper ............................................................................................... 276
ConeAngleManip - superclass: helper ...................................................................................... 277
ConvertToPatch - superclass: modifier .................................................................................... 278
DeletePatch - superclass: modifier............................................................................................ 279
Diffuse - superclass: MAXObject .............................................................................................. 279
diffuseRenderElement - superclass: MAXObject ...................................................................... 280
Drag - superclass: SpacewarpObject ......................................................................................... 281
emissionRenderElement - superclass: MAXObject................................................................... 285
FloatList - superclass: FloatController ...................................................................................... 286
FloatReactor - superclass: FloatController ................................................................................ 287
Hose - superclass: GeometryClass ............................................................................................ 287
HSDS_Modifier - superclass: modifier ...................................................................................... 290
HSDSObject - superclass: modifier ........................................................................................... 292
imageMotionBlur - superclass: renderEffect............................................................................. 294
Link - superclass: Matrix3Controller ........................................................................................ 294
Link.link_params - superclass: MAXObject.............................................................................. 295
Link_Constraint - superclass: Matrix3Controller..................................................................... 295
Link Constraint.link params - superclass: MAXObject ............................................................ 296
LinkedXForm - superclass: modifier......................................................................................... 297
LookAt_Constraint - superclass: RotationController ............................................................... 297
Mesher - superclass: GeometryClass......................................................................................... 298
meshsmooth - superclass: modifier .......................................................................................... 298
Motion_Blur - superclass: renderEffect..................................................................................... 302
MultiRes - superclass: modifier................................................................................................. 302
Normalize_Spl - superclass: modifier ....................................................................................... 305
Orientation_Constraint - superclass: RotationController........................................................ 306
particleMesher - superclass: GeometryClass ............................................................................ 306
Patch_Select - superclass: modifier ........................................................................................... 307
Path_Constraint - superclass: PositionController .................................................................... 307
PDynaflector - superclass: SpacewarpObject ............................................................................ 309
Plane_Angle - superclass: helper............................................................................................... 310
PlaneAngleManip - superclass: helper...................................................................................... 311
Point3List - superclass: Point3Controller................................................................................. 312
Point3Reactor - superclass: Point3Controller .......................................................................... 312
Point3Spring - superclass: Point3Controller ............................................................................ 313
Point_Cache - superclass: modifier .......................................................................................... 314
Point_CacheSpacewarpModifier - superclass: SpacewarpModifier .......................................... 315
PointCache - superclass: modifier ............................................................................................ 316
PointCacheWSM - superclass: SpacewarpModifier .................................................................. 317
PointHelperObj - superclass: helper ......................................................................................... 318
Poly_Select - superclass: modifier ............................................................................................. 319
x Contents

Position_Constraint - superclass: PositionController .............................................................. 320

PositionList - superclass: PositionController............................................................................ 321
PositionReactor - superclass: PositionController ..................................................................... 321
PositionSpring - superclass: PositionController ....................................................................... 321
PSpawnflector - superclass: SpacewarpObject .......................................................................... 322
Reflection - superclass: MAXObject ......................................................................................... 323
reflectionRenderElement - superclass: MAXObject ................................................................. 324
Refraction - superclass: MAXObject ......................................................................................... 326
refractionRenderElement - superclass: MAXObject ................................................................. 327
RingWave - superclass: GeometryClass .................................................................................... 328
RotationList - superclass: RotationController .......................................................................... 328
RotationReactor - superclass: RotationController .................................................................... 328
ScaleList - superclass: ScaleController ...................................................................................... 328
ScaleReactor - superclass: ScaleController ................................................................................ 329
SDynaflector - superclass: SpacewarpObject ............................................................................ 329
section - superclass: shape ........................................................................................................ 330
Self_Illumination - superclass: MAXObject.............................................................................. 331
ShadowRenderElement - superclass: MAXObject .................................................................... 332
sliderManipulator - superclass: helper ..................................................................................... 333
Specular - superclass: MAXObject ............................................................................................ 334
specularRenderElement - superclass: MAXObject.................................................................... 335
SpringPoint3Controller - superclass: Point3Controller ........................................................... 336
SpringPositionController - superclass: PositionController ...................................................... 337
SSpawnflector - superclass: SpacewarpObject .......................................................................... 338
transform_script - superclass: Matrix3Controller .................................................................... 339
Turn_to_Mesh - superclass: modifier ....................................................................................... 340
Turn_to_Patch - superclass: modifier ....................................................................................... 342
Turn_to_Poly - superclass: modifier ......................................................................................... 343
UDynaDeflector - superclass: SpacewarpObject....................................................................... 345
USpawnDeflector - superclass: SpacewarpObject..................................................................... 346
UVWUnwrap - superclass: modifier ......................................................................................... 347
Vortex - superclass: SpacewarpObject ...................................................................................... 347
Z_Depth - superclass: MAXObject............................................................................................ 350
ZRenderElement - superclass: MAXObject ............................................................................... 351
version 4 MAXScript Interfaces ................................................................................................... 352
Core Interfaces............................................................................................................................. 352
Core Interface Pages.................................................................................................................... 353
Interface: actionMan ................................................................................................................ 353
Interface: BoneSys .................................................................................................................... 354
Interface: browserMgr............................................................................................................... 355
Interface: cmdPanel .................................................................................................................. 356
Interface: colorMan .................................................................................................................. 356
Interface: dragAndDrop............................................................................................................ 362
Interface: HDIKSys.................................................................................................................... 365
Interface: IKSys ......................................................................................................................... 365
Interface: manip ....................................................................................................................... 366
Interface: maxOps .................................................................................................................... 368
 Contents xi

Interface: medit ........................................................................................................................ 371

Interface: menuMan ................................................................................................................. 372
Interface: msZip........................................................................................................................ 378
Interface: NetRender................................................................................................................. 379
Working with the manager ...................................................................................................... 379
Working with jobs.................................................................................................................... 384
Working with servers ............................................................................................................... 398
Working with groups ............................................................................................................... 401
Netstatus ................................................................................................................................... 402
Examples:.................................................................................................................................. 404
Interface: NullInterface ............................................................................................................ 409
Interface: objXRefs ................................................................................................................... 409
Interface: paramWire................................................................................................................ 410
Interface: pluginManager ......................................................................................................... 414
Interface: quadMenuSettings ................................................................................................... 414
Interface: rollup ........................................................................................................................ 427
Interface: SceneExposureControl ............................................................................................. 427
Interface: SceneRadiosity.......................................................................................................... 428
Interface: timeSlider ................................................................................................................. 428
Interface: trackviews ................................................................................................................. 429
Other Interfaces ........................................................................................................................... 432
Other Interface Pages .................................................................................................................. 434
bitmapTex interfaces: ............................................................................................................... 434
Block_Control interfaces: ......................................................................................................... 435
BMP interfaces: ......................................................................................................................... 437
Flex interfaces: .......................................................................................................................... 438
float_list interfaces:................................................................................................................... 441
Float Reactor interfaces: ........................................................................................................... 443
Float_Wire interfaces: ............................................................................................................... 448
FloatList interfaces:................................................................................................................... 450
FloatReactor interfaces: ............................................................................................................ 452
HSDS_Modifier interfaces:........................................................................................................ 453
HSDSObject interfaces:............................................................................................................. 453
IKChainControl interfaces: ...................................................................................................... 453
imageMotionBlur interfaces: .................................................................................................... 454
JPEG interfaces:......................................................................................................................... 454
Link interfaces: ......................................................................................................................... 455
Link_Constraint interfaces: ...................................................................................................... 455
LookAt_Constraint interfaces:.................................................................................................. 455
Motion_Blur interfaces: ............................................................................................................ 462
Orientation_Constraint interfaces: .......................................................................................... 462
path interfaces: ......................................................................................................................... 462
Path_Constraint interfaces: ...................................................................................................... 468
Plugin_Manager interfaces: ...................................................................................................... 473
Portable_Network_Graphics interfaces: ................................................................................... 473
point3_list interfaces: ............................................................................................................... 475
Point3_Reactor interfaces: ........................................................................................................ 477
xii Contents

Point3_Wire interfaces: ............................................................................................................ 477

Point3List interfaces: ................................................................................................................ 479
Point3Reactor interfaces:.......................................................................................................... 481
Point3Spring interfaces: ........................................................................................................... 482
Point_Cache interfaces: ............................................................................................................ 484
Point_CacheSpacewarpModifier interfaces: ............................................................................. 485
PointCache interfaces:.............................................................................................................. 486
PointCacheWSM interfaces: ..................................................................................................... 487
Position_Constraint interfaces: ................................................................................................ 488
position_list interfaces:............................................................................................................. 490
Position_Reactor interfaces: ..................................................................................................... 492
Position_Wire interfaces:.......................................................................................................... 492
PositionList interfaces: ............................................................................................................. 494
PositionReactor interfaces: ....................................................................................................... 496
PositionSpring interfaces:......................................................................................................... 497
radiusManip interfaces: ............................................................................................................ 500
RenderElementMgr interfaces: ................................................................................................. 503
rotation_list interfaces:............................................................................................................. 505
Rotation_Reactor interfaces:..................................................................................................... 507
Rotation_Wire interfaces: ......................................................................................................... 508
RotationList interfaces:............................................................................................................. 510
RotationReactor interfaces: ...................................................................................................... 512
scale_list interfaces: .................................................................................................................. 513
Scale_Reactor interfaces:........................................................................................................... 515
Scale_Wire interfaces: ............................................................................................................... 515
ScaleList interfaces:................................................................................................................... 517
ScaleReactor interfaces: ............................................................................................................ 519
sliderManipulator interfaces: ................................................................................................... 520
SpringPoint3Controller interfaces:........................................................................................... 523
SpringPositionController interfaces: ........................................................................................ 526
Targa interfaces:........................................................................................................................ 529
Unwrap_UVW interfaces: ......................................................................................................... 530
uvwMappingHeightManip interfaces: ..................................................................................... 551
uvwMappingLengthManip interfaces: ..................................................................................... 555
uvwMappingUTileManip interfaces:........................................................................................ 558
uvwMappingVTileManip interfaces: ........................................................................................ 562
uvwMappingWidthManip interfaces: ...................................................................................... 565
UVWUnwrap interfaces:........................................................................................................... 568
Float_Wire interfaces: ............................................................................................................... 569
Point3_Wire interfaces: ............................................................................................................ 570
Rotation_Wire interfaces: ......................................................................................................... 572
Scale_Wire interfaces: ............................................................................................................... 574
 Contents xiii

Chapter 2 Learning MAXScript ........................................................................... 577

Accessing MAXScript ................................................................................................................ 579
Source Code Layout.................................................................................................................. 580
Entering Information into MAXScript ..................................................................................... 582
Assigning Variables................................................................................................................... 585
Mathematical Operations in MAXScript.................................................................................. 588
Drawing a Box with MAXScript ............................................................................................... 591
Modifying the Box.................................................................................................................... 593
Applying Standard Transformations ........................................................................................ 598
More Box Transformations....................................................................................................... 603
Controlling Program Flow in Scripts........................................................................................ 607
Defining Custom Functions ..................................................................................................... 614
Structure Definitions ................................................................................................................ 618
3ds max Commands in MAXScript.......................................................................................... 620
Saving your Commands in a Script File ................................................................................... 621
Loading and Running your Script File ..................................................................................... 621
Loading Other Scripts............................................................................................................... 623
Learning MAXScript by Walking Through a Script ................................................................. 623
Learning MAXScript with the Macro Recorder ........................................................................ 624
The Scripts Included with 3ds max .......................................................................................... 624
Chapter 3 Reserved Keywords, Symbols, Punctuation and Variables ................ 625
Language Reserved Keywords ................................................................................................... 625
Punctuation and Symbols ........................................................................................................ 627
Reserved Global Variables ........................................................................................................ 628
Predefined Globals.................................................................................................................... 629
3ds max System Globals ........................................................................................................... 630
MAXScript System Globals ....................................................................................................... 640
Chapter 4 Variables - Assignment and Scope ..................................................... 643
Variable Assignment................................................................................................................. 643
Scope of Variables..................................................................................................................... 646
Persistent Global Variables ....................................................................................................... 651
Type-Free Variables................................................................................................................... 653
Reference Assignment .............................................................................................................. 653
Memory Allocation and Garbage Collection ........................................................................... 655
Manual Garbage Collection ..................................................................................................... 656
Chapter 5 Names, Literal Constants, and Expressions ....................................... 657
Names .......................................................................................................................................... 657
Literal Constants .......................................................................................................................... 659
Number Literals ........................................................................................................................ 660
String Literals............................................................................................................................ 660
Time Literals ............................................................................................................................. 662
Pathname Literals ..................................................................................................................... 662
Spaces and Other Special Characters in Pathnames ................................................................ 665
2D and 3D Point Literals .......................................................................................................... 665
Array Literals............................................................................................................................. 666
Expressions................................................................................................................................... 667
xiv Contents

Simple Expressions....................................................................................................................... 669

Operands...................................................................................................................................... 669
Math Expressions ......................................................................................................................... 670
Math Assignment ..................................................................................................................... 671
Precedence and Association Rules............................................................................................ 672
Polymorphism .......................................................................................................................... 672
Comparison Expressions .............................................................................................................. 673
Logical Expressions................................................................................................................... 674
Short-Circuiting Logical Expressions ....................................................................................... 675
Function Calls............................................................................................................................... 675
Positional and Keyword Arguments......................................................................................... 676
Function Precedence ................................................................................................................ 677
Code Layout ............................................................................................................................. 678
Special Notes About Function Calls ......................................................................................... 678
Block-Expressions ......................................................................................................................... 679
Context Expressions..................................................................................................................... 681
animate..................................................................................................................................... 683
at level, in ................................................................................................................................. 684
at time....................................................................................................................................... 685
coordsys .................................................................................................................................... 685
about......................................................................................................................................... 686
undo ......................................................................................................................................... 687
Cascading Contexts .................................................................................................................. 688
Nested Contexts ....................................................................................................................... 688
Sticky Contexts......................................................................................................................... 689
Chapter 6 Controlling Program Flow.................................................................. 691
If Expression ............................................................................................................................. 692
Case Expression ........................................................................................................................ 693
While and Do Loops................................................................................................................. 694
For Loop.................................................................................................................................... 694
Skipping Loop Iterations .......................................................................................................... 696
Loop Exit .................................................................................................................................. 697
Try Expression .......................................................................................................................... 697
Chapter 7 Creating Functions ............................................................................. 699
Function Variables.................................................................................................................... 701
Function Parameters................................................................................................................. 702
The Return Expression.............................................................................................................. 705
Chapter 8 Structure Definition............................................................................ 707
Defining Local Functions in Structures.................................................................................... 709
Structure Inherited Methods .................................................................................................... 711
Chapter 9 Values.................................................................................................. 713
Value Common Properties, Operators, and Methods .............................................................. 714
Working with Values................................................................................................................ 716
Basic Data Values ......................................................................................................................... 717
Number Values ......................................................................................................................... 717
String Values ............................................................................................................................. 722
 Contents xv

Name Values ............................................................................................................................. 727

BooleanClass Values ................................................................................................................. 728
Color Values ............................................................................................................................. 729
Point3 Values............................................................................................................................ 731
Point2 Values............................................................................................................................ 736
Ray Values................................................................................................................................. 737
Quat Values .............................................................................................................................. 738
AngleAxis Values ...................................................................................................................... 741
EulerAngles Values ................................................................................................................... 742
Matrix3 Values.......................................................................................................................... 744
BigMatrix Values, BigMatrixRowArray Values ......................................................................... 748
Box2 Values .............................................................................................................................. 750
Time Data Values ......................................................................................................................... 751
Time Values .............................................................................................................................. 751
Interval Values .......................................................................................................................... 752
Special Data Values ...................................................................................................................... 753
Undefined Value....................................................................................................................... 753
Ok Value ................................................................................................................................... 754
Unsupplied Value ..................................................................................................................... 754
DontCollect Value .................................................................................................................... 754
Bitmap Values .............................................................................................................................. 755
Stream Values .............................................................................................................................. 763
FileStream Values...................................................................................................................... 763
StringStream Values.................................................................................................................. 766
WindowStream Values ............................................................................................................. 767
MAXKey Values ............................................................................................................................ 767
MAXKey Common Properties, Operators, and Methods......................................................... 768
Working with MAXKey Values ................................................................................................ 769
ArrayParameter Values ................................................................................................................ 770
Chapter 10 Collections......................................................................................... 773
Collection Types........................................................................................................................... 775
Array Values.............................................................................................................................. 776
PathName Values...................................................................................................................... 780
ObjectSet Values ....................................................................................................................... 781
SelectionSetArray Values .......................................................................................................... 783
SelectionSet Values ................................................................................................................... 785
NodeChildrenArray Values ...................................................................................................... 785
VertexSelection Values ............................................................................................................. 786
FaceSelection Values................................................................................................................. 788
EdgeSelection Values ................................................................................................................ 790
BitArray Values ......................................................................................................................... 791
MAXKeyArray Values ............................................................................................................... 793
MAXNoteKeyArray Values ....................................................................................................... 794
ModifierArray Values................................................................................................................ 794
MaterialLibrary Values.............................................................................................................. 795
NURBSSet Values ...................................................................................................................... 797
xvi Contents

Chapter 11 3ds max Objects................................................................................ 799

Identifying and Accessing MAXScript Classes and Properties.................................................... 799
Class and Object Inspector Functions...................................................................................... 799
Dynamic Properties .................................................................................................................. 805
Indexed Access to Animatable Properties in 3ds max Objects ................................................ 806
Third-Party Plug-In Classes ...................................................................................................... 808
MAXWrapper : Value ................................................................................................................... 808
MAXWrapper Common Properties, Operators, and Methods................................................. 809
Access to MAXWrapper AppData............................................................................................. 813
Nested Object Controller Functions ........................................................................................ 814
Nested Object Properties .......................................................................................................... 815
Note Track Access ........................................................................................................................ 816
Notetrack Values....................................................................................................................... 816
MAXNoteKeyArray Values ....................................................................................................... 817
MAXNoteKey Values ................................................................................................................ 818
Working with Note Tracks ....................................................................................................... 818
Node : MAXWrapper ................................................................................................................... 820
Node Common Properties, Operators, and Methods................................................................. 820
General Node Properties........................................................................................................... 836
Node Transform Properties ...................................................................................................... 841
Using Node Transform Properties ............................................................................................ 843
Node User-Defined Properties and Methods............................................................................ 848
Node Subclasses........................................................................................................................... 849
GeometryClass : Node ................................................................................................................. 850
GeometryClass Common Properties, Operators, and Methods............................................... 852
Geometry - Standard and Extended Objects .............................................................................. 852
Box : GeometryClass ................................................................................................................ 853
C_Ext : GeometryClass ............................................................................................................. 854
Capsule : GeometryClass .......................................................................................................... 855
ChamferBox : GeometryClass .................................................................................................. 856
ChamferCyl : GeometryClass ................................................................................................... 857
Cone : GeometryClass .............................................................................................................. 858
Cylinder : GeometryClass......................................................................................................... 859
Gengon : GeometryClass.......................................................................................................... 861
Geosphere : GeometryClass ..................................................................................................... 862
Hedra : GeometryClass ............................................................................................................. 863
L_Ext : GeometryClass.............................................................................................................. 865
OilTank : GeometryClass.......................................................................................................... 866
Plane : GeometryClass .............................................................................................................. 867
Prism : GeometryClass.............................................................................................................. 868
Pyramid : GeometryClass ......................................................................................................... 869
RingWave : GeometryClass ...................................................................................................... 870
Sphere : GeometryClass............................................................................................................ 872
Spindle : GeometryClass........................................................................................................... 873
TargetObject : GeometryClass .................................................................................................. 874
Teapot : GeometryClass............................................................................................................ 875
 Contents xvii

Torus : GeometryClass.............................................................................................................. 875

Torus_Knot: GeometryClass ..................................................................................................... 877
Tube : GeometryClass............................................................................................................... 878
Geometry - Dynamics Objects ..................................................................................................... 879
Damper : GeometryClass.......................................................................................................... 880
Spring : GeometryClass ............................................................................................................ 883
Geometry - Compound Objects................................................................................................... 886
OldBoolean : GeometryClass ................................................................................................... 887
Boolean2 : GeometryClass........................................................................................................ 887
Conform : GeometryClass ........................................................................................................ 889
Connect : GeometryClass......................................................................................................... 889
Loft : GeometryClass ................................................................................................................ 890
Morph : GeometryClass ........................................................................................................... 891
Scatter : GeometryClass ............................................................................................................ 891
ShapeMerge : GeometryClass ................................................................................................... 893
Terrain : GeometryClass ........................................................................................................... 894
Geometry - Doors and Windows ................................................................................................. 896
Awning : GeometryClass .......................................................................................................... 897
BiFold : GeometryClass ............................................................................................................ 897
Casement : GeometryClass....................................................................................................... 898
Fixed : GeometryClass .............................................................................................................. 899
Pivot : GeometryClass .............................................................................................................. 899
Pivoted : GeometryClass .......................................................................................................... 900
Projected : GeometryClass........................................................................................................ 901
SlidingDoor : GeometryClass ................................................................................................... 901
SlidingWindow : GeometryClass ............................................................................................. 902
Geometry - Patch Objects............................................................................................................ 903
QuadPatch : GeometryClass..................................................................................................... 903
TriPatch : GeometryClass ......................................................................................................... 904
Geometry - Particle Systems........................................................................................................ 904
Particle System Common Properties, Operators, and Methods............................................... 905
Blizzard : GeometryClass .......................................................................................................... 906
PArray : GeometryClass ............................................................................................................ 913
PCloud : GeometryClass........................................................................................................... 923
Snow : GeometryClass .............................................................................................................. 931
Spray : GeometryClass.............................................................................................................. 933
SuperSpray : GeometryClass..................................................................................................... 935
Geometry - NURBS Objects ......................................................................................................... 943
NURBSSurf : GeometryClass..................................................................................................... 943
Point_Surf : GeometryClass ...................................................................................................... 943
Shape : Node................................................................................................................................ 944
Shape Common Properties, Operators, and Methods ............................................................. 945
Shapes - Splines ........................................................................................................................... 947
Spline Shape Common Properties, Operators, and Methods .................................................. 947
Arc : Shape ................................................................................................................................ 949
Circle : Shape ............................................................................................................................ 950
Donut : Shape ........................................................................................................................... 951
xviii Contents

Ellipse : Shape ........................................................................................................................... 953

Helix : Shape............................................................................................................................. 954
Line : Shape .............................................................................................................................. 955
NGon : Shape............................................................................................................................ 957
Rectangle : Shape...................................................................................................................... 958
Section : Shape.......................................................................................................................... 959
Star : Shape ............................................................................................................................... 960
Text : Shape .............................................................................................................................. 962
Shapes - NURBS Curves ............................................................................................................... 964
CV_Curve : Shape..................................................................................................................... 964
Point_Curve : Shape ................................................................................................................. 965
Light : Node ................................................................................................................................. 966
Light Common Properties, Operators, and Methods............................................................... 966
DirectionalLight : Light ............................................................................................................ 970
FreeSpot : Light......................................................................................................................... 971
OmniLight : Light..................................................................................................................... 972
TargetDirectionalLight : Light.................................................................................................. 972
TargetSpot : Light ..................................................................................................................... 973
Camera : Node ............................................................................................................................. 974
Camera Common Properties, Operators, and Methods........................................................... 974
FreeCamera : Camera ............................................................................................................... 976
TargetCamera : Camera ............................................................................................................ 976
Helper : Node............................................................................................................................... 977
Helper - Standard......................................................................................................................... 978
Bone : Helper ............................................................................................................................ 978
Compass : Helper...................................................................................................................... 979
Dummy : Helper ....................................................................................................................... 979
Grid : Helper ............................................................................................................................. 980
Point : Helper............................................................................................................................ 980
Protractor : Helper .................................................................................................................... 981
Tape : Helper............................................................................................................................. 981
Helper - Atmospheric ................................................................................................................... 982
BoxGizmo : Helper ................................................................................................................... 982
CylGizmo : Helper .................................................................................................................... 983
SphereGizmo : Helper............................................................................................................... 983
Helper - Camera Match................................................................................................................ 984
CamPoint : Helper .................................................................................................................... 984
Helper - VRML 1.0/VRBL .............................................................................................................. 984
Inline : Helper........................................................................................................................... 984
LOD : Helper............................................................................................................................. 985
VRML_VRBL : Helper................................................................................................................ 985
Helper - VRML97 .......................................................................................................................... 985
Anchor : Helper ........................................................................................................................ 986
AudioClip : Helper.................................................................................................................... 986
Background : Helper ................................................................................................................. 987
Billboard : Helper...................................................................................................................... 987
FogHelper : Helper .................................................................................................................... 987
 Contents xix

InlineHelper : Helper ................................................................................................................ 988

LODHelper : Helper .................................................................................................................. 988
NavInfo : Helper ....................................................................................................................... 988
ProxSensor : Helper .................................................................................................................. 989
Sound : Helper .......................................................................................................................... 989
TimeSensor : Helper.................................................................................................................. 990
TouchSensor : Helper ............................................................................................................... 990
System : Node .............................................................................................................................. 991
Bones : System .......................................................................................................................... 991
Sunlight : System ...................................................................................................................... 991
RingArray : System ................................................................................................................... 992
SpacewarpObject : Node ............................................................................................................. 992
Spacewarp - Geometric/Deformable .......................................................................................... 993
Bomb : SpacewarpObject .......................................................................................................... 993
ConformSpaceWarp : SpacewarpObject................................................................................... 995
SpaceDisplace : SpacewarpObject............................................................................................. 996
SpaceFFDBox : SpacewarpObject.............................................................................................. 998
SpaceFFDCyl : SpacewarpObject .............................................................................................. 999
SpaceRipple : SpacewarpObject .............................................................................................. 1001
SpaceWave : SpacewarpObject ............................................................................................... 1002
Spacewarp - Particles and Dynamics ......................................................................................... 1003
Gravity : SpacewarpObject ..................................................................................................... 1003
Motor : SpacewarpObject ....................................................................................................... 1004
PBomb : SpacewarpObject...................................................................................................... 1006
PushSpaceWarp : SpacewarpObject........................................................................................ 1008
Wind : SpacewarpObject ........................................................................................................ 1010
Spacewarp - Modifier-Based...................................................................................................... 1011
SpaceBend : SpacewarpObject ................................................................................................ 1011
SpaceNoise : SpacewarpObject ............................................................................................... 1012
SpaceSkew : SpacewarpObject ................................................................................................ 1014
SpaceStretch : SpacewarpObject ............................................................................................. 1015
SpaceTaper : SpacewarpObject ............................................................................................... 1016
SpaceTwist : SpacewarpObject................................................................................................ 1017
Spacewarp - Dynamics Interface ............................................................................................... 1018
PDynaFlect : SpacewarpObject ............................................................................................... 1019
SDynaFlect : SpacewarpObject ............................................................................................... 1020
UDynaFlect : SpacewarpObject .............................................................................................. 1022
Spacewarp - Particles Only ........................................................................................................ 1024
Deflector : SpacewarpObject .................................................................................................. 1024
Path_Follow : SpacewarpObject ............................................................................................. 1025
POmniFlect : SpacewarpObject .............................................................................................. 1027
SDeflector : SpacewarpObject................................................................................................. 1030
SOmniFlect : SpacewarpObject .............................................................................................. 1031
UDeflector : SpacewarpObject................................................................................................ 1033
UOmniFlect : SpacewarpObject.............................................................................................. 1034
XRef Objects and Scenes ........................................................................................................... 1037
XRefObject : Node .................................................................................................................. 1037
xx Contents

XRefScene Values ................................................................................................................... 1038

Editable Meshes, Splines, and Patches...................................................................................... 1041
Editable_Mesh : GeometryClass and TriMesh : Value ........................................................... 1041
Working with Editable Meshes .............................................................................................. 1077
SplineShape : Shape................................................................................................................ 1079
Patch : GeometryClass............................................................................................................ 1088
Modifier : MAXWrapper and SpacewarpModifier : MAXWrapper........................................... 1095
Modifier Common Properties, Operators, and Methods.......................................................... 1096
Modifier Sub-Object Transform Properties ............................................................................ 1099
Modifier and SpacewarpModifier Types ................................................................................... 1100
Modifiers .................................................................................................................................... 1103
Affect_Region : Modifier......................................................................................................... 1103
Bend : Modifier ....................................................................................................................... 1104
Bevel : Modifier ...................................................................................................................... 1106
Bevel_Profile : Modifier .......................................................................................................... 1108
CameraMap : Modifier ........................................................................................................... 1109
Cap_Holes : Modifier .............................................................................................................. 1110
CrossSection : Modifier .......................................................................................................... 1110
DeleteMesh : Modifier ............................................................................................................ 1111
DeleteSplineModifier : Modifier ............................................................................................. 1111
Disp_Approx : Modifier .......................................................................................................... 1111
Displace : Modifier ................................................................................................................. 1112
Edit_Mesh : Modifier .............................................................................................................. 1114
Edit_Patch : Modifier .............................................................................................................. 1115
Edit_Spline : Modifier ............................................................................................................. 1115
Extrude : Modifier................................................................................................................... 1115
FFDBox : Modifier................................................................................................................... 1117
FFDCyl : Modifier ................................................................................................................... 1119
FFD_2x2x2 : Modifier ............................................................................................................. 1121
FFD_3x3x3 : Modifier ............................................................................................................. 1123
FFD_4x4x4 : Modifier ............................................................................................................. 1124
FFD_Select : Modifier.............................................................................................................. 1126
Face_Extrude : Modifier .......................................................................................................... 1127
Fillet_Chamfer : Modifier ....................................................................................................... 1127
Flex : Modifier......................................................................................................................... 1128
Lathe : Modifier ...................................................................................................................... 1133
Lattice : Modifier .................................................................................................................... 1135
Linked_XForm : Modifier ....................................................................................................... 1136
MaterialByElement : Modifier ................................................................................................ 1136
MaterialModifier : Modifier .................................................................................................... 1137
Melt : Modifier........................................................................................................................ 1138
MeshSmooth : Modifier.......................................................................................................... 1139
Mesh_Select : Modifier ........................................................................................................... 1142
Mirror : Modifier..................................................................................................................... 1143
Morpher : Modifier ................................................................................................................. 1144
NCurve_Sel : Modifier ............................................................................................................ 1145
NoiseModifier : Modifier ........................................................................................................ 1145
 Contents xxi

Normalize_Spline : Modifier................................................................................................... 1146

NormalModifier : Modifier ..................................................................................................... 1147
NSurf_Sel : Modifier................................................................................................................ 1147
Optimize : Modifier ................................................................................................................ 1148
PatchDeform : Modifier.......................................................................................................... 1150
PathDeform : Modifier ........................................................................................................... 1151
Preserve : Modifier .................................................................................................................. 1152
Push : Modifier ....................................................................................................................... 1153
Relax : Modifier ...................................................................................................................... 1154
Ripple : Modifier ..................................................................................................................... 1154
Skew : Modifier ....................................................................................................................... 1155
Skin : Modifier ........................................................................................................................ 1157
SliceModifier : Modifier .......................................................................................................... 1165
Smooth : Modifier .................................................................................................................. 1166
Spherify : Modifier.................................................................................................................. 1167
SplineSelect : Modifier ............................................................................................................ 1167
Squeeze : Modifier .................................................................................................................. 1167
STL_Check : Modifier ............................................................................................................. 1169
Stretch : Modifier .................................................................................................................... 1170
Surface : Modifier.................................................................................................................... 1171
SurfDeform : Modifier ............................................................................................................ 1171
Taper : Modifier ...................................................................................................................... 1173
Tessellate : Modifier ................................................................................................................ 1174
Trim_Extend : Modifier .......................................................................................................... 1175
Twist : Modifier ...................................................................................................................... 1175
Unwrap_UVW : Modifier ....................................................................................................... 1176
UVW_Xform : Modifier .......................................................................................................... 1187
UVWmap : Modifier ............................................................................................................... 1188
Vertex_Colors : Modifier ........................................................................................................ 1191
VertexPaint : Modifier ............................................................................................................ 1191
VolumeSelect : Modifier ......................................................................................................... 1192
Wave : Modifier ...................................................................................................................... 1194
XForm : Modifier .................................................................................................................... 1195
Spacewarp Binding SpacewarpModifiers.................................................................................. 1196
Other SpacewarpModifiers........................................................................................................ 1198
Displace_Mesh : SpacewarpModifier ...................................................................................... 1198
Displace_NURBS : SpacewarpModifier ................................................................................... 1198
MapScaler : SpacewarpModifier ............................................................................................. 1198
SpaceCameraMap : SpacewarpModifier ................................................................................. 1199
SpacePatchDeform : SpacewarpModifier................................................................................ 1199
SpacePathDeform : SpacewarpModifier ................................................................................. 1200
SpaceSurfDeform : SpacewarpModifier .................................................................................. 1201
Surface_Mapper : SpacewarpModifier .................................................................................... 1202
Material : MAXWrapper ............................................................................................................ 1203
Material Common Properties, Operators, and Methods........................................................ 1203
Material Types ........................................................................................................................... 1204
Blend : Material ...................................................................................................................... 1205
xxii Contents

CompositeMaterial : Material................................................................................................. 1206

DoubleSided : Material ........................................................................................................... 1207
MatteShadow : Material ......................................................................................................... 1208
MorpherMaterial : Material .................................................................................................... 1209
MultiMaterial : Material ......................................................................................................... 1210
NoMaterial : Material ............................................................................................................. 1212
RayTraceMaterial : Material.................................................................................................... 1212
StandardMaterial : Material .................................................................................................... 1224
Shellac : Material .................................................................................................................... 1233
TopBottom : Material ............................................................................................................. 1233
TextureMap : Material ............................................................................................................... 1234
TextureMap Common Properties, Operators, and Methods ................................................. 1235
TextureMap Shared Classes....................................................................................................... 1236
UVGenClass : Material ........................................................................................................... 1237
StandardXYZGen : Material ................................................................................................... 1238
TexOutputClass : Material...................................................................................................... 1239
TextureMap Types ..................................................................................................................... 1240
Adobe_Photoshop_Plug_In_Filter : TextureMap.................................................................... 1241
Adobe_Premiere_Video_Filter : TextureMap .......................................................................... 1242
BitmapTexture : TextureMap ................................................................................................. 1243
Bricks : TextureMap ................................................................................................................ 1245
Cellular : TextureMap............................................................................................................. 1247
Checker : TextureMap ............................................................................................................ 1249
CompositeTextureMap : TextureMap .................................................................................... 1250
Dent : TextureMap ................................................................................................................. 1251
Falloff : TextureMap ............................................................................................................... 1252
FalloffTextureMap : TextureMap............................................................................................ 1255
FlatMirror : TextureMap ......................................................................................................... 1255
Gradient : TextureMap ........................................................................................................... 1257
Gradient_Ramp : TextureMap ................................................................................................ 1259
Marble : TextureMap .............................................................................................................. 1261
Mask : TextureMap ................................................................................................................. 1262
Mix : TextureMap ................................................................................................................... 1262
Noise : TextureMap ................................................................................................................ 1263
NoTexture : TextureMap ........................................................................................................ 1265
Output : TextureMap.............................................................................................................. 1265
Paint : TextureMap ................................................................................................................. 1266
Particle_Age : TextureMap...................................................................................................... 1266
Particle_MBlur : TextureMap.................................................................................................. 1267
Perlin_Marble : TextureMap ................................................................................................... 1268
Planet : TextureMap ............................................................................................................... 1269
Raytrace : TextureMap............................................................................................................ 1271
Reflect_Refract : TextureMap.................................................................................................. 1276
RGB_Multiply : TextureMap................................................................................................... 1278
RGB_Tint : TextureMap .......................................................................................................... 1278
Smoke : TextureMap............................................................................................................... 1279
Speckle : TextureMap.............................................................................................................. 1280
 Contents xxiii

Splat : TextureMap ................................................................................................................. 1281

Stucco : TextureMap ............................................................................................................... 1282
Swirl : TextureMap ................................................................................................................. 1283
Thin_Wall_Refraction : TextureMap ...................................................................................... 1284
Vertex_Color : TextureMap .................................................................................................... 1285
Water : TextureMap................................................................................................................ 1286
Wood : TextureMap................................................................................................................ 1287
Animation Controllers ............................................................................................................... 1288
Controller Common Properties, Operators, and Methods ....................................................... 1289
Controller Time Functions ..................................................................................................... 1292
Controller Key Functions ....................................................................................................... 1294
Controller Out-Of-Range Functions....................................................................................... 1296
Controller Ease and Multiplier Curve Functions ................................................................... 1297
Controller Key Reducer .......................................................................................................... 1299
Time and Key Functions on Object Hierarchies ........................................................................ 1299
Controller Types ........................................................................................................................ 1300
Controllers - Superclass Level................................................................................................. 1300
FloatController : MAXWrapper.............................................................................................. 1301
MasterBlockController : MAXWrapper .................................................................................. 1301
Matrix3Controller : MAXWrapper ......................................................................................... 1302
MorphController : MAXWrapper........................................................................................... 1302
Point3Controller : MAXWrapper ........................................................................................... 1302
PositionController : MAXWrapper ........................................................................................ 1303
RotationController : MAXWrapper........................................................................................ 1303
ScaleController : MAXWrapper.............................................................................................. 1304
QuatController : MAXWrapper.............................................................................................. 1304
Attachment : PositionController............................................................................................ 1304
Attachment Controller Keys .................................................................................................. 1305
Audio Controllers ................................................................................................................... 1306
Barycentric_Morph_Controller : MorphController ............................................................... 1306
Barycentric_Morph_Controller Keys ...................................................................................... 1308
Bezier Controllers ................................................................................................................... 1309
Bezier Controller Keys ............................................................................................................ 1310
Block : FloatController ........................................................................................................... 1311
Block_Control : MasterBlockController ................................................................................. 1311
Cubic_Morph_Controller : MorphController ........................................................................ 1312
Cubic_Morph_Controller Keys............................................................................................... 1312
Dynamics Controllers............................................................................................................. 1312
Expression Controllers ........................................................................................................... 1313
IK_ControllerMatrix3Controller : Matrix3Controller............................................................ 1313
Linear Controllers................................................................................................................... 1315
Linear Controller Keys............................................................................................................ 1315
Link_Control : Matrix3Controller.......................................................................................... 1316
List Controllers ....................................................................................................................... 1317
LOD_Controller : FloatController .......................................................................................... 1319
LookAt : Matrix3Controller.................................................................................................... 1319
MasterBlock : MasterBlockController..................................................................................... 1320
xxiv Contents

Motion Capture Controllers................................................................................................... 1321

Noise Controllers.................................................................................................................... 1322
On_Off : FloatController ........................................................................................................ 1323
On_Off Controller Keys.......................................................................................................... 1323
Path : PositionController........................................................................................................ 1324
PRS : Matrix3Controller ......................................................................................................... 1325
Reactor Controllers................................................................................................................. 1326
Script Controllers.................................................................................................................... 1329
Slave_Control : Matrix3Controller......................................................................................... 1333
Slave Controllers..................................................................................................................... 1333
Surface_position : PositionController .................................................................................... 1334
TCB Controllers ...................................................................................................................... 1334
TCB Controller Keys ............................................................................................................... 1335
Waveform_Float : FloatController ......................................................................................... 1335
XYZ Controllers ...................................................................................................................... 1335
Atmospheric : MAXWrapper ..................................................................................................... 1337
Atmospheric Effects Common Properties, Operators, and Methods ..................................... 1338
Atmospheric Effect Types .......................................................................................................... 1339
Fire_Effect : Atmospheric........................................................................................................ 1339
Setting explosion start and end times for Fire-Effect ............................................................. 1341
Fog : Atmospheric................................................................................................................... 1342
Volume_Fog : Atmospheric .................................................................................................... 1343
Volume_Light : Atmospheric ................................................................................................. 1344
Working with Atmospherics ...................................................................................................... 1345
RenderEffect : MAXWrapper ..................................................................................................... 1347
Render Effects Common Properties, Operators, and Methods .............................................. 1347
Render Effect Types ................................................................................................................... 1348
Blur : RenderEffect .................................................................................................................. 1349
Brightness_and_Contrast : RenderEffect ................................................................................ 1353
Color_Balance : RenderEffect ................................................................................................. 1354
Depth_of_Field : RenderEffect ................................................................................................ 1354
File_Output : RenderEffect ..................................................................................................... 1356
Film_Grain : RenderEffect ...................................................................................................... 1356
Lens Effects ................................................................................................................................ 1357
Lens_Effects : RenderEffect ..................................................................................................... 1357
Lens_Effects - Auto_Secondary ............................................................................................... 1360
Lens_Effects - Glow................................................................................................................. 1363
Lens_Effects - Manual_Secondary .......................................................................................... 1366
Lens_Effects - Ray ................................................................................................................... 1370
Lens_Effects - Ring.................................................................................................................. 1373
Lens_Effects - Star ................................................................................................................... 1376
Lens_Effects - Streak ............................................................................................................... 1379
Track View Nodes ...................................................................................................................... 1382
Working with NURBS................................................................................................................. 1384
Working with the NURBS Classes .......................................................................................... 1385
Overview of the Principal NURBS Classes.............................................................................. 1386
Using the NURBS Classes and Functions to Create and Modify 3ds max NURBS Models ....... 1389
 Contents xxv

Creating New NURBS Objects ................................................................................................ 1389

Modifying Existing NURBS Objects ....................................................................................... 1390
Parameter Ranges for Curves and Surfaces............................................................................. 1391
Materials Assignment and Texture Coordinates .................................................................... 1391
Creating NURBS Scene Objects .............................................................................................. 1392
Creating NURBSCVSurface Values ......................................................................................... 1394
NURBS Node Properties and Methods ................................................................................... 1397
The NURBS Classes .................................................................................................................... 1401
NURBSObject Values .............................................................................................................. 1402
NURBSPoint Classes ................................................................................................................... 1403
NURBSPoint : NURBSObject................................................................................................... 1403
NURBSCurveConstPoint : NURBSPoint ................................................................................. 1403
NURBSCurveIntersectPoint : NURBSPoint............................................................................. 1404
NURBSCurveSurfaceIntersectPoint : NURBSPoint ................................................................. 1405
NURBSIndependentPoint : NURBSPoint................................................................................ 1406
NURBSPointConstPoint : NURBSPoint .................................................................................. 1407
NURBSSurfConstPoint : NURBSPoint .................................................................................... 1407
NURBSControlVertex Class ........................................................................................................ 1409
NURBSControlVertex : NURBSObject .................................................................................... 1409
NURBSCurve Classes .................................................................................................................. 1409
NURBSCurve : NURBSObject.................................................................................................. 1409
NURBSBlendCurve : NURBSCurve ......................................................................................... 1410
NURBSChamferCurve : NURBSCurve .................................................................................... 1411
NURBSCVCurve : NURBSCurve ............................................................................................. 1412
NURBSCurveOnSurface : NURBSCVCurve............................................................................. 1414
NURBSFilletCurve : NURBSCurve .......................................................................................... 1415
NURBSIsoCurve : NURBSCurve.............................................................................................. 1416
NURBSMirrorCurve : NURBSCurve ........................................................................................ 1417
NURBSOffsetCurve : NURBSCurve......................................................................................... 1417
NURBSPointCurve : NURBSCurve.......................................................................................... 1418
NURBSPointCurveOnSurface : NURBSPointCurve ................................................................ 1419
NURBSProjectNormalCurve : NURBSCurve ........................................................................... 1420
NURBSProjectVectorCurve : NURBSCurve............................................................................. 1421
NURBSSurfaceEdgeCurve : NURBSCurve ............................................................................... 1422
NURBSSurfaceNormalCurve : NURBSCurve........................................................................... 1422
NURBSSurfSurfIntersectionCurve : NURBSCurve .................................................................. 1423
NURBSXFormCurve : NURBSCurve ....................................................................................... 1424
NURBSSurface Classes ............................................................................................................... 1425
NURBSSurface : NURBSObject................................................................................................ 1425
NURBS1RailSweepSurface : NURBSSurface ............................................................................ 1427
NURBS2RailSweepSurface : NURBSSurface ............................................................................ 1429
NURBSBlendSurface : NURBSSurface ..................................................................................... 1430
NURBSCapSurface : NURBSSurface ........................................................................................ 1432
NURBSCVSurface : NURBSSurface.......................................................................................... 1433
NURBSExtrudeSurface : NURBSSurface .................................................................................. 1435
NURBSFilletSurface : NURBSSurface....................................................................................... 1436
NURBSLatheSurface : NURBSSurface...................................................................................... 1437
xxvi Contents

NURBSMirrorSurface : NURBSSurface .................................................................................... 1437

NURBSMultiCurveTrimSurface : NURBSSurface .................................................................... 1438
NURBSNBlendSurface : NURBSSurface................................................................................... 1439
NURBSOffsetSurface : NURBSSurface ..................................................................................... 1440
NURBSPointSurface : NURBSSurface ...................................................................................... 1441
NURBSRuledSurface : NURBSSurface ..................................................................................... 1442
NURBSULoftSurface : NURBSSurface ..................................................................................... 1443
NURBSUVLoftSurface : NURBSSurface ................................................................................... 1444
NURBSXFormSurface : NURBSSurface.................................................................................... 1445
NURBSTexturePoint Class.......................................................................................................... 1446
NURBSTexturePoint : NURBSObject ...................................................................................... 1446
NURBS Associated Classes ......................................................................................................... 1447
NURBSDisplay : Value ............................................................................................................ 1447
NURBSSelection : Value.......................................................................................................... 1448
NURBSSet : Value.................................................................................................................... 1450
NURBSSurfaceApproximation : Value.................................................................................... 1453
NURBSTextureSurface : Value ................................................................................................ 1455
Biped and Physique ................................................................................................................... 1456
Biped : System ........................................................................................................................ 1456
Biped-Related Classes ............................................................................................................. 1457
BipedExportInterface Values .................................................................................................. 1458
Physique : Modifier ................................................................................................................ 1458
PhyContextExport Values ...................................................................................................... 1458
PhyRigidVertex Values ........................................................................................................... 1459
PhyBlendingRigidVertex Values............................................................................................. 1459
Missing Object Classes............................................................................................................... 1460
Scripting Vertex and Control Point Animation ......................................................................... 1461
Chapter 12 Creating MAXScript Tools .............................................................. 1463
Scripted Utilities......................................................................................................................... 1463
Scripted Utility Panels ............................................................................................................ 1464
Utility Clauses ........................................................................................................................ 1466
Managing Multiple Rollouts in a Scripted Utility .................................................................. 1468
Rollout Clauses ....................................................................................................................... 1470
Utility and Rollout Properties, Methods, and Event Handlers .............................................. 1474
Rollout Floater Windows........................................................................................................ 1477
Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code.......... 1478
Accessing Locals and Other Items in a Rollout from External Code ..................................... 1480
Rollout User-Interface Controls ................................................................................................. 1481
Rollout User-Interface Controls Common Properties............................................................ 1481
Rollout User-Interface Controls Common Layout Parameters .............................................. 1483
Rollout User-Interface Control Types ........................................................................................ 1484
Bitmap .................................................................................................................................... 1487
Button ..................................................................................................................................... 1488
Checkbox ................................................................................................................................ 1489
Checkbutton........................................................................................................................... 1490
Colorpicker ............................................................................................................................. 1492
 Contents xxvii

Combobox .............................................................................................................................. 1493

Dropdownlist.......................................................................................................................... 1494
Edittext ................................................................................................................................... 1496
Label ....................................................................................................................................... 1497
Listbox .................................................................................................................................... 1497
Mapbutton.............................................................................................................................. 1499
Materialbutton........................................................................................................................ 1500
MultiListBox ........................................................................................................................... 1502
Pickbutton .............................................................................................................................. 1504
ProgressBar.............................................................................................................................. 1505
Radiobuttons .......................................................................................................................... 1506
Slider ....................................................................................................................................... 1507
Spinner ................................................................................................................................... 1509
Timer....................................................................................................................................... 1512
Image Buttons............................................................................................................................ 1513
Scripted Right-Click Menus ....................................................................................................... 1514
RCMenu Clauses..................................................................................................................... 1515
RCMenu User-Interface Items.................................................................................................... 1518
menuItem ............................................................................................................................... 1518
separator ................................................................................................................................. 1519
subMenu ................................................................................................................................. 1520
Defining Macro Scripts .............................................................................................................. 1521
Creating Icon Bitmap Files ..................................................................................................... 1530
Scripted Mouse Tools ................................................................................................................ 1531
Mouse Tool Clauses ................................................................................................................ 1532
Scripted Plug-ins ........................................................................................................................ 1538
Scripted Plug-in Clauses ......................................................................................................... 1542
Scripted Plug-in Methods ....................................................................................................... 1551
Updating Scripted Plug-ins..................................................................................................... 1553
Scripted Geometry Plug-ins .................................................................................................... 1555
Scripted SimpleObject Plug-ins .............................................................................................. 1556
Scripted Shape Plug-ins .......................................................................................................... 1560
Scripted Light Plug-ins ........................................................................................................... 1561
Scripted Helper Plug-ins ......................................................................................................... 1561
Scripted Modifier Plug-ins ...................................................................................................... 1562
Scripted SimpleMod Plug-ins ................................................................................................. 1563
Scripted Material Plug-ins....................................................................................................... 1565
Scripted TextureMap Plug-ins ................................................................................................ 1566
Scripted RenderEffect Plug-ins ............................................................................................... 1566
Scripted Atmospheric Plug-ins ............................................................................................... 1569
Chapter 13 Interacting with the 3ds max User Interface ................................. 1571
Command Panels ....................................................................................................................... 1571
Create Panel............................................................................................................................ 1572
Modify Panel .......................................................................................................................... 1572
Main Toolbar.............................................................................................................................. 1574
xxviii Contents

Status Bar ................................................................................................................................... 1577

Prompt Line ............................................................................................................................ 1577
Coordinate Display................................................................................................................. 1578
Progress Bar Display ............................................................................................................... 1578
Status Bar Buttons................................................................................................................... 1579
Time Control .............................................................................................................................. 1580
Trackbar ..................................................................................................................................... 1581
Viewports ................................................................................................................................... 1581
Accessing Active Viewport Info, Type, and Transforms ........................................................ 1581
Viewport Background Images................................................................................................. 1586
Viewport Grids ....................................................................................................................... 1587
Mouse Cursors ........................................................................................................................ 1588
Picking Points in the Viewports ............................................................................................. 1589
Viewport Drawing Methods ................................................................................................... 1592
Miscellaneous Viewport Methods and System Globals ......................................................... 1603
3ds max User Interface Colors................................................................................................... 1604
Material Editor ........................................................................................................................... 1606
Track View .................................................................................................................................. 1609
Render Scene Dialog.................................................................................................................. 1611
3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters ..................................................... 1614
Schematic View .......................................................................................................................... 1615
Time Configuration Dialog ........................................................................................................ 1616
RAMPlayer.................................................................................................................................. 1617
Track View Pick Dialog............................................................................................................... 1617
Picking Scene Nodes .................................................................................................................. 1618
Picking Scene Nodes By Hit.................................................................................................... 1618
Picking Scene Nodes by Name ............................................................................................... 1619
Picking Scene Nodes By Region.............................................................................................. 1620
Miscellaneous Dialogs................................................................................................................ 1621
MAXScript Message and Query Dialogs.................................................................................... 1622
Keyboard Entry .......................................................................................................................... 1623
Macro Scripts ............................................................................................................................. 1624
3ds max System Directories....................................................................................................... 1625
3ds max Scene File Properties ................................................................................................... 1628
3ds max Commands .................................................................................................................. 1630
Chapter 14 File Access ....................................................................................... 1639
3ds max File Loading and Saving........................................................................................... 1639
Bitmap Files ............................................................................................................................ 1641
XRef Files ................................................................................................................................ 1643
Text File Input and Output .................................................................................................... 1643
Standard Open and Save File Dialogs..................................................................................... 1643
File Name Parsing ................................................................................................................... 1644
External File Methods............................................................................................................. 1645
Encrypted Files ....................................................................................................................... 1647
Accessing INI File Keys ........................................................................................................... 1647
Custom User Interface Files.................................................................................................... 1648
 Contents xxix

Chapter 15 Change Handlers and Callbacks ..................................................... 1649

Change Handlers and When Constructs ............................................................................... 1650
Time Change Callback Mechanism ....................................................................................... 1654
Viewport Redraw Callback Mechanism ................................................................................. 1655
General Event Callback Mechanism ...................................................................................... 1656
Chapter 16 Miscellaneous Functions ................................................................. 1663
Pausing Script Execution ........................................................................................................ 1664
Time Stamping ....................................................................................................................... 1664
Controlling the Renderer ....................................................................................................... 1664
Executing External Commands and Programs ...................................................................... 1668
Exiting and Resetting 3ds max ............................................................................................... 1669
Chapter 17 OLE Automation.............................................................................. 1671
Setting Up MAXScript OLE Automation ................................................................................ 1673
Exposing MAXScript Functions.............................................................................................. 1673
3ds max Specific Errors........................................................................................................... 1674
Running the OLE Demo ......................................................................................................... 1674
Chapter 18 Trigonometric Functions and Vector Arithmetic ........................... 1675
Trigonometric Functions ........................................................................................................ 1675
Vector Arithmetic ................................................................................................................... 1677
Chapter 19 MAXScript Grammar and Class Hierarchy ..................................... 1681
MAXScript Grammar .............................................................................................................. 1681
MAXScript Class Hierarchy .................................................................................................... 1688
Chapter 20 Using the HTML Help Viewer ......................................................... 1715
Using the HTML Help Viewer ................................................................................................ 1715
Finding Information Fast ....................................................................................................... 1717
Searching for Help Topics ...................................................................................................... 1718
Favorites Tab........................................................................................................................... 1721
HTML Help Viewer Toolbar ................................................................................................... 1721
HTML Help Viewer Right-Click Menus .................................................................................. 1722
Keyboard Shortcuts in the Help Viewer ................................................................................. 1722
Chapter 21 character studio 3 MAXScript Extensions ...................................... 1725
Biped General Topics ................................................................................................................. 1725
Biped Load and Save Methods ............................................................................................... 1725
Biped Creation........................................................................................................................ 1727
Biped Display Preferences Access ........................................................................................... 1729
Biped Sample Scripts .............................................................................................................. 1730
biped_object : GeometryClass ................................................................................................ 1730
Biped Layers............................................................................................................................ 1731
Biped Node Hierarchy ............................................................................................................ 1731
Biped and Crowd Interaction................................................................................................. 1734
Biped Controllers ....................................................................................................................... 1735
Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller .................................................. 1736
FootSteps : Matrix3 Controller ............................................................................................... 1744
Biped Slave Controller ............................................................................................................ 1745
xxx Contents

Biped Footsteps and Footprints ................................................................................................ 1745

Biped Footprints ..................................................................................................................... 1745
Biped Class : MultFprintParams ............................................................................................. 1748
FootSteps : Matrix3 Controller ............................................................................................... 1750
BipedFSKey : MAXObject ....................................................................................................... 1751
Biped Motion Flow..................................................................................................................... 1752
MoFlow : MaxWrapper........................................................................................................... 1752
MoFlowScript : MaxWrapper ................................................................................................. 1754
MoFlowTranInfo : MaxWrapper ............................................................................................ 1756
MoFlowTransition : MaxWrapper .......................................................................................... 1758
Biped Keys.................................................................................................................................. 1759
BipedKey : MAXObject........................................................................................................... 1761
BipedFSKey : MAXObject ....................................................................................................... 1763
Biped Motion Capture ............................................................................................................... 1763
Crowds ....................................................................................................................................... 1771
Crowd : helper ........................................................................................................................ 1771
Delegate : Helper .................................................................................................................... 1773
CrowdScatter: ......................................................................................................................... 1778
CrowdAssignment : MAXObject ............................................................................................ 1784
CrowdTeam : ReferenceTarget................................................................................................ 1785
CrowdState:ReferenceTarget................................................................................................... 1786
CrowdTransition : MAXObject .............................................................................................. 1787
Crowds - Methods .................................................................................................................. 1788
CogControl : MAXObject....................................................................................................... 1791
Crowd Priority Properties ....................................................................................................... 1792
Crowd Behaviors ........................................................................................................................ 1792
Avoid_Behavior : MAXObject ................................................................................................ 1793
Orientation_Behavior : MAXObject....................................................................................... 1794
Path_Follow_Behavior : MAXObject ...................................................................................... 1796
Repel_Behavior : MAXObject ................................................................................................. 1798
Scripted_Behavior : MAXObject ............................................................................................. 1799
Seek_Behavior : MAXObject................................................................................................... 1807
Space_Warp_Behavior: MAXObject ....................................................................................... 1809
Speed_Vary_Behavior : MAXObject ....................................................................................... 1809
Surface_Arrive_Behavior : MAXObject................................................................................... 1811
Surface_Follow_Behavior : MAXObject.................................................................................. 1814
Wall_Repel_Behavior : MAXObject........................................................................................ 1816
Wall_Seek_Behavior : MAXObject ......................................................................................... 1817
Wander_Behavior : MAXObject ............................................................................................. 1819
MotionClips and GlobalMotionClip .......................................................................................... 1820
SpaceWarps................................................................................................................................ 1821
Vector_Field: SpacewarpObject .............................................................................................. 1821
Chapter 22 CS3Tools.cui Tutorial ...................................................................... 1825
Index ................................................................................................................. 1839
Introduction

3ds max 4 MAXScript Online Reference

MAXScript is the built-in scripting language for 3ds max and 3D Studio VIZ. MAXScript provides
3ds max and 3DS VIZ users 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 rollouts or modeless windows, to give them a
standard 3ds max or 3DS VIZ user interface.
• Package scripts as a macro, and install these Macro Scripts as buttons in the 3ds max toolbars.
• 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, and render effects.
• Build custom import/export tools using the built-in 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 3ds max as MAXScript commands.
• Store in scene files the scripts to run for each of the notification events supported by 3ds max,
such as pre- and post-scene file open, new, reset, scene file save, pre- and post-render, selection
change, and so on.
Because the functionality of MAXScript is almost identical for both 3ds max and 3DS VIZ, this
online reference refers to 3ds max to avoid using both product names redundantly. It also points out
specific differences between MAXScript for 3ds max and 3DS VIZ.
xxxii Chapter | Introduction

See also
MAXScript Overview (p. xxxii)
Using the MAXScript Documentation (p. xxxiii)
The MAXScript Utility Panel (p. xxxiv)
General MAXScript Topics (p. lii)
Learning MAXScript (p. 577)
Syntax Definitions in This Document (p. lx)
Objects and Classes in Object-Oriented Programming (p. lxii)
What’s New in MAXScript (p. 1)
3ds max 4 MAXScript Online Reference (p. xxxi)

MAXScript Overview
The MAXScript language is specifically designed to complement 3ds max. It has many special
features and constructs such as coordinate system contexts, object primitives and materials that
mirror high-level concepts in the 3ds max user-interface. It has an animation mode with automatic
keyframing and access to scene objects using hierarchical path names that match the 3ds max object
hierarchy.
The language syntax is simple enough for non-programmers, as it includes minimal punctuation
and formatting rules. Coupled with the use of the command-line Listener window, the ability to
install scripts as toolbar buttons, and the recording of user actions as MAXScript commands,
MAXScript can be employed casually by the user while working in the 3ds max point-and-click user
interface.
MAXScript is also rich enough to enable sophisticated programming tasks, with capabilities such as
3D vector, matrix, and quaternion algebra. MAXScript is well suited to working with large
collections of objects; for example, making complex procedural selections, constructing random star
fields, or placing objects in numerically precise patterns.
MAXScript allows scripts to be packaged as Utility panel rollouts, as modeless windows, and as
3ds max toolbar buttons. MAXScript can also be used to extend or replace the user interface for
objects, modifiers, materials, textures, render effects, and atmospheric effects; or to create custom
mesh objects, modifiers, and render effects. This allows job-specific tools to be scripted by the
technical department and made available to artists and animators through standard 3ds max
point-and-click user interfaces.
MAXScript supports formatted text I/O, so it is possible to produce asset reports directly from
3ds max scene files and read files containing scene layout, naming, texture details, and so on,
exported from other project management software.
MAXScript can also be used as a high-level scene import utility. By outputting MAXScript scripts
containing object creation commands, it is possible for other programs and packages to export
directly using any of the high-level 3ds max constructs.
 Using the MAXScript Documentation xxxiii

Using the MAXScript Documentation

This reference is written primarily for animators learning MAXScript. The topics are organized with
the introductory material presented first, then descriptions of the MAXScript syntax and grammar,
followed by a description of creating, accessing, and modifying the various 3ds max objects. These
3ds max objects include geometry objects, modifiers, controllers, materials, textures, and render
effects. The MAXScript tools are then described, followed by descriptions of the methods for
interacting with the 3ds max user interface, accessing external files, and establishing notifications
to a script when an object or 3ds max state changes. Throughout these topics, the purpose and
syntax of the commands in the MAXScript language are described.
Although it’s helpful to have programming experience, the basic aspects of MAXScript do not
require this or an in-depth understanding of the structure underlying 3ds max. Concepts presented
in one topic do assume a basic understanding of the concepts presented in earlier topics. At the very
least, the topics up to and including Controlling Program Flow (p. 691) should be read in order. By
reading the topics in order, you will learn the MAXScript language starting with the basics, and work
your way toward writing full-featured MAXScript utilities. In the later sections, features and
techniques are presented for programmers with more advanced programming experience.
For those new to MAXScript, Learning MAXScript (p. 577) provides an introduction to the features,
syntax, and practical applications of MAXScript.
For information about navigating this online reference, searching, and marking often-accessed
topics, see topics in the last section, Using the HTML Help Viewer (p. 1715).
To see what has been added to MAXScript in 3ds max 4, see What’s New in MAXScript (p. 1).
xxxiv Chapter | Introduction

The MAXScript Utility Panel

The Utility Panel user interface to MAXScript is described in the following topics. It consists of the
MAXScript rollout in the Utilities panel, the Listener window, and MAXScript Editor windows.
To access the MAXScript Utility panel rollout, open the Utilities panel and click the MAXScript
Utility button.

The following options appear in the MAXScript rollout:

 Using the MAXScript Documentation xxxv

Open Listener
Opens the MAXScript Listener window, or restores and brings it to the front if it is minimized or is
behind other 3ds max windows. The Listener window can also be opened by right-clicking in the
Mini Listener in the 3ds max status bar and choosing Open Listener Window, by choosing
MAXScript > MAXScript Listener in the 3ds max menu bar, or by pressing F11.
For Listener window features and commands, see The MAXScript Listener Window (p. xxxvi) topic.

New Script
Opens a new MAXScript Editor window used for writing a new script. A new Editor window is also
opened by choosing MAXScript > New Script in the 3ds max menu bar, or File > New Script in the
Listener window menu bar.
For Editor window features and commands, see The MAXScript Editor Windows (p. xliv) topic.

Open Script
Opens a common File Open dialog for choosing an existing script. A new MAXScript Editor window
then displays the selected script. A script file can also be opened by choosing MAXScript > Open
Script in the 3ds max menu bar, or File > Open Script in the Listener window menu bar.
For Editor window features and commands, see The MAXScript Editor Windows (p. xliv) topic.

Run Script
Opens a common File Open dialog for choosing an existing script. MAXScript then reads and
executes the selected script. Any output is printed to the Listener window. A script file can also be
run by choosing MAXScript > Run Script in the 3ds max menu bar, or File > Run Script in the Listener
window menu bar.
For more information, see the Running Scripts (p. xlix) topic.

Utilities
Displays a list of available scripted utilities. A MAXScript defining a scripted utility must be executed
before the scripted utility name appears in the Utilities list.
For more information, see the Accessing Scripted Utilities (p. l) topic.

Close
Closes the MAXScript Utility rollout. Any scripted Utilities panel rollouts are also closed.
xxxvi Chapter | Introduction

The MAXScript Listener Window

The MAXScript Listener window is an interactive interpreter for the MAXScript language and works
similar to a DOS command prompt window. You enter MAXScript commands in this window, and
when you press ENTER they are executed immediately.
The Listener window is appropriate for performing interactive work and developing small code
fragments. Extended blocks of code should be developed in a Script Editor Window (p. xliv).
Each command you execute in Listener is actually an expression with a result which Listener prints
out after each execution. All commands in MAXScript are expressions or function calls that can look
like commands in other languages. The terms command and expression are synonymous in
MAXScript. You can enter any MAXScript expression or sub-expression in Listener for evaluation,
and Listener prints out its result.

You can open only one instance of the MAXScript Listener window at a time. To open Listener,
choose the MAXScript utility on the Utilities panel and click Open Listener. Other methods for
opening Listener are described in The MAXScript Utility Panel (p. xxxiv) topic.
The Listener window is a resizable, modeless window. You can switch between it and 3ds max as you
work. If you close the Listener window and then reopen it, the text in the window before it was
 Using the MAXScript Listener xxxvii

closed reappears. If Auto Open Listener on Output is checked in Customize > Preferences >
MAXScript, the Listener window opens automatically when a script outputs to it.
Listener is divided into two panes. The top (pink) pane is the Macro Recorder pane, and the bottom
(white) pane is the output pane. When the Macro Recorder is enabled, everything recorded is
displayed in the Macro Recorder pane. The output of results from scripts are displayed in the output
pane. The output of code executed in the Macro Recorder pane is always directed to the output pane
so as not to clutter the recordings. Both panes allow you to cut-and-paste, drag-and-drop, edit, select,
and execute code. You can resize the panes by dragging on the split bar between them.
The left-end of the 3ds max status panel contains a resizable Mini Listener. If the Mini Listener is not
visible, drag on the vertical split bar at the left edge of the status panel to reveal the Mini Listener.
The Mini Listener panes act as single-line sliding windows for the current line in the corresponding
Listener panes. The Mini Listener panes always show what you are typing or where the edit cursor
is placed in the Listener panes. Conversely, anything you type into a Mini Listener pane is entered
into the corresponding Listener pane at the current edit cursor position.
You can install Listener into a 3ds max viewport by right-clicking the viewport label, choosing
Extended, and then MAXScript Listener.

See also
Using the MAXScript Listener (p. xxxvii)

Using the MAXScript Listener

The MAXScript Listener is a combination of text editor and command prompt window. MAXScript
executes the commands you write when you press ENTER, but you can also scroll through the text
to re-execute existing commands, or edit them and then have MAXScript execute the modified code.
Listener has the following features:
• A line selection margin at the left window border. When you move the cursor into the left
margin, it changes to a right-pointing arrow. A single-click selects an entire line, and
click-dragging selects multiple lines.
• Drag-and-drop for copying text within Listener and to and from script Editor windows.
• Selected text is loaded automatically into the search text dialog field when you choose
Search > Find or Search > Replace. This is useful for quickly finding other occurrences of the
selected text.
xxxviii Chapter | Introduction

• Color-coding for distinguishing between input text, output text, and error message text. Three
MAXScript system global variables control these colors, and you can assign them new colors to
customize your Listener.

Text Type Variable Default Color

typed input text inputTextColor black
output text outputTextColor blue
error message text messageTextColor red

For commands within the Listener window, see the Listener Commands (p. xxxviii) topic.

See also
Using the ‘?’ Symbol (p. xli)
Turning on the Listener Log (p. xli)
Controlling the Listener Contents and the Insertion Point (p. xlii)
Including Scripts Within Scripts (p. lix)
Aborting Execution with the ESC Key (p. lv)

Listener Commands
Menu Bar Commands and Keyboard Shortcuts
The following menu bar commands and keyboard shortcuts are available in Listener. The edit
commands listed are also available in the Listener right-click menu. The menu bar commands for
Macro Recorder are described in The Macro Recorder (p. l) topic.

File > Save As, CTRL+S

Opens a common File Save dialog for choosing a file name to which the current contents of the
active Listener pane is stored. All text in the active pane is saved to the specified file.

File > New Script, CTRL+N

Opens a new MAXScript Editor window used for writing a new script.

File > Open Script, CTRL+O

Opens a common File Open dialog for choosing an existing script file. A new MAXScript Editor
window displays the contents of the selected script file.

File > Run Script, CTRL+R

Opens a common File Open dialog for choosing an existing script file. The selected script file
contents are executed.
 Listener Commands xxxix

Edit > Undo, CTRL+Z

If the last change made to the Listener’s content was an edit, undoes that edit. Only one level of
undo is supported. If the last change was a command evaluation, removes all the text printed in
Listener by that command, making it easy to remove large print-outs. Pressing CTRL+Z a second
time restores the removed text and also selects it. This feature can be used as a quick way to cut or
copy a command’s output.

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 > Clear All

Deletes all text in the active Listener pane.

Edit > Select All, CTRL+A

Selects all text in the active Listener pane.

Search > Find, CTRL+F

Displays Find dialog. Performs search in the active Listener pane for the Find What 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 as the Find What text. If matching text is found, the text is selected.

Search > Find Next, CTRL+G

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

Search > Replace, CTRL+H

Displays Replace dialog. Performs search in the active Listener pane 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 is the
specified text.

Help > Help

Displays the MAXScript 4 Online Reference.
xl Chapter | Introduction

Help > About MAXScript

Displays About MAXScript dialog.

CTRL+B
Selects the text in the current bracket. Bracket balancer lets you check bracket balancing in long
pieces 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. If the cursor is next to a bracket, the code bracketed
by it and its matching bracket will be selected and highlighted. If the cursor is not next to a bracket,
the closest bracketed code containing the cursor will be selected. If you press CTRL+B again, the next
outer bracketed fragment is selected, and so on. You can keep pressing CTRL+B to move out through
bracket nestings. If at any point there is a bracket mismatch, the balancer will beep and not select
any text.

End-Of-Text Commands
The simplest way to use the MAXScript Listener is to enter commands at the end of the existing text
and press ENTER. This is called the end-of-text compilation. After each command is executed and any
results are printed to the output pane, you can enter another command and press ENTER, and so on.
When you write new commands at the end of the text in Listener, pressing ENTER executes the last
line and inserts a new line.

Editing and Executing Mid-Text Commands

When you want to use or edit existing text in Listener, you can differentiate between inserting new
lines and executing the current line as follows:
• Press ENTER to insert a new line at the current cursor position.
• Press Number-Pad ENTER to execute the line that contains the cursor. When you reexecute an
existing line, its output and any Error Messages (p. liii) are inserted after the current line if the
output pane is active, or at the current edit cursor location in the output pane if the Macro
Recorder pane is active.
If you do not have a number pad on your keyboard, SHIFT+ENTER is an alternative to the
Number-Pad ENTER key.

Selecting and Executing Commands

You can select multiple text lines and press SHIFT+ENTER to execute all of the selected lines. Each
command in the selection is executed in the order it appears in the selection and any output is
inserted after the entire selection. You can also select a portion of text within a line and press
SHIFT+ENTER to evaluate it, as long as it constitutes a valid MAXScript expression. For example, you
can display the value of a sub-expression in a long equation by selecting and executing only that
sub-expression within a line. The output is inserted after the current line if the output pane is active,
or at the current edit cursor location in the output pane if the Macro Recorder pane is active.
 Using the ‘?’ Symbol xli

Executing Code Blocks

MAXScript commands may be single or multiline commands, or Block Expressions (p. 679). If you
want to enter a block expression or a multiline command within existing text in the MAXScript
Listener window, press ENTER to insert each line. Then drag-select all the lines in the command or
block and press SHIFT+ENTER to execute the lines.
If you enter multiline commands or a block expression at the end of the text in the MAXScript
Listener window, remember that each line is compiled when you press ENTER. The multiline
command isn’t executed until the end of the command is entered, nor are block expressions
executed until the block is closed. While you cannot edit a faulty previous line within the multiline
commands or block expression that has already been compiled but not yet executed, you can edit
any text within the current line before you press ENTER. You can abort the current end-of-text
compilation by pressing the ESC key to start over if necessary.

Installing Code Blocks as Macro Scripts

You can select one or more text lines and drag them to a 3ds max toolbar to create a Macro Script
containing the selected lines. For more information, see the Defining Macro Scripts (p. 1521) topic.

Using the ‘?’ Symbol

Each time you evaluate a command or code selection, the last evaluation result output to the
Listener output pane is captured into an internal variable denoted by the ? symbol. You can access
that value again with the ? symbol. You can use the ? anywhere you normally use a variable name
and MAXScript evaluates the ? as the last Listener result. A common use is to capture the ? value into
one of your own variables for later reuse, such as in the following statement:
x = ?

See also
Using the MAXScript Listener (p. xxxvii)

Turning On the Listener Log

While you work in Listener, you can use the Listener logging feature to capture your entered text
and all printed output into a text file. Only text entered in either pane and printed output to the
output pane is captured. Macro Recorder output is not captured. You turn on logging with the
openLog() method.
openLog <filename_string> [ mode: “w” | “a” ] [ outputOnly:<boolean> ]
where <filename_string> is a string literal or an expression that evaluates to a string,
and specifies the name of the log file to be created. For example:
openLog “my_log.txt”

or:
logfile=”my_log.txt”
openLog logfile
xlii Chapter | Introduction

The default mode (mode:”w”) creates a new file or overwrites an existing file. To append
the log results to an existing file; specify mode:”a”. If the specified file does not exist, an
error message will be generated. Both input and output are logged by default; specify
outputOnly:true to log only MAXScript output. For example:
openLog “my_log.txt” mode:”a” outputOnly:true
would append only the MAXScript output to file my_log.txt.
If a log file is already open, the openlog() method will close that log file.
MAXScript echoes Listener activity as it occurs to the log file until you stop logging. The log file data
is not continuously written to the file, rather the log data is written to a buffer in memory, and when
the buffer is full the data in the buffer is written to the file. You can use the flushLog() method to
ensure the log’s buffer is flushed so that all output is written to the file:
flushLog()

You can stop logging, flush the log’s buffer, and close the log file using the closeLog() method:
closeLog()

No error message is generated if the flushLog() or closeLog() methods are called and no log file
is open.

Controlling the Listener Contents and the Insertion Point

The Listener output pane’s content and insertion point placement can be controlled with the
following methods:
clearListener()
Clears all text from the Listener output pane.
setListenerSel #(<start_integer>,<end_integer>)
Sets the current text selection in Listener. The start and end values are the character offsets
in the Listener output pane text, starting at 0. If the start and end values are the same, no
text is selected and the insertion point is placed at the specified point. You can specify -1
for the start or end values, which specifies the end of the Listener output pane text. For
example, the following would put the insertion point at the end of the text:
setListenerSel #(-1,-1)

while the following would select all of the text in the Listener output pane text:
setListenerSel #(0,-1)

<start_integer> and <end_integer> are integer literals, or expressions that evaluate

to an integer.
getListenerSel()
Returns the current text selection indexes as a two-element array, #(start, end). These
values are the character offsets in the Listener output pane text, starting at 0. If there is no
selection, but only an insertion point, the start and end values are equal. Only the
 Controlling the Listener Contents and the Insertion Point xliii

selections set using the setListenerSel() method are recognized by this method. If no
selection has been set using the setListenerSel() method, the start and end values
returned are the offset to the end of the Listener output pane text.
getListenerSelText()
Returns the currently selected text, or an empty string if no text is selected and only the
insertion point is showing. Only the selections set using the setListenerSel() method
are recognized by this method. If no selection has been set using the setListenerSel()
method, an empty string is returned. For example, the following lines would capture the
entire contents of the Listener output pane to variable ListenerText:
( global ListenerText -- declare variable so its scope is higher
-- than inside just the following block
-- expression
( setListenerSel #(0,-1) -- select all the text
ListenerText=getListenerSelText() -- get selected text
setListenerSel #(-1,-1) -- set insertion point at
-- end of output pane
)
)

setListenerSelText <replacement_string>
Replaces the currently selected text with the replacement string. If no text is selected and
only the insertion point is showing, setListenerSelText() inserts the replacement
string at the insertion point. Only the selections set using the setListenerSel()
method are recognized by this method. If no selection has been set using the
setListenerSel() method, the insertion point is the end of the Listener output pane
text. <replacement_string> is a string literal or an expression that evaluates to a string.
include <filename_string>
Inserts the specified file’s content into the Listener output pane. The inserted text is not
evaluated. You can use this method to load a script and then step through it, executing
any selected text with SHIFT+ENTER. <filename_string> is a string literal or an
expression that evaluates to a string, and specifies the name of the file to insert. Example
uses are:
include “my_script.ms”

or:
scriptfile=”c:\\my_scripts\\my_script.ms”
include scriptfile

If you don’t explicitly specify a directory in the file name, the file will be searched for in
the following directories, in the order listed:
xliv Chapter | Introduction

• The current MAXScript directory

• The 3ds max executable main directory
• The Windows NT 32-bit system directory (system32)
• The Windows 16-bit system directory (system)
• The Windows directory
• The directories that are listed in the PATH environment variable

The MAXScript Editor Windows

MAXScript Editor windows are text editor windows you can open within 3ds max and use to create
or edit text files, notably MAXScript script files. Press Open Script on the MAXScript rollout, File >
Open Script in the Listener menu bar, or MAXScript > Open Script in the 3ds max menu bar to open
an existing script file. MAXScript opens the selected script in a modeless MAXScript Editor window,
such as the one shown.

To create a fresh script, press New Script on the MAXScript rollout, File > New Script in the Listener
menu bar, or MAXScript > New Script in the 3ds max menu bar to open a new, empty MAXScript
Editor window. You can write and edit text, including drag-and-drop editing, in the MAXScript
Editor as you would in other editors like WordPad. The menus are similar to those in many standard
Windows text editors. You may have any number of MAXScript Editor windows open at the
same time.
 The MAXScript Editor Windows xlv

MAXScript Editor is suited to developing longer scripts or code fragments you want to keep. You can
edit and test parts of them until they are complete, then save your code in a script file for later use.
This is a common method for developing large scripts, utilities, and function libraries.
You can select one or more text lines and drag them to a 3ds max toolbar to create a Macro Script
containing the selected lines. For more information, see the Defining Macro Scripts (p. 1521) topic.
You can open a MAXScript Editor window from within the Listener or from other running scripts
by calling the edit() method. The syntax for the edit() method is:
edit <filename_string>
where <filename_string> is a string literal or an expression that evaluates to a string,
and specifies the name of the file whose contents are to be loaded into the new MAXScript
Editor window. Example uses are:
edit “my_script.ms”

or:
scriptfile=”my_script.ms”
edit scriptfile

The file will be searched for in the following directories, in the order listed:
• The current MAXScsript directory
• The 3ds max executable main directory
• The Windows NT 32-bit system directory (system32)
• The Windows 16-bit system directory (system)
• The Windows directory
• The directories that are listed in the PATH environment variable
You can create an empty MAXScript Editor window from within the Listener or from other running
scripts by calling the newScript() method. The syntax for the newScript() method is:
newScript()
Opens an empty MAXScript Editor window and returns a WindowStream value that may
be used as the target for print and format operations. This is useful for directing output to
a separate window for ease of inspection or editing, or later saving to a file. Output to a
WindowStream is inserted at the current cursor position in that window. For example:
debug = newScript()
...
print $foo to:debug
...
format “name is %\n” obj.name to:debug

If you need to locate the source of a scripted function, you can use the showSource() method. It
displays a MAXScript Editor window containing the source file in which the function was defined,
positioned at the function’s definition. The form is:
showSource <fn>
xlvi Chapter | Introduction

A MAXScript Editor window has the following features:

• Titles that display only the current script’s file name, rather than its full path name, so
minimized MAXScript Editor windows can be easily distinguished.
• A line selection margin at the left window border. When you move the cursor into the left
margin, it changes to a right-pointing arrow. A single-click selects an entire line, and
click-dragging selects multiple lines.
• Drag-and-drop for copying text to and from other MAXScript Editor windows, the Listener
window, or any other text editor window that supports Window’s drag-and-drop.
• Selected text is loaded automatically into the search text dialog field when you choose
Search > Find or Search > Replace. This is useful for quickly finding other occurrences of the
selected text.
For commands use within the MAXScript Editor window, see the MAXScript Editor
Commands (p. xlvi) topic.

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

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 window’s scroll position does not change.
 MAXScript Editor Commands xlvii

Edit > Undo, CTRL+Z

Undoes the last change made to the MAXScript Editor’s content. Only one level of undo is
supported.

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 > Find, CTRL+F

Displays Find dialog. Performs search in the MAXScript Editor for the Find What 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 as the Find What text. If matching text is found, the text is selected.

Search > Find Next, CTRL+G

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

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.

Help > Help

Displays the MAXScript 4 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.
xlviii Chapter | Introduction

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.
If you have a number pad on your keyboard, the Number-Pad ENTER key is an alternative to
SHIFT+ENTER and can be used to execute commands. You may find the Number-Pad ENTER key
faster and easier to use.

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. Select one of the items in
the pop-up menu to position that definition at the top of the MAXScript Editor window. This
simplifies large script navigation.
 Running Scripts xlix

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. If the cursor is next to a bracket, the code bracketed
by it and its matching bracket will be selected and highlighted. If the cursor is not next to a bracket,
the closest bracketed code containing the cursor will be selected. If you press CTRL+B again, the next
outer bracketed fragment is selected, and so on. You can keep pressing CTRL+B to move out through
bracket nestings. If at any point there is a bracket mismatch, the balancer will beep and not select
any 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 light red. This often helps in reading large, complex programs. New text is always colored black
and you have to press CTRL+D at some point to recolor the script. Syntax coloring is a programming
aid and does not effect script execution.

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. This feature allows you to quickly review the code pieces you
recently worked on.

Running Scripts
To run an existing script file, press Run Script on the MAXScript rollout, File > Run Script in the
Listener menu bar, or MAXScript > Run Script in the 3ds max menu bar. This opens a common File
Open dialog for choosing the script. MAXScript then reads and executes the selected script. Any
output is printed to the Listener output pane.
You can also run a script from Listener or from within other scripts using the fileIn() method:
fileIn <filename_string> [ quiet:<boolean> ]
where <filename_string> is a string literal or an expression that evaluates to a string,
and specifies the name of the script file whose content is executed. The script file content
is executed one expression at a time, and halts processing if an error is encountered at any
point. By default, the file is not listed as it is loaded; use quiet:false to get a running
listing to the Listener. Example uses are:
fileIn “my_script.ms”

or:
scriptfile=”my_script.ms”
fileIn scriptfile
l Chapter | Introduction

The script file content is compiled in a global scope context, as opposed to the scope in effect when
the filein() method is executed. For more information, see the Scope of Variables (p. 646) topic.

Accessing Scripted Utilities

The Utilities list in the MAXScript rollout contains scripted utilities that have been defined in startup
scripts or while working in MAXScript. For details about defining scripted utilities, see the Scripted
Utility Panels (p. 1464) topic.
As soon as you define a utility, MAXScript adds the utility’s name to the Utilities list. When you
select a utility from this list, its rollout is added to the Utilities panel after the MAXScript rollout.
You can open as many utilities as you need, and close each one with its designated Close button.
If you modify and reexecute the script for an open utility rollout, that rollout is replaced
immediately with the updated rollout. This lets you develop scripted utility rollouts incrementally
with immediate, visual feedback.

The Macro Recorder

The MAXScript Macro Recorder captures many of the actions performed by the user, and generates
the MAXScript commands that correspond to those actions. Output from Macro Recorder is
displayed in the Macro Recorder pane of the MAXScript Listener window. Several filtering options
are available that control what types of user actions are recorded, whether the generated MAXScript
commands contain explicit object references or are selection-relative, and whether the generated
MAXScript commands contain explicit or relative transforms and coordinates. These options are set
using the MacroRecorder menu in the Listener window. The default option settings are specified in
the MAXScript page of the 3ds max Preferences dialog, as described in the MAXScript Preferences
Settings topic in the 3ds max online help. These settings can also be changed or set by editing the
[MAXScript] section of the 3dsmax.ini file.
While many areas in 3ds max 4 generate Macro Recorder output, there are also many areas that do
not. In general, most of the buttons on the 3ds max Menu Bar, toolbars, Status Bar, Create panel,
and Modify panel will generate Macro Recorder output. If the button invokes a secondary dialog,
changing setting or performing actions in the secondary dialog typically will not generate Macro
Recorder output. In the Create and Modify panels, Macro Recorder output will be generated if the
object or modifier can be created by MAXScript. In some cases, the plug-in implementing an object
or modifier has not been updated to support Macro Recorder, so that object or modifier will not
generate Macro Recorder output. Future versions of 3ds max and 3ds max plug-ins will be updated
to support the Macro Recorder and will generate Macro Recorder output when used.
MAXScript supports text drag-and-drop onto toolbars to create Macro Script buttons. You can select
and drag text from any text window, such as Listener window panes or Editor windows, onto any
visible toolbar. The cursor changes to an arrow with a + sign when it is OK to drop the text. If you
drop it, a Macro Script button is added to the toolbar with the dropped text as the body of the Macro
Script. The classic case here would be to drag text from the Macro Recorder pane onto a toolbar to
 The Macro Recorder li

make a button that does the sequence of events just recorded. For more information, see the Defining
Macro Scripts (p. 1521) topic.
The following Macro Recorder menu commands are available in Listener:

Enable
When Enable is selected the Macro Recorder will generate MAXScript commands.

Explicit Scene Object Names/Selection-Relative Scene Object Names

Specifies whether to use explicit scene object names or the selection set token in the generated
commands if only one object is selected. If more than one object is selected, the selection set token
is always used. For example, if Explicit Scene Object Names is enabled, a typical generated command
would be:
move $Sphere03 [55.6739,23.5,0]

If Selection-Relative Scene Object Names is enabled, a typical generated command would be:
move $ [0,-47.8044,0]

By using Selection-Relative Scene Object Names, you can apply the recorded script to a different
selection, thereby making it somewhat general. Use Explicit Scene Object Names if you want the
script to always work on the same objects regardless of the current scene selection.

Absolute Transform Assignments/Relative Transform Operations

Specifies whether to use absolute or relative transform commands in the generated commands. For
example, if Absolute Transform Assignments is enabled, a typical generated command when you
move a selection in a viewport would be:
$.position = [55.6739,23.5,0]

If Relative Transform Operations is enabled, a typical generated command would be:

move $ [0,-47.8044,0]

When the Absolute Transform Assignments option is selected, absolute transform assignments are
output only if a single object is transformed. If multiple objects are selected, relative transform
operations are output.

Explicit Sub-object Sets/Selection-Relative Sub-object Sets

Specifies whether to use explicit sub-object identifiers or the sub-object selection set property in the
generated commands. For example, if Explicit Sub-object Sets is enabled, a typical generated
command would be:
move $Sphere02.verts[#{20..32, 51..65}] [40.0986,10.3648,0]

If Selection-Relative Sub-object Sets is enabled, a typical generated command would be:

move $Sphere02.selectedVerts [40.0986,10.3648,0]
lii Chapter | Introduction

By using Selection-Relative Sub-object Sets, you can apply the recorded script to a different selection,
thereby making it somewhat general. Use Explicit Sub-object Sets if you want the script to always
work on the same sub-objects regardless of the current sub-object selection.

Command Panel Switchings

When Command Panel Switchings is selected, the Macro Recorder will generate MAXScript
commands for command panel switches. In most cases, recording command panel switches is
superfluous as most scripts are not dependent on the user interface mode to work.

Tool Selections
When Tool Selections is selected, the Macro Recorder will generate MAXScript commands for the
selection of tools in the 3ds max toolbar. In most cases, recording the selection of tools is superfluous
as most scripts are not dependent on the tool selection to work.

Menu Item Selections

When Menu Item Selections is selected, the Macro Recorder will generate MAXScript commands for
the selection of menu items from the 3ds max menu bar.

General MAXScript Topics

This section presents topics that supply information on general MAXScript topics.
Error Messages (p. liii)
Aborting Execution with the ESC Key (p. lv)
MAXScript Desktop State (p. lvi)
Startup Scripts (p. lvi)
Running Scripts from the Command Line (p. lvii)
The Scripts Included with 3ds max (p. 624)
Source Code Layout and Continuation Lines (p. lvii)
Including Scripts within Scripts (p. lix)
Encrypting Script Files (p. lx)
 Error Messages liii

Error Messages
When MAXScript detects a runtime error in your script, it displays an error message and prints
diagnostic information to the Listener output pane. If the error occurs in a controller script or rollout
panel script, the error message is displayed in an Alert Box window, otherwise it is printed in the
Listener output pane.
The diagnostic information is in the form of a call stack trace-back which can help determine the
cause and location of the error in your code. The call stack trace-back shows the nesting of called
MAXScript functions at the point of error, deepest ones first to outermost ones last. The call stack
trace-back also displays the values in all the local variables and function parameters at the levels they
are declared or first used. Note that for loops produce separate entries in the call stack trace-back
and include a variable dump for the loop variable and any locals in the loop body.
As a further aid in locating the error, MAXScript shows the line in which the error occurred in an
MAXScript Editor window if the running code was compiled from a source file (any code not entered
directly in the Listener). If the source file is not currently open in a window, MAXScript opens the
file in a new MAXScript Editor window. The line containing the code in which the error occurred is
highlighted and scrolled into view. The error message is either displayed in a Alert Box window or
the Listener window. In both cases, the Alert Box or Listener window is brought to the front and the
MAXScript Editor window containing the code causing the error is immediately behind.
All compile and runtime error messages reported in the Listener output pane are preceded by the
comment symbol “--”, so you can reselect and evaluate code in Listener that might have embedded
error messages and not have them cause syntax errors.
In the following figure, an Editor and a Listener window are shown where an error was detected
while running the script. The error occurred in the highlighted line in the Editor window. Looking
at the call stack trace-back, we see the error occurred when the for loop variable i is equal to 6. In
the line in error, the position of the object specified by the sixth element of array b is being set. After
further investigation, it was found the array b only had five elements defined. Thus element b[i]
contained the value undefined, which resulted in the error as there is no position property
associated with undefined.
liv Chapter | Introduction

In the following figure, an error dialog and script controller dialog are shown. An error was detected
while running the script assigned to a script controller. This error was caused by the deletion of
object box02, whose position was used in the script.
 Aborting Execution with the ESC Key lv

Aborting Execution with the ESC Key

You can abort running MAXScript code by pressing and holding the ESC key. MAXScript may take
a moment to respond, so hold the ESC key down until it does. The ESC key aborts any currently
executing MAXScript code, whether it is in a scripted utility, a script controller, or running in the
MAXScript Listener window. If the MAXScript code that is aborted is in a script controller, a Script
Controller dialog is displayed showing the script used by the controller. Execution of the script
controller will restart when you click the Close button.
MAXScript code locks out the rest of 3ds max while it is executing. You cannot work interactively in
3ds max while MAXScript code is running to avoid conflicts between code actions and your actions.
If 3ds max appears unresponsive at any time, it may be running MAXScript code which you can
attempt to abort by pressing ESC. If you are testing scripts and 3ds max doesn’t return control to you
within a reasonable time, press ESC to abort the code execution. You can also press ESC to abort a
compilation of a multiline command in the MAXScript Listener window.
Use the MAXScript global variable escapeEnable in scripts to turn on and off the ESC key interrupt
detection.
lvi Chapter | Introduction

MAXScript Desktop State

MAXScript remembers the state of its desktop (the location of active Editor and Listener windows)
when you exit 3ds max and restores this state when you restart MAXScript. Any MAXScript Editor
files missing when you restart will not have their windows reopened.
The desktop state is stored in a file called maxscrpt.dsk in the 3ds max executable directory. You can
rename this file and replace it if you want to keep several desktop setups configured, or simply delete
it so the current desktop will not be restored.

Startup Scripts
When the 3ds max is first started, MAXScript searches for any startup script files that it then
automatically loads and runs. This feature is useful if you have function libraries you always use and
want preloaded, or if you want to establish custom UI settings, define scripted plug-ins, or load
scripted utility rollouts.
The automatic loading of startup script files can be deactivated by turning off the Auto Start
MAXScript option in the MAXScript page of the 3ds max Preferences dialog, as described in the
MAXScript Preferences Settings topic in the 3ds max online help.
MAXScript first searches for a file named startup.ms in the following directories, in the order listed:
• The Scripts directory (defined in the 3ds max Configure Paths dialog)
• The Startup Scripts directory (defined in the 3ds max Configure Paths dialog)
• The 3DS executable main directory
• The Windows NT 32-bit system directory (system32)
• The Windows 16-bit system directory (system)
• The Windows directory
• The directories that are listed in the PATH environment variable
MAXScript stops searching when it finds the first occurrence of startup.ms.
MAXScript then recursively scans the 3ds max plug-ins and Startup Scripts directories (both defined
in the 3ds max Configure Paths dialog) and directories nested within them for .ms and .mse script
files and loads them. In this pass, any script files with the name startup.ms are ignored. This allows
you to place your scripted plug-in scripts in the 3ds max plug-in folders for automatic loading. They
can be managed like DLL plug-ins, and used to organize your startup scripts into groups in their own
directories for easier management. You can prevent a nested directory from being scanned by
placing its name in parentheses, for example “(old-versions)”, allowing you to enable and disable
scripts in handy directory-based groupings.
 Running Scripts from the Command Line lvii

Running Scripts from the Command Line

You can launch 3ds max from a DOS command line and have it run a specified launch script, which
is useful for tasks such as unattended batch-rendering. This capability uses the existing -U 3ds max
command line switch that names a utility to be run when 3ds max is started. The -U switch allows
an optional extra argument which, for MAXScript, is taken to be the name of the launch script to
run. The case of MAXScript must be as shown in the following example:
c:\3dsmax\3dsmax -U MAXScript rendercams.ms

This example command line would launch the 3ds max executable in c:\3dsmax, start MAXScript,
and then have it run the launch script rendercams.ms.
The following example launch script loads two scenes, renders frames from each of the cameras in
them, and then quits 3ds max:
loadMaxFile “foo.max”
for c in cameras do render camera:c outputfile:(”foo_”+c.name+”.bmp”)
loadMaxFile “baz.max”
for c in cameras do render camera:c outputfile:(”baz_”+c.name+”.bmp”)
quitMax #noPrompt

This example makes use of the quitMax() method to exit 3ds max (see Exiting and Resetting
3ds max (p. 1669) ) when the script is finished. Launch scripts need not be batch scripts as in this
example, but may be used to condition 3ds max for interactive use, for example by loading a scene
file and setting some user-interface options.
The normal startup scripts, startup.ms and those in the Startup Scripts directory, are run before the
launch script.
It is also possible to install scripts into individual scene files that run automatically when that scene
is open or closed or at certain other events (see General Event Callback Mechanism (p. 29)).

Source Code Layout and Continuation Lines

The layout rules for MAXScript code are unlike those of most programming languages and give you
the advantages of freeform languages, such as C and C++, but without the need for extensive
punctuation, like semicolons and parenthesized parameter lists.
MAXScript lets you break statements and expressions across lines wherever you want, providing the
line break is in the middle of an expression. MAXScript reads your code until the end of each line
and determines whether it has a complete expression. If it does not, it continues to read subsequent
lines until it finds the rest of the expression.
lviii Chapter | Introduction

Take as an example the following line:

a + b * c / d - e + f * g / h

This line can be broken after any of the operators. MAXScript continues to read the next line,
because an operator needs another argument. For example:
a + b * c / d - e +
f * g / h

You cannot break the example line as shown next and get the same result, because the expression
on the first line is a complete expression. MAXScript considers the two lines as separate expressions,
and the second line is now syntactically wrong, because it starts with an operator.
a + b * c / d - e
+ f * g / h

This scheme allows you to write the following forms of the same statement without using periods
or semicolons, as you might in other freeform languages. For example, a if/then/else construct could
be written as:
if a < b then print c else print d

or,
if a < b then print c
else print d

or,
if
a < b
then
print c
else
print d

If you do want to break a line at the end of a sub-expression, you can use the backslash line
continuation character: ‘\’. The previous example above of an invalid break can be made valid using
the line continuation character after the ‘e’:
a + b * c / d - e \
+ f * g / h

Whenever MAXScript encounters a ‘\’ as the last character on a line, except for spaces, tabs, or
comments, it continues to read the next line as though the line break were not present.
Line continuations are often used to break up function calls with many arguments, as shown in
many of the Expressions (p. 667) topics.
MAXScript also lets you combine multiple statements and expressions in a single line. The
statements or expressions are separated with a ‘;’.
 Including Scripts Within Scripts lix

Examples:
print “End of input data reached” to:f ; close f ; f = undefined
if a < 0 do (print “value out of range”;a=0)

Comments in MAXScript begin with a double-hyphen (‘--’) and extend to the end of the current
line. Many code examples in this help file use comments in this style.
Example:
-- special cases...
if first do
subanims[6]=undefined -- subanims[6] is #Image_Motion_Blur_Multiplier

Including Scripts Within Scripts

MAXScript provides a compile-time source-file include mechanism, allowing you to break up large
scripts into smaller files that can be included at nearly any point in a script. You can use the
include <file> construct at any point in your code to effectively insert the contents of a file at
that point in your code. The form is:
include “filename_string”
This is a compile-time construct, therefore the file name specification must be a string literal, and
not a variable or an expression.
Example:
utility foo “Baz”
(
local a, b, c
include “foo-ui.ms”
rollout bar “Bar”
(
include “bar-rollout.ms”
)
include “foo-handlers.ms”
)

The include <file> construct is effectively replaced in the source code at that point with the
contents of the named file.
You can nest included files as deeply as needed; included files can include other files, and so on.
Because include is a compile-time construct, the current MAXScript scope is maintained within the
included file. This is opposed to the fileIn() method described in the Running Scripts (p. xlix) topic,
whose script file content is compiled in a global scope context. For more information, see the Scope
of Variables (p. 646) topic.
lx Chapter | Introduction

The include <file> can appear at any point a new token is expected, such as a name, literal, or
punctuation. This means that you could complete a partial expression with an included file. For
example:
include “op1.ms” + include “op2.ms”
if include “test2.ms” then print a else print b

You cannot place an include <file> within a token. For example, the following is not valid:
timeval = 2:include “framenum.ms”.0

Encrypting Script Files

MAXScript lets you create an encrypted copy of a specified script file with the same name prefix, but
with the suffix .mse, in the same directory as the source script file. The encryption uses a fixed
hidden key that lets it run on any 3ds max system, but effectively hides the source of the script.
Encrypted script files have the suffix .mse. To encrypt a script, use the following MAXScript method:
encryptScript <filename_string>
where <filename_string> is a string literal or an expression that evaluates to a string,
and specifies the name of the script file whose contents are encrypted. Example uses are:
encryptScript “my_script.ms”

or:
scriptfile=”my_script.ms”
encryptScript scriptfile

The encrypted script file from the previous examples would be named my_script.mse.
The Run Script button in the MAXScript rollout and the fileIn() method described in the Running
Scripts (p. xlix) topic automatically support .mse encrypted scripts.
You can couple this script source code encryption with the hardwareLockID variable and the
encrypted file I/O functions to provide authorization-based protection for your scripts.

Syntax Definitions in This Document

The ways you can write MAXScript tokens and clauses are given using a set of shorthand rules as
shown in the following example:
[-]{<digit>}[.{<digit>}][(e | E)[+ | -]{<digit>}+]
These rules, or syntax definitions, follow the standard EBNF notation (Extended Backus-Naur Form).
The previous example shows the syntax for a decimal number in MAXScript. The rules typically
contain a number of characters with special meanings. For example, brackets enclose optional items,
such as the minus sign in front of the number. Braces enclose items you can use repeatedly, and bars
separate multiple items from which you can choose one. Sometimes, rules are given names so they
can be referred to in the documentation or as parts of other rules. The special characters in the rules
have the following meaning:
 Encrypting Script Files lxi

[...] -- items inside the brackets are optional

(...|...|...) -- choose one of the items separated by the bars
{...} -- you can specify the braced item ZERO or more times
{...}+ -- you can specify the braced item ONE or more times
::= -- define a name for a syntax rule
<rule> -- you can insert what is defined by the named rule
bold_characters -- characters or token as written

The previous number syntax example is interpreted as follows:

Syntax Definition
[-]{<digit>} an optional minus sign (the sign), followed by 0 or more digits (the integer part),
followed by
[.{<digit>}] an optional sequence (the fraction part) comprised of:
a period character, followed by 0 or more digits, followed by
[(e | E)[+ | -]{<digit>}+] an optional sequence (the exponent part) comprised of:
either an ‘e’ or ‘E’, followed by an optional plus or minus sign, followed by one or
more digits.

Examples of valid numbers are:

123
1.456
-0.89e-7
1.536E23

The following numbers are not valid:

12x34
-0.45x10^3
0e

The syntax definitions in the MAXScript Grammar (p. 1681) topic are in the form of named rule
definitions. For example:
number ::= [-]{<digit>}[.{<digit>}](e | E)[+ | -]{<digit>}+]
allowing the rule to be referred to by name in other rules in the grammar. An example of such a
rule is:
mod <number1> <number2>
modulo arithmetic, the remainder when <number1> is divided by <number2>
Some definitions throughout this document also use the convention of showing alternative
definitions for a rule on consecutive lines instead of separating them with the ‘|’ symbol.
lxii Chapter | Introduction

Objects and Classes in Object-Oriented Programming

To understand the terminology associated with MAXScript, a basic understanding of object-oriented
programming is required.
All of the values you work with in MAXScript have a well-defined type, such as integer, matrix3, or
twist. The type of a value is also known as its class, following the convention of modern object-
oriented languages. We’ve been using a somewhat neutral convention so far of calling the things
you compute with values. The term for these things in object-oriented languages is, not surprisingly,
object. The terms object and value are synonymous in this document. An object is a particular instance
of an class.
For example, in MAXScript Box is a class. It is not a box as shown in 3ds max, but rather defines the
characteristics such a box has. These characteristics include the ways to create an instance of the Box
class (a box object); the properties of a box object (such as Height, Width, and Length); and
operations you can perform on a box object (such as move, copy, and delete). To create a box object,
you would say:
b=box()
In this line box() is a constructor - it causes a box object to be created, and returns a reference to
the box object. This reference is then stored in variable b. No parameters (such as Height, Width,
and Length) were supplied for the constructor, so the default values specified by the Box class are
used. In the 3ds max viewports, the box object is displayed, and can be manipulated like any other
object you create in 3ds max. If parameters are supplied for the constructor, these parameters replace
the “()”. For example:
b=box width:10 length:100
creates a box object with the supplied parameters. All unsupplied parameters will use their
default values.
MAXScript is internally object-oriented. All the built-in classes are arranged in an inheritance
hierarchy and most of the built-in functions are polymorphic, terms we’ll explore below. You cannot,
however, create new classes in MAXScript and the functions you can script are not polymorphic.
This may change in later versions of MAXScript, but it is an advanced refinement that is not really
necessary in an application scripting language, where the most important abstractions are the
features of the host application and are already built-in.

See also
Inheritance and Polymorphism (p. lxiii)
Properties, Methods, Operators, and Literals (p. lxiv)
 Inheritance and Polymorphism lxiii

Inheritance and Polymorphism

Inheritance and polymorphism are the two defining characteristics of object-oriented languages.
Inheritance is the ability of an object class to inherit the operations and properties of its parent class.
Polymorphism is the ability of a single-named operation to work on different values of different
object classes. We’ll explore them here to see how they are used in 3ds max and MAXScript.
First and foremost, both characteristics depend on the system having a well-defined type, or class,
for every value. Assigning classes to values divides all the values you can work with into groups, each
of which have well-defined operations and properties for their values. In some languages, like
standard C++, the class is only manifest at compile-time. In others, like Smalltalk and MAXScript,
the classes are actual runtime entities and every value has a runtime class-tag that says what class it
is. This is the main reason MAXScript can have type-free variables. It can look at the class-tag of the
value in a variable at runtime to determine its class.
Once the objects are grouped into classes, the groups themselves can be arranged into hierarchies.
We do this all the time in real life. A classic example is the biological hierarchy, arranging real-life
objects hierarchically into animals and plants and mammals and vertebrates and humans and adults
and children, and so on. An object-oriented language provides a way to arrange value classes into
hierarchies and, like the hierarchies we are used to, a class at some point in the hierarchy shares all
the operations and properties of all its parent classes. This sharing is known as inheritance in
object-oriented languages, and the operations and properties defined for a class are automatically
inherited by all of its descendant classes. As an example, the following is the hierarchy for the
Box class:
Value
MAXWrapper
Node
GeometryClass
Box

Various characteristics are defined for a class, and each lower class inherits those characteristics. For
example, the classOf() method is defined for class Value, and class Box inherits this method
through its hierarchy. Thus you can specify a Box object as a parameter to the classOf() method.
In the MAXScript Class Hierarchy (p. 1688) topic, all the built-in classes in MAXScript are laid out in
their place in the hierarchy so you can see for each class the classes it inherits characteristics from.
Some of the hierarchy comes from within 3ds max itself which is internally object-oriented. All of
its objects, modifiers, controllers, and so on are arranged in a well-defined inheritance hierarchy.
Once the objects have been grouped into classes, the symbology for the operations that can be
performed on objects of each class can be simplified. The classic example of this comes from
mathematics. The symbolic operators ‘+’, ‘-’, ‘*’, and ‘/’ are shared among many types of values
(integers, reals, complex, vectors, matrices, and so on), and perform the correct action on the types
they are applied to. This capability for a single-named operation to work on different types is called
polymorphism. Object-oriented languages let you use the same name for different methods or
operators across different classes, and the correct method to apply is automatically determined based
on the class of the value it is used with.
lxiv Chapter | Introduction

In MAXScript, all math operators and methods are polymorphic in this sense and reflect the
standard mathematical conventions. An interesting example for 3ds max use is the random()
method. It takes two arguments and generates a random value between them. So, if you give it floats
it gives you a float back; if you give it 3D points, it gives you a random point in the box they define
the corners of; if you give it quaternions, it gives you back a random rotation between them, and
so on.
Further, all the methods that work on 3ds max objects are polymorphic within their hierarchies. So
move, hide, and select work on all types of scene objects; time scaling and insertion work on all the
types of controllers, and so on.

Properties, Methods, Operators, and Literals

One principle of object-oriented programming is that how a class operates internally is hidden. All
interactions with a class are defined by the external interfaces for the class. These external interfaces
are broken up into several categories.
Properties: Accessible parameters for objects of the class. Examples of properties are height, width,
and length for boxes, and radius for spheres.
Methods: Defines all the functions you can call for objects of the class. Examples of methods are
moving or rotating a 3ds max object, adding a modifier to a 3ds max object, and accessing the
position of vertices in a 3ds max object. The terms method and function are synonymous in this
document.
Operators: Defines the math and other symbolic operators that are defined on values in the class.
An example of an operator is the ‘-’ operator, which will perform a mathematical operation on
numbers, colors, vectors, and matrices, but will perform a Boolean subtraction when used with
3ds max objects.
Constructors: The various ways you can create objects of the class. For example Point3 0 0 0 and
<color> as Point3 are constructors for the Point3 class. Executing either of these constructors
will create a new Point3 object.
Literals: Any literal form for objects of the class. For example [0,0,0] is a literal form for the Point3
class, and “Hello world” is a literal form for the String class.
Chapter 1: What’s New in 3ds max 4 MAXScript

What’s New in 3ds max 4 MAXScript

MAXScript has been greatly expanded in 3ds max 4 so that almost all actions in the software are
now scriptable. Much of this exposure is due to Function Publishing and interfaces (p. 67).
Additionally, the exposure is an automatic result of more plug-ins moving from ParamBlocks to
ParamBlock2s. The remaining exposure used the MAXScript SDK to expose functions to MAXScript.

Note:
ParamBlock2s make it possible for plug-ins to host all of their user visible parameters in one or more
parameter blocks, including complex parameters such as ReferenceTargets, Sub-Anims, dynamic
parameter tables (Tabs<>), and class parameters. The parameter blocks handle old-version loading
and reference management automatic. They augment the Parameter Map mechanism to provide
automatic UI for the new parameter types including common MAX controls such as node pickers,
texmap selectors, etc. as well as listboxes for tabular parameters and, further, to automate the
construction of ParamMaps and ParamDlgs in common situations. Additionally, ParamBlock2’s
provide a system that describes all the parameter blocks and parameters of a plug-in along with a
metadata ‘reflection’ API so that systems like the MAXScript, the Macro Recorder, Schematic View,
and custom exporters can access plug-in data automatically. This metadata includes version and
position-independent parameter IDs and both localized and fixed machine-parsable names for all
classes and parameters. This helps to address version compatibility and scripter/exporter
localization issues.
For design details see the 3ds max sdk help file topic “Parameter Blocks and Maps in Release 3”.

Note:
The MAXScript SDK is a set of Visual C++ headers and import libraries that C++ programmers can
use to extend MAXScript. These extensions can be in the form of new built-in functions, new system
globals or descriptors for new MAX plug-in class properties. This is useful for 3rd-party plug-in
developers to write custom scripting interfaces for their plug-ins, and for programmers to do custom
C++ performance code and drive it with scripts for hybrid tools.
2 Chapter 1 | What’s New in 3ds max 4 MAXScript

The scripter SDK allows extensions to be added either incrementally through a MAXScript-specific
DLL file type that is loaded by MAXScript or by runtime calls directly to MAXScript from within an
existing plug-in.
For design details see the 3ds max sdk help file topic “MAXScript SDK”.

Note:
The areas in this documentation exposed by Function Publishing will document the interface
information provided by the “showInterfaces” function (p. 159), in three sections: Properties,
Methods, and Actions. In the Properties section, each property exposed by the interface is
listed along with its data type or enumeration values and whether the property can be read and
written to. In the Methods section, each method is listed along with its return type and its argument
list. The value type for each argument is shown. If the return type is shown as <void>, the method
returns a value of ‘ok’. Methods that are used by Actions are commented as such. These methods
typically require that the object be selected and active in the appropriate command panel. In the
Actions section, each Action is listed along with its category and action description as shown in
the Customize User Interface dialog, and the shortcut keys, if any, assigned to the Action.
The following topics are new to MAXScript:
• Learning MAXScript (p. 577): Walkthrough tutorial for beginning MAXScript users.

Additional Note:
The name of the atmosphere in releases prior to 3ds max 4 known as the “Combustion effect” is now
called “Fire Effect”.
The following are new MAXScript features in 3ds max 4:
Action Manager:
Action Manager (p. 9)
ActiveX Controls in MAXScript Rollouts:
ActiveX Controls in MAXScript Rollouts (p. 10)
Asset Browser:
Asset Browser enhancements (p. 22)
Bones:
Access to the new node bone properties and methods (p. 23)
Bone Creation (p. 25)
Cache Modifiers:
Point Cache Modifier (p. 26)
CallBack Notification Codes:
RenderEffect Progress Callback Mechanism (p. 28): You can control the main RenderEffects
dialog progress bar using several callbacks.
Notify Callbacks for Animate button on and off Transitions (p. 27)
Color Manager:
Color Manager (p. 35)
 What’s New in 3ds max 4 MAXScript 3

Combustion:
Combustion (p. 38)
Constraints:
Path Constraint (p. 39)
LookAt Constraint (p. 40)
Orientation Constraint Controller (p. 40)
Position Constraint (p. 41)
Link Controller for Constraints (p. 42)
Controller Functions for use with Constraint Assignments (p. 42)
Context Filters:
Context Filters (p. 43)
Custom Attributes:
Scripted Custom Attributes (p. 45)
Depth of Field:
Depth of Field (p. 54)
Edit Mesh:
ApplyOperation function (p. 54)
Editable Patch:
Patches (p. 55)
Filters:
class id filter (p. 59)
Selection Filter (p. 61)
iDrop - drag and drop:
iDrop - drag and drop (p. 62)
Interfaces:
Interfaces (p. 67)
Core Interfaces (p. 70)
Other Interfaces (p. 71)
Inverse Kinematics:
HD IK controller chains can be assigned to existing hierarchies (p. 73)
IKLimb Solver (p. 74)
Materials:
Multi/Sub Material (p. 75)
Menu Manager:
Menu Manager (p. 75)
Mesher:
Mesher (p. 82)
Network Render Interface:
Network Render Interface (p. 82)
4 Chapter 1 | What’s New in 3ds max 4 MAXScript

Node Handles:
Node Handles (p. 83)
Node vertexColorType:
Node vertexColorType (p. 83)
OLE Automation:
MAXScript.reg - Registery file (p. 84)
Parameter Wiring:
Parameter Wiring (p. 85)
Plug-In Manager:
Plug-In Manager (p. 86)
Portable Licence Manager:
maxOps (p. 87)
Quad Menu:
Quad Menu (p. 90)
Reactors:
Reactor controller (p. 91)
Render Elements Manager:
Render Element Manager (p. 92)
Scripted Plug-In:
type:#integer parameters in scripted plug-in parameter blocks (p. 93)
Scripted Plug-in Events (p. 93)
Scripted Cameras:
Scripted Cameras (p. 94)
Scripted Controllers:
dependsOn For Scripted Controllers (p. 95)
Matrix3 Scripted Controller (p. 96)
Scripted Manipulators:
Scripted Manipulators (p. 97)
Scripted Objects:
on detachedFromNode For Object Scripted Plug-ins (p. 106)
Scripted RenderEffects:
RenderEffect Progress Callback Mechanism (p. 28)
Scripted Rollouts:
Multi-line editText UI items in Scripted Rollouts (p. 108)
Spring Controller:
Spring Controller (p. 109)
System Tools:
System Tools (p. 112)
TrackBar:
Trackbar Interface (p. 113)
 What’s New in 3ds max 4 MAXScript 5

Trackviews:
Trackviews (p. 114)
Visual MAXScript:
Visual MAXScript (p. 117)
Xref Objects:
Xref Objects (p. 120)
Zip-file Script Packages:
Zip-file Script Packages (p. 122)
MAXScript Language Improvements in 3ds max 4:
The following are new MAXScript methods for 3ds max 4:
IsValidNode (p. 136)
getTextExtent (p. 175)
isActive <atmos> (p. 1338)
isActive <renderEffect> (p. 1348)
affectRegionVal (p. 1104)
getMAXSaveFileName & getMAXOpenFileName (p. 1640)
Language Improvements:
Affect Region Function (p. 127)
BinStream for Binary Reading and Writing (p. 128)
By Reference Parameter Passing (p. 129)
C++-style bracketing comments (p. 131)
Coercion of bitArray to array and integer arrays to bitArrays (p. 132)
Detecting Deleted Nodes (p. 133)
Dereferencing Operator (p. 133)
forceUpdate Function added to UVWUnwrap (p. 134)
hasProperty() function (p. 135)
Improved the Performance of Iterating and Indexing the ‘selection’ and ‘$’ Object Sets (p. 135)
isValidNode (p. 136)
Readable/Writable Checks (p. 135)
RubberBanding in pickObject() Function (p. 136)
SetDir (p. 136)
Shortcut system replaced (p. 137)
startObjectCreation() (p. 138)
Subanim Indexing Operator, [], on MAX Objects Now Takes Subanim Names (p. 139)
superclasses read-only global variable (p. 139)
Symbolic Pathnames (p. 140)
System Information (p. 141)
validModifier() function (p. 142)
Visible Class For ‘&’ Reference Values (p. 142)
6 Chapter 1 | What’s New in 3ds max 4 MAXScript

Controllers:
List Controller (p. 143)
mapKeys() method (p. 144)
moveKeys function (p. 145)
Keys:
Bezier Keys inTangentLength and outTangentLength (p. 158)
Object Inspector Functions:
Class and Object Inspector Functions Enhanced (p. 159)
Renderer:
render() Function Re-entrant (p. 160)
SuperClasses:
Bitmap Manager - Function Published BMM control (p. 161)
Utilities, Global Utilities and Render Element plug-ins (p. 161)
Renderer (p. 162)
2 New Scripted Pug-in Superclasses (p. 162)
Globals and Locals:
Definition Constructs Can Include Global Variable Declarations At Top Level (p. 162)
Changes to Undeclared Implicit Global Variables (p. 163)
Material Editor, Material and Textures:
Accessing The Material Editor Active Slot (p. 163)
BitmapTex Reload and viewImage (p. 164)
BMP, PNG, JPEG and TGA I/O Interfaces (p. 164)
Material Editor Access (p. 165)
Material Level Show-in-viewport State (p. 166)
Maxops:
maxOps (p. 87)
User Interface:
Angle UI element (p. 168)
CreateDialog (p. 169)
Curve Control (p. 170)
isActive (p. 176)
keyboard.escPressed (p. 176)
MAX Open & Save Dialogs (p. 177)
Menu and CUI Loading (p. 178)
mtlBrowser (p. 180)
SetBackground Method (p. 180)
mouseTrack() Function (p. 180)
snapMode (p. 182)
Spinner UI Item setKeyBrackets (p. 182)
Timer UI element (p. 183)
TimeSlider on/off toggle (p. 183)
 What’s New in 3ds max 4 MAXScript 7

Undo/Redo Dropdown Labels (p. 184)

Zoom to Bounds (p. 184)
Command Panels and Rollout Pages:
Customize The Order of Rollup Pages (p. 185)
MAXScript Dialogs and Rollout Floaters as Extended viewports (p. 186)
Rollout .Controls Property (p. 187)
Rollout Systems ‘category’ Mechanism (p. 188)
All Const and MAXScript Functions in 3ds max 4:
MAXScriptFunction List (p. 190)
Const Class (p. 191)
Const Generic (p. 195)
Const MappedGeneric (p. 207)
Const NodeGeneric (p. 209)
Const Primitives (p. 213)
Const StructDef (p. 231)
New Classes in 3ds max 4:
New Classes in release 4 (p. 259)
New MAXScript Interfaces in 3ds max 4:
Core Interfaces:
Core Interfaces (p. 70)
Other Interfaces:
Other Interfaces (p. 71)
The following topics contain updates to previous MAXScript documentation:
• General Event Callback Mechanism (p. 30): New notifications (everything from #systemPreReset
down is new)
• Defining Macro Scripts (p. 1524): Explanation of how the memory stack treats local macro script
variables (only need to review the one paragraph -- “Normal locals are visible...”).
• Editable Mesh : GeometryClass and TriMesh : Value (p. 1041): New MeshOps, including
sub-object support.
• New properties/methods in:
• Skin (p. 1157)
• Flex (p. 1128)
• UVW Unwrap (p. 1176)
• Added/updated properties to the following objects/modifiers/controllers:
• Attachment (p. 1304)
• Path (p. 1324)
• XYZ Controllers (p. 1335)
• Point Surf (p. 943)
8 Chapter 1 | What’s New in 3ds max 4 MAXScript

• Ringwave (p. 870)

• Terrain (p. 894)
• Point (p. 980)
• Multimaterial (p. 1210) (materialIDList, material1)
• FFD 2x2x2 (p. 1121) (deformType)
• FFD 3x3x3 (p. 1123) (deformType)
• FFD 4x4x4 (p. 1124) (deformType)
• FFD Box (p. 1117) (deformType)
• FFD Cyl (p. 1119) (deformType)
• MeshSmooth (p. 1139)
• Blur (p. 1349)
• Deflector (p. 1024)
• Gravity (p. 1003)
• PDynaFlect (p. 1019)
• POmniFlect (p. 1027)
• SDeflector (p. 1030)
• SDynaFlect (p. 1020)
• SOmniFlect (p. 1031)
• UDeflector (p. 1033)
• UDynaFlect (p. 1022)
• UOmniFlect (p. 1034)
• Wind (p. 1010)
• Arc (p. 949)
• Circle (p. 950)
• Donut (p. 951)
• CV Curve (p. 964)
• Ellipse (p. 953)
• Helix (p. 954)
• Line (p. 955)
• NGon (p. 957)
• Rectangle (p. 958)
• Point Curve (p. 965)
• SplineShape (p. 1079)
• Star (p. 960)
• Text (p. 962)
• CompositeMaterial (p. 1206) (amount, baseMaterial)
• RaytraceMaterial (p. 1212) (enable Raytraced refractions)
 What’s New in 3ds max 4 MAXScript 9

• SpaceFFDBox (p. 998) (deformType)

• SpaceFFDCyl (p. 999) (deformType)
• StandardMaterial (p. 1224) (bounce, staticFriction, slidingFriction, ambient, diffuse, specular,
selfIllumAmount, selfIllumColor, specularLevel, glossiness, soften)

version 4 MAXScript New Features

Action Manager
Topic: version 4 MAXScript New Features/Action Manager
All Action Items are macro recorded when executed. This includes main menus items, CUI buttons,
keyboard shortcuts and quad menu items.
The code emitted for many action items looks like:
actionMan.executeAction 0 “50002” -- Tools: Rotate Mode

The MAXScript Interface: actionMan (p. 353) has a function called “executeAction”. It takes as
parameters the ID of the action table and the “persistent id” of the action. A comment string
that includes the category and tooltip for the action follows it. Some action items have custom code
emitters that emit better looking code.
This interface is currently intended only for running macro recorded actions.

Note:
There is no way currently to query the action manager for all the available action items.
actionMan.loadKeyboardFile “KbdFile.kbd”
This loads the named keyboard file from the current UI directory.
actionMan.saveKeyboardFile “KbdFile.kbd”
Saves the current keyboard configuration into the given file name in the UI directory.
actionMan.getKeyboardFile()
Returns the full path to the current keyboard file.

See Also
Interface: actionMan (p. 353)
The Macro Recorder (p. l)
Defining Macro Scripts (p. 1521)
The MAXScript Listener Window (p. xxxvi)
Turning On the Listener Log (p. xli)
Listener Commands (p. xxxviii)
10 Chapter 1 | What’s New in 3ds max 4 MAXScript

ActiveX Controls in MAXScript Rollouts

Topic: version 4 MAXScript New Features/ActiveX Controls in Rollouts
This feature expands the number of controls that can be created in MAXScript by allowing any type
of ActiveX Controls to be embedded in a rollout.
Examples include:
Simple controls
ActiveMovieControl Object,
Calendar Control,
Microsoft TreeView
…

Compound controls
Microsoft Excel,
Microsoft Internet Explorer
Adobe Acrobat
…
This provides numerous possibilities in MAXScript which include:
• Embed a web browser into a rollout and then navigate the user to a web site.
• Embed an Excel spreadsheet into a rollout, extract the user entered values from cells and then
create animation in Max.
• Create an ActiveMovie player through MAXScript, load an Avi file and then synchronize the
animation between the rendered Avi in ActiveMovie player to animation in Max.
The technology behind this feature is a MAXScript extension plug-in (MxsActiveX.dlx) making it
MAXScript capable. It does not use ParamBlock2.
The plug-in adds a new type of rollout control. The syntax is:
activeXControl <name> [ <control_type> ] [ prop1:<value> ] [ prop2:<value> ] …

Parameters:
<control_type>
A string to create the control. The string must be formatted in one of the following ways:
• A Program ID such as “MSCAL.Calendar.7”
• A Class ID such as “{8E27C92B-1264-101C-8A2F-040224009C02}”
• A URL such as “http://www.microsoft.com”
• A reference to an Active document such as “file://\\Documents\MyDoc.doc”
• A fragment of HTML such as “MSHTML:<HTML><BODY>This is a line of text</BODY></
HTML>”
 What’s New in 3ds max 4 MAXScript 11

Note:
“MSHTML:” must precede the HTML fragment so that it is designated as being a
MSHTML stream.
prop1:<value>
prop2:<value>
…
These are control specific keyword arguments. You can get a list of properties and their
types by calling showProperties on the control.
Examples:
activeXControl ax “{05589FA1-C356-11CE-BF01-00AA0055595A}” height:200 \
width:300 align:#left
Examples:
----------------------------------------------------------------------
-- Creates a Windows media player in a rollout.
-- Load an avi file by clicking the “Pick Avi” button and choosing an Avi file.
-- When the play button is hit the “on timer...” is called
-- This synchronizes the time slider with the active frame in the media player
-- Clicking show properties to get all the properties listed in the listbox
-- You can also set a property by picking a property from the listbox and entering
the new value in the text below
--------------------------------------------------------------------
rollout rActiveX “Creates a Windows media player in a rollout”
(
local val
activeXControl ax “{05589FA1-C356-11CE-BF01-00AA0055595A}” height:200 width:300
align:#left

button btnPick “Pick Avi” pos:[320, 10]

button btnProps “Show Properties” pos:[320, 50]
listBox lbProps “Properties:” pos:[420, 10] width:170
editText etValue “Value:”pos:[385, 170] width:200
labellblStatus““pos:[440, 190]

on btnPick pressed do
(
local f = getOpenFileName caption:”Pick Any Avi File” types:”*.avi”
if f != undefined then
ax.FileName = f
)
on btnProps pressed do
(
showProperties ax
lbProps.items = getPropNames ax
)
on lbProps selected sel do
(
if lbProps.items.count > 0 then
(
try ( val = getProperty ax lbProps.items[sel] )
12 Chapter 1 | What’s New in 3ds max 4 MAXScript

catch ( val == undefined )

etValue.text = val as string
)
)
on etValue entered text do
(
try( setProperty ax lbProps.selected (text as (classof val)) )
catch( etValue.text = “Set Failed” )
)
on ax timer do (
sliderTime = animationRange.start + (ax.CurrentPosition * (animationRange.end -
animationRange.start))/(ax.selectionEnd - ax.selectionStart)
)

on ax PositionChange oldPos newPos do (

format “[%, %]\n” oldPos newPos
)
)
nf = newRolloutFloater “Test ActiveX” 650 300
addRollout rActiveX nf

activeXControl ax “e:\\test.xls” height:200 width:300 align:#left

-------------------------------------------------------------------
-- creates a excel spreadsheet inside an embedded IE browser control
-- also registers it as an extended viewport
-------------------------------------------------------------------
rollout rExcel “Excel”
(
activeXControl ax “e:\\test.xls” height:250 width:370 align:#center
)
fExcel = newRolloutFloater “Excel” 390 270
addRollout rExcel fExcel
 What’s New in 3ds max 4 MAXScript 13

format “----Application----”
showProperties rExcel.ax.application
format “----Parent----”
showProperties rExcel.ax.parent
format “----Container----”
showProperties rExcel.ax.container
-- In case of MS Excel .document points to the msexcel.workbook
workbook = rExcel.ax.document
format “----Document----”
showProperties workbook showHidden:true
showMethods workbook showHidden:false
props = getPropNames workbook
sort props
for prop in props do
(
try
(
format “\t%=%\n” (prop as string) (getProperty workbook prop)
) catch ()
)
14 Chapter 1 | What’s New in 3ds max 4 MAXScript

Properties
There are 2 common properties for ActiveX controls, .pos and .size. Other ActiveX properties are
control specific and vary from one control to another.
Properties can be set like:
ax.filename = true
where ax is the control name.
Additionally, there is support for color properties. The internal representation of colors for ActiveX
controls is COLORREF(unsigned integer) so you’ll always get them in integers but you can set them
as follows:
ax.forecolor = red -- if a .forecolor property exists

Methods
All methods of ActiveX controls are control specific and vary from one control to another. Methods
can be called like:
ax.AboutBox()
ax.loadURL “www.discreet.com”

Events
Events are notifications sent by the ActiveX controls to the rollout, whenever an action is performed
on the control, e.g.: clicking a button, browsing to a webpage. If supporting event handler is
implemented for the event, in the rollout context, the handler is called with supporting arguments.

Supporting Functions
showAllActiveXControls [ to:<stream> ]
Prints a list of ActiveX controls with their progID and classID, registered on your system.
showMethods <axControl> [ to:<stream> ] [showHidden:<false>]
Prints a list of methods and their arguments that can be invoked on the control
showEvents <axControl> [ to:<stream> ]
Prints a list of events and their arguments that are sent by the control
showProperties <axControl> [ to:<stream> ] [showHidden:<false>]
Prints a list of the properties and their types, supported by the control. Some properties are
marked read-only
getPropNames <axControl> [showHidden:<false>]
Returns an array of the properties supported by the control
 What’s New in 3ds max 4 MAXScript 15

Common Parameters
to:<stream>
is the output stringstream.
showHidden:<boolean>
controls whether hidden properties/methods should be included in the enumeration. The
default value is false.
All supported COM datatypes are converted to an appropriate MAXScript wrapper when passed to
and from a COM object. Here are the supported types and their mapping
undefined - VT_EMPTY
boolean - VT_BOOL
integer - VT_UI1
integer - VT_UI2
integer - VT_UI4
integer - VT_UI8
integer - VT_I1
integer - VT_I2
integer - VT_I4
integer - VT_I8
float - VT_R4
float - VT_R8
string - VT_BSTR
float - VT_CY
date - VT_DATE
error - VT_ERROR
color - VT_COLOR
MSDispatch - VT_DISPATCH
font - VT_FONT
undefined - VT_UNKNOWN
ComArray - VT_SAFEARRAY
ComArray - VT_CARRAY
ComArray - VT_ARRAY

Valid string handling for property sets and method call arguments, you can safely do
ax.Navigate “beta.discreet.com”
where: ax is the Microsoft Web Browser Control
16 Chapter 1 | What’s New in 3ds max 4 MAXScript

Note:
Restricted functions like QueryInterface, AddRef, Release are displayed by showMethods() function.
Examples:
---------------------------------------------------------
-- creates a IE browser control in a rollout as registers it an extended
-- viewport. Pick “Web Page” from the Extended Views
-- menu to display the rollout in the webpage. Also click various hypertext links
-- to see the text change in the viewports
---------------------------------------------------------
rollout rWebpage “Web page”
(
local txtObj
local vpsz = getViewSize()
activeXControl ax “www.yahoo.com” height:(vpsz.y-50) width:(vpsz.x-50)
align:#center

fn checkTextObject =
(
if $text01 == undefined then
(
txtObj = text text:”“ name:”text01”
addModifier txtObj (extrude amount:10)
txtObj.wirecolor = red
)
else ( txtObj = $text01 )
)
on rWebpage open do ( checkTextObject() )
on ax TitleChange txt do
(
checkTextObject()
if not (matchPattern txt pattern:”http:”) then
(
if txtObj.text != text then
(
print txt
txtObj.text = txt
max tool zoomextents all
)
)
)
)
fWebPage = newRolloutFloater “Web page” rWebpage.vpsz.x rWebpage.vpsz.y
addRollout rWebPage fWebPage
registerViewWindow fWebPage
showProperties rWebpage.ax
 What’s New in 3ds max 4 MAXScript 17

Accessing Indexed Properties

getIndexedProperty <activeXControl : MSDispatch> <index>
setIndexedProperty <activeXControl : MSDispatch> <index> <value>
These functions are used to access properties on activeX controls that require an
integer index.
Example:
getIndexedProperty axListview.listitems.subitems 1
setIndexedProperty axListview.listitems.subitems 1 “Subitem1”

Disable 3ds max keyboard accelerators

For most of the ActiveX controls there is no automatic way of determining if it supports keyboard
input to disable Max’s accelerators. Therefore a new MAXScript system global called
“enableAccelerators” can be set to false whenever an ActiveX control gets focus so that the user can
type in the controls.
Here is a sample that can be handy to enable/disable keyboard accelarators:
rollout rAccelState “State”
(
checkButton accelState “Test”
on rAccelState open do
18 Chapter 1 | What’s New in 3ds max 4 MAXScript

(
accelState.text = if (enableAccelerators) then “Enabled” else “Disabled”
accelState.checked = enableAccelerators
)
on accelState changed state do
(
enableAccelerators = state
accelState.text = if (enableAccelerators) then “Enabled” else “Disabled”
)
)
nf = newRolloutFloater ““ 100 100
addRollout rAccelState nf

shockwave flash object events

Here is a sample script that creates a text object and sets the text to FSCommand event argument
value sent by shockwave flash objects:
rollout rFlash “Shockwave Flash Object”
(
local txtObj
fn checkTextObject =
(
if $text01 == undefined then
(
txtObj = text text:”“ name:”text01”
addModifier txtObj (extrude amount:10)
txtObj.wirecolor = red
rotate txtObj 90 x_axis
)
else ( txtObj = $text01 )
)
activeXControl axFlash “{D27CDB6E-AE6D-11CF-96B8-444553540000}” height:200
width:300 align:#left
on axFlash OnReadyStateChange arg1 do format “handler: OnReadyStateChange : %\n”
arg1
on axFlash OnProgress arg1 do format “handler: OnProgress : %\n” arg1
on axFlash FSCommand arg1 arg2 do
(
checkTextObject()
txtObj.text = arg1 + “+” + arg2
max tool zoomextents all
 What’s New in 3ds max 4 MAXScript 19

)
on rFlash open do
(
axFlash.movie = “e:\\Movie1.swf”
axFlash.movie = “e:\\Movie1.swf” -- need to load 2nd time sometimes
checkTextObject();
)
)
flashFloater = newRolloutFloater “Shockwave Flash Object” 350 300 10 10
addRollout rFlash flashFloater

COM enums are now represented as MAXScript name internals

Preforming a showProperties on Microsoft controls, like ListView, one of the properties
returned is:
.MousePointer : MousePointerConstants( #ccDefault | #ccArrow | #ccCross | #ccIBeam
| #ccIcon | #ccSize | #ccSizeNESW | #ccSizeNS | #ccSizeNWSE | #ccSizeEW |
#ccUpArrow | #ccHourglass | #ccNoDrop | #ccArrowHourglass | #ccArrowQuestion |
#ccSizeAll | #ccCustom )

which you can set like

ax.MousePointer = #ccArrow
20 Chapter 1 | What’s New in 3ds max 4 MAXScript

Properties which return arrays can be itterated

For example, .listItems in the ListView control, returns IListItems. This can be looped through
and also indexed.
for li in ax.listItems do li.bold = true

or:
ax.listItems[1].text = “foo”

.description property
on any activeX control returns a description string of the format
<TypeLib name> (TypeLib info) ? <Help file name if any> - <help context id>

For example .description on a listview control on my system returned:

“MSComctlLib (Microsoft Windows Common Controls 6.0
(SP4))?C:\WINNT\HELP\cmctl198.chm-210000”

MAXScript sample
rollout controlR92 “Microsoft ListView Control, version 6.0”
(
activeXControl ax “{BDD1F04B-858B-11D1-B16A-00C0F0283628}” height:200 width:300
align:#left
--on ax Click do format “handler: Click\n”
--on ax DblClick do format “handler: DblClick\n”
on controlR92 open do
(
showProperties ax
ax.MousePointer = #ccArrow
ax.GridLines = true
ax.AllowColumnReorder = true
ax.BorderStyle = #ccFixedSingle
ax.view = #lvwReport

chs = ax.columnHeaders
--showProperties chs
--showMethods chs
hTargets = chs.Add()
 What’s New in 3ds max 4 MAXScript 21

hWeights = chs.Add()

hTargets.text = “Node”
hWeights.text = “Weights”

lis = ax.listItems
for i=0 to 10 do
(
local li
li = lis.Add()
li.text = “Item “ + i as string
)
for li in ax.listItems do li.bold = true
li = ax.HitTest 100 1500
if li != undefined do
(
showProperties li
li.text = “Just Hit Tested”
showEvents controlR92.ax
showMethods controlR92.ax
)
)
)
nr92 = newRolloutFloater “Microsoft ListView Control, version 6.0” 350 300 10 10
addRollout ControlR92 nr92

See Also
i-drop - drag and drop (p. 62)
Visual MAXScript (p. 117)
MAXScript Dialogs and Rollout Floaters as Extended viewports (p. 186)
22 Chapter 1 | What’s New in 3ds max 4 MAXScript

Asset Browser
Asset Browser enhancements
Topic: version 4 MAXScript New Features/Asset Browser
The Asset Browser provides access from your desktop to design content on the World Wide Web.
From within the program you can browse the Internet for texture samples and product models. This
includes bitmap textures (BMP, JPG, GIF, TIF, and TGA), or geometry files (MAX, DWG, and so on).
You can drag these samples and models into your scene for immediate visualization and
presentation. You can use the CTRL key to drag geometry into predefined locations. You can also use
the Asset Browser to browse thumbnail displays of bitmap textures and geometry files on your hard
disk or shared network drives. Then you can either view them or drag them into your sceneor into
valid map buttons or slots.
• Several special new icons are now used in Thumbnail view to represent script files (.ms, .mcr,
.mse), dropScripts (.ds), and script zip packages (.mzp).
• Now viewing or double-clicking script source files (.ms, .mcr, .ds) will open them in a MAXScript
editor window, ready for editing and evaluation. You can also double-click .mzp script zip
package files to open them in WinZip or some other zip utility if the type .mzp has been
associated with that utility.
• Executable script files (.ms, .mcr, .mse, .mzp) now have a Run... menu item available in the
right-click menu on their thumbnail icons in the thumbnail view, allowing you to launch them
directly from within the asset browser.
• The home page for web views is now <max-directory>\web\maxindex.html.

Properties:
assetBrowser.open ()
Return Value:
Opens the asset browser if it is not already open.
Properties:
assetBrowser.gotoURL <URL_string>
Parameters:
<URL_string>
Opens the given URL in the asset browser.
Remarks:
This can be a web URL or a local or network disc directory path name.

See Also
Interface: browserMgr (p. 355)
i-drop - drag and drop (p. 62)
Zip-file Script Packages (p. 122)
 Access to the node bone properties and methods 23

Bones

Access to the node bone properties and methods

Topic: version 4 MAXScript New Features/Bones
There are several properties and methods accessible on scene nodes that correspond to the Bone
parameters and functions in the node properties dialog.

The new properties are:

<node>.boneEnable
boolean, read-only, see <node>.setBoneEnable for the set method.
<node>.boneAutoAlign
boolean
When turned off, the bone’s pivot point will not align to its child object. The translation of a
child bone will not be converted into rotation of the parent. Instead the child will be allowed
to move away from the parent’s X-axis.

Note:
Changing the state of this check box will not have an immediate visual effect on the skeleton. It
only affects future behavior when bones are moved. This option is only available if Bone is off.
<node>.boneFreezeLength
boolean
When turned on, the bone maintains its length. When turned off, the bone’s length is based on
the translation of its child bone. This option is available only if Auto-Align is on.
<node>.boneScaleType
one of #scale, #squash, or #none
None: No stretch takes place.
Scale: Lets the bone scale. The stretch happens along one axis.
Squash: Lets the bone squash. The bone gets fatter as it gets shorter, and thinner as it gets
longer.
<node>.stretchTM
matrix3, read-only
The new methods are:

Prototype:
<node>.setBoneEnable <onOff_boolean> <initial-time_time>

Remarks:
Sets the Bone enable on or off.
24 Chapter 1 | What’s New in 3ds max 4 MAXScript

Parameters:
<onOff boolean>
When turned on, the bone or object behaves as a bone. Turning this option off causes
the node to stop behaving like a bone. There is no auto alignment or stretching. Note
that turning this option on will not cause the object to immediately align or stretch.
However future translations of children may cause rotation and stretching.
Default=on for bone objects, off for other kinds of objects.
<initial-time time>
Specifies the time at which to calculate and store initial child position. This is usually
user with the current time slider position. The time associated with the time slider can
be queried and set using the sliderTime global variable. Time Control (p. 1580)

Note:
A very good macroscript example to review, which uses .setBoneEnable, can be found at
..\ui\macroscripts\Macro_Bones.mcr.

Prototype:
<node>.realignBoneToChild ()

Remarks:
When turned on, the bone or object behaves as a bone. Turning this option off causes the node to
stop behaving like a bone. There is no auto alignment or stretching. Note that turning this option
on will not cause the object to immediately align or stretch. However future translations of children
may cause rotation and stretching. Default=on for bone objects, off for other kinds of objects.

Prototype:
<node>.resetBoneStretch ()

Remarks:
Resets the initial child position used to compute the stretch factor to the current child position. This
will cause the stretch factor to become equal to one. If it was previously not equal to one then the
object would snap to its original unstretched state.

See Also
Node Common Properties, Operators, and Methods (p. 820)
Bone Creation (p. 25)
Bone : Helper (p. 978)
Skin : Modifier (p. 1157)
Bones : System (p. 991)
Interface: BoneSys (p. 354)
 Bone Creation 25

Bone Creation
Topic: version 4 MAXScript New Features/Bones
Interface: BoneSys (p. 354)
There is a function published interface to create bone links.

Prototype:
BoneSys.createBone <startPosition> <endPosition> <zAxis>

Parameters:
<startPosition>
The location of the new bone as point3
<endPosition>
The direction (X axis) of the bone and the bone length as point3
<zAxis>
The direction of the Z axis for the new bone node as point3

Return Value:
It returns the new bone node that was created.

Note:
If the Z axis is not perpendicular to the X axis, the Z axis will be made perpendicular. To create a
bone chain, call createBone repeatedly with the startPosition set to the value of the previous
endPosition. Note that newly created bones are not linked to any parent. So to create a bone chain,
the script would also need to link each newly created bone segment to the previous.

See Also
Bones : System (p. 991)
Core Interfaces (p. 70)
Node Common Properties, Operators, and Methods (p. 820)
Bone Creation (p. 25)
Bone : Helper (p. 978)
Skin : Modifier (p. 1157)
Access to the new node bone properties and methods (p. 23) Bones_System
26 Chapter 1 | What’s New in 3ds max 4 MAXScript

Cache Modifiers
Point Cache Modifier
Topic: version 4 MAXScript New Features/Cache Modifiers/Point Cache Modifier
Point Cache - superclass: modifier (p. 314)
This is a simple point caching system. It lets you store modifier animation to a disk file that records
only changes in vertex positions, and then play back the animation using the information in the
disk file instead of the modifier keyframes. It caches the points of an object across time and then
reads them from the disk on play back. It is useful when you have large intricate stacks that you want
to speed up or modifiers such as flex that you want to bake.
This modifier sacrifices memory for speed, it stores three caches of the points to allow for fast reading
from the disk. You can instance this modifier but the instances must have the same number of
points, otherwise the results will be inconsistent. This also only record point position it does not
store mapping, topology changes etc. It also cannot deal with animated topology changes.
Four MAXScript interface methods have been exposed to allow pressing the Record, Set Cache,
EnableMods, and DisableMods buttons.

Methods
Prototype:
<void>record()

Remarks:
Stores the vertex animation to a disk file. Call Record to activate the Save Points dialog, which lets
you specify a path and file name for the cache file. Click OK to record the file, and then load it into
the Point Cache modifier, ready for playback.

Prototype:
<void>setCache()

Remarks:
Loads a vertex animation from a cache file on disk into the Point Cache modifier. If number of
vertices in the cache file does not match the number of vertices in the object, a warning appears, but
no error occurs.

Prototype:
<void>enableMods()

Remarks:
Turns on all stack modifiers below the Point Cache modifier. Use this when you want to change
modifier settings.
 Notify Callbacks for Animate button on and off Transitions 27

Prototype:
<void>disableMods()

Remarks:
Turns off all the object’s stack modifiers below Point Cache so that only the cached vertex animation
appears when you play back the animation.

WSM component of Point Cache.

PointCacheWSM interfaces: (p. 487)

Note:
The WSM is identical to the local space version except it records points in World Space and exist
higher in the stack.

See Also
PointCache interfaces: (p. 486)
PointCache - superclass: modifier (p. 316)

CallBack Notification Codes

Notify Callbacks for Animate button on and off Transitions

Topic: version 4 MAXScript New Features/CallBack Notification Codes
Notify callbacks for Animate button on and off transitions. The new codes for callback scripts are
#animateOn and #animateOff.

See Also
General Event Callback Mechanism (p. 29)
28 Chapter 1 | What’s New in 3ds max 4 MAXScript

RenderEffects Progress Callback Mechanism

You can control the main RenderEffects dialog progress bar using an on apply handler with
progressCB, the progress callback interface object. The following syntax lets you do this:
on apply <bitmap> progressCB: do <fn>

The first argument is the bitmap value to be modified by the effect, and progressCB is a progress
callback interface object. This interface has several methods you can call during the course of
processing the bitmap that control the progress bar and check for user cancellation.

Methods
progressCB.setTitle <string>
Sets the title on the progress bar.
progressCB.progress <done> <total>
Indicates the progress of the rendering. Both arguments are integers; done indicates how
much of the rendering has been completed, and total indicates how much there is
to do.
When this is called, the main render effects progress bar is updated to reflect this progress.
This function also returns a boolean, which if true indicates that the user has hit the
escape key to cancel the effect rendering.
progressCB.check()
Indicates whether the user has hit the escape key to cancel the effect rendering. This
function returns a boolean; false if processing should continue, and true if the user has
cancelled the rendering.
Example:
on apply bm progressCB: do
(
…
progressCB.setTitle “My Effect Pass1”
…
escapeEnable = false -- turn on scripter escape processing
for i in …
(
<the effect rendering loop>
…
if progressCB.progress completed total then exit
)
…
escapeEnable = true
…
)

The progress bar update is done inside the main processing loop and the check for user cancel is
done on the same call, causing the loop to exit prematurely in this example.
 General Event Callback Mechanism 29

See Also
RenderEffect : MAXWrapper (p. 1347)
Scripted RenderEffect Plug-ins (p. 1566)
Render Effects Common Properties, Operators, and Methods (p. 1347)

General Event Callback Mechanism

MAXScript allows you to register callback scripts for all of the notification events supported by
3ds max, such as pre/post scene file open, new, reset, scene file save, pre/post render, selection
change, etc. You can specify any number of callback scripts per notification event. Callback scripts
can be bundled into ID’d sets, and can be deleted individually or all callback scripts in and ID’d set
can be deleted. Callback scripts can be specified as persistent so that they are saved and loaded with
the currently open file.
The callbacks are maintained by the following set of functions:
callbacks.addScript <callback_type_name> \
( <script_string> | <script_stringstream> | \
fileName:<filename_string> ) \
[ id:<name> ] [ persistent:<boolean> ]
This method is used to register a new callback script. Requires as the first argument a name
that specifies which type of notify event this script is associated with. The list of valid
callback_type_name values is listed below.
The script is supplied either as a direct String or StringStream value containing the text of
the script to run, or as a fileName: keyword argument, in which case the named file is
loaded and run whenever the event notification callback occurs. You can specify either a
direct string or a fileName:, but not both.
The optional id: parameter lets you tag one or a group of callbacks with a unique name so
that you can remove them all as a group without interfering with other callbacks, perhaps
registered by other scripted tools.
The optional persistent: parameter lets you control whether the script is saved
permanently in the currently open scene file or is a global callback script that remains in
place no matter what file opening and closing is performed. A true value for the
parameter specifies that the script should be stored in the current file and loaded and
registered for callback whenever that file is opened again. Persistent callback scripts are
always removed when a new file is loaded or a reset is performed so that persistent scripts
in one file don’t accidentally get copied to a later file. The default for this parameter is
false, indicating the script is a global script and is not persistent.
30 Chapter 1 | What’s New in 3ds max 4 MAXScript

For example:
callbacks.addScript #preRender “setUpRenderGeom()” \
id:#jbwRender
registers a new callback script that will be called just before a render is performed. The
script invokes a function (that has presumably already been set up). An unique ID has
been assigned to the script for later selective removal.
callbacks.removeScripts [ <callback_type_name> ] [ id:<name> ]
This method is used to unregister and remove one or more callback scripts. Specifying
just a callback event type name removes all the callback scripts for that event.
Specifying just an id:<name> removes all callback scripts in all events with that ID.
Specifying both limits the ID-based removal to the specified event type.
callbacks.show ()
This method lists out the current callback scripts in the Listener window.
callbacks.broadcastCallback <callback_type_name>
This method provides a way for you to simulate one of the events and have all the
callback scripts for it executed. Within 3ds max, the #preRenderFrame and
#preRenderFrame callbacks can only be called by the renderer. These callbacks can
not be called by using this method.
The following is a list of valid callback event type names:
#unitsChange
Sent if the user changes the unit setting.
#timeunitsChange
Sent if the user changes the time format setting.
#viewportChange
Sent if the user changes the viewport layout.
#spacemodeChange
Sent if the user changes the reference coordinate system.
#modPanelSelChanged
Sent whenever the Modify panel opens on a new selection, either because the Modify
panel was just selected or because a new selection is made in the scene. The notify occurs
at a point just prior to panel redraw but after the selection has been established, so that
callback functions can modify the panel state without it being overwritten.

System Notifications
#systemPreReset
Sent before 3ds max is reset.
#systemPostReset
Sent after 3ds max is reset.
#postSystemStartup
Sent when the software goes live.
#pluginLoa\ded
Sent whenever a plug-in is loaded.
 General Event Callback Mechanism 31

#systemPreNew
Sent just before 3ds max is reset.
#systemPostNew
Sent just after 3ds max is reset.
#preSystemShutdown
Sent just before the software enters the shutdown process.
#postSystemShutdown
Sent just before the software finishes the shutdown process.
#colorChanged
Sent when the system is updating it’s custom colors.

File Notifications
#filePreOpen
Sent before a new file is opened.
#filePostOpen
Sent after a new file is opened successfully.
#filePreMerge
Sent before a file is merged.
#filePostMerge
Sent after a file is merged successfully.
#filePreSave
Sent before a file is saved.
#filePostSave
Sent after a file is saved.

Renderer Notifications
#preRender
Sent before rendering is started. This notification is sent out before the renderer creates the
render instance objects, which means that you can create nodes and other objects as a
response to this event. When rendering multiple frames, this event is sent only once at the
beginning of the rendering phase, and not on a per-frame basis. In the #preRender
callback, you can’t change any of the render parameters (height, width, aliasing, etc) and
effect the current render sessions. Those parameters have already been set up internally in
3ds max, and so changes to them won’t occur until the next render session occurs.
#postRender
Sent after rendering has finished. This notification is sent out after the renderer destroys
the render instance objects, which means that you can create nodes and other objects as a
response to this event. When rendering multiple frames, this event is sent only once at the
end of the rendering phase, and not on a per-frame basis.
#preRenderEval
Sent just before the renderer starts evaluating objects.
32 Chapter 1 | What’s New in 3ds max 4 MAXScript

#preRenderFrame
Sent just before each frame is rendered by the renderer. This notification is sent out after
the renderer has taken a snapshot of the scene geometry. At the time of this call the scene
cannot be modified. The renderer has already called GetRenderMesh() on all the object
instances, and the materials and lights are already updated. If you don’t modify anything
that is rendered, then it is okay to use this callback. The current frame being rendered is set
into the MAXScript currentTime context and system global, so any references to other
scene object properties will automatically be resolved at the currently rendering frame’s
time. This notification is not sent out when the renderer is called to update the Material
Editor sample spheres, only during output rendering.
#postRenderFrame
Sent just after each frame is rendered by the renderer. The current frame being rendered is
set into the MAXScript currentTime context and system global, so any references to other
scene object properties will automatically be resolved at the currently rendering frame’s
time. This notification is not sent out when the renderer is called to update the Material
Editor sample spheres, only during output rendering.
#renderParamsChanged
Sent whenever the common renderer parameters have changed.

Import/Export Notifications
#preImport
Sent before a file is imported.
#postImport
Sent after a file is imported successfully.
#importFailed
Sent if import fails.
#preExport
Sent before a file is exported.
#postExport
Sent after a file is exported successfully.
#exportFailed
Sent if export fails.

Node Related Notifications

#nodeCreated
Sent when a node is created.
#nodeRenamed
Sent if a scene node is renamed.
#nodeHide
Sent when a node is hidden.
#nodeUnhide
Sent when a node is unhidden.
 General Event Callback Mechanism 33

#nodeFreeze
Sent when a node is frozen.
#nodeUnfreeze
Sent when a node is unfrozen.
#nodeLinked
Sent when a new parent-child link is made.
#nodeUnlinked
Sent when a parent-child link is broken.
#nodePreMaterial
Sent just before a node gets a new material
#nodePostMaterial
Sent just after a node gets a new material
#sceneNodeAdded
Sent just after a node is added to the scene.
#selNodesPreDelete
Sent just before selected nodes are deleted.
#selNodesPostDelete
Sent just after selected nodes are deleted.
#nodeMaterialChanged
Sent after the material is changed for the selected nodes.
#nodeWSCacheUpdated
Sent whenever the modifier stack display is reevaluated.

Material Library Notifications

#matLibPreOpen
Sent just before loading a material library.
#matLibPostOpen
Sent just after loading a material library.
#matLibPreSave
Sent just before saving a material library.
#matLibPostSave
Sent just after saving a material library.
#matLibPreMerge
Sent just before merging a material library.
#matLibPostMerge
Sent just after merging a material library.
34 Chapter 1 | What’s New in 3ds max 4 MAXScript

Asset Browser Notifications

#abPreNavigate
Sent whenever a URL is loaded into the Asset Browser.

VIZ-Only Notifications
#heightMenuChanged
Sent when a user operated the height menu.
#fileLinkPreBind
Sent just before a file link bind.
#fileLinkPostBind
Sent just after a file link bind.
#fileLinkPreDetach
Sent just before a file link detach.
#fileLinkPostDetach
Sent just after a file link detach.
#fileLinkPreReload
Sent just before a file link reload.
#fileLinkPostReload
Sent just after a file link reload.
#fileLinkPreAttach
Sent just before a file link attach.
#fileLinkPostAttach
Sent just after a file link attach.

Other Notifications
#wmEnable
Sent when main window gets an wm_enable (BOOL enabled).
#selectionSetChanged
Sent after the selection set has changed.
#bitmapChanged
Sent after a bitmap is reloaded.
 General Event Callback Mechanism 35

Color Manager
Topic: version 4 MAXScript New Features/Color Manager
There is a Function Published interface in MAXScript called “colorMan (p. 356)” that exports the
color manager interface.
All colors are represented as Point3 values of the form [red, green,blue], where each value runs from
0.0 to 1.0.
colorMan.useStandardWindowsColors()
Returns true if the standard windows colors are used and false if custom colors are used.
colorMan.setUseStandardWindowsColors onOff
Sets the value of “useStandardWindowsColors”. Passing in “true” tells the system to use
the standard windows colors, and false tells the system to use the custom colors.
colorMan.registerColor color name category defaultColor
This registers a new color with the system. This adds a color to the color manager database
that is then accessible from the color customization UI.
Example:
colorMan.registerColor #myNewColor “My Own Color” “Ugly Colors” [1,0,0]
This registers a new color, with the name #myNewColor, with a default value of red.
The category in the customization UI will be “Ugly Colors” and the name will be “My
Own Color”.
In other scripts you can access this color using:
colorMan.getColor #myNewColor

Note:
colorMan.registerColor should be called from a script in the “.\stdplugs\stdscripts” folder. These
scripts are run when MAX starts, so the color will be available in the customization UI immediately.
If the user customizes this color, its value will be saved in the MaxColors.clr file.
colorMan.loadColorFile()
This method will load the specified color file from the current UI directory.
colorMan.saveColorFile()
This brings up the file save dialog and lets the user save a new color file.
colorMan.setColor color colorValue
This sets the value of the given color to the given value. Besides the colors that you register
using registerColor, there is a set of built-in colors that you can set and get:
#background -- The background for all controls and buttons
#text -- The text for all controls and buttons
#activeCommand -- The color command mode buttons turn when pressed
#hilight -- The hilight color for 3d controls
#shadow -- The shadow color for 3d controls
#window -- The background color for edit boxes, list boxes and other
windows
#activeCaption --
#appWorkspace --
36 Chapter 1 | What’s New in 3ds max 4 MAXScript

These two are currently unused, but would be used if a 3rd party developer uses the
Windows colors in C++ code:
GetCustSysColor(COLOR_APPWORKSPACE)
or:
GetCustSysColor(COLOR_ACTIVECAPTION)
These were put in for completeness with the windows API.
#toolTipBackground -- The background for viewport tool tips
#toolTipText -- The text color for viewport tool tips
#hilightText -- The hilight color in the stack view drop-down list
#windowText -- The color used in edit boxes, list boxes and other windows
#itemHilight -- Used as the highlight color on the stack-view drop down list
of modifiers.
#subObjectColor -- The color used to hilight sub-object levels in StackView
#3dDarkShadow -- the dark shadow color on 3d controls
#3dLight -- the light color on 3d controls
#trackbarBg -- trackbar background
#trackbarBgSel -- trackbar background for selected keys
#trackbarText -- trackbar text
#trackbarTicks -- trackbar ticks
#trackbarKeys -- trackbar keys
#trackbarSelKeys -- track bar selected keys
#trackbarCursor -- track bar cursor
#pressedButton -- background color for pressed buttons, like the transform
constraints
#timeSliderBg -- The background for the time slider bar.
#viewportBorder -- The viewport border color
#activeViewportBorder -- The active viewport border color
#rollupTitleFace -- Rollout title background
#rollupTitleText -- rollout title text
#rollupTitleHilight-- rollout title 3d highlight
#rollupTitleShadow -- rollout title 3d shadow
#selectionRubberBand -- the selection marquee color
#stackViewSelection -- the color of a selected item in stack view

colorMan.getColor color
Gets the value of the given color.
colorMan.getName color
Gets the name of the given color.
colorMan.getCategory color
Gets the category of the given color.
colorMan.getIconColorScale type which
Gets the value of the icon image processing value.
type enums: {#disabledIcon|#enabledIcon}
which enums: {#saturationScale|#valueScale|#alphaScale}
Returns a floating point value (in the range 0.0f to 1.0f) that is one of the scale factors
applied to the specified icon type. These scale values used to do image processing on the
icons at start-up time.
 General Event Callback Mechanism 37

colorMan.setIconColorScale type which value

Sets the value of the icon image processing value. The value runs from 0.0 to 100.0.
colorMan.getIconColorInvert type
Gets the value for inverting icon colors for the given type.
colorMan.setIconColorInvert type value
Sets the value for inverting icon colors for the given type.
“Value” can be true or false.
colorMan.getFileName()
Returns the file name of the currently loaded color file.
colorMan.getDefaultColor color
Returns the default color value for the given color. This is the color passed in as
“defaultColor” in registerColor.
colorMan.repaintUI type
Whenever you change a color with the color manager, you need to repaint the UI to see the effect.
The value of “type” can be:
#repaintAll -- repaint all of MAX’s UI. Can be slow.
#repaintTrackBar -- just repaint the track bar
#repaintTimeBar -- just repaint the time slider

Here is a macroScript that turns the time slider and trackbar backgrounds blue:
Example:
macroScript BlueBar
category: “Color”
tooltip: “Blue Bar”
(
on execute do
(
colorMan.setColor #timeSliderBg [0, 0, .6]
colorMan.repaintUI #repaintTimeBar
colorMan.setColor #trackbarBg [0, 0, .6]
colorMan.repaintUI #repaintTrackBar
)
)

MAXScript calls that let you load, save and query color files.
colorMan.loadColorFile “MyColors.clr”
Loads the given color file from the current UI directory.
Returns true if it succeeds, and false otherwise.
colorMan.saveColorFIle “MyColors.clr”
Saves the current color scheme into the named file in the current UI directory.
Returns true if it succeeds, and false otherwise.
colorMan.getColorFile()
Returns the full path to the current color file.
38 Chapter 1 | What’s New in 3ds max 4 MAXScript

Example:
To set the selected object color to red, you would use:
SetUIColor 0 red
colorMan.repaintUI #repaintall

See Also
Interface: colorMan (p. 356)
3ds max User Interface Colors (p. 1604)

Combustion
Topic: version 4 MAXScript New Features/Combustion
With the Combustion map, you can create maps interactively using the Discreet combustion
product and 3ds max at the same time. You use combustion software to paint on a bitmap, and the
material updates automatically in the 3ds max Material Editor and in shaded viewports.
Important: The combustion map works only if Discreet combustion is installed on your system.
You can use combustion as a material map in 3ds max. With a Combustion map, you can create a
material from a Paint or composite operator, and in turn apply that material to objects in a 3ds max
scene. The Combustion map can include combustion effects, and it can be animated.
In addition, with combustion you can import 3ds max scenes that have been rendered to a rich pixel
file (RPF or RLA file). The imported rich pixel rendering becomes an element of your composite. You
can adjust its 3D position relative to video elements of the composite, and you can apply
combustion 3D Post effects to objects within it. See the combustion User’s Guide for more information.
Note: Because 3ds max runs only on Windows, you cannot use combustion to create material maps
on a Macintosh.
Note: The environmental atmospheric effect known as “Combustion” in versions prior to 3ds max 4
is now known as the Fire effect.
A Combustion map is a 2D map (p. 274). It is a combustion project used by the 3ds max Material
Editor, so like any combustion project, it is vector-based, animatable, and fully editable. From within
the Material Editor, you can have combustion create a new project from scratch, or use an existing
composite or Paint branch. You can synchronize the combustion Timeline with the 3ds max time
slider so animated materials synchronize with your 3D scene.
A macroScript has been added that gets called by the render management system to output render
element info to the combustion(tm) .cws file format.
../UI/MacroScripts/Macro_CombustionOutput.mcr
Associated files include:
RenderElements-fns.ms
CombustionExport-fns.ms
CombustionExport.ini
 Path Constraint 39

Example:
C = combustion()

See Also
Combustion.coordinates - superclass: MAXObject (p. 274)
Render Element Manager (p. 92)
Material Common Properties, Operators, and Methods (p. 1203)

Constraints

Path Constraint
Topic: version 4 MAXScript New Features/Constraints
Path Constraint - superclass: PositionController (p. 307)
Path Constraint interfaces: (p. 468)
A path constraint restricts an objects movement along a spline or at an averaged distance between
multiple splines.

Path Target Object

A path target can be any type of Spline. The spline curve (target) defines a path of motion for the
constrained object. Targets can be animated using any of the standard translation, rotation, scale
tools. Setting keys on the path’s sub object level, such as vertex, or segment will animate the path
while effecting the constrained object.

See Also
path interfaces: (p. 462)
LookAt Constraint (p. 40)
Orientation Constraint Controller (p. 40)
Link Controller for Constraints (p. 42)
Controller Functions for use with Constraint Assignments (p. 42)
40 Chapter 1 | What’s New in 3ds max 4 MAXScript

LookAt Constraint
Topic: version 4 MAXScript New Features/Constraints
LookAt Constraint - superclass: RotationController (p. 297)
LookAt Constraint interfaces: (p. 455)
Look-At Constraint constrains an object’s orientation so that it’s always looking at another object.

Note:
The old Look At Controller, which is a full transform controller, will be invisible to the user unless
an old file is loaded. The new LookAt Constraint Controller is a rotation controller and NOT a TM
controller which the old LookAt was. The old LookAt will be phased out.
At this time, old LookAt.IsPublic returns zero, so that the users won’t see the old LookAt. However,
the old MAX files will still load the old LookAt and the camera and the light will continue to use the
old LookAt.

See Also
Path Constraint (p. 39)
Position Constraint (p. 41)
Orientation Constraint Controller (p. 40)
Link Controller for Constraints (p. 42)
Controller Functions for use with Constraint Assignments (p. 42)

Orientation Constraint Controller

Topic: version 4 MAXScript New Features/Constraints
Orientation Constraint - superclass: RotationController (p. 306)
Orientation Constraint interfaces: (p. 462)
An Orientation Constraint causes an object’s orientation to follow the orientation of an object or
averaged orientation of several objects.
An Orientation Constrained object can be any type of object that inherits its rotation from a target
object. Once constrained you can not rotate the object manually. You may move or scale the object
as long as its not constrained in a manner that affects the object’s position or scale controller.
The target object can be any type of object. The rotation of a target object drives the constrained
object. Targets can be animated using any of the standard translation, rotation, scale tools.
 Position Constraint 41

See Also
Path Constraint (p. 39)
Position Constraint (p. 41)
LookAt Constraint (p. 40)
Link Controller for Constraints (p. 42)
Controller Functions for use with Constraint Assignments (p. 42)

Position Constraint
Topic: version 4 MAXScript New Features/Constraints
Position Constraint - superclass: PositionController (p. 320)
Position Constraint interfaces: (p. 488)
A position constraint causes an object to follow the position of an object or the averaged position
of several objects.
In order to activate, a position constraint requires an object and a target object. Once assigned the
object becomes constrained to the target objects position. Animating the target’s position causes the
constrained object to follow
Each target has a weight value defining its influence. A value of 0 is equal to off. Any value greater
than 0 will cause the target to influence the constrained object. Weight values may be animated to
create effects such a ball being picked up from a table.
Multiple targets can be used to influence a constrained object. When using multiple targets, each
target’s weight value defines how much it influences the constrained object. For example if a sphere
is Position constrained between 2 targets and each target’s weight value is 100. Then the sphere will
maintain an equal distance between both targets even when they are in motion. If one of the weight
values is 0 and the other is 50, then the Sphere is only influenced by the target with the higher value.
Example:
posCtrl = Position_Constraint()
posConstraintInterface = posCtrl.constraints

appendNode <node>
Adds a node to the node list with a default weight of 50
appendWeightedNode <node> <weight>
Adds a node to the node list with the specified weight
getNode <index>
Returns the node specified by the index. Index is a 1 based array
setNode <node> <index>
Replaces the node with the given index with a new node
getWeight <index> <time>
Returns the weight at the time for the node specified by the index.
setWeight <weight> <index> <time>
Sets the weight for the node specified by the index at the given time.
42 Chapter 1 | What’s New in 3ds max 4 MAXScript

Use:
posConstraintInterface.appendNode $box01
posConstraintInterface.appendWeightedNode $box02 200
node1 = posConstraintInterface.getNode 1
posConstraintInterface.setNode $box03 2
weight = posConstraintInterface.getWeight 1 50
posConstraintInterface.setWeight 250 1 0

See Also
Path Constraint (p. 39)
LookAt Constraint (p. 40)
Orientation Constraint Controller (p. 40)
Link Controller for Constraints (p. 42) Controller Functions for use with Constraint Assignments (p. 42)

Link Controller for Constraints

Topic: version 4 MAXScript New Features/Constraints
A Link constraint is used to animate an object linking from one target object to another.
The Link constraint causes an object to inherit the position, rotation and scale of its target object.

See Also
Path Constraint (p. 39)
LookAt Constraint (p. 40)
Position Constraint (p. 41)
Orientation Constraint Controller (p. 40)
Link Controller for Constraints (p. 42)
Controller Functions for use with Constraint Assignments (p. 42)

Controller Functions for use with Constraint Assignments

Topic: version 4 MAXScript New Features/Constraints
These functions are defined in in stdplugs\stdscripts\ControllerFunctions.ms
and in ui\macroscripts\Macro_Constraints.mcr.

Prototype:
AddListController OBJ Trans ListType

Remarks:
Checks to see if a list controller is assigned. If not, it will assign to the designated Trans using the
ListType, This way it can be used for all list controllers.
 Controller Functions for use with Constraint Assignments 43

Example:
Foo = Selection as array
AddListController “Foo[1]” “Pos” “Position_List”

Prototype:
AddConstraint OBJ Trans Constraint List

Prototype:
SetActiveController OBJ Trans Controller

Prototype:
AddConstraintTargets OBJ Trans Array Target

See Also
Path Constraint (p. 39)
LookAt Constraint (p. 40)
Position Constraint (p. 41)
Orientation Constraint Controller (p. 40)

Context Filters
Topic: version 4 MAXScript New Features/Context Filters
Filter functions for context sensitive menus:
Use this for .IsEnabled or .IsVisible handlers in macrocripts. isEnabled and isChecked handlers have
been added to many of the existingmacroScripts. All of the modifier, creation and polygon toolbox
macroScripts have these two handlers.
These handlers allow object creation CUI buttons to turn green while creating objects, and modifier
buttons are only enabled if they apply to the current selection. The polygon toolbox buttons also
only enable when applicable, and the selection level buttons stay pressed while in the sub-object
level.
This structure is defined in .\stdplugs\stdscripts\FilterFunctions.ms.
An example use of the filter functions can be found in the Selection and Display Callbacks Script
File, .\stdplugs\stdscripts\Selection_Display_Filters.ms
#Struct:Filters(
Is_EditMesh:<fn>,
Is_NURBS:<fn>,
Is_EditPoly:<fn>,
Is_EditPatch:<fn>,
Is_EditSpline:<fn>,
Is_MeshSelect:<fn>,
Is_PolySelect:<fn>,
Is_SplineSelect:<fn>,
Is_PatchSelect:<fn>,
Is_PosXYZ:<fn>,
Is_RotationXYZ:<fn>,
44 Chapter 1 | What’s New in 3ds max 4 MAXScript

Is_ScaleXYZ:<fn>,
is_Child:<fn>,
This is used for the new IK assignments.
is_Parent:<fn>,
This is used for the new IK assignments.
CanSwitchTo_XXXX for SubObject levels
CanSwitchTo_Vertex:<fn>,
CanSwitchTo_Edge:<fn>,
CanSwitchTo_Face:<fn>,
CanSwitchTo_Polygon:<fn>,
CanSwitchTo_Element:<fn>,
CanSwitchTo_Border:<fn>,
CanSwitchTo_Patch:<fn>,
CanSwitchTo_Segment:<fn>,
CanSwitchTo_Spline:<fn>,

These can be used to check if MeshSelect, PatchSelect, SplineSelect, Edit(able) Patch,

Edit(able)Mesh, and Edit(able)Spline can go into these subobject levels.
Are_Modifiers_Applied:<fn>,
The following requires a node to be passed into the function.
Is_Bone:<fn>,
Is_IKChain:<fn>,
Is_Point:<fn>,
Is_Light:<fn>,
Is_Camera:<fn>)

Return Value:
They return true if the selected object’s function name condition is met.

See Also
Macro Scripts (p. 1624)
Defining Macro Scripts (p. 1521)
macros const StructDef (p. 239)
 Scripted Custom Attributes 45

Custom Attributes

Scripted Custom Attributes

Topic: version 4 MAXScript New Features/Custom Attributes
Custom Attributes let you create and assign additional parameters to any object, modifier, or
material in your scene. This is useful for game and other project-specific data.
MAXScript provides a way to define and add these custom attributes to objects in the scene and also
a way to define UI rollups for accessing these attributes.
Attributes can be added to an object via an “attribute definition”. This is a new syntactic
construct in MAXScript that is similar to a scripted plug-in definition, but rather than adding a new
plug-in class, a definition is built that can be used to add custom attributes and rollup UI to any
number of objects at any time, through a special new function.

Note:
You cannot use Custom Attributes for per-face-data. The face-data channels store objects of a user
defined type and the scripter cannot create objects of types other than those known by MAXScript.
The new syntax has the following form:
attributes <varname>
[version:n]
[silentErrors:t/f]
[initialRollupState:0xnnnnn]
(
<locals>
<globals>
<parameters>
<rollouts>
<handlers>
)

Remarks:
The name is now simply a descriptive name for the definition and can be either a <name> or a
<string>.
Example:
attributes “Game Data”
(
...
)
or
attributes gameData
(
...
)
46 Chapter 1 | What’s New in 3ds max 4 MAXScript

The attribute header keyword parameters and main clauses are basically identical to the same
keyword parameters and clauses in Scripted Plug-ins (p. 1538). The ‘custom attributes’ are effectively
the parameters defined in any parameter clauses in the body of the attributes definition. The UI for
them is defined by the rollout clauses, which will be automatically displayed in the Command Panel
and Material Editor when an object containing custom attributes is selected.
Example:
attributes weaponData
(
parameters main rollout:params
(
hitPoints type:#float ui:hits default:10
cost type:#float ui:cost default:100
sound type:#string
)

rollout params “Weapon Parameters”

(
spinner hits “Hit Points” type:#float
spinner cost “Cost” type:#float
dropdownlist sound_dd “Sound” items:#(”boom”, “sparkle”, “zap”,
“fizzle”)
on sound_dd selected i do sound = sound_dd.items[i]
)
)

Remarks:
This defines three new attributes, say for weapon objects in a game level editor set up. The attributes,
hitPoints, cost and sound, are defined as parameters and the UI for them in a rollout.

Note:
The auto-UI connection between the parameters and rollout items via the ui and keyword is the
same as the support in Scripted Plug-ins (p. 1538). You can treat attribute scripting as basically
identical to scripting plug-ins, in terms of parameter, rollout setup and handler programming.

Adding attributes to an object

Prototype:
custAttributes.add <object_or_collection> <attributes_definition>[#unique]

Remarks:
Adds a set of attributes to an object or a collection. You can only add one custom attribute set of a
particular attributes definition to an object, but you can have as many different attribute sets from
different definitions as needed.

Parameters:
#unique
 Scripted Custom Attributes 47

When adding custom attributes to an object using the custAttributes.add() function, you
can now supply an optional #unique keyword as the third argument. If you do this, each
object being added to will have custom attributes added that have their own private copy
of the definition and do *not* share the original definition. Any later redefinitions of the
original attributes definition will not update these custom attributes. To update the
individual object’s attributes, you would get the unique definition from the object using
custAttributes.getDef, and redefine it in one of the two ways described.

Note:
If you extract the uniquely-added definition, and use it directly in another non-unique
custAttributes.add() on some other object, a definition sharing will be set up. Using #unique
when adding a global definition will make the added custom attributes non-global, they will
have their own private definition which starts out being identical to the original global
definition.
Example:
custAttributes.add $weapon01 weaponData
Opening $weapon01 in the Modify panel will now display the “Weapon Parameters”
rollout and allow them to be edited as can normal object parameters. You can use
attribute definitions to add their defined sets of attributes to any object at any time.
Any appropriate type of parameter can be animated, also, exactly as with scripted
plug-ins.
The custAttributes.add() function can be applied to an object collection to add sets of attributes to
a group of objects in one go.
Example:
custAttributes.add $weapon* weaponData
Adds a separate set of these custom attributes to all objects whose names begin
“weapon” in the scene.

Note:
Further, an object can have any number of separate sets of custom attributes added from different
attribute definitions.
As with Scripted plug-ins (p. 1538), an attributes definition can have any number of sets of parameter
and rollout clauses, to allow you to organize added attributes into multiple rollouts as needed.
Scripted custom attributes added to an object or modifier can be accessed in MAXScript. They turn
up directly as properties on the objects they are added to. If the names of any of the custom
attributes are the same as existing properties on the host object, the custom attributes are
effectively hidden when accessed directly. As an alternative, you can access each added block
of custom attributes by their attributes definition name and then access individual
attributes as properties within that block.
48 Chapter 1 | What’s New in 3ds max 4 MAXScript

So, for example, if the following attributes were added to $box01

the_weaponData = attributes weaponData
(
parameters main rollout:params
(
hitPoints type:#float ui:hits default:10
cost type:#float ui:cost default:100
sound type:#string
)

rollout params “Weapon Parameters”

( ... )
)

the custom attributes could be accessed as

$box01.hitPoints
$box01.cost
$box01.sound

or indirectly through the attributes block:

$box01.weaponData.hitPoints
$box01.weaponData.cost
$box01.weaponData.sound

• scripted custom attributes are properly saved to and loaded from scene files.
• you can assign a fixed, global definition ID to an attributes definition.
This acts in a similar way to class IDs in scripted plug-ins. Such definitions are global across
any number of scenes that custom attributes may be present in and all instances of custom
attributes of a global definition will have the same shape. The ID is specified with a new
header parameter, ‘attribID:’
attributes <name>
attribID:#(<number>, <number>)
(
...
)

Remarks:
The ID number pair is chosen to be unique, perhaps generated with the genClassID (p. 141) ()
function in MAXScript. Attribute definitions without attribID’s are private to the current MAX
session.
genClassID()

This method generates a random class ID similar to #(0x9b7ea231, 0xb6db86ef), and prints it
to Listener. You can just cut and paste this class ID into your script to use the generated ID.
 Scripted Custom Attributes 49

Global and Private Definitions

Definitions are identified now depending on whether they are global or private definitions. Global
definitions have explicit attribID: parameters, which define a globally unique ID for that definition
and ensure that any object with custom attributes based on a definition with that ID will be follow
the same definition. Whenever you evaluate an attributes definition with a particular attribID: you
will update all objects that have custom attributes based on that definition, and loading objects with
attributes of that attribID will update themselves to the current definition.
Private definitions have no explicit attribID: parameter (they effectively have an internally-
generated random one). Each time you evaluate one, except as described in the redefinition section
below, a completely distinct definition is created with its own internal ID.
In the case of both global and private definitions, the ‘attributes’ definition construct now returns
the definition as its value, so you would typically assign that value to a local and then use it to add
custom attributes to objects via the custAttributes.add() function.
Example:
local def
def = attributes “Game Data”
(
parameters ...
rollout ...
)
custAttributes.add $box01 def
custAttributes.add $box02 def

This example adds a separate set of the defined custom attributes to box01 and box02. The
definition is shared between the two boxes. Now this is a private definition, it has no attribID:, so if
you evaluated the ‘def = attributes (...)’ again, it would *not* automatically update box01’s and
box02’s attributes, as used to happen in prior builds, but create a new definition. In order to redefine
a specific attribute definition so that all objects will be updated that had attributes added using it,
you use one of two schemes that operate on the actual definition value (as it sits in the ‘def’ variable
in the above, for example). First, you can use the new ‘redefine:’ attributes definition parameter.
Example:
attributes “Game Data”
redefine:def
(
parameters ...
rollout ...
)

This expects an existing attributes definition as the value given in the redefine: parameter and will
update it to the definition that follows, and update any custom attributes made from that particular
definition value. In the example, this would update $box01 and $box02.
Alternatively, you can use the new custAttributes.redefine method:
custAttributes.redefine <def> <definition_string>
50 Chapter 1 | What’s New in 3ds max 4 MAXScript

Example:
local new_def = “attributes \“Game Data\“ ( ... )”
custAttributes.redefine def new_def

This is particularly useful in situations where you are generating the attributes definition
automatically as a string. You can use this function to compile and apply the redefinition to a
particular definition object in one go, without having to construct a name for the object, as you
would if you used the redefine: parameter scheme.
To redefine the attributes on some object, say based on the defData in that object’s custom attributes,
you might use this sequence:
old_def = custAttributes.getDef $box03 1 -- get existing def
old_def_data = custAttributes.getDefData old_def -- get my defData from it
new_def_string = generate_new_def old_def_data ... -- make new def string
custAttributes.redefine old_def new_def_string -- redefine it

These redefinition techniques can be used with global definitions (with explicit attribID:), but are
strictly unnecessary since the particular definition value is specified uniquely by the attribID:
parameter. In any situation that you evaluate a global definition, all custom attributes in the current
scene made from that definition will be updated.

Custom Attribute Management Functions

custAttributes.count <obj>
Returns a count of the number of separate scripted custom attribute sets have been added
via the .add() function.
custAttributes.get <obj> (<index> | <attrib_def>)
Returns the custom attribute set, specified as an index or by its defining attribute
definition.

Note:
The custom attribute set values, returned by the custAttributes. are effectively holder
values for the object’s custom parameters in that attribute set. You can get at these
parameter values as simple properties on the attribute set value.
Example:
gp = custAttributes.get $ gameParams
gp.hitPoints = 50

this is equivalent to accessing the custom attribute parameters directly on the object:
$.gameParams.hitPoints = 50

custAttributes.delete <obj_or_collection> (<index> | <attrib_def>)

Deletes the specified custom attribute set from the object or from all the objects in the
given collection. The set to be deleted is defined by index number or by its defining
attributes definition.
 Scripted Custom Attributes 51

custAttributes.makeUnique <obj> (<index> | <attrib_def>)

If some objects with custom attribute sets share a specific attributes definition, you can
make selected objects have unique copies of the definition.
Example:
custAttributes.add $box* def1

you can make box01 unique with:

custAttributes.makeUnique $box01 def1

or all of them unique with:

custAttributes.makeUnique $box* def1

custAttributes.getDef (<obj> <index>) | <custAttrib>

Returns the attribute definition for a given custom attribute set in an object or from a custom
attribute set accessed with the .get() method.
custAttributes.getDefs <obj>
Returns an array of definitions in attribute set order.

Attribute definition values

Attribute definition values now have several properties directly accessible:
<def>.name
Get and set descriptive name
<def>.source
Read-only, the source code for the definition
<def>.defData
Get and set the user-supplied def data value
<def>.attribID
Read-only, a two-element array containing the attribID for the def
custAttributes.getDefSource <attrib_def>
Returns the source code for the attributes definition as a string.
custAttributes.setDefData <def> <data>
Adds user-supplied data to an attributes definition.
Parameters:
The <data> value supplied here will be stored persistently with the definition and loaded
on scene loads containing attribute sets of this definition.
custAttributes.getDefData <attrib_def>
Returns the saved user-supplied data.
custAttributes.getPBlockDefs <attrib_def>

Return Values:
Returns an array containing a runtime readable encoding of all of the parameter block
definitions in the custAttributes definition. in the following form:
#(<paramblock>, <paramblock2>, ...)
52 Chapter 1 | What’s New in 3ds max 4 MAXScript

Parameters:
<paramblock>
An array of details for one parameter block in this form:
#(<name>, <id>, <refno>, <keyword_params>, <parameter1>, <parameter2>,
<parameter3>, ....)
<id>
The parameter block’s internal ID number
<refno>
The reference number of the parameter block in the owning plug-in instance
<keyword_params>
An array of the keyword parameters given on the parameter block definition in
the form:
#(<keyword>, <value>, <keyword2_name>, <value2>, ...)

<Parameter1 to ParameterN
Definition details for each parameter in the block in the following form:
#(<param_name> <keyword_params>)
<keyword_params>
An array containing all of the keyword parameters specified on that parameter’s
definition in the cust attrib definition, in the same form as the
<keyword_params> above.
Example:
Here is a function that will extract pBlock data from a custom attribute.
mapped fn custAttribute_showPBlockDefs obj =
(
format “%\n” obj.name
for objDef in (custAttributes.getDefs obj) do
(
format “\t%\n” objDef
format “\tname: %\n” objDef.name
format “\tattribute id: %\n” objDef.attribID
format “\tParameter Blocks:”
pbArray = custAttributes.getPBlockDefs objdef
for a = 1 to pbArray.count do
(
itms = pbArray[a]
format “\n\t\tname = %\n” itms[1]
format “\t\tid = %\n” itms[2]
format “\t\towners reference number = %\n” itms[3]
keywordParams = itms[4]
format “\t\tparameter block keywords:\n”
for x = 1 to keywordParams.Count/2 do
(
format “\t\t\t% = %\n” keywordParams[x] keywordParams[x+1]
x = x+1
)
format “\t\tparameters:”
 Scripted Custom Attributes 53

for y = 5 to itms.Count do
(
format “\n\t\t\t#name = %\n” itms[y][1]
for z = 1 to itms[y][2].Count by 2 do
(
format “\t\t\t% = %\n” itms[y][2][z] itms[y][2][z+1]
)
)
)
)
)
custAttributes.getSceneDefs ()
Returns an array of all the attribute definitions in the current scene.
custAttributes.deleteDef <attrib_def>
Deletes the given attribute definiton from the current scene and the current running MAX
session. There must be no objects in the scene containing custom attributes added using this
definition.

Note:
Its name can be gotten via the .name property.

Materials and Texture Maps

Scripted custom attributes can be added to any material or texture map. Rollouts defined in these
attributes will appear at the end of the Mtl Editor dialog when the material or map containing the
custom attributes is selected in the Mtl Editor.

Note:
Typing CAT_Debug = True in the MAXScript listener window will expose the code in the listener
when you add a custom attribute through the User Interface.

See Also
custAttributes const StructDef (p. 234)
54 Chapter 1 | What’s New in 3ds max 4 MAXScript

Depth of Field
Topic: version 4 MAXScript New Features/
Depth of field is available for any renderer plug-in via a published function publishing interface. No
ui has been added. Functionality can be tested by enabling various parameters via MAXScript, and
performing a normal render.
The settable dof parameters can be seen by typing ‘apropos “dof”’ in the MAXScript listener window
or here (p. 234).
To create a DOF display in a camera viewport, simply call
maxops.DisplayActiveCameraViewWithMultiPassEffect

Note that if the active view is not a camera view, or if DOF is not turned on in the camera’s
properties, then this call does nothing. Additionally, note that this method works with general
multi-pass effects and not just DOF.

See Also
DOF const StructDef (p. 234)
Depth of Field : RenderEffect (p. 1354)
Interface: maxOps (p. 368)

Edit Mesh

ApplyOperation function
Topic: version 4 MAXScript New Features/Edit Mesh
The ApplyOperation function is used by the Quad menu for activating object functions.
fn ApplyOperation ctype oper =
(
If (Modpanel.getcurrentObject () == $.baseobject) then oper $
If Classof (Modpanel.getcurrentObject ()) == ctype then
(oper $.modifiers[modPanel.getModifierIndex $
Modpanel.getcurrentObject))])
)

Example:
ApplyOperation Edit_Mesh meshops.StartExtrude

Remarks:
Starts the extrude function on EditMesh if it is either the currently selected modifier or baseobject.
 Patches 55

See Also
Quad Menu (p. 90)
MAXScriptFunction List (p. 190)

Editable Patch

Patches
Topic: version 4 MAXScript New Features/Editable Patch
There is a patch function package containing a large number of functions for creating, modifying
and accessing patch objects. The sub-object selection system in MAXScript has also been extended
to cover patch objects.
• The Editable Patch object in MAX was called ‘Patch’ in MAXScript. It has been renamed to
‘Editable_Patch’ to be consistent with Editable_Mesh and Editable_Poly, and to allow the new
patch function package to be named ‘patch’.
• The MAXScript sub-object selection system has been extended to work with Editable Patch
objects. This means that all the MAXScript VertexSelection, FaceSelection, and EdgeSelection
properties and operations now work with patch objects. The ‘face’ sub-object selections in this
system correspond to the ‘patch’ sub-object level when applied to patches.
• The Patch functions. All the functions in this package take either a scene node containing an
Editable Patch object or an Editable Patch base object as the first argument. QuadPatch and
TriPatch objects need to be converted to Editable Patches for the Patch functions to be
applicable. For example, when using the convertTo $foo Editable_Patch.
• To create a patch object from scratch, create an Editable_Patch scene object to create an empty
patch object and use the geometry & topology creations functions below to fill the patch out,
then use the patch.update() function to complete construction.

Note:
Any set of changes to a patch object using the following functions do not fully take effect until the
patch.update() function is called on it. This makes construction substantially more efficient, but can
leave a patch in an unstable state if the script that contains the changing code finishes before calling
patch.update on it, which may result in a MAX crash.

Functions:
The following functions are used to get and set the overall geometry of the patch. Supply keep:true
to the setNumXXX functions for them to retain existing vertex/vector/patch/edge data, defaults to
false, which cleans out the geometry.
The functions are largely direct calls to the methods of the same name on the MAX SDK class
PatchMesh. See the SDK Help file Advanced Topic “Working with Patches,” and the documentation
for the main Patch system classes for more detailed info.
56 Chapter 1 | What’s New in 3ds max 4 MAXScript

<integer> patch.getNumVerts <obj>

patch.setNumVerts <obj> <num> [keep:<boolean>]
<integer> patch.getNumVecs <obj>
patch.setNumVecs <obj> <num> [keep:<boolean>]
<integer> patch.getNumPatches <obj>
patch.setNumPatches <obj> <num> [keep:<boolean>]
<integer> patch.getNumEdges <obj>
patch.setNumEdges <obj> <num> [keep:<boolean>]

The following functions get and set individual vertex and vector handle locations.
The vertex and vector coordinates are interpreted in MAXScript’s current working coordinate
context.
Consistent with the rest of MAXScript, all vertex/patch/vector/edge indexes start numbering at 1.
<point3> patch.getVert <obj> <index>
patch.setVert <obj> <index> <point3>
<point3> patch.getVec <obj> <index>
patch.setVec <obj> <index> <point3>

The following two functions are the main mechanism for creating individual patches in the
patch mesh.
patch.makeQuadPatch <obj> <index> <va> <vab> <vba> <vb> <vbc> <vcb> <vc> <vcd>
<vdc> <vd> <vda> <vad> <i1> <i2> <i3> <i4> <sm>

where:
index = The index of the patch to create (0> = index < numPatches).
va = The first vertex.
vab = Vector ab.
vba = Vector ba.
vb = The second vertex.
vbc = Vector bc.
vcb = Vector cb.
vc = The third vertex.
vcd = Vector cd.
vdc = Vector dc.
vd = The fourth vertex.
vda = Vector da.
vad = Vector ad.
i1 = Interior 1.
i2 = Interior 2.
i3 = Interior 3.
i4 = Interior 4.
sm = The smoothing group mask

patch.makeTriPatch <obj> <index> <va> <vab> <vba> <vb> <vbc> <vcb> <vc> <vca> <vac>
<i1> <i2> <i3> <sm>
 Patches 57

where:
index = The index of the patch to create (0> = index < numPatches).
va = The first vertex.
vab = Vector ab.
vba = Vector ba.
vb = The second vertex.
vbc = Vector bc.
vcb = Vector cb.
vc = The third vertex.
vca = Vector ca.
vac = Vector ac.
i1 = Interior 1.
i2 = Interior 2.
i3 = Interior 3.
sm = The smoothing group mask

The following function forces all the geometry and topology caches to be rebuilt, change
notifications to be sent and a screen redraw request to be flagged.
You must call this function after making any changes to a path object before exiting the script
making the changes otherwise and invalid patch may bepassed to MAX possibly causing a crash. The
patch.update() function is similar in function and purpose to the update() function in mesh object
scripting.
patch.update <obj>

The following functions give access to the topology of an existing patch object. They return either
indexes or arrays of indexes of the sub-objects requested.
Example:
getVertVecs() returns an array of the vectors coming out of the specified vertex.
<integer_array> patch.getVertVecs <obj> <index>
<integer_array> patch.getVertPatches <obj> <index>
<integer_array> patch.getVertEdges <obj> <index>
<integer> patch.getVecVert <obj> <index>
<integer_array> patch.getVecPatches <obj> <index>
<integer> patch.getEdgeVert1 <obj> <index>
<integer> patch.getEdgeVert2 <obj> <index>
<integer> patch.getEdgeVec12 <obj> <index>
<integer> patch.getEdgeVec21 <obj> <index>

The following functions access and manipulate the texture mapping information in the
patch object.
patch.setNumMaps <obj> <num> [keep:<bool>]
<integer> patch.getNumMaps <obj>
patch.setMapSupport <obj> <map_chan> [init:<boolean>]
<boolean> patch.getMapSupport <obj> <map_chan>
patch.maxMapChannels <obj>
patch.setNumMapVerts <obj> <map_chan> <num> [keep:<boolean>]
<integer> patch.getNumMapVerts <obj> <map_index>
58 Chapter 1 | What’s New in 3ds max 4 MAXScript

patch.setNumMapPatches <obj> <map_chan> <num> [keep:<boolean>]

<point3> patch.getMapVert <obj> <map_chan> <index>
patch.setMapVert <obj> <map_chan> <index> <point3>
<index_array> patch.getMapPatch <obj> <map_chan> <index>
patch.setMapPatch <obj> <map_chan> <index> <index_array>

The following functions get and set the material ID for the patch object as a whole or for individual
patches.
<integer> patch.getMtlID <obj>
patch.setMtlID <obj> <mtl_id>
<integer> patch.getPatchMtlID <obj> <index>
patch.setPatchMtlID <obj> <patch_index> <mtl_id>

The following functions access and control viewport and renderer tessellation and visibility.
patch.setMeshSteps <obj> <steps>
patch.getMeshSteps <obj>
patch.setMeshStepsRender <obj> <steps>
patch.getMeshStepsRender <obj>
patch.setShowInterior <obj> <bool>
patch.getShowInterior <obj>
patch.setAdaptive <obj> <bool>
patch.getAdaptive <obj>
The following functions access topology info for the specified sub-object.
<integer_array> patch.getEdges <obj> <v1> [<v2>]
<integer_array> patch.getPatches <obj> <v1> [<v2>]
<integer_array> patch.getVectors <obj> <vert>

The following function transforms all the vertices and vectors in the patch object by the given
matrix. This transform happens in object local space.
patch.transform <obj> <matrix3>

The following functions perform various high-level operations on a patch object:

patch.weldVerts <obj> <threshold> <weldIdentical_bool> <startVert>
patch.weld2Verts <obj> <v1> <v2>
patch.weldEdges <obj>
patch.deletePatchParts <obj> <del_vert_bitarray> <del_patches_bitarray>
patch.clonePatchParts <obj> <patch_bit_array>
patch.subdivideEdges <obj> <propagate>
patch.subdividePatches <obj> <propagate>
patch.addTriPatch <obj>
patch.addQuadPatch <obj>

The following functions get and manipulate surface normal information. Again, normal vectors are
given in MAXScript’s current working coordinate context.
patch.patchNormal <obj> <patch>
patch.edgeNormal <obj> <edge>
patch.updatePatchNormals <obj>
 class id filter 59

patch.flipPatchNormal <obj> <patch>

patch.unifyNormals <obj>
patch.autoSmooth <obj> <angle> <useSel_bool> <preventIndirectSmoothing_bool>

The following functions access and change the vertex and interior vertex types:
patch.changeVertType <obj> <vert> #corner|#coplanar
patch.getVertType <obj> <vert> -> #corner or #coplanar
patch.changePatchInteriorType <obj> <patch> #automatic|#manual
patch.getPatchInteriorType <obj> <patch> -> #automatic or #manual

The following function returns the current mesh tessellation for the patch object:
<mesh value> patch.getMesh <obj>

The following functions are used to interpolate individual patch surfaces. A tri-patch interpolation
takes u,v,w barycentric coordinates. A quad-patch takes u and c parameters. In both cases, the point
returns is given in the current MAXScript working coordinate context.
<point3> patch.interpTriPatch <obj> <patch> <u> <v> <w>
<point3> patch.interpQuadPatch <obj> <patch> <u> <v>

See Also
patch const StructDef (p. 245)
patchOps const StructDef (p. 247)
Patch Select - superclass: modifier (p. 307)
Patch : GeometryClass (p. 1088)

Filters

class id filter
Topic: version 4 MAXScript New Features/Filters
In the Selection filters/combos filter you can, in addition to registering super classid filters, add
class id filters. The bottom left list box displays a list of all helper and geom class ids. To add a
filter select one and hit the add button below the list box. It will then appear in the lower right list
box. This list displays all of the current class id filters. Once OK is pressed then the select filter drop
down contains those class ids that were added.
You can also register filters through a callback in MAXScript.
fn selectfilter_cb node =
(
print currentTime
true
)
registerSelectFilterCallback selectfilter_cb “MAXScript”
60 Chapter 1 | What’s New in 3ds max 4 MAXScript

The above example filter prints out the current time and filters nothing. The selectfilter_cb will
return TRUE if the node is to be selectable else false.

Prototype:
registerSelectFilterCallback <filterFunction> <name>

Parameters:
<filterFunction>
The filter function
<name>
The string which appears in the filter drop down list

Remarks:
The registerSelectFilterCallback takes 2 parameters. The filter function expects one parameter, which
is the node to be checked.

Prototype:
unregisterSelectFilterCallback <filterFunction>

Parameters:
<filterFunction>
The filter function

Remarks:
There is also an unregisterSelectFilterCallback which removes the callback.
Example:
unregisterSelectFilterCallback selectfilter_cb

See Also
Selection Filter (p. 61)
Main Toolbar (p. 1574)
toolMode const StructDef (p. 257)
 Selection Filter 61

Selection Filter
Topic: version 4 MAXScript Language Improvements/User Interface
The Selection Filter list lets you restrict to specific types and combinations of objects that can be
selected by the selection tools. For example, if Cameras is selected, you can select only cameras with
the selection tools. Other objects do not respond.

Prototype:
<int>GetSelectFilter

Return Value:
Returns your current selected select filter in the toolbar.

Prototype:
<void >SetSelectFilter <int_index>
<int_index>
The index of the display filter that you want to check.

Return Value:
Sets your current select filter in the toolbar.

Prototype:
<int >GetNumberSelectFilters

Return Value:
Returns the number select filters in the drop down.

Prototype:
<BOOL>GetDisplayFilter <int_index>
Parameters:
<int_index>
The index of the display filter that you want to check.

Return Value:
Returns whether a display filter is on or not in the display panel.

Prototype:
<void>SetDisplayFilter <int_index> <bool_on>
Parameters:
<int_index>
The index of the display filter that you want to check.
<bool_on>
The state that you want to set the display filter to.
62 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Sets the state of a display filter.

Prototype:
<int>GetNumberDisplayFilters

Return Value:
Returns the number of display filters in the display panel.

Prototype:
<string>GetSelectFilterName <int_index>
Parameters:
<int_index>
The index of the display filter that you want to check.

Return Value:
These just return the name that appears in the interface for the appropriate filter.

Prototype:
<string>GetDisplayFilterName <int_index>
Parameters:
<int_index>
The index of the display filter that you want to check.

Return Value:
These just return the name that appears in the interface for the appropriate filter.

See Also
class id filter (p. 59)
Main Toolbar (p. 1574)
toolMode const StructDef (p. 257)

i-drop - drag and drop

Topic: version 4 MAXScript New Features/i-drop - drag and drop
i-drop drag-and-drop support in MAX allows i-drop-encapsulated files, scripts and texturemaps to be
dragged from web pages directly onto a MAX viewport, toolbar or menubar.
Example:
Here is a simple HTML file containing a single i-drop active-X control that represents a MAX file that
can be dropped into a MAX viewport. The HTML refers to an XML file containing details about the
MAX file to drop. The image proxy, XML file and .max file names specify files on a local G: drive,
you will have to adjust these for your setup.
 Selection Filter 63

HTML:
<!doctype html public “-//w3c//dtd html 4.0 transitional//en”>
<html>
<head>
<meta http-equiv=”Content-Type” content=”text/html; charset=iso-8859-1”>
<meta name=”Author” content=”Your Name”>
<meta name=”GENERATOR” content=”Mozilla/4.7 [en] (WinNT; U) [Netscape]”>
<title>example</title>
</head>
<body>
Here is an i-drop activeX control ....
<p>
<object name=”idrop” width=”64” height=”80” classid=”clsid:AF2880B4-B183-11D2-
ADE7-00A0245D8F3F”>
<param name=”package” value=”file:///G:/iDrop/example.xml”>
</object>
</body>
</html>
The XML package file:
<?xml version=”1.0”?>
<package xmlns=”x-schema:http://vizdevel/idrop/idrop-schema.xml”>
<proxy defaultsrc=”file:///G:/iDrop/blob.gif”>
<caption>i-Drop it!</caption>
<img src=”file:///G:/iDrop/blob.gif”/>

</proxy>
<dataset>
<datasrc clipformat=”CF_IDROP.MAX”>
<datafile src=”file:///G:/iDrop/foo.max”/>
</datasrc>
</dataset>
</package>

Drag-and-Drop Manager
Interface: dragAndDrop (p. 362)
A new type of datasrc file in an i-drop XML file can be specified that contains a macroScript with
drag-and-drop handlers that will be run when you drag and drop the i-drop control onto a MAX
viewport. These new kinds of files are called ‘drop scripts’ and have the suffix .ds. Such files
should contain a single macroScript definition with handlers for one or more of the special
dropscript events. If there is more than just a single macroScript in the .ds file, all other text is
ignored.
Here is a sample XML specifying a dropScript file called “foo.ds”:
<?xml version=”1.0”?>
<package xmlns=”x-schema:http://vizdevel/idrop/idrop-schema.xml”>
<proxy defaultsrc=”file:///G:/iDrop/blob.gif”>
<caption>i-Drop Script!</caption>
<img src=”file:///G:/iDrop/blob.gif”/>
</proxy>
64 Chapter 1 | What’s New in 3ds max 4 MAXScript

<dataset>
<datasrc clipformat=”CF_IDROP.MAX”>
<datafile src=”file:///G:/iDrop/foo.ds”/>
</datasrc>
</dataset>
</package>

dropScript Events
The current dropScript events are delivered as a mixture of positional and keyword parameters. The
first parameter is positional and is always the code name for the window on which the drop is
currently occurring. Subsequent parameters are keyword parameters that vary in name and number
depending on the window being currently dragged over or dropped on.
on droppable <window> node: point: do ...
on drop <window> node: point: do ...

Parameters:
<window>
a window identifier
node:
any item (scene node) currently under the mouse pointer
point:

Remarks:
If supplied, the ‘droppable‘ handler is called continuously while the i-drop control is dragged over
the MAX viewport, and should return true or false depending on whether the item is droppable at
that position. If the mouse is not over a scene node, the <item> argument value is undefined. You
implement the ‘droppable’ filter if the dropScript wants to limit droppability in any way.
The ‘drop’ handler is called when the user finally drops the i-drop control over a viewport and is
given the same parameters as ‘droppable’.
For example, currently for viewport windows, the full signatures are:
on droppable window node: point: do ...
on drop window node: point: do ...
but since keyword arguments are optional, you can choose any subset of the keyword arguments you
need, such as:
on drop window node: do ...
or:
on drop window do ...

Remarks:
Passing by keyword like this allows different context windows to supply a variable and large range
of context info without requiring an unwieldy and fixed set of positional args.
 Selection Filter 65

Example:
Here is a sample ‘foo.ds’ file.
macroScript foo
(
on droppable window item return
window == #viewport and
item != undefined and
classOf item == sphere

on drop window item do

(
item.scale *= 1.2
item.material = meditmaterials[1]
)
)

Example Remarks:
The droppable handle only allows dropping when the mouse is over a sphere scene node. When
dropped, that sphere will be scaled up by 1.2 and be assigned the material currently in slot 1 in the
material editor.

Dropping .max files from the Windows desktop

Behavior is handled differently depending on whether you drop the file on a viewport or anywhere
else in the MAX UI. If you drop a scene file on a viewport, the file is MERGED. If you drop elsewhere,
such as on the toolbars or menu bar, the file is OPENED, closing the currently open file.
When dropping .max scene files onto a MAX viewport, either from i-drop-enabled web pages or
directly from file directories, the Merge/XRef/Cancel pop-up menu that is displayed now includes
an Open item, which will perform a complete file open, replacing the currently open scene.

Note:
Dropping .max scene file anywhere onto the MAX UI outside viewport will automatically perform
a scene open.

Dropscripts from Toolbars

dragging-and-dropping dropScripts from the MAX toolbars is possible. DropScripts are simply
macroScripts with ‘on drop’ and optionally ‘on droppable’ handlers, as defined above. If a
macroScript button on a toolbar has an ‘on drop’ handler defined, you can drag that button off
the toolbar to initiate dropScript drag-and-drop.
Example:
Here’s a simple dropScript that applies a newly created brick material to the object that it is dropped
on. Note that it also has an ‘on execute’ handler that does the same thing to the current selection.
By providing both ‘on drop’ and ‘on execute’ handlers, you can make such a macroScript
installable in menus, hotkeys and toolbars or droppable from toolbars, the web, etc.
66 Chapter 1 | What’s New in 3ds max 4 MAXScript

macroScript dropBricks category:”DropScripts” Icon:#(”MAXScript”, 3)

(
on droppable window node: return
window == #viewport and node != undefined

on drop window node: do

node.material = standard diffuseMap:(bricks()) showInViewport:true

on execute do if selection.count == 1 then

$.material = standard diffuseMap:(bricks()) showInViewport:true
)

Remarks:
Note the use of the newly-added ‘showInViewport’ property on materials.

Drag-and-Drop script files

• You can now drop plain script files of type, .ms, .mse or .mcr, either via i-drop controls or
directly from file directories. The script is simply run when it is dropped.
• dropScripts can now supply an ‘on loaded do ...’ handler which will be called whenever
the dropScript is first loaded during a drag-and-drop operation, either from the web or from a
file directory. This allows the dropScript to perform any one-time initialization it might require
to set up drop, such as loading ancillary files, etc.

Drag-and-drop MAXScript Zip files

See also Zip-file Script Packages (p. 122)
The OLE-based drag-and-drop system in MAXScript accepts the dropping of MAXScript .mzp zip
packages. They can be dropped either from i-drop-enabled web pages or directly from file directories,
say from the Windows Explorer or the new MAX Asset Browser.
The main use for this feature is to allow script packages to be dropped into MAX and
automatically run, particularly packaged dropScripts. But, since the package can contain files of
any kind, it is possible to use it to drop any set of files, say a scene file and its maps & other
supporting files, or a new plug-in, etc. The mzp.run control file allows you to set up arbitrary
distributions of the files in the package using the extract to, copy and move commands. This can be
a useful alternative to the current i-drop package-dropping mechanism, which simply places
all the downloaded files listed in the i-drop to the MAX downloads directory.

.mzp drop protocol

When a .mzp package is dropped, the sequence of events that occurs differs slightly, depending on
whether it is dropped via an i-drop control or directly from a file directory. In summary, the i-drop
first downloads the package and then extracts it, dropping from a file directory extracts directly from
that file. Further, the ‘on droppable’ handler in any dropScript specified in the package is only
run if the package is droped via a i-drop, dropping from a file directory is a system-controlled action
that doesn’t provide any drag-over callbacks in which to run the ‘on droppable’ test.
 Selection Filter 67

From an i-drop, the .mzp file is first downloaded to the <max>\downloads directory, along with any
other files specified in the i-drop XML file, overwriting any files currently there. If the .mzp file is
the first file in the i-drop file set, it is the prime dropped file and the following .mzp processing
continues. The .mzp file is then extracted to a new temp directory, in the system’s main TEMP
directory, and the mzp.run control file is run. If there is no mzp.run file in the package, the first
file in the .mzp package is dropped, causing whatever drop protocol is appropriate for that file type.
If supplied, a typical mzp.run control file will contain extract to, move and copy commands
to control the disposition of the files extracted from the package, say placing any texture files in
$maps & scene files in $scenes, etc.
During this execution of the mzp.run file after initial load, all copies and moves are performed, and
a ‘drop’ command is looked for. The file specified on the drop command is remembered for later
drop processing. Any ‘run’ commands are ignored.
At this point, the drop file is known, either because it was supplied on a ‘drop’ command in the
mzp.run file or because it is the first file in the .mzp package if there was no mzp.run file or drop
command. If the drop file is anything other than .ds dropScript file, the drop protocol
appropriate to that file is engaged. If it is a .ds dropScript, and the drop is from an i-drop, any
‘on droppable’ handler in the dropscript is repeatedly run as the mouse is moved off MAX’s
windows, and the cursor changes to show valid drop targets. If the drag-and-drop is from a file
directory, the arrow+ cursor shows, but the ‘on droppable’ handler is NOT called. This is a
consequence of the limitations of simple file drag-and-drop in Windows. When the mouse-click is
released, the ‘on droppable’ handler is called on the target window and object and if it returns
OK or is not supplied, the ‘on drop’ handler is called. This protocol is identical to dropping .ds
dropScript files directly, as if they were not inside a .mzp package.

Note:
You can specify a file type other than a dropScript on the ‘drop’ command, such as an image or scene
file. This allows the .mzp drag-and-drop to be used for dropping any kind of package, not just scripts.

See Also
Interface: dragAndDrop (p. 362)
Zip-file Script Packages (p. 122)

Interfaces
Topic: version 4 MAXScript New Features/Interfaces
The Function Publishing System, new to 3ds max version 4, is a system that allows plug-ins to
publish their major functions and operations in such a way that code outside the plug-in can
discover and make inquiries about these functions and is thus able to call them though a common
calling mechanism. The whole system is very similar to Window’s COM and OLE Automation
systems and share many similar concepts in the architecture. However, the Function Publishing
System is not based on COM and OLE but instead is a custom architecture more suited and
optimized for MAX. The Function Publishing API serves a number of purposes, which allow 3rd
68 Chapter 1 | What’s New in 3ds max 4 MAXScript

party developers to open up important portions of their plug-ins for use by external sources,
allowing for users to extend and control these directly.

Note:
For complete details on the Function Publishing System, please see the 3ds max sdk help file topic
“Function Publishing System”.
Interfaces
Core Interfaces (p. 70)
Other Interfaces (p. 71)
Functions are published in one or more Interfaces by a plug-in. Action functions must be published
in their own set of interfaces. Each interface is represented by an instance of a class derived from the
base class FPInterface. An external system can find out about the interfaces published by calling
various query methods on ClassDesc that access these interface definition objects. As well as these
enquiry or ‘reflection’ methods, an FPInterface also has the calling methods for actually invoking a
particular function in the interface, so that if something has hold of one of your interfaces, it can
call any of its published functions.

Action Interfaces
Action Manager (p. 9)
A special kind of interface is the Action Interface. These interfaces only contain UI Action Functions
that provide a programmatic way of “pressing” buttons and keys in the UI for a plug-in.

Direct dot-notation properties

MAXScript exposes properties defined in this way as direct dot-notation properties on the interface.
So, were before the Get/SetRadius in the example cylinder mixin would have been accessed as
functions
Example:
r = $cyl01.cylMixin.getRadius()
$cyl01.cylMixin.setRadius 23

you now can use:

r = $cyl01.cylMixin.radius
$cyl01.cylMixin.radius = 23

This is true for all the types of FP interfaces that turn up in MAXScript, static, mixin and core. As a
further optimization, MAXScript now effectively promotes all interface methods and properties to
the level of the interface, so if individual methods and properties have unique names within all the
interfaces of an object or class, you can elide the interface name. The above examples could now be
written
Example:
r = $cyl01.getRadius()
$cyl01.setRadius 23
 Selection Filter 69

and:
r = $cyl01.radius
$cyl01.radius = 23

If there is a naming conflict, you can always include the interface name level to resolve this.

Published Functions and MAXScript

MAXScript automatically provides access to all functions published by a plug-in via the Function
Publishing system. Each plug-in class appears in MAXScript as a MAX class object, which can be used
to construct instances of the plug-in, do class tests, etc. If a plug-in publishes interfaces, they are
visible in MAXScript as properties on this class object. The internal name for the interface is used as
the property name. All the functions in the interface are accessible as named properties on the
interface. So, if the above example interfaces were published by EditMesh, the following script
fragments would work
Example:
EditMesh.faceOps.extrude $foo.mesh #{1,2,3} 10
calls the Extrude function in the FaceOps interface on $foo’s mesh, faces 1, 2 and 3, amount 10
units.
EditMesh.actions
retrieves and displays the action functions. Each interface is stored as a struct definition in the
class object.
EditMesh.actions.create()
starts (or stops) the create mode. This would have the side-effect of highlighting/unhighlighting
the Create button in the EditMesh rollups. Calls to Action functions in MAXScript return true
if the function returns FPS_OK and false otherwise.
if EditMesh.actions.create.isChecked() then ...
The predicate functions for an Action Function are available as properties on the action function
object itself, as shown. You can determine if a predicate is supplied by asking:
if EditMesh.actions.create.isChecked != undefined

Associated Method:
getCoreInterfaces()
Returns an array of core interface values.

See Also
Core Interfaces (p. 70)
Other Interfaces (p. 71)
By Reference Parameter Passing (p. 129)
Dereferencing Operator (p. 133)
Visible Class For ‘&’ Reference Values (p. 142)
Action Manager (p. 9)
Class and Object Inspector Functions Enhanced (p. 159)
Class and Object Inspector Functions (p. 799)
70 Chapter 1 | What’s New in 3ds max 4 MAXScript

Core Interfaces
Topic: version 4 MAXScript New Features/Interfaces
Interfaces (p. 67)
actionMan (p. 353)
BoneSys (p. 354)
browserMgr (p. 355)
cmdPanel (p. 356)
colorMan (p. 356)
dragAndDrop (p. 362)
HDIKSys (p. 365)
IKSys (p. 365)
manip (p. 366)
maxOps (p. 368)
medit (p. 371)
menuMan (p. 372)
msZip (p. 378)
netrender (p. 379)
NullInterface (p. 409)
objXRefs (p. 409)
paramWire (p. 410)
pluginManager (p. 414)
quadMenuSettings (p. 414)
rollup (p. 427)
SceneExposureControl (p. 427)
SceneRadiosity (p. 428)
timeSlider (p. 428)
trackviews (p. 429)

See Also
Other Interfaces (p. 71)
Class and Object Inspector Functions (p. 799)
Class and Object Inspector Functions Enhanced (p. 159)
 Other Interfaces 71

Other Interfaces
Topic: version 4 MAXScript New Features/Interfaces
Interfaces (p. 67)
bitmapTex (p. 434)
Block Control (p. 435)
BMP (p. 437)
Flex interfaces: (p. 438)
float list (p. 441)
Float Reactor (p. 443)
Float Wire interfaces: (p. 448)
FloatList (p. 450)
FloatReactor (p. 452)
HSDS Modifier (p. 453)
HSDS Object (p. 453)
IKChainControl (p. 453)
imageMotionBlur (p. 454)
JPEG (p. 454)
Link (p. 455)
Link Constraint (p. 455)
LookAt Constraint (p. 455)
Motion Blur (p. 462)
Orientation Constraint (p. 462)
Path (p. 462)
Path Constraint (p. 468)
Plugin Manager (p. 473)
Portable Network Graphics (p. 473)
Point3 list (p. 475)
Point3 Reactor (p. 477)
Point3 Wire (p. 477)
Point3List (p. 479)
Point3Reactor (p. 481)
Point3Spring (p. 482)
Point Cache (p. 484)
Point CacheSpacewarpModifier (p. 485)
72 Chapter 1 | What’s New in 3ds max 4 MAXScript

PointCache (p. 486)

PointCacheWSM (p. 487)
Position Constraint (p. 488)
position list (p. 490)
Position Reactor (p. 492)
Position Wire (p. 492)
PositionList (p. 494)
PositionReactor (p. 496)
PositionSpring (p. 497)
radiusManip (p. 500)
RenderElementMgr (p. 503)
rotation list (p. 505)
Rotation Reactor (p. 507)
Rotation Wire (p. 508)
RotationList (p. 510)
RotationReactor (p. 512)
scale list (p. 513)
Scale Reactor (p. 515)
Scale Wire (p. 515)
ScaleList (p. 517)
ScaleReactor (p. 519)
sliderManipulator (p. 520)
SpringPoint3Controller (p. 523)
SpringPositionController (p. 526)
Targa (p. 529)
Unwrap UVW (p. 530)
uvwMappingHeightManip (p. 551)
uvwMappingLengthManip (p. 555)
uvwMappingUTileManip (p. 558)
uvwMappingVTileManip (p. 562)
uvwMappingWidthManip (p. 565)
UVWUnwrap (p. 568)
Float Wire (p. 448)
Point3 Wire (p. 477)
 HD IK controller chains can be assigned to existing hierarchies 73

Rotation Wire (p. 508)

Scale Wire (p. 515)

See Also
Core Interfaces (p. 70)
Class and Object Inspector Functions (p. 799)
Class and Object Inspector Functions Enhanced (p. 159)

Inverse Kinematics

HD IK controller chains can be assigned to existing hierarchies

Topic: version 4 MAXScript New Features/IK
The IKChainControl uses a boolean controller for turning the IK solver on/off. On/off implies an
opposite referencing structure. When it is on, joints reference the ik goal, whereas when it is off, the
goal references the end joint, ie. the goal has to snap to the end effector. This means that the
direction of message propagation is decided on the state of this boolean controller. To avoid
evaluating an animatable attribute during message propagation, we require that this controller
cannot be replaced by a possibly arbitrarily wired controller.
HD IK controller chains can be assigned to existing hierarchies.

Prototype:
HDIKSys.ikChain <startJoint> <endJoint> <assignEE>
Parameters
<startJoint>
The first node in the new chain, called the ancestor.
<endJoint>
The last node in the chain, called the decendent.
<assignEE>
A boolean parameter: when TRUE, a position end effector is created at the endJoint.
Example:
If 4 boxes existed in the scene and Box02 was a child of Box01, Box03 was a child of Box02, and
Box04 was a child of Box03:
HDIKSys.ikChain $Box01 $Box04 TRUE
would assign HD IK controllers and create an end effector at Box04.

Pos/Rotation/Scale Property Access

Pos/Rotation/Scale properties of the nodes are accessible immediately. Instead of writing
$node.transform.controller.ik_goal.controller.pos, you can say, in MAXScript,
$node.pos.controller, etc.
74 Chapter 1 | What’s New in 3ds max 4 MAXScript

Note:
Both IKControl and IKChainControl can not be instanced.

See Also
IKChainControl interfaces: (p. 453)
Interface: HDIKSys (p. 365)
Interface: IKSys (p. 365)
IKLimb Solver (p. 74)

IKLimb Solver
Topic: version 4 MAXScript New Features/IK
The IK Limb Solver is specifically meant for animating the limbs of human characters; for example,
the hip to the ankle, or the shoulder to the wrist. It affects only two bones in a chain. It is an
analytical solver that is very fast and accurate in viewports.
Note: To use with the IK Limb solver, a bones system must have three bones in the chain. The goal
is placed at the pivot point of the third bone, and the IK solution is calculated for the first and second
bones.
The IK Limb solver works not only with bone hierarchies, but with any linked hierarchy that has
three elements, and is set up to model a human limb. The additional requirements are:
• The first joint is “spherical.” That is, it has 3 degrees of freedom.
• The second joint is “revolute.” That is, it has 1 degree of freedom.
If you attempt to put an IK Limb solver on an inappropriate chain, a warning message informs you
that your IK Limb solver assignment has no effect.
The IK Limb solver uses the same controls as the HI IK solver, so it follows the model of setting
preference angles for joints, and allows for mixing periods of forward and inverse kinematics in the
same animation period. It does not use the HD IK Solver methods of damping, precedence, and
setting joint limits.
The IK Limb solver is provided as part of the Discreet Open Source initiative, so it can be exported
directly to a game engine.
The joint angles are obtained by computing the transformation (rotation) between the initial
chain plane and the target chain plane. The initial chain plane is defined by three unit vectors:
1. shoulder-to-elbow unit vector (at the initial pose)
2. projection of end-effector-axis on a plane perpendicular to the shoulder-to-elbow unit vector
(at the initial pose)
3. cross product of the above two.
Similarly, the target plane is defined by three analogous vectors at the target pose.
 IKLimb Solver 75

See Also
Interface: IKSys (p. 365)
Interface: HDIKSys (p. 365)
HD IK controller chains can be assigned to existing hierarchies (p. 73)
IKChainControl interfaces: (p. 453)

Materials
Multi/Sub Material
Topic: version 4 MAXScript New Features/Material/Multi/Sub Material
Each entry in the Multi/Sub matl interface now has an associated ID. The previous version had the
ID being the same as the number of the sub-material in the list.
This can be seen here: MultiMaterial : Material (p. 1210)

Menu Manager
Topic: version 4 MAXScript New Features/Menu Manager
MAXScript has full access to the menu manager and menu creation system.

Note:
Be very careful when using or testing this API. It makes permanent changes to the menu database,
and it is very easy to mess things up quite badly. For example, if you “unRegister” the main menu
bar, 3ds max won’t start.
Anyone using this API should make a copy of the “..\UI\MaxMenus.mnu” file before running any
of the scripts. If anything messes up, just copy the backup version back on to MaxMenu.mnu.
There are 4 exposed interfaces to MAXScript: the menu manager, menu objects, quad menu objects
and menu items.
• The menu manager is a database of menus and quad menus.
• The main menubar and all sub-menus are menu objects.
• A quad menu object holds 4 menu objects, one for each quad.
• A menu object is a container for menu items.
• A menu item can be a separator, an action that invokes a macroScript or a sub-menu that pops
up a cascading menu.

Menu Manager
menuMan.loadMenuFile “file.mnu”
This loads a new menu file with the given name. It looks in the current “UI” directory for
the file. It return true if successful, and false if not.
menuMan.saveMenuFile “file.mnu”
This saves a new menu file with the given name. It saves it in the current “UI” directory.
76 Chapter 1 | What’s New in 3ds max 4 MAXScript

menuMan.getMenuFile()
Returns the full path to the current menu file.
menuMan.updateMenuBar()
This updates the main menu bar with any changes that have been made. This MUST be
called after changing anything on the main menu bar.
menuMan.registerMenuContext contextId
This call is used to register menu extensions. The “contextId” is a random 32-bit integer. It
can be generated using the “genclassid()” (p. 141). This function registers an extension with
the menu manager that is remembered permanently. It returns true the first time the
extension is registered, and false every time thereafter. This is saved in the MaxMenu.mnu
file, so it is sticky from session to session. This is used so that scripts can add items and
sub-menus MAX’s main menu bar and quad menus. See the sample scripts below for the
proper usage.
menuMan.findMenu “menuName”
This function returns the menu with the given name. It returns “undefined” if no menu
exists in the menu manager with the given name. This requires the full name of the menu,
including and “&” characters that might be in the name.
Example:
helpMenu = menuMan.findMenu “&Help”
Retrieve 3ds max’s help menu.
menuMan.findQuadMenu “qhadMenuName”
This works like “findMenu” but it gets quad menus instead of menus.
menuMan.unRegisterMenu menu
This removes a menu from the menu manager. Use extreme caution with this method! If
you unregister a menu that is used as a sub-menu, or in a quad menu, or the main menu
bar, bad things will result.
menuMan.unRegisterQuadMenu quadMenu
This is like “unregisterMenu” but for quad menus.
menuMan.createMenu “name”
This creates a new, empty menu with the given name.
menuMan.createQuadMenu “name” “quad1Name” “quad2Name” “quad3Name” “quad4Name”
This creates a new, empty quad menu. It contains, 4 empty menus, one for each quad.
menuMan.createSubMenuItem “name” subMenu
This creates a new sub-menu item that can be added to a menu. It uses the given “name”
and it displays the given sub-menu.
menuMan.createSeparatorItem()
This creates a new menu separator that can be added to a menu.
menuMan.createActionItem “macroScriptName” “macroScriptCategory”
This creates a new menu item that can be added to a menu. The item is an action that
executes the macro script with the given name and category. This returns “undefined” if
there is no macroScript with the given name and category.
 IKLimb Solver 77

menuMan.setViewportRightClickMenu which quadMenu

This sets the viewport right click menu to be the given quad menu. The value of “which”
can be one of the following:
#nonePressed
#shiftPressed
#altPressed
#controlPressed
#shiftAndAltPressed
#shiftAndControlPressed
#controlAndAltPressed
#shiftAndAltAndControlPressed

Example:
menuMan.setViewportRightClickMenu #nonePressed “Modeling 2”
That sets the default (no keys pressed) quad menu to “Modeling 2”. The menu name must be a
quad menu that is listed in the “Quads” customization dialog, and the name must match
exactly, including capitalization.
menuMan.SetViewportRightClickMenu returns FALSE if you try to set the viewport right-click
menu to a menu that is not allowed.
menuMan.getViewportRightClickMenu which
Retrieves the quad menu used for right-clicking in the viewport. The “which” parameter
can be one of the following:
#nonePressed
#shiftPressed
#altPressed
#controlPressed
#shiftAndAltPressed
#shiftAndControlPressed
#controlAndAltPressed
#shiftAndAltAndControlPressed

menuMan.getMainMenuBar()
Returns the menu being used as MAX’s main menu bar.
menuMan.setMainMenuBar menu
Sets the menu being used as MAX’s main menu bar. You must call
“menuMan.updateMenuBar()” in order to see the result.
menuMan.getShowAllQuads quadMenu
Gets the “show all quads” setting for the given quad menu.
menuMan.setShowAllQuads quadMenu value
This sets the “show all quads” flag for the given quad menu. “Value” can be true or false.
menuMan.getQuadMenuName quadMenu
This returns the name of the given quad menu.
menuMan.setQuadMenuName quadMenu “name”
This sets the name of the give quad menu.
78 Chapter 1 | What’s New in 3ds max 4 MAXScript

menuMan.numMenus()
Returns the total number of menus in registered with the menu manager.
menuMan.getMenu index
Retrieves the “index” th menu in the menu manager. This is a 1-based index.
menuMan.numQuadMenus()
Returns the total number of quad menus registered with the menu manager.
menuMan.getQuadMenu index
Retrieves the “index” th quad menu in the menu manager. This is a 1-based index.

Quad Menu objects

Quad menu objects have the following functions available:
quadMenu.getMenu quadIndex
Retrieves the menu object associated with the 4 quads of the menu. “quadIndex” can take
the value 0, 1, 2, or 3. Quad 0 is the lower-right, and they are numbered counter-clockwise
from there.
quadMenu.trackMenu showAllQuads
This displays the quad menu. If “showAllQuads” is true, then all 4 quads a re shows at
once. It is displayed at the current cursor position.

Menu Objects
Menus are containers for menu items, and have the following functions:
menu.setTitle “title”
Sets the title of the menu to the give string.
menu.getTitle()
Returns the current title of the menu.
menu.numItems()
Returns the number of items the menu holds.
menu.getItem index
Retrieves the menu item at the given index. The index is 0-based.
menu.addItem menuItem position
This inserts an item in the menu at the given position, which is 0-based. If the position is
-1, then the item is appended to the end of the menu.
menu.removeItemByPosition position
This removes the item at the given position.
menu.removeItem menuItem
This removes the given item from the menu, if it is in the menu.
 IKLimb Solver 79

Menu Item objects

A menu item can be a separator, a sub-menu or an action that is connected to a macroScript. The
following functions are available for menuItems:
menuItem.setTitle “title”
Sets the name associated with the item.
menuItem.getTitle()
Returns the name associated with the item.
menuItem.setUseCustomTitle value
When value is true, this tells an item that is associated with a macroScript to use the item
title when displaying the menu. Otherwise it will use the name of the macro or the
“buttontext” of the macroScript.
menuItem.getUseCustomTitle()
Returns the current value of the custom title flag.
menuItem.setDisplayFlat value
This is for sub-menu items. When value is true, it tells the menu to display the sub-menu
in-line, rather than as a cascading sub-menu.
menuItem.getDisplayFlat()
Returns the current value for the “display flat” flag.
menuItem.getIsSeparator()
Returns true if the item is a separator, and false otherwise.
menuItem.getSubMenu()
If the item is a sub-menu item, this returns the menu associated with the sub-menu.
Included below is a script that shows how to use the menuMan interface to register menu
extensions. This script should go in the “stdplugs\stdscripts” folder.
Example:
-- Sample menu extension script
-- If this script is placed in the “stdplugs\stdscripts”
-- folder, then this will add the new items to MAX’s menu bar
-- when MAX starts.
-- A sample macroScript that we will attach to a menu item
macroScript MyTest
category:”Menu Test”
tooltip:”Test Menu Item”
(
on execute do print “Hello World!”
)

Example:
-- This example adds a new entry to MAX’s main “Help” menu.
-- Register a menu context. This returns true the first time it
-- is registered, and we can add things to the menu. If
-- it returns false, then the context is already registered,
-- and the items are already in the menu.
-- The number 0x246c6dbe is random, and can be generated
-- using the genClassID() function (p. 141).
80 Chapter 1 | What’s New in 3ds max 4 MAXScript

if menuMan.registerMenuContext 0x246c6dbe then

(
-- Get the main menu bar
local mainMenuBar = menuMan.getMainMenuBar()
-- The help menu is always the last menu.
local helpMenuIndex = mainMenuBar.numItems()
-- Get the menu item that holds the help menu
local helpMenuItem = mainMenuBar.getItem(helpMenuIndex)
-- Get the menu from the item
local helpMenu = helpMenuItem.getSubMenu()
-- create a menu separator item
local sepItem = menuMan.createSeparatorItem()
-- create a menu items that calls the sample macroScript
local testItem = menuMan.createActionItem “MyTest” “Menu Test”
-- Add the separator to the end of the help menu.
-- the position of -1 means add it to the end.
helpMenu.addItem sepItem -1
-- Add the action item to the end of the help menu.
helpMenu.addItem testItem -1
-- redraw the menu bar with the new item
menuMan.updateMenuBar()
)
Example:
-- This example adds a new sub-menu to MAX’s main menu bar.
-- It adds the menu just before the “Help” menu.
if menuMan.registerMenuContext 0x1ee76d8e then
(
-- Get the main menu bar
local mainMenuBar = menuMan.getMainMenuBar()
-- Create a new menu
local subMenu = menuMan.createMenu “Test Menu”
-- create a menu item that calls the sample macroScript
local testItem = menuMan.createActionItem “MyTest” “Menu Test”
-- Add the item to the menu
subMenu.addItem testItem -1
-- Create a new menu item with the menu as it’s sub-menu
local subMenuItem = menuMan.createSubMenuItem “Test Menu” subMenu
-- compute the index of the next-to-last menu item in the main menu bar
local subMenuIndex = mainMenuBar.numItems() - 1
-- Add the sub-menu just at the second to last slot
mainMenuBar.addItem subMenuItem subMenuIndex
-- redraw the menu bar with the new item
menuMan.updateMenuBar()
)
 IKLimb Solver 81

Example:
-- This example adds a new command to MAX’s default right-click quad menu
if menuMan.registerMenuContext 0x36690115 then
(
-- Get the default viewport right-click quad menu
local quadMenu = menuMan.getViewportRightClickMenu #nonePressed
-- Get the lower-left menu from the quad
local menu = quadMenu.getMenu 3
-- create a menu item that calls the sample macroScript
local testItem = menuMan.createActionItem “MyTest” “Menu Test”
-- Add the item to the menu
menu.addItem testItem -1
)

Example:
Here are two macroScripts that set and reset two of the right-click menus:
macroScript SetQuads
category:”Custom UI”
tooltip:”Set Quad”
(
on execute do
(
quadmenu = menuMan.findQuadMenu “Modeling 2”
if quadmenu != undefined do menuMan.setViewportRightClickMenu
#nonePressed quadmenu
quadmenu = menuMan.findQuadMenu “Sample 4x1”
menuMan.setViewportRightClickMenu #controlPressed quadmenu
)
)

macroScript ResetQuads
category:”Custom UI”
tooltip:”Reset Quads”
(
on execute do
(
quadmenu = menuMan.findQuadMenu “Default Viewport Quad”
if quadmenu != undefined do menuMan.setViewportRightClickMenu
#nonePressed quadmenu
quadmenu = menuMan.findQuadMenu “Modeling 1 [Cntrl+RMB]”
if quadmenu != undefined do menuMan.setViewportRightClickMenu
#controlPressed quadmenu
)
)
82 Chapter 1 | What’s New in 3ds max 4 MAXScript

You can display a quad menu like this:

menuMan.trackQuadMenu “Default Viewport Quad”

The menu name must be a quad menu that is listed in the “Quads” customization dialog,
and the name must match exactly, including capitalization.

See Also
Quad Menu (p. 90)
Menu and CUI Loading (p. 178)
maxOps (p. 87)
Interface: quadMenuSettings (p. 414)
Interface: menuMan (p. 372)
Interface: maxOps (p. 368)

Mesher
Topic: version 4 MAXScript New Features/Mesher
The Mesher compound object converts procedural objects to mesh objects on a per-frame basis so
that you can apply modifiers such as Bend or UVW Map. It can be used with any type of object, but
is designed primarily to work with particle systems. Mesher is also useful for low-overhead
instancing of objects with complex modifier stacks.

See Also
Mesher - superclass: GeometryClass (p. 298)
particleMesher - superclass: GeometryClass (p. 306)

Network Render Interface

Topic: version 4 MAXScript New Features/Network Render Interface
The interface is fully described here: Interface: NetRender (p. 379)
Network Rendering is the rendering of animations using more than one computer connected by a
network.
Large and complex animations take many hours to render, even on the fastest PCs. Network
rendering allows you to use the power of other 3ds max enabled computers to speed up the process.

Note:
For additional details regarding network rendering, please see the topic “Network Rendering” in
the 3ds max online reference.

See Also
3D Studio MAX System Globals (p. 630)
 IKLimb Solver 83

Node Handles
Topic: version 4 MAXScript New Features/Node Handles
A property has been added to a node’s interface called .handle. This can be used to get the unique
node handle ID from the node.

Usage:
id = $Box01.handle-- returns the unique id associated with the node
A method in the maxOps interface (p. 368) will return a node associated with a given handle.

Usage:
node = maxOps.getNodeByHandle <number>-- returns the node associated with the id passed in.

Note:
It is safer to say $box01.inode.handle than $box01.handle. This is to prevent cases where the
baseobject has property called handle, like a teapot, and you get that object’s handle instead of the
node handle.

See Also
maxOps (p. 87)

Node vertexColorType
Topic: version 4 MAXScript New Features/Node vertexColorType
In the node interface, the vertexColorType property has been changed to take a symbolic enum. This
is the assigned vertex color displayed in viewports.
.vertexColorType : enum : Read|Write
vertexColorType enums: {#color|#illum|#alpha|#color_plus_illum}
Example:
$Sphere01.vertexColorType = #illum

See Also
Node : MAXWrapper (p. 820)
Node Common Properties, Operators, and Methods (p. 820)
Node Handles (p. 83)
Class and Object Inspector Functions Enhanced (p. 159)
Access to the node bone properties and methods (p. 23)
84 Chapter 1 | What’s New in 3ds max 4 MAXScript

OLE Automation

MAXScript.reg - Registery file

Topic: version 4 MAXScript New Features/OLE Automation
The last line has to be edited to point at your current 3ds max exe location.
Save the file as MAXScript.reg.
Then just double-click it in Windows Explore to register with the Windows Registery.
;-------- cut here -------------
REGEDIT
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; registration info MAX.Application (defaults to MAX.Application.4)
HKEY_CLASSES_ROOT\MAX.Application = OLE Automation MAX Application
HKEY_CLASSES_ROOT\MAX.Application\Clsid = {7FA22CB1-D26F-11d0-B260-00A0240CEEA3}
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; registration info MAX 4.0
; (Application Object)
HKEY_CLASSES_ROOT\MAX.Application.4 = OLE Automation MAX 4.0 Application
HKEY_CLASSES_ROOT\MAX.Application.4\Clsid = {7FA22CB1-D26F-11d0-B260-00A0240CEEA3}
HKEY_CLASSES_ROOT\CLSID\{7FA22CB1-D26F-11d0-B260-00A0240CEEA3} = OLE Automation
MAX 4.0 Application
HKEY_CLASSES_ROOT\CLSID\{7FA22CB1-D26F-11d0-B260-00A0240CEEA3}\ProgID =
MAX.Application.4
HKEY_CLASSES_ROOT\CLSID\{7FA22CB1-D26F-11d0-B260-
00A0240CEEA3}\VersionIndependentProgID = MAX.Application
HKEY_CLASSES_ROOT\CLSID\{7FA22CB1-D26F-11d0-B260-00A0240CEEA3}\LocalServer32 =
c:\3dsmax\3dsmax.exe
;---- cut here

See Also
Setting Up MAXScript OLE Automation (p. 1673)
OLE Automation (p. 1671)
Running the OLE Demo (p. 1674)
Exposing MAXScript Functions (p. 1673)
3ds max Specific Errors (p. 1674)
 MAXScript.reg - Registery file 85

Parameter Wiring
Topic: version 4 MAXScript New Features/Parameter Wiring
The Parameter Wire manager is described in the core interface ‘paramWire’.
In the general case, a wire controller can be wired to any number of other wire controllers in
two-way relationships. Each wire has a set of information that defines it, accessible using the
indexed accessor functions.
Example:
The following will demonstrate a way to query a wire controller and determine what parameters
it is referencing.
local wc = $foo.pos.controller -- get pos controller
if classOf wc == WirePosition then
(
-- list out its connections
for i in 1 to wc.numWires do
(
local parent = wc.getWireParent i,
parent_owner = (refs.dependents parent)[1], -- hack!
param_name = getSubAnimName parent wc.getWireSubnum
format “wire %: % in %\n” i param_name parent_owner
)
)
Additionally, you can use the subAnim indexing operator as a way to scan down through an
object for wire controllers:
for i in 1 to $foo.numSubs do
if classOf $foo[i].controller == ...

Also, you might also find the exprForMAXObject() (p. 809) method useful here to get a scripter
expression for the parent or parent owner.

See Also
Interface: paramWire (p. 410)
Float Wire interfaces: (p. 448)
Position Wire interfaces: (p. 492)
Rotation Wire interfaces: (p. 508)
Scale Wire interfaces: (p. 515)
86 Chapter 1 | What’s New in 3ds max 4 MAXScript

Plug-In Manager
Topic: version 4 MAXScript New Features/Plug In Manager
The Plug-in Manager lets you manage plug-ins dynamically without any initialization required. The
Plug-in Manager provides a list of all plug-ins found in the 3ds max plug-in directories, including
the plug-in description, type (object, helper, modifier, and so on), status (loaded or deferred), size,
and path. The Plug-in Manager provides options to load or tag as deferred, any particular plug-in,
regardless where they reside on disk.
When you start the Plug-in Manager, it scans through all the plug-in paths specified in the plug-in.ini
file and lists them in the Plug-in Manager dialog.

Actually there are two different FP interfaces in the plug-in manager, one is a action interface
accessed through Plug-in_manager and the other one is a static interface called plug-inManager.
You can access the static interface like
plug-inManager.show = true
or:
plug-inManager.loadClass Flex
Currently there is no way to integrate these into one so.

Properties:
plug-inManager.visible = true --show
plug-inManager.visible = false –hide

Remarks:
Show and hide the plug-in manager.
 maxOps 87

Prototype:
plug-inManager.loadClass <class>

Remarks:
Will ensure that the given class is loaded, in the event that it is a deferred loading class, and so any
MAXScript methods or Function Published interfaces it publishes will be available.
Example:
plug-inManager.loadClass Flex

After this code is executed, all the Flex modifier MAXScript methods are installed and callable.
Note this is only needed in situations where a plug-in loading may be deferred and it does not
have any instances already in the current scene.

See Also
Interface: plug-inManager (p. 414)
Plug-in Manager interfaces: (p. 473)

Portable Licence Manager

maxOps
Topic: version 4 MAXScript Language Improvements/maxops
There are many new MAXScript functions exposed in maxops (p. 368):
maxOps.setActiveViewportTransparencyDisplay takes a single integer argument.
0 turns off transparency in the active viewport
1 sets it to screendoor
2 sets it to blended transparency.

maxOps.setSelectionType takes two boolean arguments.

true true: enables auto Win/Cross: moving left-to-right is crossing selection
true false: enables auto Win/Cross: moving right-to-left is crossing selection
false true: disables auto Win/Cross, turns ON crossing selection
false false: disables auto Win/Cross, turns OFF crossing selection

maxOps.productVersion
the enum values returned are as follows:
#productVersionDevel- debug build, or licensed in-house
#productVersionTrial - trial license
#productVersionOrdinary - commercial license
#productVersionNFR - not for resale
#productVersionEdu - educational or student license
88 Chapter 1 | What’s New in 3ds max 4 MAXScript

maxOps.licenseBehavior
the enum values returned are as follows:
#licenseBehaviorPermanent - permanent license, or hardware lock
#licenseBehaviorExtendable - term license, can be extended
#licenseBehaviorNonextendable - term license, cannot be extended

maxOps.licenseDaysLeft
Its return value is an integer indicating the number of full days left in the term of the license. A
value of 0 means that today is the last day of validity. For permanent licenses, a fixed value is
returned indicating greater than 10 years are left.

Note:
It should be noted that the all copies of 3ds max return a hardwarelockid (p. 630) of “-1” while under
the grace period and until they have been authorized. You can check for that number and initiate
your own demo mode.
maxOps.getNodeByHandleNode_Handles
Returns the node associated with the id passed in.
maxOps.setSelectionType <auto> <method>
<auto>
True or False
<method>
Valid values or method are #window, #crossing, #leftToRight, #rightToLeft.
#window or #crossing is to be used if the first argument (auto) is false. #leftToRight or
#rightToLeft is to be used when auto is true.
maxOps.trackBar
maxOps.getTrackBarItrackBar()
maxOps.trackBar.visible
maxOps.trackBar.filter
maxOps.trackBar.showFrames
maxOps.trackBar.showAudio
maxOps.trackBar.showSelectionRange
maxOps.trackBar.showSnapToFrames
maxOps.trackBar.keyTransparency
maxOps.trackBar.selKeyTransparency
maxOps.trackBar.cursorTransparency
maxOps.trackBar.redraw()
maxOps.trackBar.getNextKeyTime()
maxOps.trackBar.getPreviousKeyTime()
maxOps.cloneNodes

Prototype:
<boolean>CloneNodes <&node array>nodes <&point3>offset expandHierarchy:<boolean>
cloneType:<enum> actualNodeList:<node array> newNodes:<node array>
 maxOps 89

Arguments:
nodes is In parameter
This is the list of nodes that you want to clone.
offset is In parameter
The positional offset that will be applied to the cloned nodes.

Keyword arguments:
expandHierarchy default value: false
Indicates if children will be cloned in hierarchies. Default is false.
cloneType enums: {#copy|#instance|#reference}
default value: #copy
actualNodeList default value: #()
This node array will be filled in with the original nodes to be cloned. The reason for
this is that there can be dependencies between nodes that causes other nodes to be
added to the list. For example light/camera targets, nodes part of systems, part of
groups or expanded hierarchies etc.
newNodes default value: #()
This node array will be filled in with the new cloned nodes. There is a one to one
relationship between the nodes in the resultSource and the resultTraget.

Return Value:
If successful true, otherwise false.
maxOps.CollapseNode node noWarnings
maxOps.CollapseNodeTo node modIndex noWarnings

See Also
Interface: maxOps (p. 368)
ItrackBar (p. 113)
Node Handles (p. 83)
3D Studio MAX System Globals (p. 630)
90 Chapter 1 | What’s New in 3ds max 4 MAXScript

Quad Menu
Topic: version 4 MAXScript New Features/Quad Menu
When you click the right mouse button anywhere in an active viewport, except on the viewport
label, the program displays a Quad menu at the mouse cursor. The quad menu can display up to four
quadrant areas with various commands.
In the MAXScript listener window, type apropos “quadmenusettings” to see the list of functions
available.
The Quad menu is set in the startup scripts directory called QuadOptions_Startup.ms.
The two right quadrants of the default quad menu display generic commands, which are shared
between all objects. The two left quadrants contain context-specific commands, such as mesh tools
and light commands. Each of these menus provides convenient access to functions found in the
command panel.
The quad menu contents depend on what is selected, as well as any customization options you may
have selected in the Quads panel of the Customize UI dialog. The menus are set up to display only
the commands that are available for the current selection, therefore selecting different types of
objects displays different commands in the quadrants. Consequently, if no object is selected, all of
the object-specific commands will be hidden. If all of the commands for one quadrant are hidden,
the quadrant will not be displayed.

Note:
PickObject() does not pick objects when launched from a Quad Menu. It will hang and refuses to
pick any object. Hit ‘escape’ for emergency exit. PickObject works correctly from a shortcut and
toolbar.

See also
Interface: quadMenuSettings (p. 414)
ApplyOperation function (p. 54)
Menu Manager (p. 75)
Interface: menuMan (p. 372)
Menu and CUI Loading (p. 178)
 Reactor controller 91

Reactors

Reactor controller
Topic: version 4 MAXScript New Features/Reactors
The Reactor controller is a procedural controller that reacts to changes in any other controller within
the software. Reactor comes in five different forms: Position Reactor, Rotation Reactor, Point3
Reactor, Scale Reactor, and Float Reactor. Any animatable parameter in the software can react to
changes in any other animatable parameter. Reactor is not based on time, but is based on other
variables in your scene.
Example:
-- Setup a scene
ball = sphere name:”ball” pos:[-40,0,50] radius:10
ball.pos.controller = position_XYZ()
-- create some keys
key = addNewKey ball.pos.Zposition.controller 0
key.outTangentType = #slow
key.value = 50
key = addNewKey ball.pos.Xposition.controller 0
key.value = -40
key = addNewKey ball.pos.Zposition.controller 25
key.InTangentType = #fast
key.outTangentType = #fast
key.value = 4
key = addNewKey ball.pos.Xposition.controller 25
key.value = -10
key = addNewKey ball.pos.Zposition.controller 50
key.InTangentType = #slow
key.value = 50
key = addNewKey ball.pos.Xposition.controller 50
key.value = 20
ball.showtrajectory = true
-- assign a reactor controller to the scale of the ball
reactor = Scale_Reactor()
ball.scale.controller = reactor
-- Pick the react to object, and create reactions
reactor.reactions.reactTo ball.pos.ZPosition.controller 0
reactor.reactions.setName 0 “UnSquashed”
reactor.reactions.setVectorState 0 [1,1,1]
reactor.reactions.create “squashed” 25
reactor.reactions.setVectorState 1 [2.5,2.5,.4]
reactor.reactions.setValueAsFloat 0 10
reactor.reactions.setInfluence 0 6
reactor.reactions.setInfluence 1 5.5
reactor.reactions.setStrength 1 1.5
reactor.reactions.setFalloff 0 1.75
ss = StringStream ““
reactor.reactions.getType()
92 Chapter 1 | What’s New in 3ds max 4 MAXScript

ct = reactor.reactions.getCount()
format “Reactor Statistics: \n------------------------------\n \n” to:ss
format “Count : %\n” ct to:ss
format “\n” to:ss
for i = 0 to ct-1 do
(
format “Reaction #: % \n------------------------------------------------
Name : %
State: %
Value: %
Strength: %
Influence : %
Falloff: % \n\n” (i) (reactor.reactions.getName i)
(getReactionState reactor (i+1)) (getReactionValue reactor (i+1))
(reactor.reactions.getStrength i) (reactor.reactions.getInfluence i )
(reactor.reactions.getFalloff i ) to:ss
)
print ss

See Also
Reactor Controllers (p. 1326)
Float Reactor interfaces: (p. 443)
Point3 Reactor interfaces: (p. 477)
Scale Reactor interfaces: (p. 515)
Position Reactor interfaces: (p. 492)

Render Element Manager

Topic: version 4 MAXScript New Features/Render Element Manager
Rendering to elements lets you separate various information in the rendering into individual image
files. This can be useful when you work with some image-processing or special-effects software. You
can later do compositing with the element renderings.
When you render one or more elements, a normal complete rendering is also generated. In fact, the
element renderings are generated during the same rendering pass, so rendering elements costs little
extra render time.
Rendering to elements is available only when you do production rendering with the default scanline
renderer.
RenderElementMgr interfaces: (p. 503)
This is the interface for the Render Element Manager.

See Also
Interface: maxOps (p. 368)
Combustion (p. 38)
 type:#integer parameters in scripted plug-in parameter blocks 93

Scripted Plug-Ins

type:#integer parameters in scripted plug-in parameter blocks

Topic: version 4 MAXScript New Features/Scripted Plug-In
type:#integer parameters in scripted plug-in parameter blocks can now be associated with
dropDownList rollout items via the ui: option in the parameter definition.
The value in the parameter corresponds to the 1-based index of the currently selected item in the
dropDownList.
Typically, you would populate this list with names or strings, and the value in the associate
parameter effectively becomes a code number for these names or strings. Setting the value of the
parameter via a script will automatically cause the corresponding item in the dropDownList to be
selected if the UI for that object is currently open.

See Also
Scripted Plug-ins (p. 1538)
Scripted Plug-in Events (p. 93)
Scripted Cameras (p. 94)

Scripted Plug-in Events

Topic: version 4 MAXScript New Features/Scripted Plug-In
Two new event calls have been added to scripted plug-ins. If you provide handlers for these in your
scripted plug-in body, they will be called when their corresponding event occurs.
on attachedToNode <nodeVar> do ...
Called whenever a scripted plug-in scene object (geometry, camera, light, helper, shape) is
bound to a node in the scene, such as during create mode. The node that the current plug-in
instance is being attached to is given as the first argument. In the event of scene node
instancing, this handler may be called several times, whenever the base object is instanced to a
node. Note that, in most cases, this will be called in the middle of a create mode and
consequently, actions such as creating other nodes in the handler body are forbidden, as they
are generally in ‘on create’ handlers.
on deleted do ...
Called whenever the scripted plug-in object is finally deleted. This may not occur immediately,
such as when a scene node containing a scripted base object is deleted, since the object is held
onto by the undo stack in case the node delete is undone by the user. The delete may occur
when the undo stack is cleared, such file new or reset.
94 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
Scripted Plug-ins (p. 1538)
type:#integer parameters in scripted plug-in parameter blocks (p. 93)
Scripted Cameras (p. 94)

Scripted Cameras
Topic: version 4 MAXScript New Features/Scripted Plug-In/Scripted Cameras
Scripted camera plug-ins can now be written in MAXScript. At present, you can write either
extending camera plug-ins that extend existing MAX cameras or temporary camera plug-ins that can
be used to host create tools for a custom camera system.
The plug-in superclass for cameras is ‘camera’.
An event handler is available to scripted cameras that gives access to the
CameraObject::renderApertureChanged callbacks made by the rendering dialog to a camera
when the user adjusts parameters that affect render aperture. The new handler is optional.
on renderApertureChanged val do ....
The ‘val’ parameter contains the new render aperture value. This typically gets called
when you select a new apeture in the Output Size dropdown in the render dialog or adjust
a spinner when in Custom mode.
There are several cases where this handler is called:
• In the Render Scene dialog, if Image Aspect is unlocked and you change Width, Height, or
Pixel Aspect
• In the Render Scene dialog, if you click on one of the output size preset buttons
• In the Render Scene dialog, if Image Aspect is locked and you change Width, Height, or Pixel
Aspect, or if you change Aperture Width, and then click on either Render or Close
The value being passed into handler is the aperture width. You can get the remaining values via:
renderWidth, renderHeight, and RenderPixelAspect global variables. However, what you get for
these values are typically the old value, with the exception of the Aperture Width value. The call to
the handler is coming from a “InvalidateCameras” method, which is called right before setting the
new values. Doesn’t look like any broadcasts are made after the new values are set, and if safe frames
isn’t turned on in any viewport, none of the viewports are redrawn.
We recommend that if a scripted camera uses this handler, it should cache the old Aperture Width
value and test the incoming value against the cached value before proceeding.
 dependsOn For Scripted Controllers 95

Example:
plug-in Camera CamTest
name:”CamTest”
classID:#(0x47db14ff, 0x4e9b5f90)
category:”Standard”
( on renderApertureChanged val do format “renderApertureChanged: %\n” val
tool create
( on mousePoint click do #stop
)
)

See Also
Scripted Plug-ins (p. 1538)
Scripted Plug-in Events (p. 93)
type:#integer parameters in scripted plug-in parameter blocks (p. 93)
Scripted Cameras (p. 94)

Scripted Controllers

dependsOn For Scripted Controllers

Topic: version 4 MAXScript New Features/Scripted Plug-In/Scripted Controllers
dependsOn is used with scripted controllers to enable interactive update of scripted controllers
when the code in them depends on other objects in the scene. You place a call to dependsOn in the
controller script somewhere (usually at the top), with a list of objects on which the controller
depends. Interactive changes to any of these objects will cause the object containing the script
controller to also update.
Example:
A $foo.pos controller script:
dependsOn $foo2 $foo3
($foo2.pos + $foo3.pos) / 2

will always keep $foo centered between $foo1 and $foo2. The objects given to the dependsOn()
function can be any MAX object, controllers, base object, nodes, materials, etc. They must be
individual, explicit objects, not wild-card path names or arrays of objects. The object can be the
exact controller you want to depend on or any containing object. The strict dependency for the
above script would be,
Example:
dependsOn $foo2.pos.controller $foo3.pos.controller
The simpler $foo2 $foo3 will catch *any* kind of changes to those nodes or components in them
like base objects, modifiers, or materials and update the script-controlled object. The dependency is
96 Chapter 1 | What’s New in 3ds max 4 MAXScript

established the first time the controller is evaluated after any script change or recompile. This can
be when editing in a controller property box, or after a scene load.
You can programmatically force a recompile and reset of the dependents by setting the control script
to itself:
$foo.pos.controller.script = $foo.pos.controller.script

See Also
script controllers (p. 162)

Matrix3 Scripted Controller

Topic: version 4 MAXScript New Features/Scripted Plug-In/Scripted Controllers
The Transform Script controller contains all of the information contained in a Position/Rotation/
Scale (PRS) controller in one scripted matrix value. Instead of having three separate tracks for
position, rotation, and scale, all three values can be simultaneously accessed from one script
controller dialog. Because a script defines the transform values, they are easier to animate.
The value of the controller script must be a matrix3 value. A matrix3 value is a 4x3 3D
transformation matrix. For more information, see the Matrix3 Values topic in the MAXScript
reference.
The software interprets the text you type into the Script text box as the body of a MAXScript block
expression. You can type as many expressions as you want on as many lines as you want, and they
are evaluated in turn. The value of the last expression is taken as the controller value. This must yield
a matrix3 value for Transform Script controllers.
Since the text is inside a block expression, you can declare local variables, which are visible only
within the script and are temporary for one evaluation. You can also declare or access global
variables that are shared with all other scripts in MAXScript and hold their values from one
evaluation to the next.
The software with respect to a specific animation time always evaluates a controller. This might be
the current time slider or incrementing frame time if an animation is playing, or a rendering is under
way. In the case of Script controllers, the time being evaluated is used to establish an automatic “at
time” context around the controller script, so any properties you access (outside of other explicit “at
time” expressions) yield the correct values for the current controller evaluation time. This means
you don’t have to do anything special in your scripts to work at the correct time. You can access the
evaluation time, with the standard MAXScript variable, current Time. You can also reference scene
property values at other times by using “at time” expressions in your scripts, as in regular MAXScript
programming.
Example:
t=transform_script()
t.script = “(matrix3 1)”
 Matrix3 Scripted Controller 97

See Also
transform_script - superclass: Matrix3Controller (p. 339)
Script Controllers (p. 1329)

Scripted Manipulators
Topic: version 4 MAXScript New Features/Scripted Plug-In/Scripted Manipulators
Manipulators are a new type of helper object. They are designed to support direct manipulation of
parameters in the3D viewports. They can be set up to manipulate parameters on objects, modifiers,
controllers and nodes.
There is a “Manipulate” button on the main toolbar. When pressed, the system will show all the
manipulators for selected objects. As the mouse passes over a manipulator, it turns red, and a tool
tip pops up with the name of the current value of the parameter that is affected by that manipulator.
To manipulate the value, you click down on the gizmo with the left mouse button and drag it. Most
manipulators are designed so that the gizmo will track under the current mouse position, if possible.
Note that “Manipulate” is not a separate mode. It modifies whatever mode you are currently in
(select, move, create, etc.) to show manipulators and allow manipulation. If you are in move mode,
for example, you can still move things around as usual. The only difference is that if you click down
on a manipulator, you will manipulate, instead of move.
There are two flavors of manipulators. The first are manipulators that are automatically created
when you enter “Manipulate” mode. The hotspot manipulator is like that. The second kind is
stand-alone objects, like the slider manipulator. These are usually used in conjunction with
parameter wiring to get make them useful.
To create a stand-alone manipulator, you go to the “Helpers” section of the create panel, and select
“Manipulators” in the drop-down list.
Stand-alone manipulators do not need to be selected in order to be manipulated. However, the
automatically created manipulators, like the hotspot manipulator, are only displayed for selected
objects.
Manipulators support both 3d gizmos and 2d (screen space) gizmos. The hotspot manipulator is an
example of a 3d gizmo, and the slider is an example of a 2d gizmo.
Manipulators can be created either as standard MAX plug-ins in C++, or they can be implemented
in MAXScript. In MAXScript, they are a type of Scripted Plug-in object (p. 1538), so if you want to write
your own manipulator, it would be a good idea to read about Scripted Plug-ins (p. 1538) first. They are
very similar to scripted geometry objects.
Three scripted manipulators that you can use as sample code can be found in the
“..\stdplugs\stdscripts” folder.
• RadiusManip.ms: Generic “radius” manipulator
• SliderManip.ms: A 2d viewport slider. A stand-alone manipulator
• UVWManip.ms: A set of manipulators for the UVW modifier
98 Chapter 1 | What’s New in 3ds max 4 MAXScript

Radius Manipulator
The radius manipulator is fairly simple, so it makes a good example to describe the scripted
manipulator system.
The code for the manipulator is included below, followed by a detailed description of how it works.
--------------------------------------------------------------------
-- Generic radius manipulator
-- Written by Scott Morrison
-- This manipulator sets the radius on any object or modifier with
-- a parameter named “radius”. It creates a circle gizmo of the appropriate
-- radius centered at the origin in the XY plane.
plug-in simpleManipulator radiusManip
name:”RadiusManip”
invisible:true
(
-- Create the green and red colors for the gizmo
local g = [0, 1, 0], r = [1, 0, 0]
-- This manipulator manipulates any node with a “radius” property
on canManipulate target return (findItem (getPropNames target) #radius) != 0
-- Create the manipulator gizmo.
-- This is called initially and whenever the manipulator target changes
on updateGizmos do
(
-- Clear the current gizmo cache
this.clearGizmos()

-- Set the radius of circle gizmo a little bigger than the target radius
giz = manip.makeCircle [0,0,0] (target.radius * 1.01) 28
-- Add the circle to the manipulator
this.addGizmoShape giz 0 g r
-- return the ToolTip string
return node.name + “ radius = “ + target.radius as string
)
-- mouseMove is called on every mouse move when dragging the manip
-- It needs to convert the mouse position ‘m’ into a new value for the
radius
on mouseMove m which do
(
-- Create the XY plane.
-- manip.makePlaneFromNormal takes a normal vector and a point
-- and creates a plane passing through the point with the given normal
local pl = manip.makePlaneFromNormal z_axis [0, 0, 0],
projectedPoint = [0,0,0]
-- Compute the hit-ray in local coordinates
viewRay = this.getLocalViewRay m
-- Intersect the plane with the view ray
res = pl.intersect viewRay &projectedPoint
 Matrix3 Scripted Controller 99

-- If the intersection worked, set the radius

if (res) then target.radius = (length projectedPoint) / 1.01
)
)
--------------------------------------------------------------------

The header:
plug-in simpleManipulator radiusManip
name:”RadiusManip”
invisible:true

Indicates to MAXScript that this is a scripted manipulator plug-in called “RadiusManip”. The
“invisible:true” tells the system not to make a creation button for the manipulator in the
create panel.

The body:
A set of handlers for various events.
on canManipulate target return (findItem (getPropNames target) #radius) != 0
“canManipulate” is called on every manipulator, for every node that is selected when the
“Manipulate” button is pressed. The “target” parameter is the object that we might potentially
manipulate. It is called on the base object, all the modifiers on the object, and transform controllers
on the object’s node. Also, if the transform controller is a PRS controller, it calls “canManipulate”
on the position, rotation and scale controllers.
In the case of the radius manipulator, it can manipulate any object that has a property named
“radius”.
If you want to create a manipulator that works on a specific object type, say a sphere, you can say:
on canManipulate target return classOf target == sphere
There is an alternative handler that may be needed in some cases called “canManipulateNode n”.
This is called passing in the each selected node to the handler. This is not normally needed, but
available if your manipulator wants to manipulate property of a node other than the ones that are
passed as the “target” to “canManipulate”.

Note:
A Scripted Plug-in should only implement one of these handlers, not both.
The next handler is called “updateGizmos,” and this is called whenever a manipulator need to build
its gizmos. This happens when the manipulator is created, and whenever the target that it is
manipulating changes.
When MAXScript creates a manipulator, it sets up some variables that are available inside the calls
to its handlers. One of these is called “target” and it is the object, modifier or controller that is
being manipulated. Another is called “this” and it is the manipulator itself. It also sets up some
constant values that can be used as flags on gizmos. These will be described later. There is also a
“node” value available which is the node that owns the target.
100 Chapter 1 | What’s New in 3ds max 4 MAXScript

The first thing every manipulator must to in the “updateGizmos” handler is call
“this.clearGizmos()”. This clears any currently cached gizmos.
Next it creates a set of gizmos that will be displayed in the viewport. In the case of the radius
manipulator, it creates a single circle that represents the radius being manipulated.
giz = manip.makeCircle [0,0,0] (target.radius * 1.01) 28

“manip” is a exported set of utility interface functions that manipulators can use. See the
“Reference” section below for full details. In this case we are creating a circle, centered at the
origin, with radius 1.01 times the radius we are manipulating, and 28 segments. The “1.01” factor
was added so that the gizmo will stick out a little bit from the object it is manipulating. If we used
the radius directly, then it might not be visible in the viewport, because it co-exists with the object
it is manipulating.
Note that 3d gizmos are defined in the local coordinate system of the node that owns the
manipulator target. The system will automatically compensate if the node is moved, rotated or
scaled when displaying or hit-testing the manipulator.
Next, we add the gizmo to the manipulator:
this.addGizmoShape giz 0 g r

This tells the manipulator to add the shape gizmo to the manipulator, with no special flags values
ie. the “0”. All of the the flags will be decribed below. Additionally, the command indicates to use
green (“g”) as the unselected color and red (“r”) as the selected color. The selected color is used when
the mouse passes over it, and the unselected color is used when the mouse isn’t over it.
Finally, this method returns a string value that will be used as the tool tip when the mouse passes
over the gizmo.
In general, gizmos can be made from meshes, shapes (wire frame), text and markers. The details are
covered in the reference section below.
The next handler is called “mouseMove m which”. This is called on every mouse movement when
the target is being manipulated. The “m” parameter holds the screen coordinates of the mouse
location, and the “which” parameter is an index that indicates which gizmo is being dragged. The
gizmos are numbered in the order of their creation in “updateGizmos,” starting at 0.
The mouseMove handler is usually the trickiest part of the manipulator to implement. It needs to
update the value of the parameter being manipulated in such a way that the manipulator gizmo
tracks under themouse, if possible.
For manipulators that exist in 3d space, this is normally done by computing a “hit-ray,” which is
a ray in 3d space that passes through the mouse position, and travels in the direction of the view.
This is computed as follows:
viewRay = this.getLocalViewRay m

This view ray is then intersected with some plane, and the new parameter value is computed using
the intersection point.
 Matrix3 Scripted Controller 101

In the case of the radius manipulator, the plane we use is the XY plane, because the radius circle lies
on the XY plane, in local coordinate space.
This plane is computed as follows:
local pl = manip.makePlaneFromNormal z_axis [0, 0, 0],

This create “pl” which is a plane whose normal is the Z axis, and which passes through the origin
([0,0,0]).
To intersect this with the view ray, we use the “intersect” operation on planes:
projectedPoint = [0,0,0]

res = pl.intersect viewRay &projectedPoint

We set up “projectedPoint” first at the holder of the result of the intersection. The return value
“res” is a boolean value that tells us if the intersection worked or not. If it returns true, the
intersection worked, if it returns false, it failed. It can fail if the plane is parallel to the view ray.
Once we have the intersection point, in “projectedPoint,” then we use that to determine a new
value for the radius. In this case we use the distance from the origin (“length projectedPoint”)
as the new radius. We scale it by dividing by 1.01 to compensate for the fact that we made the gizmo
1.01 time bigger than the actual radius being manipulated.
That’s it! Generally, you will need to use some trigonometry and linear algebra in your
“mouseMove” handler. The idea behind direct manipulation is that the gizmo should track directly
under the mouse.
For a more complicated example of a 3d manipulator, check the code in UVWManip.ms.

Stand-alone Manipulators
Stand-alone manipulators, like the 2d slider, require a bit more work.
The code in SliderManip.ms will be used for this discussion.
The header has a bit more information:
plug-in simpleManipulator sliderManipulator
name:”Slider”
classID:#(0x47db14ef, 0x4e9b5990)
category:”Manipulators”

Since stand-alone manipulators can be saved in the MAX file, it needs a class ID (p. 141). See the
MAXScript reference for more information about that. It also does not include the
“invisible:true” line, which means that the system will create a button for it in the “Create”
panel. It will be placed in the “Manipulators” section of the helper create panel.
We also need to define a parameter block and rollout UI for the object. This is done in the same way
as other scripted plug-ins.
Stand-alone manipulators manipulate themselves, so the “canManipulate” handler looks like this:
on canManipulate target return (classOf target) == sliderManipulator
102 Chapter 1 | What’s New in 3ds max 4 MAXScript

We also need to provide a creation tool that handles mouse interaction when creating the
manipulator. This is handle exactly like other scripted plug-ins.
A stand-alone manipulator also needs some special code in its “updateGizmos” handler. For the
slider this looks like:
-- If this is not a stand-alone manip, get values from the manip target
if (target != undefined) then
(
this.value = target.value
this.minVal = target.minVal
this.maxVal = target.maxVal
this.xPos = target.xPos
this.yPos = target.yPos
this.width = target.width
this.hide = target.hide
this.sldName = target.sldName
this.snapToggle = target.snapToggle
this.snapVal = target.snapVal
unselColor = greenColor
)
else
(
unselColor = yellowColor
)

The test of “target != undefined” is to see if this if this is a manipulator, or stand-alone object.
When the object is stand-alone, the value of “target” is undefined, and it uses the value of the
parameters from its own parameter block. It target is defined, then this means it is manipulating. In
that case, we want to copy the values of the parameters from the target that we are manipulating.

Reference
Scripted manipulators can have the following handlers:
on canManipulate target
This returns a value that says whether this manipulator manipulate the given target.
on canManipulateNode n
This returns a value that says whether this manipulator manipulate the given node.

Note:
A manipulator should only implement one of these handlers.
on updateGizmos
This is called whenever the manipulator needs to build its gizmos. It returns a string value
that is used for the tool tip. If it returns an empty string, no tool tip is displayed.
on mouseMove m which
This is called when the user has grabbed a gizmo and is dragging it.
 Matrix3 Scripted Controller 103

The “m” parameter hold the current screen coordinates of the mouse, and the “which”
parameter indicates the 0-based index of the gizmo that is being dragged. This is what
handles that actual manipulation.

Note:
Normally this will set a value of a parameter of the manipulation target based on the mouse location.
on mouseDown m which
Called when the user first clicks the mouse down on the gizmo.
on mouseUp m which
Called when the user releases the mouse after manipulation is done.

Helper Functions
There are some built-in functions that manipulators support, and a couple of helper packages with
utility functions.
The simpleManipulator type itself has these functions available:
this.clearGizmos()
This must be called at the beginning of the “updateGizmos” handler in order to clear the
current gizmo cache.
this.addGizmoMesh mesh flags unselColor selColor
This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any
arbitrary MAX mesh, and created with the tools in MAXScript for creating meshes. One
convenient way to do this is to create an instance of a primitive and get the mesh from it.
The flags can be 0, or one or more of these value. If you want more than one flag to apply,
then you add the values together. Here are all the flags, and whether that can be used with
addGizmoText, addGizmoMarker, addGizmoShape and addGizmoMesh:
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed,
applies to all.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested,
applies to all.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport, applies
to all.
this.addGizmoShape gizmoShape flags unselColor selColor
This creates a gizmo from a shape object. The gizmoShape can be created using functions
from the “manip” package, described below.
The flags can take on the same value as for “addGizmoMesh,” with two new values
supported:
gizmoUseScreenSpace
104 Chapter 1 | What’s New in 3ds max 4 MAXScript

This tells the system to interpret the coordinates of the shape as device coordinates in
the viewport, not as 3d values. The values are still specified as 3d points, but the “Z”
coordinate is ignored, applies to all but addGizmoMesh.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0
to 1.0, and interpreted in each viewport as a percentage of the width or height of the
viewport, applies to all but addGizmoMesh.
addGizmoMarker markerType position flags unselColor selColor
The creates a gizmo using a marker. The value of the “markerType” parameter can be:
#point
#hollowBox
#plusSign
#asterisk
#xMarker
#bigBox
#circle
#triangle
#diamond
#smallHollowBox
#smallCircle
#smallTriangle
#smallDiamond
#dot
#smallDot
The position is a point in 3d space, or 2d screen space. The flags are the same ones
supported by addGizmoShape.
addGizmoText text position flags unselColor selColor
This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or
grabbed by the mouse. It is used for display purposes only.
getLocalViewRay m
This function takes a mouse position and returns the ray that passes through that mouse
position in the direction of the view. It is returned in the local coordinates of the node that
owns the manipulator target.

The “manip” package

“manip” is a value in MAXScript that contains a set of useful interface functions for manipulators.
The functions it exports are:
manip.makeSphere position radius segments
This returns a mesh sphere with the given position, radius, and segments.
manip.makeTorus position radius1 radius2 segments sides
Create a torus mesh with the given values.
manip.makeBox position length width height lengthSegs widthSegs heightSegs
Creates a box mesh with the given parameters.
 Matrix3 Scripted Controller 105

manip.makePlaneFromNormal normal point

Creates a Plane object with the given normal that passes through the given point.
manip.makeCircle center radius segments
Creates a circle shape in the XY plane with the given parameters.
manip.makeGizmoShape()
Creates an empty gizmo shape. See the details of “GizmoShape” below for how to use this.

Plane objects
The plane objects returned from “manip.makePlaneFromNormal” have the following functions
available:
projectedPoint = [0,0,0]
plane.intersect ray &intersectionPoint
This intersects the given ray with the plane. It returns true if it succeeds, and false if it
doesn’t. If it works, then the intersection point is set in the “intersectionPoint” value,
which must be initialized to a Point3 value in advance.
plane.mostOrthogonal ray otherPlane
This returns the plane that is most orthogonal to the given ray. This means the plane that
is most “square” to the view direction.
Sometimes a manipulator might choose between two different planes on which to project a ray. It
is usually best to project it to the plane which faces the view ray most directly, and this function
determines that. See “UVWManip.ms” for an example of how to use this.
plane.getNormal()
Returns the normal of a plane.
plane.getPoint()
Return the point that the plane passes through.
plane.getPlaneConstant()
Return the value of the plane constant. This is the value of “D” in the equation that
defines the plane:
Ax + By +Cz + D = 0

GizmoShape objects.
A GizmoShape is a shape object that you can use to construct wire-frame gizmos. You can get an
empty GizmoShape as follows:
local giz = manip.makeGizmoShape()

The functions available are:

giz.addPoint point
This adds a new point to the shape. The points are connected by line segments in order to
create the wireframe. If you want a closed shape, you have to add the first point again as
the last point.
106 Chapter 1 | What’s New in 3ds max 4 MAXScript

giz.startNewLine()
This begins a new line segment in the shape.
giz.transform matrix
This transforms the gizmo by the given Matrix3 transform.

Note:
See the UVWManip.ms for an example of creating 3d gizmos with GizmoShape.

See Also
Interface: manip (p. 366)
sliderManipulator interfaces: (p. 520)
radiusManip interfaces: (p. 500)
uvwMappingHeightManip interfaces: (p. 551)
uvwMappingLengthManip interfaces: (p. 555)
uvwMappingUTileManip interfaces: (p. 558)
uvwMappingVTileManip interfaces: (p. 562)
uvwMappingWidthManip interfaces: (p. 565)
ConeAngleManip - superclass: helper (p. 277)
PlaneAngleManip - superclass: helper (p. 311)
Scripted Plug-ins (p. 1538)
sliderManipulator - superclass: helper (p. 333)

Scripted Objects

on detachedFromNode For Object Scripted Plug-ins

Topic: version 4 MAXScript New Features/Scripted Plug-In/Scripted Objects
There is a handler to scene object scripted plug-ins, on detachedFromNode <node> do ... This is
called whenever a node that references a plug-in instance is deleted in the scene. Note that, in the
presence of instancing, there may still be other nodes referencing the base object instance.

See Also
Scripted Plug-ins (p. 1538)
 RenderEffects Progress Callback Mechanism 107

Scripted RenderEffects

RenderEffects Progress Callback Mechanism

You can control the main RenderEffects dialog progress bar using an on apply handler with
progressCB, the progress callback interface object. The following syntax lets you do this:
on apply <bitmap> progressCB: do <fn>

The first argument is the bitmap value to be modified by the effect, and progressCB is a progress
callback interface object. This interface has several methods you can call during the course of
processing the bitmap that control the progress bar and check for user cancellation.

Methods
progressCB.setTitle <string>
Sets the title on the progress bar.
progressCB.progress <done> <total>
Indicates the progress of the rendering. Both arguments are integers; done indicates how
much of the rendering has been completed, and total indicates how much there is
to do.
When this is called, the main render effects progress bar is updated to reflect this progress.
This function also returns a boolean, which if true indicates that the user has hit the
escape key to cancel the effect rendering.
progressCB.check()
Indicates whether the user has hit the escape key to cancel the effect rendering. This
function returns a boolean; false if processing should continue, and true if the user has
cancelled the rendering.
Example:
on apply bm progressCB: do
(
…
progressCB.setTitle “My Effect Pass1”
…
escapeEnable = false -- turn on scripter escape processing
for i in …
(
<the effect rendering loop>
…
if progressCB.progress completed total then exit
)
…
escapeEnable = true
…
)
108 Chapter 1 | What’s New in 3ds max 4 MAXScript

The progress bar update is done inside the main processing loop and the check for user cancel is
done on the same call, causing the loop to exit prematurely in this example.

See Also
RenderEffect : MAXWrapper (p. 1347)
Scripted RenderEffect Plug-ins (p. 1566)
Render Effects Common Properties, Operators, and Methods (p. 1347)

Scripted Rollouts

Multi-line editText UI items in Scripted Rollouts

Topic: version 4 MAXScript New Features/Scripted Plug-In/Scripted Rollouts
Multi-line editText UI items can now be created in scripted rollouts.
If an explicit height: parameter is supplied on an editText item definition that specifies a pixel height
greater than one line of text, that editText item becomes a multi-line edit box, allowing multiple
lines of text to be entered.
When in multi-line mode, <enter> keystrokes no longer cause the ‘on entered’ handler to be called,
but are inserted into the edit box as new lines.
They do, of course, cause ‘on changed’ handlers to be called. These are called on every keystroke.
For multi-line editText items, ‘on entered’ handlers are called when the edit box loses keyboard
focus, such as if you tab or click out of the edit box.

See Also
Edittext (p. 1496)
Rollout Floater Windows (p. 1477)
 Multi-line editText UI items in Scripted Rollouts 109

Skin
Joint Angle Morph
Spring Controller
Topic: version 4 MAXScript New Features/Spring Controller
The Spring controller adds secondary dynamics effects to any point or object position. The end
result is secondary mass/spring dynamics similar to Flex. This constraint adds realism to generally
static animations.
When you apply Spring to an animated object, its original motion is preserved and secondary,
velocity-based dynamics are applied. When you first apply the controller, it constructs a virtual
spring between the object’s original position and where it would end up after forces are applied to
it. You can adjust spring tension and dampening. Increasing the tension creates a tighter spring,
while increasing the dampening smoothes out jitters in the motion.
Users have control over the point’s Mass and Drag, the spring’s Tension and Dampening, and other
world space constraints. These include being able to add external forces like Wind and Gravity
(spacewarps), and being able to constrain the spring effects along a given axis. This way you can add
vertical dynamics while controlling the about of effect it has in the horizontal directions.
The solution is calculated using a start time and a step size. Solutions are cached once for the last
tick calculated, and once per frame. Performance should be the same one each frame as you step
forward, and significantly faster after the first pass if nothing changes. Cached values will be used if
going backwards in time.
The biggest slowdown occurs when animating an object that the controller uses as a force way down
the time line since this is a history dependant solver. If a lot of animation is going to occur along a
long timeline you can shut off the spring solver by setting steps to 0. Set this back to the desired
value when you want the solution recalculated.

Methods
Prototype:
<float>getMass()

Return Value:
Returns the mass.

Prototype:
<void>setMass <float>mass
Parameters:
<float>mass
110 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Sets the mass. The mass of the object to which the Spring controller is applied. Increasing the mass
causes the “bouncing” spring motion to become more exaggerated.

Prototype:
<float>getDrag()

Return Value:
Returns the drag.

Prototype:
<void>setDrag <float>drag
Parameters:
<float>drag

Remarks:
Sets the drag. Acts as air friction on the spring motion. A low Drag setting results in a greater
“bouncing” effect, while a high Drag results in subdued bouncing. Default=1. Range=0 to 10.

Prototype:
<float>getTension <index>springIndex
Parameters:
<index>springIndex

Return Value:
Gets the tension for the spring corresponding to the index.

Prototype:
<void>setTension <index>springIndex <float>tension
Parameters:
<index>springIndex
<float>tension

Remarks:
Sets the tension for the spring corresponding to the index. The “stiffness” of the virtual spring
between the controlled object and the highlighted spring object(s).

Prototype:
<float>getDampening <index>springIndex
Parameters:
<index>springIndex

Return Value:
Gets the dampening for the spring corresponding to the index.
 Multi-line editText UI items in Scripted Rollouts 111

Prototype:
<void>setDampening <index>springIndex <float>dampening
Parameters:
<index>springIndex
<float>dampening

Remarks:
Sets the dampening for the spring corresponding to the index. : Acts as a multiplier of an internal
factor that determines how quickly the object comes to rest. With the Self Influence spring,
changing Dampening has the same effect as changing Drag. With other springs, Dampening affects
only the movement caused by that spring. Internally, the dampening value is proportional to the
tension, so as you increase the tension and make the solution more stiff, the dampening is increased
to maintain system stability.

Prototype:
<boolean>addSpring <node>node
Parameters:
<node>node

Remarks:
Adds the node to the spring list.

Return Value:
Returns true if successful, false otherwise

Prototype:
<integer>getSpringCount()

Return Value:
Returns the number of springs in the spring system.

Prototype:
<void>removeSpringByIndex <index>springIndex
Parameters:
<index>springIndex

Remarks:
Removes the spring corresponding to the index.

Prototype:
<void>removeSpring <node>node
Parameters:
<node>node

Remarks:
Removes the spring if the node is in the spring list.
112 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
PositionSpring interfaces: (p. 497)
Point3Spring interfaces: (p. 482)
SpringPoint3Controller interfaces: (p. 523)
SpringPoint3Controller - superclass: Point3Controller (p. 336)
SpringPositionController interfaces: (p. 526)
SpringPositionController - superclass: PositionController (p. 337)
Flex : Modifier (p. 1128)
Flex interfaces: (p. 438)
flexOps const StructDef (p. 235)

SubObject Mode
System Tools
Topic: version 4 MAXScript New Features/System Tools
A new global struct called “systemTools” has been added to MAXScript.
This group of functions lets you gather various pieces of information about the system that you
are using.
systemTools.NumberOfProcessors()
Returns the number of processors
systemTools.GetScreenWidth()
Returns the screen width including multiple monitors.
systemTools.GetScreenHeight()
Returns the screen height including multiple monitors.
systemTools.IsWindows98or2000()
Returns true if the OS is Windows98 or Win2000
systemTools.IsWindows9x()
Returns true if the OS is a Win9x flavor
systemTools.IsDebugging()
Returns true if running in a debugger

See Also
systemTools const StructDef (p. 256)
System Information (p. 141)
sysInfo const StructDef (p. 255)
 Multi-line editText UI items in Scripted Rollouts 113

Trackbar Interface
Topic: version 4 MAXScript New Features/TrackBar
An interface has been added to access properties and methods of the trackbar. The trackbar interface
can be retrieved using a function or property in maxOps. (p. 368)
trackBar_Interface = maxOps.trackBar
or:
trackBar_Interface = maxOps.getTrackBar()

The following methods and properties are available for the trackbar.
Properties:
.visible : boolean : Read|Write
Displays or hides the trackbar
.filter : enum : Read|Write
filter enums: {#all|#TMOnly|#currentTM|#cbject|#mat}
Sets and gets the filter that determines which keys are displayed in the trackbar
.showFrames : bool : Read|Write
Sets/gets whether or not frames are displayed in the trackbar
.showAudio : bool : Read|Write
Sets/gets whether or not the audio track is displayed in the trackbar
.showSelectionRange : bool : Read|Write
Sets/gets whether or not selection ranges are displayed in the trackbar
.showSnapToFrames : bool : Read|Write
Sets/gets whether or not keys are snapped to frames when moved
.keyTransparency : integer : Read|Write
Sets/gets the key transparency value. Acceptable values range 0-255
.selKeyTransparency : integer : Read|Write
Sets/gets the selected key transparency value. Acceptable values range 0-255
.cursorTransparency : integer : Read|Write
Sets/gets the cursor transparency value. Acceptable values range 0-255
114 Chapter 1 | What’s New in 3ds max 4 MAXScript

Methods:
<void>redraw forceRedraw:<bool>
forceRedraw default value: false
Indicates if the redraw should be forced
Redraws the trackbar.
<time>getNextKeyTime()
Gets the next key time. The “at time” context can be used to determine the starting point.
<time>getPreviousKeyTime()
Gets the previous key time. The “at time” context can be used to determine the
starting point.

See Also
maxOps (p. 87)
Interface: maxOps (p. 368)

Trackviews
Topic: version 4 MAXScript New Features/Trackviews
The methods and properties are:
trackviews.isOpen <fpvalue>name or index
Returns a boolean value indicating if the specified trackview is open.
trackviews.isCurrent <fpvalue>name or index
Returns a boolean value indicating if the trackview is the last one used or not.
trackviews.setCurrent <fpvalue>name or index
Sets the specified trackview to be the current one. Returns true if successful.
trackviews.currentTrackView
Read only property that returns the interface for the currently used trackview. Returns
undefined if the trackview is closed.
trackviews.lastUsedTrackViewName
Read only property that returns the name of the current trackview.
trackviews.openLastUsedTrackView()
Opens the current trackview if it has been closed.
trackviews.delete <fpvalue>name or index
Deletes the specified trackview.
trackviews.close <fpvalue>name or index
You can now close a trackview based on it’s index or name.
trackviews.open <fpvalue>name or index
You can now open a trackview based on it’s index or name.
trackviews.getTrackView <fpvalue>name or index
This method will get a trackview based on it’s index or name.
 Multi-line editText UI items in Scripted Rollouts 115

Example:
showInterface (trackviews.getTrackView 1)
trackviews.getAllTrackViews()
Returns an array of trackviews.
trackviews.numTrackViews()
Returns the number of trackviews.
trackviews.getTrackViewName <index>index
Returns the name of the trackview window based on the index.
<void>setName <string>name
Sets the name of the trackview window
<integer>getNumTracks()
Gets the number of tracks currently displayed in trackview
<integer>numSelTracks()
Gets the number of selected tracks
<boolean>canAssignController()
Tests to see if all selected tracks are of the same type
<void>assignControllerDialog
Invokes the assign controller dialog if canAssignController()
<boolean>assignController <maxObject>controller
Assigns the controller to the selected tracks if canAssignController() is true and the
controller is the appropriate type
<void>showControllerTypes <boolean>state
Sets the ShowControllerType property
<void>expandTracks()
Expands all tracks
<void>zoomSelected()
Zooms to the selected object’s track
<void>zoomOnTrack <maxObject>parent <index>subNum
Zooms to the track defined by the parent and the subNum
<maxObject>getTrack <index>index
Returns the object belonging to the indexed track
<maxObject>getParent <index>index
Gets the parent of the object belonging to the index track. If the object is a position
controller, the parent is the Transform controller
<maxObject>getSelected <index>index
Gets the objects belonging to the selected, indexed track
<maxObject>getParentOfSelected <index>index
Gets the indexed selected tracks parent object
<index>getSelectedSubNum <index>index
Gets the subNum of the selected track
<index>getIndex <maxObject>object
Gets the index for the animatable object
116 Chapter 1 | What’s New in 3ds max 4 MAXScript

<boolean>selectTrackByIndex <index>index <boolean>clearSelection

Selects tracks by index
<boolean>selectTrack <maxObject>object <boolean>clearSelection
Selects tracks by object
A trackview interface can be obtained for one of the currently open trackviews using one of the
following methods.
trackviews.getTrackViewByName <name as string>

trackviews.getTrackViewByIndex <index as int>

trackviews.getAllTrackViews()

Once you have an instance of the trackview interface you can call the following new methods on it.
getEditMode()
Gets the current edit mode as an symbolic enum.
setEditMode <type as symbolic enum>
Sets the current edit mode
editMode
Property to do the same as the above two methods
valid symbolic enum values are:
#editKeys
#editTime
#editFCurves
#editRanges
#positionRanges

See Also
trackView const StructDef (p. 257)
Interface: trackviews (p. 429)
Track View (p. 1609)
 Multi-line editText UI items in Scripted Rollouts 117

Visual MAXScript
Topic: version 4 MAXScript New Features/Visual MAXScript

“Visual MAXScript is a direct-manipulation, multithreaded, forms-based editor that you can use to
layout and edit MAXScript rollouts. Rollout scripts can be created from scratch in the forms editor,
or use it to interactively edit and add to an existing rollout definition in a script editor window.”
The layout editor can be accessed in two ways:
• as a stand-alone Utility plug-in named “Visual MAXScript”
When accessed as a Utility through the Utility command panel, the layout editor operates in a
“stand-alone” mode. Any forms created can either be exported as separate script files containing
the rollout definition script or saved in a special .vms binary layout file that can be opened again
by the Visual MAXScript utility. When used in this mode, any script files exported can be
opened in script editor windows for further editing in MAXScript or merging with other
script files.
118 Chapter 1 | What’s New in 3ds max 4 MAXScript

• through 2 new menu items in the Edit menu in script editor windows
When accessed through the new script editor Edit menu items, the layout editor is designed for
application to rollout definition sections in the active script editor. The “New Rollout” menu
item is used to create a rollout definition from scratch. You place the cursor in the edit window
where you want the newly-generated rollout code to be inserted and choose Edit>New Rollout.
This opens the editor on a blank form to which you can add and arrange and edit rollout items.
Choosing File>Save or hitting the Save icon in the layout editor window will cause the script for
the rollout to be inserted at that point in the editor window. Subsequent edits and saves while
the layout editor is still open cause that inserted code to be updated.
The “Edit Rollout” item (hotkey F2), is used to edit an existing rollout definition in the active script
editor. You place the cursor anywhere inside a rollout or utility definition, choose Edit>Edit Rollout
(F2), and the layout editor is opened showing that rollout. You can edit and add to the rollout in the
layout editor and when you choose File>Save or click the Save icon in the layout editor, the original
definition is replaced with new code corresponding to the edited rollout. Subsequent changes and
saves while the layout editor is still open cause that code to be updated each time.

Features:
• You can have more than one layout editor open at a time This allows you to cut and paste
operations between them. Also, note that cutting and pasting in VMS also copies event code.
• When opened from a script editor window, the text in that editor window becomes ‘frozen’
while the layout editor is open. The editor window can be brought to the front and scrolled and
saved, but any other operation will be ignored and a beep will sound. The editor will ‘unfreeze’
as soon as you close the layout editor.
• The Edit>Edit Rollout function can be applied to any existing rollout definition. It attempts to
parse the definition and open an equivalent editable version in the layout editor. This is a
somewhat tricky heuristic and may well fail for certain rollouts until we get the bugs out.
MAXScript preserves all the code in the rollout and updates only those parts that correspond to
the things you can edit in the layout editor, namely, UI items and their handlers.
• Code generated by the layout editor always specifies explicit pos: width: and height:
parameters for UI items, it does not use align:, offset:, or any of the other
auto-layout parameters. This means that any rollout that you edit that uses automatic
layout will be transformed into an explicitly-positioned layout when you do the first File>Save.
It is quite difficult to preserve the auto-layout parameters under arbitrary edits in the editor and
the assumption is that once you start editing a rollout using the layout editor you will continue
to do so.
Note:
An extreme example of this is the group ( ) construct which is used to nest a set of items in a group
box. Nested group ( ) constructs are removed completely by the layout editor and replaced with new
groupBox UI items that define an explicitly-sized box around the original items. You can edit and
add and nest groupBoxes as needed in the editor.
 Multi-line editText UI items in Scripted Rollouts 119

• If there is a syntax error in a rollout definition being opened by Edit>Edit Rollout, the syntax
error is reported and highlighted and the layout editor does not open - it can only be opened
on error free source.
• When you first edit or create a rollout in the layout editor, it defaults to the standard width for
Command Panel rollouts. You can adjust this width in the editor by resizing the outer gray
rectangle and the editor emits width: and height: parameters on the generated rollout
header. You can edit these numbers in the script editor and they will be honored by the layout
editor when you next edit that rollout.
For command panel rollouts and other scripted plug-ins, there are now symbolic
constants provided that produce the correct width automatically. These are:
#cmdPanel
#effectsDlg
#mtlEditor

so, to set up the rollout for a scripted material (p. 1565), you’d add a width: parameter to
the rollout header like this:
rollout foo “Frabulation” width:#mtlEditor
(
...

• You add new UI items by clicking its button in the item toolbar at the bottom and then dragging
out a rectangle for it in the main form. You can select an existing item and edit its paramters in
the property list on the right. You can select multiple items by fence-dragging or ctrl-clicking
and perform various alignments operations, see the Layout menu. A selected item can be deleted
by clicking the red X toolbar button. The various panes can be resized or even torn off if you
want to customize the editor layout.
• Axis restriction works by holding the shift down while moving objects. This will restrict
movement to the X or Y axis based on the angle of the mouse from its initial position.
• editText boxes in the editor can now be multi-line, consistent with the mulit-line editText in
MAXScript (p. 108).
• Editing in the Array editor dialog has been rationalized and improved. Clicking on an item in
the list box toggles the selection state of it. When items are selected in the list box, changing
text in the edit field and hitting enter changes all the selected items to what was in the edit box,
this allows for editing of entries in the middle of the list.
• A new custom item type has been added to the item type toolbar at the bottom of the VisualMS
dialog, allowing custom items to be created from scratch in the editor. Its icon appears in the
toolbar as a face in profile. When first created, the item class parameter in the parameter list
shows as ‘???’ and must be edited to contain the desired custom item type.
• An ActiveX control rollout item type is available in MAXScript. The icon for it appears in the UI
item toolbar at the bottom of the VisualMS dialog, as a dot array with the word OLE
superimposed. ActiveX Controls in MAXScript Rollouts (p. 10)
120 Chapter 1 | What’s New in 3ds max 4 MAXScript

• Editing an existing rollout source that contains any unrecognized UI item types, such as those
added from 3rd-party .dlx MAXScript extensions appear in the VisualMS rollout window as new
‘custom’ items, displaying as a rectangle containing the new ‘custom’ type icon. Any definition
parameters on are displayed and editable in the parameter list, and overall position and size of
the bounding rectangle of the custom type can be edited in the rollout pane.
• You can de-select everything by clicking in the white space around the main form.
• The main form always has a black rectangle drawn around it even when deselected. This allows
you to see the form if both the background of the application and the form are the same color.
• Resizing of the main form now snaps to the grid if it is on.
• The paste command now works much better. Pasted objects are offset by [10,10] pixels,
maintain unique names, and then pasting everything is de-selected and the pasted objects get
selected.
• When editing an existing rollout definition that makes use of autmatic layout in VMS for the
first time, it is highly recommended that you add a ‘width:n’ parameter to the rollout header
first so that the editor can position items correctly.If no width: parameter is supplied, it
defaults to Command Panel width which may be too small for floating window rollouts or
scripted materials or effects.
For rollouts that will appear in a rolloutFloater, you should set the rollout width: equal to
the floater window width minus 30.
Example:
rollout foo “Frabulation” width:#270
(
...
)
...
rf = newRolloutFloater “Frabo” 300 220
addRollout foo rf

Xref Objects
Topic: version 4 MAXScript New Features/Xref Objects
An updated function published interface for Xref Objects.
Interface: objXRefs (p. 409)

Explicit References
A file being xref’d that has a script controller whose script has explicit references ($sphere01, etc.)
to objects in the incoming xref file have a potential problem for the script writer. The problem is,
the objects in the xref file are invisible to the scripter, and so a script will fail. This is actually a
general problem with xrefs, you cannot have scripts of any kind in the file (scripts controllers, param
wires, callback scripts, etc.) that depend on explicit scene object references.
 Multi-line editText UI items in Scripted Rollouts 121

The persistent global solution is the only one that is viable at this time. There are two general
solutions: 1) associate an owning-scene context with controller scripts, etc., when they come in via
xref and use that to anchor pathname searches and other scene-relative references, and 2) have an
accessible ‘evaluation context’ for controllers sent as part of the GetValue() call, so we can know
what object’s parameter the current GetValue() call is being made for and can therefore get rid of
many of the uses of explicit pathnames in the scripts.

Currently, MAXScript now fully loads any persistent globals in xref’d and merged files, but does NOT
make them persistent in the current scene. As an example of a setup showing how this can be used,
imagine a file with 3 spheres that will be xref’d. You need to establish persistent globals for all the
scene objects to be referrenced in controller scripts, like this:
persistent global s1 = $sphere01, s2 = $sphere02, s3 = $sphere03
this has to be run sometime while the to-be-xrefed scene is the currently open scene. Then
in the controller scripts, you’d say something like:
global s1, s2
dependsOn s1 s2
(s1.pos + s2.pos) / 2
Note this uses ‘global’ not ‘persistent global’, so you don’t go making them persistent
again when they get xref’d into some other scene.

See Also
XRef Files (p. 1643)
XRefScene Values (p. 1038)
XRefObject : Node (p. 1037)
xrefs const StructDef (p. 259)
xrefPaths const StructDef (p. 259)
Interface: objXRefs (p. 409)
122 Chapter 1 | What’s New in 3ds max 4 MAXScript

Zip-file Script Packages

Topic: version 4 MAXScript New Features/Zip-file Script Packages
This is a new feature in MAXScript that allows a package of related files, perhaps making up a
scripted tool, to be bundled and compressed into a single zip format file. This package file can then
be run like an ordinary .ms file. Any secondary files, needed by the tool, will be either automatically
found in the package or they will be automatically extracted to specified locations prior to running
the main tool scripts.
The file type for script packages is ‘.mzp’. These files are recognized as executable script files in the
following situations:
• auto-loading at MAX startup, in scripts\startups, stdplugs\stdscripts, etc. any .mzp file found
is run.
• choosing the Run Script menu item in the main MAXScript menu, or in the Listener menu, now
shows .mzp files as one of the default kinds of executable files in the Open Script dialog and will
run it if selected
• specifying a fileName: parameter when adding a callBack script (p. 29)
• as executable files inside other .mzp archives, you can nest them if want
• when using the fileIn <fileName> function (p. xlix), you can specify a .mzp package for fileIn

The mzp package

The package startup control file is ‘mzp.run’. When a .mzp package is opened, it is scanned for an
‘mzp.run’ file and, if found, the package commands in it are executed in sequence.
If there is no mzp.run control file in the package, MAXScript will unzip all the files in it to a unique
temporary directory in the system temp directory and run all the executable script files it finds, in
unspecified order. The kinds of rundle script files in a .mzp package are .ms, .mse and nested
.mzp files.
When the contents of the .mzp file is extracted to a destination folder, either the default temp folder
or one defined in the mzp.run control file, MAXScript will build and replicate any folder structure
that is present in the .mzp file.
When you cause a script file inside the package to be run, either through ‘run’ commands in the
mzp.run file, or by the default running scheme described in the previous item, the package becomes
a search context for files that the script may try to open while it is running such things as image
.bmp files, include files, etc. Only files named by relative path names are searched for in the package,
fully specified paths (with device names at the front) will be looked for at the specified location.
The names of files and directories in commands that take them now can be supplied WITHOUT
surrounding double quotes if the name contains only the following kinds of characters:
alphanumeric, ‘_’, ‘$’, ‘*’, ‘.’, ‘-’, ‘\‘
which covers most file names. Any file names with embedded spaces or punctuation
not in the above list needs double-quotes.
 Multi-line editText UI items in Scripted Rollouts 123

Example:
name “test package”
version 3
treeCopy flobber to $scripts
copy *.ms to $scripts\flobber\dobber
move foo.max $scenes
drop $scenes\foo.max

The zip package is a text file that contains one or more of the following commands. All are optional.
name “<package_name>“
Names the package.
description “<text>“
Describes the package. Normally, a readme file in the package would give extended
operating instructions, if they are provided.
version <number>
Returns the version number of the package.
extract to “<directory>“
Specifies the location in which to extract the contained files. This can be an absolute path
name (starting with a drive letter or \) or a relative name. Relative names are taken as
being relative to the default temp directory. The special prefix $max can be used to specify
the main MAX executable directory
run “<script_file_name>“
If the package is launched from a MAXScript run menu item or via a fileIn() function, run
the named script file. There can be more than one run command and they are run in
order. These are ignored if the package is launched via a fileIn() call that is supplied with
an explicit script file to run.
drop “<dropScript_file_name>“
If the package is launched by drag-and-drop into MAX, run the named dropScript file.
There can only be one of these per msp.startup file.
copy “<files>“ to “<directory>“
Copies the named file or files (if the <files> string contains wild-cards) to the given
directory. The special $max prefix can be used here.
clear temp
Cause the temporarily-extracted files to be deleted once all the nominated scripts are run
or dropped.
clear temp on MAX exit
Cause the temporarily-extracted files to be deleted when the currently running MAX
session exits.
clear temp on reset
Cause the temporarily-extracted files to be deleted when a file open or reset is performed.
keep temp
Prevents any deletion of the extracted files.
124 Chapter 1 | What’s New in 3ds max 4 MAXScript

File Searches:
The following functions will perform searches for files given as relative file names in the current
package file:
fileIn <filename> (p. xlix)
include <filename> (p. lix)
openBitmap <filename> (p. 755)
editScript <filename>

Note:
Any saves will not go back into the package, but into the temp extracted file.
loadMAXFile <filename>
mergeMAXFile <filename> ...
getMAXFileObjectNames <filename>
importFile <filename> ...
loadMaterialLibrary <filename>

Bitmap Searches:
The following UI items will search for named bitmap .bmp files in the package:
bitmap <name> fileName:<filename>
button <name> images:<image_spec_array>
checkButton <name> images:<image_spec_array>

Relative file names can contain path names, so for example,

fileIn “libs/myFns.ms”
would search in the “libs” sub-folder in the extracted package for “myFns.ms”. You can
arrange the contents of the package in any kind of folder nesting desired and file names in
running script or in the mzp.run control file are relative to the package directory structure.

Copy and Move:

copy “<from>“ to “<to>“ [noReplace]
move “<from>“ to “<to>“ [noReplace]
treeCopy “<from>“ to “<to>“ [noReplace]
treeMove “<from>“ to “<to>“ [noReplace]

These cause files from within the package to be copied or moved as specified. The treeCopy &
treeMove variants move whole nested directories of files. By default, any existing files in the
destination location are replaced with the newly extracted ones, add the ‘noReplace’ keyword to
prevent this.
The <to> spec must always be a directory. Any treeCopy/Move replicates the source sub-directories
into the <to> directory, making new directories as needed. The <from> spec for copy & move may
be any relative or fully specified file name or wild-card pattern. Relatively named files are looked for
in that relative position in the package. Fully specified names are looked for in the main file-system.
The <from> spec for treeCopy/Move may be just a directory path, in which case the whole directory
and its subdirectories are copied/moved, or it can be a wild-card path name in which case just the
matching files or directory trees are copied/moved.
 Multi-line editText UI items in Scripted Rollouts 125

The file path names you can specify in the various commands (extract to, run, copy, move, etc.) can
have a starting path that is one of several special names beginning with $. These name useful
locations in the currently running MAX installation.
The $ names recognized are:
$max - main MAX executable directory
$maps - first directory in Maps directory config
$scenes - scenes directory
$fonts - fonts directory
$imports - imports directory
$sounds - sounds directory
$matlibs - matlibs directory
$scripts - scripts
$startupScripts - auto-load startup scripts
$plug-ins - first in the Plug-ins directory config
$plugcfg - plugcfg
$images - images
$ui - UI
$macroScripts - macroScripts in UI directory
$web - web directory
$temp - system temp directory

These directories reflect any customization the user has set up in the various preference dialogs.
Example:
If you had set up a package with several scenes, plug-ins & map files in several directories in the
package, you could install them with some move commands in the mzp.run file, something like this:
move “plug-ins\*.*” to “$plug-ins”
move “*.max” to “$scenes”
move “texmaps\*.bmp” to “$maps”

Note:
As an added feature, if the scripts run from within a package define any functions, macroScripts,
plug-ins, rollouts, or any major MAXScript value or construct that might live longer that the
running script, then the package is ‘associated’ with that defined value or construct and will again
become the initial search location whenever the functions or handlers in the rollouts/plug-ins/
macroScripts/etc. are later run.

Open, Merge, Xref and Import:

open <max_file_name> -- opens the named MAX scene file
merge <max_file_name> -- merges the named MAX scene file
xref <max_file_name> -- xref the named MAX scene file
import <importable_file_name> -- imports the named file
Only one ‘open’ or ‘import’ command may be used per mzp.run file. Any number of merge and xref
commands can be used.
126 Chapter 1 | What’s New in 3ds max 4 MAXScript

Winzip:
You can initially create a .mzp with a zip utility such as WinZip. You can then associate that utility
with the .mzp type, so simple double-clicking a .mzp file will open it in that editor. You only need
to set up this association once, and you can do this in the Windows Explorer by selecting a .mzp file,
shift-right-clicking on the selected file and choosing “Open with...” in the popup menu that
appears. Scroll the application list that appears to find you desired zip utility and check the “Always
use this program ...” checkbox at the bottom of the dialog.

msZip Interface:
The MAXScript zip package interface (p. 378) has exposed 2 scripter-callable functions:
msZip.fileInPackage <mzpFilename> &<exractDirVar>

The ‘fileInPackage’ function is essentially the equivalent of:

fileIn <mzpFileName>

and will return true if success or false if there is a failure, or a missing or invalid .mzp file, and it will
also return the directory that the package file were extracted to in the pass-by-reference
<extractDirVar> argument.
Example:
local extractDir = ““
if msZip.fileInPackage “foo.mzp” &extractDir then
(
-- extractDir contains the extracted-to directory name
...
)

msZip.unloadPackage <mzpFilename> &<exractDirVar> &<dropFileVar>

The ‘unloadPackage’ function performs an extract and executes all the file copying and moving
commands in any enclosed mzp.run file, but will not execute any scripts in the package. The
extractTo directory and any ‘drop’ command file found will be returned in the pass-by-reference
arguments.
Example:
local extractDir = ““, dropFile = ““
if msZip.unloadPackage’ “foo.mzp” &extractDir &dropFile then
(
-- extractDir contains the extracted-to directory name
-- dropFile contains any found drop file name (the path to extracted
location )
...
)

See Also
i-drop - drag and drop (p. 62)
 Additional Keyword Parameter On pickObject() forceListenerFocus: 127

version 4 MAXScript Language Improvements

Additional Keyword Parameter On pickObject() forceListenerFocus:

Topic: version 4 MAXScript Language Improvements/forceListenerFocus:
There is a new keyword parameter on pickObject() to control listener focus forcing.
The new parameter is forceListenerFocus: which takes a boolean value.
Defaults to true to retain existing semantics and backward compatibility.

See Also
Picking Scene Nodes By Hit (p. 1618)
RubberBanding in pickObject() Function (p. 136)

Affect Region Function

Topic: version 4 MAXScript Language Improvements/Language Improvements
<float> affectRegionVal <distance_float> <falloff_float> <pinch_float>
<bubble_float>
The standard affect region function, based on a distance and the three affect region
parameters (same as the editable mesh). This function is a cubic curve which returns 1 at
distance 0, 0 if distance is greater than falloff, and other values for distance between 0 and
falloff.
This is the function used inside the Affect_Region modifier. For the different editables, one of the
data channels is the selection weight. If you wanted to, you could use this function to calculate the
vertex selection weights on you own.

See Also
Affect Region : Modifier (p. 1103)
128 Chapter 1 | What’s New in 3ds max 4 MAXScript

“Apropos” and “ShowProperties” and now “Help” and “Show”

Topic: Magma MAXScript Language/Object Inspector Functions
To make scripting easier to teach and use everyday, a ScriptTool function for “Help” and “Show” has
been added.
So now typing Help “Box”, will show all the commands using the name BOX.
“Show” is the short way of typing ”ShowProperties”
Show $ --will show you the properties of the selected object and so on.

See Also
Class and Object Inspector Functions (p. 799)
Class and Object Inspector Functions Enhanced (p. 159)

BinStream for Binary Reading and Writing

Topic: version 4 MAXScript Language Improvements/Language Improvements
BinStream fopen <String fileName> <String mode>
Opens a file for reading or writing based on the mode parameter. This can either be “wb”
for Writing Binary or “rb” for Reading Binary. The function will return a BinStream value.
Boolean FClose <BinStream>
Close a BinStream value. Returns True if it successfully closed the BinStream.
Boolean fseek <BinStream> <Integer> <#seek_set | #seek_cur | #seek_end>
Move the file pointer to the specified location based off the seek parameter.
#seek_set - base off start of file.
#seek_cur - base off current position.
#seek_end - base off end of file.

Integer ftell <BinStream>

Returns the current file pointer position.
Boolean WriteByte <BinStream> <Integer> [#signed | #unsigned]
Writes a Integer to the file as one byte. Returns True if write was successful.
Boolean WriteShort <BinStream> <Integer> [#signed | #unsigned]
Writes a Integer to the file as two bytes. Returns True if write was successful.
Boolean WriteLong <BinStream> <Integer> [#signed | #unsigned]
Writes a Integer to the file as four bytes. Returns True if write was successful.
Boolean WriteFloat <BinStream> <Float>
Writes a Float to the file as four bytes. Returns True if write was successful.
Boolean WriteString <BinStream> <String>
Writes a string to the file. Returns True if write was successful.
Integer ReadByte <BinStream> [#signed | #unsigned]
Read a one byte value and return as an Integer.
 By Reference Parameter Passing 129

Integer ReadShort <BinStream> [#signed | #unsigned]

Read a two byte value and return as an Integer.
Integer ReadLong <BinStream> [#signed | #unsigned]
Read a four byte value and return as an Integer.
Float ReadFloat <BinStream>
Read a four byte value and return as an Float.
String ReadString <BinStream>
Read a string from the file.
Example:
f=fopen “c:\\test.bin” “wb”
WriteString f “String”
WriteByte f 64
WriteShort f 128
WriteLong f 256
WriteFloat f 512.0
WriteString f “gnirtS”
WriteLong f (ftell f)
fclose f
f=fopen “c:\\test.bin” “rb”
ReadString f
ReadByte f
ReadShort f
ReadLong f
ReadFloat f
ReadString f
ftell f
ReadLong f
fclose f

See Also
FileStream Values (p. 763)

By Reference Parameter Passing

Topic: version 4 MAXScript Language Improvements/Language Improvements
MAXScript has been extended to support by-reference parameter passing. This allows a reference to
be passed to a variable, property, or array element in the caller’s context as a parameter to a function
and any assignments to that parameter in the called function will be assigned directly to the caller’s
variable, property. or array element. This is often used as a mechanism for passing multiple results
back from a function.
To define by-reference parameters for a function, you prefix them with an ‘&’ character.
130 Chapter 1 | What’s New in 3ds max 4 MAXScript

Example:
function foo x y &z =
(
...
z = x * y
...
return true
)

Declares a function taking three parameters, x, y and z. The &z in the parameter list indicates
the z parameter is to be passed by-reference. To call this function, you provide a reference value
for the z parameter using the new ‘&‘ reference operator.
Example:
local var1, var2
...
var1 = foo 2 3 &var2
Calls the foo function with the arguments 2, 3 and &var2. The &var2 is a reference to
the var2 local variable. When the function is called, the z parameter in the body is a
reference to var2 local in the caller, and the
z = x * y
assignment in the body of foo will cause x * y to be assigned to the var2 local in the
caller. After
var1 = foo 2 3 &var2
var1 will contain true and var2 will contain x * y or 6.
Any number of by-reference parameters can be used and they can be keyword parameters if needed:
fn foo x y &z: = ...
called like this:
var1 = foo 2 3 z:&var2
The ‘&’ reference operator used to supply references in a call can be applied to any
<accessor> construct in MAXScript. These are:
variables (locals, globals, rollout locals, plug-in locals, etc.)
property access
array index
parameter (of a scripted plug-in)

Example:
p = [1, 2, 3]
foo 2 3 &p.x
would cause the x coordinate in the point to be passed by-reference and so after the call,
the value in p would be
[6, 2, 3]
 C++-style bracketing comments 131

Example:
a = #(1, 2, 3, 4, 5)
foo 2 3 &a[3]
would cause the 3rd element in the array to be passed by-reference and so after the
call, the value in a would be #(1, 2, 6, 4, 5)

Note:
This mechanism is used by the Function Publishing interface in MAXScript to support BY-REF
interface method parameters and results. Any parameter defined as by-ref (or with a type code
suffix _BR) in the published interface, requires an ‘&’ reference value.

See Also
Dereferencing Operator (p. 133)
Visible Class For ‘&’ Reference Values (p. 142)

C++-style bracketing comments

Topic: version 4 MAXScript Language Improvements/Language Improvements
C++-style bracketing can be used to comment out extended segments of code or add lengthy
comments. These comments begin with the two characters /* and end at the next */ (or end of file).
Example:
/* this is a long comment
blah blah
print “debug 1” -- code commented out
more comments
*/

You can also use this within a line to comment out a script fragment:
for i in 1 to 10 do ( /* messageBox “in loop”; */ frabulate i )

Note:
The /* and */ have to be adjacent characters. If you leave out the closing */ or make it * /, the rest of
the file will be commented out.

See Also
MAXScript Editor Commands (p. xlvi)
Source Code Layout (p. 580)
Source Code Layout and Continuation Lines (p. lvii)
132 Chapter 1 | What’s New in 3ds max 4 MAXScript

Coercion of bitArray to array and integer arrays to bitArrays

Topic: version 4 MAXScript Language Improvements/Language Improvements
Coercion of bitArray to array and integer arrays to bitArrays implemented.
<bitArray> as array
<integer array> as bitArray

Example:
a=#{1..5,10)
b=a as array
c=b as bitarray

If an element of the array cannot be coerced to an integer, and error is thrown

.numberSet and .isEmpty are read-only properties, which have been added to the BitArrayValue
class.
.numberSet

Return Value:
Returns the number of bits set
.isEmpty

Return Value:
Returns true if no bits are set and false if one or more bits are set.
Example:
a=#{1..5,10..20}
a.numberset --> 16
a.isEmpty --> false
a=#{}
a.numberset --> 0
a.isEmpty --> true

The ‘*’ operator has been added to bitArrays which performs an ‘AND’ operation:
<bitarray> * <bitarray> -- intersection (”AND” operation)

See Also
BitArray Values (p. 791)
Value Common Properties, Operators, and Methods (p. 714)
 Command line -U MAXScript startup scripts 133

Command line -U MAXScript startup scripts

Command line -U MAXScript startup scripts are run *after* MAX has completely booted and the
standard MAXScript stdscripts and scripts\startup scripts have been run.

See Also
Running Scripts from the Command Line (p. lvii)

Detecting Deleted Nodes

Topic: version 4 MAXScript Language Improvements/Language Improvements
<node> == undefined and <node> != undefined
In the above, when a node has been deleted return false and true, respectively.
Example:
if mynode != undefined and not isdeleted myNode do ...

See Also
Node Common Properties, Operators, and Methods (p. 820)

Dereferencing Operator
Topic: version 4 MAXScript Language Improvements/Language Improvements
Visible Class For ‘&’ Reference Values (p. 142)
A Function Published dereferencing prefix operator, *, has been added to MAXScript. This can be
used in conjunction with the new ‘&’ reference operator that was added to support pass-by-reference
arguments to functions and interface methods.
The ‘&’ operator is used to get a ‘reference’ to a variable or property or array element slot in
MAXScript. You can pass this reference in to a function that accepts by-reference arguments,
allowing its code to directly assign values to the referenced variable or property or array element,
thus supporting a kind of multiple-value return.
The new ‘*’ operator allows you to work with ‘&’ reference values anywhere in MAXScript code.
Therefore ‘dereference’ the reference and get the value in the slot or variable it is referring to and to
assign it to the referenced slot.
Examples:
ref = &$foo.pos
this puts a value into ref which is a reference to the .pos property in the scene object $foo.
Elsewhere in the code, you could use the new ‘*’ dereferencing operator to say:
$baz.pos = *ref
the ‘*’ dereferences the reference value in ref, essentially making this equivalent to:
$baz.pos = $foo.pos
you can also use this construct as a destination for an assignment:
134 Chapter 1 | What’s New in 3ds max 4 MAXScript

*ref = [10,0,0]
first dereferences the reference in ‘ref’ to $foo.pos and then assigns to that, effectively
setting $foo’s position.
In order to avoid ambiguity with the ‘*’ multiply operator, the precedence of the ‘*‘ dereferencing
operator is set at just lower than the function call and just higher than the ‘as’ coercion operator.
This means that if you want to send a dereferenced value into a function as an argument, you must
surround the dereferencing with parentheses, as in:
foo (*ref) x y z

Remember that reference values can be generated for variables, properties and array elements, as
Example:
&foo
&$box.position.x
&valArray[23]

The ‘*’ dereferencing operator is a moderately advanced feature in MAXScript that is often used to
allow very general purpose code to be written that uses references instead of actual objects so that it
can be applied to different kinds of objects and properties at different times.
Nested property access allowed in ‘&’ reference values in MAXScript. This allows constructs like:
r = &$foo.pos, and later *r.controller to mean $foo.pos.controller.

See Also
By Reference Parameter Passing (p. 129)

forceUpdate Function added to UVWUnwrap

Topic: version 4 MAXScript Language Improvements/Language Improvements
Unwrap UVW : Modifier (p. 1176)
A forceUpdate function added to MAXScript.
Right now when the user changes the topology Unwrap resets the mapping. If the forceUpdate is set
to true then the mapping will not be reset, but you can’t edit/see any mapping that makes sense.
This flag is for advance users that want to lock a mapping and then set the topology back down for
maximized viewport speed.
forceUpdate(BOOL update)

See Also
UVWUnwrap interfaces: (p. 568)
Unwrap UVW interfaces: (p. 530)
 hasProperty() function 135

hasProperty() function
Topic: version 4 MAXScript Language Improvements/Language Improvements

Prototype:
hasProperty <obj> <prop_name_or_pattern_string>

Return Value:
Returns true if the object has the given property.

See Also
Properties, Methods, Operators, and Literals (p. lxiv)

Improved the Performance of Iterating and Indexing the ‘selection’

and ‘$’ Object Sets
Topic: version 4 MAXScript Language Improvements/Language Improvements
Substantially improved the performance of iterating and indexing the ‘selection’ and ‘$’ object sets.
In prior versions, the whole scene was traversed looking for selected nodes when indexing, iterating
or snapshotting into an array, causing big delays in large scenes. Now, the ‘selection’ object set uses
direct access to the SDK explicit current selection set.

See Also
Node Common Properties, Operators, and Methods (p. 820)

Readable/Writable Checks
Topic: version 4 MAXScript Language Improvements/Language Improvements
MAXScript now does readable/writable checks and throws an error if you try to read from a
write-only file and vice versa. Some modes are read/write, such as “a+” “w+” and “r+”.

See Also
FileStream Values (p. 763)
136 Chapter 1 | What’s New in 3ds max 4 MAXScript

isValidNode
Topic: version 4 MAXScript Language Improvements/Language Improvements
isValidNode <var>
Returns true if <var> is a node value, and the node has not been deleted. False otherwise.

See Also
Detecting Deleted Nodes (p. 133)
Node Common Properties, Operators, and Methods (p. 820)

RubberBanding in pickObject() Function

Topic: version 4 MAXScript Language Improvements/Language Improvements
The pickObject() function in MAXScript now supports 2 new optional keyword arguments for
controlling the display of a rubber-banding line in the viewport during pick operations. The new
keywords are:
rubberBand:<point3>
rubberBandColor:<color>

If rubberBand: is supplied on the pickObject() call, it enables rubberbanding, with the given
<point3> as world-space coordinates for the start point of the rubber band. You can use the
rubberBandColor: argument to override the default line color of gray (color 128 128 128).
Example:
obj2 = pickObject rubberBand:obj1.pos rubberBandColor:yellow

See Also
Picking Scene Nodes By Hit (p. 1618)
Additional Keyword Parameter On pickObject() (p. 127)

SetDir
Topic: version 4 MAXScript Language Improvements/Language Improvements
SetDir <filetype_name> <string>
Sets the directory specified in string. Replicated in the Customize > Configure Paths dialog
for the specified file type.
 Shortcut system replaced 137

The valid <filetype_name> values are:

#autoback
#drivers
#export
#expression
#font
#help
#image
#import
#matlib
#maxroot
#maxstart
#plugcfg
#preview
#scene
#scripts
#sound
#startupScripts
#ui
#vpost

Returns true if successful, false if not. Does not check to see if <string> is a valid path. Any change
made through this function is immediately reflected in the 3dsmax.ini file and so is persistent. Use
with caution.

See Also
3ds max System Directories (p. 1625)

Shortcut system replaced

Topic: version 4 MAXScript Language Improvements/Language Improvements
The “shortcuts” feature in previous versions of MAXScript has been removed. In it’s place you can
use macro-recording of actions.
To determine how to invoke an action from MAXScript, you should go to the UI customization
dialog and put that action on a button, menu or keyboard shortcut. Then turn on macro recording
and execute the action.
The code that is emitted can be cut and pasted in to your script.
If you turn on macro recording and start using the menu, quad menu or toolbar, you’ll see code
emitted that looks like this
Example:
actionMan.executeAction 0 “59225” -- Manipulate Mode
This is code that will execute the same action as pressing the “Manipulate Mode” button.
The comment is also generated, and it uses the action’s tool tip. The parameters of
“actionMan.executeAction” are the integer ActionTableId of the table the action comes
138 Chapter 1 | What’s New in 3ds max 4 MAXScript

from, and the “persistent id” if the action. Actions exported from core all have persistent
ids that are fixed integers as a string.
Actions are accessible, all that you need to know are the ActionTableId and the persistent ID in order
to invoke the operation.

Note:
Certain actions emit much better code. If an action is exported using a function published action
table, then the code it emits calls that function. For example, if you bring up the “Plug-in Manager”
from the customize menu, the code emitted is:
Plug-in_Manager.Plug-inMgrAction.show ()
If the action comes from a macro script, which many of our actions do, the code looks like:
macros.run “Modifiers” “Bend”

See Also
Action Manager (p. 9)
Interface: actionMan (p. 353)

startObjectCreation()
Topic: version 4 MAXScript Language Improvements/Language Improvements
The startObjectCreation() function has been enhanced.
startObjectCreation <maxobjclass> [returnNewNodes:<flag>] [newNodeCallback:<fn>]

The values that can now be supplied to the optional ‘returnNewNodes:’ keyword argument are true,
false (the default) or #first. If ‘true’ is supplied, all of the nodes created, up until the current create
mode is exited, will be returned in an array. If #first is supplied, only the first node created is
returned, immediately after it is created. The function doesn’t wait for the create mode to be exited
by the user.
The optional ‘newNodeCallback:’ keyword argument can supply a scripted function of one
argument to the create mode that is started, such that the function will be called each time a node
is created with the new node as its argument. This is similar to supplying pickObject() filter
functions, although the return value of the newNodeCallback: function is ignored. Note that the
callback function is invoked immediately upon new node creation, *before* any base object is
installed in it, so *only* node-related properties can be accessed and changed during this callback.
Example:
fn setColor n = n.wireColor = red
startObjectCreation box newNodeCallback:setColor
would cause all new boxes created in the started create mode to have red wire color.
The ‘returnNewNodes:’ and ‘newNodeCallback:’ can both be supplied on the same call; the callback
will be called on each node, and they will be returned in an array as the result of the
startObjectCreation() function.
 Subanim Indexing Operator, [], on MAX Objects Now Takes Subanim Names 139

See Also
Create Panel (p. 1572)
Defining Macro Scripts (p. 1521)
Change Handlers and Callbacks (p. 1649)
callbacks const StructDef (p. 233)

Subanim Indexing Operator, [], on MAX Objects Now Takes

Subanim Names
Topic: version 4 MAXScript Language Improvements/Language Improvements
The subanim indexing operator, [], on MAX objects now takes subanim names as well as indexes.
These can be any expression that yields a string or name value. So, whereas in earlier releases, getting
at the position subAnim in a node require you to remember index 3 for the transform subanim and 1
for its position subanim, in other words
Example:
$foo[3][1] -- position within transform within node

Now you can use:

$foo[#transform][#position]

The names you can use are those seen in the track view or retrieved with the functions
getSubAnimName() or getSubAnimNames().

See Also
Indexed Access to Animatable Properties in 3D Studio MAX Objects (p. 806)

superclasses read-only global variable

Topic: version 4 MAXScript Language Improvements/Language Improvements
superclasses
A read-only global variable containing an array of the MAXSuperClass values
superclasses system Array #(MAXWrapper, MAXWrapper, node, ParamBlock, GeometryClass,
camera, light, shape, helper, System, ParamBlock2, ReferenceMaker, ReferenceTarget, modifier,
SpacewarpModifier, SpacewarpObject, BitmapIO, material, textureMap, UVGenClass, ...)

See Also
Utilities, Global Utilities and Render Element plug-ins (p. 161)
Scripted Plug-ins (p. 1538)
140 Chapter 1 | What’s New in 3ds max 4 MAXScript

Symbolic Pathnames
Topic: version 4 MAXScript Language Improvements/Language Improvements
Support for $<name> symbolic pathnames to all the places that filenames can be supplied for
opening things in MAXScript. Any filename you give to MAXScript in the following situations can
begin with a ‘$’ followed by one of the symbolic directory names below.
Example:
fileIn “$scripts\foo.ms”
will open the file “foo.ms” in the current MAX scripts directory. The situations in which
MAXScript honors ‘$’ symbolic directories are as follows:

Functions:
fileIn()
openBitmap()
createBitmap() in the fileName: parameter
render() in the outputFile: parameter

Compiler directives:
include <filename_string>

Rollouts:
any bitmap image file names for buttons, checkbuttons, bitmap
The following symbolic names are recognized:
$max - main MAX executable directory
$maps - first directory in Maps directory config
$scenes - scenes directory
$fonts - fonts directory
$imports - imports directory
$sounds - sounds directory
$matlibs - matlibs directory
$scripts - scripts
$startupScripts - auto-load startup scripts
$plug-ins - first in the Plug-ins directory config
$plugcfg - plugcfg
$images - images
$ui - UI
$macroScripts - macroScripts in UI directory
$web - web directory
$temp - system temp directory
Please note that these are similar to the 3D Studio MAX System Globals (p. 630) filetype names which
start with a “#”.

See Also
Zip-file Script Packages (p. 122)
3D Studio MAX System Globals (p. 630)
 System Information 141

System Information
Topic: version 4 MAXScript Language Improvements/Language Improvements
sysInfo const StructDef (p. 255)
sysInfo.windowsdir
A read only variable to get the Windows directory as a <string> value.
sysInfo.systemdir
A read only variable to get the Windows System directory as a <string> value.
sysInfo.windowsdir
A read only variable to get the Temp directory as a <string> value.
sysInfo.windowsdir
Variable to get/set the current directory as a <string> value.
sysInfo.username
A read only variable to get the user name as a <string> value.
sysInfo.computername
A read only variable to get the computer name as a <string> value.
sysInfo.cpucount
A read only variable to get the number of CPUs as a <integer> value.

See Also
System Tools (p. 112)

The Super Class ID and the Class ID

Plug-ins of all types create MAX system objects. These are not the 3D objects that appear in a scene,
but objects in the C++ sense. There are two IDs associated with each plug-in system object. These are
the Super Class ID and the Class ID. The Super Class ID specifies what super-class of MAX the plug-in
class is a sub-class of. The Class ID differentiates between the various plug-ins for a super-class.
MAXScript provides a method to generate a fresh random class ID each time you run it:
genClassID()

This method generates a random class ID similar to #(0x9b7ea231, 0xb6db86ef), and prints it to
Listener. You can just cut and paste this class ID into your script to use the generated ID.
MAX, and each plug-in falls into one of these predefined categories define the Super Class IDs. For
instance, all Texture Map plug-ins share the same Super Class ID of TEXMAP_CLASS_ID. Each
individual texture map plug-in has its own unique Class ID however. Thus, the Super Class ID
defines which kind of object it is, the Class ID uniquely identifies a specific plug-in class.
142 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
Scripted Plug-ins (p. 1538)
Scripted Custom Attributes (p. 45)
Menu Manager (p. 75)

validModifier() function
Topic: version 4 MAXScript Language Improvements/Language Improvements
The validModifier() function improved so that it will take a modifier class in place of a modifier to
preclude the need to create a modifier to do the test.
Prototype:
validModifier <node_or_node_collection> <mod_or_mod_class>

It is recommended that classes be used in RCMenus and macroScripts using validModifier() to reduce
resource usage.
Example:
if validModifier $ Edit_Mesh then ...

instead of:
if validModifier $ (Edit_Mesh()) then ...

The MAXScript isValidModifier function will check if it has been passed a modifier that doesn’t exist
at runtime. It returns false in this case. It uses the ClassEntry to determine the InputType() of the
modifier.

See Also
Node Common Properties, Operators, and Methods (p. 820)
Modifier Common Properties, Operators, and Methods (p. 1096)

Visible Class For ‘&’ Reference Values

Topic: version 4 MAXScript Language Improvements/Language Improvements
Dereferencing Operator (p. 133)
In prior releases, the class of a reference value (as returned by the ‘&’ prefix operator) was shown as
Value. It is now the class ‘ValueRef’.
Example:
ref = &foo.name
classOf ref -> ValueRef
if classOf x == ValueRef then y = *x
Nested property accessing allowed in ‘&’ reference values in MAXScript.
This allows constructs like: r = &$foo.pos, and later *r.controller to mean $foo.pos.controller.
 List Controller 143

See Also
By Reference Parameter Passing (p. 129)
Dereferencing Operator (p. 133)

Controllers

List Controller
Topic: version 4 MAXScript Language Improvements/Controllers
The List controller combines multiple controllers into a single effect. It is a compound controller
with tools for managing the order in which its internal controllers are calculated. Controllers are
evaluated in a top to bottom order; the controller at the top of the list is evaluated first.
When you assign a List controller to a parameter, the current controller is moved one level below
the List controller; it becomes the first controller in the list. A second parameter is added below the
List controller and is named Available. This is an empty placeholder for the next controller you add
to the list.
ListCtrl const StructDef (p. 238)
Example:
lst = $.pos.controller -- if this is a list controller
showInterfaces lst -- interface name is “list”
Methods:
lst.getCount()
Returns the count function.
lst.count
Returns count property (read only).
lst.SetActive <index>
Set active function
lst.GetActive()
Get active function
lst.active
Get/set active property.
lst.cut <index>
Cut the indexed sub-controller
lst.paste <index>
Paste clip to index location.
lst.delete <index>
Delete the indexed sub-controller.
lst.setName <index> <string>
Sets the name of the indexed sub-controller.
144 Chapter 1 | What’s New in 3ds max 4 MAXScript

lst.getName <index>
Gets the name of the indexed sub-controller.
Example:
b = Box lengthsegs:1 widthsegs:1 heightsegs:1 length:65.7611 width:32.0211
height:39.8261 pos:[-15.6972,-84.9615,0] isSelected:on
b.pos.controller = position_list ()
b.pos.controller.Available.controller = Position_XYZ ()
b.pos.controller.Available.controller = tcb_position ()
b.pos.controller.Available.controller = bezier_position ()
lst = b.pos.controller -- the list controller
showInterfaces lst-- interface name is “list”
lst.getCount() -- count function
lst.count-- count property (read only)
lst.SetActive 3 -- set active function
lst.GetActive() -- get active function
lst.active-- active property
lst.cut 2-- cut the second sub-controller
lst.paste 1-- paste it to the top of the list
lst.delete lst.count -- delete the second to last sub-controller
lst.setName 2 “My Bezier” -- sets the name of the second sub-controller
lst.getName 2-- gets the name of the sub-controller

See Also
List Controllers (p. 1317)

mapKeys() method
Topic: version 4 MAXScript Language Improvements/Controllers
The mapKeys() method gives access to the SDK function Control::MapKeys().
The form is:
mapKeys <max_object> (<map_struct> | <fn> <arg>) [#allKeys] [#selection] *
[#slide] [#rightToLeft]

This is like other recursive controller key functions (p. 1294) in MAXScript, such as moveKeys,
deleteKeys, etc., which operate on all the keys in nested controllers in the object you supply. The
thing to be mapped is either a scripted function and argument pair or a struct instance. If a function
is supplied, it should take two arguments, the time value to be mapped and the <arg> from the
mapKeys() call, and pass back the mapped time.
Example:
fn bumpTime t delta = t + delta
mapKeys $foo bumpTime 23 #selection
will add 23 to all the selected keys in controllers within $foo.
If a struct is supplied, it should have at least a ‘map’ member function that takes a time to be mapped
and returns the mapped time. The advantage of a struct is that it is a way to set up complex
parameterized mapping by having as many data members as needed to hold the parameters.
 moveKeys function 145

Example:
struct mapper
(
scale,
offset,
fn map t = return t * scale * offset
)
mapKeys $foo (mapper scale:0.5 offset:10)

will execute a combination time scale and offset in one pass.

See Also
Time and Key Functions on Object Hierarchies (p. 1299)
Nested Object Controller Functions (p. 814)
Controller Time Functions (p. 1292)
Controller Key Functions (p. 1294)
MAXKeyArray Values (p. 793)

moveKeys function
Topic: version 4 MAXScript Language Improvements/Controllers
moveKeys <key_array> <time> [ #selection ]
Moves all keys by the time given. If #selection is specified, move the current selection otherwise
move all keys.
moveKeys function only works on track properties, .controller and .track. It is not defined on the
keys virtual array.
Example:
moveKeys $box01.pos.controller 5
or:
moveKeys $box01.pos.track 5

See Also
Time and Key Functions on Object Hierarchies (p. 1299)
Nested Object Controller Functions (p. 814)
Controller Time Functions (p. 1292)
Controller Key Functions (p. 1294)
MAXKeyArray Values (p. 793)
146 Chapter 1 | What’s New in 3ds max 4 MAXScript

Geometry, Modifiers, Space Warps

Hose - superclass: GeometryClass

Hose - superclass: GeometryClass; super-superclass:node - 27:0 - classID: #(1777953373, 593249034)
The Hose object is a flexible object that you can connect between two objects, whereupon it reacts
to their movement. It’s similar to Spring, but does not have dynamics properties. You can specify the
overall diameter and length of the hose, the number of turns, and the diameter and shape of its
“wire”.
Constructor:
Hose ...

Properties:
<Hose>.End_Placement_Method Integer default: 1 -- integer
<Hose>.Generate_Mapping_Coordinates Integer default: 0 -- integer
Sets up required coordinates for applying mapped materials to the hose. Default=off.
<Hose>.Hose_Height Float default: 1.0 -- animatable;
float
Use this field/spinner to set the straight-line height or length of the hose when it is not
bound. This is not the actual length of the hose. Available only when Free Hose is chosen.
<Hose>.Segments_Along_Hose Integer default: 45 -- animatable;
integer
The total number of segments in the hose’s length. Increase this setting for a smooth
profile when the hose is curved. Default=16.
<Hose>.Smooth_Spring Integer default: 0 -- integer
Choose one of the following smoothing options:
All: The entire hose is smoothed.
Sides: Smoothing is applied along the length of the hose but not around its circumference.
None: No smoothing is applied.
Segments: Smoothing is applied only on the inner section of the hose.
<Hose>.Renderable_Hose Integer default: 1 -- integer
When on, the hose is rendered using the specified settings. When off, the hose is not
rendered. Default=on.
<Hose>.Hose_Cross_Section_Type Integer default: 0 -- integer
Sets a circular cross-section.
Lets you specify different settings for width and depth.
Similar to Rectangular Hose, but rounds one side for a D-shaped cross-section.
<Hose>.Round_Hose_Diameter Float default: 0.2 -- animatable;
float
The maximum width of the hose at the ends.
 Hose - superclass: GeometryClass 147

<Hose>.Round_Hose_Sides Integer default: 8 -- animatable;

integer
The number of sides of the hose. A Sides setting of 3 gives a triangular cross-section; 4 gives
a square cross-section; and 5 gives a pentagonal cross-section. Increase Sides for a circular
cross-section. Default=6.
<Hose>.Rectangular_Hose_Width Float default: 0.2 -- animatable;
float
The width of the hose.
<Hose>.Rectangular_Hose_Depth Float default: 0.2 -- animatable;
float
The height of the hose.
<Hose>.Rectangular_Hose_Fillet_Size Float default: 0.0 -- animatable;
float
The amount by which the cross-section corners are rounded. For this to be visible, Fillet
Segs must be set to 1 or higher. Default=0.
<Hose>.Rectangular_Hose_Fillet_Segs Integer default: 0 -- animatable;
integer
The number of segments across each filleted corner. A Fillet Segs setting of 1 cuts the
corner straight across; use higher settings for rounded corners. Default=0.
<Hose>.Rectangular_Hose_Section_Rotation Float default: 0.0 -- animatable;
angle; Controller Scaling: (1 : 57.2958)
The orientation of the hose along its long axis. Default=0.
<Hose>.D_Section_Hose_Width Float default: 0.2 -- animatable;
float
The width of the hose.
<Hose>.D_Section_Hose_Depth Float default: 0.2 -- animatable;
float
The height of the hose.
<Hose>.D_Section_Hose_Fillet_Size Float default: 0.0 -- animatable;
float
The amount by which the two cross-section corners opposite the rounded side are
rounded. For this to be visible, Fillet Segs must be set to 1 or higher. Default=0.
<Hose>.D_Section_Hose_Fillet_Segs Integer default: 0 -- animatable;
integer
The number of segments across each filleted corner. A Fillet Segs setting of 1 cuts the
corner straight across; use higher settings for rounded corners. Default=0.
<Hose>.D_Section_Hose_Round_Segs Integer default: 8 -- animatable;
integer
The number of segments on the rounded side. Increase for a smoother profile. Default=4.
<Hose>.D_Section_Hose_Section_Rotation Float default: 0.0 -- animatable;
angle; Controller Scaling: (1 : 57.2958)
The orientation of the hose along its long axis. Default=0.
148 Chapter 1 | What’s New in 3ds max 4 MAXScript

<Hose>.Flex_Section_Enabled Integer default: 1 -- integer

When on, lets you set the following four parameters for the central, flexible section of the
hose. When off, the hose’s diameter is uniform throughout its length.
<Hose>.Flex_Section_Start Float default: 10.0 -- animatable;
percentage; Controller Scaling: (1 : 100.0)
The percentage of the hose length from the starting extremity of the hose at which the flex
section begins. By default, the starting end of the hose is the end at which the object pivot
appears. Default=10%.
<Hose>.Flex_Section_Stop Float default: 90.0 -- animatable;
percentage; Controller Scaling: (1 : 100.0)
The percentage of the hose length from the end extremity of the hose at which the flex
section begins. By default, the end extremity of the hose is opposite the end at which the
object pivot appears. Default=90%.
<Hose>.Flex_Cycle_Count Integer default: 5 -- animatable;
integer
The number of corrugations in the flex section. The number of visible cycles is limited by
the number of segments; if Segments isn’t high enough to support the number of cycles,
then not all cycles will appear. Default=10.
Tip: To set the appropriate number of segments, first set Cycles, and then increase
Segments until the number of visible cycles stops changing.
<Hose>.Flex_Section_Diameter Float default: -20.0 -- animatable;
percentage; Controller Scaling: (1 : 100.0)
The relative width of the “outside” parts of the cycles. At negative settings, these are
smaller than the overall hose diameter. At positive settings, these are larger than the
overall hose diameter. Default=-20%. Range=-50% to 500%.
<Hose>.Top_Tension Float default: 100.0 -- animatable;
float
Determines the arc of the hose near the Top object. Lower the tension to decrease the arc,
and raise the tension to increase the arc. Default=100.
<Hose>.Bottom_Tension Float default: 100.0 -- animatable;
float
Determines the arc of the hose near the Bottom object. Lower the tension to decrease the
arc, and raise the tension to increase the arc. Default=100.

See Also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Drag - superclass: SpacewarpObject 149

Drag - superclass: SpacewarpObject

Drag - superclass: SpacewarpObject; super-superclass:node - 29:0 - classID: #(1173650369,
674975258)
The Drag space warp is a particle motion damper that reduces particle velocity by a specified amount
within a specified range. The damping can be applied linearly, spherically, or cylindrically. Drag is
useful for simulating wind resistance, transfers into dense media (like water), impacts with force
fields, and other, similar situations.
With each damping type, you can control the damping effect along several vectors. The damping is
also affected by particle system settings, such as speed.

Constructor:
Drag ...

Properties:
<Drag>.‘time on’ Integer default: 0 -- integer; Time_On
The frame numbers at which the space warp becomes active and becomes inactive.
<Drag>.‘time off’ Integer default: 16000 -- animatable; integer;
Time_Off
The frame numbers at which the space warp becomes active and becomes inactive.
<Drag>.symmetry Integer default: 0 -- radio button number;
Damping_Symmetry
This group lets you choose Linear Damping, Spherical Damping, or Cylindrical Damping,
plus a set of parameters for each.
<Drag>.dampingx Float default: 5.0 -- animatable; percentage;
X_Damping; Controller Scaling: (1 : 100.0)
Specifies the percentage of particle motion along the local Drag space warp axis that’s
affected by the damping.
<Drag>.rangex Float default: 100.0 -- animatable; float; X_Range
Sets the thickness of the “range plane,” or the infinite plane perpendicular to the specified
axis. Takes effect only when Unlimited Range is turned off.
<Drag>.falloffx Float default: 1000.0 -- animatable; float;
X_Falloff
Specifies the distance beyond the X, Y, or Z Range within which Linear Damping is
applied. Damping is strongest at the Range distance, decreases linearly out to the limit of
the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range,
it is measured from the center of the icon, and always has a minimum value equal to the
Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingy Float default: 0.0 -- animatable; percentage;
Y_Damping; Controller Scaling: (1 : 100.0)
Specifies the percentage of particle motion along the local Drag space warp axis that’s
affected by the damping.
150 Chapter 1 | What’s New in 3ds max 4 MAXScript

<Drag>.rangey Float default: 100.0 -- animatable; float; Y_Range

Sets the thickness of the “range plane,” or the infinite plane perpendicular to the specified
axis. Takes effect only when Unlimited Range is turned off.
<Drag>.falloffy Float default: 1000.0 -- animatable; float;
Y_Falloff
Specifies the distance beyond the X, Y, or Z Range within which Linear Damping is
applied. Damping is strongest at the Range distance, decreases linearly out to the limit of
the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range,
it is measured from the center of the icon, and always has a minimum value equal to the
Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingz Float default: 0.0 -- animatable; percentage;
Z_Damping; Controller Scaling: (1 : 100.0)
Specifies the percentage of particle motion along the local Drag space warp axis that’s
affected by the damping.
<Drag>.rangez Float default: 100.0 -- animatable; float; Z_Range
Sets the thickness of the “range plane,” or the infinite plane perpendicular to the specified
axis. Takes effect only when Unlimited Range is turned off.
<Drag>.falloffz Float default: 1000.0 -- animatable; float;
Z_Falloff
Specifies the distance beyond the X, Y, or Z Range within which Linear Damping is
applied. Damping is strongest at the Range distance, decreases linearly out to the limit of
the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range,
it is measured from the center of the icon, and always has a minimum value equal to the
Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingr Float default: 5.0 -- animatable; percentage;
Radial_Damping; Controller Scaling: (1 : 100.0)
Radial specifies the percentage of particle motion toward or away from the center of the
Drag icon that’s affected by the damping. Tangential specifies the percentage of particle
motion across the body of the Drag icon that’s affected by the damping.
<Drag>.ranger Float default: 100.0 -- animatable; float;
Radial_Range
Specifies the distance from the center of the Drag icon, in system units, within which
damping is in full effect. Takes effect only when Unlimited Range is turned off.
<Drag>.falloffr Float default: 1000.0 -- animatable; float;
Radial_Falloff
Specifies the distance beyond the Radial/Tangential Range within which Linear Damping
is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of
the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range,
it is measured from the center of the icon, and always has a minimum value equal to the
Range value. Takes effect only when Unlimited Range is turned off.
 Drag - superclass: SpacewarpObject 151

<Drag>.dampinggc Float default: 0.0 -- animatable; percentage;

Tangential_Damping; Controller Scaling: (1 : 100.0)
Radial specifies the percentage of particle motion toward or away from the center of the
Drag icon that’s affected by the damping. Tangential specifies the percentage of particle
motion across the body of the Drag icon that’s affected by the damping.
<Drag>.rangegc Float default: 100.0 -- animatable; float;
Tangential_Range
Specifies the distance from the center of the Drag icon, in system units, within which
damping is in full effect. Takes effect only when Unlimited Range is turned off.
<Drag>.falloffgc Float default: 1000.0 -- animatable; float;
Tangential_Falloff
Specifies the distance beyond the Radial/Tangential Range within which Linear Damping
is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of
the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range,
it is measured from the center of the icon, and always has a minimum value equal to the
Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingrc Float default: 5.0 -- animatable; percentage;
Radial_Damping; Controller Scaling: (1 : 100.0)
Damping controls the percentage of particle motion toward or away from the center of the
circular portion of the icon (Radial), across the radial vector (Tangential), or along the
length of the icon’s long axis (Axial) that’s affected by the damping, on a per-frame basis.
<Drag>.rangerc Float default: 100.0 -- animatable; float;
Radial_Range
Specifies the distance from the center of the Drag icon, in system units, within which
Radial and Axial damping are in full effect. Range also specifies the thickness of the
infinite plane that governs the range of Axial damping. Takes effect only when Unlimited
Range is turned off.
<Drag>.falloffrc Float default: 1000.0 -- animatable; float;
Radial_Falloff
Specifies the distance beyond the Radial/Tangential/Axial Range within which Linear
Damping is applied. Damping is strongest at the Range distance, decreases linearly out to
the limit of the Falloff, and has no effect beyond that. While Falloff is effected only
beyond the Range, it is measured from the center of the icon, and always has a minimum
value equal to the Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingc Float default: 0.0 -- animatable; percentage;
Tangential_Damping; Controller Scaling: (1 : 100.0)
Damping controls the percentage of particle motion toward or away from the center of the
circular portion of the icon (Radial), across the radial vector (Tangential), or along the
length of the icon’s long axis (Axial) that’s affected by the damping, on a per-frame basis.
152 Chapter 1 | What’s New in 3ds max 4 MAXScript

<Drag>.rangec Float default: 100.0 -- animatable; float;

Tangential_Range
Specifies the distance from the center of the Drag icon, in system units, within which
Radial and Axial damping are in full effect. Range also specifies the thickness of the
infinite plane that governs the range of Axial damping. Takes effect only when Unlimited
Range is turned off.
<Drag>.falloffc Float default: 1000.0 -- animatable; float;
Tangential_Falloff
Specifies the distance beyond the Radial/Tangential/Axial Range within which Linear
Damping is applied. Damping is strongest at the Range distance, decreases linearly out to
the limit of the Falloff, and has no effect beyond that. While Falloff is effected only
beyond the Range, it is measured from the center of the icon, and always has a minimum
value equal to the Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingax Float default: 0.0 -- animatable; percentage;
Axial_Damping; Controller Scaling: (1 : 100.0)
Damping controls the percentage of particle motion toward or away from the center of the
circular portion of the icon (Radial), across the radial vector (Tangential), or along the
length of the icon’s long axis (Axial) that’s affected by the damping, on a per-frame basis.
<Drag>.rangeax Float default: 100.0 -- animatable; float;
Axial_Range
Specifies the distance from the center of the Drag icon, in system units, within which
Radial and Axial damping are in full effect. Range also specifies the thickness of the
infinite plane that governs the range of Axial damping. Takes effect only when Unlimited
Range is turned off.
<Drag>.falloffax Float default: 1000.0 -- animatable; float;
Axial_Falloff
Specifies the distance beyond the Radial/Tangential/Axial Range within which Linear
Damping is applied. Damping is strongest at the Range distance, decreases linearly out to
the limit of the Falloff, and has no effect beyond that. While Falloff is effected only
beyond the Range, it is measured from the center of the icon, and always has a minimum
value equal to the Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.rangeless BooleanClass default: true -- boolean; Unlimited_Range
<Drag>.iconsize Float default: 10.0 -- float; Icon_Size
Specifies the size of the icon.
Example:
Drag time_on:0 time_off:10 symmetry:0 dampingx:5 rangex:100 falloffx:1000
dampingy:0 rangey:100 falloffy:1000 dampingz:0 rangez:100 falloffz:1000 dampingr:5
ranger:100 falloffr:1000 dampinggc:0 rangegc:100 falloffgc:1000 dampingrc:5
rangerc:100 falloffrc:1000 dampingc:0 rangec:100 falloffc:1000 dampingax:0
rangeax:100 falloffax:1000 rangeless:on pos:[-16.2008,-105.647,0] isSelected:on
iconSize:13.7761

See Also
Modifier and SpacewarpModifier Types (p. 1100)
 MultiRes - superclass: modifier 153

MultiRes - superclass: modifier

MultiRes - superclass: modifier; super-superclass:MAXWrapper - 10:0 - classID: #(1788759147,
1229407453)
The MultiRes modifier reduces the memory overhead needed to render models by decreasing the
number of vertices and polygons. This is useful not only within 3ds max but for game and Web
content creators who export models for use outside of MAX. MultiRes offers several advantages over
the Optimize modifier, including faster operation and the ability to specify reduction as an exact
percentage or vertex count.
Constructor:
MultiRes ...

Properties:
<MultiRes>.Vtx_Count Integer default: 0 -- animatable;
integer
The total number of vertices in the modified object. Use this control to set the maximum
number of vertices in the output mesh. Adjusting this setting alters the Percent value
as well.
<MultiRes>.Vertex_Percentage Float default: 100.0 --
animatable; float
The modified object’s vertex count as a percentage of the overall number of vertices in the
original mesh. Adjusting this setting alters the Count value as well.
Note: After you type in a specific percentage, such as 30, you might find that the software
changes the value to a slightly lower one, such as 29.971. This is due to the relationship
between the overall number of vertices in the model and the percentage calculation. It is
not a bug, but simply the closest solution to your request.
<MultiRes>.Vertex_Merging BooleanClass default: false -- boolean
When on, lets MultiRes merge vertices between discrete elements in a model.
For example, if you apply MultiRes to a teapot, which comprises four separate elements,
and turn on Vertex Merging, as you adjust the vertex resolution, the separate components
will meld together into one contiguous lower-resolution object.
To control Vertex Merging, you can set a Merge Threshold. This value determines the
3ds max unit distance within which to merge elements.
<MultiRes>.Threshold Float default: 0.0 -- float
This spinner value sets the maximum distance in 3ds max units between vertices in order
for those vertices to be considered for merging. Once this threshold is achieved, then the
vertices between elements will be welded together as the mesh is reduced in complexity.
Note: To eliminate only coincident vertices, set Merge Threshold to 0.0. This is similar to
the Weld Vertex function.
154 Chapter 1 | What’s New in 3ds max 4 MAXScript

<MultiRes>.Merge_Within BooleanClass default: false -- boolean

When on, MultiRes merges the boundaries of adjacent elements and vertices within
elements. Many objects can contain multiple groups of vertices that don’t share
connectivity. A simple example of this is the Teapot object. It comprises four different
elements: the body, the handle, the spout, and the lid. Normally, MultiRes optimizes each
discrete element in a mesh on its own.
The default behavior of the Vertex Merging option is to merge vertices between elements.
Turning on Within Mesh? causes vertices within elements to be merged as well.
<MultiRes>.Boundary_Metric BooleanClass default: false -- boolean
When on, MultiRes preserves materials assigned to the selected model. The material
boundaries defined by Material IDs are retained as long as possible, and are the last to be
eliminated at low vertex counts. Default=off.
<MultiRes>.Maintain_Base_Vertices BooleanClass default: false -- boolean
When on, overrides the MultiRes optimization algorithms and preserves any vertices
selected at the MultiRes Vertex sub-object level as “critical” ones. Use this feature to retain
critical features of an object or character such as its fingers or claws, or other geometry that
might become unrecognizable if reduced too severely.
To select vertices for use with this option, use the MultiRes Vertex sub-object level. To
access this level, first go to the modifier stack display and click the plus-sign icon next to
the MultiRes modifier. This opens up its hierarchy, which consists of the single Vertex sub-
object level. Next, click the Vertex entry. The MultiRes vertices appear on the mesh as blue
dots. You can select these using any standard interactive method, but you cannot
transform them.
Important: After selecting MultiRes sub-object vertices with Maintain Base Vertices turned
on, re-generate the mesh before changing the vertex resolution.
In the following illustration, the clown started out as a high-resolution mesh. All of the
MultiRes vertices in the right half were selected, Maintain Base Vertices was turned on, and
then the vertices were reduced.
{mrm_clown.bmp}
<MultiRes>.Multiple_Normals_Per_Vertex BooleanClass default: true -- boolean
When on, lets MultiRes assign multiple normals for each vertex. By default, MultiRes
generates a single normal per vertex.
If multiple normals are generated, they are applied as the vertex resolution is decreased
and increased.
When the Multiple Normals Per Vertex option is checked, the MultiRes modifier generates
normal updates when the geometry surrounding a vertex changes. You must specify a
crease angle in degrees (0.0 - 180.0). The crease angle is the angle between the face normals.
It is used to decide when a normal should be shared across an edge between two faces.
For example, in a plane defined as a mesh grid of 10 x 10 faces, any two adjacent faces
have a crease angle of zero. In a cube, adjacent faces have a crease angle of 90 degrees. In
 MultiRes - superclass: modifier 155

general, crease angles approaching 0 yield smoother shading. Crease angles approaching
180 yield more visible corners.
<MultiRes>.Crease_Angle Float default: 75.0 -- float
The value of the crease necessary in order to generate multiple normals. Available only
when Multiple Normals Per Vertex is on.
The optimal crease angle depends on the model; set it interactively and check the viewport
and rendered images for shading effects. While use of multiple normals per vertex enables
more accurate shading, it can require more internal data.
<MultiRes>.Generate BooleanClass default: false -- boolean
Applies the current MultiRes settings to the modified object. When you first apply
MultiRes to an object, it must initialize its mesh-optimizing algorithm; you are prompted
by the modifier to “Generate when ready”.
Note: When working with complex meshes, the initial analysis may take a little while.
During this time, MultiRes displays a special cursor to indicate it is working. Progress is
indicated on this cursor by the movement of the gray area from top to bottom. To cancel
this process, press ESC.
Example:
modPanel.addModToSelection(MultiRes())
$.modifiers[#MultiRes].Vtx_Count = 482
$.modifiers[#MultiRes].Vertex_Percentage = 100
$.modifiers[#MultiRes].Vertex_Percentage = 99
$.modifiers[#MultiRes].Vtx_Count = 476
$.modifiers[#MultiRes].Vertex_Percentage = 98.7552
$.modifiers[#MultiRes].Vertex_Merging = on
$.modifiers[#MultiRes].Threshold = 0.01
$.modifiers[#MultiRes].Merge_Within = on
$.modifiers[#MultiRes].Boundary_Metric = on
$.modifiers[#MultiRes].Maintain_Base_Vertices = on
$.modifiers[#MultiRes].Crease_Angle = 75.75

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
156 Chapter 1 | What’s New in 3ds max 4 MAXScript

Vortex - superclass: SpacewarpObject

Vortex - superclass: SpacewarpObject; super-superclass:node - 19:0 - classID: #(217851359,
1867456353)
The Vortex space warp applies a force to particle systems, spinning them through a whirling vortex,
and then moving them down a long, thin spout or vortex well. Vortex is useful for creating black
holes, whirlpools, tornadoes, and other funnel-type objects.
The space warp settings let you control the vortex shape, the well characteristics, and rate and range
of particle capture. The shape of the vortex is also affected by particle system settings, such as speed.
Constructor
Vortex ...

Properties:
<Vortex>.‘time on’ Integer default: 0 -- integer; Time_On
The frame numbers at which the space warp becomes active and becomes inactive.
<Vortex>.‘time off’ Integer default: 16000 -- animatable;
integer; Time_Off
The frame numbers at which the space warp becomes active and becomes inactive.
<Vortex>.axialstrength Float default: 0.1 -- animatable; float;
Axial_Drop_Strength
Specifies how quickly particles move in the direction of the drop axis.
<Vortex>.axialrange Float default: 100.0 -- animatable;
float; Axial_Range
The distance from the center of the Vortex icon, in system units, at which Axial Damping
has its full effect. Takes effect only when Unlimited Range is turned off.
<Vortex>.axialfalloff Float default: 1000.0 -- animatable;
float; Axial_Falloff
Specifies the distance beyond the Axial Range within which Axial Damping is applied.
Axial Damping is strongest at the Range distance, decreases linearly out to the limit of the
Axial Falloff, and has no effect beyond that. Takes effect only when Unlimited Range is
turned off.
<Vortex>.axialdamping Float default: 5.0 -- animatable;
percentage; Axial_Damping; Controller Scaling: (1 : 100.0)
Controls the degree to which particle motion parallel to the drop axis is restrained per
frame. Default=5.0. Range=0 to 100.
For subtle effects, use values of less than 10%. For more overt effects, try using higher
values that increase to 100% over the course of a few frames.
<Vortex>.rotationstrength Float default: 0.5 -- animatable; float;
Orbital_Speed_Strength
Specifies how quickly the particles rotate.
 Vortex - superclass: SpacewarpObject 157

<Vortex>.rotationrange Float default: 100.0 -- animatable;

float; Orbital_Range
The distance from the center of the Vortex icon, in system units, at which Orbital
Damping has its full effect. Takes effect only when Unlimited Range is turned off.
<Vortex>.rotationfalloff Float default: 1000.0 -- animatable;
float; Orbital_Falloff
Specifies the distance beyond the Orbital Range within which Orbital Damping is applied.
Orbital Damping is strongest at the Range distance, decreases linearly out to the limit of
the Orbital Falloff, and has no effect beyond that. Takes effect only when Unlimited Range
is turned off.
<Vortex>.rotationdamping Float default: 5.0 -- animatable;
percentage; Orbital_Damping; Controller Scaling: (1 : 100.0)
Controls the degree to which orbital particle motion is restrained per frame. Smaller values
produce a wide spiral, while larger values produce a thin spiral. Default=5.0. Range=0
to 100.
<Vortex>.radialstrength Float default: 0.5 -- animatable; float;
Radial_Pull_Strength
Specifies the distance from the drop axis at which the particles rotate.
<Vortex>.radialrange Float default: 100.0 -- animatable;
float; Radial_Range
The distance from the center of the Vortex icon, in system units, at which Radial Damping
has its full effect. Takes effect only when Unlimited Range is turned off.
<Vortex>.radialfalloff Float default: 1000.0 -- animatable;
float; Radial_Falloff
Specifies the distance beyond the Radial Range within which Radial Damping is applied.
Radial Damping is strongest at the Range distance, decreases linearly out to the limit of the
Radial Falloff, and has no effect beyond that. Takes effect only when Unlimited Range is
turned off.
<Vortex>.radialdamping Float default: 5.0 -- animatable;
percentage; Radial_Damping; Controller Scaling: (1 : 100.0)
Controls the degree to which Radial Pull is restrained per frame. Default=5.0. Range=0
to 100.
<Vortex>.taperstrength Float default: 100.0 -- animatable;
float; Taper_Length
Controls the shape of the vortex. Low values create a vortex with a wide, flared mouth,
while high values create a vortex with nearly vertical sides. Default=100. Range=1.0 to 4.0.
<Vortex>.tapershape Float default: 1.0 -- animatable; float;
Taper_Curve
Controls the length of the vortex, as well as its shape. Lower settings give you a “tighter”
vortex, while higher settings give you a “looser” vortex. Default=100.
<Vortex>.direction Integer default: 0 -- radio button number
Determines whether particles rotate clockwise or counterclockwise.
158 Chapter 1 | What’s New in 3ds max 4 MAXScript

<Vortex>.rangeless BooleanClass default: true -- boolean;

Unlimited_Range
When on, Vortex exerts full damping strength over an unlimited range. When off, the
Range and Falloff settings take effect.
<Vortex>.iconsize Float default: 10.0 -- float; Icon_Size
Specifies the size of the icon.
Example:
Vortex ‘time on’:0 ‘time off’:16000 axialstrength:0.1 axialrange:100
axialfalloff:1000 axialdamping:5 rotationstrength:0.5 rotationrange:100
rotationfalloff:1000 rotationdamping:5 radialstrength:0.5 radialrange:100
radialfalloff:1000 radialdamping:5 taperstrength:100 tapershape:1 direction:0
rangeless:on pos:[32.5437,-58.2321,0] isSelected:on iconSize:25.8103

See Also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Keys
Bezier Keys inTangentLength and outTangentLength
Topic: version 4 MAXScript Language Improvements/Keys
There are 2 additional properties in MAXScript for bezier keys .inTangentLength and
.outTangentLength. These are the handles’ magnitude in frames.
There is a new check box to the key property/Master Point control dialog found in the Motion Panel.
It is called Free Handle. When Free Handle is checked, the user can move the horizontal handle
where ever s/he feels. Otherwise, s/he is constrained, to prevent discontinuities.
Correspondingly, there is a new bezier key property called .freeHandle that implements the
functionality described above.
Note:
There are a fair number of classes that don’t implement the showproperties method. MAXKey is one
of them. getPropNames is not implemented for it either.

See Also
MAXKey Values (p. 767)
MAXKeyArray Values (p. 793)
MAXKey Common Properties, Operators, and Methods (p. 768)
Working with MAXKey Values (p. 769)
 Class and Object Inspector Functions Enhanced 159

Object Inspector Functions

Class and Object Inspector Functions Enhanced

Topic: version 4 MAXScript Language Improvements/Object Inspector Functions Enhanced
Interfaces (p. 67)
Core Interfaces (p. 70)
Other Interfaces (p. 71)
showInterfaces {<maxwrapper> | <maxclass> | node} [ to:<stream> ]

where <maxwrapper> is the 3ds max object to be inspected

<maxclass> is the 3ds max class to be inspected
and the optional to:<stream> keyword argument specifies a Stream Value to output the
display to.
When the 3ds max entity specified is a node (for example $box01), this function only displays the
Interfaces of the base object. It does not show the Interfaces of the transform controllers, modifiers,
or materials applied to the object. To display the Interfaces for one of these objects, that object must
be specified as the 3ds max entity.
As a special case, you can also call showInterfaces on the superclass ‘Node’ to display the interfaces
that are common to all scene nodes.
The display of interface information is divided into three sections: Properties, Methods, and
Actions. In the Properties section, each property exposed by the interface is listed along with its data
type or enumeration values and whether the property can be read and written to. In the Methods
section, each method is listed along with its return type and its argument list. The value type for
each argument is shown. If the return type of is shown as <void>, the method returns a value of ‘ok’.
Methods that are used by Actions are commented as such. These methods typically require that the
object be selected and active in the appropriate command panel. In the Actions section, each Action
is listed along with its category and action description as shown in the Customize User Interface
dialog, and the shortcut keys, if any, assigned to the Action.
Note:
Refer to the MAXScript Class Hierarchy (p. 1688) to see which objects are exposed via maxwrapper.
Example:
showinterfaces node
Result:
showinterfaces node
Interface: INode
Properties:
.boneEnable : boolean : Read|Write
.posTaskWeight : float : Read|Write
.rotTaskWeight : float : Read|Write
.boneAutoAlign : boolean : Read|Write
160 Chapter 1 | What’s New in 3ds max 4 MAXScript

.boneFreezeLength : boolean : Read|Write

.boneScaleType : enum : Read|Write
boneScaleType enums: {#scale|#squash|#none}
.stretchTM : matrix3 by value : Read
.boneAxis : enum : Read|Write
boneAxis enums: {#X|#Y|#Z}
.boneAxisFlip : boolean : Read|Write
.primaryVisibility : boolean : Read|Write
.secondaryVisibility : boolean : Read|Write
.applyAtmospherics : boolean : Read|Write
.vertexColorType : enum : Read|Write
vertexColorType enums: {#color|#illum|#alpha|#color_plus_illum}
.showVertexColors : integer : Read|Write
.shadeVertexColors : integer : Read|Write
.handle : DWORD : Read
Methods:
<void>setBoneEnable <boolean>onOff <time>time
<void>realignBoneToChild()
<void>resetBoneStretch()
Actions:
OK

See Also
Core Interfaces (p. 70)
Other Interfaces (p. 71)

Renderer

render() Function Re-entrant

Topic: version 4 MAXScript Language Improvements/Renderer
The render() function can now be called re-entrantly within a scripted render effect (p. 1566), scripted
atmospheric (p. 1569) or scripted material (p. 1565). In prior releases, attempting to do this caused a
runtime error saying that the renderer could not be called while a render was already under way.

See Also
Controlling the Renderer (p. 1664)
Interface: NetRender (p. 379)
 Bitmap Manager – Function Published BMM control 161

SuperClasses

Bitmap Manager – Function Published BMM control

Topic: version 4 MAXScript Language Improvements/SuperClasses
BitmapIO superclass added to scripter to enable Function Published BMM control interfaces.

See Also
BMP, PNG, JPEG and TGA I/O Interfaces (p. 164)
BMP interfaces: (p. 437)
Portable Network Graphics interfaces: (p. 473)
JPEG interfaces: (p. 454)
Targa interfaces: (p. 529)

Utilities, Global Utilities and Render Element plug-ins

Topic: version 4 MAXScript Language Improvements/SuperClasses
Superclasses for Utilities, Global Utilities and Render Element plug-ins added so they can be accessed
and manipulated in MAXScript.
The Utility and GUP superclasses were added to permit access to any static Function Published
interfaces published by the utilities, but MAXScript was attempting to treat them as
ReferenceTarget-based objects, which they are not. There is now a new base superclass,
non_reftarget_maxwrapper_class that should be used for any new superclasses added whose classes
do not live in the ReferenceTarget class hierarchy.

See Also
Render Element Manager (p. 92)
Plug In Manager (p. 86)
Plug-in Manager interfaces: (p. 473)
Visual MAXScript (p. 117)
162 Chapter 1 | What’s New in 3ds max 4 MAXScript

Renderer
Topic: version 4 MAXScript Language Improvements/SuperClasses
A MAXClass wrapper added for the plug-in renderer superclass so that a renderer instances can be
worked with in MAXScript. The new superclass is named “Renderer”.

See Also
Controlling the Renderer (p. 1664)
Interface: NetRender (p. 379)

2 New Scripted Plug-in Superclasses on apply handlers for scripted

RenderEffects
Topic: version 4 MAXScript Language Improvements/SuperClasses
The 2 new scripted plug-in superclasses are Camera and simpleManipulator.
There are several simpleManipulator scripted plug-ins in stdplugs\stdscripts -
radiusManip.ms, sliderManip.ms, and UVWManip.ms.

See Also
Scripted Cameras (p. 94)
Scripted Manipulators (p. 97)

Globals and Locals

Definition Constructs Can Include Global Variable Declarations At

Top Level
Topic: version 4 MAXScript Language Improvements/Globals and Locals
All the major definition constructs in MAXScript (such as utility, rollout, macroScript, rcmenu, tool,
plug-in, etc.) can now include global variable declarations at the top-level within them.
Example:
rollout foo “foo”
(
local a, b = undefined, c
global d, e = 3 -- now possible

spinner bar “Bar”

checkBox baz “Baz: “

on bar changed do ...

)
 Changes to Undeclared Implicit Global Variables 163

In prior releases, globals had to be declared inside on-handler bodies. Any initializers present in a
global declaration like this are at compile time, so the initial value expressions must be executable
at the time the script is compiled.

See Also
Scope of Variables (p. 646)

Changes to Undeclared Implicit Global Variables

Topic: version 4 MAXScript Language Improvements/Globals and Locals
In prior releases, the MAXScript compiler was treating any undeclared variables used in rollout and
plug-in and macroScript handlers as implicitly global. This was at variance with the use of
undeclared variables inside ordinary functions and for-loop bodies and also at variance with the
main scripter documentation. It was also preventing the new stack-based scripter memory
management system from achieving maximum effect in handler execution.
All undeclared variables in handler code are now implicitly declared as locals.

See Also
Definition Constructs Can Include Global Variable Declarations At Top Level (p. 162)
Scope of Variables (p. 646)

Material Editor, Material and Textures

Accessing The Material Editor Active Slot

Topic: version 4 MAXScript Language Improvements/Material Editor, Material and Textures
MAXScript can now access the active slot in the material editor. There is a new system global
variable, activeMeditSlot, that can contain the index of the currently active Material Editor slot. You
can read this to find the active slot, or assign an integer (between 1 and 24) to it to set the active slot.
Examples:
activeMeditSlot = 5 -- set slot 5 to active slot
mtl = meditMaterials[activeMeditSlot] -- pick up active material/map

See Also
Material Editor (p. 1606)
Material Editor Access (p. 165)
Material Level Show-in-viewport State (p. 166)
164 Chapter 1 | What’s New in 3ds max 4 MAXScript

BitmapTex Reload and viewImage

Topic: version 4 MAXScript Language Improvements/Material Editor, Material and Textures
In MAXScript the Bitmap texture now has a reload and viewImage function which are identical to
what is exposed in the bitmapTex interface.

See Also
bitmapTex interfaces: (p. 434)
BitmapTexture : TextureMap (p. 1243)
BMP, PNG, JPEG and TGA I/O Interfaces (p. 164)
Material Editor Access (p. 165)
Accessing The Material Editor Active Slot (p. 163)
Material Level Show-in-viewport State (p. 166)
showTextureMap() function (p. 167)

BMP, PNG, JPEG and TGA I/O Interfaces

Topic: version 4 MAXScript Language Improvements/Material Editor, Material and Textures
BMP interfaces: (p. 437)
This is a function published interface for bmp I/O that provides access to the type of image to
be saved.
Portable Network Graphics interfaces: (p. 473)
This is a function published interface for png I/O that provides access to the type of image to
be saved.
JPEG interfaces: (p. 454)
This is a function published interface for jpeg I/O that provides access to the type of image to
be saved.
Targa interfaces: (p. 529)
This is a function published interface for tga I/O that provides access to the type of image to
be saved.
 Material Editor Access 165

Material Editor Access

Topic: version 4 MAXScript Language Improvements/Material Editor, Material and Textures
Interface available for Texmap and Mtl, Interface: medit (p. 371).
Prototype:
<maxObject>GetCurMtl()
Return Value:
This method returns a material base pointer for the current material.
Prototype:
<void>SetActiveMtlSlot <index>slot <boolean>forceUpdate
Parameters:
<index>slot
The material slot index.
<boolean>forceUpdate
Set this to TRUE to update the slot contents.
Remarks:
This method allows you to set the active material slot.
Prototype:
<index>GetActiveMtlSlot()
Return Value:
This method returns the index of the active material slot.
Prototype:
<void>PutMtlToMtlEditor <maxObject>mtl <index>slot
Parameters:
<maxObject>mtl
The material you want to put.
<index>slot
The index of the material slot you wish to put the material into.
Remarks:
This method allows you to put the specified material to the specified material editor slot.
Prototype:
<maxObject>GetTopMtlSlot <index>slot
Parameters:
<index>slot
The index of the material slot for which you wish to obtain the material.
Return Value:
This method returns a pointer to the material base from the specified slot.
166 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<boolean>OkMtlForScene <material>mtl
Parameters:
<material>mtl
The pointer to the material.
Return Value:
This method is available in release 4.0 and later only.
Before assigning material to scene, call this to avoid duplicate names.
Prototype:
<void>UpdateMtlEditorBrackets()

Remarks:
This method is available in release 3.0 and later only.
This method makes sure the Materials Editor slots correctly reflect which materials are used in the
scene, which are used by selected objects, etc. This is used internally for the drag-and-drop of
materials to nodes -- there is no reason why a plug-in developer should need to call it.

See Also
Interface: medit (p. 371)
BitmapTex Reload and viewImage (p. 164)

Material Level Show-in-viewport State

Topic: version 4 MAXScript Language Improvements/Material Editor, Material and Textures
The material-level show-in-viewport state is now also accessible as a new property on materials,
.showInViewport, which can also be set on a material constructor call using the showInViewport:
keyword argument.
Example:
b=box()
b.material = standard diffuseMap:(checker()) showInViewport:true

See Also
Material Common Properties, Operators, and Methods (p. 1203)
i-drop - drag and drop (p. 62)
 showTextureMap() function 167

showTextureMap() function
Topic: version 4 MAXScript Language Improvements/Material Editor, Material and Textures
The showTextureMap() function has been updated to allow control over material level texture
showing in the viewport. The full form is now:
showTextureMap <material> [<texmap>] <boolean>

If the optional <texmap> is supplied, it must be a direct subtexture of the supplied material and its
show-in-viewport state will be set on or off according to the <boolean> argument. If only a
<material> is supplied, its show-in-viewport state will be set by the <boolean> argument.
Example:
showTextureMap $foo.material on
showTextureMap $foo.material $foo.material.diffusemap off
Note:
Mapping coordinates aren’t explicitly enabled for the objects at creation time. When a script is
run in the Listener, using ‘showTextureMap’ is indirectly turning mapping coordinates on. This
happens during the scene redraw which happens after each line is executed, if needed. If a script
is run from a script editor, or if you put parenthesis around a script, no scene redraw is
performed until the entire script is run. Since no redraw is performed, no mapping coordinates
exist on the object when the script tries to access them. Solutions: explicitly perform a scene
redraw [redrawViews()] after ‘showTextureMap’, or explicitly turn on mapping coordinates for
the object.

See Also
Material Editor (p. 1606)
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Level Show-in-viewport State (p. 166)
Accessing The Material Editor Active Slot (p. 163)
Material Editor Access (p. 165)
168 Chapter 1 | What’s New in 3ds max 4 MAXScript

User Interface

Angle UI element
Topic: version 4 MAXScript Language Improvements/User Interface
The Angle UI element:
• Display of caption string
• Handling of align layout parameter
• StartDegrees and startRadians properties - controls the zero degrees position
• Dir property - either #cw or #ccw (default #ccw)
• Range property - point3 specifying min, max, and value in degrees.
• If min and max values are the same sign, click and move in angle UI will give result of correct
sign. If min and max are different signs, shift or ctrl click will give negative result, click will give
positive result.
Example:
rollout test “ Angle Test”
(
Angle ang2 “Angle” diameter:40 align:#center range:[-180,180,45] startdegrees:270
dir:#cw
)
createdialog test 200 100

See Also
Rollout User-Interface Controls (p. 1481)
Rollout User-Interface Controls Types (p. 1484)
Rollout User-Interface Controls Common Layout Parameters (p. 1483)
Rollout User-Interface Controls Common Properties (p. 1481)
 CreateDialog 169

CreateDialog
Topic: version 4 MAXScript Language Improvements/User Interface
CreateDialog has been enhanced. The prototype is now:
CreateDialog <Rollout> [<height> <width> <position_x> <position_y>] \
[pos:<Point2>] [width:<integer>] [height:<integer>] \
[bgcolor:<color>] [fgcolor:<color>] \
[bitmap:<bitmap>] {bmpstyle:<bmpstyle> \
[menu:<RCMenu>] [style:<array>] [modal:<boolean>]

Modal dialog support added to MAXScript scripter dialogs, those created with the CreateDialog()
function. A new keyword argument can be supplied to the CreateDialog() function,
modal:<boolean>, to control whether the dialog is modal or not. Defaults to modal:false.
A modal dialog ignores all user interactions except those within the dialog. Call DestroyDialog() to
close it, presumably in a scripted OK button, or the like. The user can also close a modal scripted
dialog by hitting the <escape> key.
Associated Methods:
Prototype:
<Point2> GetDialogPos <Rollout>
Remarks:
Returns the position of the Dialog built from the rollout relative to the upper left corner of the screen
in Point2 format.
Prototype:
SetDialogPos <Rollout> <Point2>
Parameters:
<Rollout>
The rollout used to build the Dialog to set the position of.
<Point2>
Position where to place the Dialog.
Remarks:
Sets the position of the dialog built from the rollout relative to the upper left corner of the screen.

See Also
MAXScript Dialogs and Rollout Floaters as Extended viewports (p. 186)
170 Chapter 1 | What’s New in 3ds max 4 MAXScript

Curve Control
Topic: version 4 MAXScript Language Improvements/User Interface

You can create CurveControl’s in rollouts by using the following:

CurveControl <name> [ <caption> ] [ visible: <boolean> ] [ numCurves: <integer> ] \
[ x_range: <point2> ] [ y_range: <point2> ] [ zoomValues: <point2> ]\
[ scrollValues: <point2> ] [ displayModes: <bitarray> ] \
[ commandMode: <#move_xy | #move_x | #move_y | #scale | #corner | bezier> ]\
[ uiFlags: <array_of_ui_flags> ] \
[ rcmFlags: <array_of_rcm_flags> ] [ asPopup:<boolean> ]

uiFlags:
Any combination of the following flags:
#drawBG, #drawgrid, #upperToolbar, #showReset, #scrollBars, #constrainY,#xvalue

rcmFlags:
Any combination of the following flags:
#move_xy, #move_x, #move_y, #scale, #corner, #bezier, #delete, #all

Properties:
<curvecontrol>.visible : Boolean
<curvecontrol>.x_range : Point2
 Curve Control 171

<curvecontrol>.y_range : Point2
<curvecontrol>.displayModes : BitArray
<curvecontrol>.commandMode : Name
<curvecontrol>.zoomValues : Point2

Note:
The following will automatically do a zoom extents all:
zoom <curvecontrol> #all

<curvecontrol>.scrollValues : Point2
<curvecontrol>.curves : Array, read-only
Returns an array of curves of type MAXCurve
Events:
In the following events <ci> represents the active Curve Index.
on <curvecontrol> selChanged <ci> <val> do <expr>
Sent when a point is selected or deselected. <val> is the number of points, which
are selected.
on <curvecontrol> ptChanged <ci> <val> do <expr>
Sent when a point is changed, <val> is the index of the changed point
on <curvecontrol> tangentChanged <ci> <val> type do <expr>
Sent when a point’s in or out tangent is changed, <val> is the index of the changed point
type is #inTangent or #outTangent, depending on what changed.
on <curvecontrol> deleted <ci> <val> do <expr>
Sent when a point is deleted, val is the index of the deleted point.
on <curvecontrol> reset <ci> do <expr>
Sent when a curve is reset
ccCurve represents a single curve in a curve control
Properties:
<ccCurve>.animatable : Boolean
<ccCurve>.color : Color
<ccCurve>.disabledColor : Color
<ccCurve>.width : Integer
<ccCurve>.disabledWidth: Integer
<ccCurve>.disabledStyle : Name
<ccCurve>.style : Name

these are the drawing styles for the curves, can be any one of the following
#solid, #dash, #dot, #dashDot, #dashDotDot, #null, #insideFrame
<ccCurve>.lookupTableSize: Integer
This method sets the size of the Curve Control lookup table. The lookup table allows users of the
Curve Control to easily speed up their value access. The default value for the lookup table size is
1000. Used when getValue() is called on the curve.
172 Chapter 1 | What’s New in 3ds max 4 MAXScript

<ccCurve>.numPoints: Integer
<ccCurve>.points: Array, read-only
Returns a CurvePointsArray
Methods:
getValue ccCurve <time_value> <float_x> [lookup:<false>]
Returns a Point2
isAnimated ccCurve <index>
Returns a Boolean value
getSelectedPts ccCurve
Returns a BitArray
setSelectedPts <ccCurve> <bitarray> [#select] [#deSelect] [#clear]
setPoint <ccCurve> <index> <ccpoint> [checkConstraints:<true>]
getPoint <ccCurve> <index>
insertPoint <ccCurve> <index> <ccpoint>
deletePoint <ccCurve> <index>
CurvePointsArray represents an array of curve points. CurvePointValue represents a
curve point.
CurvePointValue represents a curve point, you create a curve point like:
ccPoint <pt_point2> <in_point> <out_point2> \
[bezier:<false>] [corner:<false>] [lock_x:<false>] [lock_y:<false>] \
[select:<false>] [end:<false>] [noXConstraint:<false>]

Properties:
<ccpoint>.value: Point2
<ccpoint>.inTangent: Point2
<ccpoint>.outTangent: Point2
<ccpoint>.bezier: Boolean
<ccpoint>.corner: Boolean
<ccpoint>.lock_x: Boolean
<ccpoint>.lock_y: Boolean
<ccpoint>.selected: Boolean
<ccpoint>.end: Boolean
<ccpoint>.noXConstraint: Boolean

Example:
rollout uTestCurveControl “Curve Control”(
-- Curve control Properties
local ccProps = #(
#visible,
#numCurves,
#x_range,
#y_range,
#displayModes,
#zoomValues,
#scrollValues,
#commandMode)
 Curve Control 173

-- Curve properties
local curveProps = #(
#name,
#animatable,
#color,
#disabledColor,
#width,
#disabledWidth,
#style,
#disabledStyle,
#numPoints,
#lookupTableSize)

-- Curve Point properties

local cpProps = #(
#value,
#inTangent,
#outTangent,
#bezier,
#corner,
#lock_x,
#lock_y,
#selected,
#end,
#noXConstraint)

button btn_props “Print Properties”

checkBox chk_visible “Visible”checked:true
checkBox chk_enable “Enable”checked:true

CurveControl cc_test “Curve Control:”

height:200
width:400
align:#center
numCurves:2
visible:true
x_range:[-100,100]
y_range:[-100,100]
scrollValues:[-100,100]
commandMode:#move_xy
-- The following parameters default to all flags if not specified
--uiFlags:#(#drawBG, #drawgrid, #upperToolbar, #showReset, #scrollBars,
#constrainY, #xvalue)
rcmFlags:#(#delete)
asPopup:false

on chk_visible changed state do cc_test.visible = state

on chk_enable changed state do cc_test.enabled = state
on uTestCurveControl open do
(
local colors = #(red, green, blue)
174 Chapter 1 | What’s New in 3ds max 4 MAXScript

local styles = #(#solid, #dash, #dot, #dashDot, #dashDotDot, #null, #insideFrame)

local num = cc_test.numCurves

-- Initialize curve properties

for i=2 to num do
(
local crv = cc_test.curves[i]
local ci = ((mod (i-1) colors.count)+1) as integer
local si = ((mod (i-1) styles.count)+1) as integer
crv.name = “Curve” + i as string
crv.color = colors[ci]
crv.disabledColor = colors[ci]*0.5
crv.style = styles[si]
--crv.width = crv.disabledWidth = i
crv.numPoints = i*2
local del = (cc_test.x_range.y -
cc_test.x_range.x)/(crv.numPoints-1)
--format “del:%\n” del
-- Place intermediate points equally spaced
for j=1 to crv.numPoints do
(
local cp = crv.points[j]
format “% end: % -> “ j cp.end
--cp.corner = true
cp.value = [cc_test.x_range.x+(j-1)*del, cp.value.y]
cp.inTangent = [0.2,0.2]
cp.outTangent = [0.2,-0.2]
crv.points[j] = cp
format “%\n” crv.points[j].end
format “value: %\n”
crv.points[j].value
)
)
)

on btn_props pressed do
(
local tab = “\t”
-- print the CC properties
format “Curve Control Properties\n”
for p in ccProps do
format (tab + “% : %\n”) (p as string) (getProperty cc_test p)

format (tab + “Curves:\n”)

tab += “\t”
for i=1 to cc_test.numCurves do
(
local crv = cc_test.curves[i]

-- print each Curve’s properties

format (tab + “Curve%\n”) i
 getTextExtent 175

for p in curveProps do
format (tab + “\t% : %\n”) (p as string) (getProperty crv p)

format (tab + “\tPoints:\n”)

for j=1 to crv.numPoints do
(
local cp = crv.points[j]
format (tab + “\t\tPoint%\n”) j
-- Print each curve point properties
for pp in cpProps do
format (tab + “\t\t\t% : %\n”) (pp as string) (getProperty cp pp)
)
)
)

-- Curve control event handlers

on cc_test selChanged ci val do format “curve % numSelected : %\n” ci val
on cc_test ptChanged ci val do format “curve % ptChanged : %\n” ci val
on cc_test tangentChanged ci val type do format “curve % tangentChanged : % %\n” ci
val (type as string)
on cc_test deleted ci pi do format “curve % deleted : %\n” ci pi
on cc_test reset ci do format “curve % resetted\n” ci
)
curveFloater = newRolloutFloater “Curve Control Test” 500 400
addRollout uTestCurveControl curveFloater

See Also
Rollout User-Interface Controls (p. 1481)
Rollout User-Interface Controls Types (p. 1484)
Rollout User-Interface Controls Common Layout Parameters (p. 1483)
Rollout User-Interface Controls Common Properties (p. 1481)

getTextExtent
Topic: version 4 MAXScript Language Improvements/User Interface
getTextExtent <string>
Returns a Point2 value containing the size of the string in pixels if it was displayed in a
command panel.

See Also
String Values (p. 722)
176 Chapter 1 | What’s New in 3ds max 4 MAXScript

isActive
Topic: version 4 MAXScript Language Improvements/User Interface
Prototype:
isActive <atmos>
Return Value:
Returns true if the atmospheric is set to active; false otherwise

See Also
Atmospheric Effects Common Properties, Operators, and Methods
Prototype:
isActive <renderEffect>
Return Value:
Returns true if the render effect is set to active; false otherwise

See Also
Render Effects Common Properties, Operators, and Methods (p. 1347)

keyboard.escPressed
Topic: version 4 MAXScript Language Improvements/User Interface
keyboard const StructDef (p. 237)
A new keyboard key-state system variable, keyboard.escPressed. Read-only variable yields true or
false depending on whether the Esc key is currently pressed.

See Also
Keyboard Entry (p. 1623)
3D Studio MAX System Globals (p. 630)

macroScript Localization Support for CUI and menu files

In order to make the menu and CUI files more easily localized, a keyword argument,
GlobalCategory:, has been added to the macroScript facility.
Previously, when a macroScript is assigned to a CUI button or menu item, it is identified in the CUI
or MNU file using the macroScript name and category, like this (from the menu file):
Item6_Action=647394:Isolate`Tools

“Isolate” is the name of the macro and “Tools” is the category.

 MAX Open & Save Dialogs 177

The macroScript that defines this operation looks like:

MacroScript Isolate
Category:”Tools”
ToolTip:”Isolate Tool”
Icon:#(”ViewPortNavigationControls”,7)

The problem is when the macroScript is localized, the category is localized but the macroScript name
“Isolate” should not be localized. When it is localized, then the MNU file entry of “Isolate `Tools”
no longer works.
A non-localized category name is needed that would be used to write the operation to MNU and
CUI files.
In this case the macroScript now looks like:
MacroScript Isolate
Category:”Tools”
GlobalCategory:”Tools” -- This is the new keyword
ToolTip:”Isolate Tool”
Icon:#(”ViewPortNavigationControls”,7)

When this macroScript is localized the Category would be translated, but the GlobalCategory
would not.

MAX Open & Save Dialogs

Topic: version 4 MAXScript Language Improvements/User Interface
Prototype:
<string> getMAXSaveFileName filename:<seed_filename_string>
Remarks:
Displays standard MAX file save dialog.
Return Value:
Returns file name or value ‘undefined’ if canceled.
Prototype:
<string> getMAXOpenFileName filename:<seed_filename_string>
dir:<seed_directory_string>
Remarks:
Displays standard MAX file open dialog.
Return Value:
Returns file name or value ‘undefined’ if canceled.

See Also
3ds max File Loading and Saving (p. 1639)
178 Chapter 1 | What’s New in 3ds max 4 MAXScript

Menu and CUI Loading

Topic: version 4 MAXScript Language Improvements/User Interface
You can now load a menu file in MAXScript as follows:
menuMan.loadMenuFile “MaxModelingMenu.mnu”
The full path should not be specified. It will look in the appropriate directories for menu files.
The default is the “ui” directory.
You can set the main menu in max as follows:
menuMan.setMainMenuBar “Menu Bar1”

To restore MAX’s default main menu:

menuMan.setMainMenuBar “Main Menu Bar”

The function returns true of it succeeds and false if it can’t find the named menu.
You can set the quad right-click menu that MAX uses in the viewports using the following
MAXScript:
menuMan.setViewportRightClickMenu #nonePressed “Modeling 2”
Sets the default (no keys pressed) quad menu to “Modeling 2”. The menu name must be a quad
menu that is listed in the “Quads” customization dialog, and the name must match exactly,
including capitalization.
For the first parameter, you can use one of the following 8 values:
#nonePressed
#shiftPressed
#altPressed
#controlPressed
#shiftAndAltPressed
#shiftAndControlPressed
#controlAndAltPressed
#shiftAndAltAndControlPressed

Here are two macroScripts that set and reset two of the right-click menus:
Example:
macroScript SetQuads
category:”Custom UI”
tooltip:”Set Quad”
(
on execute do
(
menuMan.setViewportRightClickMenu #nonePressed “Modeling 2”
menuMan.setViewportRightClickMenu #controlPressed “Sample 4x1”
)
)
------------------------------
macroScript ResetQuads
category:”Custom UI”
 Menu and CUI Loading 179

tooltip:”Reset Quads”
(
on execute do
(
menuMan.setViewportRightClickMenu #nonePressed “Default Viewport
Quad”
menuMan.setViewportRightClickMenu #controlPressed “Modeling 1
[Cntrl+RMB]”
)
)

You can display a quad menu like this:

menuMan.trackQuadMenu “Default Viewport Quad”
The menu name must be a quad menu that is listed in the “Quads” customization dialog, and
the name must match exactly, including capitalization.
Menu Manager (p. 75)
Interface: menuMan (p. 372)
You can load a CUI file from MAXScript as follows:
maxOps.loadCUIFile “ModelingCUI.cui”

It will search the appropriate UI directory for the .cui file.

Interface: maxOps (p. 368)
maxOps (p. 87)
cui.expertModeOff() -- Turns expert mode on
cui.expertModeOff() -- Turns expert mode off
cui.getExpertMode() -- returns true of expert mode is on

cui const StructDef (p. 234)

cui.commandPanelOpen --Lets you get and set whether the command panel is displayed. A
Boolean value - true if the command panel is displayed, false if not displayed.

See Also
cui const StructDef (p. 234)
3D Studio MAX System Globals (p. 630)
180 Chapter 1 | What’s New in 3ds max 4 MAXScript

mtlBrowser
Topic: version 4 MAXScript Language Improvements/User Interface
mtlBrowser const StructDef (p. 244)
Prototype:
mtlBrowser.browseFrom [#mtlLibrary | #mtlEditor | #activeSlot | #selected | #scene |
#new]

Remarks:
Lets you set the Browse From: source for the modeless material browser.

See Also
Miscellaneous Dialogs (p. 1621)

SetBackground Method
Topic: version 4 MAXScript Language Improvements/User Interface
Changed SetBackground to take a color in addition to a point3.
Prototype:
setBackGround [<time>] <color>
Remarks:
If the time value is not specified, the current MAXScript time is used.
Prototype:
getBackGround [<time>]
Remarks:
Gets method that parallels setBackGround method.

See Also
Working with Atmospherics (p. 1345)

mouseTrack() Function
Topic: version 4 MAXScript Language Improvements/User Interface
While the tracking is going on, this function is called whenever a mouse action occurs, such as a
button click or a drag, etc. The function has the form:
mouseTrack [on:<node>] [prompt:”msg”] [snap:#2D|#3D]
[trackCallback:fn|#(fn,arg)]
 mouseTrack() Function 181

Parameters:
on:<node>
Optionally specifies a scene object to track on. If you don’t supply an object, the
mouse tracks on the current active grid. Note that the object surface tracker uses
the SDK function IntersectRay() which is not reliably implemented on all object
types. Editable meshes always work OK, so you can convertToMesh() if needed.
prompt:”msg”
Displays the prompt message in the MAX status line
snap:#2D|#3D
Relevant when not tracking on an object surface (no on:<node> specified). If snap
mode is on and #2D is supplied, snaps to snap points on grid, if #3D is specified
snaps to any near snap point in space.
trackCallback:fn|#(fn,arg)
Is where you specify the function to be called as the mouse is dragged over the
active grid or object surface. You can specify it is a single function or a function
and an argument value in a two element array. The latter form is useful if you
have a common callback function for many tasks and want to send in a parameter
to control its operation for a particular use. The function you give must be of the
following form:
fn callback_fn msg ir obj faceNum shift ctrl alt = ...
in other words, a scripted function of 7 arguments. While the tracking is going
on, it is called whenever a mouse action occurs, such as a button click or a
drag, etc.
The ‘msg’ argument is a message code that indicates what kind of action occurred, and can be one of:
#freeMove - means the mouse is moved without a button being pressed
#mousePoint - means the left mouse button has just been pressed
#mouseMove - means the mouse is being dragged with the left button down
#mouseAbout - means the right mouse button was clicked, normally meaning cancel

Parameters:
‘ir’
The grid or surface intersection normal Ray at the current mouse position. The ray
has a .pos property giving the point in space of the normal and a .dir property
giving the normal’s direction vector.
‘obj’
The object being dragged over or undefined if no on:<node> was supplied.
‘faceNum’
The number of the face the mouse is over if the object being tracked is an editable
mesh, undefined otherwise.
182 Chapter 1 | What’s New in 3ds max 4 MAXScript

‘shift’, ‘ctrl’ and ‘alt’

True or false depending on the down or up state of the <shift>, <ctrl> and <alt>
keys on the keyboard.
The function should return the special value #continue to continue tracking or
any other value to halt tracking. That value then becomes the result of the
original mouseTrack() call.

See Also
Rollout User-Interface Controls (p. 1481)

snapMode
Topic: version 4 MAXScript Language Improvements/User Interface
snapMode const StructDef (p. 254)
Prototype:
snapMode.active
Remarks:
Lets you get and set a Boolean value defining the Snap toggle state - on (true) or off (false).
Prototype:
snapMode.type
Remarks:
Lets you get and set a Name value defining whether 2D (#2D), 2.5D (#2_5D), or 3D (#3D)
is the current snap type.

See Also
3D Studio MAX System Globals (p. 630)

Spinner UI Item setKeyBrackets

Topic: version 4 MAXScript Language Improvements/User Interface
A new parameter has been added to spinner UI items, setKeyBrackets, which can be set to true (on)
or false (off) to turn on and off the red keyframe brackets that signal a keyframe is present for
animated parameters. This allows you to simulate keyframe notification in scripted rollouts by
setting this spinner property on or off, most likely in a time change callback function. You can set
this as a parameter on a spinner definition,
spinner ... setKeyBrackets:<boolean> ...
or via property assignment,
<spinner>.setKeyBrackets = <boolean>
 Timer UI element 183

See Also
Spinner (p. 1509)
Rollout User-Interface Controls (p. 1481)
Rollout User-Interface Controls Types (p. 1484)
Rollout User-Interface Controls Common Layout Parameters (p. 1483)
Rollout User-Interface Controls Common Properties (p. 1481)

Timer UI element
Topic: version 4 MAXScript Language Improvements/User Interface
The Timer UI element has been enhanced in the following ways:
• The initial state of timer now respects the timer’s .active parameter.
• A new .ticks read/write property which is incremented by 1 at each ‘tick’ of the timer.

See Also
Timer (p. 1512)
Rollout User-Interface Controls (p. 1481)
Rollout User-Interface Controls Types (p. 1484)
Rollout User-Interface Controls Common Layout Parameters (p. 1483)
Rollout User-Interface Controls Common Properties (p. 1481)

TimeSlider on/off toggle

Topic: version 4 MAXScript Language Improvements/User Interface
There is an interface to turn on/off the timeslider has been added.
This is accessed through the scripter in the following way:
[void] timeSlider.setVisible [true|false]
[bool] timeSlider.isVisible

In the scripter, this is always sticky across sessions.

See Also
Interface: timeSlider (p. 428)
184 Chapter 1 | What’s New in 3ds max 4 MAXScript

Undo/Redo Dropdown Labels

Topic: version 4 MAXScript Language Improvements/User Interface
MAXScript now provides some control over the labels displayed in the MAX undo/redo dropdown
list for undoable MAXScript operations. This is an improvement to just displaying “MAXScript” in
all cases, as it did in prior versions.
Any undoable macroScript execution, such as via a toolbar button, menu item, hotkey or quad-
menu item, will now be displayed in the undo/redo list with the name of the macroScript.
The ‘undo on’ context prefix now accepts an optional string literal (text in double quotes) after the
‘undo’ keyword, which will be used as the label for the undo block in the MAX undo/redo lists.
Example:
undo “add background” on
(
...
)

will generate an undo-block for all the operations in the block-expression following the
prefix, which will display in the undo/redo lists with the given string as its name. The
name must be a literal string and is optional, and will default to “MAXScript”.

See Also
undo (p. 687)
Sticky Contexts (p. 689)

Zoom to Bounds
Topic: version 4 MAXScript Language Improvements/User Interface
ZoomToBounds just zooms the current or selected viewport to a bounding region.
Prototype:
Viewport.ZoomToBounds <A_Point3> <B_Point3> <All_Bool>
Parameters:
A_Point3 and B_Point3 define the bounding region to zoom to.
All_Bool determines whether only the selected or all viewports get zoomed

See Also
viewport const StructDef (p. 258)
 Customize The Order of Rollup Pages 185

Command Panels and Rollout Pages

Customize The Order of Rollup Pages

Topic: version 4 MAXScript Language Improvements/User Interface/Command Panels and
Rollout Pages
Dragging and dropping rollouts sets Rollup order. The order of the rollups will be saved in the file
RollupOrder.cfg (in ASCII), which is located in the UI directory. Deleting this file, or removing an
entry for a specific Class, will reset the Rollout order.
cmdPanel.GetRollupThreshold()
cmdPanel.SetRollupThreshold()
Determines how many pixels of a rollout should be scrollable in the command panel before the
rollout is shifted into a separate command panel column. This option is only applicable when there
are multiple columns displayed in the command panel.
Rollups, which can be customized have a new RCMenu entry, that lets the user reset the rollup
customization. In order to delete all rollup customization the user can simply delete the
RollupOrder.cfg file in the UI directory and restart MAX.

See Also
Interface: cmdPanel (p. 356)
Rollout Systems ‘category’ Mechanism (p. 188)
Rollout User-Interface Controls (p. 1481)
Rollout User-Interface Controls Types (p. 1484)
Rollout User-Interface Controls Common Layout Parameters (p. 1483)
Rollout User-Interface Controls Common Properties (p. 1481)
Visual MAXScript (p. 117)
186 Chapter 1 | What’s New in 3ds max 4 MAXScript

MAXScript Dialogs and Rollout Floaters as Extended viewports

Topic: version 4 MAXScript Language Improvements/User Interface/Command Panels and
Rollout Pages
The following functions can be used to register and unregister MAXScript dialogs and rollout floaters
as extended viewports.
registerViewWindow <MAXScript_dialog | rollout_floater>
Registers any MAXScript dialog or rollout floater as an extended viewport. The title of the
dialog or floater appears in the viewport right click menu, under Views > Extended menu.
When picked the dialog or floater will be displayed in that viewport.
If you click anywhere on the outside border, it will pop up the standard views menu. This will let
you switch to a different view window.
unRegisterViewWindow < MAXScript_dialog | rollout_floater>
Unregisters a dialog or floater as an extended view window. It will throw an error if the
dialog or floater is currently displayed in a viewport.
Here is a sample script that creates two instances of a Cult3D viewer, found at www.cycore.com, and
opens two files from the internet. Install the Cult3d Viewer and execute the script example below.
After executing the script right click on any of the viewports and pick “Views > Extended > Cult3D
Player” to display the window in the viewport.
example:
rollout rCult3D “Cult3D Player”
(
activeXControl ax1 “{31B7EB4E-8B4B-11D1-A789-00A0CC6651A8}” align:#left
setupEvents:false pos:[10,10]
activeXControl ax2 “{31B7EB4E-8B4B-11D1-A789-00A0CC6651A8}” align:#left
setupEvents:false pos:[10,220]
on rCult3D resized size do
(
local csz = (size - [20,30])*[1,.5]
ax2.pos = [10, csz.y+20]
ax1.size = ax2.size = csz
)
on rCult3D open do
(
ax1.size = ax2.size = [300,200]
ax1.LoadCult3D “http://www.cult3d.com/gallery/ecommerce/olympus_on_the_beach.co”
ax2.LoadCult3D “http://www.cult3d.com/gallery/
museum/madonna.co”
)
)
createDialog rCult3D width:320 height:430
registerViewWindow rCult3D
 Rollout .Controls Property 187

See Also
ActiveX Controls in MAXScript Rollouts (p. 10)

Rollout .Controls Property

Topic: version 4 MAXScript Language Improvements/User Interface/Command Panels and
Rollout Pages
<rollout>.controls
Property which returns an array of all the controls in the rollout.
Example:
for c in foo.controls do c.enabled = false
Remarks:
foo is a rollout.
188 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
Rollout User-Interface Controls (p. 1481)
Rollout User-Interface Controls Types (p. 1484)
Rollout User-Interface Controls Common Properties (p. 1481)
Rollout User-Interface Controls Common Layout Parameters (p. 1483)

Rollout Systems ‘category’ Mechanism

Topic: version 4 MAXScript Language Improvements/User Interface/Command Panels and
Rollout Pages
You can control the grouping of rollups for a plug-in by supplying a category:<integer> header
parameter, before the opening parenthesis of the rollout body.
Example:
rollout foo “Frabulator” category:3
(
....
)

Category number orders the rollouts.

See Also
Rollout User-Interface Controls (p. 1481)
Rollout User-Interface Controls Types (p. 1484)
Rollout User-Interface Controls Common Properties (p. 1481)
Customize The Order of Rollup Pages (p. 185)
Interface: cmdPanel (p. 356)
Rollout User-Interface Controls Common Layout Parameters (p. 1483)
Visual MAXScript (p. 117)

version 4 All Const and MAXScript Functions

Definitions for MAXScript internal organization

MAXScriptFunction
Const Generic
Const MappedGeneric
Const NodeGeneric
Const Primitives
Const StructDef
 Definitions for MAXScript internal organization 189

Const Class
When you say something like “fn test val = ...”, a MAXScriptFunction value is created and stored
in variable test. If variable test was passed into another method, for example as a filter function, that
method would test the class of the value to make sure it’s a MAXScriptFunction and then call it using
apply().
The ‘Const’ preceding the following simply says that it is a value that is created during MAXScript
initialization.

A Generic is one or more methods with the same name, but defined for different classes. Which
method is called depends on the class of the first argument to the method. For example, ‘random’
is declared as a Generic, and there are methods implementing ‘random’ in several classes - Integer,
Float, Point3, Color, Quat, etc. When MAXScript sees ‘random v1 v2’ in a script, it looks at the class
of v1, and then calls the ‘random’ method for that class. So if v1 were a float, MAXScript would call
the Float::random() method.

A MappedGeneric is the same as a Generic, but the first argument can be a collection. If it is a
collection, the the method is called individually on each member of the collection. For example,
‘deleteTime $box* 10f 10f’ deletes 10f at frame 10 in all keys in all objects named $box*. deleteTime
can also be used on controllers, that’s why it is a Generic

A NodeGeneric is the same as a MappedGeneric, but its first argument has to be a node or a
collection of nodes. But given the definition of Generic, that doesn’t make much sense. If the first
argument is a collection, and the method is applied to each member of the collection.

Primitives are methods that aren’t class specific. The method is responsible for checking the types
of its arguments (if any) and throwing an error if one isn’t correct. There is only one definition of
the Primitive.

A StructDef is a structure value. If the structure value is created by a script, its class is StructDef. If
MAXScript creates the structure during initialization, its class is Const StructDef. So, for example,
my meshop methods are defined to exist in a structure called meshop. Since this structure is created
during initialization, the class of meshop is Const StructDef.

Const Class is just a class that is defined in MAXScript itself. So, for example, BitArray is a Const
Class. MAXScript also scans the classes registered with MAX - these classes will be created in
MAXScript as Const MAXClass.
190 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
MAXScriptFunction List (p. 190)
Const Generic (p. 195)
Const MappedGeneric (p. 207)
Const NodeGeneric (p. 209)
Const Primitives (p. 213)
Const StructDef (p. 231)
Const Class (p. 191)

MAXScriptFunction List
AddConstraint Controller Functions for use with Constraint Assignments (p. 42)
Camera Common Properties, Operators, and Methods (p. 974) - in example
Scripted Geometry Plug-ins (p. 1555) - in example
Scripted Shape Plug-ins (p. 1560) - in example
Scripted SimpleObject Plug-ins (p. 1556) - in example
The Return Expression (p. 705) - in example
Time Values (p. 751)
AddConstraintTargets Controller Functions for use with Constraint Assignments (p. 42)
AddListController Controller Functions for use with Constraint Assignments (p. 42)
AddMod
ApplyOperation ApplyOperation function (p. 54)
ChangeSystemColorsAnimateOff
ChangeSystemColorsAnimateOn
help
KindOfRenderElement
RElements2cws
SaveQuadClr
SetActiveController Controller Functions for use with Constraint Assignments (p. 42)
show “Apropos” and “ShowProperties” and now “Help” and “Show” (p. 128)
TurnToSeq

See Also
Definitions for MAXScript internal organization (p. 188)
 Const Class 191

Const Class
ActionPredicate
ActiveXControl ActiveX Controls in MAXScript Rollouts (p. 10) - in example with
def
AngleAxis
AngleControl
Array
ArrayParameter
AtmosphericClass MAXScript Class Hierarchy (p. 1688)
BigMatrix BigMatrix Values (p. 748) - in example with def
Basic Data Values (p. 717)
Const Generic (p. 195) – links
Const MappedGeneric (p. 207)
MAXScript Class Hierarchy (p. 1688)
BigMatrixRowArray BigMatrix Values (p. 748) - in example with def
MAXScript Class Hierarchy (p. 1688)

BinStream
BipedExportInterface
BipedFSKey
BipedGeneric
BipedKey
BitArray
bitmap
BitmapControl
BooleanClass
Box2
ButtonControl
ccCurve
ccPoint
CCRootClass
ChangeHandler
CharStream
CheckBoxControl
CheckButtonControl
class
color
ColorPickerControl
ComboBoxControl
Control
CTBitMap
CTMotionTracker
CurveCtlGeneric
CurvePointsArray
EdgeSelection
EditTextControl
EffectClass
EmptyClass
EulerAngles
FaceSelection
192 Chapter 1 | What’s New in 3ds max 4 MAXScript

FileStream
float
Function
Generic
GeomObject
GroupBoxControl
GroupEndControl
GroupStartControl
HashTable
ImgTag
integer
Interface
InterfaceFunction
Interval
IObject
LabelControl
LinkControl
ListBoxControl
MapButtonControl
MappedGeneric
MappedPrimitive
MapSupportClass
MaterialLibrary
Matrix3
MAXAKey
MAXClass
MAXCurveCtl
MAXFilterClass
MAXKey
MAXKeyArray
MAXMeshClass
MAXModifierArray
MAXNoteKey
MAXNoteKeyArray
MAXObject
MAXRefTarg
MAXRootNode
MAXScriptFunction
MAXSuperClass
MAXTVNode
MeditMaterialsClass
menuitem
MixinInterface
ModifierClass
MoFlow
MoFlowScript
MoFlowSnippet
MoFlowTranInfo
MoFlowTransition
MotionTracker
MouseTool
 Const Class 193

MSBipedRootClass
MSComMethod
MSCustAttribDef
MSDispatch
MSPluginClass
MtlButtonControl
MultiListBoxControl
MultiMaterialClass
MultipleFSParams
name
NodeChildrenArray
NodeGeneric
NoteTrack
Number
NURBS1RailSweepSurface
NURBS2RailSweepSurface
NURBSBlendCurve
NURBSBlendSurface
NURBSCapSurface
NURBSChamferCurve
NURBSControlVertex
NURBSCurve
NURBSCurveConstPoint
NURBSCurveIntersectPoint
NURBSCurveOnSurface
NURBSCurveSurfaceIntersectPoint
NURBSCVCurve
NURBSCVSurface
NURBSDisplay
NURBSExtrudeSurface
NURBSFilletCurve
NURBSFilletSurface
NURBSIndependentPoint
NURBSIsoCurve
NURBSLatheSurface
NURBSMirrorCurve
NURBSMirrorSurface
NURBSMultiCurveTrimSurface
NURBSNBlendSurface
NURBSObject
NURBSOffsetCurve
NURBSOffsetSurface
NURBSPoint
NURBSPointConstPoint
NURBSPointCurve
NURBSPointCurveOnSurface
NURBSPointSurface
NURBSProjectNormalCurve
NURBSProjectVectorCurve
NURBSRuledSurface
NURBSSelection
194 Chapter 1 | What’s New in 3ds max 4 MAXScript

NURBSSet
NURBSSurface
NURBSSurfaceApproximation
NURBSSurfaceEdgeCurve
NURBSSurfaceNormalCurve
NURBSSurfConstPoint
NURBSSurfSurfIntersectionCurve
NURBSTexturePoint
NURBSTextureSurface
NURBSULoftSurface
NURBSUVLoftSurface
NURBSXFormCurve
NURBSXFormSurface
object
ObjectSet
OkClass
OLEMethod
OLEObject
PathName
PhyBlendedRigidVertex
PhyContextExport
PhyRigidVertex
PickerControl
Point2
point3
Primitive
progressBar
Quat
RadioControl
Ray
RCMenu
RolloutClass
RolloutControl
RolloutFloater
SelectionSet
SelectionSetArray
set
SliderControl
SpinnerControl
StandardMaterialClass
StaticMethodInterface
String
StringStream
StructDef
subAnim
TxtureClass
time
Timer
TriMesh
UndefinedClass
UnsuppliedClass
 Const Generic 195

UserGeneric
value
ValueRef
VertexSelection
WindowStream
XRefScene

See Also
Definitions for MAXScript internal organization (p. 188)

Const Generic
abs Number Values (p. 717) - in example with def
Camera Common Properties, Operators, and Methods (p. 974) - in example
Scripted Geometry Plug-ins (p. 1555) - in example
Scripted Shape Plug-ins (p. 1560) - in example
Scripted SimpleObject Plug-ins (p. 1556) - in example
The Return Expression (p. 705) - in example
Time Values (p. 751)
addMultiplierCurve Controller Ease and Multiplier Curve Functions (p. 1297) - in example with def
addNewNoteKey MAXNoteKeyArray Values (p. 817) - in example
MAXNoteKey Values (p. 818) - in example
Working with Note Tracks (p. 818) - in example
addNewNoteKey MAXNoteKeyArray Values (p. 817) - in example
MAXNoteKey Values (p. 818) - in example
Working with Note Tracks (p. 818) - in example
addPluginRollouts Scripted Plug-in Methods (p. 1551)
AllowBlending PhyContextExport Values (p. 1458)
append
appendCurve NURBS1RailSweepSurface : NURBSSurface (p. 1427)
NURBS2RailSweepSurface : NURBSSurface (p. 1429)
NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438)
NURBSULoftSurface : NURBSSurface (p. 1443)
appendCurveByID NURBS1RailSweepSurface : NURBSSurface (p. 1427)
NURBS2RailSweepSurface : NURBSSurface (p. 1429)
NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438)
NURBSULoftSurface : NURBSSurface (p. 1443)
appendGizmo Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
Working with Atmospherics (p. 1345) - example
196 Chapter 1 | What’s New in 3ds max 4 MAXScript

appendObject Modifying Existing NURBS Objects (p. 1390)

Creating New NURBS Objects (p. 1389) - in example
NURBSSet : Value (p. 1450)
appendUCurve NURBSUVLoftSurface : NURBSSurface (p. 1444)
appendUCurveByID NURBSUVLoftSurface : NURBSSurface (p. 1444)
appendVCurve NURBSUVLoftSurface : NURBSSurface (p. 1444)
appendVCurveByID NURBSUVLoftSurface : NURBSSurface (p. 1444)
applyEaseCurve Controller Ease and Multiplier Curve Functions (p. 1297) - in example with def
attach
buildTVFaces Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Working with Editable Meshes (p. 1077) - in example
buildVCFaces Editable_Mesh : GeometryClass and TriMesh : Value (p. 1041)
canConvertTo Node Common Properties, Operators, and Methods (p. 820)
NURBS Node Properties and Methods (p. 1397)
classOf
clear
clearAllAppData Access to MAXWrapper AppData (p. 813)
clearCacheEntry
clearProdTess NURBSSet : Value (p. 1450)
NURBSSurface : NURBSObject (p. 1425)
clearViewTess NURBSSet : Value (p. 1450)
NURBSSurface : NURBSObject (p. 1425)
close
closeU NURBSCVSurface : NURBSSurface (p. 1433)
NURBSPointSurface : NURBSSurface (p. 1441)
closeV NURBSCVSurface : NURBSSurface (p. 1433)
NURBSPointSurface : NURBSSurface (p. 1441)
collapseface Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
composite
Conjugate Quat Values (p. 738)
contains
ConvertToRigid PhyContextExport Values (p. 1458)
createInstance MAXWrapper Common Properties, Operators, and Methods (p. 809)
Scripted Manipulator (p. 97) - in example
Scripted Manipulators (p. 97) - in example
Scripted SimpleObject Plug-ins (p. 1556) - in example with def
 Const Generic 197

crop bgndRenderElement - superclass: MAXObject (p. 270) - in example

BitmapTex fnReload and fnCrop (p. 164)
bitmapTex interfaces: (p. 434) - in example
BitmapTexture : TextureMap (p. 1243)
cross
defaultVCFaces Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
deleteAppData Access to MAXWrapper AppData (p. 813)
deleteface Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
deleteGizmo Atmospheric Effect Types (p. 1339)
deleteItem
deleteKey Attachment : PositionController (p. 1304)
Biped Keys (p. 1759)
Controller Key Functions (p. 1294)
MAXKeyArray Values (p. 793)
deleteMultiplierCurve Controller Ease and Multiplier Curve Functions (p. 1297)
deleteNoteKey MAXNoteKeyArray Values (p. 817)
Working with Note Tracks (p. 818) - in example
deleteNoteKeys MAXNoteKeyArray Values (p. 817)
Working with Note Tracks (p. 818) - in example
deleteObjects NURBSSet : Value (p. 1450)
deleteTracker
deletevert Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
deselectKey Controller Key Functions (p. 1294)
detachFaces
detachVerts -jpr see above
disconnect Interface: paramWire (p. 410) - in example
displacementToPreset Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
display
distance
dot
empty
eof NURBSCurve : NURBSObject (p. 1409)
evalPos NURBSSurface : NURBSObject (p. 1425)
evalTangent NURBSCurve : NURBSObject (p. 1409)
evalUTangent NURBSSurface : NURBSObject (p. 1425)
evalVTangent NURBSSurface : NURBSObject (p. 1425)
execute
198 Chapter 1 | What’s New in 3ds max 4 MAXScript

exp Number Values (p. 717)

Mathematical Operations in MAXScript (p. 588)
Quat Values (p. 738) - in example with def
exprForMAXObject Mesher - superclass: GeometryClass (p. 298)
extrudeface Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Scripted SimpleObject Plug-ins (p. 1556)
filepos FileStream Values (p. 763)
StringStream Values (p. 766)
findItem
findPattern
findString String Values (p. 722)
Function Parameters (p. 702)
Pickbutton (p. 1504)
flagChanged XRefScene Values (p. 1038)
flush FileStream Values (p. 763)
StringStream Values (p. 766)
Turning On the Listener Log (p. xli)
getAfterORT Controller Out-Of-Range Functions (p. 1296)
Controller Key Reducer
getAppData Access to MAXWrapper AppData (p. 813)
getBeforeORT Controller Out-Of-Range Functions (p. 1296)
getChannel Bitmap Values (p. 755)
getChannelAsMask Bitmap Values (p. 755)
Scripted RenderEffect Plug-ins (p. 1566) - in example
getCurve NURBS1RailSweepSurface : NURBSSurface (p. 1427)
NURBS2RailSweepSurface : NURBSSurface (p. 1429)
NURBSULoftSurface : NURBSSurface (p. 1443)
getCurveID NURBS1RailSweepSurface : NURBSSurface (p. 1427)
NURBS2RailSweepSurface : NURBSSurface (p. 1429)
NURBSULoftSurface : NURBSSurface (p. 1443)
getCurveStartPoint NURBS1RailSweepSurface : NURBSSurface (p. 1427)
NURBS2RailSweepSurface : NURBSSurface (p. 1429)
getCV NURBSControlVertex : NURBSObject (p. 1409)
NURBSCVCurve : NURBSCurve (p. 1412)
NURBSCVSurface : NURBSSurface (p. 1433)
getDisplacementMapping Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getEdge NURBSBlendSurface : NURBSSurface (p. 1430)
NURBSNBlendSurface : NURBSSurface (p. 1439)
getEdgeVis Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
 Const Generic 199

getface Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)

Working with Editable Meshes (p. 1077)
getFaceMatID Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getFaceNormal Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getFaceSmoothGroup Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getFlip NURBS1RailSweepSurface : NURBSSurface (p. 1427)
NURBS2RailSweepSurface : NURBSSurface (p. 1429)
NURBSULoftSurface : NURBSSurface (p. 1443)
Path interfaces: (p. 462)
Path Constraint interfaces: (p. 468)
getFlipTrim NURBSFilletSurface : NURBSSurface (p. 1436)
getGenerateUVs NURBSSurface : NURBSObject (p. 1425)
getGizmo Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
getIndexedPixels Bitmap Values (p. 755)
getKey
getKeyIndex Controller Key Functions (p. 1294)
getKnot NURBSCVCurve : NURBSCurve (p. 1412)
getModContextBBoxMax Modifier Common Properties, Operators, and Methods (p. 1096)
Modifier Sub-Object Transform Properties (p. 1099)
Node Common Properties, Operators, and Methods (p. 820)
getModContextBBoxMin Modifier Common Properties, Operators, and Methods (p. 1096)
Modifier Sub-Object Transform Properties (p. 1099)
Node Common Properties, Operators, and Methods (p. 820)
Scripting Vertex and Control Point Animation (p. 1461)
getModContextTM Modifier Common Properties, Operators, and Methods (p. 1096)
Modifier Sub-Object Transform Properties (p. 1099)
Node Common Properties, Operators, and Methods (p. 820)
getMultiplierValue Controller Ease and Multiplier Curve Functions (p. 1297)
GetNode Biped and Physique (p. 1456) - in example
getnormal Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Scripted Manipulators (p. 97)
getNoteKeyIndex Notetrack Values (p. 816)
getNoteKeyTime MAXNoteKeyArray Values (p. 817)
Notetrack Values (p. 816)
getNumCPVVerts Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getNumFaces Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getNumTVerts Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getNumVerts Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Patches (p. 55)
200 Chapter 1 | What’s New in 3ds max 4 MAXScript

getObject Patches
GetOffsetVector Biped and Physique (p. 1456) - in example
getParent NURBSBlendSurface : NURBSSurface (p. 1430)
NURBSFilletSurface : NURBSSurface (p. 1436)
NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438)
NURBSNBlendSurface : NURBSSurface (p. 1439)
Trackviews (p. 114)
getParentID NURBSBlendSurface : NURBSSurface (p. 1430)
NURBSFilletSurface : NURBSSurface (p. 1436)
NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438)
NURBSNBlendSurface : NURBSSurface (p. 1439)
getPixels Bitmap Files (p. 1641)
Scripted RenderEffect Plug-ins (p. 1566)
getPoint NURBSIndependentPoint : NURBSPoint (p. 1406)
NURBSPointCurve : NURBSCurve (p. 1418)
NURBSPointSurface : NURBSSurface (p. 1441)
NURBSTexturePoint : NURBSObject (p. 1446)
NURBSTextureSurface : Value (p. 1455)
Curve Control (p. 170)
Scripted Manipulators (p. 97)
getProdTess NURBSSet : Value (p. 1450)
NURBSSurface : NURBSObject (p. 1425)
getPropNames Class and Object Inspector Functions (p. 799)
Array Values (p. 776) - in example
ActiveX Controls in MAXScript Rollouts (p. 10)
Scripted Manipulators (p. 97) - in example
getRadius NURBSFilletSurface : NURBSSurface (p. 1436)
getSeed NURBSFilletSurface : NURBSSurface (p. 1436)
getSplitMesh Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getSubAnim Indexed Access to Animatable Properties in 3D Studio MAX Objects (p. 806)
getSubAnimName Indexed Access to Animatable Properties in 3D Studio MAX Objects (p. 806)
Subanim Indexing Operator, [], on MAX Objects Now Takes Subanim Names (p. 139)
getSubAnimNames Indexed Access to Animatable Properties in 3D Studio MAX Objects (p. 806)
Subanim Indexing Operator, [], on MAX Objects Now Takes Subanim Names (p. 139)
getSubdivisionDisplacement Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getTextureSurface NURBSSurface : NURBSObject (p. 1425)
NURBSTextureSurface : Value (p. 1455)
getTextureUVs NURBSSurface : NURBSObject (p. 1425)
getTiling NURBSSurface : NURBSObject (p. 1425)
getTilingOffset NURBSSurface : NURBSObject (p. 1425)
 Const Generic 201

getTimeRange Controller Time Functions (p. 1292)

getTracker
getTrimSurface NURBSFilletSurface : NURBSSurface (p. 1436)
getTVert Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Node Common Properties, Operators, and Methods (p. 820) - in example
getTVFace Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Node Common Properties, Operators, and Methods (p. 820) - in example
getUCurve NURBSUVLoftSurface : NURBSSurface (p. 1444)
getUCurveID NURBSUVLoftSurface : NURBSSurface (p. 1444)
getUKnot NURBSCVSurface : NURBSSurface (p. 1433)
getVCFace Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getVCurve NURBSUVLoftSurface : NURBSSurface (p. 1444)
getVCurveID NURBSUVLoftSurface : NURBSSurface (p. 1444)
getVert Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Patches (p. 55)
Script Controllers (p. 1329) - in example
getvertcolor Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getVertexInterface PhyBlendingRigidVertex Values (p. 1459)
PhyContextExport Values (p. 1458)
PhyRigidVertex Values (p. 1459)
Biped and Physique (p. 1456) - in example
getViewTess NURBSSet : Value (p. 1450)
NURBSSurface : NURBSObject (p. 1425)
getVKnot NURBSCVSurface : NURBSSurface (p. 1433)
getWeight PhyBlendingRigidVertex Values (p. 1459)
Class and Object Inspector Functions (p. 159) - in example
LookAt Constraint - superclass: RotationController (p. 297)
LookAt Constraint interfaces: (p. 455)
Orientation Constraint Controller (p. 40)
Path Constraint interfaces: (p. 468)
Position Constraint (p. 41)
Position Constraint interfaces: (p. 488)
gotoFrame Bitmap Values (p. 755)
invalTrack
Inverse Matrix3 Values
Matrix3 Values Using Node Transform Properties (p. 843) - in example
invert BigMatrix Values (p. 748)
VolumeSelect : Modifier (p. 1192)
Volume Light : Atmospheric (p. 1344)
Volume Fog : Atmospheric (p. 1343)
202 Chapter 1 | What’s New in 3ds max 4 MAXScript

isEmpty Box2 Values (p. 750)

Coercion of bitArray to array and integer arrays to bitArrays (p. 132)
isIdentity Matrix3 Values (p. 744)
Quat Values (p. 738)
isKeySelected Controller Key Functions (p. 1294)
CS3Tools.cui Tutorial (p. 1825) - in example
isKindOf Working with Values (p. 716)
ObjectSet Values (p. 781) - in example
Structure Inherited Methods (p. 711)
join BitArray Values (p. 791)
Array Values (p. 776)
length
LnDif Quat Values (p. 738)
loadFrames
LogN Quat Values (p. 738)
merge XRefScene Values (p. 1038)
Zip-file Script Packages (p. 122)
NURBSSet : Value (p. 1450)
moveKey Controller Key Functions (p. 1294)
normalize Quat Values (p. 738)
Point3 Values (p. 731)
Point2 Values (p. 736)
Scripted Plug-in Methods (p. 1551) - in example
numEaseCurves Controller Ease and Multiplier Curve Functions (p. 1297)
numKeys Controller Key Functions (p. 1294)
numMultiplierCurves Controller Ease and Multiplier Curve Functions (p. 1297)
numSelKeys Controller Key Functions (p. 1294)
perspectiveMatch
QCompA Quat Values (p. 738)
qorthog Quat Values (p. 738)
random Number Values (p. 717)
Node Common Properties, Operators, and Methods (p. 820)
readChar FileStream Values (p. 763)
StringStream Values (p. 766)
readChars FileStream Values (p. 763)
StringStream Values (p. 766)
readDelimitedString FileStream Values (p. 763)
StringStream Values (p. 766)
 Const Generic 203

readExpr MAXScript System Globals (p. 640)

Value Common Properties, Operators, and Methods (p. 714)
FileStream Values (p. 763)
StringStream Values (p. 766)
readLine FileStream Values (p. 763)
StringStream Values (p. 766)
readValue FileStream Values (p. 763)
StringStream Values (p. 766)
Access to MAXWrapper AppData (p. 813) - in example
Encrypted Files (p. 1647) - in example
MAXScript System Globals (p. 640)
Node User-Defined Properties and Methods (p. 848) - in example
rectify Box2 Values (p. 750)
refine NURBSCVCurve : NURBSCurve (p. 1412)
NURBSCVSurface : NURBSSurface (p. 1433)
NURBSPointCurve : NURBSCurve (p. 1418)
NURBSPointSurface : NURBSSurface (p. 1441)
refineU NURBSCVSurface : NURBSSurface (p. 1433)
NURBSPointSurface : NURBSSurface (p. 1441)
refineV NURBSCVSurface : NURBSSurface (p. 1433)
NURBSPointSurface : NURBSSurface (p. 1441)
removeObject Modifying Existing NURBS Objects (p. 1390)
NURBSSet : Value (p. 1450)
renderMap Material Editor (p. 1606)
TextureMap Common Properties, Operators, and Methods (p. 1235)
reparameterize NURBSCVCurve : NURBSCurve (p. 1412)
NURBSCVSurface : NURBSSurface (p. 1433)
replace String Literals (p. 660)
resample
reset Curve Control (p. 170)
Flex interfaces: (p. 438)
resetZoom
save Bitmap Values (p. 755)
seek FileStream Values (p. 763)
StringStream Values (p. 766)
selectKey Controller Key Functions (p. 1294)
setAppData Access to MAXWrapper AppData (p. 813)
setCacheEntry
204 Chapter 1 | What’s New in 3ds max 4 MAXScript

setCurve NURBS1RailSweepSurface : NURBSSurface (p. 1427)

NURBS2RailSweepSurface : NURBSSurface (p. 1429)
NURBSULoftSurface : NURBSSurface (p. 1443)
setCurveByID NURBS1RailSweepSurface : NURBSSurface (p. 1427)
NURBS2RailSweepSurface : NURBSSurface (p. 1429)
NURBSULoftSurface : NURBSSurface (p. 1443)
setCurveStartPoint NURBS1RailSweepSurface : NURBSSurface (p. 1427)
NURBS2RailSweepSurface : NURBSSurface (p. 1429)
setCV NURBSCVCurve : NURBSCurve (p. 1412)
NURBSCVSurface : NURBSSurface (p. 1433)
Creating New NURBS Objects (p. 1389) - in example
setDisplacementMapping Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setEdge NURBSBlendSurface : NURBSSurface (p. 1430)
NURBSNBlendSurface : NURBSSurface (p. 1439)
setEdgeVis Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setface Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Working with Editable Meshes (p. 1077) – in example
setFaceMatID Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setfacenormal Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setFaceSmoothGroup Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setFade
setFlip NURBS1RailSweepSurface : NURBSSurface (p. 1427)
NURBS2RailSweepSurface : NURBSSurface (p. 1429)
NURBSULoftSurface : NURBSSurface (p. 1443)
path interfaces: (p. 462)
Path Constraint interfaces: (p. 468)
setFlipTrim NURBSFilletSurface : NURBSSurface (p. 1436)
setGenerateUVs NURBSSurface : NURBSObject (p. 1425)
setIndexedPixels Bitmap Files (p. 1641)
setKnot NURBSCVCurve : NURBSCurve (p. 1412)
Creating New NURBS Objects (p. 1389) – in example
setMesh Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Scripted SimpleObject Plug-ins (p. 1556) – in example
SetNonUniformScale BipedExportInterface Values (p. 1458)
setnormal Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setNumCPVVerts Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setNumFaces Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setNumTVerts Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setNumVerts Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Patches (p. 55)
 Const Generic 205

setObject NURBSSet : Value (p. 1450)

Modifying Existing NURBS Objects (p. 1390)
setParent NURBSBlendSurface : NURBSSurface (p. 1430)
NURBSFilletSurface : NURBSSurface (p. 1436)
NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438)
NURBSNBlendSurface : NURBSSurface (p. 1439)
setParentID NURBSBlendSurface : NURBSSurface (p. 1430)
NURBSFilletSurface : NURBSSurface (p. 1436)
NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438)
NURBSNBlendSurface : NURBSSurface (p. 1439)
setPixels Bitmap Files (p. 1641)
Scripted RenderEffect Plug-ins (p. 1566) – in example
setPoint Curve Control (p. 170)
NURBSPointCurve : NURBSCurve (p. 1418)
NURBSPointSurface : NURBSSurface (p. 1441)
NURBSTextureSurface : Value (p. 1455)
setProdTess NURBSSet : Value (p. 1450)
NURBSSurface : NURBSObject (p. 1425)
setRadius NURBSFilletSurface : NURBSSurface (p. 1436)
setSeed NURBSFilletSurface : NURBSSurface (p. 1436)
setSize BigMatrix Values (p. 748)
setSplitMesh Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setStruct
setSubdivisionDisplacement Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setTextureSurface NURBSSurface : NURBSObject (p. 1425)
NURBSTextureSurface : Value (p. 1455)
setTextureUVs NURBSSurface : NURBSObject (p. 1425)
Materials Assignment and Texture Coordinates (p. 1391)
setTiling NURBSSurface : NURBSObject (p. 1425)
setTilingOffset NURBSSurface : NURBSObject (p. 1425)
setTrimSurface NURBSFilletSurface : NURBSSurface (p. 1436)
settvert Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Working with Editable Meshes (p. 1077)
setTVFace Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Working with Editable Meshes (p. 1077)
setUCurve NURBSUVLoftSurface : NURBSSurface (p. 1444)
setUCurveByID NURBSUVLoftSurface : NURBSSurface (p. 1444)
setUKnot NURBSCVSurface : NURBSSurface (p. 1433)
setVCFace Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setVCurve NURBSUVLoftSurface : NURBSSurface (p. 1444)
206 Chapter 1 | What’s New in 3ds max 4 MAXScript

setVCurveByID NURBSUVLoftSurface : NURBSSurface (p. 1444)

setVert Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Patches (p. 55)
setVertColor Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setViewTess NURBSSet : Value (p. 1450)
NURBSSurface : NURBSObject (p. 1425)
setVKnot NURBSCVSurface : NURBSSurface (p. 1433)
showInterface Class and Object Inspector Functions (p. 159)
Trackviews (p. 114)
showInterfaces Class and Object Inspector Functions (p. 159)
List Controller (p. 143)
showProperties “Apropos” and “ShowProperties” and now “Help” and “Show” (p. 128)
Class and Object Inspector Functions (p. 799)
showTrack
skipToNextLine FileStream Values (p. 763)
StringStream Values (p. 766)
skipToString FileStream Values (p. 763)
StringStream Values (p. 766)
Slerp EulerAngles Values (p. 742)
Quat Values (p. 738)
sort Array Values (p. 776)
sortNoteKeys MAXNoteKeyArray Values (p. 817)
Working with Note Tracks (p. 818) - in example
squad Quat Values (p. 738)
substring String Literals (p. 660)
superClassOf Working with Values (p. 716)
Structure Inherited Methods (p. 711)
Value Common Properties, Operators, and Methods (p. 714)
Picking Scene Nodes By Hit (p. 1618)
supportsTimeOperations Controller Time Functions (p. 1292)
transform
transpose BigMatrix Values (p. 748)
unDisplay Bitmap Files (p. 1641)
update
updateXRef XRefObject : Node (p. 1037)
XRefScene Values (p. 1038)
XFormMat Matrix3 Values (p. 744)
zoom
 Const MappedGeneric 207

See Also
Definitions for MAXScript internal organization (p. 188)

Const MappedGeneric
addEaseCurve Controller Ease and Multiplier Curve Functions (p. 1297)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
addNewKey MAXKey Common Properties, Operators, and Methods (p. 768)
deleteEaseCurve Controller Ease and Multiplier Curve Functions (p. 1297)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
deleteKeys MAXKeyArray Values (p. 793)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
Controller Key Functions (p. 1294)
deleteTime Controller Time Functions (p. 1292)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
deselectKeys Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
Controller Key Functions (p. 1294)
enableORTs Controller Out-Of-Range Functions (p. 1296)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
Identity BigMatrix Values (p. 748)
insertTime Controller Time Functions (p. 1292)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
mapKeys mapKeys() method (p. 144)
moveKeys MAXKeyArray Values (p. 793)
Controller Key Functions (p. 1294)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
Orthogonalize Matrix3 Values (p. 744)
PreRotate Matrix3 Values (p. 744)
PreRotateX Matrix3 Values (p. 744)
PreRotateY Matrix3 Values (p. 744)
PreRotateZ Matrix3 Values (p. 744)
PreScale Matrix3 Values (p. 744)
208 Chapter 1 | What’s New in 3ds max 4 MAXScript

PreTranslate Matrix3 Values (p. 1299)

print Value Common Properties, Operators, and Methods (p. 714)
reduceKeys Controller Key Reducer (p. 1299)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
reverseTime Controller Time Functions (p. 1292)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
RotateX Matrix3 Values (p. 744)
RotateY Matrix3 Values (p. 744)
RotateZ Matrix3 Values (p. 744)
scaleTime Controller Time Functions (p. 1292)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
selectKeys Controller Key Functions (p. 1294)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
Attachment : PositionController (p. 1304)
setAfterORT Controller Ease and Multiplier Curve Functions (p. 1297)
Controller Out-Of-Range Functions (p. 1296)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
setBeforeORT Names (p. 657)
Controller Ease and Multiplier Curve Functions (p. 1297)
Controller Out-Of-Range Functions (p. 1296)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies
setTimeRange Controller Time Functions (p. 1292)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies
sortKeys MAXKeyArray Values (p. 793)
Controller Key Functions (p. 1294)
Nested Object Controller Functions (p. 814)
Time and Key Functions on Object Hierarchies (p. 1299)
Working with MAXKey Values (p. 769)
Working with Note Tracks (p. 818)
Translate Matrix3 Values (p. 744)
Box2 Values (p. 750)
Zero
 Const NodeGeneric 209

See Also
Definitions for MAXScript internal organization (p. 188)

Const NodeGeneric
addAndWeld SplineShape : Shape (p. 1079)
addKnot SplineShape : Shape (p. 1079)
addModifier
addNewSpline SplineShape : Shape (p. 1079)
addNURBSSet Modifying Existing NURBS Objects (p. 1390)
NURBS Node Properties and Methods (p. 1397)
Parameter Ranges for Curves and Surfaces (p. 1391)
bindKnot SplineShape : Shape (p. 1079)
bindSpaceWarp
breakCurve NURBS Node Properties and Methods (p. 1397)
breakSurface Modifying Existing NURBS Objects (p. 1390)
NURBS Node Properties and Methods (p. 1397)
collapseStack Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Modifier Common Properties, Operators, and Methods (p. 1096)
Node Common Properties, Operators, and Methods (p. 820)
Patch : GeometryClass (p. 1088)
convertTo Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Node Common Properties, Operators, and Methods (p. 820)
NURBS Node Properties and Methods (p. 1397)
Patch : GeometryClass (p. 1088)
Patches (p. 55)
convertToMesh
convertToNURBSCurve Collections (p. 773)
Node Common Properties, Operators, and Methods (p. 820)
NURBS Node Properties and Methods (p. 1397)
convertToNURBSSurface Node Common Properties, Operators, and Methods (p. 820)
NURBS Node Properties and Methods (p. 1397)
convertToPoly
convertToSplineShape Modifier Common Properties, Operators, and Methods (p. 1096)
Node Common Properties, Operators, and Methods (p. 820)
NURBS Node Properties and Methods (p. 1397)
Scripting Vertex and Control Point Animation (p. 1461)
Section : Shape (p. 959)
SplineShape : Shape (p. 1079)
copy
210 Chapter 1 | What’s New in 3ds max 4 MAXScript

curveLength Shape Common Properties, Operators, and Methods (p. 945)

deleteKnot SplineShape : Shape (p. 1079)
deleteModifier Modifier Common Properties, Operators, and Methods (p. 1096)
Node Common Properties, Operators, and Methods (p. 820)
deleteSpline SplineShape : Shape (p. 1079)
Modifier and SpacewarpModifier Types (p. 1100)
deselect
flagForeground Node Common Properties, Operators, and Methods (p. 820)
Scripted Atmospheric Plug-ins (p. 1569) - in example
Slider (p. 1507)
Spinner (p. 1509)
freeze
getEdgeSelection Edit Mesh : Modifier (p. 1114)
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Mesh Select : Modifier (p. 1142)
polyop const StructDef (p. 248)
getFaceSelection Edit Mesh : Modifier (p. 1114)
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Mesh Select : Modifier (p. 1142)
polyop const StructDef (p. 248)
getInVec SplineShape : Shape (p. 1079)
getKnotPoint SplineShape : Shape (p. 1079)
getKnotType SplineShape : Shape (p. 1079)
getNURBSSet
getOutVec SplineShape : Shape (p. 1079)
getSegmentType SplineShape : Shape (p. 1079)
getUserProp Node Common Properties, Operators, and Methods (p. 820)
Node User-Defined Properties and Methods (p. 848)
getUserPropBuffer Node Common Properties, Operators, and Methods (p. 820)
Node User-Defined Properties and Methods (p. 848)
getVertSelection Edit Mesh : Modifier (p. 1114)
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Mesh Select : Modifier (p. 1142)
polyop const StructDef (p. 248)
hide
hideSelectedSegments
hideSelectedSplines
hideSelectedVerts
instance
instanceReplace Node Common Properties, Operators, and Methods (p. 820)
 Const NodeGeneric 211

intersectRay mouseTrack() Function (p. 180)

Node Common Properties, Operators, and Methods (p. 820)
intersects Node Common Properties, Operators, and Methods (p. 820)
Scripted Manipulator (p. 97)
isClosed NURBSCurve : NURBSObject (p. 1409)
SplineShape : Shape (p. 1079)
isDeleted Node Common Properties, Operators, and Methods (p. 820) - in example with def
PathName Values (p. 780) - in example with def
joinCurves NURBS Node Properties and Methods (p. 1397)
joinSurfaces NURBS Node Properties and Methods (p. 1397)
lengthInterp Shape Common Properties, Operators, and Methods (p. 945)
lengthTangent Shape Common Properties, Operators, and Methods (p. 945)
lengthToPathParam Shape Common Properties, Operators, and Methods (p. 945)
makeIndependent NURBS Node Properties and Methods (p. 1397)
materialID Bitmap Values (p. 755)
MaterialModifier : Modifier (p. 1137)
SplineShape : Shape (p. 1079)
move
nearestPathParam Shape Common Properties, Operators, and Methods (p. 945)
numKnots NURBSCVCurve : NURBSCurve (p. 1412)
Creating New NURBS Objects (p. 1389) – in example
Shape Common Properties, Operators, and Methods (p. 945)
SplineShape : Shape (p. 1079)
numSegments SplineShape : Shape (p. 1079)
numSplines SplineShape : Shape (p. 1079)
open
particleAge Particle System Common Properties, Operators, and Methods (p. 905)
particleCount Particle System Common Properties, Operators, and Methods (p. 905)
particlePos Particle System Common Properties, Operators, and Methods (p. 905)
particleSize Particle System Common Properties, Operators, and Methods (p. 905)
particleVelocity Particle System Common Properties, Operators, and Methods (p. 905)
pathInterp Particle System Common Properties, Operators, and Methods (p. 905)
pathTangent Particle System Common Properties, Operators, and Methods (p. 905)
pathToLengthParam Shape Common Properties, Operators, and Methods (p. 945)
printstack Node Common Properties, Operators, and Methods (p. 820)
reference
referenceReplace Node Common Properties, Operators, and Methods (p. 820)
refineSegment SplineShape : Shape (p. 1079)
resetShape SplineShape : Shape (p. 1079)
212 Chapter 1 | What’s New in 3ds max 4 MAXScript

reverse
rotate
scale
select
selectmore Node Common Properties, Operators, and Methods (p. 820)
ObjectSet Values (p. 781) - In Example With Def
setEdgeSelection polyop const StructDef (p. 248)
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) - In Example
setFaceSelection polyop const StructDef (p. 248)
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) - In Example
setFirstKnot SplineShape : Shape (p. 1079)
setFirstSpline SplineShape : Shape (p. 1079)
setInVec SplineShape : Shape (p. 1079)
setKnotPoint SplineShape : Shape (p. 1079)
setKnotType SplineShape : Shape (p. 1079)
setOutVec SplineShape : Shape (p. 1079)
setRenderApproximation NURBS Node Properties and Methods (p. 1397)
NURBSSurfaceApproximation : Value (p. 1453)
setSegmentType SplineShape : Shape (p. 1079)
setSurfaceDisplay NURBS Node Properties and Methods (p. 1397)
NURBSSurfaceApproximation : Value (p. 1453)
setUserProp Node Common Properties, Operators, and Methods (p. 820)
Node User-Defined Properties and Methods (p. 848) - In Example With Def
setUserPropBuffer Node Common Properties, Operators, and Methods (p. 820)
Node User-Defined Properties and Methods (p. 848) - In Example With Def
setVertSelection Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) - In Example With Def
polyop const StructDef (p. 248)
setViewApproximation NURBS Node Properties and Methods (p. 1397)
NURBSSurfaceApproximation : Value (p. 1453)
snapShot Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Node Common Properties, Operators, and Methods (p. 820)
unbindKnot SplineShape : Shape (p. 1079)
unfreeze MAX Commands (p. 1630)
MAX Commands in MAXScript (p. 620)
Node Common Properties, Operators, and Methods (p. 820)
Unwrap UVW interfaces: (p. 530)
UVWUnwrap interfaces: (p. 568)
Visual MAXScript (p. 117)
unhide
unhideSegments SplineShape : Shape (p. 1079)
 Const Primitives 213

updateBindList SplineShape : Shape (p. 1079)

updateShape SplineShape : Shape (p. 1079)

See Also
Definitions for MAXScript internal organization (p. 188)

Const Primitives
All known const Primitives.

acos Number Values (p. 717)

addAtmospheric Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
addEffect Render Effects Common Properties, Operators, and Methods (p. 1347)
addMorphTarget Barycentric Morph Controller : MorphController (p. 1306)
addNoteTrack Notetrack Values (p. 816)
Working with Note Tracks (p. 818)
addRollout Utility Clauses (p. 1466)
Managing Multiple Rollouts in a Scripted Utility (p. 1468)
Rollout Floater Windows (p. 1477)
Scripted Utilities (p. 1463)
Utility and Rollout Properties, Methods, and Event Handlers (p. 1474)
addTrackViewController Track View Nodes (p. 1382)
affectRegionVal Affect Region Function (p. 127)
amax Array Values (p. 776)
amin Array Values (p. 776)
animateAll Scripting Vertex and Control Point Animation (p. 1461)
Modifier Sub-Object Transform Properties (p. 1099)
animateVertex SplineShape : Shape (p. 1079)
Scripting Vertex and Control Point Animation (p. 1461)
Modifier Sub-Object Transform Properties (p. 1099)
appendSubSelSet Main Toolbar (p. 1574)
apropos Class and Object Inspector Functions (p. 799)
“Apropos” and “ShowProperties” and now “Help” and “Show” (p. 128)
arbAxis Point3 Values (p. 731)
asin Number Values (p. 717)
assignNewName Material Common Properties, Operators, and Methods (p. 1203)
atan Number Values (p. 717)
atan2 Number Values (p. 717)
attachObjects Node Common Properties, Operators, and Methods (p. 820)
214 Chapter 1 | What’s New in 3ds max 4 MAXScript

averageSelVertCenter Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)

averageSelVertNormal Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
axisTripodLocked Miscellaneous Viewport Methods and System Globals (p. 1603)
boxPickNode Picking Scene Nodes By Region (p. 1620)
break
ceil Number Values (p. 717)
checkForSave 3ds max File Loading and Saving (p. 1639)
circlePickNode Picking Scene Nodes By Region (p. 1620)
clearCurSelSet Main Toolbar (p. 1574)
clearListener Controlling the Listener Contents and the Insertion Point (p. xlii)
clearNodeSelection Node Common Properties, Operators, and Methods (p. 820)
clearSelection ObjectSet Values (p. 781)
Node Common Properties, Operators, and Methods (p. 820)
Trackviews (p. 114)
ClearSubSelSets Main Toolbar (p. 1574)
clearUndoBuffer undo (p. 687)
Exiting and Resetting 3ds max (p. 1669)
closelog Turning On the Listener Log (p. xli)
closeRolloutFloater Rollout Floater Windows (p. 1477)
closeUtility Utility and Rollout Properties, Methods, and Event Handlers (p. 1474)
completeRedraw Refreshing the Viewports (p. 1585)
configureBitmapPaths Miscellaneous Dialogs (p. 1621)
conformToShape FFD 2x2x2 : Modifier (p. 1121)
FFD 3x3x3 : Modifier (p. 1123)
FFD 4x4x4 : Modifier (p. 1124)
FFD Box : Modifier (p. 1117)
FFD Cyl : Modifier (p. 1119)
copyFile External File Methods (p. 1645)
cos Trigonometric Functions (p. 1675)
Function Variables (p. 701)
Number Values (p. 717)
cosh Mathematical Operations in MAXScript (p. 588)
Number Values (p. 717)
CreateDialog CreateDialog (p. 169)
createfile FileStream Values (p. 763)
Encrypted Files (p. 1647)
createLockKey Controller Key Functions (p. 1294)
 Const Primitives 215

createMorphObject Barycentric Morph Controller : MorphController (p. 1306)

Barycentric Morph Controller Keys (p. 1308)
Morph : GeometryClass (p. 891)
createOLEObject OLE Automation (p. 1671)
createPreview Miscellaneous Viewport Methods and System Globals (p. 1603)
createReaction Reactor Controllers (p. 1326)
degToRad Number Values (p. 717)
deleteAllChangeHandlers Change Handlers and When Constructs (p. 1650)
deleteAtmospheric Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
deleteChangeHandler Change Handlers and When Constructs (p. 1650)
deleteEffect Render Effects Common Properties, Operators, and Methods (p. 1347)
deleteFile External File Methods (p. 1645)
deleteMorphTarget Barycentric Morph Controller : MorphController (p. 1306)
deleteNoteTrack Notetrack Values (p. 816)
Working with Note Tracks (p. 818)
deleteReaction Reactor Controllers (p. 1326)
deleteTrackViewController Track View Nodes (p. 1382)
deleteTrackViewNode Track View Nodes (p. 1382)
dependsOn dependsOn For Scripted Controllers (p. 95)
deselectHiddenEdges Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
deselectHiddenFaces Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
deselectNode Node Common Properties, Operators, and Methods (p. 820)
DestroyDialog CreateDialog (p. 169)
DisableSceneRedraw Refreshing the Viewports (p. 1585)
disableStatusXYZ Coordinate Display (p. 1578)
displayControlDialog Controller Common Properties, Operators, and Methods (p. 1289)
displayTempPrompt Prompt Line (p. 1577)
doesFileExist File Name Parsing (p. 1644)
DOSCommand Executing External Commands (p. 1668)
dumpMAXStrings
editAtmosphere Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
editAtmospheric Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
editEffect Render Effects Common Properties, Operators, and Methods (p. 1347)
enableCoordCenter Main Toolbar (p. 1574)
enableRefCoordSys Main Toolbar (p. 1574)
EnableSceneRedraw Refreshing the Viewports (p. 1585)
enableShowEndRes Modify Panel (p. 1572)
enableStatusXYZ Coordinate Display (p. 1578)
216 Chapter 1 | What’s New in 3ds max 4 MAXScript

enableSubObjSel Modify Panel (p. 1572)

enableUndo Main Toolbar (p. 1574)
encryptFile Encrypted Files (p. 1647)
encryptScript Encrypting Script Files (p. lx)
enumerateFiles Bitmap Files (p. 1641)
BitmapTexture : TextureMap (p. 1243)
eulerToQuat Quat Values (p. 738)
EulerAngles Values (p. 742)
exclusionListDlg Miscellaneous Dialogs (p. 1621)
explodeGroup Node Common Properties, Operators, and Methods (p. 820)
exportFile 3ds max File Loading and Saving (p. 1639)
fclose BinStream for Binary Reading and Writing (p. 128)
fencePickNode Picking Scene Nodes By Region (p. 1620)
fetchMaxFile 3ds max File Loading and Saving (p. 1639)
filein Zip-file Script Packages (p. 122)
Running Scripts (p. xlix)
Including Scripts Within Scripts (p. lix)
Creating Functions (p. 699)
Encrypting Script Files (p. lx)
Symbolic Pathnames (p. 140)
filenameFromPath File Name Parsing (p. 1644)
fileOpenMatLib Material Editor (p. 1606)
MaterialLibrary Values (p. 795)
fileSaveAsMatLib Material Editor (p. 1606)
MaterialLibrary Values (p. 795)
fileSaveMatLib Material Editor (p. 1606)
MaterialLibrary Values (p. 795)
filterString String Values (p. 722)
flashNodes Miscellaneous Viewport Methods and System Globals (p. 1603)
floor Number Literals (p. 660)
flushlog Turning On the Listener Log (p. xli)
fopen BinStream for Binary Reading and Writing (p. 128)
ForceCompleteRedraw Refreshing the Viewports (p. 1585)
format StringStream Values (p. 766)
fractalNoise Color Values (p. 729)
Point3 Values (p. 731)
freeSceneBitmaps Bitmap Values (p. 755)
BitmapTexture : TextureMap (p. 1243)
Miscellaneous Functions (p. 1663)
 Const Primitives 217

freezeSelection Status Bar Buttons (p. 1579)

fseek BinStream for Binary Reading and Writing (p. 128)
ftell BinStream for Binary Reading and Writing (p. 128)
gc Manual Garbage Collection (p. 656)
Bitmap Values (p. 755)
genClassID Scripted Plug-ins (p. 1538)
Scripted Custom Attributes (p. 45)
getActiveCamera Accessing Active Viewport Info, Type, and Transforms (p. 1581)
Defining Macro Scripts (p. 1521)
Viewport Drawing Methods (p. 1592)
getAtmospheric Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
Setting explosion start and end times for Combustion (p. 1341)
getBackGround SetBackground Method (p. 180)
getBackGroundController Working with Atmospherics (p. 1345)
getBipedExportInterface BipedExportInterface Values (p. 1458)
getBitmapOpenFileName Bitmap Values (p. 755)
getBitmapSaveFileName Bitmap Values (p. 755)
getBkgFrameNum Viewport Background Images (p. 1586)
getBkgImageAnimate Viewport Background Images (p. 1586)
getBkgImageAspect Viewport Background Images (p. 1586)
getBkgORType Viewport Background Images (p. 1586)
getBkgRangeVal Viewport Background Images (p. 1586)
getBkgStartTime Viewport Background Images (p. 1586)
getBkgSyncFrame Viewport Background Images (p. 1586)
getCommandPanelTaskMode Command Panels (p. 1571)
getCoordCenter Main Toolbar (p. 1574)
Node Common Properties, Operators, and Methods (p. 820) – in example
getCoreInterfaces Interfaces (p. 67)
getCPTM Accessing Active Viewport Info, Type, and Transforms (p. 1581)
getCrossing Status Bar Buttons (p. 1579)
getCurNameSelSet
getCurrentSelection Collections (p. 773)
ObjectSet Values (p. 781)
getCVertMode Node Common Properties, Operators, and Methods (p. 820)
GetDefaultUIColor 3ds max User Interface Colors (p. 1604)
GetDialogPos -jprBuild: M023-Title: Added Simon Feltman’s CtrlLib classes to MXSAgni
getDimensions FFD Box : Modifier (p. 1117)
FFD Cyl : Modifier (p. 1119)
218 Chapter 1 | What’s New in 3ds max 4 MAXScript

GetDir 3ds max System Directories (p. 1625)

SetDir (p. 136)
getDirectories External File Methods (p. 1645)
GetDisplayFilter Selection Filter (p. 61)
getEffect Render Effects Common Properties, Operators, and Methods (p. 1347)
getEulerMatAngleRatio EulerAngles Values (p. 742)
Matrix3 Values (p. 744)
getEulerQuatAngleRatio Quat Values (p. 738)
EulerAngles Values (p. 742)
getFileAttribute External File Methods (p. 1645)
getFileCreateDate External File Methods (p. 1645)
getFileModDate External File Methods (p. 1645)
getFilenameFile Viewport Drawing Methods (p. 1592)
File Name Parsing (p. 1644)
External File Methods (p. 1645)
Defining Macro Scripts (p. 1521)
getFilenamePath File Name Parsing (p. 1644)
getFilenameType External File Methods (p. 1645)
File Name Parsing (p. 1644)
getFiles External File Methods (p. 1645)
getFileVersion External File Methods (p. 1645)
getGridMajorLines Viewport Grids (p. 1587)
getGridSpacing Viewport Grids (p. 1587)
getHashValue Value Common Properties, Operators, and Methods (p. 714)
getImageBlurMultController Node Common Properties, Operators, and Methods (p. 820)
General Node Properties (p. 836)
getInheritanceFlags Node Common Properties, Operators, and Methods (p. 820)
getInheritVisibility Node Common Properties, Operators, and Methods (p. 820)
getINISetting Accessing INI File Keys (p. 1647)
getKBChar Keyboard Entry (p. 1623)
getKBLine Keyboard Entry (p. 1623)
getKBPoint Keyboard Entry (p. 1623)
getKBValue Keyboard Entry (p. 1623)
getKeyStepsPos Time Configuration Dialog (p. 1616)
getKeyStepsRot Time Configuration Dialog (p. 1616)
getKeyStepsScale Time Configuration Dialog (p. 1616)
getKeyStepsSelOnly Time Configuration Dialog (p. 1616)
getKeyStepsUseTrans Time Configuration Dialog (p. 1616)
getKnotSelection SplineShape : Shape (p. 1079)
 Const Primitives 219

getListenerSel Controlling the Listener Contents and the Insertion Point (p. xlii)
getListenerSelText Controlling the Listener Contents and the Insertion Point (p. xlii)
getMaterialID SplineShape : Shape (p. 1079)
getMatLibFileName Material Editor (p. 1606)
MaterialLibrary Values (p. 795)
getMAXFileObjectNames 3ds max File Loading and Saving (p. 1639)
Zip-file Script Packages (p. 122)
getMAXOpenFileName MAX Open & Save Dialogs (p. 177)
getMAXSaveFileName MAX Open & Save Dialogs (p. 177)
getMeditMaterial Material Common Properties, Operators, and Methods (p. 1203)
Material Editor (p. 1606)
MaterialLibrary Values (p. 795)
getMKKey Barycentric Morph Controller : MorphController (p. 1306)
Barycentric Morph Controller Keys (p. 1308)
getMKKeyIndex Barycentric Morph Controller : MorphController (p. 1306)
getMKTargetNames Barycentric Morph Controller : MorphController (p. 1306)
getMKTargetWeights Barycentric Morph Controller : MorphController (p. 1306)
getMKTime Barycentric Morph Controller Keys (p. 1308)
getMKWeight Barycentric Morph Controller Keys (p. 1308)
getMTLMEditFlags Material Common Properties, Operators, and Methods (p. 1203)
getMTLMeditObjType Material Common Properties, Operators, and Methods (p. 1203)
getMTLMeditTiling Material Common Properties, Operators, and Methods (p. 1203)
getNamedSelSetItem SelectionSetArray Values (p. 783)
getNamedSelSetItemCount SelectionSetArray Values (p. 783)
getNamedSelSetName SelectionSetArray Values (p. 783)
getNodeByName Node Common Properties, Operators, and Methods (p. 820)
getNoteTrack Notetrack Values (p. 816)
MAXNoteKeyArray Values (p. 817)
Working with Note Tracks (p. 818)
getNumAxis Main Toolbar (p. 1574)
getNumberDisplayFilters Selection Filter (p. 61)
getNumberSelectFilters Selection Filter (p. 61)
getNumNamedSelSets SelectionSetArray Values (p. 783)
getOpenFileName Standard Open and Save File Dialogs (p. 1643)
ActiveX Controls in MAXScript Rollouts (p. 10) – in example
getPatchSteps Patch : GeometryClass (p. 1088)
getPhyContextExport Biped and Physique (p. 1456)
PhyContextExport Values (p. 1458)
getPointController Controller Common Properties, Operators, and Methods (p. 1289)
220 Chapter 1 | What’s New in 3ds max 4 MAXScript

getPointControllers Controller Common Properties, Operators, and Methods (p. 1289)

getPolygonCount
getPosTaskWeight
getProgressCancel
getProperty
getPropertyController
getReactionCount
getReactionFalloff
getReactionInfluence
getReactionName
getReactionState
getReactionStrength
getReactionValue
getRefCoordSys
getRendApertureWidth
getRenderID
getRendImageAspect
getRotTaskWeight
getSaveFileName
getSavePath
getSaveRequired
getScreenScaleFactor
getSegLengths
getSegSelection
getSelectedReactionNum
GetSelectFilter
getShadeCVerts
getSnapMode
getSnapState
getSplineSelection
getTaskAxisState
getTextExtent
Node Common Properties, Operators, and Methods (p. 820)
Node Common Properties, Operators, and Methods (p. 820)
Progress Bar Display (p. 1578)
Class and Object Inspector Functions (p. 799)
Curve Control (p. 170) - in example
ActiveX Controls in MAXScript Rollouts (p. 10) - in example
Class and Object Inspector Functions (p. 799)
Reactor Controllers (p. 1326)
Reactor Controllers (p. 1326)
Reactor Controllers (p. 1326)
Reactor Controllers (p. 1326)
Reactor controller (p. 91) - in example
Reactor Controllers (p. 1326)
Reactor Controllers (p. 1326)
Reactor controller (p. 91) - in example
Reactor Controllers (p. 1326)
Main Toolbar (p. 1574)
Render Scene Dialog (p. 1611)
Node Common Properties, Operators, and Methods (p. 820)
Render Scene Dialog (p. 1611)
Node Common Properties, Operators, and Methods (p. 820)
Standard Open and Save File Dialogs (p. 1643)
Viewport Drawing Methods (p. 1592) - in example
Defining Macro Scripts (p. 1521) - in example
Standard Open and Save File Dialogs (p. 1643)
Exiting and Resetting 3ds max (p. 1669)
undo (p. 687)
Accessing Active Viewport Info, Type, and Transforms (p. 1581)
SplineShape : Shape (p. 1079)
SplineShape : Shape (p. 1079)
Reactor Controllers (p. 1326)
Selection Filter (p. 61)
Node Common Properties, Operators, and Methods (p. 820)
Status Bar Buttons (p. 1579)
Status Bar Buttons (p. 1579)
SplineShape : Shape (p. 1079)
Node Common Properties, Operators, and Methods (p. 820)
getTextExtent (p. 175)
 Const Primitives 221

GetTMController
gettoolbtnstate Main Toolbar (p. 1574)
getTrajectoryOn Node Common Properties, Operators, and Methods (p. 820)
getTransformAxis Node Common Properties, Operators, and Methods (p. 820)
getTransformLockFlags Node Common Properties, Operators, and Methods (p. 820)
GetUIColor 3ds max User Interface Colors (p. 1604)
getUseDraftRenderer Render Scene Dialog (p. 1611)
getUseEnvironmentMap Working with Atmospherics (p. 1345)
getViewFOV Accessing Active Viewport Info, Type, and Transforms (p. 1581)
getViewSize Accessing Active Viewport Info, Type, and Transforms (p. 1581)
ActiveX Controls in MAXScript Rollouts (p. 10) - in example
getViewTM Accessing Active Viewport Info, Type, and Transforms (p. 1581)
getVisController General Node Properties (p. 836)
Node Common Properties, Operators, and Methods (p. 820)
getVPortBGColor Miscellaneous Viewport Methods and System Globals (p. 1603)
getXYZControllers XYZ Controllers (p. 1335)
group Node Common Properties, Operators, and Methods (p. 820)
hasNoteTracks Notetrack Values (p. 816)
Working with Note Tracks (p. 818) - in example
hasProperty hasProperty() function (p. 135)
HitByNameDlg Main Toolbar (p. 1574)
holdMaxFile 3ds max File Loading and Saving (p. 1639)
importFile Zip-file Script Packages (p. 122)
3ds max File Loading and Saving (p. 1639)
include Including Scripts Within Scripts (p. lix)
Symbolic Pathnames (p. 140)
insertItem Array Values (p. 776)
interpCurve3D SplineShape : Shape (p. 1079)
intersectRayEx Node Common Properties, Operators, and Methods (p. 820)
invalidateTM Node Common Properties, Operators, and Methods (p. 820)
invalidateTreeTM Node Common Properties, Operators, and Methods (p. 820)
invalidateWS Node Common Properties, Operators, and Methods (p. 820)
isActive
isBoneOnly Node Common Properties, Operators, and Methods (p. 820)
isController Value Common Properties, Operators, and Methods (p. 714)
isCPEdgeOnInView Miscellaneous Viewport Methods and System Globals (p. 1603)
isCreatingObject
isGroupHead Node Common Properties, Operators, and Methods (p. 820)
222 Chapter 1 | What’s New in 3ds max 4 MAXScript

isGroupMember Node Common Properties, Operators, and Methods (p. 820)

IsNetServer Miscellaneous Functions (p. 1663)
isOpenGroupHead Node Common Properties, Operators, and Methods (p. 820)
isOpenGroupMember Node Common Properties, Operators, and Methods (p. 820)
IsPointSelected Node Common Properties, Operators, and Methods (p. 820)
NURBS Node Properties and Methods (p. 1397)
isreadOnly
isSceneRedrawDisabled Refreshing the Viewports (p. 1585)
isSelectionFrozen Status Bar Buttons (p. 1579)
IsShapeObject Node Common Properties, Operators, and Methods (p. 820)
isStruct Value Common Properties, Operators, and Methods (p. 714)
isStructDef Value Common Properties, Operators, and Methods (p. 714)
IsSubSelEnabled Modify Panel (p. 1572)
isSurfaceUVClosed Node Common Properties, Operators, and Methods (p. 820)
LoadDefaultMatLib Material Editor (p. 1606)
MaterialLibrary Values (p. 795)
loadDllsFromDir Miscellaneous Functions (p. 1663)
loadMaterialLibrary Material Editor (p. 1606)
MaterialLibrary Values (p. 795)
Zip-file Script Packages (p. 122)
loadMaxFile 3ds max File Loading and Saving (p. 1639)
Zip-file Script Packages (p. 122)
Running Scripts from the Command Line (p. lvii) - in example
Mouse Cursors (p. 1588) - in example
External File Methods (p. 1645) - in example
locals Visibility of Locals, Functions, Structures and User-Interface Items in Rollout Code
(p. 1478)
What’s New in MAXScript (p. 1)
Viewport Redraw Callback Mechanism (p. 1655)
Time Change Callback Mechanism (p. 1654)
String Values (p. 722)
Scripted Plug-in Clauses (p. 1542)
Scripted Custom Attributes (p. 45)
Script Controllers (p. 1329)
Scope of Variables (p. 646)
lockAxisTripods Miscellaneous Viewport Methods and System Globals (p. 1603)
log Number Values (p. 717)
log10 Number Values (p. 717)
makeDir External File Methods (p. 1645)
MakeNURBSConeSurface Creating NURBSCVSurface Values (p. 1394)
 Const Primitives 223

MakeNURBSCylinderSurface Creating NURBSCVSurface Values (p. 1394)

MakeNURBSLatheSurface Creating NURBSCVSurface Values (p. 1394)
MakeNURBSSphereSurface Creating NURBSCVSurface Values (p. 1394)
MakeNURBSTorusSurface Creating NURBSCVSurface Values (p. 1394)
mapScreenToCP Accessing Active Viewport Info, Type, and Transforms (p. 1581)
mapScreenToView Accessing Active Viewport Info, Type, and Transforms (p. 1581)
mapScreenToWorldRay Accessing Active Viewport Info, Type, and Transforms (p. 1581)
matchPattern String Values (p. 722)
ActiveX Controls in MAXScript Rollouts (p. 10) - in example
MaterialBrowseDlg Miscellaneous Dialogs (p. 1621)
MatrixFromNormal Matrix3 Values (p. 744)
Point3 Values (p. 731)
maxVersion Miscellaneous Functions (p. 1663)
mergeMaxFile Node Common Properties, Operators, and Methods (p. 820)
3ds max File Loading and Saving (p. 1639)
Zip-file Script Packages (p. 122)
messageBox MAXScript Message and Query Dialogs (p. 1622)
mirrorIKConstraints Node Common Properties, Operators, and Methods (p. 820)
mod MAX Commands (p. 1630)
mouseTrack mouseTrack() Function (p. 180)
namedSelSetListChanged Main Toolbar (p. 1574)
newRolloutFloate Rollout Floater Windows (p. 1477)
Scripted Utilities (p. 1463)
Curve Control (p. 170) - in example
newScript WindowStream Values (p. 767)
The MAXScript Editor Windows (p. xliv)
newTrackViewNode Track View Nodes (p. 1382)
nodeColorPicker Miscellaneous Dialogs (p. 1621)
nodeIKParamsChanged Node Common Properties, Operators, and Methods (p. 820)
nodeInvalRect Refreshing the Viewports (p. 1585)
Node Common Properties, Operators, and Methods (p. 820) - in example
noise3 Color Values (p. 729)
Point3 Values (p. 731)
noise4 Color Values (p. 729)
Point3 Values (p. 731)
normtime Time Values (p. 751)
numMapsUsed Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
numNoteTracks Notetrack Values (p. 816)
Working with Note Tracks (p. 818) - in example
224 Chapter 1 | What’s New in 3ds max 4 MAXScript

numSurfaces Node Common Properties, Operators, and Methods (p. 820)

NURBSExtrudeNode Creating NURBS Scene Objects (p. 1392)
NURBSLatheNode Creating NURBS Scene Objects (p. 1392)
NURBSNode Using the NURBS Classes and Functions to Create and Modify 3ds max NURBS
Models (p. 1389)
OkMtlForScene Interface: medit (p. 371)
OKToBindToNode Node Common Properties, Operators, and Methods (p. 820)
openBitMap Bitmap Values (p. 755)
openCTBitMap
openEncryptedFile FileStream Values (p. 763)
Encrypted Files (p. 1647)
openfile Function Parameters (p. 702) - in example
FileStream Values (p. 763)
openlog Turning On the Listener Log (p. xli)
openUtility Utility and Rollout Properties, Methods, and Event Handlers (p. 1474)
pickObject startObjectCreation() (p. 138)
RubberBanding in pickObject() Function (p. 136)
Picking Scene Nodes By Hit (p. 1618)
pickOffsetDistance Picking Points in the Viewports (p. 1589)
pickPoint Keyboard Entry (p. 1623)
Picking Points in the Viewports (p. 1589)
playAnimation Time Control (p. 1580)
pointSelection NURBS Node Properties and Methods (p. 1397)
Node Common Properties, Operators, and Methods (p. 820)
popPrompt Prompt Line (p. 1577)
popupMenu
pow Number Values (p. 717)
progressEnd Progress Bar Display (p. 1578)
progressStart Progress Bar Display (p. 1578)
progressUpdate Progress Bar Display (p. 1578)
PushPrompt Prompt Line (p. 1577)
qsort Array Values (p. 776)
quatToEuler EulerAngles Values (p. 742)
Quat Values (p. 738)
queryBox MAXScript Message and Query Dialogs (p. 1622)
quitMax Running Scripts from the Command Line (p. lvii)
Exiting and Resetting 3ds max (p. 1669)
radToDeg Number Values (p. 717)

reactTo
ReadByte
ReadFloat
ReadLong
ReadShort
ReadString
redrawViews
registerDisplayFilterCallback
registerOLEInterface
registerRedrawViewsCallback
registerRightClickMenu
registerSelectFilterCallback
registerTimeCallback
registerViewWindow
releaseAllOLEObjects
releaseOLEObject
removeRollout
removeTempPrompt
renameFile
render
replaceInstances
replacePrompt
rescaleWorldUnits
Const Primitives 225
Reactor controller (p. 91)
Reactor Controllers (p. 1326)
BinStream for Binary Reading and Writing (p. 128)
BinStream for Binary Reading and Writing (p. 128)
BinStream for Binary Reading and Writing (p. 128)
BinStream for Binary Reading and Writing (p. 128)
BinStream for Binary Reading and Writing (p. 128)
Refreshing the Viewports (p. 1585)
Picking Points in the Viewports (p. 1589)
Node Common Properties, Operators, and Methods (p. 820) - in example
Change Handlers and When Constructs (p. 1650)
Exposing MAXScript Functions (p. 1673)
Running the OLE Demo (p. 1674)
Viewport Redraw Callback Mechanism (p. 1655)
Scripted Right-Click Menus (p. 1514)
subMenu (p. 1520) - in example
separator (p. 1519) - in example
menuItem (p. 1518) - in example
class id filter (p. 59)
Time Change Callback Mechanism (p. 1654)
Rollout Floaters as Extended viewports (p. 186)
ActiveX Controls in MAXScript Rollouts (p. 10)
OLE Automation (p. 1671)
OLE Automation (p. 1671)
Utility and Rollout Properties, Methods, and Event Handlers (p. 1474)
Rollout Floater Windows (p. 1477)
Managing Multiple Rollouts in a Scripted Utility (p. 1468)
Utility Clauses (p. 1466) - in example
Visibility of Locals, Functions, Structures and User-Interface Items in Rollout
Code (p. 1478)
Prompt Line (p. 1577)
External File Methods (p. 1645)
Controlling the Renderer (p. 1664)
General Event Callback Mechanism (p. 29)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Prompt Line (p. 1577)
Miscellaneous Functions (p. 1663)
226 Chapter 1 | What’s New in 3ds max 4 MAXScript

resetLattice FFD 2x2x2 : Modifier (p. 1121)

FFD 3x3x3 : Modifier (p. 1123)
FFD 4x4x4 : Modifier (p. 1124)
FFD Box : Modifier (p. 1117)
FFD Cyl : Modifier (p. 1119)
resetLengthInterp Shape Common Properties, Operators, and Methods (p. 945)
resetMaxFile Exiting and Resetting 3ds max (p. 1669)
rotateXMatrix Matrix3 Values (p. 744)
rotateYMatrix Matrix3 Values (p. 744)
rotateYPRMatrix Matrix3 Values (p. 744)
rotateZMatrix Matrix3 Values (p. 744)
saveMaterialLibrary Material Editor (p. 1606)
saveMaxFile 3ds max File Loading and Saving (p. 1639)
saveNodes 3ds max File Loading and Saving (p. 1639)
SelectionSetArray Values (p. 783)
scaleMatrix Matrix3 Values (p. 744)
seed Number Values (p. 717)
selectBitMap Bitmap Values (p. 755)
selectByName Picking Scene Nodes by Name (p. 1619)
selectCTBitMap
selectReaction Reactor Controllers (p. 1326)
selectSaveBitMap Bitmap Values (p. 755)
setActive Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
Render Effects Common Properties, Operators, and Methods (p. 1347)
setArrowCursor Mouse Cursors (p. 1588)
setAtmospheric Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
setBackGround Working with Atmospherics (p. 1345)
SetBackground Method (p. 180)
setBackGroundController Working with Atmospherics (p. 1345)
setBkgFrameRange Viewport Background Images (p. 1586)
setBkgImageAnimate Viewport Background Images (p. 1586)
setBkgImageAspect Viewport Background Images (p. 1586)
setBkgORType Viewport Background Images (p. 1586)
setBkgStartTime Viewport Background Images (p. 1586)
setBkgSyncFrame Viewport Background Images (p. 1586)
SetCommandPanelTaskMode Command Panels (p. 1571)
setCoordCenter Main Toolbar (p. 1574)
setCurNamedSelSet Main Toolbar (p. 1574)
setCVertMode Node Common Properties, Operators, and Methods (p. 820)
 Const Primitives 227

setDimension FFD Box : Modifier (p. 1117)

FFD Cyl : Modifier (p. 1119)
SetDir SetDir (p. 136)
SetDisplayFilter Selection Filter (p. 61)
setEffect Render Effects Common Properties, Operators, and Methods (p. 1347)
setFileAttribute External File Methods (p. 1645)
setFocus -jpr M029-SO selection as bitArray, ConvertTo for PolyMesh, SetFocus Minton
setGroupHead Node Common Properties, Operators, and Methods (p. 820)
setGroupMember Node Common Properties, Operators, and Methods (p. 820)
setGroupOpen Node Common Properties, Operators, and Methods (p. 820)
setImageBlurMultController Node Common Properties, Operators, and Methods (p. 820)
General Node Properties (p. 836)
setImageBlurMultiplier Node Common Properties, Operators, and Methods (p. 820)
setInheritanceFlags Node Common Properties, Operators, and Methods (p. 820)
setInheritVisibility Node Common Properties, Operators, and Methods (p. 820)
setINISetting Accessing INI File Keys (p. 1647)
setKeyStepsPos Time Configuration Dialog (p. 1616)
setKeyStepsRot Time Configuration Dialog (p. 1616)
setKeyStepsScale Time Configuration Dialog (p. 1616)
setKeyStepsSelOnly Time Configuration Dialog (p. 1616)
setKeyStepsUseTrans Time Configuration Dialog (p. 1616)
setKnotSelection SplineShape : Shape (p. 1079)
setListenerSel Controlling the Listener Contents and the Insertion Point (p. xlii)
setListenerSelText Controlling the Listener Contents and the Insertion Point (p. xlii)
setMaterialID SplineShape : Shape (p. 1079)
setMeditMaterial Material Common Properties, Operators, and Methods (p. 1203)
Material Editor (p. 1606)
MaterialLibrary Values (p. 795)
setMKTime Barycentric Morph Controller Keys (p. 1308)
setMKWeight Barycentric Morph Controller Keys (p. 1308)
setMorphTarget Barycentric Morph Controller : MorphController (p. 1306)
setMorphTargetName Barycentric Morph Controller : MorphController (p. 1306)
setMotBlur Node Common Properties, Operators, and Methods (p. 820)
setMTLMEditFlags Material Common Properties, Operators, and Methods (p. 1203)
setMTLMeditObjType Material Common Properties, Operators, and Methods (p. 1203)
setMTLMeditTiling Material Common Properties, Operators, and Methods (p. 1203)
setOpenSceneScript
setPatchSteps Patch : GeometryClass (p. 1088)
228 Chapter 1 | What’s New in 3ds max 4 MAXScript

setPosTaskWeight Node Common Properties, Operators, and Methods (p. 820)

setProgressCancel Progress Bar Display (p. 1578)
setProperty Class and Object Inspector Functions (p. 799)
ActiveX Controls in MAXScript Rollouts (p. 10) - in example
SetPropertyController Class and Object Inspector Functions (p. 799)
setReactionFalloff Reactor Controllers (p. 1326)
setReactionInfluence Reactor Controllers (p. 1326)
setReactionName Reactor Controllers (p. 1326)
setReactionState Reactor Controllers (p. 1326)
setReactionStrength Reactor Controllers (p. 1326)
setReactionValue Reactor Controllers (p. 1326)
setRefCoordSys Main Toolbar (p. 1574)
setRenderable Node Common Properties, Operators, and Methods (p. 820)
setRenderID Node Common Properties, Operators, and Methods (p. 820)
setRotTaskWeight Node Common Properties, Operators, and Methods (p. 820)
setSaveRequired Exiting and Resetting 3ds max (p. 1669)
undo (p. 687)
setSaveSceneScript
setSegSelection SplineShape : Shape (p. 1079)
SetSelectFilter Selection Filter (p. 61)
setShadeCVerts Node Common Properties, Operators, and Methods (p. 820)
setSilentMode Bitmap Values (p. 755)
setSplineSelection SplineShape : Shape (p. 1079)
setStatusXYZ Coordinate Display (p. 1578)
setSysCur Mouse Cursors (p. 1588)
setTaskAxisState Node Common Properties, Operators, and Methods (p. 820)
setToolBtnState Main Toolbar (p. 1574)
setTrajectoryOn Node Common Properties, Operators, and Methods (p. 820)
setTransformLockFlags Node Common Properties, Operators, and Methods (p. 820)
SetUIColor 3ds max User Interface Colors (p. 1604)
setupEvents
SetUseDraftRenderer Render Scene Dialog (p. 1611)
setUseEnvironmentMap Working with Atmospherics (p. 1345)
setVPortBGColor Miscellaneous Viewport Methods and System Globals (p. 1603)
setWaitCursor Mouse Cursors (p. 1588)
ShellLaunch Executing External Commands (p. 1668)
showAllActiveXControls ActiveX Controls in MAXScript Rollouts (p. 10)
 Const Primitives 229

showClass Class and Object Inspector Functions (p. 799)

Dynamic Properties (p. 805)
showEvents ActiveX Controls in MAXScript Rollouts (p. 10)
showMethods ActiveX Controls in MAXScript Rollouts (p. 10)
showSource The MAXScript Editor Windows (p. xliv)
Creating Functions (p. 699)
showTextureMap showTextureMap() function (p. 167)
Material Editor (p. 1606)
Node Common Properties, Operators, and Methods (p. 820) - in example
TextureMap Common Properties, Operators, and Methods (p. 1235)
Working with Editable Meshes (p. 1077)
silentMode Bitmap Values (p. 755)
sin Number Values (p. 717)
sinh Number Values (p. 717)
sleep Pausing Script Execution (p. 1664)
snapshotAsMesh Node Common Properties, Operators, and Methods (p. 820)
sqrt Number Values (p. 717)
squadrev Quat Values (p. 738)
startObjectCreation Create Panel (p. 1572)
Defining Macro Scripts (p. 1521)
startObjectCreation() (p. 138)
startTool Mouse Tool Clauses (p. 1532)
Scripted Mouse Tools (p. 1531)
stopAnimation Time Control (p. 1580)
stopCreating Node Common Properties, Operators, and Methods (p. 820)
NURBS Node Properties and Methods (p. 1397)
Modifying Existing NURBS Objects (p. 1390)
stopTool Scripted Mouse Tools (p. 1531)
subdivideSegment SplineShape : Shape (p. 1079)
swap Miscellaneous Functions (p. 1663)
tan Number Values (p. 717)
tangentCurve3D SplineShape : Shape (p. 1079)
tanh Number Values (p. 717)
thawSelection Status Bar Buttons (p. 1579)
timeStamp Time Stamping (p. 1664)
TransMatrix Matrix3 Values (p. 744)
Scripted Manipulator (p. 97) - in example
Scripted Manipulators (p. 97) - in example
230 Chapter 1 | What’s New in 3ds max 4 MAXScript

turbulence Color Values (p. 729)

Point3 Values (p. 731)
ungroup Node Common Properties, Operators, and Methods (p. 820)
uniqueName Node Common Properties, Operators, and Methods (p. 820)
unregisterAllRightClickMenus Scripted Right-Click Menus (p. 1514)
unregisterRedrawViewsCallback Viewport Redraw Callback Mechanism (p. 1655)
unregisterRightClickMenu Scripted Right-Click Menus (p. 1514)
unregisterSelectFilterCallback class id filter (p. 59)
unregisterTimeCallback Time Change Callback Mechanism (p. 1654)
unRegisterViewWindow Rollout Floaters as Extended viewports (p. 186)
updateMTLInMedit Material Common Properties, Operators, and Methods (p. 1203)
updateSurfaceMapper Surface Mapper : SpacewarpModifier (p. 1202)
validModifier Node Common Properties, Operators, and Methods (p. 820)
validModifer() function (p. 142)
Modifier Common Properties, Operators, and Methods (p. 1096)
WriteByte BinStream for Binary Reading and Writing (p. 128)
WriteFloat BinStream for Binary Reading and Writing (p. 128)
WriteLong BinStream for Binary Reading and Writing (p. 128)
WriteShort BinStream for Binary Reading and Writing (p. 128)
WriteString BinStream for Binary Reading and Writing (p. 128)
yesNoCancelBox MAXScript Message and Query Dialogs (p. 1622)

See Also
Definitions for MAXScript internal organization (p. 188)
 Const StructDef 231

Const StructDef
AttachCtrl (p. 232)
autoBackup (p. 232)
bit (p. 233)
boolObj (p. 233)
callbacks (p. 233)
cui (p. 234)
custAttributes (p. 234)
DOF (p. 234)
fileProperties (p. 235)
flexOps (p. 235)
gw (p. 235)
ik (p. 237)
keyboard (p. 237)
LE (p. 237)
LinkCtrl (p. 238)
ListCtrl (p. 238)
logsystem (p. 238)
macros (p. 239)
mapPaths (p. 239)
meshop (p. 239)
meshOps (p. 243)
modPanel (p. 244)
mouse (p. 244)
mtlBrowser (p. 244)
options (p. 245)
patch (p. 245)
patchOps (p. 247)
persistents (p. 247)
polyop (p. 248)
polyOps (p. 251)
patch.getEdgeVec21
preferences (p. 252)
refs (p. 252)
scanlineRender (p. 252)
schematicView (p. 252)
232 Chapter 1 | What’s New in 3ds max 4 MAXScript

skinOps (p. 253)

snapMode (p. 254)
splineOps (p. 255)
sysInfo (p. 255)
systemTools (p. 256)
terrainOps (p. 256)
timeConfiguration (p. 256)
toolMode (p. 257)
trackbar (p. 257)
trackview (p. 257)
units (p. 258)
viewport (p. 258)
WAVsound (p. 258)
xrefPaths (p. 259)
xrefs (p. 259)

See Also
Definitions for MAXScript internal organization (p. 188)

Const StructDef Pages

AttachCtrl const StructDef

Attachment : PositionController (p. 1304)
AttachCtrl.addNewKey
AttachCtrl.getKey
Attachment Controller Keys (p. 1305)

autoBackup const StructDef

3D Studio MAX System Globals (p. 630)
autoBackup.enabled SystemGlobal:enabled false
autoBackup.time SystemGlobal:time 5.0
 bit const StructDef 233

bit const StructDef

Number Values (p. 717)
bit.and
bit.charAsInt
bit.flip
bit.get
bit.intAsChar
bit.intAsHex
bit.not
bit.or
bit.set
bit.shift
bit.xor

boolObj const StructDef

Boolean2 : GeometryClass (p. 887)
boolObj.createBooleanObject
boolObj.GetBoolCutType
boolObj.GetBoolOp
boolObj.GetDisplayResult
boolObj.GetOperandSel
boolObj.GetOptimize
boolObj.GetShowHiddenOps
boolObj.GetUpdateMode
boolObj.SetBoolCutType
boolObj.SetBoolOp
boolObj.SetDisplayResult
boolObj.setOperandB
boolObj.SetOperandSel
boolObj.SetOptimize
boolObj.SetShowHiddenOps
boolObj.SetUpdateMode

callbacks const StructDef

General Event Callback Mechanism (p. 29)
callbacks.addScript
callbacks.broadcastCallback
callbacks.removeScripts
callbacks.show
234 Chapter 1 | What’s New in 3ds max 4 MAXScript

cui const StructDef

3D Studio MAX System Globals (p. 630)
Menu and CUI Loading
Command Panels (p. 1571)
Custom User Interface Files (p. 1648)
cui.commandPanelOpen SystemGlobal:commandPanelOpen true
cui.expertModeOff
cui.expertModeOn
cui.getConfigFile
cui.GetDir
cui.getExpertMode
cui.loadConfig
cui.saveConfig
cui.saveConfigAs
cui.setConfigFile

custAttributes const StructDef

Scripted Custom Attributes (p. 45)
custAttributes.add
custAttributes.count
custAttributes.delete
custAttributes.deleteDef
custAttributes.get
custAttributes.getDef
custAttributes.getDefData
custAttributes.getDefs
custAttributes.getDefSource
custAttributes.getPBlockDefs
custAttributes.getSceneDefs
custAttributes.makeUnique
custAttributes.redefine
custAttributes.setDefData

DOF const StructDef

Depth of Field : RenderEffect (p. 1354)
DOF.addCam
DOF.addFocalNode
DOF.deleteCam
DOF.deleteCamByName
DOF.deleteFocalNode
DOF.deleteFocalNodeByName
 fileProperties const StructDef 235

fileProperties const StructDef

3ds max Scene File Properties (p. 1628)
fileProperties.addProperty
fileProperties.deleteProperty
fileProperties.findProperty
fileProperties.getItems
fileProperties.getNumProperties
fileProperties.getPropertyName
fileProperties.getPropertyValue

flexOps const StructDef

Flex : Modifier (p. 1128)
flexOps.ClearEdgeVertices
flexOps.GetNumberVertices
flexOps.GetVertexWeight
flexOps.isEdgeVertex
flexOps.SelectVertices
flexOps.SetEdgeVertices
flexOps.SetVertexWeights

See Also
PositionSpring interfaces: (p. 497)
Point3Spring interfaces: (p. 482)
SpringPoint3Controller interfaces: (p. 523)
SpringPoint3Controller - superclass: Point3Controller (p. 336)
SpringPositionController interfaces: (p. 526)
SpringPositionController - superclass: PositionController (p. 337)
Flex : Modifier (p. 1128)
Flex interfaces: (p. 438)
flexOps const StructDef (p. 235)

gw const StructDef
Viewport Drawing Methods (p. 1592)
gw.clearScreen
gw.enlargeUpdateRect
gw.GetCPDisp
gw.getDriverString
gw.getFlipped
gw.GetFocalDist
gw.getHitherCoord
gw.getMaxLights
236 Chapter 1 | What’s New in 3ds max 4 MAXScript

gw.GetPointOnCP
gw.getRndLimits
gw.getRndMode
gw.getSkipCount
gw.getUpdateRect
gw.getViewportDib
gw.GetVPWorldWidth
gw.getWinDepth
gw.getWinSizeX
gw.getWinSizeY
gw.getYonCoord
gw.hMarSker
gw.hPolygon
gw.hPolyline
gw.hText
gw.hTransPoint
gw.hTriStrip
gw.isPerspectiveView
gw.IsPerspView
gw.MapCPToWorld
gw.marker
gw.NonScalingObjectSize
gw.polygon
gw.polyline
gw.querySupport
gw.resetUpdateRect
gw.setColor
gw.setPos
gw.setRndLimits
gw.setSkipCount
gw.setTransform
gw.SnapLength
gw.SnapPoint
gw.text
gw.transPoint
gw.updateScreen
gw.wMarker
gw.wPolygon
gw.wPolyline
gw.wText
gw.wTransPoint
gw.wTriStrip

See Also
Accessing Active Viewport Info, Type, and Transforms (p. 1581)
 ik const StructDef 237

ik const StructDef
IK_ControllerMatrix3Controller : Matrix3Controller (p. 1313)
ik.getBindOrient
ik.getBindPos
ik.GetEndTime
ik.getIsTerminator
ik.GetIterations
ik.getPinNode
ik.GetPosThreshold
ik.getPrecedence
ik.GetRotThreshold
ik.GetStartTime
ik.setBindOrient
ik.setBindPos
ik.SetEndTime
ik.setIsTerminator
ik.SetIterations
ik.setPinNode
ik.SetPosThreshold
ik.setPrecedence
ik.SetRotThreshold
ik.SetStartTime

keyboard const StructDef

3D Studio MAX System Globals (p. 630)
Keyboard Entry (p. 1623)
keyboard.altPressed SystemGlobal:altPressed false
keyboard.controlPressed SystemGlobal:controlPressed false
keyboard.escPressed SystemGlobal:escPressed false
keyboard.shiftPressed SystemGlobal:shiftPressed false

LE const StructDef
Lens Effects : RenderEffect (p. 1357)
LE.addASec
LE.addGlow
LE.addLight
LE.addLightNode
LE.addMSec (p. 1366)
LE.addRay
LE.addRing
LE.addStar
LE.addStreak (p. 1379)
LE.deleteElement
LE.deleteElementByName
LE.deleteLight
238 Chapter 1 | What’s New in 3ds max 4 MAXScript

LE.deleteLightByName
LE.lightIndex
LE.lightName
LE.load
LE.numLights
LE.save

LinkCtrl const StructDef

Link Control : Matrix3Controller (p. 1316)
LinkCtrl.addLink
LinkCtrl.deleteLink
LinkCtrl.getLinkCount
LinkCtrl.getLinkNode
LinkCtrl.getLinkTime
LinkCtrl.setLinkNode
LinkCtrl.setLinkTime

ListCtrl const StructDef

List Controller (p. 143)
ListCtrl.getActive
ListCtrl.getName
ListCtrl.setActive
ListCtrl.setName

See Also
List Controllers (p. 1317)

ListCtrl const StructDef

List Controller (p. 143)
ListCtrl.getActive
ListCtrl.getName
ListCtrl.setActive
ListCtrl.setName

See Also
List Controllers (p. 1317)
 logsystem const StructDef 239

logsystem const StructDef

3D Studio MAX System Globals (p. 630)
logsystem.quietMode SystemGlobal:quietMode false

macros const StructDef

Macro Scripts (p. 1624)
Defining Macro Scripts (p. 1521)
macros.edit
macros.load
macros.new
macros.run

mapPaths const StructDef

3ds max System Directories (p. 1625)
mapPaths.add
mapPaths.count
mapPaths.delete
mapPaths.get

meshop const StructDef

Editable_Mesh : GeometryClass and TriMesh : Value (p. 1041)
meshop.applyUVWMap
meshop.attach
meshop.autoEdge
meshop.autosmooth
meshop.bevelFaces
meshop.breakVerts
meshop.buildMapFaces
meshop.chamferEdges
meshop.chamferVerts
meshop.cloneEdges
meshop.cloneFaces
meshop.cloneVerts
meshop.collapseEdges
meshop.collapseFaces
meshop.createPolygon
meshop.cut
meshop.defaultMapFaces
meshop.deleteEdges
meshop.deleteFaces
meshop.deleteIsoMapVerts
meshop.deleteIsoMapVertsAll
meshop.deleteIsoVerts
240 Chapter 1 | What’s New in 3ds max 4 MAXScript

meshop.deleteMapVertSet
meshop.deleteVerts
meshop.detachFaces
meshop.detachVerts
meshop.divideEdge
meshop.divideEdges
meshop.divideFace
meshop.divideFaceByEdges
meshop.divideFaces
meshop.edgeTessellate
meshop.explodeAllFaces
meshop.explodeFaces
meshop.extrudeEdges
meshop.extrudeFaces
meshop.flipNormals
meshop.freeMapChannel
meshop.freeMapFaces
meshop.freeMapVerts
meshop.freeVAlphas
meshop.freeVData
meshop.freeVertCorners
meshop.freeVertWeights
meshop.freeVSelectWeights
meshop.getAffectBackfacing
meshop.getBaryCoords
meshop.getBubble
meshop.getDisplacementMapping
meshop.getEdgesReverseEdge
meshop.getEdgesUsingFace
meshop.getEdgesUsingVert
meshop.getElementsUsingFace
meshop.getExtrusionType
meshop.getFaceArea
meshop.getFaceCenter
meshop.getFaceRNormals
meshop.getFacesUsingEdge
meshop.getFacesUsingVert
meshop.getFalloff
meshop.getHiddenFaces
meshop.getHiddenVerts
meshop.getIgnoreBackfacing
meshop.getIgnoreVisEdges
meshop.getIsoMapVerts
meshop.getIsoVerts
meshop.getMapFace
meshop.getMapFacesUsingMapVert
meshop.getMapSupport
meshop.getMapVert
meshop.getMapVertsUsingMapFace
meshop.getNormalSize
meshop.getNumCPVVerts
 meshop const StructDef 241

meshop.getNumFaces
meshop.getNumMapFaces
meshop.getNumMaps
meshop.getNumMapVerts
meshop.getNumTVerts
meshop.getNumVDataChannels
meshop.getNumVerts
meshop.getOpenEdges
meshop.getPinch
meshop.getPlanarThreshold
meshop.getPolysUsingEdge
meshop.getPolysUsingFace
meshop.getPolysUsingVert
meshop.getSelByVertex
meshop.getShowFNormals
meshop.getShowVNormals
meshop.getSoftSel
meshop.getSplitMesh
meshop.getSSEdgeDist
meshop.getSSUseEdgeDist
meshop.getSubdivisionAngle
meshop.getSubdivisionDisplacement
meshop.getSubdivisionDistance
meshop.getSubdivisionEdge
meshop.getSubdivisionMaxLevels
meshop.getSubdivisionMaxTriangles
meshop.getSubdivisionMethod
meshop.getSubdivisionMinLevels
meshop.getSubdivisionSteps
meshop.getSubdivisionStyle
meshop.getSubdivisionView
meshop.getUIParam
meshop.getVAlpha
meshop.getVDataChannelSupport
meshop.getVDataValue
meshop.getVert
meshop.getVertCorner
meshop.getVertexAngles
meshop.getVertsByColor
meshop.getVertsUsedOnlyByFaces
meshop.getVertsUsingEdge
meshop.getVertsUsingFace
meshop.getVertWeight
meshop.getVSelectWeight
meshop.getWeldPixels
meshop.getWeldThreshold
meshop.makeFacesPlanar
meshop.makeMapPlanar
meshop.makeVertsPlanar
meshop.minVertexDistanceFrom
meshop.minVertexDistancesFrom
242 Chapter 1 | What’s New in 3ds max 4 MAXScript

meshop.moveVert
meshop.moveVertsToPlane
meshop.optimize
meshop.removeDegenerateFaces
meshop.removeIllegalFaces
meshop.resetVAlphas
meshop.resetVertCorners
meshop.resetVertWeights
meshop.resetVSelectWeights
meshop.setAffectBackfacing
meshop.setBubble
meshop.setDisplacementMapping
meshop.setExtrusionType
meshop.setFaceAlpha
meshop.setFaceColor
meshop.setFalloff
meshop.setHiddenFaces
meshop.setHiddenVerts
meshop.setIgnoreBackfacing
meshop.setIgnoreVisEdges
meshop.setMapFace
meshop.setMapSupport
meshop.setMapVert
meshop.setNormalSize
meshop.setNumCPVVerts
meshop.setNumFaces
meshop.setNumMapFaces
meshop.setNumMaps
meshop.setNumMapVerts
meshop.setNumTVerts
meshop.setNumVDataChannels
meshop.setNumVerts
meshop.setPinch
meshop.setPlanarThreshold
meshop.setSelByVertex
meshop.setShowFNormals
meshop.setShowVNormals
meshop.setSoftSel
meshop.setSplitMesh
meshop.setSSEdgeDist
meshop.setSSUseEdgeDist
meshop.setSubdivisionAngle
meshop.setSubdivisionDisplacement
meshop.setSubdivisionDistance
meshop.setSubdivisionEdge
meshop.setSubdivisionMaxLevels
meshop.setSubdivisionMaxTriangles
meshop.setSubdivisionMethod
meshop.setSubdivisionMinLevels
meshop.setSubdivisionSteps
meshop.setSubdivisionStyle
 meshOps const StructDef 243

meshop.setSubdivisionView
meshop.setUIParam
meshop.setVAlpha
meshop.setVDataChannelSupport
meshop.setVDataValue
meshop.setVert
meshop.setVertAlpha
meshop.setVertColor
meshop.setVertCorner
meshop.setVertWeight
meshop.setVSelectWeight
meshop.setWeldPixels
meshop.setWeldThreshold
meshop.slice
meshop.supportVAlphas
meshop.supportVertCorners
meshop.supportVertWeights
meshop.supportVSelectWeights
meshop.turnEdge
meshop.unifyNormals
meshop.weldVertsByThreshold
meshop.weldVertSet

meshOps const StructDef

Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
meshOps.attachList
meshOps.autoEdge
meshOps.autosmooth
meshOps.break
meshOps.clearAllSG
meshOps.collapse
meshOps.createShapeFromEdges
meshOps.delete
meshOps.detach
meshOps.explode
meshOps.flipNormal
meshOps.gridAlign
meshOps.hide
meshOps.invisibleEdge
meshOps.makePlanar
meshOps.removeIsolatedVerts
meshOps.selectByColor
meshOps.selectByID
meshOps.selectBySG
meshOps.selectOpenEdges
meshOps.showNormal
meshOps.slice
meshOps.startAttach
meshOps.startBevel
244 Chapter 1 | What’s New in 3ds max 4 MAXScript

meshOps.startChamfer
meshOps.startCreate
meshOps.startCut
meshOps.startDivide
meshOps.startExtrude
meshOps.startFlipNormalMode
meshOps.startSlicePlane
meshOps.startTurn
meshOps.startWeldTarget
meshOps.tessellate
meshOps.unhideAll
meshOps.unifyNormal
meshOps.viewAlign
meshOps.visibleEdge
meshOps.weld

modPanel const StructDef

Modify Panel (p. 1572)
modPanel.addModToSelection
modPanel.getCurrentObject
modPanel.getModifierIndex
modPanel.setCurrentObject

See Also
Modifier Common Properties, Operators, and Methods (p. 1096)
Modifier : MAXWrapper and SpacewarpModifier : MAXWrapper (p. 1095)

mouse const StructDef

Mouse Cursors (p. 1588)
mouse.buttonStates SystemGlobal:buttonStates #{}
mouse.mode SystemGlobal:mode 0
mouse.pos SystemGlobal:pos [106,85]
mouse.screenpos
SystemGlobal:screenpos [657,577]

mtlBrowser const StructDef

Miscellaneous Dialogs (p. 1621)
mtlBrowser.browseFrom

See Also
mtlBrowser (p. 180)
 options const StructDef 245

options const StructDef

MAXScript System Globals (p. 640)
options.oldPrintStyles SystemGlobal:oldPrintStyles false

See Also
Value Common Properties, Operators, and Methods (p. 714)

patch const StructDef

Patches (p. 55)
Patch : GeometryClass (p. 1088)
patch.addQuadPatch
patch.addTriPatch
patch.autosmooth
patch.changePatchInteriorType
patch.changeVertType
patch.clonePatchParts
patch.deletePatchParts
patch.edgeNormal
patch.flipPatchNormal
patch.getAdaptive
patch.getEdges
patch.getEdgeVec12
patch.getEdgeVert1
patch.getEdgeVert2
patch.getMapPatch
patch.getMapSupport
patch.getMapVert
patch.getMesh
patch.getMeshSteps
patch.getMeshStepsRender
patch.getMtlID
patch.getNumEdges
patch.getNumMaps
patch.getNumMapVerts
patch.getNumPatches
patch.getNumVecs
patch.getNumVerts
patch.getPatches
patch.getPatchInteriorType
patch.getPatchMtlID
patch.getShowInterior
patch.getVec
patch.getVecPatches
patch.getVectors
patch.getVecVert
patch.getVert
246 Chapter 1 | What’s New in 3ds max 4 MAXScript

patch.getVertEdges
patch.getVertPatches
patch.getVertType
patch.getVertVecs
patch.interpQuadPatch
patch.interpTriPatch
patch.makeQuadPatch
patch.makeTriPatch
patch.maxMapChannels
patch.patchNormal
patch.setAdaptive
patch.setMapPatch
patch.setMapSupport
patch.setMapVert
patch.setMeshSteps
patch.setMeshStepsRender
patch.setMtlID
patch.setNumEdges
patch.setNumMapPatches
patch.setNumMaps
patch.setNumMapVerts
patch.setNumPatches
patch.setNumVecs
patch.setNumVerts
patch.setPatchMtlID
patch.setShowInterior
patch.setVec
patch.setVert
patch.subdivideEdges
patch.subdividePatches
patch.transform
patch.unifyNormals
patch.update
patch.updatePatchNormals
patch.weld2Verts
patch.weldEdges
patch.weldVerts

See Also
Patch Select - superclass: modifier (p. 307)
patchOps const StructDef (p. 247)
 patchOps const StructDef 247

patchOps const StructDef

Patch : GeometryClass (p. 1088)
patchOps.addQuad
patchOps.addTri
patchOps.break
patchOps.clearAllSG
patchOps.createShapeFromEdges
patchOps.delete
patchOps.detach
patchOps.flipNormal
patchOps.hide
patchOps.selectByID
patchOps.selectBySG
patchOps.selectOpenEdges
patchOps.startAttach
patchOps.startBevel
patchOps.startBind
patchOps.startCreate
patchOps.startExtrude
patchOps.startFlipNormalMode
patchOps.startWeldTarget
patchOps.subdivide
patchOps.unbind
patchOps.unhideAll
patchOps.unifyNormal
patchOps.weld

See Also
Patches (p. 55)
patch const StructDef (p. 245)
patchOps const StructDef (p. 247)
Patch_Select - superclass: modifier (p. 307)

persistents const StructDef

Persistent Global Variables (p. 651)
persistents.remove
persistents.removeAll
persistents.show
248 Chapter 1 | What’s New in 3ds max 4 MAXScript

polyop const StructDef

polyop.applyUVWMap
polyop.attach
polyop.autosmooth
polyop.breakVerts
polyop.capHolesByEdge
polyop.capHolesByFace
polyop.capHolesByVert
polyop.collapseDeadStructs
polyop.collapseEdges
polyop.collapseFaces
polyop.collapseVerts
polyop.createEdge
polyop.createPolygon
polyop.createShape
polyop.createVert
polyop.cutEdge
polyop.cutFace
polyop.cutVert
polyop.defaultMapFaces
polyop.deleteEdges
polyop.deleteFaces
polyop.deleteIsoVerts
polyop.deleteVerts
polyop.detachEdges
polyop.detachFaces
polyop.detachVerts
polyop.divideEdge
polyop.divideFace
polyop.fillInMesh
polyop.flipNormals
polyop.forceSubdivision
polyop.freeEData
polyop.freeVData
polyop.getBorderFromEdge
polyop.getDeadEdges
polyop.getDeadFaces
polyop.getDeadVerts
polyop.getEDataChannelSupport
polyop.getEDataValue
polyop.getEdgeFaces
polyop.getEdgeFlags
polyop.getEdgesByFlag
polyop.getEdgeSelection
polyop.getEdgesUsingFace
polyop.getEdgesUsingVert
polyop.getEdgeVerts
polyop.getEdgeVis
polyop.getElementsUsingFace
polyop.getFaceArea
 polyop const StructDef 249

polyop.getFaceCenter
polyop.getFaceDeg
polyop.getFaceEdges
polyop.getFaceFlags
polyop.getFaceMatID
polyop.getFaceNormal
polyop.getFacesByFlag
polyop.getFaceSelection
polyop.getFaceSmoothGroup
polyop.getFacesUsingEdge
polyop.getFacesUsingVert
polyop.getFaceVerts
polyop.getHasDeadStructs
polyop.getHiddenFaces
polyop.getHiddenVerts
polyop.getMapFace
polyop.getMapSupport
polyop.getMapVert
polyop.getNumEDataChannels
polyop.getNumEdges
polyop.getNumFaces
polyop.getNumMapFaces
polyop.getNumMaps
polyop.getNumMapVerts
polyop.getNumVDataChannels
polyop.getNumVerts
polyop.getOpenEdges
polyop.getSafeFaceCenter
polyop.getSlicePlane
polyop.getVDataChannelSupport
polyop.getVDataValue
polyop.getVert
polyop.getVertFlags
polyop.getVertsByColor
polyop.getVertsByFlag
polyop.getVertSelection
polyop.getVertsUsedOnlyByFaces
polyop.getVertsUsingEdge
polyop.getVertsUsingFace
polyop.inSlicePlaneMode
polyop.isEdgeDead
polyop.isFaceDead
polyop.isMeshFilledIn
polyop.isVertDead
polyop.makeEdgesPlanar
polyop.makeFacesPlanar
polyop.makeVertsPlanar
polyop.meshSmoothByEdge
polyop.meshSmoothByFace
polyop.meshSmoothByVert
polyop.moveEdgesToPlane
250 Chapter 1 | What’s New in 3ds max 4 MAXScript

polyop.moveFacesToPlane
polyop.moveVert
polyop.moveVertsToPlane
polyop.propagateFlags
polyop.resetEData
polyop.resetSlicePlane
polyop.resetVData
polyop.retriangulate
polyop.setDiagonal
polyop.setEDataChannelSupport
polyop.setEDataValue
polyop.setEdgeFlags
polyop.setEdgeSelection
polyop.setEdgeVis
polyop.setFaceColor
polyop.setFaceFlags
polyop.setFaceMatID
polyop.setFaceSelection
polyop.setFaceSmoothGroup
polyop.setHiddenFaces
polyop.setHiddenVerts
polyop.setMapFace
polyop.setMapSupport
polyop.setMapVert
polyop.setNumEDataChannels
polyop.setNumMapFaces
polyop.setNumMaps
polyop.setNumMapVerts
polyop.setNumVDataChannels
polyop.setSlicePlane
polyop.setVDataChannelSupport
polyop.setVDataValue
polyop.setVert
polyop.setVertColor
polyop.setVertFlags
polyop.setVertSelection
polyop.slice
polyop.splitEdges
polyop.tessellateByEdge
polyop.tessellateByFace
polyop.tessellateByVert
polyop.unHideAllFaces
polyop.unHideAllVerts
polyop.weldEdges
polyop.weldEdgesByThreshold
polyop.weldVerts
polyop.weldVertsByThreshold
 polyOps const StructDef 251

polyOps const StructDef

polyOps.attachList
polyOps.autosmooth
polyOps.break
polyOps.cap
polyOps.clearAllSG
polyOps.collapse
polyOps.createShapeFromEdges
polyOps.delete
polyOps.detach
polyOps.flipNormal
polyOps.gridAlign
polyOps.hide
polyOps.makePlanar
polyOps.meshsmooth
polyOps.NamedSelCopy
polyOps.NamedSelPaste
polyOps.removeIsolatedVerts
polyOps.resetPlane
polyOps.retriangulate
polyOps.selectByColor
polyOps.selectByID
polyOps.selectBySG
polyOps.slice
polyOps.split
polyOps.startBevel
polyOps.startChamferEdge
polyOps.startChamferVertex
polyOps.startCreateEdge
polyOps.startCreateFace
polyOps.startCreateVertex
polyOps.startCutEdge
polyOps.startCutFace
polyOps.startCutVertex
polyOps.startDivideEdge
polyOps.startDivideFace
polyOps.startEditTri
polyOps.startExtrudeEdge
polyOps.startExtrudeFace
polyOps.startExtrudeVertex
polyOps.startSlicePlane
polyOps.startWeldTarget
polyOps.tessellate
polyOps.unhide
polyOps.update
polyOps.viewAlign
polyOps.weld
252 Chapter 1 | What’s New in 3ds max 4 MAXScript

preferences const StructDef

3D Studio MAX System Globals (p. 630)
preferences.constantReferenceSystem SystemGlobal:constantReferenceSystem false
preferences.flyOffTime SystemGlobal:flyOffTime 300
preferences.maximumGBufferLayers SystemGlobal:maximumGBufferLayers 10
preferences.spinnerWrap SystemGlobal:spinnerWrap false
preferences.useLargeVertexDots SystemGlobal:useLargeVertexDots false
preferences.useTransformGizmos SystemGlobal:useTransformGizmos true
preferences.useVertexDots SystemGlobal:useVertexDots true

See Also
Miscellaneous Viewport Methods and System Globals (p. 1603)

refs const StructDef

MAXWrapper Common Properties, Operators, and Methods (p. 809)
refs.dependents

scanlineRender const StructDef

Render Scene Dialog (p. 1611)
scanlineRender.antiAliasFilter SystemGlobal:antiAliasFilter Area:
scanlineRender.antiAliasFilterSize SystemGlobal:antiAliasFilterSize 1.5
scanlineRender.enablePixelSampler SystemGlobal:enablePixelSampler true

See Also
3D Studio MAX System Globals (p. 630)
3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters (p. 1614)

schematicView const StructDef

Schematic View (p. 1615)
schematicView.close
schematicView.getSchematicViewName
schematicView.numSchematicViews
schematicView.open
schematicView.zoomSelected
 skinOps const StructDef 253

skinOps const StructDef

Skin : Modifier (p. 1157)
skinOps.AddBone
skinOps.addBoneFromViewEnd
skinOps.addBoneFromViewStart
skinOps.AddCrossSection
skinOps.buttonAdd
skinOps.buttonAddCrossSection
skinOps.buttonAddGizmo
skinOps.buttonCopyGizmo
skinOps.buttonExclude
skinOps.buttonInclude
skinOps.buttonPaint
skinOps.buttonPasteGizmo
skinOps.buttonRemove
skinOps.buttonRemoveCrossSection
skinOps.buttonRemoveGizmo
skinOps.buttonSelectExcluded
skinOps.copySelectedBone
skinOps.enableGizmo
skinOps.GetBoneName
skinOps.getBonePropEnvelopeVisible
skinOps.getBonePropFalloff
skinOps.getBonePropRelative
skinOps.GetCrossSectionU
skinOps.GetEndPoint
skinOps.GetInnerRadius
skinOps.GetNumberBones
skinOps.GetNumberCrossSections
skinOps.getNumberOfGizmos
skinOps.getNumberOfGizmoTypes
skinOps.GetNumberVertices
skinOps.GetOuterRadius
skinOps.GetSelectedBone
skinOps.getSelectedBonePropEnvelopeVisible
skinOps.getSelectedBonePropFalloff
skinOps.getSelectedBonePropRelative
skinOps.getSelectedGizmo
skinOps.getSelectedGizmoType
skinOps.GetStartPoint
skinOps.GetVertexWeight
skinOps.GetVertexWeightBoneID
skinOps.GetVertexWeightCount
skinOps.isBoneSelected
skinOps.IsVertexModified
skinOps.IsVertexSelected
skinOps.loadEnvelope
skinOps.multiRemove
skinOps.pasteToAllBones
skinOps.pasteToBone
254 Chapter 1 | What’s New in 3ds max 4 MAXScript

skinOps.pasteToSelectedBone
skinOps.RemoveBone
skinOps.RemoveCrossSection
skinOps.ReplaceVertexWeights
skinOps.resetAllBones
skinOps.resetSelectedBone
skinOps.resetSelectedVerts
skinOps.saveEnvelope
skinOps.SelectBone
skinOps.selectCrossSection
skinOps.selectEndPoint
skinOps.selectGizmo
skinOps.selectGizmoType
skinOps.selectNextBone
skinOps.selectPreviousBone
skinOps.selectStartPoint
skinOps.SelectVertices
skinOps.setBonePropEnvelopeVisible
skinOps.setBonePropFalloff
skinOps.setBonePropRelative
skinOps.SetCrossSectionU
skinOps.SetEndPoint
skinOps.SetInnerRadius
skinOps.SetOuterRadius
skinOps.setSelectedBonePropEnvelopeVisible
skinOps.setSelectedBonePropFalloff
skinOps.setSelectedBonePropRelative
skinOps.SetStartPoint
skinOps.SetVertexWeights
skinOps.ZoomToBone
skinOps.ZoomToGizmo

snapMode const StructDef

Status Bar Buttons (p. 1579)
snapMode.active SystemGlobal:active false
snapMode.type SystemGlobal:type 3D

See Also
snapMode (p. 182)
3D Studio MAX System Globals (p. 630)
 splineOps const StructDef 255

splineOps const StructDef

SplineShape : Shape (p. 1079)
splineOps.attachMultiple
splineOps.close
splineOps.cycle
splineOps.delete
splineOps.detach
splineOps.divide
splineOps.explode
splineOps.fuse
splineOps.hide
splineOps.intersect
splineOps.makeFirst
splineOps.mirrorBoth
splineOps.mirrorHoriz
splineOps.mirrorVert
splineOps.reverse
splineOps.selectByID
splineOps.startAttach
splineOps.startBind
splineOps.startBreak
splineOps.startChamfer
splineOps.startConnect
splineOps.startCreateLine
splineOps.startCrossInsert
splineOps.startExtend
splineOps.startFillet
splineOps.startInsert
splineOps.startIntersect
splineOps.startOutline
splineOps.startRefine
splineOps.startRefineConnect
splineOps.startSubtract
splineOps.startTrim
splineOps.startUnion
splineOps.unbind
splineOps.unhideAll
splineOps.weld

sysInfo const StructDef

System Information (p. 141)
sysInfo.computername
sysInfo.cpucount
sysInfo.currentdir
sysInfo.DesktopBPP
sysInfo.DesktopSize
sysInfo.getMAXMemoryInfo
sysInfo.getSystemMemoryInfo
SystemGlobal:computername P3
SystemGlobal:cpucount 2
SystemGlobal:currentdir F:\M042
SystemGlobal:DesktopBPP 16
SystemGlobal:DesktopSize [1280,1024]
256 Chapter 1 | What’s New in 3ds max 4 MAXScript

sysInfo.MAXPriority SystemGlobal:MAXPriority normal

sysInfo.systemdir SystemGlobal:systemdir D:\WIN
NT\System32
sysInfo.tempdir
SystemGlobal:tempdir D:\TEMP\
sysInfo.username SystemGlobal:username Admini
strator
sysInfo.windowsdir SystemGlobal:windowsdir D:\WIN
NT

systemTools const StructDef

System Tools (p. 112)
systemTools.GetScreenHeight
systemTools.GetScreenWidth
systemTools.IsDebugging
systemTools.IsWindows98or2000
systemTools.IsWindows9x
systemTools.NumberOfProcessors

terrainOps const StructDef

Terrain : GeometryClass (p. 894)
terrainOps.addOperand
terrainOps.deleteOperand
terrainOps.getOperand
terrainOps.getOperandTM
terrainOps.setOperandTM
terrainOps.update

timeConfiguration const StructDef

Time Configuration Dialog (p. 1616)
timeConfiguration.playActiveOnly SystemGlobal:playActiveOnly true
timeConfiguration.playbackSpeed SystemGlobal:playbackSpeed 3
timeConfiguration.realTimePlayback SystemGlobal:realTimePlayback true
timeConfiguration.useTrackBar SystemGlobal:useTrackBar true

See Also
3D Studio MAX System Globals (p. 630)
 toolMode const StructDef 257

toolMode const StructDef

Main Toolbar (p. 1574)
toolMode.AxisConstraints SystemGlobal:AxisConstraints XY
toolMode.CommandMode SystemGlobal:CommandMode select
toolMode.coordsys
toolMode.nonUniformScale
toolMode.pivotCenter
toolMode.selectionCenter
toolMode.squashScale
toolMode.transformCenter
toolMode.uniformScale

See Also
Trackbar (p. 1581)

trackbar const StructDef

3D Studio MAX System Globals (p. 630)
trackbar.filter SystemGlobal:filter all
trackbar.GetNextKeyTime
trackbar.GetPreviousKeyTime
trackbar.visible SystemGlobal:visible true

See Also
Trackbar (p. 1581)
maxOps (p. 87)
ItrackBar (p. 113)

trackView const StructDef

Track View (p. 1609)
trackView.clearFilter
trackView.close
trackView.getTrackViewName
trackView.numTrackViews
trackView.open
trackView.pickTrackDlg
trackView.setFilter
trackView.zoomSelected

See Also
Trackviews (p. 114)
258 Chapter 1 | What’s New in 3ds max 4 MAXScript

units const StructDef

3D Studio MAX System Globals (p. 630)
units.CustomName SystemGlobal:CustomName FL
units.CustomUnit SystemGlobal:CustomUnit feet
units.CustomValue SystemGlobal:CustomValue 660.0
units.decodeValue
units.DisplayType SystemGlobal:DisplayType Generic
units.formatValue
units.MetricType SystemGlobal:MetricType meters
units.SystemScale SystemGlobal:SystemScale 1.0
units.SystemType SystemGlobal:SystemType inches
units.USFrac SystemGlobal:USFrac frac_1_8
units.USType SystemGlobal:USType
ft_Dec_In

viewport const StructDef

Accessing Active Viewport Info, Type, and Transforms (p. 1581)
viewport.activeViewport SystemGlobal:activeViewport 4
viewport.GetCamera
viewport.GetLayout
viewport.GetTM
viewport.GetType
viewport.numViews SystemGlobal:numViews 4
viewport.resetAllViews
viewport.SetCamera
viewport.SetLayout
viewport.SetTM
viewport.SetType
viewport.ZoomToBounds

See Also
3D Studio MAX System Globals (p. 630)
Zoom to Bounds (p. 184)

WAVsound const StructDef

Sound : Helper (p. 989)
WAVsound.end SystemGlobal:end -1.34218e+007f
WAVsound.filename SystemGlobal:filename
WAVsound.isPlaying SystemGlobal:isPlaying false
WAVsound.mute SystemGlobal:mute true
WAVsound.scrub
WAVsound.start SystemGlobal:start -
1.34218e+007f
 xrefPaths const StructDef 259

xrefPaths const StructDef

3ds max System Directories (p. 1625)
xrefPaths.add
Appends the specified path to the list of XRef search paths.
xrefPaths.count
Returns the number of XRef search paths defined.
xrefPaths.delete
Returns the indexed XRef search path as a string. The index is 1-based.
xrefPaths.get
Deletes the indexed XRef search path. The index is 1-based.

xrefs const Structdef

XRefScene Values (p. 1038)
xrefs.addNewXRefFile
xrefs.addNewXRefObject
xrefs.attemptUnresolvedXRefs
xrefs.deleteAllXRefs
xrefs.findUnresolvedXRefs
xrefs.getXRefFile
xrefs.getXRefFileCount
xrefs.updateChangedXRefs

version 4 New Classes

New Classes in version 4

Note:
The name of the atmosphere in releases prior to 3ds max 4, known as the “Combustion effect” is
now called “Fire Effect”.
Additive Euler XYZ - superclass: RotationController (p. 262)
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
AutomaticAdaptiveExposureControl - superclass: MAXObject (p. 267)
Automatic Exposure Control - superclass: MAXObject (p. 268)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
BlendRenderElement - superclass: MAXObject (p. 271)
clrShadowRenderElement - superclass: MAXObject (p. 272)
260 Chapter 1 | What’s New in 3ds max 4 MAXScript

Colored Shadow - superclass: MAXObject (p. 273)

Combustion.coordinates - superclass: MAXObject (p. 274)
Cone Angle - superclass: helper (p. 276)
ConeAngleManip - superclass: helper (p. 277)
ConvertToPatch - superclass: modifier (p. 278)
DeletePatch - superclass: modifier (p. 279)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
Drag - superclass: SpacewarpObject (p. 149)
emissionRenderElement - superclass: MAXObject (p. 285)
FloatList - superclass: FloatController (p. 286)
FloatReactor - superclass: FloatController (p. 287)
Hose - superclass: GeometryClass (p. 146)
HSDS Modifier - superclass: modifier (p. 290)
HSDSObject - superclass: modifier (p. 292)
imageMotionBlur - superclass: renderEffect (p. 294)
Link - superclass: Matrix3Controller (p. 294)
Link.link params - superclass: MAXObject (p. 295)
Link Constraint - superclass: Matrix3Controller (p. 295)
Link Constraint.link_params - superclass: MAXObject (p. 296)
LinkedXForm - superclass: modifier (p. 297)
LookAt Constraint - superclass: RotationController (p. 297)
Mesher - superclass: GeometryClass (p. 298)
meshsmooth - superclass: modifier (p. 298)
Motion Blur - superclass: renderEffect (p. 302)
MultiRes - superclass: modifier (p. 153)
Normalize Spl - superclass: modifier (p. 305)
Orientation Constraint - superclass: RotationController (p. 306)
particleMesher - superclass: GeometryClass (p. 306)
Patch Select - superclass: modifier (p. 307)
Path Constraint - superclass: PositionController (p. 307)
PDynaflector - superclass: SpacewarpObject (p. 309)
Plane Angle - superclass: helper (p. 310)
PlaneAngleManip - superclass: helper (p. 311)
 New Classes in version 4 261

Point3List interfaces: (p. 479)

Point3Reactor - superclass: Point3Controller (p. 312)
Point3Spring - superclass: Point3Controller (p. 313)
Point Cache - superclass: modifier (p. 314)
Point CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315)
PointCache - superclass: modifier (p. 316)
PointCacheWSM - superclass: SpacewarpModifier (p. 317)
PointHelperObj - superclass: helper (p. 318)
Poly Select - superclass: modifier (p. 319)
Position Constraint - superclass: PositionController (p. 320)
PositionList superclass_PositionController (p. 321)
PositionReactor - superclass: PositionController (p. 321)
PositionSpring - superclass: PositionController (p. 321)
PSpawnflector superclass_SpacewarpObject (p. 322)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement superclass_MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
RingWave - superclass: GeometryClass (p. 328)
RotationList - superclass: RotationController (p. 328)
RotationReactor - superclass: RotationController (p. 328)
ScaleList - superclass: ScaleController (p. 328)
ScaleReactor - superclass: ScaleController (p. 329)
SDynaflector - superclass: SpacewarpObject (p. 329)
section - superclass: shape (p. 330)
Self_Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
sliderManipulator - superclass: helper (p. 333)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)
SpringPoint3Controller - superclass: Point3Controller (p. 336)
SpringPositionController - superclass: PositionController (p. 337)
SSpawnflector - superclass: SpacewarpObject (p. 338)
transform_script - superclass: Matrix3Controller (p. 339)
262 Chapter 1 | What’s New in 3ds max 4 MAXScript

Turn_to_Mesh - superclass: modifier (p. 340)

Turn_to_Patch - superclass: modifier (p. 342)
Turn_to_Poly - superclass: modifier (p. 343)
UDynaDeflector - superclass: SpacewarpObject (p. 345)
USpawnDeflector - superclass: SpacewarpObject (p. 346)
UVWUnwrap - superclass: modifier (p. 347)
Vortex - superclass: SpacewarpObject (p. 156)
Z_Depth - superclass: MAXObject (p. 350)
ZRenderElement - superclass: MAXObject (p. 351)

New Classes in version 4 Pages

Additive_Euler_XYZ - superclass: RotationController

Additive_Euler_XYZ - superclass: RotationController; super-superclass:MAXWrapper -
3:3 - classID: #(8226, 0)
<Additive_Euler_XYZ>.additive_x_rotation Float default: 0.0 --
animatable; float; Controller Scaling: (1 : 57.2958)
<Additive_Euler_XYZ>.additive_y_rotation Float default: 0.0 --
animatable; float; Controller Scaling: (1 : 57.2958)
<Additive_Euler_XYZ>.additive_z_rotation Float default: 0.0 --
animatable; float; Controller Scaling: (1 : 57.2958)

Alpha - superclass: MAXObject

Alpha - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(13, 0)
Constructor:
Alpha ...

Properties:
<Alpha>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<Alpha>.filterOn BooleanClass default: true -- boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<Alpha>.elementName String default: “Alpha” -- string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<Alpha>.bitmap UndefinedClass default: undefined -- bitmap
 alphaRenderElement - superclass: MAXObject 263

See Also
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)

alphaRenderElement - superclass: MAXObject

alphaRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(13, 0)
Constructor:
alphaRenderElement ...

Properties:
<alphaRenderElement>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<alphaRenderElement>.filterOn BooleanClass default: true --
boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<alphaRenderElement>.elementName String default: “Alpha” --
string
Shows the name of the currently selected element. You can type in a custom name for the
element.
264 Chapter 1 | What’s New in 3ds max 4 MAXScript

This control is unavailable when multiple elements are selected.

<alphaRenderElement>.bitmap UndefinedClass default: undefined --
bitmap

See Also
Alpha - superclass: MAXObject (p. 262)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored_Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self_Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)

Atmosphere - superclass: MAXObject

Atmosphere - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(9, 0)
Constructor:
Atmosphere ...

Properties:
<Atmosphere>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<Atmosphere>.filterOn BooleanClass default: true -- boolean;
FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<Atmosphere>.elementName String default: “Atmosphere” -- string
 atmosphereRenderElement - superclass: MAXObject 265

Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<Atmosphere>.bitmap UndefinedClass default: undefined -- bitmap

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)

atmosphereRenderElement - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(9, 0)
Constructor:
Atmosphere ...

Properties:
<atmosphereRenderElement>.enabled BooleanClass default: true --
boolean
Shows whether the element is enabled.
<atmosphereRenderElement>.filterOn BooleanClass default: true --
boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
266 Chapter 1 | What’s New in 3ds max 4 MAXScript

<atmosphereRenderElement>.elementName String default:

“Atmosphere” -- string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<atmosphereRenderElement>.bitmap UndefinedClass default: undefined -
- bitmap

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)
 AutomaticAdaptiveExposureControl - superclass: MAXObject 267

AutomaticAdaptiveExposureControl - superclass: MAXObject

AutomaticAdaptiveExposureControl - superclass: MAXObject; super-superclass:Value - 5:0 - classID:
#(2020371114, 1150503387)
Constructor:
AutomaticAdaptiveExposureControl ...

Properties:
<AutomaticAdaptiveExposureControl>.physicalScale Float default: 1500.0
-- animatable; float; Physical_Scale
Sets a physical scale for exposure control to use. This is a light intensity value, in candelas.
It can range from 0.0 to 200,000.0. The physical scale is factored into light multiplier
values, and self-illumination, reflection, and refraction maps. Default=1500.0.
Decreasing the physical scale dims the scene. Increasing the physical scale increases
brightness, up to a scale value at which the scene grows no brighter.
This parameter is animatable.
<AutomaticAdaptiveExposureControl>.chromaticAdaptation BooleanClass default:
false -- boolean; Chromatic_Adaptation
When the check box is turned on, chromatic adaptation converts all colors so the color
displayed in the color swatch appears as white. Default=off.
Clicking the color swatch displays a Color Selector so you can choose the color to adapt to.
Chromatic adaptation is a form of color correction. You can use this control to simulate
the eye adjusting to lighting. For example, when the light in a room has a yellow cast, our
mind adjusts it so that objects we know to be white, such as printed pages, appear as
white.
<AutomaticAdaptiveExposureControl>.colorDiscrimination BooleanClass default:
false -- boolean; Color_Discrimination
When on, renders dimly lit colors as if the light were too dim for the eye to distinguish
between colors. When on, renders even dimly lit colors. Default=off.
Color differentiation simulates the eye’s response to dim lighting. In dim lighting, the eye
does not perceive colors and sees tones of gray instead.
The effect of this setting is not apparent except at very low light levels: below 5.62
candelas. This occurs only if the Physical Scale is less than 5.62, if a light’s Multiplier is less
than 0.00017, or both. When Physical Scale is less than 0.00562, the scene is completely
gray.
<AutomaticAdaptiveExposureControl>.whiteColor Color default: (color
255 255 255) -- animatable; RGB color; Color_Discrimination; Controller Scaling:
([1,1,1] : (color 255 255 255))
268 Chapter 1 | What’s New in 3ds max 4 MAXScript

<AutomaticAdaptiveExposureControl>.exposureValue Float default: 0.0

-- animatable; float; Exposure_Value
Adjusts the overall brightness of the rendering. Can range from -5.0 to 5.0. Negative values
make the image darker, and positive values make it brighter. Default=0.0.
The exposure value is comparable to the exposure compensation setting in cameras with
automatic exposure.
This parameter is animatable.

Automatic_Exposure_Control - superclass: MAXObject

Automatic_Exposure_Control - superclass: MAXObject; super-superclass:Value - 5:0 - classID:
#(2020371114, 1150503387)
Constructor:
Automatic_Exposure_Control ...

Properties:
<Automatic_Exposure_Control>.physicalScale Float default: 1500.0
-- animatable; float; Physical_Scale
Sets a physical scale for exposure control to use. This is a light intensity value, in candelas.
It can range from 0.0 to 200,000.0. The physical scale is factored into light multiplier
values, and self-illumination, reflection, and refraction maps. Default=1500.0.
Decreasing the physical scale dims the scene. Increasing the physical scale increases
brightness, up to a scale value at which the scene grows no brighter.
This parameter is animatable.
<Automatic_Exposure_Control>.chromaticAdaptation BooleanClass default: false
-- boolean; Chromatic_Adaptation
When the check box is turned on, chromatic adaptation converts all colors so the color
displayed in the color swatch appears as white. Default=off.
Clicking the color swatch displays a Color Selector so you can choose the color to adapt to.
Chromatic adaptation is a form of color correction. You can use this control to simulate
the eye adjusting to lighting. For example, when the light in a room has a yellow cast, our
mind adjusts it so that objects we know to be white, such as printed pages, appear as
white.
<Automatic_Exposure_Control>.colorDiscrimination BooleanClass default: false
-- boolean; Color_Discrimination
When on, renders dimly lit colors as if the light were too dim for the eye to distinguish
between colors. When on, renders even dimly lit colors. Default=off.
Color differentiation simulates the eye’s response to dim lighting. In dim lighting, the eye
does not perceive colors and sees tones of gray instead.
The effect of this setting is not apparent except at very low light levels: below 5.62
candelas. This occurs only if the Physical Scale is less than 5.62, if a light’s Multiplier is less
 BackgroundRenderElement - superclass: MAXObject 269

than 0.00017, or both. When Physical Scale is less than 0.00562, the scene is completely
gray.
<Automatic_Exposure_Control>.whiteColor Color default: (color 255 255 255) --
animatable; RGB color; Color_Discrimination; Controller Scaling: ([1,1,1] :
(color 255 255 255))

<Automatic_Exposure_Control>.exposureValue Float default: 0.0

-- animatable; float; Exposure_Value
Adjusts the overall brightness of the rendering. Can range from -5.0 to 5.0. Negative values
make the image darker, and positive values make it brighter. Default=0.0.
The exposure value is comparable to the exposure compensation setting in cameras with
automatic exposure.
This parameter is animatable.

BackgroundRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(15, 0)
Constructor:
BackgroundRenderElement ...

Properties:
<BackgroundRenderElement>.enabled BooleanClass default: true --
boolean
Shows whether the element is enabled.
<BackgroundRenderElement>.filterOn BooleanClass default: true --
boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<BackgroundRenderElement>.elementName String default:
“Background” -- string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<BackgroundRenderElement>.bitmap UndefinedClass default: undefined --
bitmap

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
bgndRenderElement - superclass: MAXObject (p. 270)
270 Chapter 1 | What’s New in 3ds max 4 MAXScript

clrShadowRenderElement - superclass: MAXObject (p. 272)

Colored Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)

bgndRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(15, 0)
Constructor:
bgndRenderElement ...

Properties:
<bgndRenderElement>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<bgndRenderElement>.filterOn BooleanClass default: true -- boolean;
FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<bgndRenderElement>.elementName String default: “Background” --
string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<bgndRenderElement>.bitmap UndefinedClass default: undefined --
bitmap

See Also
bitmapTex interfaces: (p. 434)
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
 BlendRenderElement - superclass: MAXObject 271

atmosphereRenderElement - superclass: MAXObject (p. 265)

BackgroundRenderElement - superclass: MAXObject (p. 269)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)

BlendRenderElement - superclass: MAXObject

BlendRenderElement - superclass: MAXObject; super-superclass:Value - 12:0 - classID: #(11, 0)
Constructor:
BlendRenderElement

Properties:
<BlendRenderElement>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<BlendRenderElement>.filterOn BooleanClass default: true -- boolean;
FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<BlendRenderElement>.elementName String default: “Blend” -- string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<BlendRenderElement>.bitmap UndefinedClass default: undefined -- bitmap

<BlendRenderElement>.atmosphereOn BooleanClass default: true -- boolean

When on, include atmospheric effects. Default=on.
<BlendRenderElement>.shadowOn BooleanClass default: true -- boolean;
ShadowsOn
When on, include shadows. Default=on.
272 Chapter 1 | What’s New in 3ds max 4 MAXScript

<BlendRenderElement>.diffuseOn BooleanClass default: true -- boolean;

Diffuse_On
When on, include the diffuse color component. Default=on.
<BlendRenderElement>.ambientOn BooleanClass default: true -- boolean;
Ambient_On
When on, include the ambient color component. Default=on.
<BlendRenderElement>.specularOn BooleanClass default: true -- boolean;
Specular_On
When on, include the specular color component. Default=on.
<BlendRenderElement>.emissionOn BooleanClass default: true -- boolean;
Self_Illumination
When on, include self-illumination. Default=on.
<BlendRenderElement>.reflectionOn BooleanClass default: true -- boolean;
Reflection_On
When on, include reflections. Default=on.
<BlendRenderElement>.refractionOn BooleanClass default: true -- boolean;
Refraction_On
When on, include refractions. Default=on.

clrShadowRenderElement - superclass: MAXObject

clrShadowRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(14, 0)
Constructor:
clrShadowRenderElement ...

Properties:
<clrShadowRenderElement>.enabled BooleanClass default: true --
boolean
Shows whether the element is enabled.
<clrShadowRenderElement>.filterOn BooleanClass default: true --
boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<clrShadowRenderElement>.elementName String default: “Colored
Shadow” -- string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<clrShadowRenderElement>.bitmap UndefinedClass default: undefined --
bitmap
 Colored_Shadow - superclass: MAXObject 273

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
Colored Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)

Colored_Shadow - superclass: MAXObject

Colored_Shadow - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(14, 0)
Constructor:
Colored_Shadow ...

Properties:
<Colored_Shadow>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<Colored_Shadow>.filterOn BooleanClass default: true -- boolean;
FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<Colored_Shadow>.elementName String default: “Colored Shadow” --
string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<Colored_Shadow>.bitmap UndefinedClass default: undefined -- bitmap
274 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)

Combustion.coordinates - superclass: MAXObject

Combustion.coordinates - superclass: MAXObject; super-superclass:Value - 16:0 - classID: #(256, 0)
Constructor:
Combustion.coordinates ...

Properties:
<Combustion.coordinates>.blur Float default: 1.0 -- animatable;
float
Affects the sharpness or blurriness of the map based on its distance from the view. The
farther away the map is, the greater the blurring. The Blur value blurs maps in world space.
Blur is primarily used to avoid aliasing.
<Combustion.coordinates>.mapping Integer default: 0

<Combustion.coordinates>.mapChannel Integer default: 1

<Combustion.coordinates>.mappingType Integer default: 0

<Combustion.coordinates>.phase Float default: 0.0 -- animatable; float

 Combustion.coordinates - superclass: MAXObject 275

<Combustion.coordinates>.U_Offset Float default: 0.0 -- animatable;

float
Changes the position of the map in UV coordinates. The map moves in relation to its size.
For example, if you want to shift the map its full width to the left, and half its width
downward from its original position, you enter -1 in the U Offset field and 0.5 in the V
offset field.
<Combustion.coordinates>.V_Offset Float default: 0.0 -- animatable;
float
Changes the position of the map in UV coordinates. The map moves in relation to its size.
For example, if you want to shift the map its full width to the left, and half its width
downward from its original position, you enter -1 in the U Offset field and 0.5 in the V
offset field.
<Combustion.coordinates>.U_Tiling Float default: 1.0 -- animatable;
float
Determines the number of times the map is tiled (repeated) along each axis.
<Combustion.coordinates>.V_Tiling Float default: 1.0 -- animatable;
float
Determines the number of times the map is tiled (repeated) along each axis.
<Combustion.coordinates>.U_Angle Float default: 0.0 -- animatable;
angle; Controller Scaling: (1 : 57.2958)
Rotates the map about the U, V, or W axis (in degrees).
<Combustion.coordinates>.V_Angle Float default: 0.0 -- animatable;
angle; Controller Scaling: (1 : 57.2958)
Rotates the map about the U, V, or W axis (in degrees).
<Combustion.coordinates>.W_Angle Float default: 0.0 -- animatable;
angle; Controller Scaling: (1 : 57.2958)
Rotates the map about the U, V, or W axis (in degrees).
<Combustion.coordinates>.Noise_Amount Float default: 1.0 -- animatable;
float

<Combustion.coordinates>.Noise_Size Float default: 1.0 -- animatable;

float

<Combustion.coordinates>.Noise_Levels Integer default: 1 -- animatable;

integer

<Combustion.coordinates>.Blur_Offset Float default: 0.0 -- animatable;

float
Affects the sharpness or blurriness of the map without regard to its distance from the view.
Blur Offset blurs the image itself in object space. Use this option when you want to soften
or defocus the details in a map to achieve the effect of a blurred image.

See Also
Combustion (p. 38)
Material Common Properties, Operators, and Methods (p. 1203)
276 Chapter 1 | What’s New in 3ds max 4 MAXScript

Cone_Angle - superclass: helper

Cone_Angle - superclass: helper; super-superclass:node - 6:0 - classID: #(629233518, 624568848)
Constructor:
Cone_Angle ...

Properties:
<Cone_Angle>.Origin Point3 default: [0,0,0] -- point3
<Cone_Angle>.Direction Point3 default: [0,0,-1] -- point3
<Cone_Angle>.Angle Float default: 15.0 -- animatable; angle;
Controller Scaling: (1 : 57.2958)
The initial angle of the manipulator.
<Cone_Angle>.Distance Float default: 0.0 -- float
The length of the manipulator, in 3ds max units. Default=the distance of mouse drag
when the manipulator was created.
<Cone_Angle>.UseSquare BooleanClass default: false -- boolean;
Use_Square
When on, the base of the cone is square or rectangular, rather than circular. Default=off.
<Cone_Angle>.Aspect Float default: 1.0 -- float
When Use Square is on, adjusts the aspect ratio of the rectangular cone base. Default=1.0.

See Also
Scripted Manipulators (p. 97)
Interface: manip (p. 366)
radiusManip interfaces: (p. 500)
ConeAngleManip - superclass: helper (p. 277)
PlaneAngleManip - superclass: helper (p. 311)
Scripted Plug-ins (p. 1538)
sliderManipulator - superclass: helper (p. 333)
sliderManipulator interfaces: (p. 520)
uvwMappingHeightManip interfaces: (p. 551)
uvwMappingLengthManip interfaces: (p. 555)
uvwMappingUTileManip interfaces: (p. 558)
uvwMappingVTileManip interfaces: (p. 562)
uvwMappingWidthManip interfaces: (p. 565)
 ConeAngleManip - superclass: helper 277

ConeAngleManip - superclass: helper

ConeAngleManip - superclass: helper; super-superclass:node - 6:0 - classID: #(629233518,
624568848)
Constructor:
ConeAngleManip ...

Properties:
<ConeAngleManip>.Origin Point3 default: [0,0,0] -- point3
<ConeAngleManip>.Direction Point3 default: [0,0,-1] -- point3
<ConeAngleManip>.Angle Float default: 15.0 -- animatable; angle;
Controller Scaling: (1 : 57.2958)
The initial angle of the manipulator.
<ConeAngleManip>.Distance Float default: 0.0 -- float
The length of the manipulator, in 3ds max units. Default=the distance of mouse drag
when the manipulator was created.
<ConeAngleManip>.UseSquare BooleanClass default: false -- boolean;
Use_Square
When on, the base of the cone is square or rectangular, rather than circular. Default=off.
<ConeAngleManip>.Aspect Float default: 1.0 -- float
When Use Square is on, adjusts the aspect ratio of the rectangular cone base. Default=1.0.

See Also
Interface: manip (p. 366)
sliderManipulator interfaces: (p. 520)
radiusManip interfaces: (p. 500)
uvwMappingHeightManip interfaces: (p. 551)
uvwMappingLengthManip interfaces: (p. 555)
uvwMappingUTileManip interfaces: (p. 558)
uvwMappingVTileManip interfaces: (p. 562)
uvwMappingWidthManip interfaces: (p. 565)
ConeAngleManip - superclass: helper (p. 277)
PlaneAngleManip - superclass: helper (p. 311)
Scripted Plug-ins (p. 1538)
sliderManipulator - superclass: helper (p. 333)
278 Chapter 1 | What’s New in 3ds max 4 MAXScript

ConvertToPatch - superclass: modifier

ConvertToPatch - superclass: modifier; super-superclass:MAXWrapper - 4:0 - classID: #(1011577041,
590161861)
The Turn To Patch modifier lets you apply object conversions in the modifier stack. Using the Turn
To Patch modifier, you can fine-tune the conversion process such as turning quads into quad
patches.
Note: Converting from one object type to another causes a complete caching in the modifier stack.
When you have large objects in your scene, this can take up a lot of space. For example, an object
that starts as a mesh, converts to a patch, and then back to a mesh takes 3 times as much space as a
mesh which just has ordinary modifiers like Bend or UVW Map applied.
Note:
Converting from one object type to another causes a complete caching in the modifier stack. When
you have large objects in your scene, this can take up a lot of space. For example, an object that starts
as a mesh, converts to a patch, and then back to a mesh takes 3 times as much space as a mesh which
just has ordinary modifiers like Bend or UVW Map applied.
Constructor:
ConvertToPatch ...

Properties:
<ConvertToPatch>.quadsToQuads BooleanClass default: true --
animatable; boolean; Quads_to_Quad_Patches
Turns quad faces in meshes or polymeshes into quad patches.
<ConvertToPatch>.selectionConversion Integer default: 0 -- integer;
Selection_Conversion
<ConvertToPatch>.useSoftSelection Integer default: 1 -- integer;
Use_Soft_Selection
When these are on, 3ds max applies a spline curve deformation to unselected vertices
surrounding the transformed selected sub-object. This provides a magnet-like effect, with a
sphere of influence around the transformation. Use this when you want to preserve the
soft selection from beneath. For example, if Use Soft Selection is on when you select
vertices on an editable mesh, and you apply Turn To Patch with Include Soft Selection on,
then the same soft selection will apply to the patch vertices.
<ConvertToPatch>.selectionLevel Integer default: 0 -- integer;
Selection_Level

These options set the sub-object selection level for passing up the rest of the stack.
From Pipeline: Uses the equivalent of whatever the input object uses. (Patch level becomes face
level, and so on.). For example, if you create a box, convert it to an editable mesh in face mode
and apply a Turn To Patch modifier to it, 3ds max passes a sub-object selection in patch mode
up the stack. The Turn To Patch modifier takes the sub-object face selection into account and
selects the patches that derive from the face selection.
 DeletePatch - superclass: modifier 279

Object: Uses object as the selection level for passing up the rest of the stack.
Edge: Uses edge as the sub-object selection level for passing up the rest of the stack.
Vertex: Uses vertex as the sub-object selection level for passing up the rest of the stack.
Patch: Uses patch as the sub-object selection level for passing up the rest of the stack.

DeletePatch - superclass: modifier

DeletePatch - superclass: modifier; super-superclass:MAXWrapper - 0:0 - classID: #(2134166570, 0)
Apply the Delete Patch modifier to delete the geometry specified at that sub-object level.

Diffuse - superclass: MAXObject

Diffuse - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(4, 0)
Constructor:
Diffuse ...

Properties:
<Diffuse>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<Diffuse>.filterOn BooleanClass default: true -- boolean;
FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<Diffuse>.elementName String default: “Diffuse” -- string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<Diffuse>.bitmap UndefinedClass default: undefined -- bitmap

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored Shadow - superclass: MAXObject (p. 273)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
280 Chapter 1 | What’s New in 3ds max 4 MAXScript

Reflection - superclass: MAXObject (p. 323)

reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)

diffuseRenderElement - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(4, 0)
Constructor:
diffuseRenderElement ...

Properties:
<diffuseRenderElement>.enabled BooleanClass default: true --
boolean
Shows whether the element is enabled.
<diffuseRenderElement>.filterOn BooleanClass default: true --
boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<diffuseRenderElement>.elementName String default: “Diffuse” --
string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<diffuseRenderElement>.bitmap UndefinedClass default: undefined --
bitmap

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored Shadow - superclass: MAXObject (p. 273)
 Drag - superclass: SpacewarpObject 281

Diffuse - superclass: MAXObject (p. 279)

emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)

Drag - superclass: SpacewarpObject

Drag - superclass: SpacewarpObject; super-superclass:node - 29:0 - classID: #(1173650369,
674975258)
The Drag space warp is a particle motion damper that reduces particle velocity by a specified amount
within a specified range. The damping can be applied linearly, spherically, or cylindrically. Drag is
useful for simulating wind resistance, transfers into dense media (like water), impacts with force
fields, and other, similar situations.
With each damping type, you can control the damping effect along several vectors. The damping is
also affected by particle system settings, such as speed.
Constructor:
Drag ...

Properties:
<Drag>.‘time on’ Integer default: 0 -- integer; Time_On
The frame numbers at which the space warp becomes active and becomes inactive.
<Drag>.‘time off’ Integer default: 16000 -- animatable; integer;
Time_Off
The frame numbers at which the space warp becomes active and becomes inactive.
<Drag>.symmetry Integer default: 0 -- radio button number;
Damping_Symmetry
This group lets you choose Linear Damping, Spherical Damping, or Cylindrical Damping,
plus a set of parameters for each.
<Drag>.dampingx Float default: 5.0 -- animatable; percentage;
X_Damping; Controller Scaling: (1 : 100.0)
Specifies the percentage of particle motion along the local Drag space warp axis that’s
affected by the damping.
<Drag>.rangex Float default: 100.0 -- animatable; float; X_Range
282 Chapter 1 | What’s New in 3ds max 4 MAXScript

Sets the thickness of the “range plane,” or the infinite plane perpendicular to the specified
axis. Takes effect only when Unlimited Range is turned off.
<Drag>.falloffx Float default: 1000.0 -- animatable; float;
X_Falloff
Specifies the distance beyond the X, Y, or Z Range within which Linear Damping is
applied. Damping is strongest at the Range distance, decreases linearly out to the limit of
the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range,
it is measured from the center of the icon, and always has a minimum value equal to the
Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingy Float default: 0.0 -- animatable; percentage;
Y_Damping; Controller Scaling: (1 : 100.0)
Specifies the percentage of particle motion along the local Drag space warp axis that’s
affected by the damping.
<Drag>.rangey Float default: 100.0 -- animatable; float; Y_Range
Sets the thickness of the “range plane,” or the infinite plane perpendicular to the specified
axis. Takes effect only when Unlimited Range is turned off.
<Drag>.falloffy Float default: 1000.0 -- animatable; float;
Y_Falloff
Specifies the distance beyond the X, Y, or Z Range within which Linear Damping is
applied. Damping is strongest at the Range distance, decreases linearly out to the limit of
the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range,
it is measured from the center of the icon, and always has a minimum value equal to the
Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingz Float default: 0.0 -- animatable; percentage;
Z_Damping; Controller Scaling: (1 : 100.0)
Specifies the percentage of particle motion along the local Drag space warp axis that’s
affected by the damping.
<Drag>.rangez Float default: 100.0 -- animatable; float; Z_Range
Sets the thickness of the “range plane,” or the infinite plane perpendicular to the specified
axis. Takes effect only when Unlimited Range is turned off.
<Drag>.falloffz Float default: 1000.0 -- animatable; float;
Z_Falloff
Specifies the distance beyond the X, Y, or Z Range within which Linear Damping is
applied. Damping is strongest at the Range distance, decreases linearly out to the limit of
the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range,
it is measured from the center of the icon, and always has a minimum value equal to the
Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingr Float default: 5.0 -- animatable; percentage;
Radial_Damping; Controller Scaling: (1 : 100.0)
Radial specifies the percentage of particle motion toward or away from the center of the
Drag icon that’s affected by the damping. Tangential specifies the percentage of particle
motion across the body of the Drag icon that’s affected by the damping.
 Drag - superclass: SpacewarpObject 283

<Drag>.ranger Float default: 100.0 -- animatable; float;

Radial_Range
Specifies the distance from the center of the Drag icon, in system units, within which
damping is in full effect. Takes effect only when Unlimited Range is turned off.
<Drag>.falloffr Float default: 1000.0 -- animatable; float;
Radial_Falloff
Specifies the distance beyond the Radial/Tangential Range within which Linear Damping
is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of
the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range,
it is measured from the center of the icon, and always has a minimum value equal to the
Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampinggc Float default: 0.0 -- animatable; percentage;
Tangential_Damping; Controller Scaling: (1 : 100.0)
Radial specifies the percentage of particle motion toward or away from the center of the
Drag icon that’s affected by the damping. Tangential specifies the percentage of particle
motion across the body of the Drag icon that’s affected by the damping.
<Drag>.rangegc Float default: 100.0 -- animatable; float;
Tangential_Range
Specifies the distance from the center of the Drag icon, in system units, within which
damping is in full effect. Takes effect only when Unlimited Range is turned off.
<Drag>.falloffgc Float default: 1000.0 -- animatable; float;
Tangential_Falloff
Specifies the distance beyond the Radial/Tangential Range within which Linear Damping
is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of
the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range,
it is measured from the center of the icon, and always has a minimum value equal to the
Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingrc Float default: 5.0 -- animatable; percentage;
Radial_Damping; Controller Scaling: (1 : 100.0)
Damping controls the percentage of particle motion toward or away from the center of the
circular portion of the icon (Radial), across the radial vector (Tangential), or along the
length of the icon’s long axis (Axial) that’s affected by the damping, on a per-frame basis.
<Drag>.rangerc Float default: 100.0 -- animatable; float;
Radial_Range
Specifies the distance from the center of the Drag icon, in system units, within which
Radial and Axial damping are in full effect. Range also specifies the thickness of the
infinite plane that governs the range of Axial damping. Takes effect only when Unlimited
Range is turned off.
<Drag>.falloffrc Float default: 1000.0 -- animatable; float;
Radial_Falloff
Specifies the distance beyond the Radial/Tangential/Axial Range within which Linear
Damping is applied. Damping is strongest at the Range distance, decreases linearly out to
the limit of the Falloff, and has no effect beyond that. While Falloff is effected only
284 Chapter 1 | What’s New in 3ds max 4 MAXScript

beyond the Range, it is measured from the center of the icon, and always has a minimum
value equal to the Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingc Float default: 0.0 -- animatable; percentage;
Tangential_Damping; Controller Scaling: (1 : 100.0)
Damping controls the percentage of particle motion toward or away from the center of the
circular portion of the icon (Radial), across the radial vector (Tangential), or along the
length of the icon’s long axis (Axial) that’s affected by the damping, on a per-frame basis.
<Drag>.rangec Float default: 100.0 -- animatable; float;
Tangential_Range
Specifies the distance from the center of the Drag icon, in system units, within which
Radial and Axial damping are in full effect. Range also specifies the thickness of the
infinite plane that governs the range of Axial damping. Takes effect only when Unlimited
Range is turned off.
<Drag>.falloffc Float default: 1000.0 -- animatable; float;
Tangential_Falloff
Specifies the distance beyond the Radial/Tangential/Axial Range within which Linear
Damping is applied. Damping is strongest at the Range distance, decreases linearly out to
the limit of the Falloff, and has no effect beyond that. While Falloff is effected only
beyond the Range, it is measured from the center of the icon, and always has a minimum
value equal to the Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingax Float default: 0.0 -- animatable; percentage;
Axial_Damping; Controller Scaling: (1 : 100.0)
Damping controls the percentage of particle motion toward or away from the center of the
circular portion of the icon (Radial), across the radial vector (Tangential), or along the
length of the icon’s long axis (Axial) that’s affected by the damping, on a per-frame basis.
<Drag>.rangeax Float default: 100.0 -- animatable; float;
Axial_Range
Specifies the distance from the center of the Drag icon, in system units, within which
Radial and Axial damping are in full effect. Range also specifies the thickness of the
infinite plane that governs the range of Axial damping. Takes effect only when Unlimited
Range is turned off.
<Drag>.falloffax Float default: 1000.0 -- animatable; float;
Axial_Falloff
Specifies the distance beyond the Radial/Tangential/Axial Range within which Linear
Damping is applied. Damping is strongest at the Range distance, decreases linearly out to
the limit of the Falloff, and has no effect beyond that. While Falloff is effected only
beyond the Range, it is measured from the center of the icon, and always has a minimum
value equal to the Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.rangeless BooleanClass default: true -- boolean; Unlimited_Range
<Drag>.iconsize Float default: 10.0 -- float; Icon_Size
Specifies the size of the icon.
 emissionRenderElement - superclass: MAXObject 285

Example:
Drag time_on:0 time_off:10 symmetry:0 dampingx:5 rangex:100 falloffx:1000
dampingy:0 rangey:100 falloffy:1000 dampingz:0 rangez:100 falloffz:1000 dampingr:5
ranger:100 falloffr:1000 dampinggc:0 rangegc:100 falloffgc:1000 dampingrc:5
rangerc:100 falloffrc:1000 dampingc:0 rangec:100 falloffc:1000 dampingax:0
rangeax:100 falloffax:1000 rangeless:on pos:[-16.2008,-105.647,0] isSelected:on
iconSize:13.7761

See Also
Modifier and SpacewarpModifier Types (p. 1100)

emissionRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(5, 0)
Constructor:
emissionRenderElement ...

Properties:
<emissionRenderElement>.enabled BooleanClass default: true --
boolean
Shows whether the element is enabled.
<emissionRenderElement>.filterOn BooleanClass default: true --
boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<emissionRenderElement>.elementName String default: “Self-
Illumination” -- string
Shows the name of the currently selected element. You can type in a custom name for
the element.
This control is unavailable when multiple elements are selected.
<emissionRenderElement>.bitmap UndefinedClass default: undefined --
bitmap

See Also
Self Illumination - superclass: MAXObject (p. 331)
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
286 Chapter 1 | What’s New in 3ds max 4 MAXScript

Colored Shadow - superclass: MAXObject (p. 273)

Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)

FloatList - superclass: FloatController

FloatList - superclass: FloatController; super-superclass:MAXWrapper - 1:1 - classID:
#(1263210496, 0)
The List controller combines multiple controllers into a single effect. It is a compound controller
with tools for managing the order in which its internal controllers are calculated. Controllers are
evaluated in a top to bottom order; the controller at the top of the list is evaluated first.
When you assign a List controller to a parameter, the current controller is moved one level below
the List controller; it becomes the first controller in the list. A second parameter is added below the
List controller and is named Available. This is an empty placeholder for the next controller you add
to the list.
Constructor:
...

Properties:
<FloatList>.available Float default: 0.0 -- animatable; float;
Controller Scaling: (1 : 0.0); WeirdScaled (0.0)

See Also
FloatList interfaces: (p. 450)
 FloatReactor - superclass: FloatController 287

FloatReactor - superclass: FloatController

FloatReactor - superclass: FloatController; super-superclass:MAXWrapper - 0:0 -
classID: #(1904049439, 306976571)
See Also
FloatReactor interfaces: (p. 452)

Hose - superclass: GeometryClass

Hose - superclass: GeometryClass; super-superclass:node - 27:0 - classID: #(1777953373, 593249034)
The Hose object is a flexible object that you can connect between two objects, whereupon it reacts
to their movement. It’s similar to Spring, but does not have dynamics properties. You can specify the
overall diameter and length of the hose, the number of turns, and the diameter and shape of its
“wire.”
Constructor:
Hose ...

Properties:
<Hose>.End_Placement_Method Integer default: 1 -- integer
<Hose>.Generate_Mapping_Coordinates Integer default: 0 -- integer
Sets up required coordinates for applying mapped materials to the hose. Default=off.
<Hose>.Hose_Height Float default: 1.0 -- animatable;
float
Use this field/spinner to set the straight-line height or length of the hose when it is not
bound. This is not the actual length of the hose. Available only when Free Hose is chosen.
<Hose>.Segments_Along_Hose Integer default: 45 -- animatable;
integer
The total number of segments in the hose’s length. Increase this setting for a smooth
profile when the hose is curved. Default=16.
<Hose>.Smooth_Spring Integer default: 0 -- integer
Choose one of the following smoothing options:
All: The entire hose is smoothed.
Sides: Smoothing is applied along the length of the hose but not around its circumference.
None: No smoothing is applied.
Segments: Smoothing is applied only on the inner section of the hose.
<Hose>.Renderable_Hose Integer default: 1 -- integer
When on, the hose is rendered using the specified settings. When off, the hose is not
rendered. Default=on.
288 Chapter 1 | What’s New in 3ds max 4 MAXScript

<Hose>.Hose_Cross_Section_Type Integer default: 0 -- integer

Sets a circular cross-section.
Lets you specify different settings for width and depth.
Similar to Rectangular Hose, but rounds one side for a D-shaped cross-section.
<Hose>.Round_Hose_Diameter Float default: 0.2 -- animatable;
float
The maximum width of the hose at the ends.
<Hose>.Round_Hose_Sides Integer default: 8 -- animatable;
integer
The number of sides of the hose. A Sides setting of 3 gives a triangular cross-section; 4 gives
a square cross-section; and 5 gives a pentagonal cross-section. Increase Sides for a circular
cross-section. Default=6.
<Hose>.Rectangular_Hose_Width Float default: 0.2 -- animatable;
float
The width of the hose.
<Hose>.Rectangular_Hose_Depth Float default: 0.2 -- animatable;
float
The height of the hose.
<Hose>.Rectangular_Hose_Fillet_Size Float default: 0.0 -- animatable;
float
The amount by which the cross-section corners are rounded. For this to be visible, Fillet
Segs must be set to 1 or higher. Default=0.
<Hose>.Rectangular_Hose_Fillet_Segs Integer default: 0 -- animatable;
integer
The number of segments across each filleted corner. A Fillet Segs setting of 1 cuts the
corner straight across; use higher settings for rounded corners. Default=0.
<Hose>.Rectangular_Hose_Section_Rotation Float default: 0.0 -- animatable;
angle; Controller Scaling: (1 : 57.2958)
The orientation of the hose along its long axis. Default=0.
<Hose>.D_Section_Hose_Width Float default: 0.2 -- animatable;
float
The width of the hose.
<Hose>.D_Section_Hose_Depth Float default: 0.2 -- animatable;
float
The height of the hose.
<Hose>.D_Section_Hose_Fillet_Size Float default: 0.0 -- animatable;
float
The amount by which the two cross-section corners opposite the rounded side are
rounded. For this to be visible, Fillet Segs must be set to 1 or higher. Default=0.
<Hose>.D_Section_Hose_Fillet_Segs Integer default: 0 -- animatable;
integer
The number of segments across each filleted corner. A Fillet Segs setting of 1 cuts the
corner straight across; use higher settings for rounded corners. Default=0.
 Hose - superclass: GeometryClass 289

<Hose>.D_Section_Hose_Round_Segs Integer default: 8 -- animatable;

integer
The number of segments on the rounded side. Increase for a smoother profile. Default=4.
<Hose>.D_Section_Hose_Section_Rotation Float default: 0.0 -- animatable;
angle; Controller Scaling: (1 : 57.2958)
The orientation of the hose along its long axis. Default=0.
<Hose>.Flex_Section_Enabled Integer default: 1 -- integer
When on, lets you set the following four parameters for the central, flexible section of the
hose. When off, the hose’s diameter is uniform throughout its length.
<Hose>.Flex_Section_Start Float default: 10.0 -- animatable;
percentage; Controller Scaling: (1 : 100.0)
The percentage of the hose length from the starting extremity of the hose at which the flex
section begins. By default, the starting end of the hose is the end at which the object pivot
appears. Default=10%.
<Hose>.Flex_Section_Stop Float default: 90.0 -- animatable;
percentage; Controller Scaling: (1 : 100.0)
The percentage of the hose length from the end extremity of the hose at which the flex
section begins. By default, the end extremity of the hose is opposite the end at which the
object pivot appears. Default=90%.
<Hose>.Flex_Cycle_Count Integer default: 5 -- animatable;
integer
The number of corrugations in the flex section. The number of visible cycles is limited by
the number of segments; if Segments isn’t high enough to support the number of cycles,
then not all cycles will appear. Default=10.
Tip: To set the appropriate number of segments, first set Cycles, and then increase
Segments until the number of visible cycles stops changing.
<Hose>.Flex_Section_Diameter Float default: -20.0 -- animatable;
percentage; Controller Scaling: (1 : 100.0)
The relative width of the “outside” parts of the cycles. At negative settings, these are
smaller than the overall hose diameter. At positive settings, these are larger than the
overall hose diameter. Default=-20%. Range=-50% to 500%.
<Hose>.Top_Tension Float default: 100.0 -- animatable;
float
Determines the arc of the hose near the Top object. Lower the tension to decrease the arc,
and raise the tension to increase the arc. Default=100.
<Hose>.Bottom_Tension Float default: 100.0 -- animatable;
float
Determines the arc of the hose near the Bottom object. Lower the tension to decrease the
arc, and raise the tension to increase the arc. Default=100.
290 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

HSDS_Modifier - superclass: modifier

HSDS_Modifier - superclass: modifier; super-superclass:MAXWrapper - 12:0 - classID: #(341062,
28997)
Constructor:
HSDS_Modifier ...

Properties:
<HSDS_Modifier>.levelOfDetail Integer default: 0 -- integer; LOD
Shows the current level of the subdivision hierarchy. Automatically increments when you
subdivide a sub-object selection. To edit at a different level of detail, change the setting to
the desired level.
<HSDS_Modifier>.matId Integer default: 1 -- integer;
Material_Id
Displays the material ID assigned to the current selection. Available only in Polygon and
Element sub-object modes. If multiple sub-objects are selected and they don’t share an ID,
this field is blank.
<HSDS_Modifier>.shadedLattice BooleanClass default: false -- boolean;
Shaded_Lattice
Displays only polygons at the current level of detail, with highlights, but without
smoothing. Use this option to speed up the display when working with complex objects.
Default=off.
<HSDS_Modifier>.ignoreBackface BooleanClass default: false -- boolean;
Ignore_Backface
When on, you can select only those sub-objects whose normals are visible in the viewport.
When off (the default), selection includes all sub-objects, regardless of the direction of
their normals.
<HSDS_Modifier>.useSoftSel BooleanClass default: false -- boolean;
Use_Soft_Selection
These controls let you set a gradual falloff of influence between selected and unselected
vertices. See Soft Selection Rollout (Edit/Editable Mesh).
Vertex Interpolation rollout
Determines how selected vertices are treated during subdivision. Available only in Vertex
sub-object mode.
 HSDS_Modifier - superclass: modifier 291

For best results, use when moving control grid vertices at a level of detail lower than the
highest in which the vertex resides.
<HSDS_Modifier>.useEdgeDist BooleanClass default: false -- boolean;
Use_Edge_Distance

<HSDS_Modifier>.affectBackface BooleanClass default: false -- boolean;

Affect_Backface
When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the
normals of faces to which they’re attached) are facing in the opposite direction to the
average normal of the selected sub-objects, are affected by the soft selection influence.
Turn off Affect Backfacing when you want to pull faces of a thin object, such as a thin box,
but don’t want to affect faces on the other side of the object.
Note:
Affect Backfacing is not available when editing splines.
When using Edit/Editable Mesh, you can also use the keyboard shortcut CTRL+F to toggle Affect
Backfacing (while the Keyboard Shortcut Override Toggle button is turned on).
<HSDS_Modifier>.edgeDistance Integer default: 1 -- integer;
Edge_Dist
This spinner setting limits the region affected by the number of edges between the
selection and the affected vertices. The affected region is measured in terms of “edge-
distance” space, along the surface, rather than real space.
<HSDS_Modifier>.falloff Float default: 20.0 -- float
Distance in current units from the center to the edge of a sphere defining the affected
region. Use higher falloff settings to achieve more gradual slopes, depending on the scale
of your geometry. Default=20.
Note:
At the Vertex sub-object level, the region specified by the Falloff setting is depicted graphically in
the viewports as a vertex-color gradient from the Sub-selection color (normally red) to the Vertex
Ticks color (normally blue). In addition, this gradient is updated in real time as you change the
Falloff setting.
<HSDS_Modifier>.pinch Float default: 0.0 -- float
Raises and lowers the top point of the curve along the vertical axis. Sets the relative
“pointedness” of the region. When negative, a crater is produced instead of a point. At a
setting of 0, Pinch produces a smooth transition across this axis. Default=0.
<HSDS_Modifier>.bubble Float default: 0.0 -- float
Expands and contracts the curve along the vertical axis. Sets the relative “fullness” of the
region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for
Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble
move the bottom of the curve below the surface, creating a “valley” around the base of the
region. Default=0.
292 Chapter 1 | What’s New in 3ds max 4 MAXScript

<HSDS_Modifier>.vertexType Integer default: 0 -- integer;

Vertex_Type]
Standard/Conic/Cusp/Corner:
Determines how closely mesh vertices follow the movement of control grid vertices.
Standard provides the least amount of relative movement, while Cusp and Corner provide
the most. Corner also more closely matches mesh edges to the control grid edges attached
to the moved vertex. Default=Standard.

See Also
HSDS Modifier interfaces: (p. 453)

HSDSObject - superclass: modifier

HSDSObject - superclass: modifier; super-superclass:MAXWrapper - 12:0 - classID: #(341062, 28997)
Constructor:
HSDSObject ...

Properties:
<HSDSObject>.levelOfDetail Integer default: 0 -- integer; LOD
Shows the current level of the subdivision hierarchy. Automatically increments when you
subdivide a sub-object selection. To edit at a different level of detail, change the setting to
the desired level.
<HSDSObject>.matId Integer default: 1 -- integer; Material_Id
Displays the material ID assigned to the current selection. Available only in Polygon and
Element sub-object modes. If multiple sub-objects are selected and they don’t share an ID,
this field is blank.
<HSDSObject>.shadedLattice BooleanClass default: false -- boolean;
Shaded_Lattice
Displays only polygons at the current level of detail, with highlights, but without
smoothing. Use this option to speed up the display when working with complex objects.
Default=off.
<HSDSObject>.ignoreBackface BooleanClass default: false -- boolean;
Ignore_Backface
When on, you can select only those sub-objects whose normals are visible in the viewport.
When off (the default), selection includes all sub-objects, regardless of the direction of
their normals.
<HSDSObject>.useSoftSel BooleanClass default: false -- boolean;
Use_Soft_Selection
These controls let you set a gradual falloff of influence between selected and unselected
vertices. See Soft Selection Rollout (Edit/Editable Mesh).
Vertex Interpolation rollout
 HSDSObject - superclass: modifier 293

Determines how selected vertices are treated during subdivision. Available only in Vertex
sub-object mode.
For best results, use when moving control grid vertices at a level of detail lower than the
highest in which the vertex resides.
<HSDSObject>.useEdgeDist BooleanClass default: false -- boolean;
Use_Edge_Distance
This setting limits the region affected by the number of edges between the selection and
the affected vertices. The affected region is measured in terms of “edge-distance” space,
along the surface, rather than real space.
<HSDSObject>.affectBackface BooleanClass default: false -- boolean;
Affect_Backface

When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the
normals of faces to which they’re attached) are facing in the opposite direction to the
average normal of the selected sub-objects, are affected by the soft selection influence.
Turn off Affect Backfacing when you want to pull faces of a thin object, such as a thin box,
but don’t want to affect faces on the other side of the object.
Note:
Affect Backfacing is not available when editing splines.
When using Edit/Editable Mesh, you can also use the keyboard shortcut CTRL+F to toggle Affect
Backfacing (while the Keyboard Shortcut Override Toggle button is turned on).
<HSDSObject>.edgeDistance Integer default: 1 -- integer; Edge_Dist
This setting limits the region affected by the number of edges between the selection and
the affected vertices. The affected region is measured in terms of “edge-distance” space,
along the surface, rather than real space.
<HSDSObject>.falloff Float default: 20.0 -- float
Distance in current units from the center to the edge of a sphere defining the affected
region. Use higher falloff settings to achieve more gradual slopes, depending on the scale
of your geometry. Default=20.
Note:
At the Vertex sub-object level, the region specified by the Falloff setting is depicted graphically in
the viewports as a vertex-color gradient from the Sub-selection color (normally red) to the Vertex
Ticks color (normally blue). In addition, this gradient is updated in real time as you change the
Falloff setting.
<HSDSObject>.pinch Float default: 0.0 -- float
Raises and lowers the top point of the curve along the vertical axis. Sets the relative
“pointedness” of the region. When negative, a crater is produced instead of a point. At a
setting of 0, Pinch produces a smooth transition across this axis. Default=0.
<HSDSObject>.bubble Float default: 0.0 -- float
Expands and contracts the curve along the vertical axis. Sets the relative “fullness” of the
region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for
294 Chapter 1 | What’s New in 3ds max 4 MAXScript

Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble
move the bottom of the curve below the surface, creating a “valley” around the base of the
region. Default=0.
<HSDSObject>.vertexType Integer default: 0 -- integer;
Vertex_Type]
Standard/Conic/Cusp/Corner:
Determines how closely mesh vertices follow the movement of control grid vertices.
Standard provides the least amount of relative movement, while Cusp and Corner provide
the most. Corner also more closely matches mesh edges to the control grid edges attached
to the moved vertex. Default=Standard.

See Also
HSDSObject interfaces: (p. 453)

imageMotionBlur - superclass: renderEffect

imageMotionBlur - superclass: renderEffect; super-superclass:MAXWrapper - 2:0 - classID:
#(141333203, 1612379012)
Constructor:
imageMotionBlur ...

Properties:
<imageMotionBlur>.duration Float default: 1.0 -- animatable; float
Specifies how long the “virtual shutter” is open. When this is set to 1.0, the virtual shutter
is open for the entire duration between one frame and the next. The higher the value, the
greater the motion Blur effect. Default=1.0.
<imageMotionBlur>.transparency BooleanClass default: true -- boolean
When on, motion blur is applied to objects behind transparent objects. When off, objects
behind transparent objects receive no motion blur. Turning off this toggle can improve
rendering speed. Default=on.

See Also
imageMotionBlur interfaces: (p. 454)

Link - superclass: Matrix3Controller

Link - superclass: Matrix3Controller; super-superclass:MAXWrapper - 2:1 - classID: #(-2025855132, -
1430354431)
A Link constraint is used to animate an object linking from one target object to another.
The Link constraint causes an object to inherit the position, rotation and scale of its target object.
 Link.link_params - superclass: MAXObject 295

Constructor:
Link ...

Properties:
<Link>.key_mode Integer default: 0 -- integer; Link_KeyMode
<Link>.link_params SubAnim default: SubAnim:Link_Params -- transform

See Also
Link.link_params - superclass: MAXObject (p. 295)

Link.link_params - superclass: MAXObject

Link.link_params - superclass: MAXObject; super-superclass:Value - 3:3 - classID: #(8197, 0)
Constructor:
Link.link_params ...

Properties:
<Link.link_params>.position Point3 default: [0,0,0] -- animatable;
point3
<Link.link_params>.rotation Quat default: (quat 0 0 0 1) -- animatable;
quat
<Link.link_params>.scale Point3 default: [1,1,1] -- animatable;
point3

See Also
Link interfaces: (p. 455)
Link - superclass: Matrix3Controller (p. 294)

Link_Constraint - superclass: Matrix3Controller

Link_Constraint - superclass: Matrix3Controller; super-superclass:MAXWrapper - 2:1 - classID: #(-
2025855132, -1430354431)
A Link constraint is used to animate an object linking from one target object to another.
The Link constraint causes an object to inherit the position, rotation and scale of its target object.
Constructor:
Link_Constraint ...

Properties:
<Link_Constraint>.key_mode Integer default: 0 -- integer; Link_KeyMode
Remarks:
You can choose between 3 different Key Modes which will determine how keyframes are written
on the linked objects as part of the link constraint. These options will provide the following:
296 Chapter 1 | What’s New in 3ds max 4 MAXScript

No Key Mode: No keys are created any of the objects involved.

Key Nodes: Sets keys for some of the objects.
Child: Applied keys to the child object only.
Parents: Applies keys to both parents and the child object.
Key Entire Hierarchy: This applies keyframes to the chosen nodes and their entire
hierarchies.
Child: Keys the chosen object and the nodes in its hierarchy up to the world.
Parents: Keys both parents and the child and all three hierarchies up to the world.
<Link_Constraint>.link_params SubAnim default: SubAnim:Link_Params --
transform

See Also
Link Constraint.link params - superclass: MAXObject (p. 296)
Link Constraint interfaces: (p. 455)

Link Constraint.link params - superclass: MAXObject

Link Constraint.link params - superclass: MAXObject; super-superclass:Value - 3:3 - classID: #(8197, 0)
Constructor:
Link_Constraint.link_params ...

Properties:
<Link_Constraint.link_params>.position Point3 default: [0,0,0] --
animatable; point3
<Link_Constraint.link_params>.rotation Quat default: (quat 0 0 0 1) --
animatable; quat
<Link_Constraint.link_params>.scale Point3 default: [1,1,1] --
animatable; point3

See Also
Link_Constraint interfaces: (p. 455)
Link_Constraint - superclass: Matrix3Controller (p. 295)
 LinkedXForm - superclass: modifier 297

LinkedXForm - superclass: modifier

LinkedXForm - superclass: modifier; super-superclass:MAXWrapper - 1:0 - classID: #(806195, 0)
Constructor:
LinkedXForm ...

Properties:
<LinkedXForm>.node UndefinedClass default: undefined -- node
Object that the vertices are linked to. When transformed, the vertices follow.

LookAt_Constraint - superclass: RotationController

LookAt_Constraint - superclass: RotationController; super-superclass:MAXWrapper - 11:0 - classID:
#(8225, 0)
Constructor:
LookAt_Constraint ...

Properties:
<LookAt_Constraint>.relative BooleanClass default: false --
boolean
<LookAt_Constraint>.lookat_vector_length Float default: 100.0 --
animatable; float; Vector_Length
<LookAt_Constraint>.set_orientation BooleanClass default: false --
boolean
<LookAt_Constraint>.target_axis Integer default: 2 -- integer
<LookAt_Constraint>.target_axisFlip BooleanClass default: false --
boolean
<LookAt_Constraint>.upnode_axis Integer default: 0 -- integer
<LookAt_Constraint>.upnode_world BooleanClass default: true --
boolean
<LookAt_Constraint>.pickUpNode UndefinedClass default: undefined --
node; Pick_Upnode
<LookAt_Constraint>.StoUP_axis Integer default: 0 -- integer
<LookAt_Constraint>.StoUP_axisFlip BooleanClass default: false --
boolean
<LookAt_Constraint>.viewline_length_abs BooleanClass default: true --
boolean; Viewline_Abs

See Also
LookAt Constraint interfaces: (p. 455)
298 Chapter 1 | What’s New in 3ds max 4 MAXScript

Mesher - superclass: GeometryClass

Mesher - superclass: GeometryClass; super-superclass:node - 8:0 - classID: #(998877, 32670)
Constructor:
Mesher ...

Properties:
<Mesher>.pick UndefinedClass default: undefined -- node
Click this button and then select the object to be instanced by the Mesher object. After
doing so, the name of the instanced object appears on the button.
<Mesher>.renderTimeOnly BooleanClass default: false -- boolean
When on, the Mesher particles do not appear in the viewports, but only when you render
the scene. Default=off.
<Mesher>.extranodes ArrayParameter default: #() -- node array
<Mesher>.time Float default: 0.0 -- float
The number of frames ahead of or behind the original particle system that the Mesher’s
particle system will run. Default=0.
<Mesher>.radius Float default: 10.0 -- float
<Mesher>.useCustomBounds BooleanClass default: false -- boolean;
Use_Custom_Bounds
When on, Mesher replaces the dynamic bounding box derived from the particle system
and modifier with a static bounding box of the user’s choice.
<Mesher>.boundsMin Point3 default: [1,1,1] -- point3; BoundsA
<Mesher>.boundsMax Point3 default: [-1,-1,-1] -- point3;
BoundsB
The coordinates of the opposite corners of the custom bounding box.

See Also
Mesher (p. 82)
particleMesher - superclass: GeometryClass (p. 306)

meshsmooth - superclass: modifier

meshsmooth - superclass: modifier; super-superclass:MAXWrapper - 29:0 - classID: #(50, 32670)
Constructor:
meshsmooth ...

Properties:
<meshsmooth>.subdivMethod Integer default: 2 -- integer;
Subdivision_Method
Selects the Subdivision method to use:
 meshsmooth - superclass: modifier 299

0-Classic (Produces three- and four-sided facets.)

1-Quad Output (Produces only four-sided facets.)
2-NURMS (Produces Non-Uniform Rational MeshSmooth object.)
<meshsmooth>.ignoreSel BooleanClass default: true -- boolean;
Apply_To_Whole_Mesh
When turned on, any sub-object selection passed up the stack is ignored and MeshSmooth
is applied to the entire object.
<meshsmooth>.oldMapping BooleanClass default: false -- boolean;
Old_style_Mapping
Uses the algorithm from the previous release of the program to apply MeshSmooth to the
mapping coordinates. This technique tends to distort the underlying mapping coordinates
as it creates new faces and as texture coordinates shift.
<meshsmooth>.iterations Integer default: 0 -- animatable; integer
The number of iterations used to smooth the mesh. Each iteration generates new faces
using the vertices created from the previous iteration.
<meshsmooth>.smoothness Float default: 1.0 -- animatable; float;
Smoothness_Filter
Determines how sharp a corner must be before faces are added to smooth it. Smoothness is
calculated as the average angle of all edges connected to a vertex. A value of 0.0 prevents
the creation of any faces. A value of 1.0 adds faces to all vertices even if they lie on a plane.
<meshsmooth>.useRenderIterations BooleanClass default: false -- boolean;
Use_Render_Iterations
Turn on/off use of render iterations, for using a different number of iterations at render
time. When off, the software will use the iterations value.
<meshsmooth>.renderItSerations Integer default: 0 -- animatable;
integer; Render_Iterations
Number of smoothing iterations to be applied to the object at render time.
<meshsmooth>.useRenderSmoothness BooleanClass default: false -- boolean;
Use_Render_Smoothness
Turn on/off use of render smoothness, for using a different smoothness value at render
time. When off, the software will use the smoothness value.
<meshsmooth>.renderSmoothness Float default: 1.0 -- animatable; float;
Render_Smoothness
Lets you choose a different Smoothness value to be applied to the object at render time.
<meshsmooth>.faceType Integer default: 1 -- integer; Face_Type
Select the type to operate on during input conversion:
0-Faces
1-Polygons
Operate On Faces treats every triangle as a face and smooths across all edges, even invisible
edges. Operate On Polygons ignores invisible edges, treating polygons (like the quads
making up a box or the cap on a cylinder) as a single face.
300 Chapter 1 | What’s New in 3ds max 4 MAXScript

<meshsmooth>.keepConvex BooleanClass default: false -- boolean;

Keep_Input_Faces_Convex
Keeps all input polygons convex. Selecting this option causes non-convex polygons to be
handled as a minimum number of separate faces, each of which is convex.
<meshsmooth>.update Integer default: 0 -- integer; Update_Options
Set update options:
0-Always update
1-Update when rendering
2-Update Manually
<meshsmooth>.limitSurface BooleanClass default: false -- boolean;
Project_to_Limit_Surface
Places all points on the “limit surface” of the MeshSmooth result, which is the surface
you’d get after an infinite number of iterations.
<meshsmooth>.smoothResult BooleanClass default: true -- boolean;
Smooth_Output
Applies the same smoothing group to all faces.
<meshsmooth>.sepByMats BooleanClass default: false -- boolean;
Separate_By_Materials
Prevents the creation of new faces for edges between faces that do not share Material IDs.
<meshsmooth>.sepBySmGroups BooleanClass default: false -- boolean;
Separate_By_Smoothing_Group
Prevents the creation of new faces at edges between faces that don’t share at least one
smoothing group.
<meshsmooth>.ignoreBackfacing BooleanClass default: false -- boolean;
Ignore_Backfacing
When on, selection of sub-objects selects only those sub-objects whose normals are visible
in the viewport. When off (the default), selection includes all sub-objects, regardless of the
direction of their normals.
<meshsmooth>.displayCage BooleanClass default: false -- boolean;
Display_Control_Mesh
Displays an orange wireframe gizmo that shows what the control mesh looks like after it’s
been converted to polygons (if applicable) and before the smoothing occurs.
<meshsmooth>.controlLevel Integer default: 0 -- integer; Control_Level
Allows you to see the control mesh after one or more iterations and to edit sub-object
points and edges at that level.
<meshsmooth>.useSoftSel BooleanClass default: false -- boolean;
Use_Soft_Selection
Affects the action of Move, Rotate, and Scale functions within editable object or edit
modifier, and the action of deformation modifiers applied to the object if they are
operating on a sub-object selection. When on, 3ds max applies a spline curve deformation
to the unselected sub-objects surrounding the selection that you transform.
 meshsmooth - superclass: modifier 301

<meshsmooth>.useEdgeDist BooleanClass default: false -- boolean;

Use_Edge_Distance
Turn on/off use Edge Distance.
<meshsmooth>.edgeDist Integer default: 1 -- integer; Edge_Distance
Limits the region affected by the number of edges between the selection and the affected
vertices.
<meshsmooth>.affectBackfacing BooleanClass default: false -- boolean;
Affect_Backfacing
When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the
normals of faces to which they’re attached) are facing in the opposite direction to the
average normal of the selected sub-objects, are affected by the soft selection influence.
<meshsmooth>.falloff Float default: 20.0 -- float
Distance in current units from the center to the edge of a sphere defining the affected
region. Use higher falloff settings to achieve more gradual slopes, depending on the scale
of your geometry.
<meshsmooth>.pinch Float default: 0.0 -- float
Raises and lowers the top point of the curve along the vertical axis. Sets the relative
“pointedness” of the region. When negative, a crater is produced instead of a point. At a
setting of 0, Pinch produces a smooth transition across this axis.
<meshsmooth>.bubble Float default: 0.0 -- float
Expands and contracts the curve along the vertical axis. Sets the relative “fullness” of the
region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for
Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble
move the bottom of the curve below the surface, creating a “valley” around the base of the
region.
<meshsmooth>.reset Integer default: 1 -- integer; Update_Options
Select reset settings:
0-Reset all levels
1-Reset this level

See Also
MeshSmooth : Modifier (p. 1139)
302 Chapter 1 | What’s New in 3ds max 4 MAXScript

Modifier and SpacewarpModifier Types (p. 1100)

Motion_Blur - superclass: renderEffect

Motion_Blur - superclass: renderEffect; super-superclass:MAXWrapper - 2:0 - classID: #(141333203,
1612379012)
Constructor:
Motion_Blur ...

Properties:
<Motion_Blur>.duration Float default: 1.0 -- animatable;
float
Specifies how long the “virtual shutter” is open. When this is set to 1.0, the virtual shutter
is open for the entire duration between one frame and the next. The higher the value, the
greater the motion Blur effect. Default=1.0.
<Motion_Blur>.transparency BooleanClass default: true -- boolean
When on, motion blur is applied to objects behind transparent objects. When off, objects
behind transparent objects receive no motion blur. Turning off this toggle can improve
rendering speed. Default=on.

See Also
Motion_Blur interfaces: (p. 462)

MultiRes - superclass: modifier

MultiRes - superclass: modifier; super-superclass:MAXWrapper - 10:0 - classID: #(1788759147,
1229407453)
The MultiRes modifier reduces the memory overhead needed to render models by decreasing the
number of vertices and polygons. This is useful not only within 3ds max but for game and Web
content creators who export models for use outside of MAX. MultiRes offers several advantages over
the Optimize modifier, including faster operation and the ability to specify reduction as an exact
percentage or vertex count.
Constructor:
MultiRes ...

Properties:
<MultiRes>.Vtx_Count Integer default: 0 -- animatable;
integer
The total number of vertices in the modified object. Use this control to set the maximum
number of vertices in the output mesh. Adjusting this setting alters the Percent value
as well.
 MultiRes - superclass: modifier 303

<MultiRes>.Vertex_Percentage Float default: 100.0 --

animatable; float
The modified object’s vertex count as a percentage of the overall number of vertices in the
original mesh. Adjusting this setting alters the Count value as well.
Note: After you type in a specific percentage, such as 30, you might find that the software
changes the value to a slightly lower one, such as 29.971. This is due to the relationship
between the overall number of vertices in the model and the percentage calculation. It is
not a bug, but simply the closest solution to your request.
<MultiRes>.Vertex_Merging BooleanClass default: false -- boolean
When on, lets MultiRes merge vertices between discrete elements in a model.
For example, if you apply MultiRes to a teapot, which comprises four separate elements,
and turn on Vertex Merging, as you adjust the vertex resolution, the separate components
will meld together into one contiguous lower-resolution object.
To control Vertex Merging, you can set a Merge Threshold. This value determines the
3ds max unit distance within which to merge elements.
<MultiRes>.Threshold Float default: 0.0 -- float
This spinner value sets the maximum distance in 3ds max units between vertices in order
for those vertices to be considered for merging. Once this threshold is achieved, then the
vertices between elements will be welded together as the mesh is reduced in complexity.
Note: To eliminate only coincident vertices, set Merge Threshold to 0.0. This is similar to
the Weld Vertex function.
<MultiRes>.Merge_Within BooleanClass default: false -- boolean
When on, MultiRes merges the boundaries of adjacent elements and vertices within
elements. Many objects can contain multiple groups of vertices that don’t share
connectivity. A simple example of this is the Teapot object. It comprises four different
elements: the body, the handle, the spout, and the lid. Normally, MultiRes optimizes each
discrete element in a mesh on its own.
The default behavior of the Vertex Merging option is to merge vertices between elements.
Turning on Within Mesh? causes vertices within elements to be merged as well.
<MultiRes>.Boundary_Metric BooleanClass default: false -- boolean
When on, MultiRes preserves materials assigned to the selected model. The material
boundaries defined by Material IDs are retained as long as possible, and are the last to be
eliminated at low vertex counts. Default=off.
<MultiRes>.Maintain_Base_Vertices BooleanClass default: false -- boolean
When on, overrides the MultiRes optimization algorithms and preserves any vertices
selected at the MultiRes Vertex sub-object level as “critical” ones. Use this feature to retain
critical features of an object or character such as its fingers or claws, or other geometry that
might become unrecognizable if reduced too severely.
To select vertices for use with this option, use the MultiRes Vertex sub-object level. To
access this level, first go to the modifier stack display and click the plus-sign icon next to
the MultiRes modifier. This opens up its hierarchy, which consists of the single Vertex sub-
304 Chapter 1 | What’s New in 3ds max 4 MAXScript

object level. Next, click the Vertex entry. The MultiRes vertices appear on the mesh as blue
dots. You can select these using any standard interactive method, but you cannot
transform them.
Important: After selecting MultiRes sub-object vertices with Maintain Base Vertices turned
on, re-generate the mesh before changing the vertex resolution.
In the following illustration, the clown started out as a high-resolution mesh. All of the
MultiRes vertices in the right half were selected, Maintain Base Vertices was turned on, and
then the vertices were reduced.
{mrm_clown.bmp}
<MultiRes>.Multiple_Normals_Per_Vertex BooleanClass default: true -- boolean
When on, lets MultiRes assign multiple normals for each vertex. By default, MultiRes
generates a single normal per vertex.
If multiple normals are generated, they are applied as the vertex resolution is decreased
and increased.
When the Multiple Normals Per Vertex option is checked, the MultiRes modifier generates
normal updates when the geometry surrounding a vertex changes. You must specify a
crease angle in degrees (0.0 - 180.0). The crease angle is the angle between the face normals.
It is used to decide when a normal should be shared across an edge between two faces.
For example, in a plane defined as a mesh grid of 10 x 10 faces, any two adjacent faces
have a crease angle of zero. In a cube, adjacent faces have a crease angle of 90 degrees. In
general, crease angles approaching 0 yield smoother shading. Crease angles approaching
180 yield more visible corners.
<MultiRes>.Crease_Angle Float default: 75.0 -- float
The value of the crease necessary in order to generate multiple normals. Available only
when Multiple Normals Per Vertex is on.
The optimal crease angle depends on the model; set it interactively and check the viewport
and rendered images for shading effects. While use of multiple normals per vertex enables
more accurate shading, it can require more internal data.
<MultiRes>.Generate BooleanClass default: false -- boolean
Applies the current MultiRes settings to the modified object. When you first apply
MultiRes to an object, it must initialize its mesh-optimizing algorithm; you are prompted
by the modifier to “Generate when ready”.
Note: When working with complex meshes, the initial analysis may take a little while.
During this time, MultiRes displays a special cursor to indicate it is working. Progress is
indicated on this cursor by the movement of the gray area from top to bottom. To cancel
this process, press ESC.
 Normalize_Spl - superclass: modifier 305

Example:
modPanel.addModToSelection(MultiRes())
$.modifiers[#MultiRes].Vtx_Count = 482
$.modifiers[#MultiRes].Vertex_Percentage = 100
$.modifiers[#MultiRes].Vertex_Percentage = 99
$.modifiers[#MultiRes].Vtx_Count = 476
$.modifiers[#MultiRes].Vertex_Percentage = 98.7552
$.modifiers[#MultiRes].Vertex_Merging = on
$.modifiers[#MultiRes].Threshold = 0.01
$.modifiers[#MultiRes].Merge_Within = on
$.modifiers[#MultiRes].Boundary_Metric = on
$.modifiers[#MultiRes].Maintain_Base_Vertices = on
$.modifiers[#MultiRes].Crease_Angle = 75.75

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Normalize_Spl - superclass: modifier

Normalize_Spl - superclass: modifier; super-superclass:MAXWrapper - 1:0 - classID: #(474287708,
772671746)
Constructor:
Normalize_Spl ...

Properties:
<Normalize_Spl>.Length Float default: 20.0 -- float
Determines how many control points are added. Smaller values produce more control
points; larger values produce fewer.
The positions of the original vertices are disregarded. Vertices are set to regular intervals
once the Normalize Spline modifier is applied.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods
306 Chapter 1 | What’s New in 3ds max 4 MAXScript

Orientation_Constraint - superclass: RotationController

Orientation_Constraint - superclass: RotationController; super-superclass:MAXWrapper - 2:0 -
classID: #(8224, 0)
Constructor:
Orientation_Constraint ...

Properties:
<Orientation_Constraint>.relative BooleanClass default: false --
boolean
<Orientation_Constraint>.local_world Integer default: 0 -- integer;
LocalOrWorld

See Also
Orientation_Constraint interfaces: (p. 462)

particleMesher - superclass: GeometryClass

particleMesher - superclass: GeometryClass; super-superclass:node - 8:0 - classID: #(998877, 32670)
The Mesher compound object converts procedural objects to mesh objects on a per-frame basis so
that you can apply modifiers such as Bend or UVW Map. It can be used with any type of object, but
is designed primarily to work with particle systems. Mesher is also useful for low-overhead
instancing of objects with complex modifier stacks.
Constructor:
particleMesher ...

Properties:
<particleMesher>.pick UndefinedClass default: undefined -- node
Click this button and then select the object to be instanced by the Mesher object. After
doing so, the name of the instanced object appears on the button.
<particleMesher>.renderTimeOnly BooleanClass default: false -- boolean
When on, the Mesher particles do not appear in the viewports, but only when you render
the scene. Default=off.
Use this option to reduce the amount of computation required for the viewport display.
<particleMesher>.extranodes ArrayParameter default: #() -- node array
<particleMesher>.time Float default: 0.0 -- float
The number of frames ahead of or behind the original particle system that the Mesher’s
particle system will run. Default=0.
 Patch_Select - superclass: modifier 307

<particleMesher>.radius Float default: 10.0 -- float

<particleMesher>.useCustomBounds BooleanClass default: false -- boolean;
Use_Custom_Bounds
When on, Mesher replaces the dynamic bounding box derived from the particle system
and modifier with a static bounding box of the user’s choice.
<particleMesher>.boundsMin Point3 default: [1,1,1] -- point3;
BoundsA
<particleMesher>.boundsMax Point3 default: [-1,-1,-1] --
point3; BoundsB

See Also
Mesher (p. 82)
Mesher - superclass: GeometryClass (p. 298)

Patch_Select - superclass: modifier

Patch_Select - superclass: modifier; super-superclass:MAXWrapper - 0:0 - classID: #(425273138,
54557306)
The Patch Select modifier lets you pass a sub-object selection up the stack to subsequent modifiers.
It provides a superset of the selection functions available in the Edit Patch modifier. You can select
vertices, edges, patches and elements. You can also change the selection from sub-object level to
object level.

See Also
Patches (p. 55)
patch const StructDef (p. 245)
patchOps const StructDef (p. 247)
Patch : GeometryClass (p. 1088)

Path_Constraint - superclass: PositionController

Path_Constraint - superclass: PositionController; super-superclass:MAXWrapper - 12:0 - classID:
#(8209, 0)
Constructor:
Path_Constraint ...

Properties:
<Path_Constraint>.percent Float default: 0.0 --
animatable; percentage; Controller Scaling: (1 : 100.0)
Sets the percent that the object is positioned along the path. This duplicates the Value
spinner in the track Properties dialog for the Percent track in Track View. If you want to set
keys to place an object at a certain percent along the path, turn on Animate, move to the
308 Chapter 1 | What’s New in 3ds max 4 MAXScript

frame where you want the key set, and adjust the % Along Path spinner to move the
object.
<Path_Constraint>.follow BooleanClass default: false -- boolean
Aligns the object to the trajectory as it follows the contour.
<Path_Constraint>.path UndefinedClass default: undefined --
node; Path_Constraint
Add Path: is used to add a new spline path that influences the constrained object.
Delete path: is used to remove a path from the target list. Once removing the path target,
it will no longer influence the constrained object
<Path_Constraint>.bank BooleanClass default: false -- boolean
Allows the object to bank (roll) as it negotiates the curves of the spline.
<Path_Constraint>.bankAmount Float default: 0.5 --
animatable; float; Bank_Amount
Adjusts the amount of the banking to one side or the other, depending on whether the
value is positive or negative
<Path_Constraint>.smoothness Float default: 0.5 --
animatable; float
Controls how rapidly the roll angle changes as the object moves through bends in the
trajectory. Smaller values will make the object more responsive to subtle changes in the
curve, while larger values smooth out jerking. The default value is a good value for general
damping along the curve. Values below 2 tend to make the action jerky, but values around
3 can be very useful for simulating a certain degree of realistic instability.
<Path_Constraint>.allowUpsideDown BooleanClass default: false --
boolean; Allow_Upside_Down
Turn on to avoid the situation in which an object flips when going around a vertically
oriented path.
<Path_Constraint>.constantVel BooleanClass default: false --
boolean; Constant_Velocity
Provides a constant velocity along the path. When off, the velocity of the object along the
path varies depending on the distance between the vertices on the path.
<Path_Constraint>.axis Integer default: 0 -- integer
Defines which axis of the object is aligned to the trajectory of the path.
<Path_Constraint>.axisFlip BooleanClass default: false --
boolean; Axis_Flip
Turn on to flip the direction of the axis
<Path_Constraint>.loop BooleanClass default: false -- boolean
By default, when the constrained object reaches the end of a path it can no longer move
past the end point. The loop option changes this behavior so that when the constrained
object reaches the end of the path it loops back to the starting point.
<Path_Constraint>.relative BooleanClass default: false -- boolean
Turn on to maintain the original position of the constrained object. The object will follow
the path with an offset distance based on its original world space position
 PDynaflector - superclass: SpacewarpObject 309

See Also
Path_Constraint interfaces: (p. 468)

PDynaflector - superclass: SpacewarpObject

PDynaflector - superclass: SpacewarpObject; super-superclass:node - 21:0 - classID: #(11824263,
1055795908)
Constructor:
...

Properties:
<PDynaflector>.’time on’ Integer default: 0 -- animatable; integer;
Time_On

<PDynaflector>.’time off’ Integer default: 16000 -- animatable; integer;

Time_Off

<PDynaflector>.affects Float default: 10000.0 -- animatable; percentage;

Reflects; Controller Scaling: (1 : 100.0)

<PDynaflector>.bounce Float default: 1.0 -- animatable; float

<PDynaflector>.bouncevar Float default: 0.0 -- animatable; percentage;

Bounce_Variation; Controller Scaling: (1 : 100.0)

<PDynaflector>.chaos Float default: 0.0 -- animatable; percentage;

Controller Scaling: (1 : 100.0)

<PDynaflector>.inheritVelocity Float default: 1.0 -- animatable; float;

Velocity_Inheritance

<PDynaflector>.width Float default: 0.0 -- animatable; float

<PDynaflector>.height Float default: 0.0 -- animatable; float

<PDynaflector>.mass Float default: 1.0 -- animatable; float;

Particle_Mass

<PDynaflector>.’mass units’ Integer default: 0 -- radio button number;

Particle_Mass_Units

<PDynaflector>.’force in x’ Float default: 0.0 -- animatable; float;

Force_in_X_Direction

<PDynaflector>.’force in y’ Float default: 0.0 -- animatable; float;

Force_in_Y_Direction
310 Chapter 1 | What’s New in 3ds max 4 MAXScript

<PDynaflector>.’force in z’ Float default: 0.0 -- animatable; float;

Force_in_Z_Direction

<PDynaflector>.’apply at x’ Float default: 0.0 -- animatable; float;

Apply_at_X_location

<PDynaflector>.’apply at y’ Float default: 0.0 -- animatable; float;

Apply_at_Y_location

<PDynaflector>.’apply at z’ Float default: 0.0 -- animatable; float;

Apply_at_Z_location

<PDynaflector>.number Integer default: 0 -- animatable; integer;

Number_of_Particles

<PDynaflector>.friction Float default: 0.0 -- animatable; percentage;

Controller Scaling: (1 : 100.0)

<PDynaflector>.quality Integer default: 20 -- animatable; integer;

Collision_Quality

<PDynaflector>.collider UndefinedClass default: undefined -- max object;

Collision_Quality

Plane_Angle - superclass: helper

Plane_Angle - superclass: helper; super-superclass:node - 6:0 - classID: #(635524970, 561654288)
Constructor:
Plane_Angle ...

Properties:
<Plane_Angle>.Origin Point3 default: [0,0,0] -- point3
<Plane_Angle>.NormalVec Point3 default: [0,0,1] -- point3; Normal_Vector
<Plane_Angle>.UpVec Point3 default: [0,1,0] -- point3; Up_Vector
<Plane_Angle>.Angle Float default: 0.0 -- animatable; angle;
Controller Scaling: (1 : 57.2958)
The angle of the manipulator, from 0.0 to 360.0 (both values are perpendicular in the Y
axis of the viewport where you created the manipulator, unless you have rotated the
manipulator object). Default=0.0.
<Plane_Angle>.Distance Float default: 0.0 -- float
The length of the manipulator, in 3ds max units. Default=the distance of mouse drag
when the manipulator was created.
<Plane_Angle>.Size Float default: 1.0 -- float
The size of the manipulator’s handle, in 3ds max units. Default=1.0.
 PlaneAngleManip - superclass: helper 311

See Also
Scripted Manipulators (p. 97)
Interface: manip (p. 366)
sliderManipulator interfaces: (p. 520)
radiusManip interfaces: (p. 500)
uvwMappingHeightManip interfaces: (p. 551)
uvwMappingLengthManip interfaces: (p. 555)
uvwMappingUTileManip interfaces: (p. 558)
uvwMappingVTileManip interfaces: (p. 562)
uvwMappingWidthManip interfaces: (p. 565)
ConeAngleManip - superclass: helper (p. 277)
PlaneAngleManip - superclass: helper (p. 311)
Scripted Plug-ins (p. 1538)
sliderManipulator - superclass: helper (p. 333)

PlaneAngleManip - superclass: helper

PlaneAngleManip - superclass: helper; super-superclass:node - 6:0 - classID: #(635524970,
561654288)
Constructor:
PlaneAngleManip ...

Properties:
<PlaneAngleManip>.Origin Point3 default: [0,0,0] -- point3
<PlaneAngleManip>.NormalVec Point3 default: [0,0,1] -- point3;
Normal_Vector
<PlaneAngleManip>.UpVec Point3 default: [0,1,0] -- point3; Up_Vector
<PlaneAngleManip>.Angle Float default: 0.0 -- animatable; angle;
Controller Scaling: (1 : 57.2958)
The angle of the manipulator, from 0.0 to 360.0 (both values are perpendicular in the Y
axis of the viewport where you created the manipulator, unless you have rotated the
manipulator object). Default=0.0.
<PlaneAngleManip>.Distance Float default: 0.0 -- float
The length of the manipulator, in 3ds max units. Default=the distance of mouse drag
when the manipulator was created.
<PlaneAngleManip>.Size Float default: 1.0 -- float
The size of the manipulator’s handle, in 3ds max units. Default=1.0.
312 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
Scripted Manipulators (p. 97)
Interface: manip (p. 366)
sliderManipulator interfaces: (p. 520)
radiusManip interfaces: (p. 500)
uvwMappingHeightManip interfaces: (p. 551)
uvwMappingLengthManip interfaces: (p. 555)
uvwMappingUTileManip interfaces: (p. 558)
uvwMappingVTileManip interfaces: (p. 562)
uvwMappingWidthManip interfaces: (p. 565)
ConeAngleManip - superclass: helper (p. 277)
PlaneAngleManip - superclass: helper (p. 311)
Scripted Plug-ins (p. 1538)
sliderManipulator - superclass: helper (p. 333)

Point3List - superclass: Point3Controller

Point3List - superclass: Point3Controller; super-superclass:MAXWrapper - 1:1 - classID:
#(1263210497, 0)
Constructor:
Point3List ...

Properties:
<Point3List>.available Point3 default: [0,0,0] -- animatable; point3;
Controller Scaling: ([1,1,1] : [0,0,0]); WeirdScaled ([0,0,0])

See Also
Point3List interfaces: (p. 479)

Point3Reactor - superclass: Point3Controller

Point3Reactor - superclass: Point3Controller; super-superclass:MAXWrapper - 0:0 - classID:
#(419957000, 996243513)

See Also
Point3Reactor interfaces: (p. 481)
 Point3Spring - superclass: Point3Controller 313

Point3Spring - superclass: Point3Controller

Point3Spring - superclass: Point3Controller; super-superclass:MAXWrapper - 4:4 - classID:
#(327754098, 1754751609)
Constructor:
Point3Spring ...

Properties:
<Point3Spring>.position Point3 default: [0,0,0] -- animatable; point3
<Point3Spring>.x_effect Float default: 100.0
These settings let you control the percentage of the effect on the individual world axes.
Default=100. Range=0 to 200.
<Point3Spring>.y_effect Float default: 100.0
These settings let you control the percentage of the effect on the individual world axes.
Default=100. Range=0 to 200.
<Point3Spring>.z_effect Float default: 100.0
These settings let you control the percentage of the effect on the individual world axes.
Default=100. Range=0 to 200.

See Also
PositionSpring interfaces: (p. 497)
Point3Spring interfaces: (p. 482)
SpringPoint3Controller interfaces: (p. 523)
SpringPoint3Controller - superclass: Point3Controller (p. 336)
SpringPositionController interfaces: (p. 526)
SpringPositionController - superclass: PositionController (p. 337)
Flex : Modifier (p. 1128)
Flex interfaces: (p. 438)
flexOps const StructDef (p. 235)
314 Chapter 1 | What’s New in 3ds max 4 MAXScript

Point_Cache - superclass: modifier

Point_Cache - superclass: modifier; super-superclass:MAXWrapper - 7:0 - classID: #(567311073,
1221790700)
Constructor:
Point_Cache ...

Properties:
<Point_Cache>.time Float default: 0.0 -- float
<Point_Cache>.start_time Float default: 0.0 -- float
The frame number at which the cached animation starts playing back. Using decimal
fractions lets you start at a sub-frame setting when using a Frame:Ticks time display.
Default=0.0.
Sets the first frame for recording the vertex animation.
<Point_Cache>.end_time Float default: 100.0 -- float
Sets the last frame for recording the vertex animation.
<Point_Cache>.samples Integer default: 1 -- integer
<Point_Cache>.cache_file UndefinedClass default: undefined -- string
Loads a vertex animation from a cache file on disk into the Point Cache modifier. If
number of vertices in the cache file does not match the number of vertices in the object, a
warning appears, but no error occurs.
<Point_Cache>.relativeOffset BooleanClass default: false -- boolean;
Relative_Offset
Makes the Strength setting available. This enables offsetting the animated vertex positions
relative to their positions as recorded. Default=off.
Note: When you turn on Use Relative Offsets and play back a cached animation with the
modifiers turned on, the cached vertex positions are calculated relative to their positions
as calculated by the modifiers. For example, if you record a Bend animation to a cache file,
and then play it back with both Use Relative Offsets and the Bend modifier turned on and
Strength=1.0, all vertex positions are doubled, resulting in exaggerated motion.
<Point_Cache>.strength Float default: 1.0 -- animatable; float
Affects the motion relative to the original animation. Available only when Use Relative
Offsets is turned on. Default=1.0. Range=-10.0 to 10.0.
At 1.0, the animation plays back the same as recorded. With strengths between 0 and 1,
the animation is relatively restrained. At strengths greater than 1, the animation is
exaggerated. With negative Strength settings, the motion is reversed.

See Also
Point Cache Modifier (p. 26)
Point_Cache interfaces: (p. 484)
Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315)
Point_CacheSpacewarpModifier interfaces: (p. 485)
 Point_CacheSpacewarpModifier - superclass: SpacewarpModifier 315

Point_CacheSpacewarpModifier - superclass: SpacewarpModifier

Point_CacheSpacewarpModifier - superclass: SpacewarpModifier; super-superclass:MAXWrapper -
7:0 - classID: #(567311073, 1221790701)
Constructor:
Point_CacheSpacewarpModifier ...

Properties:
<Point_CacheSpacewarpModifier>.time Float default: 0.0 --
float
<Point_CacheSpacewarpModifier>.start_time Float default: 0.0 --
float
The frame number at which the cached animation starts playing back. Using decimal
fractions lets you start at a sub-frame setting when using a Frame:Ticks time display.
Default=0.0.
Sets the first frame for recording the vertex animation.
<Point_CacheSpacewarpModifier>.end_time Float default: 100.0 --
float
Sets the last frame for recording the vertex animation.
<Point_CacheSpacewarpModifier>.samples Integer default: 1 --
integer
<Point_CacheSpacewarpModifier>.cache_file UndefinedClass default:
undefined -- string
Loads a vertex animation from a cache file on disk into the Point Cache modifier. If
number of vertices in the cache file does not match the number of vertices in the object, a
warning appears, but no error occurs.
<Point_CacheSpacewarpModifier>.relativeOffset BooleanClass default: false --
boolean; Relative_Offset
Makes the Strength setting available. This enables offsetting the animated vertex positions
relative to their positions as recorded. Default=off.
Note: When you turn on Use Relative Offsets and play back a cached animation with the
modifiers turned on, the cached vertex positions are calculated relative to their positions
as calculated by the modifiers. For example, if you record a Bend animation to a cache file,
and then play it back with both Use Relative Offsets and the Bend modifier turned on and
Strength=1.0, all vertex positions are doubled, resulting in exaggerated motion.
<Point_CacheSpacewarpModifier>.strength Float default: 1.0 --
animatable; float
Affects the motion relative to the original animation. Available only when Use Relative
Offsets is turned on. Default=1.0. Range=-10.0 to 10.0.
At 1.0, the animation plays back the same as recorded. With strengths between 0 and 1,
the animation is relatively restrained. At strengths greater than 1, the animation is
exaggerated. With negative Strength settings, the motion is reversed.
316 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
Point Cache Modifier (p. 26)
Point_Cache interfaces: (p. 484)
Point_Cache - superclass: modifier (p. 314)
Point_CacheSpacewarpModifier interfaces: (p. 485)

PointCache - superclass: modifier

PointCache - superclass: modifier; super-superclass:MAXWrapper - 7:0 - classID: #(567311073,
1221790700)
Constructor:
PointCache ...

Properties:
<PointCache>.time Float default: 0.0 -- float
<PointCache>.start_time Float default: 0.0 -- float
The frame number at which the cached animation starts playing back. Using decimal
fractions lets you start at a sub-frame setting when using a Frame:Ticks time display.
Default=0.0.
Sets the first frame for recording the vertex animation.
<PointCache>.end_time Float default: 100.0 -- float
Sets the last frame for recording the vertex animation.
<PointCache>.samples Integer default: 1 -- integer
<PointCache>.cache_file UndefinedClass default: undefined -- string
Loads a vertex animation from a cache file on disk into the Point Cache modifier. If
number of vertices in the cache file does not match the number of vertices in the object, a
warning appears, but no error occurs.
<PointCache>.relativeOffset BooleanClass default: false -- boolean;
Relative_Offset
Makes the Strength setting available. This enables offsetting the animated vertex positions
relative to their positions as recorded. Default=off.
Note: When you turn on Use Relative Offsets and play back a cached animation with the
modifiers turned on, the cached vertex positions are calculated relative to their positions
as calculated by the modifiers. For example, if you record a Bend animation to a cache file,
and then play it back with both Use Relative Offsets and the Bend modifier turned on and
Strength=1.0, all vertex positions are doubled, resulting in exaggerated motion.
 PointCacheWSM - superclass: SpacewarpModifier 317

<PointCache>.strength Float default: 1.0 -- animatable; float

Affects the motion relative to the original animation. Available only when Use Relative
Offsets is turned on. Default=1.0. Range=-10.0 to 10.0.
At 1.0, the animation plays back the same as recorded. With strengths between 0 and 1,
the animation is relatively restrained. At strengths greater than 1, the animation is
exaggerated. With negative Strength settings, the motion is reversed.

See Also
Point Cache Modifier (p. 26)
Point_Cache interfaces: (p. 484)
Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315)
Point_CacheSpacewarpModifier interfaces: (p. 485)

PointCacheWSM - superclass: SpacewarpModifier

PointCacheWSM - superclass: SpacewarpModifier; super-superclass:MAXWrapper - 7:0 - classID:
#(567311073, 1221790701)
Constructor:
PointCacheWSM ...

Properties:
<PointCacheWSM>.time Float default: 0.0 -- float
<PointCacheWSM>.start_time Float default: 0.0 -- float
The frame number at which the cached animation starts playing back. Using decimal
fractions lets you start at a sub-frame setting when using a Frame:Ticks time display.
Default=0.0.
Sets the first frame for recording the vertex animation.
<PointCacheWSM>.end_time Float default: 100.0 -- float
Sets the last frame for recording the vertex animation.
<PointCacheWSM>.samples Integer default: 1 -- integer
<PointCacheWSM>.cache_file UndefinedClass default: undefined -- string
Loads a vertex animation from a cache file on disk into the Point Cache modifier. If
number of vertices in the cache file does not match the number of vertices in the object, a
warning appears, but no error occurs.
318 Chapter 1 | What’s New in 3ds max 4 MAXScript

<PointCacheWSM>.relativeOffset BooleanClass default: false -- boolean;

Relative_Offset
Makes the Strength setting available. This enables offsetting the animated vertex positions
relative to their positions as recorded. Default=off.
Note: When you turn on Use Relative Offsets and play back a cached animation with the
modifiers turned on, the cached vertex positions are calculated relative to their positions
as calculated by the modifiers. For example, if you record a Bend animation to a cache file,
and then play it back with both Use Relative Offsets and the Bend modifier turned on and
Strength=1.0, all vertex positions are doubled, resulting in exaggerated motion.
<PointCacheWSM>.strength Float default: 1.0 -- animatable; float
Affects the motion relative to the original animation. Available only when Use Relative
Offsets is turned on. Default=1.0. Range=-10.0 to 10.0.
At 1.0, the animation plays back the same as recorded. With strengths between 0 and 1,
the animation is relatively restrained. At strengths greater than 1, the animation is
exaggerated. With negative Strength settings, the motion is reversed.

See Also
Point Cache Modifier (p. 26)
Point_Cache interfaces: (p. 484)
Point_Cache - superclass: modifier (p. 314)
Point_CacheSpacewarpModifier interfaces: (p. 485)

PointHelperObj - superclass: helper

PointHelperObj - superclass: helper; super-superclass:node - 7:0 - classID: #(8211, 0)
Constructor:
PointHelperObj ...

Properties:
<PointHelperObj>.size Float default: 20.0 --
animatable; float
Sets the size for the point object. Use this to minimize the point object, or increase its size
to aid in locating it. Default=20.
<PointHelperObj>.centermarker BooleanClass default: false --
animatable; boolean; Center_Marker
Displays a small X marker at the center of the point object.
<PointHelperObj>.axistripod BooleanClass default: false --
animatable; boolean; Axis_Tripod
Displays a tripod axis indicating the position and orientation of the point object. The axis
remains visible when the point object is no longer selected.
 Poly_Select - superclass: modifier 319

<PointHelperObj>.cross BooleanClass default: true --

animatable; boolean
Displays an axis-aligned cross.
<PointHelperObj>.box BooleanClass default: false --
animatable; boolean
Displays a small box at the center of the point object.
<PointHelperObj>.constantscreensize BooleanClass default: false --
animatable; boolean; Constant_Screen_Size
Keeps the size of the point object constant, regardless of how much you zoom in or out.
<PointHelperObj>.drawontop BooleanClass default: false --
animatable; boolean; Draw_On_Top
Displays the point object on top of all other objects in the scene.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Poly_Select - superclass: modifier

Poly_Select - superclass: modifier; super-superclass:MAXWrapper - 7:0 - classID: #(2095390827,
823661829)
Constructor:
Poly_Select ...

Properties:
<Poly_Select>.useSoftSelection BooleanClass default: false --
boolean; Use_Soft_Selection
Affects the action of Move, Rotate, and Scale functions within editable object or edit
modifier, and the action of deformation modifiers applied to the object if they are
operating on a sub-object selection. When on, 3ds max applies a spline curve deformation
to the unselected sub-objects surrounding the selection that you transform. To take effect,
this check box must be on before moving the selection.
You can also use the keyboard shortcut CTRL+S to toggle Use Soft Selection (while the
Plug-In Keyboard Shortcut Toggle button is turned on).
<Poly_Select>.softselUseEdgeDistance BooleanClass default: false --
boolean; Use_Edge_Distance
<Poly_Select>.softselEdgeDist Integer default: 1 --
animatable; integer; Edge_Distance
This spinner setting limits the region affected by the number of edges between the
selection and the affected vertices. The affected region is measured in terms of
“edge-distance” space, along the surface, rather than real space.
320 Chapter 1 | What’s New in 3ds max 4 MAXScript

<Poly_Select>.softselAffectBackfacing BooleanClass default: false --

boolean; Affect_Backfacing
When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the
normals of faces to which they’re attached) are facing in the opposite direction to the
average normal of the selected sub-objects, are affected by the soft selection influence.
Turn off Affect Backfacing when you want to pull faces of a thin object, such as a thin box,
but don’t want to affect faces on the other side of the object.
You can also use the keyboard shortcut CTRL+F to toggle Affect Backfacing (while the Plug-
In Keyboard Shortcut Toggle button is turned on).
<Poly_Select>.softselFalloff Float default: 20.0 --
animatable; world units; Falloff
Distance in current units from the center to the edge of a sphere defining the affected
region. Use higher falloff settings to achieve more gradual slopes, depending on the scale
of your geometry. Default=20.
Note: At the Vertex sub-object level, the region specified by the Falloff setting is depicted
graphically in the viewports as a vertex-color gradient from the Sub-selection color
(normally red) to the Vertex Ticks color (normally blue). In addition, this gradient is
updated in real time as you change the Falloff setting.
<Poly_Select>.softselPinch Float default: 0.0 --
animatable; float; Pinch
Raises and lowers the top point of the curve along the vertical axis. Sets the relative
“pointedness” of the region. When negative, a crater is produced instead of a point. At a
setting of 0, Pinch produces a smooth transition across this axis. Default=0.
<Poly_Select>.softselBubble Float default: 0.0 --
animatable; float; Bubble
Expands and contracts the curve along the vertical axis. Sets the relative “fullness” of the
region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for
Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble
move the bottom of the curve below the surface, creating a “valley” around the base of the
region. Default=0.

Position_Constraint - superclass: PositionController

Position_Constraint - superclass: PositionController; super-superclass:MAXWrapper - 1:0 - classID:
#(8217, 0)
Constructor:
Position_Constraint ...

Properties:
<Position_Constraint>.relative BooleanClass default: false -- boolean
 PositionList - superclass: PositionController 321

See Also
Position_Constraint interfaces: (p. 488)

PositionList - superclass: PositionController

PositionList - superclass: PositionController; super-superclass:MAXWrapper - 1:1 - classID:
#(1263210498, 0)
Constructor:
PositionList ...

Properties:
<PositionList>.available Point3 default: [0,0,0] -- animatable; point3

See Also
PositionList interfaces: (p. 494)

PositionReactor - superclass: PositionController

PositionReactor - superclass: PositionController; super-superclass:MAXWrapper - 0:0 - classID:
#(2059782884, -1874176333)

See Also
PositionReactor interfaces: (p. 496)

PositionSpring - superclass: PositionController

PositionSpring - superclass: PositionController; super-superclass:MAXWrapper - 8:1 - classID:
#(2036956458, -222780984)
Constructor:
PositionSpring ...

Properties:
<PositionSpring>.effectHow Integer default: 1 -- radio button
number; Abs_Rel
<PositionSpring>.forceNode ArrayParameter default: #() -- node array;
Force_Nodes; SubAnim
<PositionSpring>.steps Integer default: 2 -- integer
<PositionSpring>.x_effect Float default: 100.0 -- animatable;
float
These settings let you control the percentage of the effect on the individual world axes.
Default=100. Range=0 to 200.
322 Chapter 1 | What’s New in 3ds max 4 MAXScript

<PositionSpring>.y_effect Float default: 100.0 -- animatable;

float
These settings let you control the percentage of the effect on the individual world axes.
Default=100. Range=0 to 200.
<PositionSpring>.z_effect Float default: 100.0 -- animatable;
float
These settings let you control the percentage of the effect on the individual world axes.
Default=100. Range=0 to 200.See Also
<PositionSpring>.start Integer default: 0 -- integer; Start_Frame
<PositionSpring>.position Point3 default: [0,0,0] -- animatable;
point3

See Also
PositionSpring interfaces: (p. 497)
Point3Spring interfaces: (p. 482)
SpringPoint3Controller interfaces: (p. 523)
SpringPoint3Controller - superclass: Point3Controller (p. 336)
SpringPositionController interfaces: (p. 526)
SpringPositionController - superclass: PositionController (p. 337)
Flex : Modifier (p. 1128)
Flex interfaces: (p. 438)
flexOps const StructDef (p. 235)

PSpawnflector - superclass: SpacewarpObject

PSpawnflector - superclass: SpacewarpObject; super-superclass:node - 22:0 - classID: #(1318347405,
1313044340)
Constructor:
PSpawnflector ...

Properties:
<PSpawnflector>.‘time on’ Integer default: 0 -- animatable;
integer; Time_On
<PSpawnflector>.‘time off’ Integer default: 16000 --
animatable; integer; Time_Off
<PSpawnflector>.affects Float default: 10000.0 --
animatable; percentage; Reflects; Controller Scaling: (1 : 100.0)
<PSpawnflector>.bounce Float default: 1.0 -- animatable;
float
<PSpawnflector>.bouncevar Float default: 0.0 -- animatable;
percentage; Bounce_Variation; Controller Scaling: (1 : 100.0)
<PSpawnflector>.chaos Float default: 0.0 -- animatable;
percentage; Controller Scaling: (1 : 100.0)
 Reflection - superclass: MAXObject 323

<PSpawnflector>.inheritVelocity Float default: 1.0 -- animatable;

float; Velocity_Inheritance
<PSpawnflector>.refracts Float default: 100.0 --
animatable; percentage; Controller Scaling: (1 : 100.0)
<PSpawnflector>.deceleration Float default: 1.0 -- animatable;
float
<PSpawnflector>.‘decel var’ Float default: 0.0 -- animatable;
percentage; Deceleration_Variation; Controller Scaling: (1 : 100.0)
<PSpawnflector>.refraction Float default: 50.0 --
animatable; percentage; Distortion; Controller Scaling: (1 : 100.0)
<PSpawnflector>.‘refraction var’ Float default: 0.0 -- animatable;
percentage; Distortion_Variation; Controller Scaling: (1 : 100.0)
<PSpawnflector>.diffusion Float default: 0.0 -- animatable;
percentage; Controller Scaling: (1 : 100.0)
<PSpawnflector>.‘diffusion var’ Float default: 0.0 -- animatable;
percentage; Diffusion_Variation; Controller Scaling: (1 : 100.0)
<PSpawnflector>.width Float default: 0.0 -- animatable;
float
<PSpawnflector>.height Float default: 0.0 -- animatable;
float
<PSpawnflector>.spawn Float default: 100.0 --
animatable; percentage; Spawn_Percentage; Controller Scaling: (1 : 100.0)
<PSpawnflector>.‘pass velocity’ Float default: 1.0 -- animatable;
float; Pass_Velocity
<PSpawnflector>.‘passvel var’ Float default: 0.0 -- animatable;
percentage; Pass_Velocity_Variation; Controller Scaling: (1 : 100.0)
<PSpawnflector>.friction Float default: 0.0 -- animatable;
percentage; Controller Scaling: (1 : 100.0)
<PSpawnflector>.quality Integer default: 20 -- animatable;
integer; Collision_Quality
<PSpawnflector>.collider UndefinedClass default: undefined -- max
object; Collision_Quality

Reflection - superclass: MAXObject

Reflection - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(6, 0)
Constructor:
Reflection ...

Properties:
<Reflection>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<Reflection>.filterOn BooleanClass default: true -- boolean;
FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
324 Chapter 1 | What’s New in 3ds max 4 MAXScript

<Reflection>.elementName String default: “Reflection” -- string

Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<Reflection>.bitmap UndefinedClass default: undefined -- bitmap

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored_Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self_Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)

reflectionRenderElement - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(6, 0)
Constructor:
reflectionRenderElement ...

Properties:
<reflectionRenderElement>.enabled BooleanClass default: true --
boolean
Shows whether the element is enabled.
 reflectionRenderElement - superclass: MAXObject 325

<reflectionRenderElement>.filterOn BooleanClass default: true --

boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<reflectionRenderElement>.elementName String default:
“Reflection” -- string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<reflectionRenderElement>.bitmap UndefinedClass default: undefined -
- bitmap

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored_Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self_Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)
326 Chapter 1 | What’s New in 3ds max 4 MAXScript

Refraction - superclass: MAXObject

Refraction - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(7, 0)
Constructor:
Refraction ...

Properties:
<Refraction>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<Refraction>.filterOn BooleanClass default: true -- boolean;
FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<Refraction>.elementName String default: “Refraction” -- string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<Refraction>.bitmap UndefinedClass default: undefined -- bitmap

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored_Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
refractionRenderElement - superclass: MAXObject (p. 327)
Self_Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)
 refractionRenderElement - superclass: MAXObject 327

refractionRenderElement - superclass: MAXObject

refractionRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(7, 0)
Constructor:
refractionRenderElement ...

Properties:
<refractionRenderElement>.enabled BooleanClass default: true --
boolean
Shows whether the element is enabled.
<refractionRenderElement>.filterOn BooleanClass default: true --
boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<refractionRenderElement>.elementName String default:
“Refraction” -- string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<refractionRenderElement>.bitmap UndefinedClass default: undefined -
- bitmap

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored_Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
Self_Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
328 Chapter 1 | What’s New in 3ds max 4 MAXScript

Specular - superclass: MAXObject (p. 334)

specularRenderElement - superclass: MAXObject (p. 335)

RingWave - superclass: GeometryClass

RingWave - superclass: GeometryClass; super-superclass:node - 26:0 - classID: #(686038884,
306926354)

RotationList - superclass: RotationController

RotationList - superclass: RotationController; super-superclass:MAXWrapper - 1:1 - classID:
#(1263210499, 0)
Constructor:
RotationList ...

Properties:
<RotationList>.available Quat default: (quat 0 0 0 1) -- animatable; quat

See Also
RotationList interfaces: (p. 510)

RotationReactor - superclass: RotationController

RotationReactor - superclass: RotationController; super-superclass:MAXWrapper - 0:0 - classID:
#(713503979, 1475640742)

See Also
RotationReactor interfaces: (p. 512)

ScaleList - superclass: ScaleController

ScaleList - superclass: ScaleController; super-superclass:MAXWrapper - 1:1 - classID:
#(1263210500, 0)
Constructor:
ScaleList ...

Properties:
<ScaleList>.available Point3 default: [0,0,0] -- animatable; point3

See Also
ScaleList interfaces: (p. 517)
 ScaleReactor - superclass: ScaleController 329

ScaleReactor - superclass: ScaleController

ScaleReactor - superclass: ScaleController; super-superclass:MAXWrapper - 0:0 - classID:
#(331629852, 751514504)

See Also
ScaleReactor interfaces: (p. 519)

SDynaflector - superclass: SpacewarpObject

SDynaflector - superclass: SpacewarpObject; super-superclass:node - 19:0 - classID: #(1147744028,
332006682)
Constructor:
...

Properties:
<SDynaflector>.‘time on’ Integer default: 0 -- animatable; integer;
Time_On

<SDynaflector>.‘time off’ Integer default: 16000 -- animatable; integer;

Time_Off

<SDynaflector>.affects Float default: 10000.0 -- animatable; percentage;

Reflects; Controller Scaling: (1 : 100.0)

<SDynaflector>.bounce Float default: 1.0 -- animatable; float

<SDynaflector>.bouncevar Float default: 0.0 -- animatable; percentage;

Bounce_Variation; Controller Scaling: (1 : 100.0)

<SDynaflector>.chaos Float default: 0.0 -- animatable; percentage;

Controller Scaling: (1 : 100.0)

<SDynaflector>.inheritVelocity Float default: 1.0 -- animatable; float;

Velocity_Inheritance

<SDynaflector>.radius Float default: 0.0 -- animatable; float

<SDynaflector>.mass Float default: 1.0 -- animatable; float;

Particle_Mass

<SDynaflector>.‘mass units’ Integer default: 0 -- radio button number;

Particle_Mass_Units

<SDynaflector>.‘force in x’ Float default: 0.0 -- animatable; float;

Force_in_X_Direction
330 Chapter 1 | What’s New in 3ds max 4 MAXScript

<SDynaflector>.‘force in y’ Float default: 0.0 -- animatable; float;

Force_in_Y_Direction

<SDynaflector>.‘force in z’ Float default: 0.0 -- animatable; float;

Force_in_Z_Direction

<SDynaflector>.‘apply at x’ Float default: 0.0 -- animatable; float;

Apply_at_X_location

<SDynaflector>.‘apply at y’ Float default: 0.0 -- animatable; float;

Apply_at_Y_location

<SDynaflector>.‘apply at z’ Float default: 0.0 -- animatable; float;

Apply_at_Z_location

<SDynaflector>.number Integer default: 0 -- animatable; integer;

Number_of_Particles

<SDynaflector>.friction Float default: 0.0 -- animatable; percentage;

Controller Scaling: (1 : 100.0)

<SDynaflector>.collider UndefinedClass default: undefined -- max object;

Friction

section - superclass: shape

section - superclass: shape; super-superclass:node - 13:0 - classID: #(549004141, 1725569194)
Constructor:
section ...

Properties:
<section>.angle Float default: 0.0 -- float
<section>.renderable BooleanClass default: false -- boolean
<section>.mapCoords BooleanClass default: false -- boolean
<section>.thickness Float default: 1.0 -- float
<section>.sides Float default: 12.0 -- integer
<section>.viewport_thickness Float default: 1.0 -- float
<section>.viewport_sides Integer default: 12 -- integer
<section>.viewport_angle Float default: 0.0 -- float
<section>.DisplayRenderMesh BooleanClass default: false -- boolean
<section>.UseViewportSettings BooleanClass default: false -- boolean
<section>.DisplayRenderSettings BooleanClass default: true -- boolean
Notes:
Setting to false won’t “take” if <shape>.useViewportSettings or <shape>.displayRenderMesh is
false. This matches the behavior in the UI where the “Viewport” option is disabled in this case.
 Self_Illumination - superclass: MAXObject 331

Self_Illumination - superclass: MAXObject

Self_Illumination - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(5, 0)
Constructor:
Self_Illumination ...

Properties:
<Self_Illumination>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<Self_Illumination>.filterOn BooleanClass default: true -- boolean;
FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<Self_Illumination>.elementName String default: “Self-
Illumination” -- string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<Self_Illumination>.bitmap UndefinedClass default: undefined --
bitmap

See Also
LOOKS THE SAME AS emissionRenderElement - superclass: MAXObject (p. 285)
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored_Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
ShadowRenderElement - superclass: MAXObject (p. 332)
332 Chapter 1 | What’s New in 3ds max 4 MAXScript

Specular - superclass: MAXObject (p. 334)

specularRenderElement - superclass: MAXObject (p. 335)

ShadowRenderElement - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(8, 0)
Constructor:
ShadowRenderElement ...

Properties:
<ShadowRenderElement>.enabled BooleanClass default: true --
boolean
Shows whether the element is enabled.
<ShadowRenderElement>.filterOn BooleanClass default: true --
boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<ShadowRenderElement>.elementName String default: “Shadow” --
string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<ShadowRenderElement>.bitmap UndefinedClass default: undefined --
bitmap

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored_Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
 sliderManipulator - superclass: helper 333

refractionRenderElement - superclass: MAXObject (p. 327)

Self_Illumination - superclass: MAXObject (p. 331)
Specular - superclass: MAXObject (p. 334)
specularRenderElement - superclass: MAXObject (p. 335)

sliderManipulator - superclass: helper

sliderManipulator - superclass: helper; super-superclass:node - 10:0 - classID: #(1205540079,
1318803856)
Constructor:
sliderManipulator ...

Properties:
<sliderManipulator>.value Float default: 0.0 -- animatable; float
The value of the slider, based on the position of the slidable triangle. Default=0.0.
<sliderManipulator>.minVal Float default: 0.0 -- animatable; float
The minimum possible value of the slider. Default=0.0.
<sliderManipulator>.maxVal Float default: 100.0 -- animatable; float
The maximum possible value of the slider. Default=100.0.
When the minimum is 0.0 and the maximum is 100.0, the slider Value can represent a
percentage.
<sliderManipulator>.xPos Float default: 0.0 -- float
The slider’s X location in the active viewport. Default=Viewport X location you clicked
when you created the slider.
<sliderManipulator>.yPos Float default: 0.0 -- float
The slider’s Y location in the active viewport. Default=Viewport Y location you clicked
when you created the slider.
<sliderManipulator>.width Float default: 100.0 -- float
The slider’s width, in 3ds max units. Default=100.0.
<sliderManipulator>.hide BooleanClass default: false -- boolean
When on, hides all of the slider except for the label and the move and show/hide
components. Default=off.
<sliderManipulator>.sldName String default: ““ -- string
The slider label that appears in viewports. Default=none.
<sliderManipulator>.snapToggle BooleanClass default: true -- boolean
When on, the slider “snaps” to incremental values. When off, Default=on.
<sliderManipulator>.snapVal Float default: 0.01 -- float
The increment used by the slider when Snap is on. Default=0.01.
334 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
Scripted Manipulators (p. 97)
Interface: manip (p. 366)
radiusManip interfaces: (p. 500)
ConeAngleManip - superclass: helper (p. 277)
PlaneAngleManip - superclass: helper (p. 311)
Scripted Plug-ins (p. 1538)
sliderManipulator - superclass: helper (p. 333)
sliderManipulator interfaces: (p. 520)
uvwMappingHeightManip interfaces: (p. 551)
uvwMappingLengthManip interfaces: (p. 555)
uvwMappingUTileManip interfaces: (p. 558)
uvwMappingVTileManip interfaces: (p. 562)
uvwMappingWidthManip interfaces: (p. 565)

Specular - superclass: MAXObject

Specular - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(2, 0)
Constructor:
Specular ...

Properties:
<Specular>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<Specular>.filterOn BooleanClass default: true -- boolean;
FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<Specular>.elementName String default: “Specular” -- string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<Specular>.bitmap UndefinedClass default: undefined -- bitmap

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
 specularRenderElement - superclass: MAXObject 335

BackgroundRenderElement - superclass: MAXObject (p. 269)

bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored_Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self_Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
specularRenderElement - superclass: MAXObject (p. 335)

specularRenderElement - superclass: MAXObject

specularRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(2, 0)
Constructor:
specularRenderElement ...

Properties:
<specularRenderElement>.enabled BooleanClass default: true --
boolean
Shows whether the element is enabled.
<specularRenderElement>.filterOn BooleanClass default: true --
boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
<specularRenderElement>.elementName String default: “Specular” --
string
Shows the name of the currently selected element. You can type in a custom name for the
element.
This control is unavailable when multiple elements are selected.
<specularRenderElement>.bitmap UndefinedClass default: undefined --
bitmap
336 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
Alpha - superclass: MAXObject (p. 262)
alphaRenderElement - superclass: MAXObject (p. 263)
Atmosphere - superclass: MAXObject (p. 264)
atmosphereRenderElement - superclass: MAXObject (p. 265)
BackgroundRenderElement - superclass: MAXObject (p. 269)
bgndRenderElement - superclass: MAXObject (p. 270)
clrShadowRenderElement - superclass: MAXObject (p. 272)
Colored_Shadow - superclass: MAXObject (p. 273)
Diffuse - superclass: MAXObject (p. 279)
diffuseRenderElement - superclass: MAXObject (p. 280)
emissionRenderElement - superclass: MAXObject (p. 285)
Reflection - superclass: MAXObject (p. 323)
reflectionRenderElement - superclass: MAXObject (p. 324)
Refraction - superclass: MAXObject (p. 326)
refractionRenderElement - superclass: MAXObject (p. 327)
Self_Illumination - superclass: MAXObject (p. 331)
ShadowRenderElement - superclass: MAXObject (p. 332)
Specular - superclass: MAXObject (p. 334) specularRenderElement_superclass_MAXObject

SpringPoint3Controller - superclass: Point3Controller

SpringPoint3Controller - superclass: Point3Controller; super-superclass:MAXWrapper - 4:4 - classID:
#(327754098, 1754751609)
Constructor:
SpringPoint3Controller ...

Properties:
<SpringPoint3Controller>.position Point3 default: [0,0,0] -- animatable;
point3
<SpringPoint3Controller>.x_effect Float default: 100.0
These settings let you control the percentage of the effect on the individual world axes.
Default=100. Range=0 to 200.
<SpringPoint3Controller>.y_effect Float default: 100.0
These settings let you control the percentage of the effect on the individual world axes.
Default=100. Range=0 to 200.
 SpringPositionController - superclass: PositionController 337

<SpringPoint3Controller>.z_effect Float default: 100.0

These settings let you control the percentage of the effect on the individual world axes.
Default=100. Range=0 to 200.See Also

See Also
PositionSpring interfaces: (p. 497)
Point3Spring interfaces: (p. 482)
SpringPoint3Controller interfaces: (p. 523)
SpringPoint3Controller - superclass: Point3Controller (p. 336)
SpringPositionController interfaces: (p. 526)
SpringPositionController - superclass: PositionController (p. 337)
Flex : Modifier (p. 1128)
Flex interfaces: (p. 438)
flexOps const StructDef (p. 235)

SpringPositionController - superclass: PositionController

SpringPositionController - superclass: PositionController; super-superclass:MAXWrapper - 8:1 -
classID: #(2036956458, -222780984)
Constructor:
SpringPositionController ...

Properties:
<SpringPositionController>.effectHow Integer default: 1 -- radio
button number; Abs_Rel
<SpringPositionController>.forceNode ArrayParameter default: #() -- node
array; Force_Nodes; SubAnim
<SpringPositionController>.steps Integer default: 2 -- integer
<SpringPositionController>.x_effect Float default: 100.0 --
animatable; float
These settings let you control the percentage of the effect on the individual world axes.
Default=100. Range=0 to 200.
<SpringPositionController>.y_effect Float default: 100.0 --
animatable; float
These settings let you control the percentage of the effect on the individual world axes.
Default=100. Range=0 to 200.
<SpringPositionController>.z_effect Float default: 100.0 --
animatable; float
These settings let you control the percentage of the effect on the individual world axes.
Default=100. Range=0 to 200.See Also
338 Chapter 1 | What’s New in 3ds max 4 MAXScript

<SpringPositionController>.start Integer default: 0 -- integer;

Start_Frame
<SpringPositionController>.position Point3 default: [0,0,0] --
animatable; point3

See Also
PositionSpring interfaces: (p. 497)
Point3Spring interfaces: (p. 482)
SpringPoint3Controller interfaces: (p. 523)
SpringPoint3Controller - superclass: Point3Controller (p. 336)
SpringPositionController interfaces: (p. 526)
SpringPositionController - superclass: PositionController (p. 337)
Flex : Modifier (p. 1128)
Flex interfaces: (p. 438)
flexOps const StructDef (p. 235)

SSpawnflector - superclass: SpacewarpObject

SSpawnflector - superclass: SpacewarpObject; super-superclass:node - 20:0 - classID: #(1700857802,
522734191)
Constructor:
SSpawnflector ...

Properties:
<SSpawnflector>.’time on’ Integer default: 0 -- animatable; integer;
Time_On

<SSpawnflector>.‘time off’ Integer default: 16000 -- animatable;

integer; Time_Off

<SSpawnflector>.affects Float default: 10000.0 -- animatable; percentage;

Reflects; Controller Scaling: (1 : 100.0)

<SSpawnflector>.bounce Float default: 1.0 -- animatable; float

<SSpawnflector>.bouncevar Float default: 0.0 -- animatable; percentage;

Bounce_Variation; Controller Scaling: (1 : 100.0)

<SSpawnflector>.chaos Float default: 0.0 -- animatable; percentage;

Controller Scaling: (1 : 100.0)

<SSpawnflector>.inheritVelocity Float default: 1.0 -- animatable; float;

Velocity_Inheritance
 transform_script - superclass: Matrix3Controller 339

<SSpawnflector>.refracts Float default: 100.0 -- animatable; percentage;

Controller Scaling: (1 : 100.0)

<SSpawnflector>.deceleration Float default: 1.0 -- animatable; float

<SSpawnflector>.‘decel var’ Float default: 0.0 -- animatable;

percentage; Deceleration_Variation; Controller Scaling: (1 : 100.0)

<SSpawnflector>.refSraction Float default: 50.0 -- animatable;

percentage; Distortion; Controller Scaling: (1 : 100.0)

<SSpawnflector>.‘refraction var’ Float default: 0.0 -- animatable;

percentage; Distortion_Variation; Controller Scaling: (1 : 100.0)

<SSpawnflector>.diffusion Float default: 0.0 -- animatable; percentage;

Controller Scaling: (1 : 100.0)

<SSpawnflector>.‘diffusion var’ Float default: 0.0 -- animatable;

percentage; Diffusion_Variation; Controller Scaling: (1 : 100.0)

<SSpawnflector>.radius Float default: 0.0 -- animatable; float

<SSpawnflector>.spawn Float default: 100.0 -- animatable; percentage;

Spawn_Percentage; Controller Scaling: (1 : 100.0)

<SSpawnflector>.‘pass velocity’ Float default: 1.0 -- animatable; float;

Pass_Velocity

<SSpawnflector>.‘passvel var’ Float default: 0.0 -- animatable;

percentage; Pass_Velocity_Variation; Controller Scaling: (1 : 100.0)

<SSpawnflector>.friction Float default: 0.0 -- animatable; percentage;

Controller Scaling: (1 : 100.0)

<SSpawnflector>.collider UndefinedClass default: undefined -- max

object; Friction

transform_script - superclass: Matrix3Controller

transform_script - superclass: Matrix3Controller; super-superclass:MAXWrapper - 1:0 - classID:
#(2136360284, 468085864)
The Transform Script controller contains all of the information contained in a Position/Rotation/
Scale (PRS) controller in one scripted matrix value. Instead of having three separate tracks for
position, rotation, and scale, all three values can be simultaneously accessed from one script
controller dialog. Because the transform values are defined by a script, they are easier to animate.
The value of the controller script must be a matrix3 value. A matrix3 value is a 4x3 3D
transformation matrix. For more information, see the Matrix3 Values topic in the MAXScript
reference.
340 Chapter 1 | What’s New in 3ds max 4 MAXScript

The software interprets the text you type into the Script text box as the body of a MAXScript block
expression. You can type as many expressions as you want on as many lines as you want, and they
are evaluated in turn. The value of the last expression is taken as the controller value. This must yield
a matrix3 value for Transform Script controllers.
Since the text is inside a block expression, you can declare local variables which are visible only
within the script and are temporary for one evaluation. You can also declare or access global
variables that are shared with all other scripts in MAXScript and hold their values from one
evaluation to the next.
A controller is always evaluated by the software with respect to a specific animation time. This might
be the current time slider or incrementing frame time if an animation is playing, or a rendering is
under way. In the case of Script controllers, the time being evaluated is used to establish an
automatic “at time” context around the controller script, so any properties you access (outside of
other explicit “at time” expressions) yield the correct values for the current controller evaluation
time. This means you don’t have to do anything special in your scripts to work at the correct time.
You can access the evaluation time, with the standard MAXScript variable, current Time. You can
also reference scene property values at other times by using “at time” expressions in your scripts, as
in regular MAXScript programming.
Constructor:
transform_script ...

Properties:
<transform_script>.script String default: “(matrix3 1)”

See Also
Script Controllers (p. 1329)

Turn_to_Mesh - superclass: modifier

Turn_to_Mesh - superclass: modifier; super-superclass:MAXWrapper - 4:0 - classID: #(1549488375,
1614380193)
Constructor:
Turn_to_Mesh ...

Properties:
<Turn_to_Mesh>.useInvisibleEdges BooleanClass default: true --
animatable; boolean; Use_Invisible_Edges
When on, uses invisible edges to represent polygons. When off, produces a completely
triangulated mesh with all visible edges. Default=on.
 Turn_to_Mesh - superclass: modifier 341

<Turn_to_Mesh>.selectionConversion Integer default: 0 -- integer;

Selection_Conversion
<Turn_to_Mesh>.useSoftSelection BooleanClass default: true -- boolean;
Use_Soft_Selection
Affects the action of sub-object Move, Rotate, and Scale functions. When these are on,
3D Studio MAX applies a spline curve deformation to unselected vertices surrounding the
transformed selected sub-object. This provides a magnet-like effect, with a sphere of
influence around the transformation. Use this when you want to preserve the soft
selection from beneath. For example, if Use Soft Selection is on when you select vertices on
an editable poly, and you apply Turn To Mesh with Include Soft Selection on, then the
same soft selection will apply to the mesh vertices. Default=on.
For more information, see Soft Selection Rollout.
Important: Be aware that when Include Soft Selection is on, bound vertices can turn
to meshes.
<Turn_to_Mesh>.selectionLevel Integer default: 0 -- integer;
Selection_Level
From Pipeline: Uses the equivalent of whatever the input object uses. (Patch level becomes
face level, and so on.). For example, if you create a box, convert it to an editable patch in
patch mode and apply a Turn To Mesh modifier to it, 3ds max passes a sub-object selection
in patch mode up the stack. The Turn To Mesh modifier takes the sub-object patch
selection into account and selects the mesh faces that derive from the patch selection.
Object: Uses object as the selection level for passing up the rest of the stack.
Edge: Uses edge as the sub-object selection level for passing up the rest of the stack.
Vertex: Uses vertex as the sub-object selection level for passing up the rest of the stack.
Face: Uses face as the sub-object selection level for passing up the rest of the stack.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
342 Chapter 1 | What’s New in 3ds max 4 MAXScript

Turn_to_Patch - superclass: modifier

Turn_to_Patch - superclass: modifier; super-superclass:MAXWrapper - 4:0 - classID: #(1011577041,
590161861)
Constructor:
Turn_to_Patch ...

Properties:
<Turn_to_Patch>.quadsToQuads BooleanClass default: true --
animatable; boolean; Quads_to_Quad_Patches
Turns quad faces in meshes or polymeshes into quad patches.
Note: When you turn this option off, 3ds max triangulates quads when the Turn To Patch
modifier is applied to a patch object.
<Turn_to_Patch>.selectionConversion Integer default: 0 -- integer;
Selection_Conversion
<Turn_to_Patch>.useSoftSelection Integer default: 1 -- integer;
Use_Soft_Selection
Affects the action of sub-object Move, Rotate, and Scale functions. When these are on,
3D Studio MAX applies a spline curve deformation to unselected vertices surrounding the
transformed selected sub-object. This provides a magnet-like effect, with a sphere of
influence around the transformation. Use this when you want to preserve the soft
selection from beneath. For example, if Use Soft Selection is on when you select vertices on
an editable poly, and you apply Turn To Mesh with Include Soft Selection on, then the
same soft selection will apply to the mesh vertices. Default=on.
For more information, see Soft Selection Rollout.
Important: Be aware that when Include Soft Selection is on, bound vertices can turn to
meshes.
<Turn_to_Patch>.selectionLevel Integer default: 0 -- integer;
Selection_Level
From Pipeline: Uses the equivalent of whatever the input object uses. (Patch level becomes
face level, and so on.). For example, if you create a box, convert it to an editable mesh in
face mode and apply a Turn To Patch modifier to it, 3ds max passes a sub-object selection
in face mode up the stack. The Turn To Patch modifier takes the sub-object face selection
into account and selects the patches that derive from the face selection.
Object: Uses object as the selection level for passing up the rest of the stack.
Edge: Uses edge as the sub-object selection level for passing up the rest of the stack.
Vertex: Uses vertex as the sub-object selection level for passing up the rest of the stack.
Face: Uses face as the sub-object selection level for passing up the rest of the stack.
 Turn_to_Poly - superclass: modifier 343

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Turn_to_Poly - superclass: modifier

Turn_to_Poly - superclass: modifier; super-superclass:MAXWrapper - 9:0 - classID: #(793333328,
1547135298)
Constructor:
Turn_to_Poly ...

Properties:
<Turn_to_Poly>.keepConvex BooleanClass default: false --
animatable; boolean; Keep_Convex
Does not join across edges if the resulting polygon would not be convex. “Convex” means
that you can connect any two points in the polygon with a line that doesn’t go outside the
polygon. A polygon is not convex if you can draw a line between vertices and that line lays
outside of the polygon.
Problems that can occur with non-convex polygons include the fact that changes in the
geometry of the input object can result in a different topology for the Turn To Poly result.
For instance, in a box, if you drag one of the top corners across the middle of the top face,
the box becomes non-convex. Turn To Poly would then see this as two triangles instead of
one quad, and the number of points in the result would change.
<Turn_to_Poly>.limitPolySize BooleanClass default: false --
animatable; boolean; Limit_Polygon_Size
Limits the number of sides to a polygon so that the surface is better defined. For example,
you might want to produce a polymesh of triangles and quads, or one composed of all
triangles, rather than joining together more than two triangles into pentagons, hexagons,
and so on.
<Turn_to_Poly>.maxPolySize Integer default: 4 -- animatable;
integer; Max_Polygon_Size
The maximum number of sides to a polygon.
<Turn_to_Poly>.requirePlanar BooleanClass default: false --
animatable; boolean; Require_Planar_Polygons
Creates polygons composed of flat planes. Does not join faces together across an edge if
the edge has a sharper angle than the threshold listed.
<Turn_to_Poly>.planarThresh Float default: 15.0 --
animatable; angle; Planar_Threshold; Controller Scaling: (1 : 57.2958)
Controls the threshold of the angle between polygonal planes.
<Turn_to_Poly>.removeMidEdgeVertices BooleanClass default: true -- boolean;
Remove_Mid_Edge_Vertices
344 Chapter 1 | What’s New in 3ds max 4 MAXScript

<Turn_to_Poly>.selectionConversion Integer default: 0 -- integer;

Selection_Conversion
<Turn_to_Poly>.useSoftSelection BooleanClass default: true -- boolean;
Use_Soft_Selection
Affects the action of sub-object Move, Rotate, and Scale functions. When these are on,
3ds max applies a spline curve deformation to unselected vertices surrounding the
transformed selected sub-object. This provides a magnet-like effect, with a sphere of
influence around the transformation. Use this when you want to preserve the soft
selection from beneath. For example, if Use Soft Selection is on when you select vertices on
an editable mesh, and you apply Turn To Poly with Include Soft Selection on, then the
same soft selection will apply to the polymesh vertices. Default=on.
Important: Be aware that when Include Soft Selection is on, bound vertices can turn to
meshes.
For more information, see Soft Selection Rollout
<Turn_to_Poly>.selectionLevel Integer default: 0 -- integer;
Selection_Level
These options set the sub-object selection level for passing up the rest of the stack.
From Pipeline: Uses the equivalent of whatever the input object uses. (Patch level becomes
face level, and so on.). For example, if you create a box, convert it to an editable mesh in
face mode and apply a Turn To Poly modifier to it, 3ds max passes a sub-object selection in
face mode up the stack. The Turn To Poly modifier takes the sub-object face selection into
account and selects the polygons that derive from the face selection.
Object: Uses object as the selection level for passing up the rest of the stack.
Edge: Uses edge as the sub-object selection level for passing up the rest of the stack.
Vertex: Uses vertex as the sub-object selection level for passing up the rest of the stack.
Face: Uses face as the sub-object selection level for passing up the rest of the stack.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 UDynaDeflector - superclass: SpacewarpObject 345

UDynaDeflector - superclass: SpacewarpObject

UDynaDeflector - superclass: SpacewarpObject; super-superclass:node - 19:0 - classID:
#(1750561194, 1736524989)
Constructor:
...

Properties:
<UDynaDeflector>.’time on’ Integer default: 0 -- animatable; integer;
Time_On

<UDynaDeflector>.’time off’ Integer default: 1600000 -- animatable;

integer; Time_Off

<UDynaDeflector>.affects Float default: 10000.0 -- animatable; percentage;

Reflects; Controller Scaling: (1 : 100.0)

<UDynaDeflector>.bounce Float default: 1.0 -- animatable; float

<UDynaDeflector>.bouncevar Float default: 0.0 -- animatable; percentage;

Bounce_Variation; Controller Scaling: (1 : 100.0)

<UDynaDeflector>.chaos Float default: 0.0 -- animatable; percentage;

Controller Scaling: (1 : 100.0)

<UDynaDeflector>.friction Float default: 0.0 -- animatable; percentage;

Controller Scaling: (1 : 100.0)

<UDynaDeflector>.inheritVelocity Float default: 1.0 -- animatable; float;

Velocity_Inheritance

<UDynaDeflector>.radius Float default: 0.0 -- animatable; float; Icon_Size

<UDynaDeflector>.mass Float default: 1.0 -- animatable; float;

Particle_Mass

<UDynaDeflector>.’mass units’ Integer default: 0 -- radio button number;

Particle_Mass_Units

<UDynaDeflector>.’force in x’ Float default: 0.0 -- animatable; float;

Force_in_X_Direction

<UDynaDeflector>.’force in y’ Float default: 0.0 -- animatable; float;

Force_in_Y_Direction

<UDynaDeflector>.’force in z’ Float default: 0.0 -- animatable; float;

Force_in_Z_Direction
346 Chapter 1 | What’s New in 3ds max 4 MAXScript

<UDynaDeflector>.’apply at x’ Float default: 0.0 -- animatable; float;

Apply_at_X_location

<UDynaDeflector>.’apply at y’ Float default: 0.0 -- animatable; float;

Apply_at_Y_location

<UDynaDeflector>.’apply at z’ Float default: 0.0 -- animatable; float;

Apply_at_Z_location

<UDynaDeflector>.number Integer default: 20 -- animatable; integer;

Number_of_Particles

<UDynaDeflector>.collider UndefinedClass default: undefined -- max object;

Friction

USpawnDeflector - superclass: SpacewarpObject

USpawnDeflector - superclass: SpacewarpObject; super-superclass:node - 20:0 - classID:
#(436029718, 1434415577)
Constructor:
...

Properties:
<USpawnDeflector>.‘time on’ Integer default: 0 -- animatable; integer;
Time_On

<USpawnDeflector>.‘time off’ Integer default: 16000 -- animatable;

integer; Time_Off

<USpawnDeflector>.affects Float default: 10000.0 -- animatable;

percentage; Reflects; Controller Scaling: (1 : 100.0)

<USpawnDeflector>.bounce Float default: 1.0 -- animatable; float

<USpawnDeflector>.bouncevar Float default: 0.0 -- animatable;

percentage; Bounce_Variation; Controller Scaling: (1 : 100.0)

<USpawnDeflector>.chaos Float default: 0.0 -- animatable; percentage;

Controller Scaling: (1 : 100.0)

<USpawnDeflector>.friction Float default: 0.0 -- animatable; percentage;

Controller Scaling: (1 : 100.0)

<USpawnDeflector>.inheritVelocity Float default: 1.0 -- animatable;

float; Velocity_Inheritance

<USpawnDeflector>.refracts Float default: 100.0 -- animatable;

percentage; Controller Scaling: (1 : 100.0)
 UVWUnwrap - superclass: modifier 347

<USpawnDeflector>.deceleration Float default: 1.0 -- animatable; float

<USpawnDeflector>.’decel var’ Float default: 0.0 -- animatable;

percentage; Deceleration_Variation; Controller Scaling: (1 : 100.0)

<USpawnDeflector>.refraction Float default: 50.0 -- animatable;

percentage; Distortion; Controller Scaling: (1 : 100.0)

<USpawnDeflector>.‘refraction var’ Float default: 0.0 -- animatable;

percentage; Distortion_Variation; Controller Scaling: (1 : 100.0)

<USpawnDeflector>.diffusion Float default: 0.0 -- animatable;

percentage; Controller Scaling: (1 : 100.0)

<USpawnDeflector>.‘diffusion var’ Float default: 0.0 -- animatable;

percentage; Diffusion_Variation; Controller Scaling: (1 : 100.0)

<USpawnDeflector>.radius Float default: 0.0 -- animatable; float;

Icon_Size

<USpawnDeflector>.spawn Float default: 100.0 -- animatable; percentage;

Spawn_Percentage; Controller Scaling: (1 : 100.0)

<USpawnDeflector>.‘pass velocity’ Float default: 1.0 -- animatable;

float; Pass_Velocity

<USpawnDeflector>.‘passvel var’ Float default: 0.0 -- animatable;

percentage; Pass_Velocity_Variation; Controller Scaling: (1 : 100.0)

<USpawnDeflector>.collider UndefinedClass default: undefined -- max

object; Friction

UVWUnwrap - superclass: modifier

UVWUnwrap - superclass: modifier; super-superclass:MAXWrapper - 0:0 - classID: #(48180794,
1924812319)
UVWUnwrap interfaces: (p. 568)

Vortex - superclass: SpacewarpObject

Vortex - superclass: SpacewarpObject; super-superclass:node - 19:0 - classID: #(217851359,
1867456353)
The Vortex space warp applies a force to particle systems, spinning them through a whirling vortex,
and then moving them down a long, thin spout or vortex well. Vortex is useful for creating black
holes, whirlpools, tornadoes, and other funnel-type objects.
The space warp settings let you control the vortex shape, the well characteristics, and rate and range
of particle capture. The shape of the vortex is also affected by particle system settings, such as speed.
348 Chapter 1 | What’s New in 3ds max 4 MAXScript

Constructor:
Vortex ...

Properties:
<Vortex>.‘time on’ Integer default: 0 -- integer; Time_On
The frame numbers at which the space warp becomes active and becomes inactive.
<Vortex>.‘time off’ Integer default: 16000 -- animatable;
integer; Time_Off
The frame numbers at which the space warp becomes active and becomes inactive.
<Vortex>.axialstrength Float default: 0.1 -- animatable; float;
Axial_Drop_Strength
Specifies how quickly particles move in the direction of the drop axis.
<Vortex>.axialrange Float default: 100.0 -- animatable;
float; Axial_Range
The distance from the center of the Vortex icon, in system units, at which Axial Damping
has its full effect. Takes effect only when Unlimited Range is turned off.
<Vortex>.axialfalloff Float default: 1000.0 -- animatable;
float; Axial_Falloff
Specifies the distance beyond the Axial Range within which Axial Damping is applied.
Axial Damping is strongest at the Range distance, decreases linearly out to the limit of the
Axial Falloff, and has no effect beyond that. Takes effect only when Unlimited Range is
turned off.
<Vortex>.axialdamping Float default: 5.0 -- animatable;
percentage; Axial_Damping; Controller Scaling: (1 : 100.0)
Controls the degree to which particle motion parallel to the drop axis is restrained per
frame. Default=5.0. Range=0 to 100.
For subtle effects, use values of less than 10%. For more overt effects, try using higher
values that increase to 100% over the course of a few frames.
<Vortex>.rotationstrength Float default: 0.5 -- animatable; float;
Orbital_Speed_Strength
Specifies how quickly the particles rotate.
<Vortex>.rotationrange Float default: 100.0 -- animatable;
float; Orbital_Range
The distance from the center of the Vortex icon, in system units, at which Orbital
Damping has its full effect. Takes effect only when Unlimited Range is turned off.
<Vortex>.rotationfalloff Float default: 1000.0 -- animatable;
float; Orbital_Falloff
Specifies the distance beyond the Orbital Range within which Orbital Damping is applied.
Orbital Damping is strongest at the Range distance, decreases linearly out to the limit of
the Orbital Falloff, and has no effect beyond that. Takes effect only when Unlimited Range
is turned off.
 Vortex - superclass: SpacewarpObject 349

<Vortex>.rotationdamping Float default: 5.0 -- animatable;

percentage; Orbital_Damping; Controller Scaling: (1 : 100.0)
Controls the degree to which orbital particle motion is restrained per frame. Smaller values
produce a wide spiral, while larger values produce a thin spiral. Default=5.0. Range=0
to 100.
<Vortex>.radialstrength Float default: 0.5 -- animatable; float;
Radial_Pull_Strength
Specifies the distance from the drop axis at which the particles rotate.
<Vortex>.radialrange Float default: 100.0 -- animatable;
float; Radial_Range
The distance from the center of the Vortex icon, in system units, at which Radial Damping
has its full effect. Takes effect only when Unlimited Range is turned off.
<Vortex>.radialfalloff Float default: 1000.0 -- animatable;
float; Radial_Falloff
Specifies the distance beyond the Radial Range within which Radial Damping is applied.
Radial Damping is strongest at the Range distance, decreases linearly out to the limit of the
Radial Falloff, and has no effect beyond that. Takes effect only when Unlimited Range is
turned off.
<Vortex>.radialdamping Float default: 5.0 -- animatable;
percentage; Radial_Damping; Controller Scaling: (1 : 100.0)
Controls the degree to which Radial Pull is restrained per frame. Default=5.0. Range=0 to
100.
<Vortex>.taperstrength Float default: 100.0 -- animatable;
float; Taper_Length
Controls the shape of the vortex. Low values create a vortex with a wide, flared mouth,
while high values create a vortex with nearly vertical sides. Default=100. Range=1.0 to 4.0.
<Vortex>.tapershape Float default: 1.0 -- animatable; float;
Taper_Curve
Controls the length of the vortex, as well as its shape. Lower settings give you a “tighter”
vortex, while higher settings give you a “looser” vortex. Default=100.
<Vortex>.direction Integer default: 0 -- radio button number
Determines whether particles rotate clockwise or counterclockwise.
<Vortex>.rangeless BooleanClass default: true -- boolean;
Unlimited_Range
When on, Vortex exerts full damping strength over an unlimited range. When off, the
Range and Falloff settings take effect.
<Vortex>.iconsize Float default: 10.0 -- float; Icon_Size
Specifies the size of the icon.
Example:
Vortex ‘time on’:0 ‘time off’:16000 axialstrength:0.1 axialrange:100
axialfalloff:1000 axialdamping:5 rotationstrength:0.5 rotationrange:100
rotationfalloff:1000 rotationdamping:5 radialstrength:0.5 radialrange:100
radialfalloff:1000 radialdamping:5 taperstrength:100 tapershape:1 direction:0
rangeless:on pos:[32.5437,-58.2321,0] isSelected:on iconSize:25.8103
350 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Z_Depth - superclass: MAXObject

Z_Depth - superclass: MAXObject; super-superclass:Value - 6:0 - classID: #(12, 0)
Constructor:
Z_Depth ...

Properties:
<Z_Depth>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<Z_Depth>.filterOn BooleanClass default: true -- boolean; FilteringOn
When on, applies the active antialiasing filter to the rendered element. When off, the
rendered element does not use the antialiasing filter. Default=on.
The Filter Enabled column of the elements list shows whether or not the filter is enabled
for an element.
You choose the antialiasing filter in the Anti-Aliasing group of the MAX Default Scanline
A-Buffer rollout.
Disabling antialiasing can improve rendering time, although the rendered element that
results might appear jagged.
<Z_Depth>.elementName String default: “Z Depth” -- string
Shows the name of the element. You can change the default name of elements, in the
Selected Element Parameters group.
To select an element, click its name in the list. Use CTRL+click to select additional
elements, or SHIFT+click to select a contiguous group of additional elements.
<Z_Depth>.bitmap UndefinedClass default: undefined -- bitmap
<Z_Depth>.zMin Float default: 100.0 -- float; Z_Min
The minimum distance to include in the Z-depth rendering. This is a value in 3ds max
units. Default=0.0 (cannot be less than zero).
<Z_Depth>.zMax Float default: 300.0 -- float; Z_Max
The maximum distance to include in the Z-depth rendering. This is a value in 3ds max
units. Default=100.0.
 ZRenderElement - superclass: MAXObject 351

ZRenderElement - superclass: MAXObject

ZRenderElement - superclass: MAXObject; super-superclass:Value - 6:0 - classID: #(12, 0)
Constructor:
ZRenderElement ...

Properties:
<ZRenderElement>.enabled BooleanClass default: true -- boolean
Shows whether the element is enabled.
<ZRenderElement>.filterOn BooleanClass default: true -- boolean;
FilteringOn
When on, applies the active antialiasing filter to the rendered element. When off, the
rendered element does not use the antialiasing filter. Default=on.
The Filter Enabled column of the elements list shows whether or not the filter is enabled
for an element.
You choose the antialiasing filter in the Anti-Aliasing group of the MAX Default Scanline
A-Buffer rollout.
Disabling antialiasing can improve rendering time, although the rendered element that
results might appear jagged.
<ZRenderElement>.elementName String default: “Z Depth” -- string
Shows the name of the element. You can change the default name of elements, in the
Selected Element Parameters group.
To select an element, click its name in the list. Use CTRL+click to select additional
elements, or SHIFT+click to select a contiguous group of additional elements.
<ZRenderElement>.bitmap UndefinedClass default: undefined -- bitmap
<ZRenderElement>.zMin Float default: 100.0 -- float; Z_Min
The minimum distance to include in the Z-depth rendering. This is a value in 3ds max
units. Default=0.0 (cannot be less than zero).
<ZRenderElement>.zMax Float default: 300.0 -- float; Z_Max
The maximum distance to include in the Z-depth rendering. This is a value in 3ds max
units. Default=100.0.
352 Chapter 1 | What’s New in 3ds max 4 MAXScript

version 4 MAXScript Interfaces

Core Interfaces
Topic: version 4 MAXScript New Features/Interfaces
Interfaces (p. 67)
actionMan (p. 353)
BoneSys (p. 354)
browserMgr (p. 355)
cmdPanel (p. 356)
colorMan (p. 356)
dragAndDrop (p. 362)
HDIKSys (p. 365)
IKSys (p. 365)
manip (p. 366)
maxOps (p. 368)
medit (p. 371)
menuMan (p. 372)
msZip (p. 378)
netrender (p. 379)
NullInterface (p. 409)
objXRefs (p. 409)
paramWire (p. 410)
pluginManager (p. 414)
quadMenuSettings (p. 414)
rollup (p. 427)
SceneExposureControl (p. 427)
SceneRadiosity (p. 428)
timeSlider (p. 428)
trackviews (p. 429)

See Also
Other Interfaces (p. 71)
Class and Object Inspector Functions (p. 799)
Class and Object Inspector Functions Enhanced (p. 159)
 Interface: actionMan 353

Core Interface Pages

Interface: actionMan
Action Manager (p. 9)
All Action Items are macro recorded when executed. This includes main menus items, CUI buttons,
keyboard shortcuts and quad menu items.
Prototype:
<boolean>executeAction <integer>tableId <string>persistentId
Parameters:
<integer>tableId
<string>persistentId
Return Value:
True if successful and false otherwise.
Prototype:
<boolean>loadKeyboardFile <string>file

Parameters:
<string>file
Return Value:
True if successful and false otherwise.
Prototype:
<boolean>saveKeyboardFile <string>file

Parameters:
<string>file
Return Value:
True if successful and false otherwise.
Prototype:
<string>getKeyboardFile()
Return Value:
True if successful and false otherwise.

See Also
Action Manager (p. 9)
The Macro Recorder (p. l)
Defining Macro Scripts (p. 1521)
The MAXScript Listener Window (p. xxxvi)
354 Chapter 1 | What’s New in 3ds max 4 MAXScript

Turning On the Listener Log (p. xli)

Listener Commands (p. xxxviii)

Interface: BoneSys
Bone Creation (p. 25)
Interface: BoneSys
Methods:
Prototype:
<node>createBone <point3>startPos <point3>endPos <point3>zAxis

Parameters:
<point3>startPos
The location of the new bone as point3
<point3>endPos
The direction (X axis) of the bone and the bone length as point3
<point3>zAxis
The direction of the Z axis for the new bone node as point3
Return Value:
It returns the new bone node that was created.
Note:
If the Z axis is not perpendicular to the X axis, the Z axis will be made perpendicular. To create a
bone chain, call createBone repeatedly with the startPosition set to the value of the previous
endPosition. Note that newly created bones are not linked to any parent. So to create a bone chain,
the script would also need to link each newly created bone segment to the previous.

See Also
Bones : System (p. 991)
Core Interfaces (p. 70)
Node Common Properties, Operators, and Methods (p. 820)
Bone Creation (p. 25)
Bone : Helper (p. 978)
Skin : Modifier (p. 1157)
Access to the new node bone properties and methods (p. 23) Bones_SystemBones_System
 Interface: browserMgr 355

Interface: browserMgr
This represents the interface to the Browser Manager.
Methods:
Prototype:
<Interface>newBrowser <string>rootURL <boolean>showDirectory <boolean>showContent
<boolean>showToolbar <boolean>showMenu
Remarks:
This method will create and open a new browser window.

Parameters:
<string>rootURL
The string containing the URL.
<boolean>showDirectory
TRUE to show as a directory, otherwise FALSE.
<boolean>showContent
TRUE to show the content window, otherwise FALSE.
<boolean>showToolbar
TRUE to show the browser toolbar, otherwise FALSE.
<boolean>showMenu
TRUE to show the browser menu, otherwise FALSE.
Return Value:
An interface to a new browsermgr.
Prototype:
<integer>numBrowsers()
Return Value:
This method will return the current number of browsers.
Prototype:
<Interface>getBrowser <integer>index
Remarks:
This method allows you to obtain a pointer to a specific browser.
Parameters:
<integer>index
Return Value:
An interface to the ith browser.
356 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
Asset Browser enhancements (p. 22)
iDrop - drag and drop (p. 62)
Zip-file Script Packages (p. 122)

Interface: cmdPanel
Customize The Order of Rollup Pages (p. 185)
Methods:
Prototype:
<integer>GetRollupThreshold()
Return Value:
Returns how many pixels of a rollout should be scrollable in the command panel before the rollout
is shifted into a separate command panel column. This option is only applicable when there are
multiple columns displayed in the command panel.
Prototype:
<void>SetRollupThreshold <integer>threshold
Remarks:
Parameters:
<integer>threshold

See Also
Rollout User-Interface Controls (p. 1481)
Rollout User-Interface Controls Types (p. 1484)
Rollout User-Interface Controls Common Properties (p. 1481)
Rollout User-Interface Controls Common Layout Parameters (p. 1483)
Customize The Order of Rollup Pages (p. 185)
Visual MAXScript (p. 117)

Interface: colorMan
Color Manager (p. 35)
This is an interface to the Color Manager. Within MAX, using the Customize pull down menu/
Customize User Interface choice/Colors tab, a user is able to alter the colors used for various UI
elements. They can change the saturation, value and transparency of elements, and load and save
color schemes.
Prototype:
<boolean>useStandardWindowsColors()
 Interface: colorMan 357

Return Value:
Returns true if the standard windows colors are used and false if custom colors are used.
Prototype:
<void>setUseStandardWindowsColors <boolean>onOff
Remarks:
Sets whether standard windows colors are used or not. This allows the developer to tell the system
to use standard windows colors, instead of the custom colors.
Parameters:
<boolean>onOff
Pass true to use the standard windows color and false to use the custom colors.
Prototype:
<boolean>registerColor <string>color <string>name <string>category <point3 by
value>defaultColor
Remarks:
This registers a new color with the system. This adds a color to the color manager database that is
then accessible from the color customization UI.
Parameters:
<string>color
The ID of the color to register. Example: #myNewColor
<string>name
The name for the color. Example: “My Own Color”
<string>category
The category for the color. If the name passed matches one of the existing MAX
categories the color will be placed in there, otherwise a new one will be created.
Example: “Fun Gaming Colors”
<point3 by value>defaultColor
The default value for the color. This is the value that the color will be reset to
when a MAX user presses “Reset” in the color customization dialog.
Example: [1,0,0]
Return Value:
Returns false if the color is already registered; otherwise true.
Prototype:
<boolean>loadColorFile <string>file
Remarks:
This method will load the specified color file from the current UI directory.
Parameters:
<string>file
The filename of the color file to load.
358 Chapter 1 | What’s New in 3ds max 4 MAXScript

Return Value:
TRUE if the load was successful, otherwise FALSE.
Prototype:
<boolean>saveColorFile <string>file
Remarks:
This method will save the specified color file from the current UI directory.
Parameters:
<string>file
The filename of the color file to save.
Return Value:
TRUE if the save process was successful, otherwise FALSE.
Prototype:
<string>getColorFile()
Return Value:
This method returns the file name of the current color file.
Prototype:
<boolean>setColor <string>color <point3 by value>colorValue
Remarks:
Sets the color value of the previously registered color whose ID is passed.
Parameters:
<string>color
Specifies which color to set.
<point3 by value>colorValue
The color value to set.
Predefined colors include:
#background -- The background for all controls and buttons
#text -- The text for all controls and buttons
#activeCommand -- The color command mode buttons turn when pressed
#hilight -- The hilight color for 3d controls
#shadow -- The shadow color for 3d controls
#window -- The background color for edit boxes, list boxes and
other windows
#activeCaption --
#toolTipBackground -- The background for viewport tool tips
#toolTipText -- The text color for viewport tool tips
#hilightText -- The hilight color in the stack view drop-down list
#windowText -- The color used in edit boxes, list boxes and other
windows
#itemHilight --
#subObjectColor -- The color used to hilight sub-object levels in
StackView
#3dDarkShadow -- the dark shadow color on 3d controls
 Interface: colorMan 359

#3dLight -- the light color on 3d controls

#appWorkspace --
#trackbarBg -- trackbar background
#trackbarBgSel -- trackbar background for selected keys
#trackbarText -- trackbar text
#trackbarTicks -- trackbar ticks
#trackbarKeys -- trackbar keys
#trackbarSelKeys -- track bar selected keys
#trackbarCursor -- track bar cursor
#pressedButton -- background color for pressed buttons, like the
transform constraints
#timeSliderBg -- The background for the time slider bar.
#viewportBorder -- The viewport border color
#activeViewportBorder -- The active viewport border color
#rollupTitleFace -- Rollout title background
#rollupTitleText -- rollout title text
#rollupTitleHilight-- rollout title 3d highlight
#rollupTitleShadow -- rollout title 3d shadow
#selectionRubberBand -- the selection marquee color
#stackViewSelection -- the color of a selected item in stack view
Return Value:
Returns true if the color was set and false if the id passed could not be found.
Prototype:
<point3 by value>getColor <string>color
Remarks:
Returns the color value of the color whose ID is passed.
Parameters:
<string>color
Specifies which color to get.
Return Value:
The color is returned or black (RGB(0,0,0)) if the Color passed was not found.
Prototype:
<string>getName <string>color

Parameters:
<string>color
The ID of the color.
Return Value:
Returns the name of the color whose ID is passed.
360 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<string>getCategory <string>color

Parameters:
<string>color
The ID of the color.
Return Value:
Returns the category string of the color whose ID is passed.
Prototype:
<float>getIconColorScale <enum>type <enum>which
type enums: {#disabledIcon|#enabledIcon}
which enums: {#saturationScale|#valueScale|#alphaScale}
Parameters:
<enum>type
One of the following values:
#disabledIcon
The disabled icons.
#enabledIcon
The enabled icons.
<enum>which
The icon color scale. One of the following values:
#saturationScale
The saturation scale.
#valueScale
The value scale.
#alphaScale
The alpha scale.
Return Value:
Returns a floating point value (in the range 0.0f to 1.0f) that is one of the scale factors applied to the
specified icon type. These scale values used to do image processing on the icons at start-up time.
Prototype:
<void>setIconColorScale <enum>type <enum>which <float>value
type enums: {#disabledIcon|#enabledIcon}
which enums: {#saturationScale|#valueScale|#alphaScale}
Remarks:
Sets the specified scale factor for the icon type passed. The color manager maintains the values for
the MAX icon image processing system. Developers can set values to scale the saturation, value and
transparency for enabled and disabled icon images using this method.
 Interface: colorMan 361

Parameters:
<enum>type
The icon type. One of the following values:
#disabledIcon
The disabled icons.
#enabledIcon
The enabled icons.
<enum>which
The icon color scale. One of the following values:
#saturationScale
The saturation scale.
#valueScale
The value scale.
#alphaScale
The alpha scale.
<float>value
The value runs from 0.0 to 100.0.
Prototype:
<boolean>getIconColorInvert <enum>type
type enums: {#disabledIcon|#enabledIcon}
Parameters:
<enum>type
The icon type. One of the following values:
#disabledIcon
The disabled icons.
#enabledIcon
The enabled icons.
Return Value:
Returns true if the invert flag is set for the specified icon type and false if not set.
Prototype:
<void>setIconColorInvert <enum>type <boolean>value
type enums: {#disabledIcon|#enabledIcon}
Remarks:
Sets the invert flag for the specified icon type to on or off.
Parameters:
<enum>type
The icon type. One of the following values:
#disabledIcon
The disabled icons.
362 Chapter 1 | What’s New in 3ds max 4 MAXScript

#enabledIcon
The enabled icons.
<boolean>value
Pass true for inverted; false for not inverted.
Prototype:
<string>getFileName()
Remarks:
Returns the file name of the currently loaded color file.
Prototype:
<point3 by value>getDefaultColor <string>color

Parameters:
<string>color
The ID of the color.
Return Value:
Returns the default color for the specified ID. The default color is the value passed as defaultValue
in registerColor, regardless if a SetColor() has been done subsequently. This is used by the UI when
the user presses “Reset” to reset a color to its default value.
Prototype:
<void>repaintUI <enum>type
type enums: {#repaintAll|#repaintTrackBar|#repaintTimeBar}
Remarks:
This method allows you to issue a repaint of the user interface.
Parameters:
RepaintType type
The type of repaint you wish to issue; #repaintAll, #repaintTrackBar,
#repaintTimeBar.

See Also
In The MAXSDK Help File:
Class IColorManager

Interface: dragAndDrop
iDrop - drag and drop (p. 62)
The Drag and Drop system is managed through a Core Function Published interface. It provides
control over the DnD system, manages handler registration and exposes some useful utility methods
for downloading URL’s, simulating drops, etc.
 Interface: dragAndDrop 363

Prototype:
<void>globalEnableDragAndDrop <boolean>onOff
Remarks:
This method allows you to globally enable or disable the DnD interface.
Parameters:
<boolean>onOff
TRUE to enable, FALSE to disable.
Prototype:
<boolean>isEnabled()
Return Value:
This method returns TRUE if the global DnD interface is enabled, otherwise FALSE.
Prototype:
<boolean>enableDragAndDrop <HWND>window <boolean>onOff
Remarks:
This method allows you to enable DnD for a given window (and its children). If no custom
DragAndDropHandler is supplied, a default one is used that will accept dropped scene files for
opening and scripts for running.
Parameters:
<HWND>window
A handle to the window you wish to enable or disable DnD for.
<boolean>onOff
TRUE to enable, FALSE to disable.
Return Value:
True if successful and false otherwise.
Prototype:
<boolean>dropPackage <HWND>window <&point>mousePoint <&string array>files
Remarks:
This method allows the simulation of a package of files into a window at a given point. A package
of files, specified as a list of URL strings is the common form of DropType data from iDrop sources
and files dragged from the Windows desktop. The entire package is downloaded, as needed, but only
the first file in the list is actually dropped into MAX. The other files in the package are presumed to
be support files, such as texmaps or xref sources, for the main drop file. After the drop, the URL
strings in the URLTab are converted to fully-specified path names to local file copies, if any had to
be downloaded from the web.
Parameters:
<HWND>window
A handle to the window. If this is set to NULL, the default MAX window is used.
<&point>mousePoint
The point at which to drop.
364 Chapter 1 | What’s New in 3ds max 4 MAXScript

<&string array>files
A reference to the local copies of the URL strings.
Return Value:
TRUE if the drop was successful, otherwise FALSE.
Prototype:
<boolean>downloadPackage <&string array>files <string>directory
Remarks:
This method serves as a utility function that can be used to download a package of URLs to the
specified directory. If the hwnd argument is supplied, any progress or other messages are centered
over that window.
Parameters:
<&string array>files
A reference to the local copies of the URL strings.
<string>directory
The directory path string to download to.
Return Value:
True if successful and false otherwise.
Prototype:
<string>getDownloadDirectory()
Return Value:
This method returns the fully-specified path to the directory in which package drops are
downloaded.
Prototype:
<boolean>DownloadUrlToDisk <string>url <string>fileName <integer>flags
Remarks:
This method allows you to download the file referenced by the URL to disk.
Parameters:
<string>url
The URL string of the file to download.
<string>fileName
The filename string of the URL to store on disk.
<integer>flags
Return Value:
True if successful and false otherwise.
Prototype:
<node>ImportContextNode()
Return Value:
Returns a pointer to the import context node.
 Interface: HDIKSys 365

See Also
Zip-file Script Packages (p. 122)
iDrop - drag and drop (p. 62)

Interface: HDIKSys
Interface: HDIKSys
Methods:
Prototype:
<void>ikChain <node>startJoint <node>endJoint <boolean>createEndEffector

Parameters:
<node>startJoint
<node>endJoint
<boolean>createEndEffector
Prototype:
<boolean>RemoveChain <node>chainNode
Remarks:
Calling this method on the master controller causes all slave controllers in the chain to be replaced
with default transform controllers (PRS). This method will support undo if it is enabled but will not
turn undo on. This method does not cause viewports to be redrawn.
Parameters:
<node>chainNode

See Also
HD IK controller chains can be assigned to existing hierarchies (p. 73)

Interface: IKSys
Interface: IKSys
Methods:
Prototype:
<node>ikChain <node>startJoint <node>endJoint <string>solver
Remarks:
Where startJoint is the first node in the new chain (ancestor), endJoint is the last node in the
chain (decendent) and assignEE is a boolean parameter: when TRUE, a position end effector is
crated at the endJoint.
Parameters:
<node>startJoint
<node>endJoint
<string>solver
366 Chapter 1 | What’s New in 3ds max 4 MAXScript

Interface: manip
Scripted Manipulators (p. 97)
Properties:
.msXYPlane : Interface : Read
.msXZPlane : Interface : Read
.msYZPlane : Interface : Read
Prototype:
<mesh>makeSphere <point3 by value>pos <float>radius <integer>segments

Parameters:
<point3 by value>pos
<float>radius
Specifies the radius of the sphere.
<integer>segments
Sets the number of polygonal divisions for the sphere.
Return Value:
This returns a mesh sphere with the given position, radius, and segments.
Prototype:
<mesh>makeTorus <point3 by value>pos <float>radius <float>radius2 <integer>segs
<integer>sides

Parameters:
<point3 by value>pos
<float>radius
Sets the distance from the center of the torus to the center of the cross-sectional
circle. This is the radius of the torus ring.
<float>radius2
Sets the radius of the cross-sectional circle. The default is 10 units. This value is
replaced each time you create a torus.
<integer>segs
Sets the number of radial divisions around the torus. By reducing this number,
you can create polygonal rings instead of circular ones.
<integer>sides
Sets the number of sides on the cross-sectional circle of the torus. By reducing this
number, you can create prism-like cross sections instead of circular ones.
Return Value:
Create a torus mesh with the given values.
Prototype:
<mesh>makeBox <point3 by value>pos <float>l <float>w <float>h <integer>lsegs
<integer>wsegs <integer>hsegs
 Interface: manip 367

Parameters:
<point3 by value>pos
<float>l
Sets the length, width, and height of the Box object. These fields also act as
readouts while you drag the sides of the box. Default=0,0,0.
<float>w
Sets the length, width, and height of the Box object. These fields also act as
readouts while you drag the sides of the box. Default=0,0,0.
<float>h
Sets the length, width, and height of the Box object. These fields also act as
readouts while you drag the sides of the box. Default=0,0,0.
<integer>lsegs
Sets the number of divisions along each axis of the object. Can be set before or
after creation. By default, each side of the box is a single segment. When you reset
these values, the new values become the default during a session. Default=1,1,1.
Tip: Increase the Segments settings to give objects extra resolution for being affected by modifiers.
For example, if you’re going to bend a box on the Z axis, you might want to set its Height Segments
parameter to 4 or more.
<integer>wsegs
Sets the number of divisions along each axis of the object. Can be set before or
after creation. By default, each side of the box is a single segment. When you reset
these values, the new values become the default during a session. Default=1,1,1.
Tip: Increase the Segments settings to give objects extra resolution for being affected by modifiers.
For example, if you’re going to bend a box on the Z axis, you might want to set its Height Segments
parameter to 4 or more.
<integer>hsegs
Sets the number of divisions along each axis of the object. Can be set before or
after creation. By default, each side of the box is a single segment. When you reset
these values, the new values become the default during a session. Default=1,1,1.
Tip: Increase the Segments settings to give objects extra resolution for being affected by modifiers.
For example, if you’re going to bend a box on the Z axis, you might want to set its Height Segments
parameter to 4 or more.
Return Value:
Creates a box mesh with the given parameters.
Prototype:
<Interface>makePlaneFromPts <point3 by value>p1 <point3 by value>p2 <point3 by
value>p3
Parameters:
<point3 by value>p1
<point3 by value>p2
<point3 by value>p3
368 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<Interface>makePlaneFromNormal <point3 by value>normal <point3 by value>point
Parameters:
<point3 by value>normal
<point3 by value>point
Return Value:
Creates a Plane object with the given normal that passes through the given point.
Prototype:
<Interface>makeGizmoShape()
Prototype:
<Interface>makeCircle <point3 by value>center <float>radius <integer>segments
Parameters:
<point3 by value>center
<float>radius
<integer>segments

Interface: maxOps
maxOps (p. 87)
Properties:
.productVersion : enum : Read
productVersion enums:
{#productVersionDevel|#productVersionTrial|#productVersionOrdinary|#productVersion
Edu|#productVersionNFR}
.licenseBehavior : enum : Read
licenseBehavior enums:
{#licenseBehaviorPermanent|#licenseBehaviorExtendable|#licenseBehaviorNonextendabl
e}
.licenseDaysLeft : integer : Read
.trackbar : Interface : Read
Methods:
Prototype:
<boolean>canImportBitmap <string>fileName
Parameters:
<string>fileName
Return Value:
True if successful and false otherwise.
Prototype:
<void>displayActiveCameraViewWithMultiPassEffect()
Remarks:
displayActiveCameraViewWithMultiPassEffect - no automatic redraw after invoked
 Interface: maxOps 369

Prototype:
<void>setActiveViewportTransparencyDisplay <integer>transparencyLevel
Parameters:
<integer>transparencyLevel
Prototype:
<boolean>loadCUIFile <string>fileName
Parameters:
<string>fileName
Return Value:
True if successful and false otherwise.
Prototype:
<boolean>isFeatureLicensed <integer>featureNumber
Parameters:
<integer>featureNumber
Return Value:
True if successful and false otherwise.
Prototype:
<Interface>GetCurRenderElementMgr()
Return Value:
gets the current render element manager.
Prototype:
<Interface>GetRenderElementMgr <enum>
Parameters:
{#Production|#Draft}
Return Value:
Gets a specific render element manager.
Prototype:
<void>CollapseNode <node>node <boolean>noWarning
Remarks:
Parameters:
<node>node
<boolean>noWarning
Prototype:
<boolean>CollapseNodeTo <node>node <index>modIndex <boolean>noWarning
Parameters:
<node>node
<index>modIndex
<boolean>noWarning
370 Chapter 1 | What’s New in 3ds max 4 MAXScript

Return Value:
True if successful and false otherwise.
Prototype:
<boolean>CloneNodes <&node array>nodes <&point3>offset expandHierarchy:<boolean>
cloneType:<enum> actualNodeList:<node array> newNodes:<node array>
Parameters:
<&node array>nodes
<&point3>offset
expandHierarchy:<boolean>
expandHierarchy default value: false
cloneType:<enum>
cloneType enums: {#copy|#instance|#reference}
cloneType default value: #copy
actualNodeList:<node array>
actualNodeList default value: #()
newNodes:<node array>
newNodes default value: #()
Return Value:
True if successful and false otherwise.
Prototype:
<boolean>setSelectionType <boolean>auto <enum>method
Parameters:
<boolean>auto
method enums: {#window|#crossing|#leftToRight|#rightToLeft}
Return Value:
True if successful and false otherwise.
Prototype:
<maxObject>getNodeByHandle <DWORD>handle
Parameters:
<DWORD>handle
Return Value:
Return a node associated with a given handle.
Prototype:
<Interface>getTrackBar()
Return Value:
The interface to a trackbar is returned.
 Interface: medit 371

Interface: medit
Interface available for Texmap and Mtl Interface_medit.
Prototype:
<maxObject>GetCurMtl()
Return Value:
This method returns a material base pointer for the current material.
Prototype:
<void>SetActiveMtlSlot <index>slot <boolean>forceUpdate
Parameters:
<index>slot
The material slot index.
<boolean>forceUpdate
Set this to TRUE to update the slot contents.
Remarks:
This method allows you to set the active material slot.
Prototype:
<index>GetActiveMtlSlot()
Return Value:
This method returns the index of the active material slot.
Prototype:
<void>PutMtlToMtlEditor <maxObject>mtl <index>slot
Parameters:
<maxObject>mtl
The material you want to put.
<index>slot
The index of the material slot you wish to put the material into.
Remarks:
This method allows you to put the specified material to the specified material editor slot.
Prototype:
<maxObject>GetTopMtlSlot <index>slot
Parameters:
<index>slot
The index of the material slot for which you wish to obtain the material.
Return Value:
This method returns a pointer to the material base from the specified slot.
Prototype:
<boolean>OkMtlForScene <material>mtl
372 Chapter 1 | What’s New in 3ds max 4 MAXScript

Parameters:
<material>mtl
The pointer to the material.
Return Value:
Before assigning material to scene, call this to avoid duplicate names.
Prototype:
<void>UpdateMtlEditorBrackets()

Remarks:
This method makes sure the Materials Editor slots correctly reflect which materials are used in the
scene, which are used by selected objects, etc. This is used internally for the drag-and-drop of
materials to nodes -- there is no reason why a plug-in developer should need to call it.

See Also
Material Editor Access (p. 165)
BitmapTex Reload and viewImage (p. 164)

Interface: menuMan
Prototype:
<boolean>loadMenuFile <string>file
Remarks:
This method allows you to load a menu file from disk and automatically update the UI accordingly.
Parameters:
<string>file
The path and filename of the menu file to load.
Return Value:
TRUE if the menu file was loaded, otherwise FALSE.
Prototype:
<boolean>saveMenuFile <string>file
Remarks:
This method allows you to save a menu file to disk.
Parameters:
<string>file
The path and filename of the menu file to save.
Return Value:
TRUE if the menu file was saved, otherwise FALSE.
 Interface: menuMan 373

Prototype:
<string>getMenuFile()
Return Value:
This method returns the file name of the currently loaded and active menu file.
Prototype:
<void>updateMenuBar()
Remarks:
This method can be called to update MAX’ main menu bar after adding sub-menu’s or menu items.
Prototype:
<boolean>registerMenuContext <integer>contextId
Remarks:
To add items to MAX’s main menu, the plug-in should check the return value of
RegisterMenuContext(), and if it is true, that means that this is the first time it has been registered,
and the plug-in can then create new menus, add items to MAX’s main menu and Quad menus.
Prototype:
<Interface>findMenu <string>menuName
Remarks:
This method will return a pointer to a menu based on its name.
Parameters:
<string>menuName
The name of the menu to return.
Return Value:
A pointer to the menu or NULL if the menu wasn’t found.
Prototype:
<Interface>findQuadMenu <string>menuName
Remarks:
This method will return a pointer to a quad menu based on its name.
Parameters:
<string>menuName
The name of the menu to return.
Return Value:
A pointer to the quad menu or NULL if the menu wasn’t found.
Prototype:
<boolean>unRegisterMenu <Interface>menu
Remarks:
This method allows you to remove a menu form the mananger.
374 Chapter 1 | What’s New in 3ds max 4 MAXScript

Parameters:
<Interface>menu
Points to the menu to unregister.
Return Value:
FALSE if the menu was not registered, TRUE if successfully unregistered.
Prototype:
<boolean>unRegisterQuadMenu <Interface>quadMenu
Parameters:
<Interface>quadMenu
Remarks:
This is like “unregisterMenu” but for quad menus.
Prototype:
<Interface>createMenu <string>name
Parameters:
<string>name
Return Value:
This creates a new, empty menu with the given name.
Prototype:
<Interface>createQuadMenu <string>name <string>quad1Name <string>quad2Name
<string>quad3Name <string>quad4Name
Parameters:
<string>name
<string>quad1Name
<string>quad2Name
<string>quad3Name
<string>quad4Name
Remarks:
This creates a new, empty quad menu. It contains, 4 empty menus, one for each quad.
Prototype:
<Interface>createSubMenuItem <string>name <Interface>subMenu
Parameters:
<string>name
<Interface>subMenu
Remarks:
This creates a new sub-menu item that can be added to a menu. It uses the given “name” and it
displays the given sub-menu.
Prototype:
<Interface>createSeparatorItem()
 Interface: menuMan 375

Return Value:
This creates a new menu separator that can be added to a menu.
Prototype:
<Interface>createActionItem <string>macroScriptName <string>macroScriptCategory
Parameters:
<string>macroScriptName
<string>macroScriptCategory
Return Value:
This creates a new menu item that can be added to a menu. The item is an action that executes the
macro script with the given name and category. This returns “undefined” if there is no macroScript
with the given name and category.
Prototype:
<boolean>setViewportRightClickMenu <enum>which <Interface>menu
which enums:
{#nonePressed|#shiftPressed|#altPressed|#controlPressed|#shiftAndAltPressed|#shiftAndControlPres
sed|#controlAndAltPressed|#shiftAndAltAndControlPressed}
Remarks:
This method allows you to set the viewport right-click menu to the specified quad menu.
Parameters:
<enum>which
See the List of Right-Click Contexts above.
<Interface>menu
A pointer to the quad menu you wish to set.
Return Value:
TRUE if it was set successfully.
Prototype:
<Interface>getViewportRightClickMenu <enum>which
which enums:
{#nonePressed|#shiftPressed|#altPressed|#controlPressed|#shiftAndAltPressed|#shiftAndControlPres
sed|#controlAndAltPressed|#shiftAndAltAndControlPressed}
Parameters:
<enum>which
See the List of Right-Click Contexts..
Return Value:
This method returns a pointer to the current viewport right-click quad menu.
Prototype:
<Interface>getMainMenuBar()
376 Chapter 1 | What’s New in 3ds max 4 MAXScript

Return Value:
This method returns a pointer to the main menu bar.
Prototype:
<boolean>setMainMenuBar <Interface>menu
Remarks:
This method allows you to set the main menu bar.
Parameters:
<Interface>menu
A pointer to the menu you wish to set as the main menu bar.
Return Value:
TRUE if it was set successfully.
Prototype:
<bool>getShowAllQuads <Interface>quadMenu
Remarks:
This method checks if the “Show All Quads” flag is set for a specific QuadMenu.
Parameters:
<Interface>quadMenu
A pointer to the QuadMenu you wish to check the flag for.
Return Value:
This method will return TRUE if the flag is set or FALSE if the flag is not set.
Prototype:
<void>setShowAllQuads <Interface>quadMenu <bool>value
Remarks:
This method sets the “Show All Quads” flag for a specific QuadMenu.
Parameters:
<Interface>quadMenu
A pointer to the QuadMenu you wish to set the flag for.
<bool>value
TRUE to set the flag to on, FALSE to set the flag off.
Prototype:
<string>getQuadMenuName <Interface>quadMenu
Parameters:
<Interface>quadMenu
A pointer to the QuadMenu for which you wish to retrieve the name.
Return Value:
This method returns the name given to a specific QuadMenu as a string.
 Interface: menuMan 377

Prototype:
<void>setQuadMenuName <Interface>quadMenu <string>name
Remarks:
This method allows you to set the name of a specific QuadMenu.
Parameters:
<Interface>quadMenu
A pointer to the QuadMenu for which you wish to set the name.
<string>name
The string containing the name for the QuadMenu.
Prototype:
<integer>numMenus()
Return Value:
Returns the total number of menus in registered with the menu manager.
Prototype:
<Interface>getMenu <index>index
Parameters:
<index>index
Return Value:
Retrieves the “index”th menu in the menu manager. This is a 1-based index.
Prototype:
<integer>numQuadMenus()
Return Value:
Returns the total number of quad menus registered with the menu manager.
Prototype:
<Interface>getQuadMenu <index>index
Parameters:
<index>index
Return Value:
Retrieves the “index”th quad menu in the menu manager. This is a 1-based index.

See Also
In The MAXSDK Help File
Class ImenuManager

See Also
Menu Manager (p. 75)
Interface: quadMenuSettings (p. 414)
378 Chapter 1 | What’s New in 3ds max 4 MAXScript

Interface: msZip
Prototype:
<boolean>fileInPackage <string>fileName <&TSTR>extractDir
Remarks:
extractDir is In parameter
This method will unload and run a zip package and return the extract_dir.
Parameters:
<string>fileName
The file name of the ZIP script package.
<&TSTR>extractDir
The directory in which the files were extracted.
Return Value:
TRUE if the zip package was run, otherwise FALSE.
Prototype:
<boolean>unloadPackage <string>fileName <&TSTR>extractDir <&TSTR>dropFile
Remarks:
extractDir is In parameter
dropFile is In parameter
This method will unload the package while ignoring any drop or run commands and return the
extract_dir and any primary drop file. If the primary dropFile is a *.ds, compile it in context of the
package and return the MacroEntry in dropScript.
Parameters:
<string>fileName
The file name of the ZIP script package.
<&TSTR>extractDir
The directory in which the files were extracted.
<&TSTR>dropFile
The primary drop file.
Return Value:
TRUE if the package was unloaded, otherwise FALSE.

See Also
Interface: dragAndDrop (p. 362)
Zip-file Script Packages (p. 122)
iDrop - drag and drop (p. 62)
 Interface: NetRender 379

Interface: NetRender
Methods:
Prototype:
<Interface>GetManager()
Remarks:
In order to access network rendering through the scripter, you need to create a manager instance.
The syntax is the following:
netrender.getmanager()

Working with the manager

The following methods can be used to query and or control the manager.
Prototype:
<netManager>.setCallback #progress | #message | #update | #managerdown |
#queuecontrol | #querycontrol <somefunction>
Remarks:
Used to listen to the manager for certain event types that occur during a network render. For each
event type, you can call a single function that you define. Each of the 6 callback types is one type of
event, and you can install a callback for any of these event or none.
You must define the function to take a different number of arguements depending on the
event type.
Requires 2 arguments, they can be:
#progress myprogess
Called anytime a download/upload is underway, including anytime you fetch
information about jobs or servers.
Requires a function defined with 2 integer parameters, ‘Total’ and ‘Current’. Total is
the total amount to transfer, and Current is the amount tranferred so far.
Example:
fn myprogress total current = -- NOTE: two integer parameters
format “Progress: completed % out of %\n” current total
m.setcallback #progress myprogress -- sets the #progress callback to use
myprogress()

#message mymessage
Called when the manager has a text message for the user. Requires a function defined
with 1 string parameter which is the message text.
380 Chapter 1 | What’s New in 3ds max 4 MAXScript

Example:
fn myNetMessage msg =-- NOTE: one string parameter
format “Message: %\n” msg
m.setcallback #message mymessage -- sets the #message callback to use
mymessage()

#update myupdate
Called when something has changed, like a job started or finished. Let’s you know
when you need to make GetUpdate calls, or other refreshing. Requires a function
defined with no parameters.
Example:
fn myUpdate =
job.GetUpdate()--example of what you might do
m.setcallback #update myupdate -- sets the #update callback to use
myupdate()

#managerdown mymanagerdown
Called when the manager shuts down. Requires a function defined with no
parameters.
Example:
fn myManagerDown =
format “Manager is dead\n”
m.setcallback mymanagerdown -- sets the #managerdown callback to use
mymanagerdown()

#queuecontrol myqueuecontrol
Called whenever queue control changes. Requires a function defined with no
parameters.
Example:
fn myQueueControl =
format “Queue control has changed\n”
m.setcallback #QueueControl myQueueControl--install the “QueueControl”
callback

#querycontrol myquerycontrol
Called when you have Queue Control, and another computer wants it, either via the
QueueManager, or with the script function <netManager>.QueryControl(). If you
want to keep control, set the value <netManager>.WantControl to true, otherwise set
it to false. The function must take one arguement, which is the name of the machine
requesting control. See the function <netManager>.QueueControl() for more
information.
 Working with the manager 381

Example:
fn myQueryControl clientName = (--NOTE: one string parameter
format “The computer % wants queue control” clientName
m.wantControl = true-- use this to keep queue control
m.wantControl = false-- use this to release queue control
)
m.setcallback #QueryControl myQueryControl--install the “QueryControl”
callback

Prototype:
<netManager>.GetCallback <#progress | #message | #update | #managerdown |
#queuecontrol | #querycontrol>
Remarks:
Returns the name of the function used for that particular callback. Returns an empty array if no
callback is assigned. Requires 1 argument, can be:
#progress
Called anytime a download/upload is underway, including anytime you fetch
information about jobs or servers
#message
Called when the manager has a text message for the user
#update
Called when something has changed, like a job started or finished. Let’s you know
when you need to make GetUpdate calls, or other refreshing
#managerdown
Called when the manager dies
#queuecontrol
Called whenever queue control changes
#querycontrol
Called when you have Queue Control, and another computer wants it
Prototype:
<netManager>.connect #manual <manager name>|<manager IP address> [port:<integer>]
or
<netManager>.connect #automatic <subnet mask> [port:<integer>]
Remarks:
Establishes a connection to the manager, allowing access to job states, server states, editing job
settings, etc…
.It takes 2 arguments and a 3rd optional argument. You can either connect to a manager
manually by specifying the manager name or ip address of the manager as a string, or automatically
by specifying the subnet mask and optional port number, eg:
m.connect #manual “manager” -- connects to manager of name “manager”
or:
m.connect #manual “192.168.0.1” -- connects to manager of IP 192.168.0.1
or:
382 Chapter 1 | What’s New in 3ds max 4 MAXScript

m.connect #automatic “255.255.255.0” port:1234 -- automatically connects

to manager on subnet 255.255.255.0 at port 1234
in either case, you can specify the optional port number should the manager be using a
non default port number. Will return true if connection was succesful.
Prototype:
<netManager>.Disconnect()
Remarks:
Disconnects the connection established with <netManager>.connect.
Prototype:
<netManager>.Kill()
Remarks:
Shutsdown the manager. You must have queue control to do this.
Prototype:
<netManager>.QueryControl #wait | #dontwait
Parameters:
requires either #wait or #dontWait. The function works as follows:
Nobody has queue controlSomeone has Queue Control
#dontWaitreturns TRUEreturns FALSE
#waitreturns TRUEprompts the current queue controller
Remarks:
In the last case, the queue controller gets the QueryControl callback, and must indicate if they want
control. If that user indicates they want to keep control, then the function returns FALSE, if they will
give up control (or the 10 second timeout expires), it returns TRUE. Note that the QueueManager
gives a prompt for the user to indicate what they want; in the scripter, you just get the callback and
have to use the wantControl value.
Note:
Please refer to callback, “#queuecontrol myqueuecontrol“, found above in
<netManager>.setCallback.
Prototype:
<netManager>.GetControl()
Remarks:
Takes control of the queue. Returns true if control was taken. From that moment on, jobs can be
submitted, edited, reprioritized, servers can be removed, until queue control is relinquished.
Note:
The current queue controller does not get its QueryControl callback triggered. Instead, they just lose
the queue control (unless they also have the queue locked lock). You should always precede a call to
GetControl() with a call to QueryControl(true), to be sure if it’s OK to do this.
 Working with the manager 383

Prototype:
<netManager>.Lock <true | false>
Remarks:
Locks out others from getting queue control; and if they call QueryControl, it will automatically
return false. For example, suppose you got control of the queue through the scripter using
getcontrol(), someone else who has the queuemanager up in readonly mode can request
queuecontrol. Setting lock to true, will disallow anyone else to take control until you until you
disconnect from the manager, or until you reset the lock to false. Note that the QueueManager
always calls QueryControl to check if it can grab the queue.
Prototype:
<netManager>.SetUpdates <true | false>
Remarks:
This function’s usage resemebles the Lock() function, in that a boolean value is passed, and you must
already have queue control. Setting updates to false will freeze the manager so that it refuses any
changes to the queue. It does not affect the callbacks. Fewer Update callbacks will be received, since
the job queue is not
updating. Use this function when submitting large numbers of changes, and when you want all the
changes to take effect at the same time. This will occur when setUpdates is called with a true value.
Prototype:
<netManager>.checkoutputvisibility <path>
Takes 1 argument, a pathname defined as a string, ie “c:\\temp”.
Remarks:
It verifies that the path exists, returns “The system cannot find the path specified. (0x3)” if the path
doesn’t exist.
Note:
Note that the manager checks this output path relative to itself, not to your local machine. Thus if
you pass “C:\\” and you have not shared you C drive, it will return OK (because the manager checks
its own C drive). Thus you should use a network name when calling this function, like
“\\\\mymachine\\share\\”. Also, if the parameter does not end in \\, the functions assumes
you’re naming a file (not a directory) and checks whether this file could be created. Always include
the \\ at the end if you’re checking whether a directory is accessible.

Properties:
The following properties can be used to get information or set certain properties of the manager.
Prototype:
<netManager>.connected
Remarks:
Returns true if connected to the manager.
384 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<netManager>.netStatus
Remarks:
Returns the status of the manager. Various information about the manager can be gathered through
netstatus,see netstatus topic.
Prototype:
<netManager>.wantControl
Remarks:
If you have QueueControl, and other computers call QueryControl, this indicates whether you want
to maintain control, or relinquish it; their call to QueryControl will return whatever you have set
for WantControl
Prototype:
<netManager>.haveControl
Remarks:
True, if you currently have QueueControl.
Prototype:
<netManager>.numJobs
Remarks:
Returns the number of jobs in the queue.
Prototype:
<netManager>.numServers
Remarks:
Returns the number of servers.
Prototype:
<netManager>.numGroups
Remarks:
Returns the number of groups.

Working with jobs

Various functions and properties can be used to access jobs. You can use the GetJobs() function to
retrieve an array of all jobs in the queue. The jobs can be filtered in various ways to return an array
based on the filter.
Note:
Do not call GetJobs() or GetServers() very often, because these are VERY heavyweight
methods.
 Working with jobs 385

Prototype:
<netManager>.getjobs [filter:#suspended | #complete | #waiting | #started | #error
| #name | #handle | #index] [key:<name> | <handle> | <index>]
The latter three filter types require a corresponding key arguement.
If used without a filter, returns an array of all jobs in queue. If no jobs are in the queue, an empty
array will be returned.
filter:#suspended
Returns an array of all suspended jobs. Returns an empty array #() if no jobs are
suspended
filter:#complete
Returns an array of all completed jobs. Returns an empty array #() if no jobs are
complete.
filter:#waiting
Returns an array of jobs that are waiting to be rendered or are being rendered. Will
return an empty array #() if no jobs are waiting.
filter:#started
returns an array of jobs that are actually started and being rendered.
filter:#complete
Returns an array of all completed jobs. Returns an empty array #() if no jobs are
complete
filter:#error
Returns an array of all jobs experiencing an error. Returns an empty array #() if no
jobs have errors
filter:#name
Pass a name as the Key argument; Returns an array of all jobs with the given
name. Returns an empty array #() if the no jobs have that name
filter:#handle
Pass a handle as the Key argument; the job with that handle will be returned (as
an array with one element). Returns an empty array #() if the no job has
that handle
filter:#index
Pass an integer as the Key argument; the job at that index in the queue will be
returned (as an array with one element). Returns an empty array #() if the no job
exists at that index
Example:
manager.GetControl() --get queue control
manager.SetUpdates false --the queue is now frozen
jobs = manager.GetJobs()
manager.SetUpdates true --the queue is unfrozen

Note:
The GetJobs() function could return incorrect results if the Queue is changed while the job
information is downloading. SetUpdates is used to guarantee that GetJobs operates without error.
386 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<netManager>.SetJobOrder <array>
Remarks:
Changes the order of the jobs in the queue. The array must contain the same jobs that are contained
in the array from .getjobs(), although they can be in different order. You must also have
queuecontrol, use .getcontrol() function to take control before setting the job order.
Prototype:
<netManager>.NewJob file:<filename>
Example:
job.newJob file:”file.max” --submitting a file
job.newJob() --submitting the current scene
Remarks:
Creates a new job instance. It requires a valid max file name, ie a max file that exists somewhere on
the hard drive or the network. Returns a job definition if the file exists, undefined if the file can’t be
found.
Note:
Jobs can not have maps included, and render element data will not be available for submitted job
but render elements will process correctly. These problems are resent when submitting a job from a
file, but not when submitting the current scene.
Prototype:
<job>.GetUpdate()
Remarks:
Updates the information about the selected job. Remember this involves a network interaction, so
it’s a heavyweight operation
Prototype:
<job>.SendUpdate()
Remarks:
Updates the job in the queue with new job settings. Must have queuecontrol. Use
<netManager>.getcontrol() to get queue control. Remember this involves a network
interaction, so it’s a heavyweightoperation
Prototype:
<job>.Submit() Servers:<array>
Remarks:
Submits a new job to be rendered to the queue. Must have queuecontrol. Use
<netManager>.getcontrol() to get queue control. if no servers are provided, then all servers will
be assigned to the job.
Prototype:
<job>.Suspend()
 Working with jobs 387

Remarks:
Suspends the selected job. Must have queuecontrol. Use <netManager>.getcontrol() to get
queue control.
Prototype:
<job>.Resume()
Remarks:
Will cause the job to resume where it left off when it was suspended. Must have queuecontrol. Use
<netManager>.getcontrol() to get queue control.
Prototype:
<job>.Restart()
Remarks:
Will restart the job from the beginning. Must have queuecontrol. Use
<netManager>.getcontrol() to get queue control.
Prototype:
<job>.Delete()
Remarks:
Will delete the job from the queue. Must have queuecontrol. Use <netManager>.getcontrol()
to get queue control.
Prototype:
<job>.AssignServer <server>
Remarks:
Assigns a selected server to the job. Must have queuecontrol. Use <netManager>.getcontrol()
to get queue control.
Prototype:
<job>.SuspendServer <server>
Remarks:
Removes a server from the selected job. Must have queuecontrol. Use
<netManager>.getcontrol() to get queue control.
Prototype:
<job>.GetServerInfo <integer>
Remarks:
Gets information about a particular server assigned to the job. Requires a server number, 1 based.
Prototype:
<job>.GetRenderElement <index>
388 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Returns information as a data structure about the nth element in the. The <element> structure is
defined below. Returns undefined if no element at the index number, eg: el =
jobs[1].getrenderelement 1 -- retrieves the 1st element in the 1st job in the queue. With this
you can find out if the element is enabled, if filtering is enabled, if atmosphere is applied, if shadows
are applied, the element name and the element output filename. The following are the properties
that are valid for an element.
Prototype:
<element>.enabled
Remarks:
Returns true if the element is enabled. Can also set it’s state.
Prototype:
<element>.filterEnabled
Remarks:
Returns true if filtering is enabled. Can also set it’s state.
Prototype:
<element>.atmosphereApplied
Remarks:
Returns true if atmosphere is applied. READ-ONLY
Prototype:
<element>.shadowsApplied
Remarks:
Returns true if shadows are applied. READ-ONLY
Prototype:
<element>.name
Remarks:
Returns the elements name. Name can be changed.
Prototype:
<element>.output
Remarks:
Returns the element’s output file name. Output name and path can be changed, however, changing
the filetype will change the extension of the image but not the actual file type, eg: the current output
returned is “\\ej4sf\frames\foo_diffuse.tga”, changing the extension to .bmp will just
result in the tga file having a .bmp extension instead of the .tga extension.
Prototype:
<job>.SetRenderElement <index> <element>
 Working with jobs 389

Remarks:
Sets the selected render element to the new values assigned to the element. In order for the change
to take effect in the job, you need to do a <job>.sendupdate() to update the job itself in the
queue.
Prototype:
<job>.GetCameras()
Remarks:
Returns an array of cameras in the scene. An empty array #() is returned if no cameras are in the
scene.
Prototype:
<job>.GetLog() start:x numLines:y
Remarks:
Returns the log for the job as text. The ‘start’ and ‘numLines’ parameters are optional. If you pass no
parameters, you get the entire log. If you only pass start, you get every line starting from the given
line. If you pass only numLines, then start is assumed to be 0.
Prototype:
<job>.GetFrameInfo <integer>
Remarks:
Returns information, as a data structure, about the nth frame. The index is 1 based. The <frame>
structure is defined below.
Example:
fr = getframeinfo 4 -- Returns info about the 4th frame. Read-only
Prototype:
<frame>.state
Remarks:
Returns the state of the frame. The state can be #waiting, #assigned or #complete.
Prototype:
<frame>.index
Remarks:
Returns the actual frame number. Read-only
Prototype:
<frame>.serverhandle
Remarks:
Returns the serverhandle. Should return undefined when frame hasn’t been rendered yet. Read-only
Prototype:
<frame>.servername
390 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Returns the name of the server that is assigned to that frame. Should return undefined if the frame
isn’t assigned yet. Read-only
Prototype:
<frame>.elapsedtime
Remarks:
Returns the time it took for the frame to render. Should return undefined if the frame isn’t assigned
yet. Read-only
Prototype:
<job>.GetServerStatusText <server>
Remarks:
Returns any messages from the chosen server assigned to the job. Will return an empty string if no
messages from the server. Read-only
Prototype:
<job>.numServers
Remarks:
Returns the number of servers assigned to the job. Read-only
Prototype:
<job>.state
Remarks:
Returns the state of the job. This can be #complete, #suspended, #busy or #waiting. Read-only
Prototype:
<job>.serverPID
Remarks:
This function gives low-level information that is intended for internal-use-only.
Prototype:
<job>.handle
Remarks:
Returns the job’s handle. Read-only
Many of the following values are read-write, but changes you make to these values will not register
with the manager until you call <job>.SendUpdate().
Note that SendUpdate requires queue control (obtained via <NetManager>.getControl)
Prototype:
<job>.name
Remarks:
Returns the name of the job. The name can be changed
 Working with jobs 391

Prototype:
<job>.filesize
Remarks:
Returns the job’s file size
Prototype:
<job>.filesizeExtracted
Remarks:
Returns the job’s extracted file size. Read-only
Prototype:
<job>.timeSubmitted
Remarks:
Returns the time at which the job was submitted as a string.
Prototype:
<job>.timeStarted
Remarks:
Returns the time at which the job was started as a string. Returns undefined if job hasn’t started.
Read-only
Prototype:
<job>.timeFinished
Remarks:
Returns the time at which the job was finished as a sting. Returns undefined if job hasn’t finished.
Read-only
Prototype:
<job>.notifications
Remarks:
Returns true if notifications are on. Can be changed
Prototype:
<job>.notifyFailure
Remarks:
Returns true if notified of failures. Can be changed
Prototype:
<job>.notifyProgress
Remarks:
Returns true if notified of progress. Can be changed
Prototype:
<job>.notifyCompletion
392 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Returns true if notified of progress is on. Can be changed
Prototype:
<job>.notifyFrameInterval
Remarks:
Returns an interval at which notifications occur. Can be changed
Prototype:
<job>.fromFrame
Remarks:
Returns the rendering start frame. Can be changed
Prototype:
<job>.toFrame
Remarks:
Returns the rendering end frame. Can be changed
Prototype:
<job>.nthFrame
Remarks:
Returns the rendering frame interval. Can be changed
Prototype:
<job>.outputWidth
Remarks:
Returns the width of the rendered frame. Can be changed
Prototype:
<job>.outputHeight
Remarks:
Returns the height of the rendered frame. Can be changed
Prototype:
<job>.numFramesComplete
Remarks:
The number of completed frames for the job. Read-only
Prototype:
<job>.priority
Remarks:
Returns the job priority.
 Working with jobs 393

Prototype:
<job>.videoPost
Remarks:
Returns true if there is a video post sequence. Read-only
Prototype:
<job>.nonconcurrentDriver
Remarks:
Returns true if the output cannot be rendered one frame at a time (like .MOV). Read-only
Prototype:
<job>.includeMaps
Remarks:
Returns true if the job was submitted with include maps on. Can be changed
Prototype:
<job>.uninterruptibleDriver
Remarks:
Returns true if the render can’t be resumed if it was interrupted or suspended. For an.AVI, you cannot
render half the file, then finish it later. You need to render the whole thing without interruption.
Read-only
Prototype:
<job>.skipRenderedFrames
Remarks:
Returns true if skip rendered frames was set to on when job was submitted. Can be changed
Prototype:
<job>.useAllServers
Remarks:
Returns true if use all servers was set to on when job was submitted. Can be changed
Prototype:
<job>.suspended
Remarks:
Returns true if the job is suspended. Read-only. To suspend the job use <job>.suspend()
Prototype:
<job>.finished
Remarks:
Returns true if the job is finished. Read-only
Prototype:
<job>.ignoreShare
394 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Returns true if the job was submitted with ignore share on. Can be changed
Prototype:
<job>.skipOutputTest
Remarks:
Returns true if the job was submitted with skip output test on. Can be changed
Prototype:
<job>.nonSeqFrames
Remarks:
Returns true if the job was submitted to render non sequential frames. Can be changed
Prototype:
<job>.combustionJob
Remarks:
Returns false if the job is a max job. Read-only
Prototype:
<job>.uncompressedFile
Remarks:
Returns false if the job file is compressed. Read-only
Prototype:
<job>.gammaCorrection
Remarks:
Returns true if the job was submitted with gamma correction on. Can be changed.
Prototype:
<job>.gammaValueIn
Remarks:
Returns a float value of the incomming gamma value. Can be changed.
Prototype:
<job>.gammaValueOut
Remarks:
Returns a float value of the outgoing gamma value. Can be changed.
Prototype:
<job>.renderPixelAspect
Remarks:
Returns a float value of the render pixel aspect ratio. Can be changed.
 Working with jobs 395

Prototype:
<job>.renderCamera
Remarks:
Returns a string with the name of the camera view being rendered. Will return an empty string if
view being rendered is an non camera view, ie perspective, front, user, etc…Can be changed. Use
<job>.getcameras() function to get a list of valid cameras in the scene to change to.
Prototype:
<job>.renderElements
Remarks:
Returns true if a job was submitted with the render elements active. Note that this will return true
even there aren’t any elements to be rendered. Can be changed.
Prototype:
<job>.numSceneObjects
Remarks:
Returns the number of objects in the scene as an integer. Read-only
Prototype:
<job>.numSceneFaces
Remarks:
Returns the number of faces in the scene as an integer. Read-only
Prototype:
<job>.numSceneLights
Remarks:
Returns the number of lights in the scene as an integer. Read-only
Prototype:
<job>.sceneStartTime
Remarks:
Returns the scene start time in frames, so if your scene is set to use MM:SS:Ticks, this will still return
a value in frames.
Prototype:
<job>.sceneEndTime
Remarks:
Returns the scene end time in frames.
Prototype:
<job>.videoColorCheck
Remarks:
Returns true if the job was submitted with videocolorcheck on. Can be changed.
396 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<job>.force2Sided
Remarks:
Returns true if the job was submitted with force 2 sided on. Can be changed.
Prototype:
<job>.renderHiddenObjects
Remarks:
Returns true if the job was submitted with render hidden objects on. Can be changed.
Prototype:
<job>.renderAtmosphericEffects
Remarks:
Returns true if the job was submitted with render render atmospheric effects on. Can be changed.
Prototype:
<job>.superBlack
Remarks:
Returns true if the job was submitted with superblack on. Can be changed.
Prototype:
<job>.serialNumbering
Remarks:
Returns true if nth serial numbering is on this property is accesible through the preferences \
rendering dialog.
Prototype:
<job>.ditherPaletted
Returns true if Dither Paletted was enabled when the job was submitted. Can be changed.
Prototype:
<job>.ditherTrueColor
Remarks:
Returns true if Dither True Color was enabled when the job was submitted. Can be changed.
Prototype:
<job>.renderFields
Remarks:
Returns true if Render Fields was enabled when the job was submitted. Can be changed.
Prototype:
<job>.renderDisplacements
Remarks:
Returns true if displacements was enabled when the job was submitted. Can be changed.
 Working with jobs 397

Prototype:
<job>.renderEffects
Remarks:
Returns true if render effects was enabled when the job was submitted. Can be changed.
Prototype:
<job>.fieldOrder
Remarks:
Returns either #odd or #even depending on what the field order was set to when job was submitted.
Can be changed.
Prototype:
<job>.numRenderElements
Remarks:
Returns the number of render elements in the scene. Read-only.
Prototype:
<job>.userName
Remarks:
Returns the name of the user, as a string, that submitted the job. Note that if a job is submitted
through the scripter using <job>.submit(), and the max file was last saved by another user on a
different computer, the username will be that of the other user. Read-only
Prototype:
<job>.computerName
Remarks:
Returns the name of the computer, as a string, that the job was submitted from. Note that if a job is
submitted through the scripter using <job>.submit(), and the max file was last saved by another
user on a different computer, the computername will be that of the computer on which the max file
was last saved. Read-only
Prototype:
<job>.managerShare
Remarks:
Returns the shared folder as a string where all jobs are stored on the manager.
Prototype:
<job>.frames
Remarks:
Returns a string of frames to render, ie “1,3,5-12”. Can be changed.
Prototype:
<job>.frameOutputName
398 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Returns the name and path of the output file. Can be changed
Prototype:
<job>.frameOutputGamma
Remarks:
Returns the output gamma of the rendered frames.
Prototype:
<job>.frameOutputDevice
Remarks:
Returns the device name if a device is specified at render time.
Prototype:
<job>.numFrames
Remarks:
Returns the total number of frames for the particular job

Working with servers

Various functions and properties can be used to access rendering servers. You can use the getservers()
function to retrieve an array of all servers managed by the manager. The servers can be filtered in
various ways to return an array based on the filter.
Note:
Do not to call GetJobs() or GetServers() very often, because these are VERY heavyweight
methods.
Prototype:
<netManager>.GetServers [filter:#idle | #busy | #absent | #suspended | #error |
#group | #job | #handle | #index] [key:<string> | <integer> | <job> ]
Remarks:
If used without a filter, GetServers() will return an array of all servers managed by the manager. If
there are no servers, the function will return an empty array.
filter:#idle
Returns an array of all idle servers
filter:#busy
Returns an array of all servers busy rendering a job
filter:#absent
Returns an array of all servers that are absent, ie that were connected to the
manager at one point but that are either down or the server service or serverapp is
not running on it.
filter:#suspended
Returns an array of all suspended servers
 Working with servers 399

filter:#error
Returns an array of all servers experiencing an error
filter:#group
Returns an array of servers in a group. Requires that the key option is used, the
key can be a group name as a string or a group number as an integer (1 based). An
empty array is returned if no groups are defined.
filter:#job
Returns an array of servers that are assigned to the specified job. Requires that the
key option be used, the key must be a job definition.
filter:#handle
Returns the server with a given handle (as an array with one item). Requires that
the key option be used, the key must be a server handle.
filter:#index
Returns the server at a given index in the server list (as an array with one item).
Requires that the key option be used, the key must be an integer (the index).
server = m.getservers()
Prototype:
<server>.GetUpdate()
Remarks:
Gets an update on the state of the server. Returns Ok if succesful.
Prototype:
<server>.SendUpdate()
Remarks:
Updates the server with new settings. Must have queuecontrol.
Prototype:
<server>.Delete()
Remarks:
Deletes the server from the manager. Must have queuecontrol.
Prototype:
<server>.ResetPerformance()
Remarks:
Resets the performance metric to 0.0. Must have queuecontrol and must do <server>.sendupdate()
to update the server.
Prototype:
<server>.netStatus
Remarks:
Netstatus
Prototype:
<server>.handle
400 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Returns the server’s handle. Read-only
Prototype:
<server>.state
Remarks:
Returns the state of the server, this can be #idle, #absent, #busy
Prototype:
<server>.name
Remarks:
Returns the name of the server. Read-only
Prototype:
<server>.totalFrames
Remarks:
Returns the total number of frames rendered by the server. Read-only
Prototype:
<server>.totalTime
Remarks:
Returns the total time that the server has been up. The value returned is in hours.
Prototype:
<server>.performance
Remarks:
Returns the performance index of the server. Read-only
Prototype:
<server>.AttendedPriority
Remarks:
Returns the priority, as an integer, of the server when the user is logged in.
0 = high priority, 1 = low priority, 2 = idle. Can be changed.
Prototype:
<server>.UnattendedPriority
 Working with groups 401

Remarks:
Returns the priority level, as an integer, of the server when the system is logged out.
0 = high priority, 1 = low priority, 2 = idle.
Note that this is only valid if running serversvc and the user is not logged in on the system. If
running serversvc and a user is logged in on the system then the attendedpriority values are in effect.
Can be changed
Prototype:
<server>.schedule
Remarks:
Returns an array of 7 bitarrays. Each bitarray is a day, each bit is an hour, each bit within that bit
array means that the server is available at that hour. A bit array of #{1, 3..5, 15..24} means that
the server is available from 12 midnight to 1am, from 3am to 5am and from 3pm to midnight.
Prototype:
<server>.jobHandle
Remarks:
Returns the handle ot the job it is working on. Will return a value of 0 if no job is being worked on
by that server.
Prototype:
<server>.jobFrameIndex
Remarks:
Returns the frame index of the job that the server is working on.
Prototype:
<server>.jobFrameTimeStarted
Remarks:
Returns the time at which the frame being rendered was started.

Working with groups

Prototype:
<netManager>.SizeofGroup <index>
Remarks:
Returns the number of servers in the nth group.
Prototype:
<netManager>.GetGroupName<index>
Remarks:
Returns the name of the nth group.
402 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<netManager>.CreateGroup <array> <string>
Remarks:
Creates a named group of servers. It takes 2 arguments: an array of servers and a string to define the
group name.
Prototype:
<netManager>.DeleteGroup <string>
Remarks:
Deletes a named group. Takes a string as an argument.

Netstatus
Both manager and servers have a netstatus property. All properties are Read-only.
system = m.netstatus
Prototype:
<system>.SpaceOnDisk <index>
Remarks:
Returns the amount of space in megs on a specified disk. The index is 1 based. Disks 1 and 2 are the
a: and b: drives.
Prototype:
<system>.numDroppedPackets
Remarks:
Returns the number of dropped packets.
Prototype:
<system>.numBad
Remarks:
Returns the number of bad packets.
Prototype:
<system>.numTCPRequests
Remarks:
Returns the number of TCP requests
Prototype:
<system>.numUDPRequests
Remarks:
Returns the number of UDP packets
Prototype:
<system>.bootTime
 Netstatus 403

Remarks:
Returns the time at which the system was started.
Prototype:
<system>.memorySize
Remarks:
Returns the amount of memory of the system.
Prototype:
<system>.numProcessors
Remarks:
Returns the number of processors in system machine
Prototype:
<system>.platformID
Remarks:
Returns an integer, a value of 1 indicates win95, a value of 2 indicates WinNT
Prototype:
<system>.majorVersion
Remarks:
Returns an integer. When the platformID indicates a WinNT system, a value of 5 or higher here
indicates Win2k.
Prototype:
<system>.minorVersion
Remarks:
Returns an integer. Win98 is indicated by a minor build greater than 0 for win95
Prototype:
<system>.buildNumber
Remarks:
Returns the build number, this only applies to winnt and win2k. Not supported under win95, win98
or win ME.
Prototype:
<system>.CSDVersion
Remarks:
Returns the service pack number of the OS as a string.
Prototype:
<system>.username
404 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Returns the login name of the user logged in on the computer or the login name used by the service.
Prototype:
<system>.tempDir
Remarks:
Returns the tempdir for the system.
Prototype:
<system>.computerName
Remarks:
Returns the name of the computer.
Prototype:
<system>.workdisk
Remarks:
Returns the disk where max is setup.
Prototype:
<system>.Disks
Remarks:
Returns a bitarray of which disks exist (1=A, 2=B, 3=C etc.)
Prototype:
<system>.mac
Remarks:
Returns the MAC address of the system’s network card. If the computer is a network server, this is its
handle.

Examples:
-- ESTABLISHING A CONNECTION --
m = netrender.getmanager()--get a NetManager instance
--start this session
m.connect #manual “nimbus”
-- OR m.connect #manual “nimbus” port:1234--specifying a port number
-- QUEUE CONTROL --
--Get QueueControl using GetControl();
--there is no way to release control, but if wantControl==false
--then control will be relinquished to the next client
--that requests it
if( m.QueryControl #wait ) do --only take control if you have permission
m.getcontrol() --takes queue control
m.wantControl=true--if another client does QueryControl(), they will get a return
value of false
m.Lock true--this completely prevents others from getting queue control
 Examples: 405

m.Lock false--others can now get control

-- SUBMITTING JOBS --
job = m.newjob file:”c:\\share\\test.max”
job.suspended = true--jobs can be submitted as suspended
job.state--should be unsubmitted
job.includeMaps = true --turn on “Include Maps”

srv_list = m.getservers() --get the server list to assign to the job

job.submit servers:srv_list --specify which servers to use for the job
-- job.submit() --this uses all servers for the job
-- GETTING JOBS & SERVER OBJECTS --
m.SetUpdates false--lock the queue, to make sure nothing changes while you download
info
j = m.getjobs filter:#suspended--an array of NetJob objects; filters are optinal
s = m.getservers filter:#idle--an array of NetServer objects; filters are optinal
--see below for other filters... there are many
m.SetUpdates true--be sure to unlock the queue!
-- WORKING WITH GROUPS --
m.creategroup s “myGroup”--takes an array of NetServers and a name
num_groups = m.numGroups--total number of groups
size_group1 = m.SizeofGroup 1--number of servers in the first group
g = m.getservers filter:#group key:1 --an array of the servers for group 1
g = m.getservers filter:#group key:”myGroup”--an array of the servers for group
“myGroup”
g_name = m.GetGroupName 1--the name of the first group
m.deletegroup g_name--delete a group
-- WORKING WITH JOBS --
job = j[1]--pull a job out of the list
jHandle = job.handle--the job’s ID
p = job.priority--job’s priority
if job.nonSeqFrames==TRUE then
frames = job.frames--one of those “1,3,5-12” frame lists
else
frames = (job.fromFrame as string) + “-” + (job.toFrame as string)
--now frames is “0-100” if 0 and 100 are the start/end frames
cameraArray = job.GetCameras()--an array of the camera names
l = job.GetLog--the entire log, as text
l = job.GetLog start:4 numLines:2 --gets the 4th and 5th entries of the log
statText = job.GetServerStatusText s[1] --text about a server, regarding this job
num_workers = job.numServers--number of servers on this job
job.frameOutputName = “d:\\blah.bmp”--change the output name
isDevice = job.frameOutputDevice--true if the output is to a device, false
otherwise
share = job.managerShare--the manager share for this job
job.filesize--size of the MAZ file for the job
job.filesizeextracted--extracted sisze of the MAZ file for the job
-- WORKING WITH SERVERS --
srv = s[1]--pull a server out of the list
sHandle = srv.Handle--the server’s ID
sName = srv.name--the server’s machine name
speed = srv.performance--server’s performance index
406 Chapter 1 | What’s New in 3ds max 4 MAXScript

srv.ResetPerformance()--reset the index

timeUsed = srv.totalTime--total time spent rendering
sjHandle = srv.jobHandle--the handle of the server’s current job, 0 if none
sjFrameIndex = srv.jobFrameIndex--the index of the frame the server is rendering
--PRACTICAL EXAMPLE; get info about the frame being rendered
sjHandle = srv.jobHandle
sjIndex = srv.jobFrameIndex
sJobs = m.getJobs filter:job key:sjHandle--should be an array with one entry
frameInfo = (sJobs[1].getFrameInfo sjIndex)--get info about the current frame
frameTime = frameInfo.elapsedTime
-- UPDATES FROM MANAGER --
--Jobs and Servers support GetUpdate and SendUpdate functions,
-- for synchronizing with the manager
job.status--should be busy
job.Suspend()
job.status--still says busy (status value is stale)
job.GetUpdate()--download the latest news
job.status--now says suspended
s[1].GetUpdate()--servers also have Get/SendUpdate
-- CALLBACKS --
-- These are used to listen for messages from the manager,
-- They are functions you can define, that will get called when
-- the manager has something to say
-- There are 6 possible callbacks
-- NOTE: you can name these functions anything you want, but they must have correct
paramters
--NETPROGRESS CALLBACK; Called anytime a download/upload is underway,
-- including anytime you fetch information about jobs or servers
fn myNetProgress total current =--NOTE: two integer parameters
format “Progress: completed % out of %\n” current total
--NETMESSAGE CALLBACK; Called when the manager has a text message for the user
fn myNetMessage msg =--NOTE: one string parameter
format “Message: %\n” msg
--UPDATE CALLBACK; Called when something has changed, like a job started or
finished
-- Let’s you know when you need to make GetUpdate calls, or other refreshing
fn myUpdate =
job.GetUpdate()--example of what you might do
--MANAGERDOWN CALLBACK; Called when the manager dies
fn myManagerDown =
format “Manager is dead\n”

--QUEUECONTROL CALLBACK; Called whenever queue control changes

fn myQueueControl =
format “Queue control has changed\n”

--QUERYCONTROL CALLBACK; Called when you have Queue Control, and another computer
wants it
fn myQueryControl clientName = (--NOTE: one string parameter
format “The computer % wants queue control” clientName
m.wantControl = true-- use this to keep queue control
 Examples: 407

m.wantControl = false-- use this to release queue control

)
--INSTALLING THE CALLBACKS; after you define the functions, you must give them to
the
-- manager as follows
--NOTE: only one callback of each type is allowed (e.g., you can’t have two
“Update” callbacks)
m.setcallback #Progress myNetProgress--install the “Progress” callback
m.setcallback #MessagemyNetMessage --install the “Message” callback
m.setcallback #UpdatemyUpdate--install the “Update” callback
m.setcallback #ManagerDown myManagerDown --install the “ManagerDown” callback
m.setcallback #QueueControl myQueueControl --install the “QueueControl” callback
m.setcallback #QueryControl myQueryControl --install the “QueryControl” callback
-- NETSTATUS OBJECTS --
--Read-only information about a computer on the network
stat = s[1].netStatus--get network info about server 1
stat.boottime--make a query
stat.Disks--
d = stat.workDisk--which is the disk for net-rendering work?
stat.SpaceOnDisk d--megabytes of free space on the workdisk
stat.memorySize--computer’s memory in bytes (note: 1 meg = 1048576 bytes)
s[1].GetUpdate()--this refreshes the netStatus object
stat = m.netStatus--manager also has a NetStatus
--NOTE: Manager has no GetUpdate(), you must fetch the NetStatus again to see any
changes
--To print out the operating system on the machine...
--Win95 has a platformID of 1; WinNT has a platformID of 2
--Win2K is indicated by a majorBuild of 5 or more for WinNT
--Win98 is indicated by a minorBuild greater than 0 for Win95.
--Also, build number and the CSDVersion string are not supported by Win95/98
format “Windows %.%, Build %, %\n” \
stat.majorVersion stat.minorVersion stat.buildNumber stat.CSDVersion
-- JOBFRAME OBJECTS --
num_frames = job.numFrames()
frame = job.getFrameInfo 1 --get info about the 1st frame
elapsed_time = frame.ElapsedTime --amount of time frame has been rendering
num_rendElems = job.numRenderElements()--number of render elements for render
if num_rendElems>0 do (
rendElem = job.GetRenderElement 1--pass the index of the element
rendElem.enabled = false--turn off the rend element
job.SetRenderElement 1 rendElem--update the job with the new changes
job.SendUpdate()--upload the changes
)
-- JOBSERVER OBJECTS --
--Read-only information about a server, in relation to a particular job
j_num_servers = j[1].numServers--how many servers does the job have?
js = j[1].GetServerInfo 1--info about the job’s first server
sh = js.serverHandle--what’s the server’s handle?
sn = js.serverName--what’s the server’s name?
isWorker = js.active--whether this server participates in this job
js_state = js.state--is the server busy with the job? has an error? etc
408 Chapter 1 | What’s New in 3ds max 4 MAXScript

--Print out some stats

format “rendering frame %, completed %, total time % hours\n” \
js.currentFrame js.numFramesComplete js.elapsedTime
--ways to get more info about this server...
jSrv = m.GetServers filter:#handle key:sh--get the actual server object
statText = j[1].GetServerStatusText jSrv[1]--text info from the server about this
job

-- RENDERELEMENT OBJECTS --
--Information about particular render elements for a job
n = j[1].numRenderElements--how many render elements for this job?
re = j[1].GetRenderElement 1--get the first one
re.enabled = false--disable it
re.filterEnabled = false--disable filtering
re.name = “newName”--change its name
useShadows = re.shadowsApplied--are shadows applied? (read-only)
useShadows = re.atmosphereApplied--are atmospherics applied (read-only)
re.output = “C:\\share\\rendElem1.bmp”--change its output path & name
j[1].SetRenderElement 1 re--update the job with the new changes
j[1].SendUpdate--upload the changes
-- WEEKLY SCHEDULES --
-- a servers’ weekly schedule is an array of seven BitArrays;
-- Each bitArray is a day, each bit is an hour
sched = s[1].schedule
sched[1][11] = false--sunday 11am, the server will not work
sched[1][12] = false -- same for sunday noon
s[1].attendedPriority = 60--set the priorities for the server’s schedule
s[1].unattendedPriority = 10
s[1].schedule = sched--set the new schedule
s[1].schedule --printout to prove the change worked
s[1].SendUpdate()--upload the changes to this server
--NOTE: a Schedule is just a BitArray and has no GetUpdate,
--you must fetch it again from the server to see any changes
-- MISCELANEOUS FUNCTIONS --
jobList = #( j[3], j[1], j[2] )--make an array of some jobs
m.SetJobOrder jobList--rearrange the jobs; e.g. j[3] is now the first in the queue
mName = (m.netStatus).computerName --the machine name of the manager
-- JOB & SERVER FILTERS --
jobServers = m.getservers filter:#Job key:j[1]
groupServers = m.getservers filter:#group key:”Clouds”
-- ENDING THE SEESION --
m.wantControl=true--other clients can now get QueueControl
m.disconnect()--end this session
-- m.kill()--brings down the manager, (would need queue control)
 Interface: NullInterface 409

Interface: NullInterface
Interface: NullInterface
Note:
Intentionally blank.

Interface: objXRefs
Interface: objXRefs
Methods:
Prototype:
<maxObject>addNewXRefObject <filename>fname <string>objname <boolean>proxy
Parameters:
<filename>fname
<string>objname
<boolean>proxy
Prototype:
<integer>getNumXRefObjects <filename>fname
Parameters:
<filename>fname
Prototype:
<maxObject>getXRefObject <filename>fname <index>index
Parameters:
<filename>fname
<index>index
Prototype:
<integer>getNumFiles()
Prototype:
<filename>getFileName <index>index
Parameters:
<index>index
Prototype:
<boolean>reloadFile <filename>fname
Parameters:
<filename>fname
Return Value:
True if successful and false otherwise.
Prototype:
<boolean>isFileUnresolved <filename>fname
410 Chapter 1 | What’s New in 3ds max 4 MAXScript

Parameters:
<filename>fname
Return Value:
True if successful and false otherwise.
Prototype:
<boolean>isFileDisabled <filename>fname
Parameters:
<filename>fname
Return Value:
True if successful and false otherwise.

See Also
XRefObject : Node (p. 1037)
XRefScene Values (p. 1038)
XRef Files (p. 1643)

Interface: paramWire
Parameter Wiring (p. 85)
This class represents the interface that provides general access to the parameter wiring functions.
Prototype:
<void>start()
Remarks:
This method will launch the parameter wiring UI mode on the currently selected object. Only works
if there is a single object selected in the viewport. It will move the cursor to the pivot point of the
node.
Example:
It might be used in a macroScript like this:
macroScript paramWire
category:”Tools”
buttonText:”Wire Parameters”
tooltip:”Start Param Wiring”
Icon:#(”MAXScript”,1)
(
on execute do paramWire.start()
on isEnabled return selection.count == 1
)

Prototype:
<void>openEditor()
 Interface: paramWire 411

Remarks:
This method will open up the parameter wiring dialog on the selected objects with no track selected
in either tree view.
Prototype:
<void>editParams <value>leftParam <value>rightParam
Remarks:
Opens the parameter wiring editor dialog on the parameters specified. The parameter is specified as
a SubAnim in MAXScript, via the index [] operator on a MAX object.
Parameters:
<value>leftParam
The sub-animatable of the left-hand reference target.
<value>rightParam
The sub-animatable of the right-hand reference target.
Note:
The subanim index operator can also take number indexes.
Prototype:
<void>editParam <value>param
Remarks:
Opens the parameter wiring editor dialog on the parameter specified. The parameter is specified as
a SubAnim in MAXScript, via the index [] operator on a MAX object.
Parameters:
<value>param
The sub-animatable of the left-hand reference target.
Example:
-- The radius parameter in a sphere node
paramWire.editParam $sphere01.baseObject[#radius]
-- The angle parameter in a bend modifier would be
paramWire.editParam $foo.bend[#angle]
-- The position parameter in node would be
paramWire.editParam $foo[#transform][#position], etc.
Prototype:
<void>editControllers <control>leftController <control>rightController
Remarks:
Opens the parameter wiring editor dialog on the two given existing wire controllers.
Parameters:
<control>leftController
A pointer to the controller for the left-hand wire.
<control>rightController
A pointer to the controller for the right-hand wire.
412 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<void>editController <control>controller
Remarks:
Opens the parameter wiring editor dialog on the given existing wire controller.
Parameters:
<control>controller
A pointer to the controller being edited.
Example:
paramWire.editController $foo.radius.controller
Prototype:
<bool>connect <value>fromParam <value>toParam <string>toExpr
Remarks:
This method allows you to set up a one-way parameter wire from the ‘fromParam’ subAnim to the
‘toParam’ subAnim, using the ‘toExpr’ as the expression for the controlled parameter.
Parameters:
<value>fromParam
The sub-animatable to wire from.
<value>toParam
The sub-animatable to wire to.
<string>toExpr
A string containing the expression on the “to wire”.
Return Value:
TRUE if the connection can be made, otherwise FALSE.
Example:
paramWire.connect $foo.baseObject[#radius] $baz.bend[#angle] “radius / 2”
Prototype:
<bool>connect2Way <value>leftParam <value>rightParam <string>leftExpr
<string>rightExpr
Remarks:
This method allows you to set up a two-way parameter wire between the ‘leftParam’ parameter and
the ‘rightParam’ parameter, with the given expression strings.
Parameters:
<value>leftParam
The sub-animatable of the left-hand reference target.
<value>rightParam
The sub-animatable of the right-hand reference target.
 Interface: paramWire 413

<string>leftExpr
A string containing the expression for the left-hand target.
<string>rightExpr
A string containing the expression for the right-hand target.
Return Value:
TRUE if the connection can be made, otherwise FALSE.
Example:
paramWire.connect2Way $foo.baseObject[#radius] $baz.bend[#angle] \ “angle / 2”
“radius * 2”
Prototype:
<bool>disconnect <control>controller
Remarks:
This method allows you to disconnect a one-way wireController from its current parameter,
replacing it with either the wire’s existing animation track or a default controller for the parameter.
Parameters:
<control>controller
A pointer to the wire controller you wish to disconnect.
Return Value:
TRUE if the disconnect was successful, otherwise FALSE.
Prototype:
<bool>disconnect2Way <control>leftController <control>rightController
Remarks:
This method allows you to disconnect a two-way wire between ‘leftcontroller’ and ‘rightController’.
If this is the last two-way wire for either controller, replace it with either the the wire’s existing
animation track or a default controller for the parameter.
Parameters:
<control>leftController
A pointer to the first wire controller you wish to disconnect.
<control>rightController
A pointer to the second wire controller you wish to disconnect.
Return Value:
TRUE if the disconnect was successful, otherwise FALSE.

See Also
In The MAXSDK Help File
Class IParamWireMgr
414 Chapter 1 | What’s New in 3ds max 4 MAXScript

Interface: pluginManager
Interface: pluginManager
Properties:
.visible : boolean : Read|Write
Remarks:
Show and hide the plug-in manager.
Methods:
<void>loadClass <class>class
Remarks:
Will ensure that the given class is loaded, in the event that it is a deferred loading class, and so any
MAXScript methods or Function Published interfaces it publishes will be available.
Parameters:
<class>class
Example:
plug-inManager.loadClass Flex

After this code is executed, all the Flex modifier MAXScript methods are installed and callable.
Note this is only needed in situations where a plug-in loading may be deferred and it does not
have any instances already in the current scene.

See Also
Interface: pluginManager (p. 414)
Plugin_Manager interfaces: (p. 473)

Interface: quadMenuSettings
This represents an interface for quad menu settings.
Note:
PickObject() does not pick objects when launched from a Quad Menu. It will hang and refuses to
pick any object. Hit ‘escape’ for emergency exit. PickObject works correctly from a shortcut and
toolbar.
Prototype:
<void>ResetDefaults()
Remarks:
This method will reset the menu settings to their defaults.
Prototype:
<void>SetBorderSize <integer>borderSize
 Interface: quadMenuSettings 415

Remarks:
This method allows you to set the menu border size.
Parameters:
<integer>borderSize
The border size in pixels.
Prototype:
<integer>GetBorderSize()
Return Value:
This method returns the menu border size.
Prototype:
<void>SetHorizontalMarginInPoints <integer>horizontalMarginInPoints
Remarks:
This method allows you to set the menu’s horizontal margin size.
Parameters:
<integer>horizontalMarginInPoints
The horizontal margin size in points.
Prototype:
<integer>GetHorizontalMarginInPoints()
Return Value:
This method returns the menu’s horizontal margin size (in points).
Prototype:
<void>SetVerticalMarginInPoints <integer>verticalMarginInPoints
Remarks:
This method allows you to set the menu’s vertical margin size.
Parameters:
<integer>verticalMarginInPoints
The vertical margin size in points.
Prototype:
<integer>GetVerticalMarginInPoints()
Return Value:
This method returns the menu’s vertical margin size (in points).
Prototype:
<void>SetItemFontFace <string>szItemFontFace
Remarks:
This method allows you to set the menu item’s font typeface.
416 Chapter 1 | What’s New in 3ds max 4 MAXScript

Parameters:
<string>szItemFontFace
A string containing the typeface name.
Prototype:
<string>GetItemFontFace()
Return Value:
This method returns the name of the menu item’s font typeface.
Prototype:
<void>SetTitleFontFace <string>szTitleFontFace
Remarks:
This method allows you to set the menu title’s font typeface.
Parameters:
<string>szTitleFontFace
A string containing the typeface name.
Prototype:
<string>GetTitleFontFace()
Return Value:
This method returns the name of the menu title’s font typeface.
Prototype:
<void>SetItemFontSize <integer>itemFontSize
Remarks:
This method allows you to set the menu item’s font size.
Parameters:
<integer>itemFontSize
The size of the font, in points.
Prototype:
<integer>GetItemFontSize()
Return Value:
This method returns the menu item’s font size, in points.
Prototype:
<void>SetTitleFontSize <integer>titleFontSize
Remarks:
This method allows you to set the menu title’s font size.
Parameters:
<integer>titleFontSize
The size of the font, in points.
 Interface: quadMenuSettings 417

Prototype:
<integer>GetTitleFontSize()
Return Value:
This method returns the menu title’s font size, in points.
Prototype:
<void>SetUseUniformItemHeight <boolean>useUniformItemHeight
Remarks:
This method allows you to set the status of a menu item’s uniform height flag.
Parameters:
<boolean>useUniformItemHeight
TRUE to set the uniform height flag ON, FALSE to set it to OFF.
Prototype:
<boolean>GetUseUniformItemHeight()
Return Value:
This method returns TRUE or FALSE if the menu item’s uniform height flag is set or not set,
respectively.
Prototype:
<void>SetOpacity <float>opacity
Remarks:
This method allows you to set the menu’s opacity value.
Parameters:
<float>opacity
The opacity value, ranging from 0.0 – 1.0 where 1 is opaque.
Prototype:
<float>GetOpacity()
Return Value:
This method returns the menu’s opacity value.
Prototype:
<void>SetDisplayMethod <integer>displayMethod
Remarks:
This method allows you to set a menu’s display method.
Parameters:
<integer>displayMethod
The display method which is one of the following:
0 - displays the menu with transparency, if opacity is < 1.
1 - stretch animate the menu by making it grow in size from its center
with transparency, if opacity is < 1.
2 - fade in from invisible to whatever opacity is set to.
418 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<integer>GetDisplayMethod()
Return Value:
This method returns the menu’s display method, which is either of the following; DM_NORMAL,
DM_STRETCH, DM_FADE, DM_NUM_METHODS
Prototype:
<void>SetAnimatedSteps <integer>animatedSteps
Remarks:
This method allows you to set the menu’s number of animated steps for the ‘growing’ effect.
Parameters:
<integer>animatedSteps
The number of steps.
Prototype:
<integer>GetAnimatedSteps()
Return Value:
This method returns the menu’s number of animated steps used for the ‘growing’ effect.
Prototype:
<void>SetAnimatedStepTime <integer>animatedStepTime
Remarks:
This method allows you to set the menu’s animated step time.
Parameters:
<integer>animatedStepTime
The animated step time, in milliseconds.
Prototype:
<integer>GetAnimatedStepTime()
Return Value:
This method returns the menu’s animated step time, in milliseconds.
Prototype:
<void>SetSubMenuPauseTime <integer>subMenuPauseTime
Remarks:
This method allows you to set the delay before a submenu is displayed.
Parameters:
<integer>subMenuPauseTime
The delay, in milliseconds.
Prototype:
<integer>GetSubMenuPauseTime()
 Interface: quadMenuSettings 419

Return Value:
This method returns the delay before a submenu is displayed, in milliseconds.
Prototype:
<void>SetUseLastExecutedItem <boolean>useLastSelectedItem
Remarks:
This method allows you to set the “last executed item” flag which determines whether to use the
menu’s last executed item when the user clicks on the menu’s titlebar.
Parameters:
<boolean>useLastSelectedItem
Prototype:
<boolean>GetUseLastExecutedItem()
Return Value:
This method returns whether the “last executed item” flag is set (TRUE) or not set (FALSE). The flag
determines whether to use the menu’s last executed item when the user clicks on the menu’s titlebar.
Prototype:
<void>SetRepositionWhenClipped <boolean>repositionWhenClipped
Remarks:
This method allows you to set the flag which controls and determines whether the menu is
repositioned when near the edge of the screen.
Parameters:
<boolean>repositionWhenClipped
TRUE to turn repositioning ON, FALSE to turn it OFF.
Prototype:
<integer>GetRepositionWhenClipped()
Remarks:
This method returns the status of the flag which controls and determines whether the menu is
repositioned when near the edge of the screen.
Return Value:
TRUE if the flag is ON, otherwise FALSE.
Prototype:
<void>SetRemoveRedundantSeparators <boolean>removeRedundantSeparators
Remarks:
This method allows you to set the flag which controls and determines whether the menu should
remove redundant separators.
Parameters:
<boolean>removeRedundantSeparators
TRUE to turn the flag ON, FALSE to turn it OFF.
420 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<integer>GetRemoveRedundantSeparators()
Remarks:
This method returns the status of the flag which controls and determines whether the menu should
remove redundant separators.
Return Value:
TRUE if the flag is ON, otherwise FALSE.
Prototype:
<void>SetFirstQuadDisplayed <integer>firstQuadDisplayed
Remarks:
This method allows you to set the first quad which will be displayed when a quad menu pops up.
Parameters:
<integer>firstQuadDisplayed
The quad index, one of the following; QUAD_ONE, QUAD_TWO, QUAD_THREE, or
QUAD_FOUR.
Prototype:
<integer>GetFirstQuadDisplayed()
Remarks:
This method returns the index of the first quad which will be displayed.
Return Value:
The quad index, one of the following; QUAD_ONE, QUAD_TWO, QUAD_THREE, or QUAD_FOUR.
Prototype:
<void>SetUseUniformQuadWidth <boolean>useUniformQuadWidth
Remarks:
This method allows you to set whether the quad menu has a uniform width.
Parameters:
<boolean>useUniformQuadWidth
TRUE to set the uniform width, FALSE to set it to non-uniform.
Prototype:
<boolean>GetUseUniformQuadWidth()
Return Value:
This method returns the status of the uniform width flag for the quad menu. TRUE if the quad menu
has been set to use uniform width, otherwise FALSE.
Prototype:
<void>SetMirrorQuad <boolean>mirrorQuad
Remarks:
This method allows you to set whether the quad menus are mirrored left to right.
 Interface: quadMenuSettings 421

Parameters:
<boolean>mirrorQuad
TRUE to mirror the menus, otherwise FALSE.
Prototype:
<integer>GetMirrorQuad()
Return Value:
This method returns TRUE if the quad menu is mirrored left to right, otherwise FALSE.
Prototype:
<void>SetMoveCursorOnReposition <boolean>moveCursorOnReposition
Remarks:
This method allows you to set whether the cursor moves when the quad menu is repositioned
because of clipping the edge of the screen.
Parameters:
<boolean>moveCursorOnReposition
TRUE to move the cursor, otherwise FALSE.
Prototype:
<boolean>GetMoveCursorOnReposition()
Return Value:
This method returns TRUE if the cursor moves when the quad menu is repositioned because of
clipping the edge of the screen, otherwise FALSE.
Prototype:
<void>SetReturnCursorAfterReposition <boolean>returnCursorAfterReposition
Remarks:
This method allows you to set whether the cursor is moved the opposite distance that it was
automatically moved when the quad menu is repositioned because of clipping the edge of the
screen.
Parameters:
<boolean>returnCursorAfterReposition
TRUE to set the flag, otherwise FALSE.
Prototype:
<boolean>GetReturnCursorAfterReposition()
Return Value:
This method returns TRUE if the cursor is moved the opposite distance that it was automatically
moved when the quad menu is repositioned because of clipping the edge of the screen, otherwise
FALSE.
Prototype:
<void>SetInitialCursorLocInBox_0to1 <float>initialCursorLocX
<float>initialCursorLocY
422 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method allows you to set the initial location of the cursor in the center quad box.
Parameters:
<float>initialCursorLocX
<float>initialCursorLocY
The location of the cursor, as a ratio of the box size, between 0.0 and 1.0.
Prototype:
<float>GetInitialCursorLocXInBox_0to1()
Return Value:
This method returns the initial x location of the cursor in the center quad box, as a ratio of the box
size, between 0.0 and 1.0.
Prototype:
<float>GetInitialCursorLocYInBox_0to1()
Return Value:
This method returns the initial y location of the cursor in the center quad box, as a ratio of the box
size, between 0.0 and 1.0.
Prototype:
<void>SetTitleBarBackgroundColor <integer>quad <&RGBA color>color
Remarks:
This method allows you to set the title bar background color for a specific quad.
color is In parameter
Parameters:
<integer>quad
The quad (numbered 1 through 4).
<&RGBA color>color
The color to set.
Prototype:
<&RGBA color>GetTitleBarBackgroundColor <integer>quad
Parameters:
<integer>quad
The quad (numbered 1 through 4).
Return Value:
This method returns the title bar background color of a specific quad. This method returns the color
as a Color.
Prototype:
<void>SetTitleBarTextColor <integer>quad <&RGBA color>color
 Interface: quadMenuSettings 423

Remarks:
This method allows you to set the title bar text color for a specific quad.
color is In parameter
Parameters:
<integer>quad
The quad (numbered 1 through 4).
<&RGBA color>color
The color to set.
Prototype:
<&RGBA color>GetTitleBarTextColor <integer>quad
Parameters:
<integer>quad
The quad (numbered 1 through 4).
Return Value:
This method returns the title bar text color of a specific quad. This method returns the color as a
Color
Prototype:
<void>SetItemBackgroundColor <integer>quad <&RGBA color>color
Remarks:
This method allows you to set the item background color for a specific quad.
color is In parameter
Parameters:
<integer>quad
The quad (numbered 1 through 4).
<&RGBA color>color
The color to set.
Prototype:
<&RGBA color>GetItemBackgroundColor <integer>quad
Parameters:
<integer>quad
The quad (numbered 1 through 4).
Return Value:
This method returns the item background color of a specific quad. This method returns the color as
a Color.
Prototype:
<void>SetItemTextColor <integer>quad <&RGBA color>color
424 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method allows you to set the item text color for a specific quad.
color is In parameter
Parameters:
<integer>quad
The quad (numbered 1 through 4).
<&RGBA color>color
The color to set.
Prototype:
<&RGBA color>GetItemTextColor <integer>quad
Parameters:
<integer>quad
The quad (numbered 1 through 4).
Return Value:
This method returns the item text color of a specific quad. This method returns the color as a Color.
Prototype:
<void>SetLastExecutedItemTextColor <integer>quad <&RGBA color>color
Remarks:
This method allows you to set the last executed item text color for a specific quad.
color is In parameter
Parameters:
<integer>quad
The quad (numbered 1 through 4).
<&RGBA color>color
The color to set.
Prototype:
<&RGBA color>GetLastExecutedItemTextColor <integer>quad
Parameters:
<integer>quad
The quad (numbered 1 through 4).
Return Value:
This method returns the last executed item text color of a specific quad. This method returns the
color as a Color.
Prototype:
<void>SetHighlightedItemBackgroundColor <integer>quad <&RGBA color>color
Remarks:
This method allows you to set the highlighted item background color for a specific quad.
Color is In parameter.
 Interface: quadMenuSettings 425

Parameters:
<integer>quad
The quad (numbered 1 through 4).
<&RGBA color>color
The color to set.
Prototype:
<&RGBA color>GetHighlightedItemBackgroundColor <integer>quad
Parameters:
<integer>quad
The quad (numbered 1 through 4).
Return Value:
This method returns the highlighted item background color of a specific quad. This method returns
the color as a Color.
Prototype:
<void>SetHighlightedItemTextColor <integer>quad <&RGBA color>color
Remarks:
This method allows you to set the highlighted item text color for a specific quad.
color is In parameter
Parameters:
<integer>quad
The quad (numbered 1 through 4).
<&RGBA color>color
The color to set.
Prototype:
<&RGBA color>GetHighlightedItemTextColor <integer>quad
Parameters:
<integer>quad
The quad (numbered 1 through 4).
Return Value:
This method returns the highlighted item text color of a specific quad. This method returns the color
as a Color.
Prototype:
<void>SetBorderColor <integer>quad <&RGBA color>color
Remarks:
This method allows you to set the border color for a specific quad.
color is In parameter
426 Chapter 1 | What’s New in 3ds max 4 MAXScript

Parameters:
<integer>quad
The quad (numbered 1 through 4).
<&RGBA color>color
The color to set.
Prototype:
<&RGBA color>GetBorderColor <integer>quad
Parameters:
<integer>quad
The quad (numbered 1 through 4).
Return Value:
This method returns the border color of a specific quad. This method returns the color as a Color.
Prototype:
<void>SetDisabledShadowColor <integer>quad <&RGBA color>color
Remarks:
This method allows you to set the disabled shadow color for a specific quad.
color is In parameter
Parameters:
<integer>quad
The quad (numbered 1 through 4).
<&RGBA color>color
The color to set.
Prototype:
<&RGBA color>GetDisabledShadowColor <integer>quad
Parameters:
<integer>quad
The quad (numbered 1 through 4).
Return Value:
This method returns the disabled shadow color of a specific quad. This method returns the color as
a Color.
Prototype:
<void>SetDisabledHighlightColor <integer>quad <&RGBA color>color
 Interface: rollup 427

Remarks:
This method allows you to set the disabled highlight color for a specific quad.
color is In parameter
Parameters:
<integer>quad
The quad (numbered 1 through 4).
<&RGBA color>color
The color to set.
Prototype:
<&RGBA color>GetDisabledHighlightColor <integer>quad
Parameters:
<integer>quad
The quad (numbered 1 through 4).
Return Value:
This method returns the disabled highlight color of a specific quad. This method returns the color
as a Color.

See Also
In The MAXSDK Help File
Class IMenuSettings

See Also
Menu Manager (p. 75)
Interface: menuMan (p. 372)

Interface: rollup
Interface: rollup
Note:
Intentionally blank.

Interface: SceneExposureControl
Interface: SceneExposureControl
Properties:
.exposureControl : maxObject : Read|Write|Validated by
428 Chapter 1 | What’s New in 3ds max 4 MAXScript

Interface: SceneRadiosity
Interface: SceneRadiosity
Properties:
.radiosity : maxObject : Read|Write|Validated by
Methods:
Prototype:
<void>showPanel()
Remarks:
The radiosity panel is disabled from the scriptor when there are no radiosity plugins registered. In
this case the SceneRadiosity.showPanel() function published method doesn’t do anything.
Prototype:
<void>closePanel()
Prototype:
<void>minimizePanel()

Interface: timeSlider
This represents the interface for the time slider.
Methods:
Prototype:
<void>setVisible <boolean>visible
Remarks:
This method allows you to set the visibility flags of the time slider.
This Setting is sticky across sessions and will be stored in the ini file.
Parameters:
<boolean>visible
TRUE to set the time slider visible, otherwise FALSE.
Prototype:
<boolean>isVisible()
Return Value:
This method returns TRUE if the time slider is visible, otherwise FALSE.

See Also
In The MAXSDK Help File
Class ITimeSlider
 Interface: trackviews 429

Interface: trackviews
Interface: trackviews
Properties:
.currentTrackView : Interface : Read
.lastUsedTrackViewName : string : Read
Methods:
Prototype:
<Interface>getTrackView <fpvalue>name or index
Parameters:
<fpvalue>name or index
Return Value:
This method will get a trackview based on it’s index or name.
Prototype:
<Interface by value array>getAllOpenTrackViews()
Return Value:
Returns an array of trackviews.
Prototype:
<integer>numTrackViews()
Return Value:
Returns the number of trackviews.
Prototype:
<boolean>open <fpvalue>name or index
Parameters:
<fpvalue>name or index
Return Value:
Open a trackview based on it’s index or name.
Prototype:
<boolean>close <fpvalue>name or index
Parameters:
<fpvalue>name or index
Return Value:
Close a trackview based on it’s index or name.
Prototype:
<void>delete <fpvalue>name or index
430 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Parameters:
<fpvalue>name or index
Prototype:
<string>getTrackViewName <index>index
Parameters:
<index>index
Return Value:
Returns the name of the trackview window based on the index.
Prototype:
<boolean>zoomSelected <TSTR>name
Parameters:
<TSTR>name
Return Value:
Zooms to the selected object’s track
Prototype:
<boolean>zoomOn <TSTR>name <maxObject>object <index>subNum
Parameters:
<TSTR>name
<maxObject>object <index>subNum
Return Value:
True if successful and false otherwise.
Prototype:
<boolean>setFilter()
Remarks:
setFilter has variable number of arguments
Return Value:
True if successful and false otherwise.
Prototype:
<boolean>clearFilter()
Remarks:
clearFilter has variable number of arguments
Return Value:
True if successful and false otherwise.
Prototype:
<fpvalue by value>pickTrackDlg()
 Interface: trackviews 431

Remarks:
pickTrackDlg has variable number of arguments
Return Value:
This method brings up the Track View Pick dialog and returns a TrackViewPick value when the user
selects a track and clicks “Ok”, or undefined if the user clicks “Cancel”. If the optional argument
#multiple is passed, multiple tracks can be picked in the dialog and an array of TrackViewPick values
is returned instead of single value.
Prototype:
<boolean>isOpen <fpvalue>name or index
Parameters:
<fpvalue>name or index
Return Value:
Returns a boolean value indicating if the specified trackview is open.
Prototype:
<boolean>openLastUsedTrackView()
Return Value:
Opens the current trackview if it has been closed.
Prototype:
<boolean>isCurrent <fpvalue>name or index
Parameters:
<fpvalue>name or index
Return Value:
Returns a boolean value indicating if the trackview is the last one used or not.
Prototype:
<boolean>setCurrent <fpvalue>name or index
Parameters:
<fpvalue>name or index
Return Value:
Sets the specified trackview to be the current one. Returns true if successful.

See Also
Track View Pick Dialog (p. 1617)
432 Chapter 1 | What’s New in 3ds max 4 MAXScript

Other Interfaces
Topic: version 4 MAXScript New Features/Interfaces
Interfaces (p. 67)
bitmapTex (p. 434)
Block Control (p. 435)
BMP (p. 437)
Flex interfaces: (p. 438)
float list (p. 441)
Float Reactor (p. 443)
Float Wire interfaces: (p. 448)
FloatList (p. 450)
FloatReactor (p. 452)
HSDS Modifier (p. 453)
HSDSObject (p. 453)
IKChainControl (p. 453)
imageMotionBlur (p. 454)
JPEG (p. 454)
Link (p. 455)
Link Constraint (p. 455)
LookAt Constraint (p. 455)
Motion Blur (p. 462)
Orientation Constraint (p. 462)
path (p. 462)
Path Constraint (p. 468)
Plugin Manager (p. 473)
Portable Network Graphics (p. 473)
point3 list (p. 475)
Point3 Reactor (p. 477)
Point3 Wire (p. 477)
Point3List (p. 479)
Point3Reactor (p. 481)
Point3Spring (p. 482)
Point Cache (p. 484)
Point CacheSpacewarpModifier (p. 485)
 Interface: trackviews 433

PointCache (p. 486)

PointCacheWSM (p. 487)
Position Constraint (p. 488)
position list (p. 490)
Position Reactor (p. 492)
Position Wire (p. 492)
PositionList (p. 494)
PositionReactor (p. 496)
PositionSpring (p. 497)
radiusManip (p. 500)
RenderElementMgr (p. 503)
rotation list (p. 505)
Rotation Reactor (p. 507)
Rotation Wire (p. 508)
RotationList (p. 510)
RotationReactor (p. 512)
scale list (p. 513)
Scale Reactor (p. 515)
Scale Wire (p. 515)
ScaleList (p. 517)
ScaleReactor (p. 519)
sliderManipulator (p. 520)
SpringPoint3Controller (p. 523)
SpringPositionController (p. 526)
Targa (p. 529)
Unwrap UVW (p. 530)
uvwMappingHeightManip (p. 551)
uvwMappingLengthManip (p. 555)
uvwMappingUTileManip (p. 558)
uvwMappingVTileManip (p. 562)
uvwMappingWidthManip (p. 565)
UVWUnwrap (p. 568)
Float Wire (p. 448)
Point3 Wire (p. 477)
434 Chapter 1 | What’s New in 3ds max 4 MAXScript

Rotation Wire (p. 508)

Scale Wire (p. 515)

See Also
Core Interfaces (p. 70)
Class and Object Inspector Functions (p. 799)
Class and Object Inspector Functions Enhanced (p. 159)

Other Interface Pages

bitmapTex interfaces:
bitmapTex interfaces:
Interface: bitmapTex
Methods:
Prototype:
<void>reload()
Remarks:
Reloads the bitmap file using the same name and path. You don’t need to use the file browser to
reload the bitmap after you’ve updated it in your paint program.
Clicking reload for any instance of the map updates the map in all sample slots and in the scene.
Prototype:
<void>viewImage()
Remarks:
Displays a Virtual Frame Buffer that shows the bitmap surrounded by a region outline. The region
outline has handles at its sides and corners. When cropping is on, dragging the handles changes the
size of the crop area. You can also drag within the region area to move it.
The VFB editing window has U/V and W/H (width/height) spinners on its toolbar. Use these to
adjust the location and size the image or crop area.
When Place is turned on, dragging the region area handles changes the scale of the bitmap (hold
down CTRL to preserve the bitmap’s aspect ratio), and dragging the image changes its location
within the tile area.
When Crop is turned on, the UV or XY button at the right of the virtual frame buffer toolbar lets
you switch between using UV or XY coordinates in the toolbar spinners. Also, you can zoom out by
pressing SHIFT+Z and zoom in by pressing Z.
 Block_Control interfaces: 435

See Also
BitmapTexture : TextureMap (p. 1243)
BMP, PNG, JPEG and TGA I/O Interfaces (p. 164)
Material Editor Access (p. 165)
Accessing The Material Editor Active Slot (p. 163)
Material Level Show-in-viewport State (p. 166)
showTextureMap() function (p. 167)

Block_Control interfaces:
Interface: list
Properties:
.count : integer : Read
.active : index : Read|Write
Methods:
Prototype:
<integer>getCount()
Remarks:
This method returns the number of items that appear in the List controllers list box.
Prototype:
<void>setActive <index>listIndex
Remarks:
This method allows you to sets the indexed item in the list active so its parameters appear in the
motion panel, and any input is directed to the indexed sub controller.
Parameters:
<index>listIndex
The index of the item to set as the active item.
Prototype:
<integer>getActive()
Remarks:
This method returns the index of the currently active item.
Prototype:
<void>delete <index>listIndex
436 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method allows you to delete the indexed sub controller from the list.
Parameters:
<index>listIndex
The index of the item to delete from the list.
Prototype:
<void>cut <index>listIndex
Remarks:
This method allows you to cut the index sub controller from the list and stores it in the buffer to
paste later.
Parameters:
<index>listIndex
The index of the item you wish to cut.
Prototype:
<void>paste <index>listIndex
Remarks:
This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.
Parameters:
<index>listIndex
The index of the slot to paste into.
Prototype:
<TSTR by value>getName <index>listIndex
Remarks:
This method returns the class name of the indexed sub-controller if a user defined name doesn’t
exist.
Parameters:
<index>listIndex
The index of the item for which to get the name.
Prototype:
<void>setName <index>listIndex <string>name
Remarks:
This method allows you to set the name of an indexed item.
Parameters:
<index>listIndex
The index of the item.
<string>name
The name to set it to.
 BMP interfaces: 437

See Also
In the MAXSDK Help File
Class IListControl

BMP interfaces:
This represents the interface for the Bitmap IO BMP format.
Interface: ibmpio
Methods:
Prototype:
<enum>getType()
getType enums: {#noType|#paletted|#true24}
Return Value:
This method returns the format type, which is one of the enum types.
Note:
#noType is equivalent to #true24
Prototype:
<void>setType <enum>type
type enums: {#noType|#paletted|#true24}
Remarks:
This method allows you to set the format type.
Parameters:
<enum>type
The type, which is one of the enum types.
Note:
#noType is equivalent to #true24

See Also
In The MAXSDK Help File
Class IBitmapIO_Bmp
438 Chapter 1 | What’s New in 3ds max 4 MAXScript

Flex interfaces:
Flex interfaces:
Interface: flexOps
Methods:
Prototype:
<void>paint()
Prototype:
<void>setReference()
Prototype:
<void>reset()
Prototype:
<void>addForce <node>force
Parameters:
<node>force
Prototype:
<void>removeForce <integer>force
Parameters:
<integer>force
Prototype:
<integer>numberVertices()
Prototype:
<void>selectVertices <bitArray>sel <boolean>update
Parameters:
<bitArray>sel
<boolean>update
Prototype:
<bitArray>getSelectedVertices()
Prototype:
<float>getVertexWeight <integer>index
Parameters:
<integer>index
Prototype:
<void>setVertexWeight <int array>indices <float array>values
Parameters:
<int array>indices
<float array>values
Prototype:
<void>setEdgeList <bitArray>sel <boolean>update
 Flex interfaces: 439

Parameters:
<bitArray>sel
<boolean>update
Prototype:
<bitArray>getEdgeList()
Prototype:
<void>addSpringFromSelection <integer>flag <boolean>addDuplicates
Parameters:
<integer>flag
<boolean>addDuplicates
Prototype:
<void>addSpring <integer>indexA <integer>indexB <integer>flag
<boolean>addDuplicates
Parameters:
<integer>indexA
<integer>indexB
<integer>flag
<boolean>addDuplicates
Prototype:
<void>removeAllSprings()
Prototype:
<void>addSpringButton()
Prototype:
<void>removeSpringButton()
Prototype:
<void>optionsButton()
Prototype:
<void>createSimpleSoftButton()
Prototype:
<void>removeSpringByEnd <integer>a
Parameters:
<integer>a
Prototype:
<void>removeSpringByEnds <integer>a <integer>b
Parameters:
<integer>a
<integer>b
440 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<void>removeSpringByIndex <integer>index
Parameters:
<integer>index
Prototype:
<integer>numberSprings()
Prototype:
<integer>getSpringGroup <integer>index
Parameters:
<integer>index
Prototype:
<void>setSpringGroup <integer>index <integer>group
Parameters:
<integer>index <integer>group
Prototype:
<float>getSpringLength <integer>index
Parameters:
<integer>index
Prototype:
<void>setSpringLength <integer>index <float>length
Parameters:
<integer>index
<float>length
Prototype:
<integer>getIndex <integer>a <integer>b
Parameters:
<integer>a
<integer>b

See Also
PositionSpring interfaces: (p. 497)
Point3Spring interfaces: (p. 482)
SpringPoint3Controller interfaces: (p. 523)
SpringPoint3Controller - superclass: Point3Controller (p. 336)
SpringPositionController interfaces: (p. 526)
SpringPositionController - superclass: PositionController (p. 337)
Flex : Modifier (p. 1128)
Flex interfaces: (p. 438)
flexOps const StructDef (p. 235)
 float_list interfaces: 441

float_list interfaces:
float_list interfaces:
This class represents the interface to the list controller.
Interface: list
Properties:
.count : integer : Read
.active : index : Read|Write
Methods:
Prototype:
<integer>getCount()
Remarks:
This method returns the number of items that appear in the List controllers list box.
Prototype:
<void>setActive <index>listIndex
Remarks:
This method allows you to sets the indexed item in the list active so its parameters appear in the
motion panel, and any input is directed to the indexed sub controller.
Parameters:
<index>listIndex
The index of the item to set as the active item.
Prototype:
<integer>getActive()
Remarks:
This method returns the index of the currently active item.
Prototype:
<void>delete <index>listIndex
Remarks:
This method allows you to delete the indexed sub controller from the list.
Parameters:
<index>listIndex
The index of the item to delete from the list.
Prototype:
<void>cut <index>listIndex
Remarks:
This method allows you to cut the index sub controller from the list and stores it in the buffer to
paste later.
442 Chapter 1 | What’s New in 3ds max 4 MAXScript

Parameters:
<index>listIndex
The index of the item you wish to cut.
Prototype:
<void>paste <index>listIndex
Remarks:
This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.
Parameters:
<index>listIndex
The index of the slot to paste into.
Prototype:
<TSTR by value>getName <index>listIndex
Remarks:
This method returns the class name of the indexed sub-controller if a user defined name doesn’t
exist.
Parameters:
<index>listIndex
The index of the item for which to get the name.
Prototype:
<void>setName <index>listIndex <string>name
Remarks:
This method allows you to set the name of an indexed item.
Parameters:
<index>listIndex
The index of the item.
<string>name
The name to set it to.

See Also
In the MAXSDK Help File
Class IListControl
 Float Reactor interfaces: 443

Float Reactor interfaces:

Float Reactor interfaces:
Interface: reactions
Properties:
.editStateMode : boolean : Read|Write
This property sets or gets the state of the Edit Reaction State toggle.
.useCurve : boolean : Read|Write
Specifies whether or not to use the curve.
Methods:
Prototype:
<void>reactTo <maxObject>object
Parameters:
<maxObject>object
The object to react to. This can either be a controller or a node.
The default influence value depends on the time the reaction was created.
Remarks:
This is a time variant function so it will use the MAXScript time context instead of requiring a Time
value as an argument.
Prototype:
<boolean>create name:<string>
name default value: “scriptCreated”
Create a new reaction and give it a name.
The default influence value depends on the time the reaction was created.
Remarks:
This is a time variant function. It will also use the name supplied if there is one, but a name is not
necessary.
Return Value:
True if successful and false otherwise.
Note:
All index parameters below are 1-based.
Prototype:
<boolean>delete <index>index
Parameters:
<index>index
Return Value:
Returns true is successful and false otherwise.
444 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<integer>getCount()
Return Value:
Returns the reaction count.
Prototype:
<void>select <index>index
Parameters:
<index>index
Prototype:
<index>getSelected()
Return Value:
Prototype:
<boolean>setStateToCurrent <index>index
Parameters:
<index>index
Remarks:
This is a Time Variant function. Sets the reaction state to the current state at the given MAXScript
time.
Return Value:
Returns true is successful and false otherwise.
Prototype:
<boolean>setFloatState <index>index <float>state
Parameters:
<index>index
<float>state
Remarks:
Set the reaction state to the value passed in. The function you use depends on the type of reactor
controller it is.
Return Value:
Returns true is successful and false otherwise.
Prototype:
<boolean>setVectorState <index>index <point3>state
Parameters:
<index>index
<point3>state
Remarks:
Set the reaction state to the value passed in. The function you use depends on the type of reactor
controller it is.
 Float Reactor interfaces: 445

Return Value:
Returns true is successful and false otherwise.
Prototype:
<boolean>setRotationState <index>index <quat>state
Parameters:
<index>index
<quat>state
Remarks:
Set the reaction state to the value passed in. The function you use depends on the type of reactor
controller it is.
Return Value:
Returns true is successful and false otherwise.
Prototype:
<boolean>setValueToCurrent <index>index
Parameters:
<index>index
Remarks:
This is a Time Variant function. Sets the reaction value to value of the ReactTo object at the given
MAXScript time.
Return Value:
Returns true is successful and false otherwise.
Prototype:
<boolean>setValueAsFloat <index>index <float>value
Parameters:
<index>index
<float>value
Remarks:
Set the reaction value to the value passed in. The function you use depends on the type of object or
controller you are reacting to. See getType() below.
Return Value:
Returns true is successful and false otherwise.
Prototype:
<boolean>setValueAsVector <index>index <point3>value
Parameters:
<index>index
<point3>value
446 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Set the reaction value to the value passed in. The function you use depends on the type of object or
controller you are reacting to. See getType() below.
Return Value:
Returns true is successful and false otherwise.
Prototype:
<boolean>setValueAsQuat <index>index <quat>value
Parameters:
<index>index
<quat>value
Remarks:
Set the reaction value to the value passed in. The function you use depends on the type of object or
controller you are reacting to. See getType() below.
Return Value:
Returns true is successful and false otherwise.
Prototype:
<boolean>setInfluence <index>index <float>influence
Parameters:
<index>index
<float>influence
Remarks:
Sets the influence for the specified reaction.
Return Value:
Returns true is successful and false otherwise.
Prototype:
<boolean>setStrength <index>index <float>strength
Parameters:
<index>index
<float>strength
Remarks:
Sets the strength for the specified reaction.
Return Value:
Returns true is successful and false otherwise.
Prototype:
<boolean>setFalloff <index>index <float>influence
Parameters:
<index>index
<float>influence
 Float Reactor interfaces: 447

Remarks:
Sets the falloff for the specified reaction.
Return Value:
Prototype:
<void>setName <index>index <string>name
Parameters:
<index>index
<string>name
Remarks:
Set the name of the reaction specified by the index.
Prototype:
<string>getName <index>index
Parameters:
<index>index
Return Value:
Returns the reaction name.
Prototype:
<float>getInfluence <index>index
Parameters:
<index>index
Return Value:
Returns the reaction influence.
Prototype:
<float>getStrength <index>index
Parameters:
<index>index
Return Value:
Returns the reaction strength.
Prototype:
<float>getFalloff <index>index
Parameters:
<index>index
Return Value:
Returns the reaction falloff.
Prototype:
<enum>getType()
getType enums: { #floatReaction | #positionalReaction | #rotationalReaction
| #scaleReaction }
448 Chapter 1 | What’s New in 3ds max 4 MAXScript

Return Value:
The type of object you are reacting to.
Prototype:
<fpvalue by value>getState <index>index
Parameters:
<index>index
Return Value:
Returns the reaction state. This value can be either a Point3, a Quat, or a float depending on the type
of reactor controller this is.
Prototype:
<fpvalue by value>getValue <index>index
Parameters:
<index>index
Return Value:
Returns the reaction value. This value can be either a Point3, a Quat, or a float depending on the
type of reactor controller this is.

Float_Wire interfaces:
This represents the interface for individual wire controllers.
Interface: wireController
Properties:
.numWires : integer : Read
This property returns the number of wires out of this controller (i.e. the number of
dependent params).
.isMaster : boolean : Read
This property will return TRUE if the wire is a master predicate, otherwise it will return
FALSE.
.isSlave : boolean : Read
This method will return TRUE if the wire is a slave predicate, otherwise it will return
FALSE.
.isTwoWay : boolean : Read
This method will return TRUE if the wire is a two-way predicate, otherwise it will return
FALSE.
.slaveAnimation : control : Read|Write
This method returns a pointer to the slave animation controller.
This method allows you to set the slave animation controller.
Prototype:
<maxObject>getWireParent <index>index
 Float_Wire interfaces: 449

Parameters:
<index>index
The index you wish to retrieve.
Return Value:
This method returns a pointer to the i-th dependent parameter parent.
Prototype:
<integer>getWireSubnum <index>index
Remarks:
This method returns the i-th dependent parameter subanim num in the animatable.
Parameters:
<index>index
The index of the subanim.
Return Value:
This method returns the i-th dependent parameter subanim num in the animatable.
Prototype:
<control>getCoController <index>index
Parameters:
<index>index
The index of the controller.
Return Value:
This method returns a pointer to the i-th CoController.
Prototype:
<string>getExprText <index>index
Parameters:
<index>index
The index of the parameter.
Return Value:
This method returns the expression string of the i-th wire parameter.
Prototype:
<void>setExprText <index>index <string>text
Remarks:
This method allows you to set the expression string of the i-th wire parameter.
Parameters:
<index>index
The index of the parameter
<string>text
The expression you wish to set.
450 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
In The MAXSDK Help File
Class IBaseWireControl

FloatList interfaces:
This class represents the interface to the list controller.
Properties:
.count : integer : Read
.active : index : Read|Write
Methods:
Prototype:
<integer>getCount()
Remarks:
This method returns the number of items that appear in the List controllers list box.
Prototype:
<void>setActive <index>listIndex
Remarks:
This method allows you to sets the indexed item in the list active so its parameters appear in the
motion panel, and any input is directed to the indexed sub controller.
Parameters:
<index>listIndex
The index of the item to set as the active item.
Prototype:
<integer>getActive()
Remarks:
This method returns the index of the currently active item.
Prototype:
<void>delete <index>listIndex
Remarks:
This method allows you to delete the indexed sub controller from the list.
Parameters:
<index>listIndex
The index of the item to delete from the list.
Prototype:
<void>cut <index>listIndex
 FloatList interfaces: 451

Remarks:
This method allows you to cut the index sub controller from the list and stores it in the buffer to
paste later.
Parameters:
<index>listIndex
The index of the item you wish to cut.
Prototype:
<void>paste <index>listIndex
Remarks:
This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.
Parameters:
<index>listIndex
The index of the slot to paste into.
Prototype:
<TSTR by value>getName <index>listIndex
Remarks:
This method returns the class name of the indexed sub-controller if a user defined name doesn’t
exist.
Parameters:
<index>listIndex
The index of the item for which to get the name.
Prototype:
<void>setName <index>listIndex <string>name
Remarks:
This method allows you to set the name of an indexed item.
Parameters:
<index>listIndex
The index of the item.
<string>name
The name to set it to.

See Also
In the MAXSDK Help File
Class IListControl
452 Chapter 1 | What’s New in 3ds max 4 MAXScript

FloatReactor interfaces:
FloatReactor interfaces:
Interface: reactions
Properties:
.editStateMode : boolean : Read|Write
.useCurve : boolean : Read|Write
methods:
<void>reactTo <maxObject>object
<boolean>create name:<string>
name default value: “scriptCreated”}
<boolean>delete <index>index
<integer>getCount()
<void>select <index>index
<index>getSelected()
<boolean>setStateToCurrent <index>index
<boolean>setFloatState <index>index <float>state
<boolean>setVectorState <index>index <point3>state
<boolean>setRotationState <index>index <quat>state
<boolean>setValueToCurrent <index>index
<boolean>setValueAsFloat <index>index <float>value
<boolean>setValueAsVector <index>index <point3>value
<boolean>setValueAsQuat <index>index <quat>value
<boolean>setInfluence <index>index <float>influence
<boolean>setStrength <index>index <float>strength
<boolean>setFalloff <index>index <float>influence
<void>setName <index>index <string>name
<string>getName <index>index
<float>getInfluence <index>index
<float>getStrength <index>index
<float>getFalloff <index>index
<enum>getType()
getType enums:
{#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}
<fpvalue by value>getState <index>index
<fpvalue by value>getValue <index>index
Actions:
 HSDS_Modifier interfaces: 453

HSDS_Modifier interfaces:
HSDS_Modifier interfaces:
Interface: hsdsOps
Properties:
methods:
<void>subdivide()
<void>deletePolygon()
<void>hide()
<void>showAll()
<void>createNamedSelection <string>name
<void>activateNamedSelection <string>name
<void>addDetail <float>length <float>angle
<void>removeDetail <float>length <float>angle
Actions:

HSDSObject interfaces:
HSDSObject interfaces:
Interface: hsdsOps
Properties:
methods:
<void>subdivide()
<void>deletePolygon()
<void>hide()
<void>showAll()
<void>createNamedSelection <string>name
<void>activateNamedSelection <string>name
<void>addDetail <float>length <float>angle
<void>removeDetail <float>length <float>angle
Actions:

IKChainControl interfaces:
IKChainControl interfaces:
Interface: Action
Properties:
methods:
<float>snap() -- Action Interface
<float>ikSnap() -- Action Interface
<float>fkSnap() -- Action Interface
Actions:
Category: IK_Chain_Actions; Action: IK_Chain_Snap_Action; Shortcut: -- none
defined --
Category: IK_Chain_Actions; Action: IK_Chain_IK_Snap; Shortcut: -- none defined
--
Category: IK_Chain_Actions; Action: IK_Chain_FK_Snap; Shortcut: -- none defined
–
454 Chapter 1 | What’s New in 3ds max 4 MAXScript

imageMotionBlur interfaces:
imageMotionBlur interfaces:
Interface: ImageMotionBlur
Properties:
methods:
Actions:

JPEG interfaces:
This represents the interface for the Bitmap IO JPG format.
Interface: ijpegio
Methods:
Prototype:
<integer>getQuality()
Return Value:
This method returns the quality level of the output image.
Prototype:
<void>setQuality <integer>quality
Remarks:
This method allows you to set the quality level of the output image.
Parameters:
<integer>quality
The quality level.
Prototype:
<integer>getSmoothing()
Return Value:
This method returns the smoothing level of the output image.
Prototype:
<void>setSmoothing <integer>smoothing
Remarks:
This method allows you set the smoothing level of the output image.
Parameters:
<integer>smoothing
The smoothing level.
 Link interfaces: 455

See Also
In The MAXSDK Help File
Class IBitmapIO_Jpeg

Link interfaces:
Link interfaces:
Interface: constraints
Properties:
methods:
<node>getTarget <index>index
<boolean>setTarget <node>target <index>index
<float>getFrameNo <index>index <time>time
<boolean>setFrameNo <integer>frameNo <index>index <time>time
<integer>getNumTargets()
<boolean>appendTarget <node>target <time>time
<void>DeleteTarget <integer>targetNumber
Actions:

Link_Constraint interfaces:
Link_Constraint interfaces:
Interface: constraints
Methods:
<node>getTarget <index>index
<boolean>setTarget <node>target <index>index
<float>getFrameNo <index>index <time>time
<boolean>setFrameNo <integer>frameNo <index>index <time>time
<integer>getNumTargets()
<boolean>appendTarget <node>target <time>time
<void>DeleteTarget <integer>targetNumber

LookAt_Constraint interfaces:
This class is an interface to the LookAt Constraint rotation controller.
Interface: constraints
Methods:
Prototype:
<node>getTarget <index>index

Parameters:
<index>index
The node number in the Look-At target list to be obtained.
456 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method will return a pointer to a node of one of the Look-At nodes that the Look-At constraint
controller targets, specified by targetNumber.
Prototype:
<boolean>setTarget <node>target <index>index

Parameters:
<node>target
Points to the node to follow.
<index>index
The node number in the Look-At target list to be set.
Remarks:
Sets one of the Look-At nodes that the Look-At constraint controller targets, specified by
targetNumber. If targetNumber is greater than the number of targets in the current list, it returns a
FALSE. In this case use the function AppendTarget.
Return Value:
TRUE if success; FALSE otherwise.
Prototype:
<float>getWeight <index>index <time>time

Parameters:
<index>index
The node number in the Look-At target list whose weight is to be obtained.
<time>time
The time at which the weight is to be obtained. The weights are animatable.
Remarks:
Gets the weight of one of the Look-At nodes that the Look-At constraint controller targets, specified
by targetNumber, and time t.
Prototype:
<boolean>setWeight <float>weight <index>index <time>time

Parameters:
<float>weight
The weight to set.
<index>index
The node number in the Look-At target list whose weight is to be set.
<time>time
The time at which the weight is to be set. The weights are animatable.
 LookAt_Constraint interfaces: 457

Remarks:
Sets the weight of one of the Look-At nodes that the Look-At constraint controller follows, specified
by targetNumber, and time t.
Return Value:
TRUE if there is more than one Look-At targets in the list and you are trying to set weight, FALSE
otherwise.
Prototype:
<integer>getNumTargets()
Remarks:
Returns the number of nodes in the list of nodes to look at.
Prototype:
<void>appendWeightedTarget <node>target <float>weight

Parameters:
<node>target
The node that is to be appended to the current Look-At target list.
<float>weight
This is the weight that is to be assigned to the newly appended Look-At target. The
default weight is 50.0.
Remarks:
Appends the current Look-At target list by one and appends the current Look-At target weightlist by
one.
Prototype:
<boolean>appendTarget <node>target

Parameters:
<node>target
The node that is to be appended to the current Look-At target list.
Remarks:
Appends the current Look-At target list by one and appends the current Look-At target weightlist
by one.
Prototype:
<boolean>getRelative()
Remarks:
Gets the relative/absolute mode corresponding to the “Keep Initial Offset” checkbox in the UI.
Prototype:
<boolean>getUpnodeWorld()
458 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Returns TRUE if the “World” checkbox is on; FALSE if off.
Prototype:
<boolean>getStoUpAxisFlip()
Remarks:
Returns TRUE if the “selected” axis flip checkbox is on; FALSE if off.
Prototype:
<boolean>getTargetAxisFlip()
Remarks:
Returns TRUE if the “source” axis flip checkbox is on; FALSE if off.
Prototype:
<boolean>getSetOrient()
Remarks:
Returns TRUE if the orientation flag is set, FALSE if off.
Prototype:
<boolean>getTargetAxis()
Remarks:
Gets the selection corresponding to the “Select LookAt Axis” button in the UI. Obtains which of the
source axes is required to coincide with the target axis.
Return Value:
(0) if the target axis coincides with the x axis of the source object. (1) if the target axis coincides with
the y axis of the source object. (2) if the target axis coincides with the z axis of the source object.
Prototype:
<boolean>getUpNodeAxis()
Remarks:
Gets the selection corresponding to the “Source/Upnode Alignment: Aligned to UpNode Axis:”
radiobutton in the UI. Obtains which of the upnode axes is required to align with a specified source
axis.
Return Value:
(0) if the upnode x axis coincides with a specified source object. (1) if the upnode y axis coincides
with a specified source object. (2) if the upnode z axis coincides with a specified source object.
Prototype:
<boolean>getStoUPAxis()
Remarks:
Gets the selection corresponding to the “Source/Upnode Alignment: Aligned to UpNode Axis:”
radiobutton in the UI. Obtains which of the source axes is required to align with a specified
upnode axis.
 LookAt_Constraint interfaces: 459

Return Value:
(0) if the source x axis coincides with a specified upnode axis. (1) if the source y axis coincides with
a specified upnode axis. (2) if the source z axis coincides with a specified upnode axis.
Prototype:
<void>setRelative <boolean>rel

Parameters:
<boolean>rel
TRUE to set the relative flag, otherwise FALSE.
Remarks:
This method allows you to set the “relative” flag.
Prototype:
<void>setUpnodeWorld <boolean>upnode

Parameters:
<boolean>upnode
TRUE to set the world flag, otherwise false.
Remarks:
This method allows you to set the “World” flag.
Prototype:
<void>setTargetAxisFlip <boolean>staxflip

Parameters:
<boolean>staxflip
TRUE to set the source flip axis flag, otherwise FALSE.
Remarks:
This method allows you to set the “source” flip axis flag.
Prototype:
<void>setStoUPAxisFlip <boolean>ssuaflip

Parameters:
<boolean>ssuaflip
TRUE to set the selected axis flip flag, otherwise FALSE.
Remarks:
This method allows you to set the “selected” axis flip flag.
Prototype:
<void>setSetOrient <boolean>ssorient
460 Chapter 1 | What’s New in 3ds max 4 MAXScript

Parameters:
<boolean>ssorient
TRUE to set the orientation flag, otherwise FALSE.
Remarks:
This method allows you to set the orientation flag.
Prototype:
<void>setResetOrient()
Remarks:
Resets to zero the amount of orientation offset, effected through the “Set Orientation” feature.
Prototype:
<void>setTargetAxis <integer>staxis

Parameters:
<integer>staxis
(0) if TargetAxis coincides with the X axis of the source object. (1) if TargetAxis
coincides with the Y axis of the source object. (2) if TargetAxis coincides with the Z
axis of the source object
Remarks:
Sets the selection corresponding to the “Set Orientation” button in the UI. Specifies which of the
source axes is required to coincide with the target axis.
Prototype:
<void>setUpNodeAxis <integer>sunaxis

Parameters:
<integer>sunaxis
(0) if the upnode X axis coincides with a specified source axis. (1) if the upnode Y axis
coincides with a specified source axis. (2) if the upnode Z axis coincides with a
specified source axis.
Remarks:
Sets the selection corresponding to the “Source/Upnode Alignment: Aligned to UpNode Axis:”
radiobutton in the UI. Specifies which of the upnode axes is required to align with a specified source
axis.
Prototype:
<void>setStoUPAxis <integer>ssuaxis

Parameters:
<integer>ssuaxis
(0) if the source X axis coincides with a specified upnode axis. (1) if the source Y axis
coincides with a specified upnode axis. (2) if the source Z axis coincides with a
specified upnode axis.
 LookAt_Constraint interfaces: 461

Remarks:
Sets the selection corresponding to the “Source/Upnode Alignment: Aligned to UpNode Axis:”
radiobutton in the UI. Specifies which of the source axes is required to align with a specified upnode
axis.
Prototype:
<boolean>GetVLisAbs()
Remarks:
Gets the ViewLine relative/absolute mode corresponding to the “Keep ViewLine Length Absolute”
checkbox in the UI. When Viewline Length is absolute, the “ViewLine Length” spinner sets the
length of the ViewLine. A negative length implies that starting from the source object the line travels
opposite to the direction of the target object. The source/target distance has no effect on the
ViewLine length in this mode. If the “Keep ViewLine Length Absolute” checkbox is unchecked, the
ViewLine length is determined from the spinner value, which is interpreted as a percentage of the
source/target distance.
Return Value:
TRUE if the ViewLine length is absolute, FALSE otherwise.
Prototype:
<void>SetVLisAbs <boolean>rel

Parameters:
<boolean>rel
TRUE if “Keep ViewLine Length Absolute” is active (checked), FALSE otherwise.
Remarks:
Sets the relative/absolute mode corresponding to the “Keep ViewLine Length Absolute” checkbox in
the UI.
Prototype:
<void>deleteTarget <integer>targetNumber

Parameters:
<integer>targetNumber
The zero based node number in the list of nodes the controller looks at.
Remarks:
This method allows you to delete a specified target.

See Also
In The MAXSDK Help File
Class ILookAtConstRotation
462 Chapter 1 | What’s New in 3ds max 4 MAXScript

Motion_Blur interfaces:
Motion_Blur interfaces:
Interface: ImageMotionBlur
Properties:
methods:
Actions:

Orientation_Constraint interfaces:
Orientation_Constraint interfaces:
Interface: constraints
Properties:
methods:
<node>getTarget <index>index
<boolean>setTarget <node>target <index>index
<float>getWeight <index>index <time>time
<boolean>setWeight <float>weight <index>index <time>time
<integer>getNumTargets()
<integer>getlw()
<void>appendWeightedTarget <node>target <float>weight
<void>deleteNode <integer>targetNumber
Actions:

path interfaces:
path interfaces:
This class represents the interface to the Path Position Controller.
Interface: constraints
Methods:
<integer>getNumTargets()
Remarks:
Returns the number of nodes in the path list.
Prototype:
<node>getTarget <index>index
Remarks:
Gets one of the path nodes that the path controller follows, specified by targetNumber.
Parameters:
<index>index
The node number in the path list to be obtained.
Prototype:
<boolean>setTarget <node>target <index>index
 path interfaces: 463

Prototype:
<float>getWeight <index>index <time>time
Remarks:
Gets the weight of one of the path nodes that the path controller follows, specified by targetNumber,
and time t. If the targetNumber is not relevant then 0.0f is returned.
Parameters:
<index>index
The node number in the path list whose weight is to be obtained.
<time>time
Prototype:
<boolean>setWeight <float>weight <index>index <time>time
Remarks:
Sets the weight of one of the path nodes that the path controller follows, specified by targetNumber.
Parameters:
<float>weight
The weight to assign.
<index>index
The node number in the path list whose weight is to be set.
<time>time
Return Value:
TRUE if there is more than one path in the list and you are trying to set weight, FALSE otherwise.
Prototype:
<void>appendWeightedTarget <node>target <float>weight
Remarks:
Appends the current path list by one and appends the current weight list by one.
Parameters:
<node>target
The node that is to be appended to the current path list.
<float>weight
The weight to be assigned to the newly appended path.
Prototype:
<void>setFollow <boolean>isSetFollow
Remarks:
This method allows you to set the follow flag.
Parameters:
<boolean>isSetFollow
TRUE for on, FALSE for off.
464 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<boolean>getFollow()
Remarks:
This method returns the state of the follow flag. TRUE if on; FALSE if off.
Prototype:
<void>setBankAmount <float>bankAmount
Remarks:
Sets the bank amount parameter.
Bank and tracking are scaled in the UI.
Parameters:
<float>bankAmount
The bank amount.
Prototype:
<float>getBankAmount()
Remarks:
Returns the bank amount setting. See the remarks in SetBankAmount() above.
Prototype:
<void>SetBank <boolean>isSetBank
Remarks:
Sets the bank parameter to on or off.
Parameters:
<boolean>isSetBank
TRUE for on; FALSE for off.
Prototype:
<boolean>getBank()
Remarks:
Returns the on/off state of the bank parameter. TRUE if on; FALSE if off.
Prototype:
<void>setTracking <float>tracking
Remarks:
Sets the smoothness parameter.
Parameters:
<float>tracking
The smoothness setting.
Prototype:
<float>getTracking()
 path interfaces: 465

Remarks:
Returns the smoothness setting. See remarks in SetTracking() above.
Prototype:
<void>setAllowFlip <boolean>allowFlip
Remarks:
Sets the state of the ‘Allow Upside Down’ parameter.
Parameters:
<boolean>allowFlip
TRUE for on; FALSE for off.
Prototype:
<boolean>getAllowFlip()
Remarks:
Returns the state of the ‘Allow Upside Down’ parameter.
Return Value:
TRUE for on; FALSE for off.
Prototype:
<void>setConstVel <boolean>constVel
Remarks:
Sets the state of the ‘Constant Velocity’ parameter.
Parameters:
<boolean>constVel
TRUE for on; FALSE for off.
Prototype:
<boolean>getConstVel()
Remarks:
Returns the state of the ‘Constant Velocity’ parameter.
Return Value:
TRUE for on; FALSE for off.
Prototype:
<void>setFlip <boolean>Flip
Remarks:
Sets the state of the ‘Flip’ parameter.
Parameters:
<boolean>Flip
TRUE for on; FALSE for off.
466 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<boolean>getFlip()
Remarks:
Returns the state of the ‘Flip’ parameter.
Return Value:
TRUE for on; FALSE for off.
Prototype:
<void>setAxis <integer>isSetFollow
Remarks:
Set the state of the axis parameter.
Parameters:
<integer>isSetFollow
The axis setting. One of the following values:
0: X axis.
1: Y axis.
2: Z axis.
Prototype:
<integer>getAxis()
Remarks:
Returns the axis setting.
Return Value:
One of the following values:
0: X axis.
1: Y axis.
2: Z axis.
Prototype:
<void>setLoop <boolean>Loop
Remarks:
This method allows you to set the state of the loop flag.
Parameters:
<boolean>Loop
TRUE for on; FALSE for off.
Prototype:
<boolean>getLoop()
Remarks:
Returns the state of the loop flag.
 path interfaces: 467

Return Value:
TRUE for on; FALSE for off.
Prototype:
<void>setRelative <boolean>relative
Remarks:
This method allows you to set the state of the relative/absolute flag.
Parameters:
<boolean>relative
TRUE to set to relative; FALSE to set to absolute.
Prototype:
<boolean>getRelative()
Remarks:
Returns the state of the relative/absolute flag.
Return Value:
TRUE if relative is on; FALSE is off (i.e. absolute).
Prototype:
<void>deleteTarget <integer>targetNumber
Remarks:
This method allows you to delete a specified target.
Parameters:
<integer>targetNumber
The node number in the orientation target list to delete.
Return Value:
TRUE if successful, otherwise FALSE.

See Also
In The MAXSDK Help File
Class IPathPosition
468 Chapter 1 | What’s New in 3ds max 4 MAXScript

Path_Constraint interfaces:
Path_Constraint interfaces:
This class represents the interface to the Path Position Controller.
Interface: constraints
Properties:
Methods:
Prototype:
<integer>getNumTargets()
Prototype:
<node>getTarget <index>index
Parameters:
<index>index
The node number in the path list to be obtained.
Return Value:
Gets one of the path nodes that the path controller follows, specified by targetNumber.
Prototype:
<boolean>setTarget <node>target <index>index
Prototype:
<float>getWeight <index>index <time>time
Parameters:
<index>index
The node number in the path list whose weight is to be obtained.
<time>time
Return Value:
Gets the weight of one of the path nodes that the path controller follows, specified by targetNumber,
and time t. If the targetNumber is not relevant then 0.0f is returned.
Prototype:
<boolean>setWeight <float>weight <index>index <time>time
Remarks:
Sets the weight of one of the path nodes that the path controller follows, specified by targetNumber.
Parameters:
<index>index
The node number in the path list whose weight is to be set.
<float>weight
The weight to assign.
<time>time
 Path_Constraint interfaces: 469

Return Value:
TRUE if there is more than one path in the list and you are trying to set weight, FALSE otherwise.
Prototype:
<void>appendWeightedTarget <node>target <float>weight
Remarks:
Appends the current path list by one and appends the current weight list by one.
Parameters:
<node>target
The node that is to be appended to the current path list.
<float>weight
The weight to be assigned to the newly appended path. Default: 50.0
Prototype:
<void>setFollow <boolean>isSetFollow
Remarks:
This method allows you to set the follow flag.
Parameters:
<boolean>isSetFollow
TRUE for on, FALSE for off.
Prototype:
<boolean>getFollow()
Return Value:
This method returns the state of the follow flag. TRUE if on; FALSE if off.
Prototype:
<void>setBankAmount <float>bankAmount
Remarks:
Sets the bank amount parameter.
Bank and tracking are scaled in the UI.
The bank values are scaled in the user interface. The following macros may be used to convert to and
from the UI values.
Parameters:
<float>bankAmount
The bank amount.
Prototype:
<float>getBankAmount()
Return Value:
Returns the bank amount setting. See the remarks in SetBankAmount() above.
470 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<void>SetBank <boolean>isSetBank
Remarks:
Sets the bank parameter to on or off.
Parameters:
<boolean>isSetBank
TRUE for on; FALSE for off.
Prototype:
<boolean>getBank()
Return Value:
Returns the on/off state of the bank parameter. TRUE if on; FALSE if off.
Prototype:
<void>setTracking <float>tracking
Remarks:
Sets the smoothness parameter.
The smoothing (tracking) values are scaled in the user interface. The following macros may be used
to convert to and from the UI values.
Parameters:
<float>tracking
The smoothness setting.
Prototype:
<float>getTracking()
Return Value:
Returns the smoothness setting. See remarks in SetTracking() above.
Prototype:
<void>setAllowFlip <boolean>allowFlip
Remarks:
Sets the state of the ‘Allow Upside Down’ parameter.
Parameters:
<boolean>allowFlip
TRUE for on; FALSE for off.
Prototype:
<boolean>getAllowFlip()
Remarks:
Returns the state of the ‘Allow Upside Down’ parameter.
Return Value:
TRUE for on; FALSE for off.
 Path_Constraint interfaces: 471

Prototype:
<void>setConstVel <boolean>constVel
Remarks:
Sets the state of the ‘Constant Velocity’ parameter.
Parameters:
<boolean>constVel
TRUE for on; FALSE for off.
Prototype:
<boolean>getConstVel()
Remarks:
Returns the state of the ‘Constant Velocity’ parameter.
Return Value:
TRUE for on; FALSE for off.
Prototype:
<void>setFlip <boolean>Flip
Remarks:
Sets the state of the ‘Flip’ parameter.
Parameters:
<boolean>Flip
TRUE for on; FALSE for off.
Prototype:
<boolean>getFlip()
Remarks:
Returns the state of the ‘Flip’ parameter.
Return Value:
TRUE for on; FALSE for off.
Prototype:
<void>setAxis <integer>isSetFollow
Remarks:
Set the state of the axis parameter.
Parameters:
<integer>isSetFollow
The axis setting. One of the following values:
0: X axis.
1: Y axis.
2: Z axis.
472 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<integer>getAxis()
Remarks:
Returns the axis setting.
Return Value:
One of the following values:
0: X axis.
1: Y axis.
2: Z axis.
Prototype:
<void>setLoop <boolean>Loop
Remarks:
This method allows you to set the state of the loop flag.
Parameters:
<boolean>Loop
TRUE for on; FALSE for off.
Prototype:
<boolean>getLoop()
Remarks:
Returns the state of the loop flag.
Return Value:
TRUE for on; FALSE for off.
Prototype:
<void>setRelative <boolean>relative
Remarks:
This method allows you to set the state of the relative/absolute flag.
Parameters:
<boolean>relative
TRUE to set to relative; FALSE to set to absolute.
Prototype:
<boolean>getRelative()
Remarks:
Returns the state of the relative/absolute flag.
Return Value:
TRUE if relative is on; FALSE is off (i.e. absolute).
 Plugin_Manager interfaces: 473

Prototype:
<void>deleteTarget <integer>targetNumber
Remarks:
This method allows you to delete a specified target.
Parameters:
<integer>targetNumber
The node number in the orientation target list to delete.
Return Value:
TRUE if successful, otherwise FALSE.

See Also In The MAXSDK Help File

Class IPathPosition

Plugin_Manager interfaces:
Plugin_Manager interfaces:
Interface: PluginMgrAction
Methods:
Prototypes:
<float>show() -- Action Interface
Actions:
Category: Plugin_Manager; Action: Plugin_Manager; Shortcut: -- none defined –

See Also
Plug-In Manager (p. 86)
Interface: pluginManager (p. 414)

Portable_Network_Graphics interfaces:
This represents the interface for the Bitmap IO PNG format.
Interface: ipngio
Methods:
Prototype:
<enum>getType()
getType enums: {#paletted|#true24|#true48|#gray8|#gray16}
Return Value:
This method returns the bitmap type, which is one of the following; BMM_PALETTED,
BMM_TRUE_24, BMM_TRUE_48, BMM_GRAY_8, or BMM_GRAY_16.
474 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<void>setType <enum>type type enums:
{#paletted|#true24|#true48|#gray8|#gray16}

Parameters:
<enum>type
One of the following; BMM_PALETTED, BMM_TRUE_24, BMM_TRUE_48,
BMM_GRAY_8, or BMM_GRAY_16.
Remarks:
This method allows you to set the bitmap type.
Prototype:
<boolean>getAlpha()
Return Value:
This method returns TRUE if the alpha flag is set, otherwise FALSE.
Prototype:
<void>setAlpha <boolean>useAlpha

Parameters:
<boolean>useAlpha
TRUE to set the alpha flag, otherwise FALSE.
Remarks:
This method allows you to set the alpha flag.
Prototype:
<boolean>getInterlaced()
Return Value:
This method returns TRUE if the interlaced flag is set, otherwise FALSE.
Prototype:
<void>setInterlaced <boolean>Interlaced

Parameters:
<boolean>Interlaced
TRUE to set the interlaced flag, otherwise FALSE.
Remarks:
This method allows you to set the interlaced flag.

See Also
In The MAXSDK Help File
Class IBitmapIO_Png
 point3_list interfaces: 475

point3_list interfaces:
This class represents the interface to the list controller.
Interface: list
Properties:
.count : integer : Read
.active : index : Read|Write
Methods:
Prototype:
<integer>getCount()
Remarks:
This method returns the number of items that appear in the List controllers list box.
Prototype:
<void>setActive <index>listIndex

Parameters:
<index>listIndex
The index of the item to set as the active item.
Remarks:
This method allows you to sets the indexed item in the list active so its parameters appear in the
motion panel, and any input is directed to the indexed sub controller.
Prototype:
<integer>getActive()
Remarks:
This method returns the index of the currently active item.
Prototype:
<void>delete <index>listIndex

Parameters:
<index>listIndex
The index of the item to delete from the list.
Remarks:
This method allows you to delete the indexed sub controller from the list.
Prototype:
<void>cut <index>listIndex

Parameters:
<index>listIndex
The index of the item you wish to cut.
476 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method allows you to cut the index sub controller from the list and stores it in the buffer to
paste later.
Prototype:
<void>paste <index>listIndex

Parameters:
<index>listIndex
The index of the slot to paste into.
Remarks:
This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.
Prototype:
<TSTR by value>getName <index>listIndex

Parameters:
<index>listIndex
The index of the item for which to get the name.
Remarks:
This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.
Prototype:
<void>setName <index>listIndex <string>name

Parameters:
<index>listIndex
The index of the item.
<string>name
The name to set it to.
Remarks:
This method allows you to set the name of an indexed item.

See Also
In the MAXSDK Help File
Class IListControl
 Point3_Reactor interfaces: 477

Point3_Reactor interfaces:
Point3_Reactor interfaces:
Interface: reactions
Properties:
.editStateMode : boolean : Read|Write
.useCurve : boolean : Read|Write
methods:
<void>reactTo <maxObject>object
<boolean>create name:<string>
name default value: “scriptCreated”}
<boolean>delete <index>index
<integer>getCount()
<void>select <index>index
<index>getSelected()
<boolean>setStateToCurrent <index>index
<boolean>setFloatState <index>index <float>state
<boolean>setVectorState <index>index <point3>state
<boolean>setRotationState <index>index <quat>state
<boolean>setValueToCurrent <index>index
<boolean>setValueAsFloat <index>index <float>value
<boolean>setValueAsVector <index>index <point3>value
<boolean>setValueAsQuat <index>index <quat>value
<boolean>setInfluence <index>index <float>influence
<boolean>setStrength <index>index <float>strength
<boolean>setFalloff <index>index <float>influence
<void>setName <index>index <string>name
<string>getName <index>index
<float>getInfluence <index>index
<float>getStrength <index>index
<float>getFalloff <index>index
<enum>getType()
getType enums:
{#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}
<fpvalue by value>getState <index>index
<fpvalue by value>getValue <index>index
Actions:

Point3_Wire interfaces:
Interface: wireController
Properties:
.numWires : integer : Read
This property returns the number of wires out of this controller (i.e. the number of
dependent params).
.isMaster : boolean : Read
This property will return TRUE if the wire is a master predicate, otherwise it will return
FALSE.
478 Chapter 1 | What’s New in 3ds max 4 MAXScript

.isSlave : boolean : Read

This method will return TRUE if the wire is a slave predicate, otherwise it will return
FALSE.
.isTwoWay : boolean : Read
This method will return TRUE if the wire is a two-way predicate, otherwise it will return
FALSE.
.slaveAnimation : control : Read|Write
This method returns a pointer to the slave animation controller.
This method allows you to set the slave animation controller.
Prototype:
<maxObject>getWireParent <index>index
Parameters:
<index>index
The index you wish to retrieve.
Return Value:
This method returns a pointer to the i-th dependent parameter parent.
Prototype:
<integer>getWireSubnum <index>index

Parameters:
<index>index
The index of the subanim.
Remarks:
This method returns the i-th dependent parameter subanim num in the animatable.
Return Value:
This method returns the i-th dependent parameter subanim num in the animatable.
Prototype:
<control>getCoController <index>index
Parameters:
<index>index
The index of the controller.
Return Value:
This method returns a pointer to the i-th CoController.
Prototype:
<string>getExprText <index>index
Parameters:
<index>index
The index of the parameter.
 Point3List interfaces: 479

Return Value:
This method returns the expression string of the i-th wire parameter.
Prototype:
<void>setExprText <index>index <string>text

Parameters:
<index>index
The index of the parameter
<string>text
The expression you wish to set.
Remarks:
This method allows you to set the expression string of the i-th wire parameter.

See Also
In The MAXSDK Help File
Class IBaseWireControl

Point3List interfaces:
Point3List interfaces:
This class represents the interface to the list controller.
Interface: list
Properties:
.count : integer : Read
.active : index : Read|Write
Methods:
Prototype:
<integer>getCount()
Remarks:
This method returns the number of items that appear in the List controllers list box.
Prototype:
<void>setActive <index>listIndex
Remarks:
This method allows you to sets the indexed item in the list active so its parameters appear in the
motion panel, and any input is directed to the indexed sub controller.
Parameters:
<index>listIndex
The index of the item to set as the active item.
480 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<integer>getActive()
Remarks:
This method returns the index of the currently active item.
Prototype:
<void>delete <index>listIndex
Remarks:
This method allows you to delete the indexed sub controller from the list.
Parameters:
<index>listIndex
The index of the item to delete from the list.
Prototype:
<void>cut <index>listIndex
Remarks:
This method allows you to cut the index sub controller from the list and stores it in the buffer to
paste later.
Parameters:
<index>listIndex
The index of the item you wish to cut.
Prototype:
<void>paste <index>listIndex
Remarks:
This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.
Parameters:
<index>listIndex
The index of the slot to paste into.
Prototype:
<TSTR by value>getName <index>listIndex
Remarks:
This method returns the class name of the indexed sub-controller if a user defined name doesn’t
exist.
Parameters:
<index>listIndex
The index of the item for which to get the name.
Prototype:
<void>setName <index>listIndex <string>name
 Point3Reactor interfaces: 481

Remarks:
This method allows you to set the name of an indexed item.
Parameters:
<index>listIndex
The index of the item.
<string>name
The name to set it to.

See Also
In the MAXSDK Help File
Class IListControl

Point3Reactor interfaces:
Point3Reactor interfaces:
Interface: reactions
Properties:
.editStateMode : boolean : Read|Write
.useCurve : boolean : Read|Write
methods:
<void>reactTo <maxObject>object
<boolean>create name:<string>
name default value: “scriptCreated”}
<boolean>delete <index>index
<integer>getCount()
<void>select <index>index
<index>getSelected()
<boolean>setStateToCurrent <index>index
<boolean>setFloatState <index>index <float>state
<boolean>setVectorState <index>index <point3>state
<boolean>setRotationState <index>index <quat>state
<boolean>setValueToCurrent <index>index
<boolean>setValueAsFloat <index>index <float>value
<boolean>setValueAsVector <index>index <point3>value
<boolean>setValueAsQuat <index>index <quat>value
<boolean>setInfluence <index>index <float>influence
<boolean>setStrength <index>index <float>strength
<boolean>setFalloff <index>index <float>influence
<void>setName <index>index <string>name
<string>getName <index>index
<float>getInfluence <index>index
<float>getStrength <index>index
<float>getFalloff <index>index
<enum>getType()
getType enums:
{#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}
<fpvalue by value>getState <index>index
482 Chapter 1 | What’s New in 3ds max 4 MAXScript

<fpvalue by value>getValue <index>index

Actions:

Point3Spring interfaces:
Interface: Spring
Properties:
Methods:
Prototype:
<float>getMass()
Return Value:
Returns the mass.
Prototype:
<void>setMass <float>mass

Parameters:
<float>mass
Remarks:
Sets the mass. The mass of the object to which the Spring controller is applied. Increasing the mass
causes the “bouncing” spring motion to become more exaggerated.
Prototype:
<float>getDrag()
Return Value:
Returns the drag.
Prototype:
<void>setDrag <float>drag

Parameters:
<float>drag
Remarks:
Sets the drag. Acts as air friction on the spring motion. A low Drag setting results in a greater
“bouncing” effect, while a high Drag results in subdued bouncing. Default=1. Range=0 to 10.
Prototype:
<float>getTension <index>springIndex

Parameters:
<index>springIndex
Return Value:
Gets the tension for the spring corresponding to the index.
 Point3Spring interfaces: 483

Prototype:
<void>setTension <index>springIndex <float>tension

Parameters:
<index>springIndex
<float>tension
Remarks:
Sets the tension for the spring corresponding to the index. The “stiffness” of the virtual spring
between the controlled object and the highlighted spring object(s).
Prototype:
<float>getDampening <index>springIndex

Parameters:
<index>springIndex
Return Value:
Gets the dampening for the spring corresponding to the index.
Prototype:
<void>setDampening <index>springIndex <float>dampening

Parameters:
<index>springIndex
<float>dampening
Remarks:
Sets the dampening for the spring corresponding to the index. : Acts as a multiplier of an internal
factor that determines how quickly the object comes to rest. With the Self Influence spring,
changing Dampening has the same effect as changing Drag. With other springs, Dampening affects
only the movement caused by that spring. Internally, the dampening value is proportional to the
tension, so as you increase the tension and make the solution more stiff, the dampening is increased
to maintain system stability.
Prototype:
<boolean>addSpring <node>node

Parameters:
<node>node
Remarks:
Adds the node to the spring list.
Return Value:
Returns true if successful, false otherwise
Prototype:
<integer>getSpringCount()
484 Chapter 1 | What’s New in 3ds max 4 MAXScript

Return Value:
Returns the number of springs in the spring system.
Prototype:
<void>removeSpringByIndex <index>springIndex

Parameters:
<index>springIndex
Remarks:
Removes the spring corresponding to the index.
Prototype:
<void>removeSpring <node>node

Parameters:
<node>node
Remarks:
Removes the spring if the node is in the spring list.

See Also
PositionSpring interfaces: (p. 497)
Point3Spring interfaces: (p. 482)
SpringPoint3Controller interfaces: (p. 523)
SpringPoint3Controller - superclass: Point3Controller (p. 336)
SpringPositionController interfaces: (p. 526)
SpringPositionController - superclass: PositionController (p. 337)
Flex : Modifier (p. 1128)
Flex interfaces: (p. 438)
flexOps const StructDef (p. 235)

Point_Cache interfaces:
This represents the interface to the PointCache Modifier.
Interface: pointCache
Methods:
Prototype:
<void>record()
Remarks:
This method will press the Record button in the rollup interface.
 Point_CacheSpacewarpModifier interfaces: 485

Prototype:
<void>setCache()
Remarks:
This method will press the Set Cache button in the rollup interface.
Prototype:
<void>enableMods()
Remarks:
This method will press the Enable Modifiers Below button in the rollup interface.
Prototype:
<void>disableMods()
Remarks:
This method will press the Disable Modifiers Below button in the rollup interface.

See Also In The MAXSDK Help File

Class IpointCache

See Also
Point Cache Modifier (p. 26)
Point_Cache - superclass: modifier (p. 314)
Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315)
Point_CacheSpacewarpModifier interfaces: (p. 485)

Point_CacheSpacewarpModifier interfaces:
This represents the interface to the PointCache Modifier.
Interface: pointCacheWSM
Methods:
Prototype:
<void>record()
Remarks:
This method will press the Record button in the rollup interface.
Prototype:
<void>setCache()
Remarks:
This method will press the Set Cache button in the rollup interface.
Prototype:
<void>enableMods()
486 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method will press the Enable Modifiers Below button in the rollup interface.
Prototype:
<void>disableMods()
Remarks:
This method will press the Disable Modifiers Below button in the rollup interface.

See Also In The MAXSDK Help File

Class IPointCacheWSM

See Also
Point Cache Modifier (p. 26)
Point_Cache interfaces: (p. 484)
Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315)
Point_CacheSpacewarpModifier_interfaces_

PointCache interfaces:
This represents the interface to the PointCache Modifier.
Interface: pointCache
Methods:
Prototype:
<void>record()
Remarks:
This method will press the Record button in the rollup interface.
Prototype:
<void>setCache()
Remarks:
This method will press the Set Cache button in the rollup interface.
Prototype:
<void>enableMods()
Remarks:
This method will press the Enable Modifiers Below button in the rollup interface.
Prototype:
<void>disableMods()
Remarks:
This method will press the Disable Modifiers Below button in the rollup interface.
 PointCacheWSM interfaces: 487

See Also
In The MAXSDK Help File
Class IpointCache

See Also
Point Cache Modifier (p. 26)
Point_Cache - superclass: modifier (p. 314)
Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315)
Point_CacheSpacewarpModifier interfaces: (p. 485)

PointCacheWSM interfaces:
This represents the interface to the PointCache Modifier.
Interface: pointCacheWSM
Methods:
Prototype:
<void>record()
Remarks:
This method will press the Record button in the rollup interface.
Prototype:
<void>setCache()
Remarks:
This method will press the Set Cache button in the rollup interface.
Prototype:
<void>enableMods()
Remarks:
This method will press the Enable Modifiers Below button in the rollup interface.
Prototype:
<void>disableMods()
Remarks:
This method will press the Disable Modifiers Below button in the rollup interface.

See Also
In The MAXSDK Help File
Class IPointCacheWSM
488 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
Point Cache Modifier (p. 26)
Point_Cache - superclass: modifier (p. 314)
Point_Cache interfaces: (p. 484)
Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315)
Point_CacheSpacewarpModifier_interfaces_

Position_Constraint interfaces:
Position_Constraint interfaces:
This class represents the interface to the Position Constraint.
Interface: constraints
Methods:
Prototype:
<integer>getNumTargets()
Remarks:
Returns the number of target nodes in the position target list.
Prototype:
<node>getTarget <index>index
Remarks:
Gets one of the position nodes that the position constraint controller targets, specified by
targetNumber.
Parameters:
<index>index
The node number in the position target list to be obtained.
Prototype:
<boolean>setTarget <node>target <index>index
Prototype:
<float>getWeight <index>index <time>time
Remarks:
Gets the weight of one of the position nodes that the position constraint controller targets, specified
by targetNumber, and time t.
Parameters:
<index>index
The node number in the position target list to set.
<time>time
 Position_Constraint interfaces: 489

Return Value:
Returns the position target weight if the targetNumber is relevant, 0.0f otherwise.
Prototype:
<boolean>setWeight <float>weight <index>index <time>time
Remarks:
Sets the weight of one of the position nodes that the position constraint controller follows, specified
by targetNumber, and time t.
Parameters:
<index>index
The node number in the position target list whose weight is to be set.
<float>weight
The weight to set.
<time>time
Return Value:
TRUE if there is more than one position target in the list and you are trying to set weight, FALSE
otherwise.
Prototype:
<boolean>appendTarget <node>target <float>weight
Remarks:
Appends the current position target list by one and appends.
Parameters:
<node>target
The node that is to be appended to the current position target list.
<float>weight
This is the weight that is to be assigned to the newly appended position target. The
default weight is 50.0.
Prototype:
<void>deleteTarget <integer>targetNumber
Remarks:
This method allows you to delete a specified target.
Parameters:
<integer>targetNumber
The node number in the position target list to delete.
Return Value:
TRUE if successful, otherwise FALSE.
490 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
In The MAXSDK Help File
Class IPosConstPosition

position_list interfaces:
This class represents the interface to the list controller.
Interface: list
Properties:
.count : integer : Read
.active : index : Read|Write
Methods:
Prototype:
<integer>getCount()
Remarks:
This method returns the number of items that appear in the List controllers list box.
Prototype:
<void>setActive <index>listIndex
Remarks:
This method allows you to sets the indexed item in the list active so its parameters appear in the
motion panel, and any input is directed to the indexed sub controller.
Parameters:
<index>listIndex
The index of the item to set as the active item.
Prototype:
<integer>getActive()
Remarks:
This method returns the index of the currently active item.
Prototype:
<void>delete <index>listIndex

Parameters:
<index>listIndex
The index of the item to delete from the list.
Remarks:
This method allows you to delete the indexed sub controller from the list.
Prototype:
<void>cut <index>listIndex
 position_list interfaces: 491

Parameters:
<index>listIndex
The index of the item you wish to cut.
Remarks:
This method allows you to cut the index sub controller from the list and stores it in the buffer to
paste later.
Prototype:
<void>paste <index>listIndex

Parameters:
<index>listIndex
The index of the slot to paste into.
Remarks:
This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.
Prototype:
<TSTR by value>getName <index>listIndex

Parameters:
<index>listIndex
The index of the item for which to get the name.
Remarks:
This method returns the class name of the indexed sub-controller if a user defined name doesn’t
exist.
Prototype:
<void>setName <index>listIndex <string>name

Parameters:
<index>listIndex
The index of the item.
<string>name
The name to set it to.
Remarks:
This method returns the class name of the indexed sub-controller if a user defined name doesn’t
exist.

See Also
In the MAXSDK Help File
Class IListControl
492 Chapter 1 | What’s New in 3ds max 4 MAXScript

Position_Reactor interfaces:
Position_Reactor interfaces:
Interface: reactions
Properties:
.editStateMode : boolean : Read|Write
.useCurve : boolean : Read|Write
methods:
<void>reactTo <maxObject>object
<boolean>create name:<string>
name default value: “scriptCreated”}
<boolean>delete <index>index
<integer>getCount()
<void>select <index>index
<index>getSelected()
<boolean>setStateToCurrent <index>index
<boolean>setFloatState <index>index <float>state
<boolean>setVectorState <index>index <point3>state
<boolean>setRotationState <index>index <quat>state
<boolean>setValueToCurrent <index>index
<boolean>setValueAsFloat <index>index <float>value
<boolean>setValueAsVector <index>index <point3>value
<boolean>setValueAsQuat <index>index <quat>value
<boolean>setInfluence <index>index <float>influence
<boolean>setStrength <index>index <float>strength
<boolean>setFalloff <index>index <float>influence
<void>setName <index>index <string>name
<string>getName <index>index
<float>getInfluence <index>index
<float>getStrength <index>index
<float>getFalloff <index>index
<enum>getType()
getType enums:
{#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}
<fpvalue by value>getState <index>index
<fpvalue by value>getValue <index>index
Actions:

Position_Wire interfaces:
This represents the interface for individual wire controllers.
Interface: wireController
Properties:
.numWires : integer : Read
This property returns the number of wires out of this controller (i.e. the number of
dependent params).
 Position_Wire interfaces: 493

.isMaster : boolean : Read

This property will return TRUE if the wire is a master predicate, otherwise it will return
FALSE.
.isSlave : boolean : Read
This method will return TRUE if the wire is a slave predicate, otherwise it will return
FALSE.
.isTwoWay : boolean : Read
This method will return TRUE if the wire is a two-way predicate, otherwise it will return
FALSE.
.slaveAnimation : control : Read|Write
This method returns a pointer to the slave animation controller.
This method allows you to set the slave animation controller.
Prototype:
<maxObject>getWireParent <index>index
Parameters:
<index>index
The index you wish to retrieve.
Return Value:
This method returns a pointer to the i-th dependent parameter parent.
Prototype:
<integer>getWireSubnum <index>index
Remarks:
This method returns the i-th dependent parameter subanim num in the animatable.
Parameters:
<index>index
The index of the subanim.
Return Value:
This method returns the i-th dependent parameter subanim num in the animatable.
Prototype:
<control>getCoController <index>index
Parameters:
<index>index
The index of the controller.
Return Value:
This method returns a pointer to the i-th CoController.
494 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<string>getExprText <index>index
Parameters:
<index>index
The index of the parameter.
Return Value:
This method returns the expression string of the i-th wire parameter.
Prototype:
<void>setExprText <index>index <string>text
Remarks:
This method allows you to set the expression string of the i-th wire parameter.
Parameters:
<index>index
The index of the parameter
<string>text
The expression you wish to set.

See Also
In The MAXSDK Help File
Class IBaseWireControl

PositionList interfaces:
This class represents the interface to the list controller.
Interface: list
Properties:
.count : integer : Read
.active : index : Read|Write
Methods:
Prototype:
<integer>getCount()
Remarks:
This method returns the number of items that appear in the List controllers list box.
Prototype:
<void>setActive <index>listIndex
Remarks:
This method allows you to sets the indexed item in the list active so its parameters appear in the
motion panel, and any input is directed to the indexed sub controller.
 PositionList interfaces: 495

Parameters:
<index>listIndex
The index of the item to set as the active item.
Prototype:
<integer>getActive()
Remarks:
This method returns the index of the currently active item.
Prototype:
<void>delete <index>listIndex
Remarks:
This method allows you to delete the indexed sub controller from the list.
Parameters:
<index>listIndex
The index of the item to delete from the list.
Prototype:
<void>cut <index>listIndex
Remarks:
This method allows you to cut the index sub controller from the list and stores it in the buffer to
paste later.
Parameters:
<index>listIndex
The index of the item you wish to cut.
Prototype:
<void>paste <index>listIndex
Remarks:
This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.
Parameters:
<index>listIndex
The index of the slot to paste into.
Prototype:
<TSTR by value>getName <index>listIndex
Remarks:
This method returns the class name of the indexed sub-controller if a user defined name doesn’t
exist.
Parameters:
<index>listIndex
The index of the item for which to get the name.
496 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<void>setName <index>listIndex <string>name
Remarks:
This method allows you to set the name of an indexed item.
Parameters:
<index>listIndex
The index of the item.
<string>name
The name to set it to.

See Also
In the MAXSDK Help File
Class IListControl

PositionReactor interfaces:
PositionReactor interfaces:
Interface: reactions
Properties:
.editStateMode : boolean : Read|Write
.useCurve : boolean : Read|Write
methods:
<void>reactTo <maxObject>object
<boolean>create name:<string>
name default value: “scriptCreated”}
<boolean>delete <index>index
<integer>getCount()
<void>select <index>index
<index>getSelected()
<boolean>setStateToCurrent <index>index
<boolean>setFloatState <index>index <float>state
<boolean>setVectorState <index>index <point3>state
<boolean>setRotationState <index>index <quat>state
<boolean>setValueToCurrent <index>index
<boolean>setValueAsFloat <index>index <float>value
<boolean>setValueAsVector <index>index <point3>value
<boolean>setValueAsQuat <index>index <quat>value
<boolean>setInfluence <index>index <float>influence
<boolean>setStrength <index>index <float>strength
<boolean>setFalloff <index>index <float>influence
<void>setName <index>index <string>name
<string>getName <index>index
<float>getInfluence <index>index
<float>getStrength <index>index
<float>getFalloff <index>index
<enum>getType()
 PositionSpring interfaces: 497

getType enums:
{#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}
<fpvalue by value>getState <index>index
<fpvalue by value>getValue <index>index
Actions:

PositionSpring interfaces:
Interface: Spring
Properties:
Methods:
Prototype:
<float>getMass()
Return Value:
Returns the mass.
Prototype:
<void>setMass <float>mass

Parameters:
<float>mass
Remarks:
Sets the mass. The mass of the object to which the Spring controller is applied. Increasing the mass
causes the “bouncing” spring motion to become more exaggerated.
Prototype:
<float>getDrag()
Return Value:
Returns the drag.
Prototype:
<void>setDrag <float>drag

Parameters:
<float>drag
Remarks:
Sets the drag. Acts as air friction on the spring motion. A low Drag setting results in a greater
“bouncing” effect, while a high Drag results in subdued bouncing. Default=1. Range=0 to 10.
Prototype:
<float>getTension <index>springIndex

Parameters:
<index>springIndex
498 Chapter 1 | What’s New in 3ds max 4 MAXScript

Return Value:
Gets the tension for the spring corresponding to the index.
Prototype:
<void>setTension <index>springIndex <float>tension

Parameters:
<index>springIndex
<float>tension
Remarks:
Sets the tension for the spring corresponding to the index. The “stiffness” of the virtual spring
between the controlled object and the highlighted spring object(s).
Prototype:
<float>getDampening <index>springIndex

Parameters:
<index>springIndex
Return Value:
Gets the dampening for the spring corresponding to the index.
Prototype:
<void>setDampening <index>springIndex <float>dampening

Parameters:
<index>springIndex
<float>dampening
Remarks:
Sets the dampening for the spring corresponding to the index. : Acts as a multiplier of an internal
factor that determines how quickly the object comes to rest. With the Self Influence spring,
changing Dampening has the same effect as changing Drag. With other springs, Dampening affects
only the movement caused by that spring. Internally, the dampening value is proportional to the
tension, so as you increase the tension and make the solution more stiff, the dampening is increased
to maintain system stability.
Prototype:
<boolean>addSpring <node>node

Parameters:
<node>node
Remarks:
Adds the node to the spring list.
Return Value:
Returns true if successful, false otherwise
 PositionSpring interfaces: 499

Prototype:
<integer>getSpringCount()
Return Value:
Returns the number of springs in the spring system.
Prototype:
<void>removeSpringByIndex <index>springIndex

Parameters:
<index>springIndex
Remarks:
Removes the spring corresponding to the index.
Prototype:
<void>removeSpring <node>node

Parameters:
<node>node
Remarks:
Removes the spring if the node is in the spring list.

See Also
PositionSpring interfaces: (p. 497)
Point3Spring interfaces: (p. 482)
SpringPoint3Controller interfaces: (p. 523)
SpringPoint3Controller - superclass: Point3Controller (p. 336)
SpringPositionController interfaces: (p. 526)
SpringPositionController - superclass: PositionController (p. 337)
Flex : Modifier (p. 1128)
Flex interfaces: (p. 438)
flexOps const StructDef (p. 235)
500 Chapter 1 | What’s New in 3ds max 4 MAXScript

radiusManip interfaces:
Interface: Manip
Properties:
.mouseState : enum : Read
mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}
Methods:
Prototype:
<void>clearGizmos()
Remarks:
This must be called at the beginning of the “updateGizmos” handler in order to clear the current
gizmo cache.
Prototype:
<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by
value>selColor

Parameters:
<mesh>mesh
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX
mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this
is to create an instance of a primitive and get the mesh from it.
The flags can be 0, or one or more of these values. If you want more than one flag to apply, then you
add the values together.
Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor
<point3 by value>selColor
Parameters:
<Interface>gizmo
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
 radiusManip interfaces: 501

gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a shape object. The gizmoShape can be created using functions from the
“manip” package, described below.
The flags can be 0, or one or more of these values. If you want more than one flag to apply, then you
add the values together.
Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by
value>unselColor <point3 by value>selColor
marker enums:
{#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond
|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

Parameters:
<enum>marker
<point3 by value>position
The position is a point in 3d space, or 2d screen space.
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
502 Chapter 1 | What’s New in 3ds max 4 MAXScript

gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
The position is a point in 3d space, or 2d screen space.
Prototype:
<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by
value>unselColor <point3 by value>selColor

Parameters:
<string>text
<point3 by value>position
<integer>flags
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the
mouse. It is used for display purposes only.
Prototype:
<ray by value>getLocalViewRay <point2 by value>m
Parameters:
<point2 by value>m
Return Value:
This function takes a mouse position and returns the ray that passes through that mouse position
in the direction of the view. It is returned in the local coordinates of the node that owns the
manipulator target.
Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip
Remarks:
Parameters:
<time>t
<&TSTR>toolTip
 RenderElementMgr interfaces: 503

RenderElementMgr interfaces:
Interface: RenderElementMgr
Prototype:
<boolean>AddRenderElement <maxObject>element
Parameters:
<maxObject>element
Remarks:
Adds a specific element.
Return Value:
Returns TRUE if Successful, FALSE otherwise
Prototype:
<boolean>RemoveRenderElement <maxObject>element
Parameters:
<maxObject>element
Remarks:
Removes a specific element.
Return Value:
Returns true is successful and false otherwise.
Prototype:
<void>RemoveAllRenderElements()
Remarks:
Removes all elements in the list.
Prototype:
<integer>NumRenderElements()
Return Value:
Returns number of elements in list
Prototype:
<maxObject>GetRenderElement <integer>index
Parameters:
<integer>index
Return Value:
Returns a specific element, index is 0 based.
Prototype:
<void>SetElementsActive <boolean>active
Parameters:
<boolean>active
504 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
Sets a boolean indicating elements are active, ie. will be created during a render.
Prototype:
<boolean>GetElementsActive()
Return Value:
Gets a boolean indicating elements are active, ie. will be created during a render.
Prototype:
<void>SetDisplayElements <boolean>display
Parameters:
<boolean>display
Remarks:
Sets boolean indicating elements will be displayed after they are created.
Prototype:
<boolean>GetDisplayElements()
Return Value:
Gets boolean indicating elements will be displayed after they are created.
Prototype:
<void>SetCombustionOutputEnabled <boolean>enabled
Parameters:
<boolean>enabled
Remarks:
Enables or disables output to combustion .cws file.
Prototype:
<boolean>GetCombustionOutputEnabled()
Return Value:
Gets boolean indicating enabled output to combustion .cws file.
Prototype:
<void>SetCombustionOutputPath <string>pathname
Parameters:
<string>pathname
Remarks:
Sets the filename of the .cws file.
Prototype:
<string>GetCombustionOutputPath()
Return Value:
Gets the filename of the .cws file.
 rotation_list interfaces: 505

Example:
-- set a list of render elements.
elementlist =
#(specular,diffuse,self_illumination,reflection,refraction,shadowrenderelement,atm
osphere,blend,z_depth,alpha,colored_shadow,backgroundrenderelement)
re = maxOps.GetCurRenderElementMgr() -- get the current render element manager
re.removeallrenderelements() -- remove all renderelements
re.numrenderelements() -- get number of render elements
prod = maxOps.GetRenderElementMgr #Production
draft = maxOps.GetRenderElementMgr #Draft
prod.numrenderelements()
draft.numrenderelements()
-- adds all renderelements to be rendered.
for n in elementlist do
(
re.addrenderelement (n elementname:(”foo_” + (n as string)))
format “\nAdded % renderelement” n
)
rendoutputfilename = “c:\\test.tga”
rendsavefile = true
setsilentmode true -- used to avoid error message when checking the filename of
element
-- get all render elements set and return name of render element and output
filename
for n = 0 to (prod.numrenderelements()- 1) do
(
el = re.getrenderelement n
format “\nGetting % render element” el.elementname
format “\nRender element outputfilename: %” el.bitmap.filename
--el.filename
)

See Also
maxOps (p. 87)

rotation_list interfaces:
This represents the interface to the list controller.
Interface: list
Properties:
.count : integer : Read
.active : index : Read|Write
Methods:
Prototype:
<integer>getCount()
506 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method returns the number of items that appear in the List controllers list box.
Prototype:
<void>setActive <index>listIndex
Remarks:
This method allows you to sets the indexed item in the list active so its parameters appear in the
motion panel, and any input is directed to the indexed sub controller.
Parameters:
<index>listIndex
The index of the item to set as the active item.
Prototype:
<integer>getActive()
Remarks:
This method returns the index of the currently active item.
Prototype:
<void>delete <index>listIndex
Remarks:
This method allows you to delete the indexed sub controller from the list.
Parameters:
<index>listIndex
The index of the item to delete from the list.
Prototype:
<void>cut <index>listIndex
Remarks:
This method allows you to cut the index sub controller from the list and stores it in the buffer to
paste later.
Parameters:
<index>listIndex
The index of the item you wish to cut.
Prototype:
<void>paste <index>listIndex
Remarks:
This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.
Parameters:
<index>listIndex
The index of the slot to paste into.
 Rotation_Reactor interfaces: 507

Prototype:
<TSTR by value>getName <index>listIndex
Remarks:
This method returns the class name of the indexed sub-controller if a user defined name doesn’t
exist.
Parameters:
<index>listIndex
The index of the item for which to get the name.
Prototype:
<void>setName <index>listIndex <string>name
Remarks:
This method allows you to set the name of an indexed item.
Parameters:
<index>listIndex
The index of the item.
<string>name
The name to set it to.

See Also
In the MAXSDK Help File
Class IListControl

Rotation_Reactor interfaces:
Rotation_Reactor interfaces:
Interface: reactions
Properties:
.editStateMode : boolean : Read|Write
.useCurve : boolean : Read|Write
Methods:
<void>reactTo <maxObject>object
<boolean>create name:<string>
name default value: “scriptCreated”}
<boolean>delete <index>index
<integer>getCount()
<void>select <index>index
<index>getSelected()
<boolean>setStateToCurrent <index>index
<boolean>setFloatState <index>index <float>state
<boolean>setVectorState <index>index <point3>state
<boolean>setRotationState <index>index <quat>state
<boolean>setValueToCurrent <index>index
<boolean>setValueAsFloat <index>index <float>value
<boolean>setValueAsVector <index>index <point3>value
508 Chapter 1 | What’s New in 3ds max 4 MAXScript

<boolean>setValueAsQuat <index>index <quat>value

<boolean>setInfluence <index>index <float>influence
<boolean>setStrength <index>index <float>strength
<boolean>setFalloff <index>index <float>influence
<void>setName <index>index <string>name
<string>getName <index>index
<float>getInfluence <index>index
<float>getStrength <index>index
<float>getFalloff <index>index
<enum>getType()
getType enums:
{#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}
<fpvalue by value>getState <index>index
<fpvalue by value>getValue <index>index
Actions:

Rotation_Wire interfaces:
This represents the interface for individual wire controllers.
Interface: wireController
Properties:
.numWires : integer : Read
This property returns the number of wires out of this controller (i.e. the number of
dependent params).
.isMaster : boolean : Read
This property will return TRUE if the wire is a master predicate, otherwise it will return
FALSE.
.isSlave : boolean : Read
This method will return TRUE if the wire is a slave predicate, otherwise it will return
FALSE.
.isTwoWay : boolean : Read
This method will return TRUE if the wire is a two-way predicate, otherwise it will return
FALSE.
.slaveAnimation : control : Read|Write
This method returns a pointer to the slave animation controller.
This method allows you to set the slave animation controller.
Prototype:
<maxObject>getWireParent <index>index
Parameters:
<index>index
The index you wish to retrieve.
Return Value:
This method returns a pointer to the i-th dependent parameter parent.
 Rotation_Wire interfaces: 509

Prototype:
<integer>getWireSubnum <index>index
Remarks:
This method returns the i-th dependent parameter subanim num in the animatable.
Parameters:
<index>index
The index of the subanim.
Return Value:
This method returns the i-th dependent parameter subanim num in the animatable.
Prototype:
<control>getCoController <index>index
Parameters:
<index>index
The index of the controller.
Return Value:
This method returns a pointer to the i-th CoController.
Prototype:
<string>getExprText <index>index
Parameters:
<index>index
The index of the parameter.
Return Value:
This method returns the expression string of the i-th wire parameter.
Prototype:
<void>setExprText <index>index <string>text
Remarks:
This method allows you to set the expression string of the i-th wire parameter.
Parameters:
<index>index
The index of the parameter
<string>text
The expression you wish to set.

See Also
In The MAXSDK Help File
Class IBaseWireControl
510 Chapter 1 | What’s New in 3ds max 4 MAXScript

RotationList interfaces:
This class represents the interface to the list controller.
Interface: list
Properties:
.count : integer : Read
.active : index : Read|Write
Methods:
Prototype:
<integer>getCount()
Remarks:
This method returns the number of items that appear in the List controllers list box.
Prototype:
<void>setActive <index>listIndex
Remarks:
This method allows you to sets the indexed item in the list active so its parameters appear in the
motion panel, and any input is directed to the indexed sub controller.
Parameters:
<index>listIndex
The index of the item to set as the active item.
Prototype:
<integer>getActive()
Remarks:
This method returns the index of the currently active item.
Prototype:
<void>delete <index>listIndex
Remarks:
This method allows you to delete the indexed sub controller from the list.
Parameters:
<index>listIndex
The index of the item to delete from the list.
Prototype:
<void>cut <index>listIndex
Remarks:
This method allows you to cut the index sub controller from the list and stores it in the buffer to
paste later.
 RotationList interfaces: 511

Parameters:
<index>listIndex
The index of the item you wish to cut.
Prototype:
<void>paste <index>listIndex
Remarks:
This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.
Parameters:
<index>listIndex
The index of the slot to paste into.
Prototype:
<TSTR by value>getName <index>listIndex
Remarks:
This method returns the class name of the indexed sub-controller if a user defined name doesn’t
exist.
Parameters:
<index>listIndex
The index of the item for which to get the name.
Prototype:
<void>setName <index>listIndex <string>name
Remarks:
This method allows you to set the name of an indexed item.
Parameters:
<index>listIndex
The index of the item.
<string>name
The name to set it to.

See Also
In the MAXSDK Help File
Class IListControl
512 Chapter 1 | What’s New in 3ds max 4 MAXScript

RotationReactor interfaces:
RotationReactor interfaces:
Interface: reactions
Properties:
.editStateMode : boolean : Read|Write
.useCurve : boolean : Read|Write
methods:
<void>reactTo <maxObject>object
<boolean>create name:<string>
name default value: “scriptCreated”}
<boolean>delete <index>index
<integer>getCount()
<void>select <index>index
<index>getSelected()
<boolean>setStateToCurrent <index>index
<boolean>setFloatState <index>index <float>state
<boolean>setVectorState <index>index <point3>state
<boolean>setRotationState <index>index <quat>state
<boolean>setValueToCurrent <index>index
<boolean>setValueAsFloat <index>index <float>value
<boolean>setValueAsVector <index>index <point3>value
<boolean>setValueAsQuat <index>index <quat>value
<boolean>setInfluence <index>index <float>influence
<boolean>setStrength <index>index <float>strength
<boolean>setFalloff <index>index <float>influence
<void>setName <index>index <string>name
<string>getName <index>index
<float>getInfluence <index>index
<float>getStrength <index>index
<float>getFalloff <index>index
<enum>getType()
getType enums:
{#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}
<fpvalue by value>getState <index>index
<fpvalue by value>getValue <index>index
Actions:
 scale_list interfaces: 513

scale_list interfaces:
This class represents the interface to the list controller.
Interface: list
Properties:
.count : integer : Read
.active : index : Read|Write

Methods:
Prototype:
<integer>getCount()
Remarks:
This method returns the number of items that appear in the List controllers list box.
Prototype:
<void>setActive <index>listIndex
Remarks:
This method allows you to sets the indexed item in the list active so its parameters appear in the
motion panel, and any input is directed to the indexed sub controller.
Parameters:
<index>listIndex
The index of the item to set as the active item.
Prototype:
<integer>getActive()
Remarks:
This method returns the index of the currently active item.
Prototype:
<void>delete <index>listIndex
Remarks:
This method allows you to delete the indexed sub controller from the list.
Parameters:
<index>listIndex
The index of the item to delete from the list.
Prototype:
<void>cut <index>listIndex
Remarks:
This method allows you to cut the index sub controller from the list and stores it in the buffer to
paste later.
514 Chapter 1 | What’s New in 3ds max 4 MAXScript

Parameters:
<index>listIndex
The index of the item you wish to cut.
Prototype:
<void>paste <index>listIndex
Remarks:
This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.
Parameters:
<index>listIndex
The index of the slot to paste into.
Prototype:
<TSTR by value>getName <index>listIndex
Remarks:
This method returns the class name of the indexed sub-controller if a user defined name doesn’t
exist.
Parameters:
<index>listIndex
The index of the item for which to get the name.
Prototype:
<void>setName <index>listIndex <string>name
Remarks:
This method allows you to set the name of an indexed item.
Parameters:
<index>listIndex
The index of the item.
<string>name
The name to set it to.

See Also
In the MAXSDK Help File
Class IListControl
 Scale_Reactor interfaces: 515

Scale_Reactor interfaces:
Scale_Reactor interfaces:
Interface: reactions
Properties:
.editStateMode : boolean : Read|Write
.useCurve : boolean : Read|Write
methods:
<void>reactTo <maxObject>object
<boolean>create name:<string>
name default value: “scriptCreated”}
<boolean>delete <index>index
<integer>getCount()
<void>select <index>index
<index>getSelected()
<boolean>setStateToCurrent <index>index
<boolean>setFloatState <index>index <float>state
<boolean>setVectorState <index>index <point3>state
<boolean>setRotationState <index>index <quat>state
<boolean>setValueToCurrent <index>index
<boolean>setValueAsFloat <index>index <float>value
<boolean>setValueAsVector <index>index <point3>value
<boolean>setValueAsQuat <index>index <quat>value
<boolean>setInfluence <index>index <float>influence
<boolean>setStrength <index>index <float>strength
<boolean>setFalloff <index>index <float>influence
<void>setName <index>index <string>name
<string>getName <index>index
<float>getInfluence <index>index
<float>getStrength <index>index
<float>getFalloff <index>index
<enum>getType()
getType enums:
{#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}
<fpvalue by value>getState <index>index
<fpvalue by value>getValue <index>index
Actions:

Scale_Wire interfaces:
This represents the interface for individual wire controllers.
Interface: wireController
Properties:
.numWires : integer : Read
This property returns the number of wires out of this controller (i.e. the number of
dependent params).
516 Chapter 1 | What’s New in 3ds max 4 MAXScript

.isMaster : boolean : Read

This property will return TRUE if the wire is a master predicate, otherwise it will return
FALSE.
.isSlave : boolean : Read
This method will return TRUE if the wire is a slave predicate, otherwise it will return
FALSE.
.isTwoWay : boolean : Read
This method will return TRUE if the wire is a two-way predicate, otherwise it will return
FALSE.
.slaveAnimation : control : Read|Write
This method returns a pointer to the slave animation controller.
This method allows you to set the slave animation controller.
Prototype:
<maxObject>getWireParent <index>index
Parameters:
<index>index
The index you wish to retrieve.
Return Value:
This method returns a pointer to the i-th dependent parameter parent.
Prototype:
<integer>getWireSubnum <index>index
Remarks:
This method returns the i-th dependent parameter subanim num in the animatable.
Parameters:
<index>index
The index of the subanim.
Return Value:
This method returns the i-th dependent parameter subanim num in the animatable.
Prototype:
<control>getCoController <index>index
Parameters:
<index>index
The index of the controller.
Return Value:
This method returns a pointer to the i-th CoController.
 ScaleList interfaces: 517

Prototype:
<string>getExprText <index>index
Parameters:
<index>index
The index of the parameter.
Return Value:
This method returns the expression string of the i-th wire parameter.
Prototype:
<void>setExprText <index>index <string>text
Remarks:
This method allows you to set the expression string of the i-th wire parameter.
Parameters:
<index>index
The index of the parameter
<string>text
The expression you wish to set.

See Also
In The MAXSDK Help File
Class IBaseWireControl

ScaleList interfaces:
This class represents the interface to the list controller.
Interface: list
Properties:
.count : integer : Read
.active : index : Read|Write
Methods:
Prototype:
<integer>getCount()
Remarks:
This method returns the number of items that appear in the List controllers list box.
Prototype:
<void>setActive <index>listIndex
Remarks:
This method allows you to sets the indexed item in the list active so its parameters appear in the
motion panel, and any input is directed to the indexed sub controller.
518 Chapter 1 | What’s New in 3ds max 4 MAXScript

Parameters:
<index>listIndex
The index of the item to set as the active item.
Prototype:
<integer>getActive()
Remarks:
This method returns the index of the currently active item.
Prototype:
<void>delete <index>listIndex
Remarks:
This method allows you to delete the indexed sub controller from the list.
Parameters:
<index>listIndex
The index of the item to delete from the list.
Prototype:
<void>cut <index>listIndex
Remarks:
This method allows you to cut the index sub controller from the list and stores it in the buffer to
paste later.
Parameters:
<index>listIndex
The index of the item you wish to cut.
Prototype:
<void>paste <index>listIndex
Remarks:
This method allows you to paste the sub-controller from the buffer into the indexed slot in the list.
Parameters:
<index>listIndex
The index of the slot to paste into.
Prototype:
<TSTR by value>getName <index>listIndex
Remarks:
This method returns the class name of the indexed sub-controller if a user defined name doesn’t
exist.
Parameters:
<index>listIndex
The index of the item for which to get the name.
 ScaleReactor interfaces: 519

Prototype:
<void>setName <index>listIndex <string>name
Remarks:
This method allows you to set the name of an indexed item.
Parameters:
<index>listIndex
The index of the item.
<string>name
The name to set it to.

See Also
In the MAXSDK Help File
Class IListControl

ScaleReactor interfaces:
ScaleReactor interfaces:
Interface: reactions
Properties:
.editStateMode : boolean : Read|Write
.useCurve : boolean : Read|Write
methods:
<void>reactTo <maxObject>object
<boolean>create name:<string>
name default value: “scriptCreated”}
<boolean>delete <index>index
<integer>getCount()
<void>select <index>index
<index>getSelected()
<boolean>setStateToCurrent <index>index
<boolean>setFloatState <index>index <float>state
<boolean>setVectorState <index>index <point3>state
<boolean>setRotationState <index>index <quat>state
<boolean>setValueToCurrent <index>index
<boolean>setValueAsFloat <index>index <float>value
<boolean>setValueAsVector <index>index <point3>value
<boolean>setValueAsQuat <index>index <quat>value
<boolean>setInfluence <index>index <float>influence
<boolean>setStrength <index>index <float>strength
<boolean>setFalloff <index>index <float>influence
<void>setName <index>index <string>name
<string>getName <index>index
<float>getInfluence <index>index
<float>getStrength <index>index
<float>getFalloff <index>index
<enum>getType()
520 Chapter 1 | What’s New in 3ds max 4 MAXScript

getType enums:
{#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction}
<fpvalue by value>getState <index>index
<fpvalue by value>getValue <index>index
Actions:

sliderManipulator interfaces:
Interface: Manip
Scripted Manipulators (p. 97)
Properties:
.mouseState : enum : Read
mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}
Methods:
Prototype:
<void>clearGizmos()
Remarks:
This must be called at the beginning of the “updateGizmos” handler in order to clear the current
gizmo cache.
Prototype:
<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by
value>selColor

Parameters:
<mesh>mesh
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX
mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this
is to create an instance of a primitive and get the mesh from it.
The flags can be 0, or one or more of these value. If you want more than one flag to apply, then you
add the values together.
 sliderManipulator interfaces: 521

Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor
<point3 by value>selColor
Parameters:
<Interface>gizmo
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a shape object. The gizmoShape can be created using functions from the
“manip” package, described below.
Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by
value>unselColor <point3 by value>selColor
marker enums:
{#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond
|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

Parameters:

<enum>marker
<point3 by value>position
The position is a point in 3d space, or 2d screen space.
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
522 Chapter 1 | What’s New in 3ds max 4 MAXScript

gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by
addGizmoShape.
Prototype:
<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by
value>unselColor <point3 by value>selColor

Parameters:
<string>text
<point3 by value>position
<integer>flags
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the
mouse. It is used for display purposes only.
Prototype:
<ray by value>getLocalViewRay <point2 by value>m
Parameters:
<point2 by value>m
Return Value:
This function takes a mouse position and returns the ray that passes through that mouse position
in the direction of the view. It is returned in the local coordinates of the node that owns the
manipulator target.
Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip
Remarks:
Parameters:
<time>t
<&TSTR>toolTip
 SpringPoint3Controller interfaces: 523

See Also
Scripted Manipulators (p. 97)
Interface: manip (p. 366)
radiusManip interfaces: (p. 500)
ConeAngleManip - superclass: helper (p. 277)
PlaneAngleManip - superclass: helper (p. 311)
Scripted Plug-ins (p. 1538)
sliderManipulator - superclass: helper (p. 333)
sliderManipulator interfaces: (p. 520)
uvwMappingHeightManip interfaces: (p. 551)
uvwMappingLengthManip interfaces: (p. 555)
uvwMappingUTileManip interfaces: (p. 558)
uvwMappingVTileManip interfaces: (p. 562)
uvwMappingWidthManip interfaces: (p. 565)

SpringPoint3Controller interfaces:
Interface: Spring
Properties:
Methods:
Prototype:
<float>getMass()
Return Value:
Returns the mass.
Prototype:
<void>setMass <float>mass

Parameters:
<float>mass
Remarks:
Sets the mass. The mass of the object to which the Spring controller is applied. Increasing the mass
causes the “bouncing” spring motion to become more exaggerated.
Prototype:
<float>getDrag()
Return Value:
Returns the drag.
524 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<void>setDrag <float>drag

Parameters:
<float>drag
Remarks:
Sets the drag. Acts as air friction on the spring motion. A low Drag setting results in a greater
“bouncing” effect, while a high Drag results in subdued bouncing. Default=1. Range=0 to 10.
Prototype:
<float>getTension <index>springIndex

Parameters:
<index>springIndex
Return Value:
Gets the tension for the spring corresponding to the index.
Prototype:
<void>setTension <index>springIndex <float>tension

Parameters:
<index>springIndex
<float>tension
Remarks:
Sets the tension for the spring corresponding to the index. The “stiffness” of the virtual spring
between the controlled object and the highlighted spring object(s).
Prototype:
<float>getDampening <index>springIndex

Parameters:
<index>springIndex
Return Value:
Gets the dampening for the spring corresponding to the index.
Prototype:
<void>setDampening <index>springIndex <float>dampening

Parameters:
<index>springIndex
<float>dampening
Remarks:
Sets the dampening for the spring corresponding to the index. : Acts as a multiplier of an internal
factor that determines how quickly the object comes to rest. With the Self Influence spring,
 SpringPoint3Controller interfaces: 525

changing Dampening has the same effect as changing Drag. With other springs, Dampening affects
only the movement caused by that spring. Internally, the dampening value is proportional to the
tension, so as you increase the tension and make the solution more stiff, the dampening is increased
to maintain system stability.
Prototype:
<boolean>addSpring <node>node

Parameters:
<node>node
Remarks:
Adds the node to the spring list.
Return Value:
Returns true if successful, false otherwise
Prototype:
<integer>getSpringCount()
Return Value:
Returns the number of springs in the spring system.
Prototype:
<void>removeSpringByIndex <index>springIndex

Parameters:
<index>springIndex
Remarks:
Removes the spring corresponding to the index.
Prototype:
<void>removeSpring <node>node

Parameters:
<node>node
Remarks:
Removes the spring if the node is in the spring list.

See Also
PositionSpring interfaces: (p. 497)
Point3Spring interfaces: (p. 482)
SpringPoint3Controller interfaces: (p. 523)
SpringPoint3Controller - superclass: Point3Controller (p. 336)
SpringPositionController interfaces: (p. 526)
526 Chapter 1 | What’s New in 3ds max 4 MAXScript

SpringPositionController - superclass: PositionController (p. 337)

Flex : Modifier (p. 1128)
Flex interfaces: (p. 438)
flexOps const StructDef (p. 235)

SpringPositionController interfaces:
Interface: Spring
Properties:
Methods:
Prototype:
<float>getMass()
Return Value:
Returns the mass.
Prototype:
<void>setMass <float>mass

Parameters:
<float>mass
Remarks:
Sets the mass. The mass of the object to which the Spring controller is applied. Increasing the mass
causes the “bouncing” spring motion to become more exaggerated.
Prototype:
<float>getDrag()
Return Value:
Returns the drag.
Prototype:
<void>setDrag <float>drag

Parameters:
<float>drag
Remarks:
Sets the drag. Acts as air friction on the spring motion. A low Drag setting results in a greater
“bouncing” effect, while a high Drag results in subdued bouncing. Default=1. Range=0 to 10.
Prototype:
<float>getTension <index>springIndex
 SpringPositionController interfaces: 527

Parameters:
<index>springIndex
Return Value:
Gets the tension for the spring corresponding to the index.
Prototype:
<void>setTension <index>springIndex <float>tension

Parameters:
<index>springIndex
<float>tension
Remarks:
Sets the tension for the spring corresponding to the index. The “stiffness” of the virtual spring
between the controlled object and the highlighted spring object(s).
Prototype:
<float>getDampening <index>springIndex

Parameters:
<index>springIndex
Return Value:
Gets the dampening for the spring corresponding to the index.
Prototype:
<void>setDampening <index>springIndex <float>dampening

Parameters:
<index>springIndex
<float>dampening
Remarks:
Sets the dampening for the spring corresponding to the index. : Acts as a multiplier of an internal
factor that determines how quickly the object comes to rest. With the Self Influence spring,
changing Dampening has the same effect as changing Drag. With other springs, Dampening affects
only the movement caused by that spring. Internally, the dampening value is proportional to the
tension, so as you increase the tension and make the solution more stiff, the dampening is increased
to maintain system stability.
Prototype:
<boolean>addSpring <node>node

Parameters:
<node>node
Remarks:
Adds the node to the spring list.
528 Chapter 1 | What’s New in 3ds max 4 MAXScript

Return Value:
Returns true if successful, false otherwise
Prototype:
<integer>getSpringCount()
Return Value:
Returns the number of springs in the spring system.
Prototype:
<void>removeSpringByIndex <index>springIndex

Parameters:
<index>springIndex
Remarks:
Removes the spring corresponding to the index.
Prototype:
<void>removeSpring <node>node

Parameters:
<node>node
Remarks:
Removes the spring if the node is in the spring list.

See Also
PositionSpring interfaces: (p. 497)
Point3Spring interfaces: (p. 482)
SpringPoint3Controller interfaces: (p. 523)
SpringPoint3Controller - superclass: Point3Controller (p. 336)
SpringPositionController interfaces: (p. 526)
SpringPositionController - superclass: PositionController (p. 337)
Flex : Modifier (p. 1128)
Flex interfaces: (p. 438)
flexOps const StructDef (p. 235)
 Targa interfaces: 529

Targa interfaces:
This class represents the interface for the Bitmap IO TGA format.
Interface: itgaio
Methods:
Prototype:
<integer>getColorDepth()
Return Value:
This method returns the color depth, which would be 16, 24, or 32.
Prototype:
<void>setColorDepth <integer>colorDepth
Remarks:
This method allows you to set the color depth.
Parameters:
<integer>colorDepth
The color depth, being either 16, 24, or 32.
Prototype:
<boolean>getCompressed()
Return Value:
This method returns TRUE if the compression flag is set, otherwise FALSE.
Prototype:
<void>setCompressed <boolean>compression
Remarks:
This method allows you to set the compression flag.
Parameters:
<boolean>compression
TRUE to set the compression flag, otherwise FALSE.
Prototype:
<boolean>getAlphaSplit()
Return Value:
This method returns TRUE if the alpha split flag is set, otherwise FALSE.
Prototype:
<void>setAlphaSplit <boolean>alphaSplit
Remarks:
This method allows you to set the alpha split flag.
530 Chapter 1 | What’s New in 3ds max 4 MAXScript

Parameters:
<boolean>alphaSplit
TRUE to set the alpha split flag, otherwise FALSE.
Prototype:
<boolean>getPreMultAlpha()
Return Value:
This method returns TRUE if the premultiplied alpha flag is set, otherwise FALSE.
Prototype:
<void>setPreMultAlpha <boolean>preMultAlpha
Remarks:
This method allows you to set the premultiplied alpha flag.
Parameters:
<boolean>preMultAlpha
TRUE to set the premultiplied alpha flag, otherwise FALSE.

See Also
In The MAXSDK Help File
Class IBitmapIO_Tga

Unwrap_UVW interfaces:
This class represents the interface to the UVW Unwrap Modifier.
Interface: unwrap
Methods:
Prototype:
<void>planarMap()
Remarks:
This method will press the Planar Map button in the rollup interface.
Prototype:
<void>save()
Remarks:
This method will press the Save button in the rollup interface.
Prototype:
<void>load()
Remarks:
This method will press the Load button in the rollup interface.
 Unwrap_UVW interfaces: 531

Prototype:
<void>reset()
Remarks:
This method will press the Reset button in the rollup interface.
Prototype:
<void>edit()
Remarks:
This method will press the Edit button in the rollup interface.
Prototype:
<void>setMapChannel <integer>mapChannel
Remarks:
This method will set the Map Channel field value in the rollup.
Parameters:
<integer>mapChannel
The Map Channel you want to set to.
Prototype:
<integer>getMapChannel()
Return Value:
This method will return the Map Channel field in the rollup.
Prototype:
<void>setProjectionType <integer>mapChannel

Parameters:
<integer>mapChannel
The mapping type:
1 for X aligned
2 for Y aligned
3 for Z aligned
4 for normal aligned.
Remarks:
This method will set the mapping type.
Prototype:
<integer>getProjectionType()
Return Value:
This method will return the mapping type; 1 for X aligned, 2 for Y aligned, 3 for Z aligned, 4 for
normal aligned.
Prototype:
<void>setVC <boolean>vertexColor
532 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method will set the Vertex Color Channel radio button in the rollup interface.
Parameters:
<boolean>vertexColor
TRUE to enable; FALSE to disable.
Prototype:
<boolean>getVC()
Return Value:
This method returns the current state of the Vertex Color Channel radio button in the rollup
interface.
Prototype:
<void>move()
Remarks:
This method will press the Move button in the edit floater.
Prototype:
<void>moveh()
Remarks:
This method will press the Move Horizontal button in the edit floater.
Prototype:
<void>movev()
Remarks:
This method will press the Move Vertical button in the edit floater.
Prototype:
<void>rotate()
Remarks:
This method will press the Rotate button in the edit floater.
Prototype:
<void>scale()
Remarks:
This method will press the Scale button in the edit floater.
Prototype:
<void>scaleh()
Remarks:
This method will press the Scale Horizontal button in the edit floater.
Prototype:
<void>scalev()
 Unwrap_UVW interfaces: 533

Remarks:
This method will press the Scale Vertical button in the edit floater.
Prototype:
<void>mirrorH()
Remarks:
This method will press the Mirror Horizontal button in the edit floater.
Prototype:
<void>mirrorV()
Remarks:
This method will press the Mirror Vertical button in the edit floater.
Prototype:
<void>expandSelection()
Remarks:
This method will press the Expand Selection button in the edit floater.
Prototype:
<void>contractSelection()
Remarks:
This method will press the Contract Selection button in the edit floater.
Prototype:
<void>setFalloffType <integer>falloffType
Remarks:
This method will set the Falloff type.
Parameters:
<integer>falloffType
The falloff type; 1 for linear, 2 for sinual, 3 for fast, and 4 for slow.
Prototype:
<integer>getFalloffType()
Return Value:
This method will return the falloff type; 1 for linear, 2 for sinual, 3 for fast, and 4 for slow.
Prototype:
<void>setFalloffSpace <integer>falloffSpace
534 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method will set the space you want the falloff to be computed in.
Parameters:
<integer>falloffSpace
The falloff space; 1 for XY, the local space of the object, 2 for UV, the UVW space of
the object.
Prototype:
<integer>getFalloffSpace()
Return Value:
This method will return the falloff space; 1 for XY, the local space of the object, 2 for UV, the UVW
space of the object.
Prototype:
<void>setFalloffDist <float>falloffDist
Remarks:
This method will set the falloff distance in the edit floater.
Parameters:
<float>falloffDist
The falloff distance.
Prototype:
<float>getFalloffDist()
Return Value:
This method will return the falloff distance.
Prototype:
<void>breakSelected()
Remarks:
This method will press the Break Selected button in the edit floater.
Prototype:
<void>weld()
Remarks:
This method will press the Target Weld button in the edit floater.
Prototype:
<void>weldSelected()
Remarks:
This method will press the Weld Selected button in the edit floater.
Prototype:
<void>updateMap()
 Unwrap_UVW interfaces: 535

Remarks:
This method will press the Update Map button in the edit floater.
Prototype:
<void>DisplayMap <boolean>displayMap
Remarks:
This method sets the state of the Display Map button in the edit floater
Parameters:
<boolean>displayMap
TRUE to toggle the Display Map button on; FALSE to toggle it off.
Prototype:
<boolean>IsMapDisplayed()
Return Value:
This method returns the state of the Display Map button in the edit floater. TRUE if it’s on; FALSE if
it’s off.
Prototype:
<void>setUVSpace <integer>UVSpace
Remarks:
This method sets the space that you want to view the texture vertices in.
Parameters:
<integer>UVSpace
The texture space; 1 for UV, 2 for VW, 3 for UW.
Prototype:
<integer>getUVSpace()
Return Value:
This method returns the space that the texture vertices are viewed in; 1 for UV, 2 for VW, 3 for UW.
Prototype:
<void>options()
Remarks:
This method will press the Options button in the edit floater.
Prototype:
<void>lock()
Remarks:
This method will toggle the Lock Selected Vertices button in the edit floater.
Prototype:
<void>hide()
536 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method will press the Hide button in the edit floater.
Prototype:
<void>unhide()
Remarks:
This method will press the Unhide button in the edit floater.
Prototype:
<void>freeze()
Remarks:
This method will press the Freeze button in the edit floater.
Prototype:
<void>unfreeze()
Remarks:
This method will press the Unfreeze button in the edit floater.
Prototype:
<void>filterselected()
Remarks:
This method will press the Filter Selected Faces button in the edit floater.
Prototype:
<void>pan()
Remarks:
This method will press the Pan button in the edit floater.
Prototype:
<void>zoom()
Remarks:
This method will press the Zoom button in the edit floater.
Prototype:
<void>zoomRegion()
Remarks:
This method will press the Zoom Region button in the edit floater.
Prototype:
<void>fit()
Remarks:
This method will press the Fit button in the edit floater.
 Unwrap_UVW interfaces: 537

Prototype:
<void>fitselected()
Remarks:
This method will press the Fit Selected button in the edit floater.
Prototype:
<void>snap()
Remarks:
This method will press the Snap button in the edit floater.
Prototype:
<integer>getCurrentMap()
Return Value:
This method returns the index into the map drop down list of the current map in the view of the
edit floater.
Prototype:
<void>setCurrentMap <integer>map
Remarks:
This method sets the currently displayed map to the specified map index.
Parameters:
<integer>map
The index of the map in the drop down list to display.
Prototype:
<integer>numberMaps()
Return Value:
This method returns the number of maps in the map drop down list.
Prototype:
<point3>getLineColor()
Return Value:
This method returns the color of the lines used to connect the texture vertices edges as a Point3
pointer.
Prototype:
<void>setLineColor <point3>color
Remarks:
This method sets the line color of the texture vertices.
Parameters:
<point3>color
The color as a Point3.
538 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<point3>getSelectionColor()
Return Value:
This method returns the texture vertices selection color as Point3.
Prototype:
<void>setSelectionColor <point3>color
Remarks:
This method sets the color of selected texture vertices.
Parameters:
<point3>color
The color as a Point3.
Prototype:
<integer>getRenderWidth()
Return Value:
This method returns the width of the bitmap used to render 2d/3d textures to and if the Use Bitmap
Resolution bitmaps is not set the width used to render bitmap.
Prototype:
<void>setRenderWidth <integer>width
Remarks:
This method sets the width of the bitmap used to render to for display.
Parameters:
<integer>width
The width in pixels.
Prototype:
<integer>getRenderHeight()
Return Value:
This method returns the height of the bitmap used to render 2d/3d textures to and if the Use Bitmap
Resolution bitmaps is not set the height used to render bitmap.
Prototype:
<void>setRenderHeight <integer>height
Remarks:
This method sets the width of the bitmap used to render to for display.
Parameters:
<integer>height
The height in pixels.
Prototype:
<boolean>getUseBitmapRes()
 Unwrap_UVW interfaces: 539

Return Value:
This method returns the state of the Use Bitmap Resolution, if false the bitmaps are rendered using
the RenderWidth/Height values.
Prototype:
<void>setUseBitmapRes <boolean>useRes
Remarks:
This method sets the state of the Use Bitmap Resolution value. If it is false the bitmaps are rendered
using the RenderWidth/Height values.
Parameters:
<boolean>useRes
TRUE to toggle on; FALSE to toggle off.
Prototype:
<float>getWeldThreshold()
Return Value:
This method returns the weld threshold.
Prototype:
<void>setWeldThreshold <float>height
Remarks:
This method sets the threshold values for welds.
Parameters:
<float>height
The welding threshold/
Prototype:
<boolean>getConstantUpdate()
Return Value:
This method returns the state of the Constant Update value which when set true forces the veiwport
to be updated on every move, otherwise it is just updated on mouse up.
Prototype:
<void>setConstantUpdate <boolean>update
Remarks:
This method Sets the state of the Constant Update value which when set true forces the viewport to
be updated on every move, otherwise it is just updated on mouse up.
Parameters:
<boolean>update
TRUE to toggle on; FALSE to toggle off.
Prototype:
<boolean>getShowSelectedVertices()
540 Chapter 1 | What’s New in 3ds max 4 MAXScript

Return Value:
This method returns whether the selected texture vertices are also displayed in the view port.
Prototype:
<void>setShowSelectedVertices <boolean>show
Remarks:
This method sets whether the selected texture vertices are also displayed in the view port.
Parameters:
<boolean>show
TRUE to toggle on; FALSE to toggle off.
Prototype:
<boolean>getMidPixelSnap()
Return Value:
This method returns whether the mid pixels snap is used, if it is false the snap is set to the bottom
right corner of the pixel, else it snaps to the center of the pixel.
Prototype:
<void>setMidPixelSnap <boolean>snap
Remarks:
This method sets whether the mid pixels snap is used, if it is false the snap is set to the bottom right
corner of the pixel, else it snaps to the center of the pixel.
Parameters:
<boolean>snap
TRUE to toggle on; FALSE to toggle off.
Prototype:
<integer>getMatID()
Return Value:
This method returns the current material id index filter.
Prototype:
<void>setMatID <integer>matid
Remarks:
This method sets the material drop list to the index supplied.
Parameters:
<integer>matid
The material ID index to set.
Prototype:
<integer>numberMatIDs()
Return Value:
This method returns the number of material ids in the material id filter drop down.
 Unwrap_UVW interfaces: 541

Prototype:
<bitArray>getSelectedVertices()
Return Value:
This method returns the current selected texture vertices in the edit floater as a bit array.
Prototype:
<void>selectVertices <bitArray>selection
Remarks:
This method selects texture vertices in the edit floater dialog.
Parameters:
<bitArray>selection
The selection set as a bit array.
Prototype:
<boolean>isVertexSelected <integer>index

Parameters:
<integer>index
The index of the vertex to check.
Return Value:
This method returns whether a texture vertex is selected.
Prototype:
<void>MoveSelectedVertices <point3>offset
Remarks:
This method moves the selected texture vertices by the offset.
Parameters:
<point3>offset
The offset by which you want to move the vertices.
Prototype:
<void>RotateSelectedVerticesCenter <float>angle
Remarks:
This method rotates the selected vertices around their center point.
Parameters:
<float>angle
The angle in radians that you want to rotate the selection by.
Prototype:
<void>RotateSelectedVertices <float>angle <point3>axis
542 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method rotates the selected vertices around a specified point.
Parameters:
<float>angle
The angle in radians that you want to rotate the selection by.
<point3>axis
The axis that you want to rotate the selected vertices by. This is in the space of the
window.
Prototype:
<void>ScaleSelectedVerticesCenter <float>scale <integer>dir
Remarks:
This method scales the selected points around their center.
Parameters:
<float>scale
The amount that you want to scale by
<integer>dir
The direction; 1 for uniform scaling, 2 for X, and 3 for Y.
Prototype:
<void>ScaleSelectedVertices <float>scale <integer>dir <point3>axis
Remarks:
This method scales the selected points around a specified point.
Parameters:
<float>scale
The amount that you want to scale by
<integer>dir
The direction; 1 for uniform scaling, 2 for X, and 3 for Y.
<point3>axis
The axis that you want to scale the selected vertices by. This is in the space of the
window.
Prototype:
<point3>GetVertexPosition <time>time <integer>index

Parameters:
<time>time
The time at which you want to get the vertex.
<integer>index
The index of the vertex.
Return Value:
This method returns the position of the vertex.
 Unwrap_UVW interfaces: 543

Prototype:
<integer>numberVertices()
Return Value:
This method returns the number of texture vertices
Prototype:
<void>moveX <float>p
Remarks:
This method sets the selected vertices x values in absolute coordinates.
Parameters:
<float>p
The absolute position along the x axis
Prototype:
<void>moveY <float>p
Remarks:
This method sets the selected vertices y values in absolute coordinates.
Parameters:
<float>p
The absolute position along the y axis
Prototype:
<void>moveZ <float>p
Remarks:
This method sets the selected vertices z values in absolute coordinates.
Parameters:
<float>p
The absolute position along the s axis
Prototype:
<bitArray>getSelectedPolygons()
Return Value:
This method returns the selected polygons in the view port as a bit array.
Prototype:
<void>selectPolygons <bitArray>selection
Remarks:
This method selects the polygons in the view ports.
Parameters:
<bitArray>selection
The polygons you wish to select.
544 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<boolean>isPolygonSelected <integer>index

Parameters:
<integer>index
The index of the polygon to check.
Return Value:
This method returns whether a polygon is selected or not.
Prototype:
<integer>numberPolygons()
Return Value:
This method returns the number of polygons in the object.
Prototype:
<void>detachEdgeVertices()
Remarks:
This method detaches any vertex that is not completely surrounded by selected vertices. This is
similar to a polygon selection detach except it uses the vertex selection to determine what is
detached.
Prototype:
<void>flipHorizontal()
Remarks:
This method will press the Flip Horizontal button in the edit floater.
Prototype:
<void>flipVertical()
Remarks:
This method will press the Flip Vertical button in the edit floater.
Prototype:
<boolean>getLockAspect()
Remarks:
This method returns whether the edit window aspect ratio is locked or not, if the aspect ratio is not
locked the image will try stretch to fit the aspect ratio of the window.
Return Value:
TRUE if locked; FALSE if unlocked.
Prototype:
<void>setLockAspect <boolean>aspect
 Unwrap_UVW interfaces: 545

Remarks:
This method sets the Lock Aspect Ratio value
Parameters:
<boolean>aspect
TRUE to lock; FALSE to unlock.
Prototype:
<float>getMapScale()
Return Value:
This method returns the scaling factor when the user applies a planar map. The smaller the value
the more planar map is scaled down.
Prototype:
<void>setMapScale <float>scale
Remarks:
This method sets the scaling factor when the user applies a planar map. The smaller the value the
more planar map is scaled down
Parameters:
<float>scale
The scaling factor for planar map.
Prototype:
<void>getSelectionFromFace()
Remarks:
This method takes the current polygon selection and uses it to select the texture vertices that are
associated with it.
Prototype:
<void>forceUpdate <boolean>update

Remarks:
This method sets a flag to determines how Unwrap will behave when a topology change occurs. If
update is TRUE the mapping gets reset, otherwise unwrap skips mapping the object if it has a
different topology. It is sometimes useful to turn this off if you have MeshSmooth or other topology
changing modifiers below Unwrap that have different topologies when rendering.
Parameters:
<boolean>update
This determines whether the mapping is reset on topology change. TRUE to update,
otherwise FALSE.
Prototype:
<void>zoomToGizmo <boolean>all
546 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method zooms the selected or all the viewports to zoom to the current planar map gizmo.
Parameters:
<boolean>all
This determines whether the active or all the viewports get zoomed. TRUE to zoom all
viewports, FALSE to view the active viewport.
Prototype:
<void>setVertexPosition <time>time <integer>index <point3>pos
Remarks:
This method sets the position of a UVW vertex at a specific time.
Parameters:
<time>time
The time at what you want to set the position.
<integer>index
The index of the vertex.
<point3>pos
The position of the vertex in UVW space.
Prototype:
<void>markAsDead <integer>index
Remarks:
This method marks a vertex that it is dead, and no longer in use. Vertices are not actually deleted
they are just marked and recycled when needed. That means when a vertex is added vertices marked
as dead will be the first ones checked. If there are no dead vertices, the vertex is appended to the end
of the list. Using this function carefully since marking a vertex as dead that is actually in use will
cause strange results.
Parameters:
<integer>index
The index of the vertex to mark as dead.
Prototype:
<integer>numberPointsInFace <integer>index

Parameters:
<integer>index
The index of the face to inspect.
Return Value:
This method retrieves the numbers of vertices that a face contains. A face can contain 3 to N number
of points depending on what type of topology Unwrap is working on. For Tri Meshes this is always
3, for patches this can be 3 or 4, and for polygons this can be 3 or greater. Unwrap abstracts all three
object types into one generic format.
 Unwrap_UVW interfaces: 547

Prototype:
<integer>getVertexIndexFromFace <integer>faceIndex <integer>ithVertex
Parameters:
<integer>faceIndex
The index of the face to inspect.
<integer>ithVertex
The I-th vertex of that you want to retrieve. This value should range from 1 to the
number of vertices that the face contains.
Prototype:
<integer>getHandleIndexFromFace <integer>faceIndex <integer>ithVertex

Parameters:
<integer>faceIndex <integer>ithVertex
The index of the face to inspect.
<integer>ithVertex
The I-th handle of that you want to retrieve. This value should range from 1 to the
number of vertices*2 that the face contains.
Return Value:
This method retrieves the index of a handle, from a face. A face contains 0 to N number of handles.
So to retrieve a particular handle index, you give it the face index and the I-th handle that you want
to inspect. So if you wanted to look at the 3 handle on face 1 you would call
GetHandleIndexFromFace(1,3). This only applies for patch meshes.
Prototype:
<integer>getInteriorIndexFromFace <integer>faceIndex <integer>ithVertex

Parameters:
<integer>faceIndex
The index of the face to inspect.
<integer>ithVertex
The I-th interior handle of that you want to retrieve. This value should range from 1
to the number of vertices that the face contains.
Return Value:
This method retrieves the index of a interior handle, from a face. A face contains 0 to N number of
interior handles. So to retrieve a particular interior handle index, you give it the face index and the
I-th interior handle that you want to inspect. So if you wanted to look at the 3 interior handle on
face 1 you would call GetInteriorIndexFromFace(1,3). This only applies for patch meshes.
548 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<integer>getVertexGeomIndexFromFace <integer>faceIndex <integer>ithVertex

Parameters:
<integer>faceIndex
The index of the face to inspect.
<integer>ithVertex
The I-th vertex of that you want to retrieve. This value should range from 1 to the
number of vertices that the face contains.
Return Value:
This method retrieves the index of a geometric vertex, from a face. This the vertex that is attached
to the mesh and not the texture faces. A face contains 0 to N number of vertices. So to retrieve a
particular vertex index, you give it the face index and the I-th vertex that you want to inspect. So if
you wanted to look at the 3 vertex on face 1 you would call GetVertexGeomIndexFromFace(1,3).
Prototype:
<integer>getHandleGeomIndexFromFace <integer>faceIndex <integer>ithVertex

Parameters:
<integer>faceIndex
The index of the face to inspect.
<integer>ithVertex
The I-th handle of that you want to retrieve. This value should range from 1 to the
number of vertices*2 that the face contains.
Return Value:
This method retrieves the index of a geometric handle from a patch. This the handle that is attached
to the patch and not the texture faces. A face contains 0 to N number of handle. So to retrieve a
particular handle index, you give it the face index and the I-th handle that you want to inspect. So
if you wanted to look at the 3 handle on face 1 you would call GetHandleGeomIndexFromFace(1,3).
Prototype:
<integer>getInteriorGeomIndexFromFace <integer>faceIndex <integer>ithVertex

Parameters:
<integer>faceIndex
The index of the face to inspect.
<integer>ithVertex
The I-th interior handle of that you want to retrieve. This value should range from 1
to the number of vertices that the face contains.
Return Value:
This method retrieves the index of a geometric interior handle from a patch. This the interior handle
that is attached to the patch and not the texture faces. A face contains 0 to N number of interior
handle. So to retrieve a particular interior handle index, you give it the face index and the I-th
 Unwrap_UVW interfaces: 549

interior handle that you want to inspect. So if you wanted to look at the 3 interior handle on face 1
you would call GetInteriorGeomIndexFromFace(1,3).
Prototype:
<void>setFaceVertex <point3>pos <integer>faceIndex <integer>ithVertex <boolean>sel
Remarks:
This method allows you to manipulate the position of vertex attached to a face. Basically it
detaches the vertex if multiple faces share that vertex and then moves it to the position
specified. So if you want to move the 3rd vertex of face 1 to .5,.5,.0 you would do setFaceVertex
[.5 .5 .0] 1 3. If you don’t want the vertex broken use SetVertexSPosition.
Parameters:
<point3>pos
The position that you want to move a vertex to.
<integer>faceIndex
The index of the face that you wish to work on.
<integer>ithVertex
The ith vertex of the face that you want to change
<boolean>sel
Whether or not to select the vertex after it is recreated
Prototype:
<void>setFaceHandle <point3>pos <integer>faceIndex <integer>ithVertex <boolean>sel
Remarks:
This method is identical to SetFaceVertex except works on patch handles.
Parameters:
<point3>pos
The position that you want to move a vertex to.
<integer>faceIndex
The index of the face that you wish to work on.
<integer>ithVertex
The ith vertex of the face that you want to change
<boolean>sel
Whether or not to select the vertex after it is recreated
Prototype:
<void>setFaceInterior <point3>pos <integer>faceIndex <integer>ithVertex
<boolean>sel
Remarks:
This method is identical to SetFaceVertex except works on patch interior handles.
Parameters:
<point3>pos
The position that you want to move a vertex to.
550 Chapter 1 | What’s New in 3ds max 4 MAXScript

<integer>faceIndex
The index of the face that you wish to work on.
<integer>ithVertex
The ith vertex of the face that you want to change
<boolean>sel
Whether or not to select the vertex after it is recreated
Prototype:
<void>setFaceVertexIndex <integer>faceIndex <integer>ithVertex
<integer>vertexIndex
Remarks:
This method allows you to set the index of the ith vertex of a face.
Parameters:
<integer>faceIndex
The index of the face that you wish to work on.
<integer>ithVertex
The ith vertex of the face that you want to manipulate.
<integer>vertexIndex
The index into the vertex list that you want to set to
Prototype:
<void>setFaceHandleIndex <integer>faceIndex <integer>ithVertex
<integer>vertexIndex
Remarks:
This method is identical to setFaceVertexIndex but works on handles for patches.
Parameters:
<integer>faceIndex
The index of the face that you wish to work on.
<integer>ithVertex
The ith vertex of the face that you want to manipulate.
<integer>vertexIndex
The index into the vertex list that you want to set to
Prototype:
<void>setFaceInteriorIndex <integer>faceIndex <integer>ithVertex
<integer>vertexIndex
Remarks:
This method is identical to setFaceVertexIndex but works on interior handles for patches.
Parameters:
<integer>faceIndex
The index of the face that you wish to work on.
<integer>ithVertex
The ith vertex of the face that you want to manipulate.
 uvwMappingHeightManip interfaces: 551

<integer>vertexIndex
The index into the vertex list that you want to set to
Prototype:
<void>updateView()
Remarks:
This method forces the viewport and dialog to update.
Prototype:
<void>getFaceSelectionFromStack()
Remarks:
This method looks at the current face selection in the stack, and copies it to the unwrap face
selection. The reason this is useful is that if some one creates a new selection modifier Unwrap can
use it. An example would be if you applied to Unwrap to a whole editable mesh, then you went back
into the editable mesh, selected some faces by smoothing group, then turned off the face subobject
selection. If you went back to Unwrap you could get this selection by calling
getFaceSelectionFromStack.

See Also
In The MAXSDK Help File
Class IUnwrapMod

uvwMappingHeightManip interfaces:
Interface: Manip
Properties:
.mouseState : enum : Read
mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}
Methods:
Prototype:
<void>clearGizmos()
Remarks:
This must be called at the beginning of the “updateGizmos” handler in order to clear the current
gizmo cache.
552 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by
value>selColor

Parameters:
<mesh>mesh
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX
mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this
is to create an instance of a primitive and get the mesh from it.
The flags can be 0, or one or more of these values. If you want more than one flag to apply, then you
add the values together.
Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor
<point3 by value>selColor
Parameters:
<Interface>gizmo
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
 uvwMappingHeightManip interfaces: 553

Remarks:
This creates a gizmo from a shape object. The gizmoShape can be created using functions from the
“manip” package, described below.
The flags can take on the same value as for “addGizmoMesh”, with two new values supported:
Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3
by value>unselColor <point3 by value>selColor
marker enums:
{#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond
|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

Parameters:

<enum>marker
<point3 by value>position
The position is a point in 3d space, or 2d screen space.
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by
addGizmoShape.
554 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by
value>unselColor <point3 by value>selColor

Parameters:
<string>text
<point3 by value>position
<integer>flags
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the
mouse. It is used for display purposes only.
Prototype:
<ray by value>getLocalViewRay <point2 by value>m
Parameters:
<point2 by value>m
Return Value:
This function takes a mouse position and returns the ray that passes through that mouse position
in the direction of the view. It is returned in the local coordinates of the node that owns the
manipulator target.
Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip
Remarks:
Parameters:
<time>t
<&TSTR>toolTip
toolTip is In parameter

See Also
Scripted Manipulators (p. 97)
Interface: manip (p. 366)
radiusManip interfaces: (p. 500)
ConeAngleManip - superclass: helper (p. 277)
PlaneAngleManip - superclass: helper (p. 311)
Scripted Plug-ins (p. 1538)
sliderManipulator - superclass: helper (p. 333)
sliderManipulator interfaces: (p. 520)
uvwMappingHeightManip interfaces: (p. 551)
 uvwMappingLengthManip interfaces: 555

uvwMappingLengthManip interfaces: (p. 555)

uvwMappingUTileManip interfaces: (p. 558)
uvwMappingVTileManip interfaces: (p. 562)
uvwMappingWidthManip interfaces: (p. 565)

uvwMappingLengthManip interfaces:
Interface: Manip
Properties:
.mouseState : enum : Read
mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}
Methods:
Prototype:
<void>clearGizmos()
Remarks:
This must be called at the beginning of the “updateGizmos” handler in order to clear the current
gizmo cache.
Prototype:
<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by
value>selColor

Parameters:
<mesh>mesh
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX
mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this
is to create an instance of a primitive and get the mesh from it.
The flags can be 0, or one or more of these value. If you want more than one flag to apply, then you
add the values together.
556 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor
<point3 by value>selColor
Parameters:
<Interface>gizmo
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a shape object. The gizmoShape can be created using functions from the
“manip” package, described below.
The flags can take on the same value as for “addGizmoMesh”, with two new values supported:
Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3
by value>unselColor <point3 by value>selColor
marker enums:
{#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond
|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

Parameters:

<enum>marker
<point3 by value>position
The position is a point in 3d space, or 2d screen space.
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
 uvwMappingLengthManip interfaces: 557

gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by
addGizmoShape.
Prototype:
<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by
value>unselColor <point3 by value>selColor

Parameters:
<string>text
<point3 by value>position
<integer>flags
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the
mouse. It is used for display purposes only.
Prototype:
<ray by value>getLocalViewRay <point2 by value>m
Parameters:
<point2 by value>m
Return Value:
This function takes a mouse position and returns the ray that passes through that mouse position
in the direction of the view. It is returned in the local coordinates of the node that owns the
manipulator target.
Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip
Remarks:
Parameters:
<time>t
<&TSTR>toolTip
558 Chapter 1 | What’s New in 3ds max 4 MAXScript

See Also
Scripted Manipulators (p. 97)
Interface: manip (p. 366)
radiusManip interfaces: (p. 500)
ConeAngleManip - superclass: helper (p. 277)
PlaneAngleManip - superclass: helper (p. 311)
Scripted Plug-ins (p. 1538)
sliderManipulator - superclass: helper (p. 333)
sliderManipulator interfaces: (p. 520)
uvwMappingHeightManip interfaces: (p. 551)
uvwMappingLengthManip interfaces: (p. 555)
uvwMappingUTileManip interfaces: (p. 558)
uvwMappingVTileManip interfaces: (p. 562)
uvwMappingWidthManip interfaces: (p. 565)

uvwMappingUTileManip interfaces:
Interface: Manip
Properties:
.mouseState : enum : Read
mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}
Methods:
Prototype:
<void>clearGizmos()
Remarks:
This must be called at the beginning of the “updateGizmos” handler in order to clear the current
gizmo cache.
Prototype:
<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by
value>selColor

Parameters:
<mesh>mesh
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
 uvwMappingUTileManip interfaces: 559

gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX
mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this
is to create an instance of a primitive and get the mesh from it.
The flags can be 0, or one or more of these values. If you want more than one flag to apply, then you
add the values together.
Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor
<point3 by value>selColor
Parameters:
<Interface>gizmo
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a shape object. The gizmoShape can be created using functions from the
“manip” package, described below.
560 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3
by value>unselColor <point3 by value>selColor
marker enums:
{#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond
|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

Parameters:

<enum>marker
<point3 by value>position
selColor The position is a point in 3d space, or 2d screen space.
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
The creates a gizmo using a marker.
Prototype:
<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by
value>unselColor <point3 by value>selColor

Parameters:
<string>text
<point3 by value>position
<integer>flags
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the
mouse. It is used for display purposes only.
 uvwMappingUTileManip interfaces: 561

Prototype:
<ray by value>getLocalViewRay <point2 by value>m
Parameters:
<point2 by value>m
Return Value:
This function takes a mouse position and returns the ray that passes through that mouse position
in the direction of the view. It is returned in the local coordinates of the node that owns the
manipulator target.
Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip
Remarks:
Parameters:
<time>t
<&TSTR>toolTip

See Also
Scripted Manipulators (p. 97)
Interface: manip (p. 366)
radiusManip interfaces: (p. 500)
ConeAngleManip - superclass: helper (p. 277)
PlaneAngleManip - superclass: helper (p. 311)
Scripted Plug-ins (p. 1538)
sliderManipulator - superclass: helper (p. 333)
sliderManipulator interfaces: (p. 520)
uvwMappingHeightManip interfaces: (p. 551)
uvwMappingLengthManip interfaces: (p. 555)
uvwMappingUTileManip interfaces: (p. 558)
uvwMappingVTileManip interfaces: (p. 562)
uvwMappingWidthManip interfaces: (p. 565)
562 Chapter 1 | What’s New in 3ds max 4 MAXScript

uvwMappingVTileManip interfaces:
Interface: Manip
Properties:
.mouseState : enum : Read
mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}
Methods:
Prototype:
<void>clearGizmos()
Remarks:
This must be called at the beginning of the “updateGizmos” handler in order to clear the current
gizmo cache.
Prototype:
<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by
value>selColor

Parameters:
<mesh>mesh
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX
mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this
is to create an instance of a primitive and get the mesh from it.
The flags can be 0, or one or more of these values. If you want more than one flag to apply, then you
add the values together.
Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor
<point3 by value>selColor
Parameters:
<Interface>gizmo
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
 uvwMappingVTileManip interfaces: 563

gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a shape object. The gizmoShape can be created using functions from the
“manip” package, described below.
The flags can take on the same value as for “addGizmoMesh”, with two new values supported:
Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3
by value>unselColor <point3 by value>selColor
marker enums:
{#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond
|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

Parameters:

<enum>marker
<point3 by value>position
The position is a point in 3d space, or 2d screen space.
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
564 Chapter 1 | What’s New in 3ds max 4 MAXScript

gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
The creates a gizmo using a marker.
Prototype:
<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by
value>unselColor <point3 by value>selColor

Parameters:
<string>text
<point3 by value>position
<integer>flags
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the
mouse. It is used for display purposes only.
Prototype:
<ray by value>getLocalViewRay <point2 by value>m
Parameters:
<point2 by value>m
Return Value:
This function takes a mouse position and returns the ray that passes through that mouse position
in the direction of the view. It is returned in the local coordinates of the node that owns the
manipulator target.
Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip
Remarks:
Parameters:
<time>t
<&TSTR>toolTip
 uvwMappingWidthManip interfaces: 565

See Also
Scripted Manipulators (p. 97)
Interface: manip (p. 366)
radiusManip interfaces: (p. 500)
ConeAngleManip - superclass: helper (p. 277)
PlaneAngleManip - superclass: helper (p. 311)
Scripted Plug-ins (p. 1538)
sliderManipulator - superclass: helper (p. 333)
sliderManipulator interfaces: (p. 520)
uvwMappingHeightManip interfaces: (p. 551)
uvwMappingLengthManip interfaces: (p. 555)
uvwMappingUTileManip interfaces: (p. 558)
uvwMappingVTileManip interfaces: (p. 562)
uvwMappingWidthManip interfaces: (p. 565)

uvwMappingWidthManip interfaces:
Interface: Manip
Properties:
.mouseState : enum : Read
mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}
Methods:
Prototype:
<void>clearGizmos()
Remarks:
This must be called at the beginning of the “updateGizmos” handler in order to clear the current
gizmo cache.
Prototype:
<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by
value>selColor

Parameters:
<mesh>mesh
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
566 Chapter 1 | What’s New in 3ds max 4 MAXScript

gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX
mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this
is to create an instance of a primitive and get the mesh from it.
The flags can be 0, or one or more of these value. If you want more than one flag to apply, then you
add the values together.
Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor
<point3 by value>selColor

Parameters:
<Interface>gizmo
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo from a shape object. The gizmoShape can be created using functions from the
“manip” package, described below.
Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3
by value>unselColor <point3 by value>selColor
marker enums:
{#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond
|#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}
 uvwMappingWidthManip interfaces: 567

Parameters:

<enum>marker
<point3 by value>position
The position is a point in 3d space, or 2d screen space.
<integer>flags
gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest
Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device
coordinates in the viewport, not as 3d values. The values are still specified as 3d
points, but the “Z” coordinate is ignored.
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from
0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height
of the viewport.
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by
addGizmoShape.
Prototype:
<void>addGizmoText <string>text <point3 by value>position <integer>flags <point3 by
value>unselColor <point3 by value>selColor

Parameters:
<string>text
<point3 by value>position
<integer>flags
<point3 by value>unselColor
<point3 by value>selColor
Remarks:
This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the
mouse. It is used for display purposes only.
Prototype:
<ray by value>getLocalViewRay <point2 by value>m
Parameters:
<point2 by value>m
568 Chapter 1 | What’s New in 3ds max 4 MAXScript

Return Value:
This function takes a mouse position and returns the ray that passes through that mouse position
in the direction of the view. It is returned in the local coordinates of the node that owns the
manipulator target.
Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip
Remarks:
Parameters:
<time>t
<&TSTR>toolTip

See Also
Scripted Manipulators (p. 97)
Interface: manip (p. 366)
radiusManip interfaces: (p. 500)
ConeAngleManip - superclass: helper (p. 277)
PlaneAngleManip - superclass: helper (p. 311)
Scripted Plug-ins (p. 1538)
sliderManipulator - superclass: helper (p. 333)
sliderManipulator interfaces: (p. 520)
uvwMappingHeightManip interfaces: (p. 551)
uvwMappingLengthManip interfaces: (p. 555)
uvwMappingUTileManip interfaces: (p. 558)
uvwMappingVTileManip interfaces: (p. 562)
uvwMappingWidthManip interfaces: (p. 565)

UVWUnwrap interfaces:
See Also
Unwrap_UVW interfaces: (p. 530)
 Float_Wire interfaces: 569

Float_Wire interfaces:
This represents the interface for individual wire controllers.
Interface: wireController
Properties:
.numWires : integer : Read
This property returns the number of wires out of this controller (i.e. the number of
dependent params).
.isMaster : boolean : Read
This property will return TRUE if the wire is a master predicate, otherwise it will return
FALSE.
.isSlave : boolean : Read
This method will return TRUE if the wire is a slave predicate, otherwise it will return
FALSE.
.isTwoWay : boolean : Read
This method will return TRUE if the wire is a two-way predicate, otherwise it will return
FALSE.
.slaveAnimation : control : Read|Write
This method returns a pointer to the slave animation controller.
This method allows you to set the slave animation controller.
Prototype:
<maxObject>getWireParent <index>index
Parameters:
<index>index
The index you wish to retrieve.
Return Value:
This method returns a pointer to the i-th dependent parameter parent.
Prototype:
<integer>getWireSubnum <index>index
Remarks:
This method returns the i-th dependent parameter subanim num in the animatable.
Parameters:
<index>index
The index of the subanim.
Return Value:
This method returns the i-th dependent parameter subanim num in the animatable.
570 Chapter 1 | What’s New in 3ds max 4 MAXScript

Prototype:
<control>getCoController <index>index
Parameters:
<index>index
The index of the controller.
Return Value:
This method returns a pointer to the i-th CoController.
Prototype:
<string>getExprText <index>index
Parameters:
<index>index
The index of the parameter.
Return Value:
This method returns the expression string of the i-th wire parameter.
Prototype:
<void>setExprText <index>index <string>text
Remarks:
This method allows you to set the expression string of the i-th wire parameter.
Parameters:
<index>index
The index of the parameter
<string>text
The expression you wish to set.

See Also
In The MAXSDK Help File
Class IBaseWireControl

Point3_Wire interfaces:
Interface: wireController
Properties:
.numWires : integer : Read
This property returns the number of wires out of this controller (i.e. the number of
dependent params).
.isMaster : boolean : Read
This property will return TRUE if the wire is a master predicate, otherwise it will return
FALSE.
 Point3_Wire interfaces: 571

.isSlave : boolean : Read

This method will return TRUE if the wire is a slave predicate, otherwise it will return
FALSE.
.isTwoWay : boolean : Read
This method will return TRUE if the wire is a two-way predicate, otherwise it will return
FALSE.
.slaveAnimation : control : Read|Write
This method returns a pointer to the slave animation controller.
This method allows you to set the slave animation controller.
Prototype:
<maxObject>getWireParent <index>index
Parameters:
<index>index
The index you wish to retrieve.
Return Value:
This method returns a pointer to the i-th dependent parameter parent.
Prototype:
<integer>getWireSubnum <index>index

Parameters:
<index>index
The index of the subanim.
Remarks:
This method returns the i-th dependent parameter subanim num in the animatable.
Return Value:
This method returns the i-th dependent parameter subanim num in the animatable.
Prototype:
<control>getCoController <index>index
Parameters:
<index>index
The index of the controller.
Return Value:
This method returns a pointer to the i-th CoController.
Prototype:
<string>getExprText <index>index
Parameters:
<index>index
The index of the parameter.
572 Chapter 1 | What’s New in 3ds max 4 MAXScript

Return Value:
This method returns the expression string of the i-th wire parameter.
Prototype:
<void>setExprText <index>index <string>text

Parameters:
<index>index
The index of the parameter
<string>text
The expression you wish to set.
Remarks:
This method allows you to set the expression string of the i-th wire parameter.

See Also
In The MAXSDK Help File
Class IBaseWireControl

Rotation_Wire interfaces:
This represents the interface for individual wire controllers.
Interface: wireController
Properties:
.numWires : integer : Read
This property returns the number of wires out of this controller (i.e. the number of
dependent params).
.isMaster : boolean : Read
This property will return TRUE if the wire is a master predicate, otherwise it will return
FALSE.
.isSlave : boolean : Read
This method will return TRUE if the wire is a slave predicate, otherwise it will return
FALSE.
.isTwoWay : boolean : Read
This method will return TRUE if the wire is a two-way predicate, otherwise it will return
FALSE.
.slaveAnimation : control : Read|Write
This method returns a pointer to the slave animation controller.
This method allows you to set the slave animation controller.
 Rotation_Wire interfaces: 573

Prototype:
<maxObject>getWireParent <index>index
Parameters:
<index>index
The index you wish to retrieve.
Return Value:
This method returns a pointer to the i-th dependent parameter parent.
Prototype:
<integer>getWireSubnum <index>index
Remarks:
This method returns the i-th dependent parameter subanim num in the animatable.
Parameters:
<index>index
The index of the subanim.
Return Value:
This method returns the i-th dependent parameter subanim num in the animatable.
Prototype:
<control>getCoController <index>index
Parameters:
<index>index
The index of the controller.
Return Value:
This method returns a pointer to the i-th CoController.
Prototype:
<string>getExprText <index>index
Parameters:
<index>index
The index of the parameter.
Return Value:
This method returns the expression string of the i-th wire parameter.
Prototype:
<void>setExprText <index>index <string>text
574 Chapter 1 | What’s New in 3ds max 4 MAXScript

Remarks:
This method allows you to set the expression string of the i-th wire parameter.
Parameters:
<index>index
The index of the parameter
<string>text
The expression you wish to set.

See Also
In The MAXSDK Help File
Class IBaseWireControl

Scale_Wire interfaces:
This represents the interface for individual wire controllers.
Interface: wireController
Properties:
.numWires : integer : Read
This property returns the number of wires out of this controller (i.e. the number of
dependent params).
.isMaster : boolean : Read
This property will return TRUE if the wire is a master predicate, otherwise it will return
FALSE.
.isSlave : boolean : Read
This method will return TRUE if the wire is a slave predicate, otherwise it will return
FALSE.
.isTwoWay : boolean : Read
This method will return TRUE if the wire is a two-way predicate, otherwise it will return
FALSE.
.slaveAnimation : control : Read|Write
This method returns a pointer to the slave animation controller.
This method allows you to set the slave animation controller.
Prototype:
<maxObject>getWireParent <index>index
Parameters:
<index>index
The index you wish to retrieve.
Return Value:
This method returns a pointer to the i-th dependent parameter parent.
 Scale_Wire interfaces: 575

Prototype:
<integer>getWireSubnum <index>index
Remarks:
This method returns the i-th dependent parameter subanim num in the animatable.
Parameters:
<index>index
The index of the subanim.
Return Value:
This method returns the i-th dependent parameter subanim num in the animatable.
Prototype:
<control>getCoController <index>index
Parameters:
<index>index
The index of the controller.
Return Value:
This method returns a pointer to the i-th CoController.
Prototype:
<string>getExprText <index>index
Parameters:
<index>index
The index of the parameter.
Return Value:
This method returns the expression string of the i-th wire parameter.
Prototype:
<void>setExprText <index>index <string>text
Remarks:
This method allows you to set the expression string of the i-th wire parameter.
Parameters:
<index>index
The index of the parameter
<string>text
The expression you wish to set.

See Also
In The MAXSDK Help File
Class IBaseWireControl
576 Chapter 1 | What’s New in 3ds max 4 MAXScript
Chapter 2: Learning MAXScript

Welcome to Learning MAXScript. This introductory reference helps you get started using
MAXScript, the scripting language that is built into 3ds max.
Learning MAXScript can be used as an introductory reference. However, it is most useful if read
straight through as a tutorial. You can follow the examples in this reference by using drag-and-drop
or copy-and-paste to bring the code from this document into the MAXScript Listener. You can also
type in your own text and start experimenting with MAXScript as you learn it.

Getting Started
Accessing MAXScript (p. 579)
Source Code Layout (p. 580)
Entering Information into MAXScript (p. 582)
Assigning Variables (p. 585)
Mathematical Operations in MAXScript (p. 588)

Working with 3ds max Objects

Drawing a Box with MAXScript (p. 591)
Modifying the Box (p. 593)
Applying Standard Transformations (p. 598)
More Box Transformations (p. 603)

Creating Your Own Scripts

Controlling Program Flow in Scripts (p. 607)
Defining Custom Functions (p. 614)
Structure Definitions (p. 618)
3ds max Commands in MAXScript (p. 620)
578 Chapter 2 | Learning MAXScript

Where to Go From Here

Saving your Commands in a Script File (p. 621)
Loading and Running Your Script File (p. 621)
Loading Other Scripts (p. 623)
Learning MAXScript by Walking Through a Script (p. 623)
Learning MAXScript with the Macro Recorder (p. 624)

Some Advanced Topics Include:

Action Manager (p. 9)
ActiveX Controls in MAXScript Rollouts (p. 10)
Asset Browser enhancements (p. 22)
Curve Control (p. 170)
Customize The Order of Rollup Pages (p. 185)
General Event Callback Mechanism (p. 29)
iDrop - drag and drop (p. 62)
Interfaces (p. 67)
Menu Manager (p. 75)
Network Render Interface (p. 82)
Parameter Wiring (p. 85)
Quad Menu (p. 90)
Scripted Custom Attributes (p. 45)
Scripted Manipulators (p. 97)
Visual MAXScript (p. 117)
Zip-file Script Packages (p. 122)
 Accessing MAXScript 579

Accessing MAXScript
MAXScript is the built-in scripting language for 3ds max (version 2.0 or higher.) Because of this, you
can use MAXScript only when 3ds max is running. There are several ways to access MAXScript from
within 3ds max. The easiest way is to select MAXScript Listener from the MAXScript menu. The
other way to start MAXScript is as follows:

1. On the Command panel, choose Utility, and click MAXScript.

The MAXScript rollout appears:

2. Click Open Listener.

The MAXScript Listener window appears with its Welcome message:
580 Chapter 2 | Learning MAXScript

The MAXScript Listener window is an interactive interpreter for the MAXScript language and works
similarly to a DOS command prompt window. Enter MAXScript commands in this window, and
press ENTER to execute them immediately.
Only one instance of the MAXScript Listener window can be open at a time. The Listener is a
resizable, modeless window. You can switch between it and the software as you work. If you close
the Listener window and then reopen it, any text that was in the window before it was closed
reappears.
The Listener is divided into two panes. The top (pink) pane is the Macro Recorder pane; the bottom
(white) pane is the output pane. The Macro Recorder plane is hidden when the Listener is opened;
drag the splitter bar down to open it.
When the Macro Recorder is enabled, every recordable command is displayed in the Macro Recorder
pane. The output of results from scripts is displayed in the output pane. The output of code executed
in the Macro Recorder pane is always directed to the output pane to prevent cluttering the
recordings. Both panes allow you to cut-and-paste, drag-and-drop, edit, select, and execute code. You
can resize the panes by dragging on the split bar between them.
The left end of the status bar contains a resizable Mini Listener.

If the Mini Listener is not visible, drag on the vertical split bar at the left edge of the status panel to
reveal this feature. The Mini Listener panes act as single-line sliding windows for the current line in
corresponding Listener panes. The Mini Listener panes always show what you are typing or where
the cursor is placed in the Listener panes. Conversely, anything you enter into a Mini Listener pane
is entered into the corresponding Listener pane at the current cursor position.

To install Listener into a viewport:

1. Right-click the viewport label.
2. Choose Extended.
3. Choose MAXScript Listener.

Source Code Layout

The layout rules for MAXScript code are unlike those of most programming languages. MAXScript
gives you the advantage of freeform languages, such as C and C++, without the need for extensive
punctuation.
MAXScript lets you break statements and expressions across lines wherever you want. The line break
can be in the middle of an expression. MAXScript reads your code until the end of each line and
determines whether it has a complete expression. If it does not, it continues to read subsequent lines
until it finds the rest of the expression.
 Source Code Layout 581

Take as an example the following line:

a + b * c / d – e + f * g / h

This line can be broken after any of the operators. MAXScript continues to read the next line,
because an operator needs another argument. For example:
a + b * c / d – e +
f * g / h

You cannot break the example line as shown next and get the same result, because the expression
on the first line is a complete expression. MAXScript considers the two lines as separate expressions,
and the second line is now syntactically wrong, because it starts with an operator.
a + b * c / d – e
+ f * g / h

If you do want to break a line at the end of a sub-expression, you can use the backslash line
continuation character: ‘\’. The previous example of an invalid break can be made valid using the
line continuation character after the ‘e’:
a + b * c / d – e \
+ f * g / h

Whenever MAXScript encounters a ‘\’ as the last character on a line (except for spaces, tabs, or
comments), it continues to read the next line as though the break were not present. Line
continuations can be useful for breaking up long or complex lines of code, making them easier
to read.
MAXScript also lets you combine multiple statements and expressions in a single line. The
statements or expressions are separated with a ‘;’, for example:
582 Chapter 2 | Learning MAXScript

Sometimes it is useful to enter comments within your script to provide guidance or context. You can
enter comments in MAXScript by preceding your comment with a double-hyphen (‘--’). As soon as
MAXScript reaches the double-hyphen, it stops evaluating the rest of that line. For example:

Entering Information into MAXScript

There are several different types of information that you will typically want to enter into the
MAXScript Listener window. These include numeric values, strings, and arrays. Information is
generally entered into MAXScript by typing a value or expression and pressing ENTER. However,
each type of information must be entered in a slightly different way.

Entering Numbers in MAXScript

MAXScript distinguishes between two types of numbers: integers and floats. An integer is a whole
number, such as 0, 1, 2, 10, 527. Floats are floating-point numbers and contain decimal points, such
as 2.5, 72.0, and 0.33.
When MAXScript performs numerical operations, the result is generally the same number-type as
the arguments in the operation. For example: 3 + 4 will return 7, while 3.0 + 4.0 will return 7.0.
 Entering Information into MAXScript 583

When MAXScript performs operations involving both float and integer-type numbers however, it
treats the integer as a float number. For example: 3 + 4.0 will return 7.0.

Entering Strings in MAXScript

MAXScript is an expression-based language. All of its constructs yield a value. Strings are MAXScript
constructs, and they are entered inside quotation marks. The command output for a string, meaning
the value a string yields in MAXScript, is the string itself.
With the MAXScript Listener window open, say hello to MAXScript:
1. At the prompt, type Hello and press ENTER.
MAXScript answers with undefined. This is called command output, which always appears in
blue. The reason for this specific output is that MAXScript doesn’t know the word Hello. It is not
defined in the language and therefore MAXScript cannot determine what to do with it.
584 Chapter 2 | Learning MAXScript

2. Write the word “Hello” again, this time with quotation marks, and press ENTER.
The command output is now “Hello”.
It seems that MAXScript knows the string “Hello” because it answers with a friendly “Hello”.
Actually, it merely knows that you entered a string, and the command output for strings is
always the value of the string you entered.

Entering Arrays in MAXScript

You can use an array to group several elements into one collection. An array is an ordered collection
of values. In MAXScript, each element in the array can contain any type of value, and all of the
elements can be accessed individually.
An array can be expressed in two forms. The first is:
#()
This is the most basic type of array: an empty one. It is important to note that all arrays must be
defined with the pound character (#) and a pair of parentheses.
 Assigning Variables 585

#( <expr> , <expr> )
This form of the array is appropriate when you would like to define one or more of the initial
elements within the array. Each value of <expr> can be a number, an expression (e.g., sin pi, 6.2^3),
or a string (e.g., “hello”). Elements do not have to be the same type of information, and there is no
limit on the number of elements you can have in an array.

Assigning Variables
In the previous lesson, you entered the string “Hello” in MAXScript, and MAXScript displayed the
same string as its command output. When you enter other strings, MAXScript displays them and
forgets about the previous ones. To make MAXScript remember the value of a string, assign it to a
variable. The general syntax for assigning a variable in MAXScript is:
variable_name = variable_value
A variable_name starts with an alphabetic character or “_” (underscore), followed by any number
of alphanumeric characters. The variable_value can be a string, a number, or any other
expression.
586 Chapter 2 | Learning MAXScript

To assign a string to a variable:

1. At the Listener prompt, enter the following command:
mystring = “This is my string.”

MAXScript returns the value of the string variable:

2. You can now refer to this string variable by entering the variable’s name. Enter mystring.
MAXScript again returns the value of the string variable:

This is faster than entering the string again. MAXScript remembers this string for as long as your
MAXScript session is open, or until you change the variable’s value.
 Assigning Variables 587

To assign a new value to an existing variable:

1. Enter mystring = “This is not your string.”
MAXScript now displays the new value of mystring:

2. When you refer to mystring now, MAXScript uses the new value. Enter mystring.
MAXScript now displays the new variable value:

Notice that MAXScript doesn’t distinguish between lowercase and uppercase variable names
because MAXScript names are not case-sensitive.
588 Chapter 2 | Learning MAXScript

Mathematical Operations in MAXScript

Besides strings, you can enter other types of data into MAXScript. MAXScript not only recognizes
numeric characters as numbers, it can also perform mathematical operations with them. As with
strings, if you just enter a number by itself, MAXScript echoes it back to you; it evaluates the number
and displays its value. Mathematical operations are more interesting.

Basic Mathematical Operations

MAXScript has many built-in functions that let you use MAXScript as a calculator.
Enter 36.5 * 2, for example, to see what a certain dimension needs to be if you want to double it.

MAXScript returns the result of the calculation. This is useful for quick calculations where loading
an external calculator program doesn’t seem worth the trouble.
MAXScript also recognizes several mathematical constants. Enter pi.

MAXScript knows the value of pi and returns it.

 Mathematical Operations in MAXScript 589

You can use this value in more complex operations. For example, if you want to know the volume
of a sphere with a 2.5-inch radius, multiply the cube of the radius by pi, then multiply by 4 and
divide by 3. Enter 4/3 * pi * 2.5^3 .

Operations with Strings

You can also perform some simple mathematical operations with strings. For example, if you have
defined a=”MAXScript” and b=” is fun!,” entering a+b returns “MAXScript is fun!”

For more string operations, see the String Values (p. 722) topic in the MAXScript reference.

Additional Mathematical Operations

MAXScript is able to perform many mathematical operations, including most trigonometric
functions (sin, cosh, atan) and transcendental functions (exp, log, sqrt). This topic introduces two
of the most useful operations: random numbers and incrementing. For a complete list of the
operations supported by MAXScript, see the Number Values (p. 717) topic in the MAXScript
reference.
590 Chapter 2 | Learning MAXScript

Creating Random Numbers

One very useful mathematical operation in MAXScript is the random number function. It returns a
pseudo-random number selected inclusively between two user-specified arguments. For example:
random 1 100
returns a random integer between 1 and 100. The return value type (Float or Integer) is the same as
the type of the first argument in the function, therefore if you enter:
random 1.0 100
MAXScript returns a random float between 1 and 100.

Note: For reasons beyond the scope of this tutorial, the random command will generate the same
‘random’ numbers each time a script is run. This happens if you restart the software and run the
script, but not if you run the script over and over. If you want the values created by the random
function to change each time you start the software, you can use the seed command:
seed <number>
where <number> is any float or integer. Each time you change the seed value, MAXScript generates
new ‘random’ numbers.
 Drawing a Box with MAXScript 591

Incrementing
Another useful mathematical operation that MAXScript provides is incrementing. This is a
shorthand form of assignment that can be used to modify a value in place, as shown in the following
long form examples:
x = x + 1
There are assignment operators corresponding to the four math operations (+,-,*, and /) that apply
the operation to the assignment’s destination with the result. Their syntax is:
<destination> += <expr> -- add <expr> to destination
<destination> -= <expr> -- subtract <expr> from destination
<destination> *= <expr> -- multiply destination by <expr>
<destination> /= <expr> -- divide destination by <expr>
Using this shorthand form of assignment, the previous example can be written as:
x += 1

Drawing a Box with MAXScript

In the previous lessons you have seen some of MAXScript’s useful capabilities; however, nothing
that is visible in the interface. MAXScript is also useful for working with regular objects, such as
boxes or cylinders. You can draw a box in MAXScript just by entering the box() command:
box()
This creates a box with the default parameters. It is generally better practice to assign an object to a
variable, so you can later refer to it by name and manipulate it using that name:
mybox = box()
When you use MAXScript to create an object without specifying any parameters, it is important to
use empty parentheses, “()”. This tells MAXScript to use the default parameters for the object. If you
want to specify any of the parameters during creation, such as the size or location of the object, you
do not need parentheses. For example:
mybox = box length:20 width:20 height:20
592 Chapter 2 | Learning MAXScript

MAXScript returns the box object name and the position of the box:

This example creates a box, and supplies three parameters: the length, width, and height of the box.
The parameter names are followed by a colon and then by the value for that parameter. You can
enter all parameters, without any punctuation between them. MAXScript returns the following
statement:
$Box:Box01 @ [0.000000, 0.000000, 0.000000].
The first part of the statement is called a pathname. A pathname in MAXScript is similar to a
pathname in Windows, such as c:\3dsmax\examples\file.max, which represents a path through a
hierarchy of directories pointing to a particular file. In MAXScript, a similar path concept is used.
However paths in MAXScript end up pointing to objects, not files. Pathnames in MAXScript always
begin with the “$” character. For more information on Pathnames, see the Pathname Literals (p. 662)
topic in the MAXScript reference.
The second part of the statement is the object name: Box01, in this case. This name appears in the

Select Object dialog when you use the Select by Name toolbar button in 3ds max. It is not the
name of your box variable, which is mybox. This variable is merely a placeholder that points to the
object, Box01.
The values inside the brackets represent the x, y, and z coordinates of the center of the box.
 Modifying the Box 593

MAXScript also draws the box in the viewports, as shown in this perspective viewport:

Notice that you can use Undo (as you can with most MAXScript creation and
modification commands) to remove the box from the scene.

Modifying the Box

In the previous lesson, you created a box by assigning it to a named variable. Because you used a
variable for the box, you can now access all of the box’s properties easily. The variable name mybox
is the handle to your box. To access the properties of the handle, append a “.” (period), and then the
property name. For example, mybox.height can be read as “the height of mybox”.
All 3ds max objects have creation parameters such as width, length, and height for boxes, or radius
for circles. These objects also have transformation properties, such as scale, rotation, or position, and
general properties like name, wireColor, etc. To change any of these properties, you can set the
property to a new value.
594 Chapter 2 | Learning MAXScript

To change the object name of the box:

If you don’t like the default object name Box01, you can change the name property of the box:
Enter mybox.name = “BlueBox” in the Listener window and the software renames the box. You
can see the new name in the Name edit box when you go to the Modify panel:

To change the color of the box:

The software assigns the color of objects randomly at creation time. Therefore, the color of your box
is not necessarily blue. In this case, BlueBox wouldn’t be an appropriate name for your box.
However, you can change the color of your box to match the name:
Enter mybox.wireColor = blue and watch the box in your viewports turn blue. You may have to
select the box again to reflect the new color in the color swatch next to the object name in the
Modify panel.
The color blue is a predefined color constant in MAXScript and its RGB value is defined as (0,0,255).
The other predefined color variables are red, green, white, black, orange, yellow, and brown. Instead
of using a predefined color, you can assign a color with different RGB values, such as:
mybox.wireColor = (color 255 0 255)
Notice the special syntax for entering specific color values. The example shown would change the

box to magenta. If you entered this command, click Undo to change the box back to blue.
For more information on colors, see the Color Values (p. 729) topic in the MAXScript reference.

To change the position of the box:

You can change the position of the box by changing the box’s position property. You refer to the
position property for this example box with mybox.pos. The position is expressed as the X, Y, Z
coordinate. For example [0,-75,0]. Bring the box forward by entering mybox.pos = [0,-75,0]
and watch the box jump forward in the perspective view:
 Modifying the Box 595

Click Undo to move the box back to the origin.

To change the size of the box:

To make the box bigger, you can use the scale property of the box:
Enter mybox.scale = [1.5,1.5,1.5] to see the box resized to 1.5 times its original size.
The scale property requires a scaling factor for each of the X, Y, and Z axes, or, in this case, the width,
length and height of the box. You don’t have to use the same value for each axis unless you want to
resize the box uniformly.
596 Chapter 2 | Learning MAXScript

If you want to change the scale to affect only the height and the width, but not the length, use the
following example:
mybox.scale = [1,3,2]
When you scale your original [20,20,20] box by any factor, the box’s parameters are still 20 for
width, 20 for length, and 20 for height. You can see this when you open the Modify panel. The box
parameters are not changed by the scale transformation:
 Modifying the Box 597

Although altering the height and width properties of the box achieves the same result, visually, the
above scale modification is not equivalent to using the following two commands:
mybox.height = 40 -- 2 times the original 20 units
mybox.width = 60 -- 3 times the original 20 units
The reason for this is that changing the height property of the box changes the creation parameter
of the box’s height. Using the scale property to transform the height of the box does not.
Again, the effect of using either method is visually the same, but when you want to maintain the
original creation parameters of an object, so that you can alter them even after a number of different
transformations, you must use the scale property to manipulate the size of the box, not the
individual creation properties.

If you entered the last two commands, click Undo twice to change the box back to its original
height and width.

To find out which other box parameters you can change:

The Parameters rollout shows all the creation parameters for a box. You can change them using the
spinners in the rollout. If you want to change the value of the length, width, and height segments,
or the setting of the mapping coordinates in MAXScript, you need to know the syntax for these
parameters. In order to find the syntax for all of the parameter settings, there are two different
inspector functions. The first of these is showclass().
Enter showclass “box.*”
MAXScript shows all the box parameters that are equivalent to the ones you see in the Parameters
rollout, including which object class the box object belongs to, and the data type that each
parameter requires:
598 Chapter 2 | Learning MAXScript

Notice that you can use the “*” character as a wildcard to see all box parameters. If you had entered
showClass “box*.*,” MAXScript would have listed the Box and the BoxGizmo classes.
The other inspector function is showProperties(). To learn more about these functions, search
for the “Class and Object Inspector Functions and Properties” topic in the MAXScript Reference.

Applying Standard Transformations

Now that you know how to create and modify the basic properties of a box, you need to learn how
to apply the standard transformations (move, scale, and rotate) to it. It is possible to designate
position, size, and orientation when the box is created; however, you can also carry out these
operations after you have created your object, just as you would in 3ds max.

To move the box:

Moving an object in MAXScript is very simple:
move name_obj [<x,y,z>]
where name_obj is the name of the object you want to move and <x,y,z> is the amount you want
it to move. It is important to note that you are not moving the object to <x,y,z>, but by the
amounts <x,y,z>. Therefore, if you apply the move function more than once, the object continues
to move. This is also true for the scale and rotate transforms. This is in contrast to setting a property
of an object. If you set the object position, scale, and rotation properties several times, the object
won’t change, assuming that you assign the same value each time.
 Applying Standard Transformations 599

For example:
mybox.pos = [10,0,0]
mybox.pos = [10,0,0]
mybox.pos = [10,0,0]
will only change the position of your box after the first line is executed. The second and third lines
do not affect the position of your box, as they do not change the position of the box.

If you entered the above commands, click Undo three times to move the box back to its
original position.
On the other hand, entering:
move mybox [10,0,0]
move mybox [10,0,0]
move mybox [10,0,0]
will move your box 30 units along the X-axis.
600 Chapter 2 | Learning MAXScript

If you entered the above commands, click Undo three times to move the box back to its
original position.
 Applying Standard Transformations 601

To scale the box:

Scaling is performed in a similar manner:
scale name_obj [<x,y,z]
where name_obj is the name of the object and <x,y,z> is a 3D coordinate that corresponds to the
amount you would like to scale the object along the X, Y, and Z-axis, respectively. Again, the scale
transformation is different from the scale object property. Setting the object’s scale property
(name_obj.scale = …) repeatedly with the same values will only scale the object the first time, but
applying the scale transformation repeatedly will continue to scale the object.

To rotate the box:

The rotate transformation is not as simple as the move and rotate transforms. In fact, there are three
ways to rotate an object in MAXScript:
• Euler Angles
• Quaternions
• Angleaxis
This introduction will only consider Euler Angles. If you would like further information on any of
these transformations, see the MAXScript reference.
To apply a rotation transform in MAXScript, you must first 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:
rot_obj = eulerangles x y z
where rot_obj can be any name and x, y, and z represent the amount you want to rotate your
object (in degrees) around the X, Y, and Z-axes, respectively. For example:
rot_box = eulerangles 0 30 0
creates an object called rot_box, which will rotate an object around the Y-axis by 30 degrees. This
rotation can be applied to your box in the following way:
rotate mybox rot_box
602 Chapter 2 | Learning MAXScript

In fact, this rotation could be applied to any object by writing the same line as above and replacing
mybox with the name of the object you want to rotate.

If you entered the above commands, click Undo to move the box back to its original position.
If you designate angles for more than one axis:
rot_box2 = eulerangles 30 45 60
The rotation is applied to an object, with the X-axis rotation occurring first, followed by the Y-axis
rotation, and then the Z-axis rotation.
Note: Moving, scaling, or rotating objects, or setting transform-related properties within a
coordinate system, will operate in relation to the current reference coordinate system (i.e., Local,
World, Screen), which is displayed in the main 3ds max toolbar. If you want to perform these
transformations in another coordinate system, see the Coordsys (p. 685) topic in the MAXScript
reference.
 More Box Transformations 603

More Box Transformations

Additional property transformations
The following lines prepare our box for more complex transformations. They change the number of
box segments on all sides, and put a check mark into the Generate Mapping Coords. box in the
Parameters rollout:
Enter the following four lines of code:
mybox.lengthsegs = 10
mybox.widthsegs = 10
mybox.heightsegs = 10
mybox.mapCoords = true

MAXScript has changed the appropriate settings in the Parameters rollout:

Any time you change a property of a 3ds max object, MAXScript immediately reflects the change in
the scene and in the user interface.
You can also create modifiers and add them to an object.

To create a modifier:
Creating a modifier is pretty simple. You use the addModifier command and specify the name of
the modifier you want to use and its appropriate parameters.
For example, to create a Twist modifier set at 30 degrees and apply it to your box, you would enter
addModifier mybox (twist angle:30)
604 Chapter 2 | Learning MAXScript

The box in your Perspective viewport is now twisted and the interface shows the new Twist modifier
in the modifier stack display, together with its parameters:
 More Box Transformations 605

To change a modifier:
Changing a modifier is similar to changing a creation parameter. Again, because you used a variable
name for your object, and you added a modifier to that object variable, you now have easy access to
the new modifier properties of your object.
To change the angle of the twist modifier to 60 degrees, enter
mybox.twist.angle = 60
606 Chapter 2 | Learning MAXScript

The twist of your box is now more pronounced and the Angle parameter of the Twist modifier
displays the new value:

From here on, you can add and change other modifiers as you like. The syntax is the same for all
modifiers. To find out the names of other modifiers, search for the “Modifier : MAXWrapper” topic
in the MAXScript Reference.

If you entered the above commands, click Undo twice to bring the box back to its
original state.
 Controlling Program Flow in Scripts 607

To animate your box:

MAXScript has several syntax forms that mirror the main UI tools, such as the Animate button, the
time slider, and the active coordinate system. In the following example, you turn on the Animate
button, set the slider to several different values, and adjust the properties of your box, just as you
would do using the software’s UI:
animate on
(
at time 0 (mybox.pos = [-100, 0, 0]; mybox.scale = [1, 1, 0.25])
at time 100 (mybox.pos = [100, 0, 0]; mybox.scale = [1, 1, 3])
)

Drag the slider around, and you will see that MAXScript has animated the box, and placed keyframes
at 0 and 100.
When you use MAXScript to animate objects, the actual Animate button in the UI does not come
on, nor does the time slider move; these things happen within MAXScript.
In this example, the time was given as a simple number. If no unit is specified, MAXScript interprets
this as a frame number. You can also use one of the various time literals in the following manner:
2.5s -- 2.5 seconds
20f -- 20 frames
4800t -- 4800 ticks = 1 sec
1m3s5f -- 1 min, 3 seconds, 5 frames
1:15.5 -- SMPTE: 1 min, 15 seconds, 5 frames

Note: All times are automatically converted to frames.

Controlling Program Flow in Scripts

Now that you have explored the beginnings of object creation and manipulation, the next step is
programming. MAXScript is a programming language at heart, and two of the most important
concepts necessary for mastering MAXScript are conditional statements and loops.
At this point, real script writing comes into play. From the Utilities command panel, click on the
“New Script” button. This opens a new MAXScript editor window where you can create, save, and
open scripts.
In the MAXScript editor window, commands are not automatically executed. In order to execute the
entire script, use “Evaluate All” from the File Menu, or press CTRL+E. You can also execute scripts
several lines at a time by highlighting the lines you want to execute and pressing SHIFT+ENTER, or
ENTER on the numeric keypad.
608 Chapter 2 | Learning MAXScript

Conditional Statements
Conditional statements simply tell MAXScript to perform a specified command if a certain
condition is met. For example:
if mybox.height == 10 then mybox.width = 20
This changes the width of your box to 20 if its height is equal to 10. You may have taken note of the
double equal sign used in the statement above. This is discussed at the end of this topic.
This “if...then...” statement can be expanded to include an “else” statement. For example:
if mybox.height == 10 then mybox.width = 20 else mybox.width = 10
This statement tells MAXScript to change the width of your box to 20 if its height is 10, otherwise
change the width to 10. The “if,” “then,” and “else” portions of the statement can all be on
separate lines:
if b.height == 10
then b.width = 20
else b.width = 10

If you are entering these commands into the Listener window, you may notice that the commands
are not executed line by line, as is typical of the Listener. This is because the Listener recognizes that
the “if” statement requires a “then” statement to be complete. In fact, the Listener does not execute
the statement after the “then” statement, because it does not know if you intend to include an “else”
statement. For this reason, the Listener does not execute an “if...then...” statement until you have
either entered a “then” statement or after the next line you type, following the “if...then...”
statement.
The double equal sign in the last statement, “==,” tells MAXScript to compare two values. The single
“=” sign always signifies assignment. This is common in many standard programming languages,
such as C++. There are several different conditional parameters used in MAXScript. They are
listed here:
== equal to
!= not equal to
> greater than
>= greater than or equal to
< less than
<= less than or equal to
Note: Any time MAXScript evaluates a conditional expression, the result is either true or false.
MAXScript temporarily stores the value of this result. In an “if...then” statement, MAXScript uses
this result to determine the path to follow in the statement. If the result of the “if” statement is true,
MAXScript will evaluate the “then” expression. If the result is false, MAXScript will evaluate the
“else” expression, assuming one is specified; otherwise, it will cease evaluating the conditional
statement. In some scripts, you might see the words on and off used in place of true and false,
respectively. These words are interchangeable and they mean the same thing to MAXScript.
 Controlling Program Flow in Scripts 609

Loops
Loops are repetitive operations that tell MAXScript to repeat the execution of a collection of
commands. Loops are useful for working with large groups of objects, as you can make changes to
many objects with one set of commands. For example, if you wanted to make 50 boxes, you could
use a loop to execute the create 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.

For 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. Use a for loop to copy the box:
for i = 1 to 5 do
(
box_copy = copy mybox
box_copy.pos = [i * 50, 0, 0]
)
610 Chapter 2 | Learning MAXScript

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’. Next, you must define how many times the statement will
repeat. In this case, you have used the variable “i” to control the loop. 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 time the loop executes, the index is incremented by 1 automatically, without
requiring any user input. Each repetition of the loop is called an iteration. To make MAXScript
increment the index by a value other than 1, insert ‘by x’ after the index statement, where x is the
amount to increment the index. For example, the following statement will set the index to 1, then 3,
then 5:
for i = 1 to 5 by 2 do
(
box_copy = copy mybox
box_copy.pos = [i * 50, 0, 0]
)
 Controlling Program Flow in Scripts 611

The “do” keyword tells MAXScript to execute the following block or statement each time the loop
repeats. Note that in some loops you might see the word “in” in place of the equal sign, “=”. These
both mean the same thing in for loops, and can be used interchangeably. Note how the index was
used within the loop statement to set the position of each new box. This is a useful way to work with
multiple object creation.
For loops can also be used to build arrays and/or access values within an array. In the following
example, you use a for loop to build an array called ‘arr’:

Remember that because MAXScript is an expression-based language, you are able to use expressions
in variable assignment, as seen above in the assignment of the for loop expression to the variable,
arr. Note the ‘collect’ statement in the for loop above. This tells MAXScript to collect the results of
each iteration in an array, rather than just calculate them. In this case, you only asked MAXScript to
collect the value of the index; however, you can collect iterations of any expression.
612 Chapter 2 | Learning MAXScript

Finally, for loops can also perform iterations with the contents of an array. In the following example,
you use a for loop to access the values of the array you created in the previous example:

The ‘print’ command is a MAXScript function that displays the specified variable in the Listener
window. In this example you used ‘in’ instead of an equal sign; however, they are still both
acceptable, even when accessing values within an array.
Note: You can also access the number of elements in an array with the .count property. For
example, the previous example could have been written:
for i = 1 to arr.count do print i
This will return the same result.

While and Do Loops

While and Do loops are used to repeatedly execute an expression until a test expression evaluates as
false. The while and do loop are simple variants of one another. The syntax is:
do <expr> while <expr> -- do loop
while <expr> do <expr> -- while loop

The following example will return the value of a variable, incrementing the variable by –1 with each
iteration.
x=10
while x>0 do print (x-=1)
 Controlling Program Flow in Scripts 613

Returns:
9
8
7
6
5
4
3
2
1
0
0

MAXScript automatically returns the final value of the loop to the Listener. In this example,
MAXScript is also instructed to return the value at each iteration of the loop; therefore, the final
value is returned twice.
Both loops repeat the do<expr> as long as the while<expr> evaluates to the value true. The do
form evaluates the do<expr> at least at least once, before evaluating the text expression at the end
of the loop. The while form evaluates the test expression at the start of the loop, and might not loop
at all.
Both forms return, as their value, the result of the do<expr> from the last successful loop iteration.
The while form returns the value undefined if the test expression immediately returns false.
For example:
x=10
do print (x-=1) while x>10
Returns:
9
undefined

However,
x=10
while x>10 do print (x-=1)
Returns:
Undefined
614 Chapter 2 | Learning MAXScript

Defining Custom Functions

MAXScript’s built-in functions are very powerful. They provide access to objects, allowing you to
read and set their properties. However, scripting in 3ds max normally entails going beyond simple
object creation. Fortunately, MAXScript allows you to make your own functions, giving you the
ability to streamline and customize your work.

Local and Global Variables

In MAXScript, there are two classes of variables that you can create: “local” and “global” variables.
When a variable is global, it means that the variable can be used anywhere in the program. The only
place you cannot use a global variable is before you have defined it. For example, the following lines
will produce an error:
sphere radius:rad
global rad = 10
The variable “rad” does not exist until it has been defined. The following is an acceptable form of
the previous lines:
global rad = 10
sphere radius:rad
Now that “rad” has been defined, MAXScript was able to use it in the definition of a sphere. In fact,
since “rad” is a global variable, it can be used throughout the rest of the script.
There are several global variables that can be used without defining them first. They are the system
global variables, which have already been created and assigned to a default value. Most of these
variables can be reassigned to different values. For more information on the system global variables,
see the 3ds max System Globals (p. 630) topic in the MAXScript reference.
Unlike global variables, local variables can be used only within the block in which they are defined.
A block is a grouping of MAXScript code, such as the statements within loops and conditional
statements. Here is an example of a for loop:
for i = 1 to 3 do
(
local rad = 10
s = sphere()
s.pos.x = i * 10
s.radius = rad
)
Local variables can only exist within a block. For this reason, they must be created in a block. If you
try to define a local variable from the top level of MAXScript, you will receive an error message.
In the previous example, you defined a local variable named “rad”. This variable is active only
within the parentheses inside the for loop; if you attempt to use the variable “rad” elsewhere, you
will get an error.
Although rad is initialized to a specific value, this is not necessary. When you define variables using
a “local” or “global” identifier, you can do so without assigning an initial value. The name of the
variable will be recognized. However, the software will not know the type of the variable (name,
 Defining Custom Functions 615

number, color, etc.). MAXScript automatically assigns the variable a special value of “undefined”.
The first time you assign something to the variable, it will become defined by the data type that you
have assigned it to. In practice, it is always best to define variables with an initial value.
It is important to note that rad is not the only local variable in the previous example. The variable
“s” is also a local variable, and cannot be accessed outside of the parentheses. It is not necessary to
declare every variable with a “global” or “local” statement. You learned previously that you can
implicitly create a variable by simply assigning a value to it. If you do not make the “global” or
“local” distinction upon your variable, MAXScript will create the appropriate association, depending
on where the variable is defined in the script. For example if you create a variable inside a block,
MAXScript automatically treats it as a local variable. On the other hand, any variable created at the
top level of MAXScript (outside of all blocks) is always a global variable. As mentioned previously,
MAXScript does not allow for the creation of local variables outside of a block. These concepts are
presented in the following example:
for i = 1 to 5
(
global rad = 10
cyl_height = 25
c = cylinder()
c.radius = rad
c.height = cyl_height
c.pos.x = i * 25
)
s = sphere radius:rad
In this example, four variables are created: rad, cyl_height, c, and s. Because they were implicitly
created within a block, c and cyl_height are both local variables. The other two variables are both
global; s, because it was created outside of a block, and rad, because it was declared as a global
variable. For this reason, you can use rad again to define the sphere, s.
616 Chapter 2 | Learning MAXScript

Defining Custom Functions

In MAXScript, you can use functions to perform almost any of the software’s operations. Start with
a simple function definition that subtracts two variables:

MAXScript returns subtract() to let you know that it has defined the function, subtract.
The definition contains the keyword function (you can also use the word fn in place of
function), followed by the name of the function (subtract), followed by the list of variables
(x and y). The equal sign signifies the start of the body of the function. The body is the series of
statements that the function executes. Even if there is only one statement, the body of the function
must be in parentheses.
Note: Any variables created in the body of a function are local variables unless otherwise specified.
Once a function has been defined, it can be used anywhere throughout the script. Therefore, it is
useful to place function definitions at the beginning of your scripts.
In order to use a function, you simply enter the function name and the values for its variables:
 Defining Custom Functions 617

This example uses what are known as positional arguments. When you call the function, you must
supply both arguments, and you must supply them in the proper order for the function to execute
properly.
The second type of arguments you can use are keyword arguments. This is what is used for all of the
object constructors in MAXScript. The function definition is the same, with the exception of
declaring the keyword arguments, or default values for the variables in a function. The following
example determines whether a number is positive, negative, or equal to zero:
function sign val:0 =
(
if val == 0
then messagebox (”Equal to 0”)
else if val > 0
then messagebox (”Greater than 0”)
else messagebox (”Less than 0”)
)
The messagebox command causes a message box to pop up on the screen, displaying the argument
in the parentheses that follow the command.
In this example, a parameter called val has been declared in the function definition. The value after
the colon is the parameter’s default value. When the function definition contains parameters like
this, they are optional in the function call. If you enter sign(), without specifying any parameters
in the function call, MAXScript uses the default value:

The “Equal to 0” message box appears, since the default value for val (0) will be used. However, if
you do define val:
sign val:-5

the “Less than 0” message appears. You can include as many keyword arguments in a function as
you need, and they can be entered in any order when calling the function. This is useful when you
consider functions such as object-creation functions, where the new object might have 20 or 30
618 Chapter 2 | Learning MAXScript

parameters associated with it. If you wanted to use positional argument functions to create the same
objects, you would have to provide all of these parameters, in the right order, each time you wanted
to call the function.
It is also possible to use both positional and keyword arguments in the same function call. In this
case, you must use positional arguments first, followed by the keyword arguments:
function mycube side position:[0, 0, 0] =
(
box length:side width:side height:side pos:position
)
This function requires you to enter the size of the cube, but the position is optional.

Structure Definitions
In addition to custom functions, you can also create custom compound values in MAXScript using
“structure definitions”. Structure definitions are a flexible data type, built of simpler data types. They
let you define the layout of a new structured type of value that you can then create and work with
in your code. The syntax for a structure definition is:
Struct <struct_name> ( <member> , <member> )

where each <member> can be one of:

<name> [ = <expr> ] – name and optional initial value
<function_definition>

Create a new structure, called person:

Struct person (name, height, age, sex)
 Structure Definitions 619

Now create an instance of this structure using the ‘person’ constructor:

Bill = person name:”Bill” height:72 age:34 sex:#male
This stores an instance of the person structure in the variable Bill. Member name is initialized to the
string value “Bill”, height to the integer value 72, age to the integer value 34, and sex to the name
value #male. Create another instance:
Joe = person name:”Joseph” sex:#male
In this example, another ‘person’ is created. However, this person does not have initialized values
for the height and age members. Since you did not provide these members with an optional
default value in our structure definition, they will default to a value of undefined.

Structure definitions are a good alternative to arrays when you have a fixed, small number of
components. The code for these types of values is easier to work with since you can reference
property names rather than index numbers in arrays.
620 Chapter 2 | Learning MAXScript

3ds max Commands in MAXScript

In addition to controlling modeling and animation, MAXScript scripts can invoke 3ds max menu
and toolbar commands. You do this using the “max” keyword. For example:
max file open
max unhide all
max quick render

The keyword max is followed by one or more words that describe the command. The available
commands can be displayed by using the “?” character in a partial max command. For example:
max time ? -- shows all the time-related commands
max sel ? -- shows all the commands with ‘sel’ in them as a substring
max ? -- shows all the commands (there are a lot)

Below is a partial list of the available commands to give you an idea of the type of 3ds max
commands you can perform with MAXScript. For a complete list, see the 3ds max Commands
(p. 1630) topic in the MAXScript reference.

3ds max Command Name Command Description

max ? Displays all max commands in the Listener
max delete Deletes selected objects or sub-objects
max file new Displays the new file dialog
max file open Displays the open file dialog
max file save Activates File/Save
max move Activates Select and Move mode
max properties Displays the Object Properties Dialog
max quick render Performs a quick render
max redo Performs a redo operation
max reset file Activates File/Reset
max rotate Activates Select And Rotate mode
max select Activates select mode
max select all Selects all objects
max time end Sets the time slider to the end frame (Go to End)
max time start Sets the time slider to the start frame (Go to Start)
max undo Performs an undo operation
max unfreeze all Unfreezes all objects
max unhide all Unhides all objects
max vpt front Sets the active viewport to Front
max zoomext sel Activates Zoom Extents Selected
 Saving your Commands in a Script File 621

Saving your Commands in a Script File

So far, you have entered your commands into the Listener window. If you had to stop at some point,
and couldn’t finish some code in one session, you would have to start all over, entering the
commands you already used in the previous session. MAXScript allows you to store your commands
in an external file that you can load and run.
The general procedure for storing commands in a script file is to click the New Script button in the
MAXScript rollout, and type commands in the Script Editor window that opens. Because you have
already entered a lot of commands in the Listener window, you can copy them from that window
into the Script Editor window.

To copy tutorial commands from the Listener into the script editor window:
1. Click the New Script button in the MAXScript rollout on the Display panel.
The Script Editor window appears with the title “Untitled - MAXScript”.
2. Position the Script Editor window side-by-side or below the Listener window so that you can
copy and paste text between the two windows.
3. In the Listener window, select the black command line from the Drawing a Box with MAXScript
(p. 591) topic (mybox = box length:20 width:20 height:20)
4. Press CTRL+C on your keyboard to copy the text to the Clipboard.
5. Click the Script Editor window to place the cursor in it, and press CTRL+V on your keyboard to
paste the command into the Script Editor window.
Tip: You can also drag selected text from the Listener and drop it in the Script Editor, or
vice versa.
6. Choose File > Save in the Choose File Name for Save dialog, navigate to your \Scripts directory.
Name your script file box_draw.ms and click Save.
Your script file is saved and the script editor window title changes to “box_draw.ms -
MAXScript.”
You have now saved your first script file. MAXScript uses the .ms extension for script files. It is good
general practice to save all of your script files into the scripts directory.

Loading and Running your Script File

You can open a script file for editing, or you can include it in another script to run automatically
when that script runs.

To run the script you just saved:

1. Reset 3ds max.
2. Go to the Utilities panel, turn on MAXScript, and in the MAXScript rollout, click the Run Script
button.
The Choose Editor File dialog appears.
622 Chapter 2 | Learning MAXScript

3. Select the box_draw.ms file, and click Open.

MAXScript immediately carries out the command that is contained in the script file and places
a box in the scene.

To open a script file for editing:

If you want to edit your script later to add more commands to it, you need to open it:
1. In the MAXScript rollout, click the Open Script button
2. Select the script you want to edit and click Open.
The Script Editor window opens, showing the text of your script. You can now edit your
commands or add new ones, as you would edit any other text file. Save the script file to keep
your changes.

To evaluate the commands in your script:

If you enter any commands in the Script Editor window manually (not by copying and pasting from
the Listener window), you can test the validity of all commands:
1. If your Listener window isn’t open, click the Open Listener button in the MAXScript rollout.
2. In the Script Editor window, choose File > Evaluate All.
MAXScript evaluates the commands in your script file. It sends any feedback to the Listener
window. It also sends each valid command to the user interface as if you had run the script. If
your script contains any syntax errors, MAXScript reports those in the Listener window in red.

To include your script in another script:

If you want to write a script for each tutorial (for example one for drawing a box, one for modifying
the box, and another one for transforming it), you could then use those three scripts in another one
that contains all the box operations. Assuming you had created the scripts box_draw.ms, box_mod.ms,
and box_trans.ms, you could then include them in a new script, box_all.ms. The text for box_all.ms
would be as follows:
include “box_draw.ms”
include “box_mod.ms”
include “box_trans.ms”

To reset 3ds max before running scripts:

If you want to start with a new scene before running any scripts, you need to reset the software:
1. Choose File > Reset.
2. Answer the Yes-No prompt to either save or discard the changes to your scene.
3. Open and run the script you want.
Note that resetting the software closes all MAXScript windows so that you can’t copy any more
commands from the Listener window. You can always copy commands from the help file, as
described below.
 Loading Other Scripts 623

To copy commands from the help file:

You can copy commands from the tutorial help file:
1. In the Help window, highlight the command you want to copy.
2. Right-click the highlighted text and select Copy from the pop-up menu.
3. In the Script Editor window, choose the Edit > Paste menu to paste the command into the
current script file, or press CTRL+V on your keyboard.

Loading Other Scripts

The software comes with many scripts pre-installed in the scripts directory. Or, you might find
MAXScript files on the World Wide Web that other MAXScript users have posted. To load any of
those script files isn’t different from loading your own scripts:

To load a script:
If you want to study a script before running it, open it first:
1. In the MAXScript rollout, click the Open Script button.
2. Select the script you want to study and click Open.
The Script Editor window opens. It shows the text of the script you selected. You can now read
the commands and see if you get an understanding of what the script might do when you run it.

To run a script:
1. In the MAXScript rollout, click the Run Script button.
The Choose Editor File dialog appears.
2. Select the script file you want to run, and click Open.
MAXScript immediately carries out the commands that are contained in the script file.

Learning MAXScript by Walking Through a Script

You can learn a lot about MAXScript by just using several different script files. The best method to
learn MAXScript commands and command syntax is to step through a script and watch the
responses in the Listener window and in the user interface. You can “walk” through a script by
loading a script into the Script Editor window and executing one command line or a command block
at a time:

To step through a script:

1. Open a script into the Script Editor window.
2. Place the cursor into the first command line and press ENTER on the number pad of your
keyboard.
The Number Pad <ENTER> key is a shortcut for executing the current command line or the
selected block of code.
624 Chapter 2 | Learning MAXScript

MAXScript executes the current command line and reflects the outcome in the Listener window
and, if appropriate, in the user interface.
3. Move the cursor to the next command line or select the next block of code from the script. Press
the number pad ENTER key again, and so on.
From here on, step through other scripts and take note of the effects. Most of the script files included
with 3ds max are very well commented and include a description about the scripts purpose. For
more information about using script files, see the Running Scripts (p. xlix) topic in the MAXScript
Reference.

Learning MAXScript with the Macro Recorder

Another useful tool for learning MAXScript is the Macro Recorder. If you want to learn how to
perform a task in MAXScript, you can use the Macro Recorder to get started. The Macro Recorder
captures many of the actions performed by the user, and generates the MAXScript commands that
correspond to those actions. The Macro Recorder output is displayed in the top pane of the
MAXScript Listener window. This pane has a pink background.
The Macro Recorder has several filtering options that control what types of user actions are recorded,
whether the generated script commands contain explicit object references or are selection-relative,
and whether the generated MAXScript commands contain explicit or relative transforms and
coordinates. These options can be set using the Macro Recorder menu in the Listener window.
Many user actions generate Macro Recorder output, but not all of them. In general, most of the
buttons on the Menu Bar, toolbars, Status Bar, Create panel, and Modify panel generate Macro
Recorder output. If the button invokes a secondary dialog, changing setting or performing actions
in the secondary dialog typically will not generate Macro Recorder output. In the Create and Modify
panels, Macro Recorder output is generated if MAXScript can create the object or modifier.
This makes the Macro Recorder a useful too for learning MAXScript, as you can perform tasks in the
UI and simultaneously see how to perform these same tasks with MAXScript.
For further documentation on the Macro Recorder, see the Macro Recorder (p. l) topic in the
MAXScript reference.

The Scripts Included with 3ds max

You can open each script in the scripts directory and study what each script does by stepping
through them. The script files are ASCII files that you can open with any ASCII editor for viewing or
printing. Most script files are very well commented and include a description of the script’s purpose.
Of particular interest is demo.ms, which you can step through to explore various aspects of
MAXScript’s capabilities.
Chapter 3: Reserved Keywords, Symbols, Punctuation and Variables

As with any computer language, MAXScript features a number of lexical tokens, corresponding to
the words and numbers and punctuation that are the building blocks of English. Tokens fall into
several categories:
• Reserved ‘keywords’ that typically introduce clauses in the language, such as if, for, and
function.
• Punctuation marks and symbols that separate or group clauses or specify math operators, etc.
• Reserved global variables containing 3ds max system global variables and MAXScript predefined
global variables.
The following list of topics contains information about the above types of tokens and their syntax:
Language Reserved Keywords (p. 625)
Punctuation and Symbols (p. 627)
Reserved Global Variables (p. 628)

Language Reserved Keywords

Keywords begin or separate portions of MAXScript commands. For example, one form of the if
expression is:
if <expr> then <expr> [ else <expr> ]

In order for MAXScript to easily identify the various portions of the if expression, the words if,
then and else are reserved keywords and can not be used as variable names or identifiers. So, for
example, you cannot declare a variable or function called if. The following table lists all MAXScript
reserved keywords. Click a reserved keyword to go to a description of its usage. In some cases, a
keyword may have more additional meanings, depending on its context. This information is also
summarized in the MAXScript Grammar (p. 1681) topic.
626 Chapter 3 | Reserved Keywords, Symbols, Punctuation and Variables

Reserved Keywords

about about
and Logical_Expressions
animate animate
as value_common_properties_operators_and_methods
at at_time
by For_Loop
case Case_Expression
catch Try_Expression
collect For_Loop
continue Skipping_Loop_Iterations
coordsys coordsys
do While_and_Do_Loops
else If_Expression
exitv Loop_Exit
fn Creating_Functions
for For_Loop
from
function Creating_Functions
global Scope_of_Variables
if If_Expression
in For_Loop
local Scope_of_Variables
macroscript Defining_Macro_Scripts
mapped Creating_Functions
max MAX_Commands
not Logical_Expressions
of Case_Expression
off Predefined_Globals
on Rollout_Clauses
or Logical_Expressions
parameters Scripted_Plugin_Clauses
persistent Persistent_Global_Variables
plugin Scripted_Plugins
rcmenu Scripted_Right_Click_Menus
return The_Return_Expression
rollout Utility_Clauses
 Punctuation and Symbols 627

set Sticky_Contexts
struct Structure_Definition
then If_Expression
throw Try_Expression
to For_Loop
tool Scripted_Mouse_Tools
try Try_Expression
undo undo
utility Scripted_Utilities
when Change_Handlers_and_When_Constructs
where For_Loop
while While_and_Do_Loops
with Loop_Exit

The from keyword is reserved, but not currently used.

Punctuation and Symbols

The following table shows all MAXScript punctuation marks and symbols. Their meanings are
described in the definitions of the various language constructs that use them and also in the
MAXScript Grammar (p. 1681) topic. Some of these punctuation marks and symbols offer more
information. Click a linked punctuation mark or symbol to go to a description of its usage. In some
cases, a keyword may have more additional meanings, depending on its context.

( Block_Expressions
) Block_Expressions
+ Math_Expressions
* Math_Expressions
- Math_Expressions
/ Math_Expressions
^ Math_Expressions
+= Math_Assignment
-= Math_Assignment
*= Math_Assignment
/= Math_Assignment
-- Source_Code_Layout_and_Continuation_Lines
= Math_Assignment
; Source_Code_Layout_and_Continuation_Lines
<eol>
628 Chapter 3 | Reserved Keywords, Symbols, Punctuation and Variables

,
[ 2D_and_3D_Point_Literals
] 2D_and_3D_Point_Literals
: Function_Calls
‘ Names
&
.
{ BitArray_Values
} BitArray_Values
# Array_Values
== Logical_Expressions
!= Logical_Expressions
< Logical_Expressions
> Logical_Expressions
>= Logical_Expressions
<= Logical_Expressions
? Using_the_?_Symbol
$ Pathname_Literals
... Pathname_Literals
.. BitArray_Values
\ Source_Code_Layout_and_Continuation_Lines

Reserved Global Variables

Reserved global variables are variables to which MAXScript automatically assigns values. The
MAXScript reserved global variables fall in 3 categories: predefined globals (such as red and pi);
3ds max system globals which give you access to state information in the 3ds max system (such as
currentFrame); and MAXScript system globals which give you access to the MAXScript system state.
Unlike language reserved keywords, you can re-use these variable names as local variables, with
values that you specify. However, it is highly recommended that you do not re-use reserved global
variable names as such usage can be highly confusing.

See Also
Predefined Globals (p. 629)
3ds max System Globals (p. 630)
MAXScript System Globals (p. 640)
Variables – Assignment and Scope (p. 643)
 Predefined Globals 629

Predefined Globals
The predefined global variables contain special values that are frequently used in scripts. These
variables are read-only.
true, false
Boolean values. Can be used for testing the results of comparisons and for state tests.
on, off
Synonyms for true and false, sometimes easier to read in state accesses.
pi, e
Float values that contain the standard mathematical constants’ values. They are equivalent
to 3.1415926535 and 2.718281828, respectively.
red, green, blue, white, black, orange, yellow, brown, gray
A predefined set of useful Color values.
x_axis, y_axis, z_axis
Point3 values that define normal vectors for the 3 major axes. They are equivalent to
[1, 0, 0], [0, 1, 0], and [0, 0, 1], respectively.
ok
A void value returned by some functions or expressions that don’t have a meaningful
value to return.
undefined
The initial value of all variables and array elements. MAXScript generates an error if you
try to perform any operation on the undefined value, except for checking to see if some
value is equal to it or not:
if a == undefined then print “oh, oh”
if b != undefined then print “whew!”

unsupplied
The initial value of all function keyword arguments. Keyword arguments are optional
arguments to functions. If a keyword argument is not supplied by the function caller and
the function definition does not specify a default value, MAXScript initializes the keyword
argument to unsupplied. You can test for this value to see whether a caller has supplied a
particular keyword. For more details, see the Function Calls (p. 675) topic.
dontcollect
This value is used in for loops to signal that the value is not to be collected. See the For
Loop (p. 694) topic for details.
630 Chapter 3 | Reserved Keywords, Symbols, Punctuation and Variables

3ds max System Globals

The 3ds max system global variables give you access to state information in the 3ds max system.
Except where noted as read-only, you can both access and assign to the global variables.
activeGrid
Contains the currently active grid. If the home grid is active, returns the value undefined.
You can assign a grid node object to this variable to make it the currently active grid. See
Viewport Grids (p. 1587).
ambientColor
Lets you get and set a Color value that defines the global rendering environment
(Rendering > Environment) ambient lighting color. See Working with 3ds max
Atmospherics (p. 1345).
ambientColorController
Lets you get and set a Controller value that defines the global rendering environment
(Rendering > Environment) ambient lighting color controller. See Working with 3ds max
Atmospherics (p. 1345).
animationRange
Lets you get and set an Interval value that defines the start and end of the current active
animation range. This variable contains the corresponding values set in the Time
Configuration dialog. See Time Configuration Dialog (p. 1616).
animButtonEnabled
A Boolean value that specifies whether the user can change the state of the Animate
button. If set to false, the user can not change the Animate button state. If set to true,
the user can change the Animate button state. A script can change the state of the Animate
button using animButtonState regardless of the animButtonEnabled value. See Time
Control (p. 1580).
animButtonState
Lets you to get and set the state of the Animate button. A Boolean value - true if Animate
is on, false if Animate is off. See Time Control (p. 1580).
autoBackup.enabled
Get/set whether auto backup is enabled as a <boolean>.
autoBackup.time
Get/set the time in minutes between auto backup as a <float>. If the specified value is <
0.01 (the UI limit), the time is set to 0.01.
backgroundColor
Lets you get and set a Color value that defines the global rendering environment
(Rendering > Environment) background color. See Working with 3ds max Atmospherics
(p. 1345).
backgroundColorController
Lets you get and set a Controller value that defines the global rendering environment
(Rendering > Environment) background color controller. See Working with 3ds max
Atmospherics (p. 1345).
 3ds max System Globals 631

backgroundImageFileName
Lets you get and set a String value that defines the viewport background image bitmap file
name. This variable contains the corresponding bitmap file name set in the Viewport
Background dialog. See Viewport Background Images (p. 1586).
cui.commandPanelOpen
Lets you get and set whether the command panel is displayed. A Boolean value - true if
the command panel is displayed, false if not displayed. See Command Panels (p. 1571).
currentMaterialLibrary
Contains a virtual array of materials and root level maps corresponding to the currently
opened material library. You can get library materials via array indexing and iterate over
them in a for loop. The array can be indexed by number, or by name or string to select by
material name. This variable is read-only. See MaterialLibrary Values (p. 795).
displayGamma
fileInGamma
fileOutGamma
Lets you get and set Float values that define the gamma preference settings. They contain
the corresponding values set in the Gamma tab of the Preferences dialog. You could use
these global variables to establish gamma for a MAXScript-created bitmap, for example:
b = bitmap 320 240 gamma:displayGamma
render camera:c to:b
This would cause the rendered bitmap to display using the current displays gamma setting
if used as a rollout bitmap or button image.
displaySafeFrames
Lets you get and set whether Show Safe Frames is on for the active viewport. A Boolean
value - true if Show Safe Frames is on, false if off.
environmentMap
Lets you get and set a TextureMap value that defines the global rendering environment
(Rendering > Environment) environment map. See Working with 3ds max Atmospherics
(p. 1345).
flyOffTime
Lets you get and set an Integer value that defines the time in milliseconds the user must
hold down on a flyout before the flyout is activated. This variable contains the
corresponding value set in the General tab of the Preferences dialog.
frameRate
Lets you get and set an Integer value that defines the current scene frame rate in frames-
per-second. This variable contains the corresponding value set in the Time Configuration
dialog. See Time Configuration Dialog (p. 1616).
globalTracks
Contains a MAXTVNode value that defines the top-level Global Tracks node in Track View.
This variable is read-only. See Track View Nodes (p. 1382).
632 Chapter 3 | Reserved Keywords, Symbols, Punctuation and Variables

hardwareLockID
Contains an Integer value that defines the 3ds max hardware lock ID. This variable is
read-only.
hotspotAngleSeparation
Contains a Float value that defines the Hot Spot/FallOff Angle Separation value. This
variable contains the corresponding value set in the Rendering tab of the Preferences
dialog. This variable is read-only.
keyboard.shiftPressed
keyboard.controlPressed
keyboard.altPressed
These variables access the current state of the keyboard shift keys and return true or
false depending on the pressed state of the key at the time the variable is read and are
read-only variables.
lightTintColor
Lets you get and set a Color value that defines the global rendering environment
(Rendering > Environment) Global Lighting Tint color. See Working with 3ds max
Atmospherics (p. 1345).
lightTintColorController
Lets you get and set a Controller value that defines the global rendering environment
(Rendering > Environment) Global Lighting Tint color controller. See Working with
3ds max Atmospherics (p. 1345).
lightLevel
Lets you get and set a Float value that defines the global rendering environment
(Rendering > Environment) Global Lighting Tint Level. See Working with 3ds max
Atmospherics (p. 1345).
lightLevelController
Lets you get and set a Controller value that defines the global rendering environment
(Rendering > Environment) Global Lighting Tint Level controller. See Working with
3ds max Atmospherics (p. 1345).
listener
Read only system global - listener edit window <WindowStream> value
localTime
Contains a String value that defines the current local date and time. This variable is read-
only. An example of the value stored in localtime is:
s = localTime
“4/14/97 10:24:57 AM”
The format of this string is controlled by the date format selected in the main Windows
Regional Settings control panel.
logsystem.quietmode
Lets you get and set whether error logging quiet mode is enabled. A Boolean value set to
true when you do not want error messages from the renderer to bring up dialog boxes. If
set to false, error messages from the renderer will bring up dialog boxes. 3ds max sets the
 3ds max System Globals 633

corresponding internal variable to true during network rendering to suppress error

messages such as the “Missing Maps” and “Missing Map Coordinates” dialogs. If this
variable is set to true and the renderer generates an error message, the renderer will exit.
After setting quiet mode, do not forget to clear it when you are done, since the user will
not see any error messages from the renderer while quiet mode is enabled.
macroRecorder
Read only system global - macro recorder edit window <WindowStream> value
maxFileName
Contains a String value that defines the file name for the currently open scene. This
variable is read-only.
maxFilePath
Contains a String value that defines the directory path for the currently open scene. This
variable is read-only.
meditMaterials
Contains a virtual array of materials and root level maps corresponding to the slots in the
material editor. You can access material editor materials and root level maps via array
indexing and iterate over them in a for loop. The array can be indexed by number to
specify slot number or name or string to select by material and root level map name. For
example:
$foo.material = meditMaterials[1]
meditMaterials[”foo mat”].diffuse = red
for m in meditMaterials do print m.diffuseMap
meditMaterials[1]=standard()
print meditMaterials.count -- number of slots
This variable is read-only, but the elements (the materials in the slots) are assignable. See
MaterialLibrary Values (p. 795). See the Material Editor (p. 1606) topic for methods for
assigning materials and maps to the material editor slots.
numEffects
Contains an Integer value that defines the number of current render effects defined in the
Rendering > Effects dialog list. This variable is read-only. See RenderEffect (p. 1347).
numAtmospherics
Contains an Integer value that defines the number of atmospheric events, as shown in
Rendering > Environment. This variable is read-only. See Working with 3ds max
Atmospherics (p. 1345).
numSubObjectLevels
Lets you get the number of sub-object levels supported by the object or modifier currently
selected in the modifier stack. If the Modify panel is not open or no objects are selected,
the global contains the value undefined. See the Modify Panel (p. 1572) topic.
playActiveOnly
Lets you get and set whether to playback the active viewport only. This variable contains
the corresponding value set in the Time Configuration dialog. A Boolean value - true if
Active Viewport Only is on, false if off. See Time Configuration Dialog (p. 1616).
634 Chapter 3 | Reserved Keywords, Symbols, Punctuation and Variables

preferences.constantReferenceSystem
Lets you get and set whether to use the same coordinate system for the Move, Rotate, and
Scale tools in the 3ds max toolbar. A Boolean value - true if Constant is on, false if off.
This variable matches the Constant check box in the General page of Customize >
Preferences.
preferences.flyOffTime
Lets you get and set an Integer value that defines the time in milliseconds the user must
hold down on a flyout before the flyout is activated. This variable contains the
corresponding value set in the General page of Customize > Preferences.
preferences.maximumGBufferLayers
Lets you get and set an Integer value that specifies the maximum number of g-buffer layers
generated during a render.
preferences.spinnerWrap
Lets you get and set a Boolean value that defines whether cursor wrapping is limited to an
area close to the spinner when you drag to adjust spinner value. This variable contains the
corresponding value set in the General page of Customize > Preferences.
preferences.useLargeVertexDots
Lets you get and set whether to use small or large dots when representing vertices as dots.
A Boolean value set to true if you when using dots to represent vertices and a large size is
desired. The value of this variable only has effect when UseVertexDots is set to true.
This variable contains the corresponding value set in the Viewports page of Customize >
Preferences.
preferences.useTransformGizmos
Lets you get and set whether to use the Transform Gizmos. A Boolean value - true if on,
false if off. This variable contains the corresponding value set in the Viewports page of
Customize > Preferences.
preferences.useVertexDots
Lets you get and set whether to represent vertices as dots. A Boolean value set to true
when you want to use dots as the representation of the vertices in a mesh. If set to false,
ticks will be used. This variable contains the corresponding value set in the Viewports page
of Customize > Preferences.
realTimePlayback
Lets you get and set whether to playback in real time mode. This variable contains the
corresponding value set in the Time Configuration dialog. A Boolean value - true if Real
Time is on, false if off. See Time Configuration Dialog (p. 1616).
renderer
Lets you switch between the draft and production renderers and test which one is active. A
Name value that accepts and contains the values #draft or #production, for example:
if renderer == #draft then ...
renderer = #production
render camera:c ...
See Controlling the Renderer (p. 1664) and Render Scene Dialog (p. 1611).
 3ds max System Globals 635

renderDisplacements
Lets you get and set whether to perform displacement mapping during a render. A Boolean
value - true if displacement mapping is to be performed, false if not.
renderEffects
Lets you get and set whether to perform Render Effects after a scene render. A Boolean
value - true if Render Effects are to be performed, false if not.
renderHeight
Lets you get and set an Integer value that defines the output size height for the active
renderer. This variable contains the corresponding value set in the Render Scene dialog.
See Render Scene Dialog (p. 1611).
renderPixelAspect
Lets you get and set an Integer value that defines the output pixel aspect for the active
renderer. This variable contains the corresponding value set in the Render Scene dialog.
renderWidth
Lets you get and set an Integer value that defines the output size width for the active
renderer. This variable contains the corresponding value set in the Render Scene dialog.
See Render Scene Dialog (p. 1611).
rendOutputFilename
Lets you get and set a String value that defines the output file name for the active renderer.
This variable contains the corresponding value set in the Render Scene dialog. If this
global variable is set to ““ the Save File check box in the Render Scene dialog is unchecked.
rootNode
Contains a Node value that defines the root node of the scene. The root node does not
physically exist in the scene, rather it is a special node that is the parent node of all nodes
that are not linked to another node. The scene can be enumerated by accessing the
children property of the root node. A run-time error is generated if you try to perform
other node operations on the root node.
sceneMaterials
Contains a virtual array of materials and root level maps corresponding to the materials
and root level maps present in the scene. You can get scene materials and root level maps
via array indexing and iterate over them in a for loop. The array can be indexed by
number, or by name or string to select by material or root level map name. This variable is
read-only. See MaterialLibrary Values (p. 795).
scriptsPath
Contains a String value that defines the full directory path to the current Scripts directory.
This variable is read-only.
636 Chapter 3 | Reserved Keywords, Symbols, Punctuation and Variables

selectionSets
Contains a virtual array of all the current named node selection sets in the Named
Selection Set drop-down list on the 3ds max toolbar. You can get named selection sets via
array indexing and iterate over them in a for loop. The array can be indexed by number,
or by name or string to select by named selection sets. You can change, add and delete
Named Selection Sets by using the standard array methods on the selectionSets array.
See the SelectionSetArray Values (p. 783) topic.
showEndResult
Lets you get and set the state of the Show End Result Toggle icon in the Modify panel. A
Boolean Value – true if Show End Result is on, false if off. See the Modify Panel (p. 1572)
topic.
skipRenderedFrames
Lets you get and set whether to skip rendered frames during a render.
A Boolean Value – true if rendered frames are to be skipped, false if not.
sliderTime
Lets you get and set a Time value that defines the time associated with the 3ds max time
slider. See Time Control (p. 1580).
snapMode.active
Lets you get and set a Boolean value defining the Snap toggle state - on (true) or off
(false). This global variable is not available in 3ds max. See Status Bar Buttons (p. 1579).
snapMode.type
Lets you get and set a Name value defining whether 2D (#2D), 2.5D (#2_5D), or 3D (#3D) is
the current snap type. This global variable is not available in 3ds max. See Status Bar
Buttons (p. 1579).
subObjectLevel
Lets you get and set the sub-object level in the Modify panel if it is open. An Integer value
of zero or greater up to the number of sub-object levels supported by the currently open
modifier, typically in the order shown in the Sub-Object drop-down list. A
subObjectLevel of 0 means sub-object mode is off. If the Modify panel is not open or
sub-object level setting not permitted in the current modifier, the global contains the
value undefined. Use the numSubObjectLevels global variable to access the maximum
valid subObjectlevel value. See the Modify Panel (p. 1572) topic. For example:
b=box() -- create a box
em=edit_mesh() -- create an Edit Mesh modifier
addModifier $box01 em -- add edit mesh mod
max modify mode -- open mod panel
select $box01 -- select object box01
print subObjectLevel -- print the current subobject level
subObjectLevel = 2 -- set sub-object level to Edge
sysInfo.DesktopSize
A read only variable to get the desktop size in pixels as a <point2> value.
sysInfo.DesktopBPP
A read only variable to get the desktop color depth in bits per pixel as an <integer> value.
 3ds max System Globals 637

sysInfo.MAXPriority
Get/set the 3ds max process priority as a <name> value. Valid priority values are #high,
#normal, and #low
ticksPerFrame
Contains an Integer value defining the system time resolution. This variable is read-only.
timeConfiguration.playActiveOnly
Lets you get and set whether to playback the active viewport only. This variable contains
the corresponding value set in the Time Configuration dialog. A Boolean value - true if
Active Viewport Only is on, false if off. See Time Configuration Dialog (p. 1616).
timeConfiguration.realTimePlayback
Lets you get and set whether to playback in real time mode. This variable contains the
corresponding value set in the Time Configuration dialog. A Boolean value - true if Real
Time is on, false if off. See Time Configuration Dialog (p. 1616).
timeConfiguration.useTrackBar
Lets you get and set the state of the Time Configuration dialog ‘Key Steps/Use TrackBar’
check box. A Boolean value – true if checked, false if not. See Time Configuration Dialog
(p. 1616).
trackbar.filter
Lets get and set the filter specifying which types of keys to show in the Trackbar. A Name
value - the valid values are: #all, #TMOnly, #currentTM, #object, and #mat.
trackbar.visible
Lets you get and set whether the trackbar is visible. A Boolean value - true if the trackbar
is visible, false if invisible
trackViewNodes
Contains a MAXTVNode value that defines top-level World node in Track View. This
variable is read-only. See Track View Nodes (p. 1382).
units.DisplayType
Get/set the current unit display type as a <name>. Valid unit display types are:
#Generic
#Metric
#US
#custom
units.MetricType
Get/set the current metric unit display type as a <name>. Valid metric unit display
types are:
#Millimeters
#Centimeters
#Meters
#Kilometers
638 Chapter 3 | Reserved Keywords, Symbols, Punctuation and Variables

units.USType
Get/set the current US standard unit display type as a <name>. Valid US standard unit
display types are:
#Frac_In
#Dec_In
#Frac_Ft
#Dec_Ft
#Ft_Frac_In
#Ft_Dec_In

units.USFrac
Get/set the current US fraction display type as a <name>. Valid US fraction display
types are:
#Frac_1_1
#Frac_1_2
#Frac_1_4
#Frac_1_8
#Frac_1_10
#Frac_1_16
#Frac_1_32
#Frac_1_64
#Frac_1_100

units.CustomName
Get/set the current custom unit name as a <string>
units.CustomValue
Get/set the current custom unit value as a <float>
units.CustomUnit
Get/set the current custom unit type as a <name>. Valid custom unit display types are:
units.SystemScale
Get/set the current system unit scale value as a <float>. This is the value shown in
Preference Settings, General tab, System Unit Scale group.
units.SystemType
Get/set the current system unit scale type as a <name>. This is the unit shown in
Preference Settings, General tab, System Unit Scale group. Valid system unit scale
types are:
#Inches
#Feet
#Miles
#Millimeters
#Centimeters
#Meters
#Kilometers
 3ds max System Globals 639

useEnvironmentMap
Lets you get and set the global rendering environment (Rendering > Environment) Use
Map value. A Boolean value – true if Use Map is on, false if off. See Working with 3ds max
Atmospherics (p. 1345).
videoPostTracks
Contains a MAXTVNode value that defines the top-level Video Post Track View node. This
variable is read-only. See Track View Nodes (p. 1382). This variable contains the value
undefined in 3D Studio VIZ.
viewport.activeViewport
Lets you get and set the index of the active viewport. See Accessing Active Viewport Info,
Type, and Transforms (p. 1581).
viewport.numViews
Contains the number of viewports in the current viewport layout. This variable is
read-only. See Accessing Active Viewport Info, Type, and Transforms (p. 1581).
The following 3ds max system global variables are specific to 3ds max’s default scanline A-Buffer
renderer. These variables return undefined if the current renderer is not 3ds max’s default scanline
A-Buffer renderer.
scanlineRender.antiAliasFilter
Lets you get and set the anti-aliasing filter. For a list of all of the anti-aliasing filters you
can say:
showClass “*:filter*”

For example:
scanlineRender.antiAliasFilter = quadratic()

The anti-aliasing filters and their parameters are described in the 3ds max Scanline A-Buffer
Renderer Anti-Aliasing Filters (p. 1614) topic.
scanlineRender.antiAliasFilterSize
Contains a float value that defines the anti-aliasing filter size.
scanlineRender.enablePixelSampler
Lets you enables and disables global super sampling. A Boolean value - true if Disable all
Samplers is off, false if on.
640 Chapter 3 | Reserved Keywords, Symbols, Punctuation and Variables

MAXScript System Globals

These globals give access to the MAXScript system state. You can access and assign to them as noted.
currentTime
Contains a Time value that defines the current evaluation time in frames as set by the
at time context expression currently in force. This is useful in functions that need to do
time-relative computations that may be called from code that sets working animation
time. If there is no at time context in force, currentTime contains the current user
interface slider time, unless a render is in progress. If a render is being performed,
currentTime contains the frame being rendered. This variable is read-only.
editorFont
Lets you get and set a String value that defines the font name for script Editor windows.
Setting this variable effects all currently open and future script Editor and MAXScript
Listener windows. This variable contains the corresponding value set in the MAXScript
page of Customize > Preferences.
editorFontSize
Lets you get and set an Integer value defining the font point size for script Editor. Setting
this variable effects all currently open and future script Editor and MAXScript Listener
windows. This variable contains the corresponding value set in the MAXScript page of
Customize > Preferences.
editorTabWidth
Lets you get and set an Integer value defining the tab width (in characters) for script Editor
windows. Setting this variable effects all currently open and future script Editor windows.
This variable contains the corresponding value set in the MAXScript page of Customize >
Preferences.
escapeEnable
Lets you get and set a Boolean value defining whether ESC key interrupt detection is on or
off. Setting enableEscape to false turns ESC key interrupt detection off, setting it to
true turns it on again. This variable is useful when used in conjunction with a Progress
Bar. You can set enableEscape to false when you don’t want the user to be able to
interrupt a script running a long computation and you have set up a progress bar with its
own Cancel button. See Progress Bar Display (p. 1578).
heapFree
Contains an Integer value defining the current amount of free memory in the MAXScript
heap. This value will vary constantly depending on where MAXScript is in its collection
regime. This variable is read-only.
 MAXScript System Globals 641

heapSize
Lets you get and set an Integer value defining the size of the heap currently allocated to
MAXScript. MAXScript carves its own working memory (called a heap) out of the memory
that 3ds max has allocated. You can add to this heap at any time by assigning the new size
to this system variable, as in:
heapSize += 1000000 -- another meg please

See also the Memory Allocation and Garbage Collection (p. 655) topic.
inputTextColor
Lets you get and set a Color value defining the color of typed input text in Listener.
messageTextColor
Lets you get and set a Color value defining the color of error message text in Listener.
outputTextColor
Lets you get and set a Color value defining the color of output text in Listener.
options.oldPrintStyles
The printed form of all basic data value types, except for BigArray, are directly readable by
the readValue() and readExpr() functions, making it simpler to read back in values
printed to a file by MAXScript. If the pre-3ds max 4 print forms are required for
compatibility with existing scripts, you can set this variable to true.
stackLimit
The stack is region of reserved memory in which MAXScript temporarily stores status data
such as procedure and function call return addresses, passed parameters, and local
variables. This defaults to 1Mb, but you may have certain scripts that contain recursive
algorithms that will exceed this limit and so generate a runtime error. You can assign to
the stackLimit variable to increase the stack size available.
stackLimit *= 2 -- double the stack

?
A special variable that is used only in the context of the MAXScript Listener. This variable
contains the result of the last expression evaluated in the Listener. For more details, see the
Using the ‘?’ Symbol (p. xli) topic.
642 Chapter 3 | Reserved Keywords, Symbols, Punctuation and Variables
Chapter 4: Variables - Assignment and Scope

A variable is a user-defined container to which you can assign a value, and then later retrieve the
value. A variable is identified by its name, and anywhere the variable name is referenced, the value
stored in that variable is used.
In this section, the various attributes and considerations associated with variables are described.

See also
Variable Assignment (p. 643)
Scope of Variables (p. 646)
Persistent Global Variables (p. 651)
Type-Free Variables (p. 653)
Reference Assignment (p. 653)
Memory Allocation and Garbage Collection (p. 655)
Manual Garbage Collection (p. 656)

Variable Assignment
The syntax for general assignment, <assignment>, is:
<destination> = <expr>
where <destination> can be one of:
<var_name>
<property>
<array_index>

Each of these destination type is described below.

MAXScript provides a swap() method that takes two valid assignment destinations as arguments
and swaps their values. Its syntax is:
swap <destination> <destination>
644 Chapter 4 | Variables - Assignment and Scope

Assignment to Variables
A variable is identified with a MAXScript <var_name>, as described in the Names (p. 657) topic. If
<destination> is a var_name, it identifies the variable to be assigned a value, as shown in the
following examples:
x = 2 + 2 * 3 -- assign to variable x
y = [1, 2, 3] + pos -- assign to variable y
z = #(1, 2, “foo”, “bar”) -- assign to variable z
z = #oops -- oops, changed my mind

Assignment to Accessors
If <destination> is a <property> or an <array_index>, the assignment is to an accessor.
Accessors are constructs used to access the components in compound values, such as arrays and
3D points. There are two kinds of accessors corresponding to the two kinds of compound values in
MAXScript:
• The component values are arranged in an indexable sequence, as in arrays or strings.
• The compound value contains a fixed set of named components, as with 3D points and time
intervals.
All 3ds max objects, such as boxes, spheres, bend modifiers, or bitmap textures are treated as
compound values in this sense. All their parameters, such as height and angle, or map file name, are
accessed as named components. In MAXScript, these named components are referred to as properties.
For more information, see the Properties, Methods, Operators, and Literals (p. lxiv) topic.
Accessors have one of two forms, an <array_index>:
<operand> [ <expr> ] -- an indexed element
or a <property>:
<operand>.<var_name> -- a named property – property var_name of value in operand

Examples of assignment to accessors are:

$box01.pos = baseObj.pos + (baseObj.radius*[0,0,1])
Set the position property of object box01 based on the position and radius properties of
the object whose value is stored in variable baseObj.
z[2] = d.rotation as eulerangles
Convert the rotation property value of the value stored in variable d to an eulerAngles
class value, and store this value in element 2 of the array stored in variable z.
Because MAXScript is an origin 1 language, all sequencable collections in MAXScript start at index
position 1. This is an important convention to remember when using the indexing operator.
The syntax definitions allow you to use any <operand> before the . or []. Because accessors are
themselves operands, this definition is recursive, which means you can string accessors together to
query nested arrays or properties:
my_things[i][j]
my_objects[i].target.position.x
 Variable Assignment 645

Accessors are evaluated left-to-right. The first example evaluates the i‘th element of my_things,
which is presumably a nested array or an array of strings, before yielding the j‘th element of that
element.
The second example retrieves an object from an array of my_objects, then its target, then the
position of the target (a 3D point), and finally the x coordinate of that point.
An <operand> can also be a block-expression, allowing you to compute the target object to be
accessed. For example:
(instance myNode).pos=myNode.parent.pos
Create an instance of the node whose value is stored in variable myNode, and set its
position to the position of the myNode‘s parent object.
(find_table “foo”)[n - 2] = “fred”
Call function find_table with a parameter value of “foo”. The return value from the
function is presumably an array. Set element n-2 of this array to the value “fred”.
The named properties defined for the MAXScript values and classes are documented with the value
and class descriptions.
Order of Evaluation
In an assignment, <expr> is evaluated before <destination>, as can be seen in the following
example:
Script:
a=#() -- create an empty array to play with
a[(print “in <destination>“;1)]=(print “in <expr>“;10)

Output:
#() -- result line 1
“in <expr>“ -- output from <expr> side of assignment
“in <destination>“ -- output from <destination> side of assignment
10 -- result line 2

Assignment in MAXScript is itself an expression and yields the value just assigned. Therefore, you
can use assignments inside other expressions or cascade assignments, as in:
x = y = z = 0
#(1, 2, a = [0,0,1], 4)
646 Chapter 4 | Variables - Assignment and Scope

Scope of Variables
Variables have an attribute called scope, which determines where in MAXScript code a variable can
be accessed. MAXScript has two kinds of variable scope, global and local. Global variables are visible
in all running MAXScript code and hold their values until you exit 3ds max. Local variables are
directly visible to code only in the lexical scope currently in effect, and hold their values only as long
as the current scope is active. Once a scope is no longer active, you can no longer access the contents
of a variable local to that scope. This is similar to how most modern programming languages
implement variables. The conditions under which MAXScript creates a new scope are
described next.
MAXScript provides language constructs used to explicitly declare and initialize both global and
local variables. The syntax for variable declaration, <variable_decls>, is as follows:
( local | global ) <decl> { , <decl> }
where <decl> is defined as:
<var_name> [ = <expr> ] -- name and optional initial value

Examples:
global baz -- initialized to ‘undefined’
global foo=10, initialized=false -- initialized globals
local x = 1, -- continued on several lines
y = 2,
z = sqrt(123.7)

As mentioned above, local variables hold their values as long as that scope is active. In nested scopes,
this is usually a very short period – it starts when a function or loop or block expression runs and
ends when it exits. Each time the scope is entered at runtime, a new set of locals is created and then
retired when the scope is exited.
In certain situations, however, the top-level scope can remains active for extended periods and so
the locals declared at that top-level hold their values for that extended period. In particular, top-level
locals declared in scripted rollouts, utilities, plug-ins, script controllers and Macro Scripts hold their
values for as long as the rollout, utility, plug-in, or Macro Script exists. Typically, they remain in
existence until you redefine them, so for example when you define a Macro Script and run it for the
first time, the top-level scope is created and remains active over any number of subsequent
executions unless you redefine the Macro Script. At this point, the existing top-level scope is retired
and a fresh one (along with its top-level locals) is created when you next execute the Macro Script.
This lets you use top-level locals in these constructs as a kind of private global; the values they hold
remain in place over many executions but only code in that construct can see the variable and so it
does not conflict with other globals.
Note that in scripted plug-ins, a separate copy of the top-level local scope is created for each instance
of the plugin and this scope remains active while that instance remains in existence up until the end
of the current 3ds max session.
 Scope of Variables 647

Note:
In 3ds max R2.x, the optional initialization value is applied to global variables only if the declaration
creates a new variable. So, for example, if you ran the following script twice, the value of x in the
second line would be 10 for the first execution, and 20 for the second execution. In 3ds max R3, the
optional initialization value is always applied to global variables.
global x = 10
print x
x=20
If you want to make the global variable initialization conditional in 3ds max R3, use a construct
similar to:
global foo; if foo == undefined do foo = 23
If you do not explicitly declare a variable, and the variable name does not exist at a higher scope,
MAXScript will create the variable the first time you use it and initialize it to hold the special value
undefined. You are not required to explicitly declare a variable, or initialize its value, before you
can use it. Variable names not explicitly declared by one of the previous statements are called
implicitly declared variables. The scope of implicitly declared variables is the MAXScript scope
context currently in effect when the variable is first used. The initial MAXScript scope context is
global, and new scope contexts are opened for the following:
• Top-level open parentheses in a script file or in the Listener
• Start of a function body
• Start of a for loop body
• Start of a utility, rollout, right-click menu, Macro Script, or tool definition
• Start of a rollout, utility, right-click menu, Macro Script, or tool event handler
• Start of a when body
Within these new scopes, newly referenced variables will be implicitly declared as local variables.
Scope contexts are nested, with the scope of a variable explicitly or implicitly declared at one scope
context level extending to all scope contexts below that level. Take for example the following script:
Script:
a=10 -- scope context: global
( b=20 -- new scope context: level 1
for i = 1 to 5 do -- new scope context: level 2
( j=random i a
k=random i b
print (j*a+k*b)
) -- end of scope context: level 2
a=a+b
) -- end of scope context: level 1
print a -- back to global scope context
print k
In this script, variable a is first used in the global scope context, and its scope includes scope contexts
global, level 1, and level 2. Variable b is first used in scope context level 1, so it is implicitly declared
as a local variable and its scope includes scope contexts level 1 and 2. Variables i and j are first used
648 Chapter 4 | Variables - Assignment and Scope

in scope context level 2, and their scope is only scope context level 2. The scope of variable k varies
depending on whether this script has been run before. The first time the script is run, variable k is
first defined at line 5, and its scope is scope context level 2. In line 11, variable k is used again.
Because the variable k defined at line 5 is no longer in scope, a new variable k is defined whose scope
is global. The second time you run the script, at line 5 MAXScript detects variable k already exists
and uses it. So the first time you run the script line 11 will print undefined, and the second time
you run the script line 11 will print the last value calculated at line 5.
Note:
The scope of the variable used as a for loop counter (variable i in the above script) is a special case.
The for loop counter variable’s scope is always the scope context created for the for loop. This is
true even if the for loop counter variable’s name has already been implicitly or explicitly declared
at a higher scope context level.
When you explicitly declare a local variable, you can reuse the same name as a variable at a higher
scope context level. If you do this, the newly declared local variable hides the outer variables with
the same name. Any reference to that variable name later in the local variable’s scope refers to the
new local variable. At the end of the local variable’s scope, the next outer variable becomes visible
again. This visibility scheme is called lexical scoping. An example of lexical scoping is shown in the
following script.
Script:
global foo = 23, x = 20 -- explicit declaration of foo and x,
-- scope is global
y = 10 -- implicit declaration of y,
-- scope is global
format “context level global: foo= %\n” foo
if x > y then
( -- top-level open parentheses - new
-- scope is created
local baz = foo + 1 -- uses the global foo
local foo = y - 1 -- declares 1st local foo, hides global foo
format “context level 1: foo= %\n” foo
b=box() -- b implicitly declared as local
b.pos.x = foo -- uses 1st local foo
if (foo > 0) then
(
local a
local foo = y - x -- a nested 2nd local foo, hides 1st local
format “ context level 2: foo= %\n” foo
a = sin foo -- uses 2nd local foo
format “a= %\n” a
) -- leave scope
b.pos.y = foo - 1.5 -- back to 1st local foo
format “context level 1: foo= %\n” foo
) -- leave scope
-- b, baz and foo no longer in scope
format “context level global: foo= %\n” foo -- back to global foo
 Scope of Variables 649

Output:
20 -- result of line 1
10 -- result of line 3
context level global - foo= 23 -- output from line 5
OK -- result of line 5
context level 1: foo= 9 -- output from line 11
context level 2: foo= -10 -- output from line 18
a= -0.173648 -- output from line 20
context level 1: foo= -10 -- output from line 23
OK -- result of if expression lines 6 to 24
context level global: foo= 23 -- output from line 26
OK -- result of line 26

This might seem a strange way of over-using a single variable name, but in large programs, these
scoping rules can be useful. For example, you may add a new user-interface item and its handlers to
a utility script. By explicitly declaring the variables used in the handlers as local, you ensure these
variables are independent of any preexisting variables with the same names in the remainder of the
script.
When writing scripts, it is good programming practice to explicitly declare your local and global
variables. Implicit declaration is provided as a short-hand, typically used when working in the
Listener interactively or developing short scripts. When developing extended scripts, explicitly
declaring variables can reduce errors and improve readability of the code. It is also recommend that
you declare as local all variables unless you really want them to be global variables. There are several
reasons for this practice:
• All the variable names used in the block or function will be together, which makes it easier to
find the variable names and helps prevent using incorrect names in the script.
• If more than one script is executed at the same time (for example, you are running a scripted
utility and have a scripted controller in the scene) and both scripts use the same global variable
name, the two scripts can interfere with one another. This can cause apparently random failures
of one or both scripts.
• You are sure you are using the correct variable in the event that a variable with the same name
has already been declared at a higher scope, and you won’t inadvertently change the higher-
level variable’s value.
• Values of variables explicitly defined as local are displayed in error call stack trace-backs.
• In 3ds max R2.5, if a 3ds max class, a MAXScript method, or a MAXScript read-only global
variable has the same name as an implicitly declared local variable, a MAXScript runtime error
will be generated if an assignment to that variable name occurs. Since the variable name already
existed with a global scope, an implicitly declared local variable was not created. Since one or
more new 3ds max classes will be created by any third party plug-ins the user has loaded, you
were not be able to tell ahead of time if a variable name was a global variable name. In
3ds max R3, if the MAXScript compiler detects that the first reference to such a variable is an
assignment, it will implicitly declare a local variable, rather than leaving it as a reference to a
read-only system global. For example, executing the following expression in 3ds max R2.5
would result in a value of Box, since Box is a 3ds max object class. In 3ds R3, MAXScript detects
650 Chapter 4 | Variables - Assignment and Scope

that the first use of variable box is an assignment and creates an implicitly declared local
variable box. The result of this expression in 3ds max R3 is the value undefined.
(if false do box=10;box)

In the following script, an error was introduced by using undefined variable k in line 7. In the
output, the error call stack trace-back shows the value for variable b in function afunc and in the
block-expression calling afunc.
Script:
fn afunc =
(
local b
b = box()
for i in 1 to 10 do
for j in 1 to 10 do
instance b pos:[i*20,j*30,30*sin(k*36)]
)
--
(
global c=10
local b
b=”hello”
afunc()
)

Output:
afunc()
-- Error occurred in j loop
-- Frame:
-- k: undefined
-- j: 1
-- called in i loop
-- Frame:
-- i: 1
-- called in afunc()
-- Frame:
-- b: $Box:Box102 @ [0.000000,0.000000,0.000000]
-- called in <block>()
-- Frame:
-- b: “hello”
-- No ““*”“ function for undefined
OK

If the same script is run with lines 3 and 12 removed, the following output is generated. Because
function afunc and the block-expression are in different MAXScript scope contexts, variable b is
implicitly declared as local in each and contain different values. However, because they were
implicitly defined, they are not included in the error call stack trace-back.
 Persistent Global Variables 651

Output:
afunc()
-- Error occurred in j loop
-- Frame:
-- k: undefined
-- j: 1
-- called in i loop
-- Frame:
-- i: 1
-- called in afunc()
-- Frame:
-- No ““*”“ function for undefined
OK

See also
Type-Free Variables (p. 653)
Reference Assignment (p. 653)
Visibility of Locals, Functions, Structures and User-Interface Items in Rollout Code (p. 1478)
Accessing Locals and Other Items in a Rollout from External Code (p. 1480)

Persistent Global Variables

MAXScript supports a limited form of persistent global variables. You declare a particular global to
be persistent and the value it contains is always saved to and restored from scene files as they are
opened and closed. Therefore, you can keep direct references to objects in the scene in variables and
those references will persist across scene save and reload.
You declare a global variable as persistent by prefacing its declaration with the reserved word
persistent. For example:
persistent global foo, baz, bar
declares the variables foo, baz, and bar to be persistent. From then on, the values in foo, baz, and
bar at the time of a scene save are stored in the .max scene file. When that file is reopened, the
values in foo, baz, and bar are restored, with an implicit declaration as persistent globals if they are
not so already declared.
The current limitation with persistent global variables is that only certain kinds of value are storable
in a scene file, and only those types of values are saved and restored across scene saves and loads.
The supported value classes are: Integer, Float, String, Color, Time, Interval, Array, Point3, Ray, Quat,
AngleAxis, EulerAngles, Matrix3, Point2, Undefined, OK, Boolean, and all the MAXWrapper classes
(nodes, modifiers, controllers, materials, and so on). All other types of values restore as the value
undefined.
In the case of Array, only those values in the array that are in the previous list are correctly saved
and restored; others appear as undefined in the restored array.
Persistent globals are removed when a File > Reset, File > New, or File > Open is performed, so
persistent globals added to one file do not “stick around” and become part of every other file opened
652 Chapter 4 | Variables - Assignment and Scope

and saved. If needed, you can install persistent globals in each new file in a #filePreSave callback.
See the General Event Callback Mechanism (p. 29) topic for more information.
The following methods are used to show and delete persistent globals variables:
persistents.show()
Displays a list of persistent globals and their value.
persistents.remove <var_name>
Removes the named persistent global from the persistent global pool. The variable remains
as a global variable and retains its value.
persistents.removeAll()
Removes all persistent globals from the persistent global pool. The variables remain as
global variables and retain their value.
Script:
a=”Hello world”
persistent global a
persistent global b=box()
persistents.show()
persistents.remove #a
persistents.removeall()
a
b

Output:
“Hello world”
OK
$Box:Box02 @ [0.000000,0.000000,0.000000]
a: “Hello world”
b: $Box:Box02 @ [0.000000,0.000000,0.000000]
OK
OK
OK
“Hello world”
$Box:Box02 @ [0.000000,0.000000,0.000000]

Note:
If a persistent global contains a MAXWrapper value, but the class instance is not in the scene, that
value is not stored/restored on a file save/load.
Example:
-- persistents - node only
persistent global global_array = #()
global_array[1] = b= box()
global_array[2] = bm= bend()
global_array[3] = sm= standard()
global_array[4] = fog()
global_array[5] = area()
global_array[6] = bezier_float()
global_array[7] = br= bricks()
global_array[8] = lookat()
 Type-Free Variables 653

global_array[9] = blur()
global_array[10] = MapScaler()
--b.material=sm
--addmodifier b bm
--sm.diffusemap=br
persistents.show()
max hold
max fetch
persistents.show()

Remarks:
Only the box is in the array after running this script. If the commented lines are run, the material,
modifier, and map are also in the array. MAXScript does not do a full reference-tree dump when it
outputs its persistent variables, it just outputs RefIDs for MAX objects and so depends on them being
dumped as references by the main file save code.

Type-Free Variables
Variables can hold any type of value, and the value type they hold can change from assignment to
assignment. For example, you can store a point3 value, then a float value, and then an array to the
same variable. The variables in MAXScript are known as type-free variables, unlike variables in C or
Java, which can only hold values of a particular declared type. This freedom makes scripting simpler
and more exploratory.
As well as being type-free, variables in MAXScript are also type-safe. This means you cannot perform
the wrong operation on a value in a variable, as shown in the following example, where MAXScript
prints an error message following the invalid operation:
x = $Box01.position -- a point3 value
x = “foo” -- a string value
x = x + 2 -- try to add a number to a string
Error: Unable to convert 2 to type String

Reference Assignment
MAXScript uses a type of assignment called reference assignment. When you create a value, for
example by writing a literal, the memory for that value is allocated and a pointer or reference to the
value is placed into the variable rather than the value itself. If you assign that variable’s value to
another variable, the reference to that value’s memory is placed in the new variable. The same
applies to assigning a variable’s value to an array element or passing it as a function call argument;
in all cases the reference is assigned or passed. When you assign a new value to a variable or when a
variable goes out of scope, the reference that the variable contained is dropped. When your program
has dropped all references to a value’s memory, that memory becomes eligible for reclamation.
This is in contrast to value assignment in which a copy of the whole value’s memory is made and
assigned. Value assignment has one advantage over reference assignment, namely that every time a
variable or an array element is re-assigned, the old value’s memory space can be immediately
654 Chapter 4 | Variables - Assignment and Scope

reclaimed because the old value is unique and nothing else can be referring to it. With reference
assignment, the system cannot reclaim the original value’s memory space, because other variables
may still point to the same value.
Some scripting languages use a copy-based approach, such as HyperCard’s HyperTalk, but its
inefficiency as well as some value sharing problems make it inappropriate for MAXScript. This
creates the task of reclaiming memory in MAXScript. Programming languages such as C or Pascal
require that the programmer explicitly reclaim a value’s memory when it is no longer needed, and
this is one of the most difficult parts of programming in those languages. Recent variants like Java
and some advanced languages like Lisp and Smalltalk provide automatic memory reclamation.
MAXScript also provides this and it is described in the Memory Allocation and Garbage Collection
(p. 655) topic.
If you assign a variable’s value to another variable, the reference to that value’s memory is placed in
the new variable. Thus, both variables are actually referencing the exact same value. If you assign a
new value to one of the variables, that variable will contain a reference to the new value, and the
other variable will contain a reference to the old value. Normally this is the desired behavior, as you
don’t want both variables to reference the new value. However, a complication occurs if a compound
value, like a point3 or array, is referenced by more than one variable, and you assign a new value to
a component of the compound value. When you assign a value to a component of a compound
value, a new compound value is not created. Therefore any variables that reference the compound
value will still point to the same value, and will “see” the changed component value. Examples of
this behavior are shown in the following script:
Script:
(
a=”hello world” -- create a string value, put reference in a
b=a -- put string’s reference in b
format “a=%; b=%\n” a b -- and print their values
b=”thanks for the fish” -- create a string value, put reference in b
format “a=%; b=%\n” a b -- print values – they are different
b=a -- put string’s reference from a in b
a[1]=”J” -- change a component value
format “a=%; b=%\n” a b -- print values – they are the same
a=b=[10,20,30] -- assign a point3 value reference to a and b
format “a=%; b=%\n” a b -- and print their values
a.x=-100 -- change a component value
format “a=%; b=%\n” a b -- print values – they are the same
)

Output:
a=hello world; b=hello world
a=hello world; b=thanks for the fish
a=Jello world; b=Jello world
a=[10,20,30]; b=[10,20,30]
a=[-100,20,30]; b=[-100,20,30]
OK
 Memory Allocation and Garbage Collection 655

In some cases, this behavior is the desired behavior, and in other cases it is not. For those cases where
it is not the desired behavior, a copy method is defined for most value types that will create a
separate copy of a value. In some cases, such as arrays and structures, the value itself may contain
compound values. The copy made is what is called a shallow copy - only a copy of the upper-level
value itself (that is, the array) is created. Copies aren’t made of compound values in the value (that
is, the elements of the array).

Memory Allocation and Garbage Collection

MAXScript allocates its own working memory in addition to any memory 3ds max allocates as it
works. The default working memory size setting for MAXScript is 5.5 MB, and the memory is virtual
and pageable like all 3ds max memory. The default allocation accommodates most tasks, but you
can increase it by incrementing the MAXScript system global variable heapSize:
heapSize += 2000000 -- another 2 MB, for a total of 7.5 MB
You can add this statement to your startup script if you always need extra memory allocated for
MAXScript tasks or you can set the default size in the MAXScript tab in the 3ds max Preferences
dialog.
Increasing the MAXScript heap reduces memory address space for other 3ds max tasks. Adjust the
default memory setting only after you receive “Out of memory” error messages from MAXScript, or
when garbage collection pauses occur frequently.
You can increase the MAXScript heap as many times as you need during a 3ds max session, but you
cannot reduce it. Restart 3ds max to reset the MAXScript memory heap to the default setting.
MAXScript uses a memory management scheme called automatic garbage collection. This means you
don’t have to explicitly reclaim any memory that a value takes up when you no longer need it.
When you assign a new value to a variable or when a local variable’s block exits, the reference that
the variable contained is dropped. When your program has dropped all references to a value’s
memory, that memory becomes eligible for reclamation.
Some values, such as arrays, have internal references to other values. In an array, each element
contains a reference to another value. When you assign a new value to an array element, the
element’s old reference is dropped. If you remove all references to the array itself, all the references
in the elements of that array are implicitly dropped. The same applies to component values, such as
in user structures and most 3ds max objects.
MAXScript reclaims memory in a garbage collection pass through memory when MAXScript runs
out of memory. This simple approach can result in a short pause because the entire MAXScript
memory is scanned for garbage. Some languages use background collectors that work continuously;
others use advanced schemes that minimize the scanning. Later versions of MAXScript might adopt
one or more of these techniques.
The advantage of garbage collection is you can create as many values as you need, and MAXScript
cleans up the ones you no longer use.
656 Chapter 4 | Variables - Assignment and Scope

Manual Garbage Collection

The function gc() invokes the garbage collector. Normally, the collector runs automatically when
available memory runs low, so you don’t normally need to call it explicitly. However, in some
situations, it is useful to be able to force a collect to ensure a pause due to garbage collection will be
delayed as long as possible.
You can also invoke the collector to cause any unreferenced open files to be closed. In some
situations, a file can be left open if a runtime error occurs while it is still open. If the file object was
being held in a local variable at this point, it may not be possible to get at it from the Listener to
force a close. Any subsequent attempts to open it may result in an “already open” error from the
operating system. Running the collector will cause the file object to be reclaimed and this forces any
open file associated with it to be closed.
gc()
This function returns the number of bytes free in the MAXScript heap after collection. Note that the
collector may take many seconds to run if the heap is full of many small reclaimable objects.
Chapter 5: Names, Literal Constants, and Expressions

Names
Names are used in MAXScript to identify variables, functions, parameters, properties, and so on.
Names start with an alphabetic character or “_” (underscore), and can contain any number of
alphanumeric characters or “_”.
Examples of valid names are:
foo
bar123
this_is_a_very_long_identifier
_heresOneWithStudlyCaps

The following names are not valid:

1object First character not an alphabetic character
pressed? ? is not a valid alphanumeric character
a big number spaces not allowed in names
seven(7) ( and ) are not valid alphanumeric characters

In contrast to most general purpose programming languages, MAXScript names are not case-
sensitive. For example, the names in the following list refer to the same variable in MAXScript:
BitMapTexture
bitmaptexture
BITMAPtexture

In syntax descriptions, name identifiers are specified as:

<var_name>

An example of a syntax where a name identifier is specified is:

for <var_name> ( in | = ) <sequence> ( do | collect ) <expr>
In this example, <var_name> specifies the for loop variable.
658 Chapter 5 | Names, Literal Constants, and Expressions

A name in a program is always interpreted as the name of a variable or parameter and it effectively
stands for the current value of that variable or parameter in any expression in which it is used. For
example, consider the following script:
i=10
j=i+5
print j
In this script, i and j are variable names. In the first line, the value 10 is assigned to variable i. In
the second line, the value 5 is added to the value stored in variable i, and then the result is stored
in variable j. In the third line, the value 15 is printed, which is the value stored in variable j.
MAXScript also allows you to work directly with names as values at runtime, as you can with
numbers and strings. To write a name value in MAXScript, you preface the name with a “#”:
#<var_name>

In syntax descriptions, name values are specified as:

<name>

Name values are primarily used for symbolic parameters in function calls, and many of the built-in
functions use them as such. The allowed values specified for symbolic parameters are defined by the
function, and are documented with the function. As an example, consider the setBeforeORT()
function. Its syntax is:
setBeforeORT <controller> <ORT_type_name>
Sets the Out-of-Range (ORT) type for the controller for the time before the first key. The
<ORT_type_name> must be one of the following name values:
#constant
#cycle
#loop
#pingPong
#linear
#relativeRepeat

An example usage of this function is:

setBeforeORT $box01.position.controller #pingPong

Name values can also be used as an index in certain Collections (p. 773). For example, the index for
a ModifierArray (p. 794) can be an integer, name, or string:
$loft01.modifiers[#Optimize] -- access modifier on object loft01 called Optimize

See also
Name Values (p. 727)
 659

Quoted Names
Names set in single quotes allow you to write names that contain illegal identifier characters, such
as spaces and other punctuation. They are primarily intended for specifying 3ds max object classes
and properties that have special characters in their names.
The form is:
‘<any_char_except_quote>‘ -- for an identifier or property name
#’<any_char_except_quote>‘ -- for a name literal
‘<any_char_except_quote>‘: -- for a keyword parameter label

Examples:
snow ‘starttime(start)’:5
b.’lifetime(life)’
$box01.modifiers[#’FFD 4x4x4’]

Spaces in Names
Because of the large amount of names in 3ds max that include spaces, the underscore character (“_”)
can be used instead of a space in a name. The following is equivalent to the last line of the above
example:
$box01.modifiers[#FFD_4x4x4]

Literal Constants
MAXScript has many built-in data types: numbers, strings, names, arrays, vectors, and matrices, as
well as special data types which store the 3ds max objects such as geometry objects, splines,
materials, modifiers, etc. Some data types have special literal constant forms, where the literal
constant is a value that is keyed directly into your program where it is needed. The syntax of the
literal constant specifies both its value and data type. In MAXScript, the assignment of a literal
constant might look like this:
b=50
In this line, b is the variable name, and 50 is the literal constant of type integer assigned to b. 50 is
a literal constant because you cannot assign a value to 50, and its value cannot be changed.

See also
Number Literals (p. 660)
String Literals (p. 660)
Time Literals (p. 662)
Pathname Literals (p. 662)
2D and 3D Point Literals (p. 665)
Array Literals (p. 666)
660 Chapter 5 | Names, Literal Constants, and Expressions

Number Literals
MAXScript uses two types of numbers:
• single precision floating point
• 32 bit signed integers
These number types correspond to the two number types (Integer and Float) used internally in
3ds max. The syntax for numbers is:
[-]{<digit>}[.{<digit>}[(e | E)[+ | -]{<digit>}+] -- decimal number
0x{<hex_digit>}+ -- hexadecimal number

Examples:
123
123.45
-0.00345
1.0e-6
0x0E
.1

See also
Number Values (p. 717)

String Literals
String literals in MAXScript are one or more characters enclosed in double quotes:
“3ds max”
“October 5th, 1996”

String literals can contain any character except another plain double quote. You can include a
double quote in a string literal, as well as some useful control characters, by using a “\” (backslash)
escape character sequence. The valid escape sequences are:
\“ -- a double quote character
\n -- a newline character
\r -- a carriage return character
\t -- a TAB character
\* -- an asterisk character
\? -- a question mark character
\\ -- a single “\” character
\% -- a percent character
\x{d} -- a hexadecimal character
 String Literals 661

Example:
print “foo should be quoted like this: \“foo\“ and a new line: \n”
would output:
“foo should be quoted like this: “foo” and a new line:
“

A “\” character that does not preface one of the specified characters is left as a single backslash.
You can break a string literal into several lines and the line breaks will stay in the string. For example:
“Twas brillig and the slithy tobes
did gyre and gimbol in the wabe
or something like that...”

Non-Printing Characters in Strings

You can specify non-printing characters in string literals using the \x hexadecimal escape sequence
convention from C/C++. The form is:
\x{<hex_digit>}+ -- <hex_digit> is a hexadecimal digit (0-9,a-f)

Example:
str = “Copyright \xa9 1997, FrabWorks, Inc”
would insert a copyright sign ©. Hexadecimal a9 is the code for that symbol.
Running the following script displays in Listener the characters associated with each
hexadecimal code:
Script:
char=”0123456789abcdef”
for i=1 to char.count do
for j=1 to char.count do
( s=execute(”\“\\x”+char[i]+char[j]+”\““)
format “%% %\n” char[i] char[j] s
)

File Path Name Strings

File path name strings use the backslash character to separate a parent directory from its sub-
directory. The backslash is used as an escape character, therefore file path names specified in a string
should use the escape character sequence for a single “\” character, i.e., “\\”. An example is:
scene_path = “g:\\3dsmax25\\scenes” -- specifies file path g:\3dsmax25\scenes

For strings that are used as file names or paths, the “/” character can be used instead of the “\\”.
MAXScript internally interprets the “/” character as a “\” character when used in a file path name
string. An example is:
scene_path = “g:/3dsmax25/scenes” -- specifies file path g:\3dsmax25\scenes

See also
String Values (p. 722)
662 Chapter 5 | Names, Literal Constants, and Expressions

Time Literals
Time is a basic data type in MAXScript. Its semantics are based on animation time in 3ds max, where
you can express time in frames, ticks or normalized time. In 3ds max, time is stored with a resolution
of 4800 ticks per second. The format for a time literal is one of:
[-]{<decimal_number>[m | s | f | t]}+ -- minutes/sec/frames/ticks
[-]{<digit>}:{<digit>}[.{<digit>}] -- SMPTE mins:secs.frame
[-]<decimal_number>n -- active segment normalized time
In the first form, the {...}+ indicates one or more repetitions, so you can string together minutes/
seconds/frames/ticks. If you do this, they must be in the specific minutes/seconds/frames/ticks
order.
The normalized time form is always relative to the current active animation time segment.
Examples:
2.5s -- 2.5 seconds
1m15s -- 1 minute 15 seconds
2m30s5f2t -- 2 minutes 30 seconds 5 frames 2 ticks
125f -- 125 frames
18.25f -- 18.25 frames
1f20t -- 1 frame 20 ticks
2:10.0 -- 2 minutes 10 seconds 0 frames (SMPTE)
0:0.29 -- 29 frames (SMPTE)
0.45n -- 0.45 normalized time (fraction of active segment)

See also
Time Values (p. 751)

Pathname Literals
Names (p. 657) identify entities such as variables and parameters inside the running MAXScript
program. If you want to identify objects by name in the 3ds max scene, you use a pathname.
Pathnames can name a single object in the scene, specify a particular object using a path through
the object hierarchy, or name sets of objects using pattern matching.
The full syntax for a pathname literal is:
<path_name> ::= $<path> | $
<path> ::= [ <objectset> ] [ / ] [ <levels> ] <level_name>
<levels> ::= <level> { / <level> }
<level> ::= <level_name>
...
<level_name> ::= { <alphanumeric > | _ | * | ? | \ }
‘{ <alphanumeric > | _ | * | ? | \ }‘

The root of a <path> can be an <objectset>, which limits the pathname searching to the object
set you specify. ObjectSets are described in the ObjectSet Values (p. 781) topic.
 Pathname Literals 663

Examples:
$box01 -- object named ‘box01’
$torso/left_up_arm/left_low_arm -- hierarchy path name
$*box* -- all objects with ‘box’ in
-- the name
$torso/* -- all the direct children of
-- $torso
$helpers/d* -- all helper objects whose name
-- starts with ‘d’

All objects in a 3ds max scene are arranged in a hierarchy as presented in Track View. This is both an
important organizing scheme in 3ds max, and it suggests a MAXScript naming scheme for objects
based on the path to an object through the hierarchy. It is also very similar to path names in an
operating system’s directory structure. For example,
$dummy/head/neck
names the scene object neck whose parent is object head, which has the top-level parent
object dummy. This pathname helps you identify a specific object in a 3ds max scene, even
if several objects have the same name. If head is unique in the scene, MAXScript lets you
use the shorthand $head to refer to it regardless of its hierarchy position. Even if the
object is not uniquely named you can use the shorthand form, but it is undetermined
which of the same-named objects you will get.
Pathnames also provide a powerful way to refer to several objects at once, such as all the children of
a certain parent, or all the objects with names containing the string foot. For this, you can use
wild-card patterns, as you can with operating system shell file naming schemes. For example,
$dummy/*
names all the immediate children of dummy. The “*” character is used as a wild card. Or,
$neck*
finds all the objects, whose names start with the string neck, anywhere in the hierarchy.
You can use wild cards anywhere in a pathname. For example,
$*foot*
finds all the objects with foot anywhere in their names. The “*” wild-card character
effectively matches any number other characters.
You can also use the “?” wild-card character to match exactly one “don’t care” character. This is, the
“?” wild-card character will match any single character. For example,
$box0?
finds all the objects that begin with box0 and have exactly one character after the 0 in
their names.
Wild-card characters can also be used for specifying parent levels in a hierarchy. For example,
$dummy/*/*
names all the children of all the children of $dummy.
664 Chapter 5 | Names, Literal Constants, and Expressions

If you want to find an object and all the children of the object at any nested level, you use the special
ellipsis level name “...”, as in:
$dummy/.../box*
This refers to $dummy and all the box* children at any level below $dummy. The “...” indicates to
search the entire hierarchy below the level of the ellipsis. MAXScript lets you omit the “/” when
using “...” because it is unambiguous:
$dummy...box*
Or, in another common example,
$dummy...*
names $dummy and all the children of $dummy at any level.
If you use a wild card in an object pathname MAXScript will manipulate all matching objects at one
time. For example,
hide $*foot*
hides all objects whose names contain foot.
You can also perform automatic collection mapping, where a property for each matching object is
set. For example,
$*box*.position += [10, 10, 0]
adds [10,10,0] to the positions of all scene objects whose names contain box. For more
information, see the Collections (p. 773) topic.
You can use a shorthand form for specifying the currently selected object or objects with the
pathname syntax. A lone “$” character refers to either the currently selected object if a single object
is selected, the current selection set as an ObjectSet if more than one object is selected, or undefined
if no objects are selected. This is a useful shorthand for use in the Listener when working on
selections. For example:
$.pos = [0,0,0]
hide $
rotate $ 35 z_axis

Inside a script, it is better to use the selection ObjectSet rather than $. selection always contains
an ObjectSet regardless of the number of selected objects. Where hide $ will generate an error if no
objects are selected (because $ contains the value undefined), hide selection will not generate
an error. Due to the way that 3ds max internally processes notification signals, the $ form of
accessing selected objects is not recommended in a select change handler. To access the selected
objects, you should use the selection ObjectSet. This is because $ relies on information that has
not yet been set in the selection processing whereas selection uses a different method of accessing
selections and the information it uses has been set up.

See also
Spaces and Other Special Characters in Pathnames (p. 665)
ObjectSet Values (p. 781)
Collections (p. 773)
 Spaces and Other Special Characters in Pathnames 665

Spaces and Other Special Characters in Pathnames

3ds max lets you use any characters you want in object names, including spaces and other
MAXScript punctuation. You can write pathnames that contain these characters by putting the
name in single quotes, for example:
$’a silly name!!’
These quotes do not hide wild-card characters, so if you happen to have an object in your scene with
a “*” in its name, you have to escape the “*” character in the pathname with a backslash:
$’what the \*’

See the String Literals (p. 660) topic for other escape character sequences.
Because of the large number of names in 3ds max that include spaces, the underscore character (“_”)
can be used instead of a space in a name. For example, the following two lines are equivalent:
bodyPart=$’Bip01 L UpperArm’
bodyPart=$Bip01_L_UpperArm

2D and 3D Point Literals

Coordinates are used extensively in MAXScript programming. They support a large range of
operations as described in the Point2 Values (p. 736) and Point3 Values (p. 731) topics. You can write
point literals using the following forms:
2D
[ <expr>, <expr> ]

3D
[ <expr>, <expr>, <expr> ]
where <expr> evaluates to an Integer or Float value.
Examples:
[320, 240] -- 2D point
[10, 20, 30] -- 3D point

Expressions in a literal are evaluated when the literal is built. The following script and results show
the value stored in a Point3 when expressions are used in the literal:
Script:
a=10
b=45
[10, 20, 30]
[sin a, 2 * b, a^2 + b^2] -- can contain expressions
666 Chapter 5 | Names, Literal Constants, and Expressions

Output:
10.0 -- result of line 1
45 -- result of line 2
[10,20,30] -- result of line 3
[0.173648,90,2125] -- result of line 4

See also
Point2 Values (p. 736)
Point3 Values (p. 731)

Array Literals
An array in MAXScript is an ordered collection of values. Each element in the array can contain any
type of value, and you can index and iterate an array. You can write array literals directly in a
program or build the collection with the array functions provided in MAXScript. For details, see the
Array Values (p. 776) topic. Array literals can be expressed in two forms:
#( <expr> { , <expr> } )
#() -- empty array

Examples:
#(1, 2, 3)
#()
#(1,”foo”,#(1.2, -4,#fred),[1,2,3]) -- this one has a nested array

Expressions in an array literal are evaluated when the literal is built. The following script and results
show the values stored in an array when expressions are used in the literal:
Script:
a=10
x=45
#(1, sin x, a * 2.3) -- can contain expressions

Output:
10.0
45
#(1, 0.707107, 23.0)
 Array Literals 667

Expressions
MAXScript is an expression-based language. Every construct in the language is an expression and
yields a result; this includes constructs that other languages consider statements. The simplified
syntax of the language allows you to build very expressive code. Anywhere you can write an <expr>
expression, you can write any construct in MAXScript.
A good example of this is the if construct. In statement-based languages, there is usually one syntax
for if statements and another for conditional expressions. In MAXScript, a single syntax is used for
both cases. For example, the following two lines of code are both valid, and their meaning should
be obvious:
if a > b then print c else print d
x = if a > b then c else d

You can also write the following line, containing a nested if expression and a nested assignment,
which itself is an expression:
x = if (if a > b then c else d) < e then f else (g = 23)

Another example is the block-expression, denoted <block_expr>. It contains a series of <expr>

expressions enclosed in parentheses:
(
print a
print b
if a > b then print “the big a”
)

Each expression in the block is separated by a line break. You can also write several expressions on
one line using a “;” (semicolon) to separate them:
(print a; print b; if a > b then print “the big a”)

Block-expressions are themselves <expr> expressions. They evaluate their component expressions
in sequence and yield as their value the value of the last expression in the block.
To create classic block-structured statements, you might write:
if a > b then
(
print c
x = sqrt (c)
)
else
(
print d
x = sin (e)
)

or, use a nested block-expression to compute a comparison operand:

if a > (y = sin b; sqrt(y * z)) then print c
668 Chapter 5 | Names, Literal Constants, and Expressions

At its simplest, a MAXScript program is made up of <expr> expressions. An <expr> is defined as

any of the following:
<simple_expr>
<variable_decls>
<assignment>
<context_expr>
<if_expr>
<while_loop>
<do_loop>
<for_loop>
<loop_exit>
<case_expr>
<try_expr>
<function_def>
<function_return>
<struct_def>
<max_command>
<utility_def>
<rollout_def>
<tool_def>
<rcmenu_def>
<plugin_def>

This list of expressions constitute the main constructs in MAXScript.

See also
Simple Expressions (p. 669)
Context Expressions (p. 681)
Controlling Program Flow (p. 691)
Creating Functions (p. 699)
Structure Definition (p. 707)
Literal Constants (p. 659)
Variables – Assignment and Scope (p. 643)
3ds max Commands (p. 1630)
Scripted Utilities (p. 1463)
Utility Clauses (p. 1466)
Scripted Mouse Tools (p. 1531)
Scripted Right-Click Menus (p. 1514)
Scripted Plug-ins (p. 1538)
 Array Literals 669

Simple Expressions
Simple expressions in MAXScript, denoted as <simple_expr>, correspond to the constructs
normally considered expressions in math and conventional programming languages, as in the
following examples:
a + b * c
sin x
The expressions are generally comprised of operands (a, b, c, and x), that are acted on by operators
(+ and *) or given as parameters to functions (sin). Simple expressions are divided into the following
groups:

See also
Operands (p. 669)
Math Expressions (p. 670)
Comparison Expressions (p. 673)
Logical Expressions (p. 674)
Function Calls (p. 675)
Block-Expressions (p. 679)

Operands
Operands, denoted as <operand> in the syntax definitions, are the references to values that
surround operators or are passed as parameters to a function. Prime examples are Literal Constants
(p. 659) and variable names. Operands are divided into two groups, Factors and Accessors.
Factors
Factors, denoted as <factor> in the syntax definitions, are references to values, where the entire
value is acted on. A factor can be a Literal Constants (p. 659), a Reserved Global Variable (p. 628), a
variable name, or an expression.
The unary minus applies the math negate operator to its operand.
-<operand> -- unary minus

The unary minus is only applicable to factors that evaluate to a number.

Examples:
-0.75
sin (-a*pi)
670 Chapter 5 | Names, Literal Constants, and Expressions

Accessors
Accessors are constructs that let you access the components in compound values, such as arrays and
3D points. There are two kinds of accessors corresponding to the two kinds of compound values in
MAXScript:
• The component values are arranged in an indexable sequence, as in arrays or strings.
• The compound value contains a fixed set of named components, as with 3D points and time
intervals.
All 3ds max objects, such as boxes, spheres, bend modifiers, or bitmap textures are treated as
compound values in this sense. All of their parameters, such as height and angle, or map file name,
are accessed as named components. In MAXScript, these named components are referred to as
properties.
Accessors have one of two forms, an <array_index>:
<operand> [ <expr> ] -- an indexed element

or a <property>:
<operand>.<var_name> -- a named property

Examples:
maps[i]
selection[n+1]
position.x
bend.angle

Math Expressions
The math expressions in MAXScript correspond to the common operator expressions in
mathematics, such as add, subtract, multiply, divide, and so on. The <math_expr> constructs in
MAXScript are:
<math_operand> + <math_operand> -- standard arithmetic addition
<math_operand> - <math_operand> -- standard arithmetic subtraction
<math_operand> * <math_operand> -- standard arithmetic
-- multiplication
<math_operand> / <math_operand> -- standard arithmetic division
<math_operand> ^ <math_operand> -- exponential, raise to the power
<math_operand> as <class> -- conversion between types

where <math_operand> can be one of:

<operand>
<function_call>
<math_expr>

Note that a math operand can be another nested math expression. This is another instance of a
recursive syntax definition which lets you create arbitrary sequences of operands and operators.
 Math Assignment 671

Note also that the math unary minus is not defined here, it is one of the <operand> types described
in the Operands (p. 669) topic.
Examples:
42
2 + 2
2 * a - sin x / b -- using a function call
(a + b) * -c
2 ^ n
(n + 1) as string -- converts result to a string value
The conversion operator, as, works between selected sets of source and destination value types. Only
certain kinds of values can be converted into certain other kinds of values. These allowed
conversions are defined for each type of value, and are documented with the value type descriptions.

See also
Math Assignment (p. 671)
Precedence and Association Rules (p. 672)
Polymorphism (p. 672)

Math Assignment
MAXScript provides the C language shorthand form of assignment that can be used to modify a
value in place, as shown in the following long-form examples:
x = x + 1 -- increment x by one
$obj.pos = $obj.pos * scale -- multiply $obj.pos by scale

Corresponding to the four math operations (+, -, *, and /) are assignment operators that apply the
operation to the assignment’s destination and update the destination with the result. Their syntax is:
<destination> += <expr> -- add <expr> to destination
<destination> -= <expr> -- subtract <expr> from destination
<destination> *= <expr> -- multiply destination by <expr>
<destination> /= <expr> -- divide destination by <expr>

Using the shorthand form of assignment, the previous examples can be written as:
x += 1 -- increment x by one
$obj.pos *= scale -- multiply $obj.pos by scale
672 Chapter 5 | Names, Literal Constants, and Expressions

Precedence and Association Rules

As in mathematics, a sequence of operands and operators is evaluated according to a set of
precedence and association rules. The following table shows sample expressions and their order of
evaluation:
Expression Order of evaluation
a + b * c a + (b * c)
a + b - c (a + b) - c
a ^ b ^ c a ^ (b ^ c) -- exponentiation, raise to the power

The evaluation order in the previous table follows standard precedence rules, where * and /
operations are evaluated before + and - operations, and where + and - operations associate to the
left (that is, operands on the left are evaluated before operands on the right) and exponentiation
operations associate to the right (that is, operands on the right are evaluated before operands on
the left).
These precedence rules define the ordering of evaluation in all expressions in MAXScript, unless
parenthesizing is used to force a different order. Expressions in parenthesis are evaluated before the
surrounding operands are applied.
The following list shows the precedence order for math expressions starting with the highest
precedence:
<operand>
<function_call>
as
^ -- right associative
* and / -- left associative
+ and - -- left associative

See also
Function Precedence (p. 677)

Polymorphism
As in mathematical expressions, MAXScript operators are polymorphic. This term means a single
operator can be used to operate on a number of different types of values and performs the
appropriate action for each type of value.
For example, a “+” operator between two integers performs integer arithmetic, between two floats it
performs real arithmetic, and between two matrices it performs a matrix addition.
MAXScript allows certain non-mathematical types to use certain math operators. For example, you
can concatenate two strings with the “+” operator:
“twas brillig” + “ and the slithy tobes”
x.name += sequence_number as string
 Polymorphism 673

In some cases, you can mix operand types and MAXScript converts them appropriately. For example,
adding a float to an integer results in a float. Multiplying a 3D point by a float results in a scalar
vector product, and so on.
Internally in MAXScript the allowable operators and the actions performed by the operators are
defined for each type of value. The allowable operators and their actions are documented with the
value type descriptions.

See also
Inheritance and Polymorphism (p. lxiii)

Comparison Expressions
Using comparison expressions you can compare values of comparable types. The result is always one
of the two Boolean values, true or false. The various forms of <compare_expr> are as follows:
<compare_operand> == <compare_operand> -- equal
<compare_operand> != <compare_operand> -- not equal
<compare_operand> > <compare_operand> -- greater than
<compare_operand> < <compare_operand> -- less than
<compare_operand> >= <compare_operand> -- greater than or equal
<compare_operand> <= <compare_operand> -- less than or equal

where <compare_operand> can be one of:

<math_expr>
<operand>
<function_call>

Examples:
a > b
sin x == 0.0
a + b <= n - 1

Comparison operations have lower precedence than math operations. In the previous examples, the
sin function call and the “+” and “-” operations are performed before the comparisons.
As with math expressions, the comparison operators work on all appropriate types. Equal “==” and
not-equal “!=” operate on all types, and the relative comparisons work between comparable types.
The allowable comparison operators are documented with the value type descriptions.
674 Chapter 5 | Names, Literal Constants, and Expressions

Logical Expressions
Logical expressions combine the results of Boolean expressions, such as comparisons, to construct
complex conditional expressions. The forms of a <logical_expr> are as follows:
<logical_operand> or <logical_operand> -- true if either operand
-- is true
<logical_operand> and <logical_operand> -- true if both operands
-- are true
[ not ] <logical_operand> -- true if operand is false

where <logical_operand> is one of the following:

<operand>
<compare_expr>
<function_call>
<logical_expr>

Logical operators only operate on Boolean values, so each <logical_operand> must evaluate to
true or false.
Examples:
a > 0 and a < n + 1
not x and y
a and b or c and d and not e

As with math expressions, <logical_expr> is a recursive definition, meaning a logical operand can
be another logical expression. You can have arbitrary sequences containing and, or, and not, and
the order of evaluation is defined by the following precedence ordering (in decreasing order of
precedence):
not -- right associative
and -- left associative
or -- left associative
This means that in an unparenthesised logical expression, not is evaluated before and
which is evaluated before or.
Logical operators have a lower precedence than comparison operators, math, and function calls.
Therefore, these operations are always evaluated before logical operators, which follows convention.
The previous examples would be evaluated in the following order:
(a > 0) and (a < (n + 1))
(not x) and y
(a and b) or ((c and d) and (not e))

See also
Short-Circuiting Logical Expressions (p. 675)
 Short-Circuiting Logical Expressions 675

Short-Circuiting Logical Expressions

Following the convention in most other programming languages, logical expressions in MAXScript
are short-circuiting or non-strict. This means only enough of the sub-expression is evaluated to
determine the overall result:
• If the first operand is false in an and expression, the result must be false, therefore, the
second operand is not evaluated.
• If the first operand is true in an or expression, the result must be true, therefore, the second
operand is not evaluated.
This saves execution time and enables useful shorthand notation. For example, if you want to
calculate “sin a” if the value of variable a isn’t undefined, you can use the following example:
if a != undefined and sin a > 0 then ...

In a strict language, the “sin a” evaluation of an undefined operand results in an error, and you
would need to break up the expression into two if statements:
if a != undefined then
if sin a > 0 then ...

Function Calls
A function call expression passes an optional list of arguments to a MAXScript or user-defined
function, and the value returned by the function is the function call expression’s result. A
<function_call> has one of the following forms:
<operand> { <argument> }+ -- one or more arguments
<operand> () -- no arguments

in which, <argument> is one of the following:

<operand>
<name>: <operand> -- keyword argument

Examples:
sin a
tan2 x y
print (n + 1) to:debug
fns[i] $box01 -- get function out of array fns
move object1 [10,20,x * 3]

This syntax is unlike most programming languages which typically use parenthesized lists of
comma-separated arguments. This syntax was chosen for MAXScript for the following reasons:
• It is simpler and easier to use, particularly if a function has many optional keyword arguments.
• The language is used in a command-line window within 3ds max. Therefore this form is similar
to other command or shell languages that users might be already know.
676 Chapter 5 | Names, Literal Constants, and Expressions

All 3ds max objects, including geometric objects, splines, materials, and so on are created using
function calls. The name of the object creation function is the object’s class name. For example:
standard() -- create a standard material
bend angle:45 -- create a bend modifier
box height:20 width:40 -- create a box

See also
Positional and Keyword Arguments (p. 676)
Function Precedence (p. 677)
Code Layout (p. 678)
Special Notes about Function Calls (p. 678)
Creating Functions (p. 699)

Positional and Keyword Arguments

A function can take two kinds of arguments:
• Positional Arguments: If you call a function that takes positional arguments, you must specify
those arguments first and in the correct order. Positional arguments correspond to the function
arguments in most programming languages—they are required and have a fixed number and
order.
• Keyword Arguments: You write keyword arguments as a keyword:value pair, and they can
appear in any order after the positional arguments. Functions can use some or all of their
keyword arguments as optional arguments. If you call a function and don’t supply optional
keyword arguments, they will have either the default value supplied by the called function, or
the special value unsupplied when first referenced in the called function.
Optional keyword arguments are useful in command languages where commands can have many
options. They are particularly useful within 3ds max where most functions have numerous optional
keyword arguments. For example, all scene object creation functions take optional keyword
arguments for their creation parameters. As there are sometimes more than 100 arguments to these
functions, using positional arguments would simply be unworkable.
As an example of positional arguments, the syntax for the print function is:
print <value> [ to: <file> ]
<value> is a positional argument, and is required. to: <file> is an optional keyword
argument, where to is the argument keyword and <file> is the argument value. If the to
argument value is unsupplied, MAXScript outputs <value> to Listener. Otherwise,
MAXScript outputs <value> to the file specified by <file>.
 Function Precedence 677

As another example, you can create a sphere object in the 3ds max scene with no arguments:
sphere()

Or, you could specify just one argument:

sphere radius:23

Or, you can specify more optional arguments:

sphere segs:20 smooth:on radius:15 hemisphere:0.5 mapcoords:on

For those keyword arguments not specified when creating 3ds max objects, default values are used.
The default value used for each keyword argument is shown in the descriptions of the object classes.

Function Precedence
A <function_call> has a lower precedence than an <operand>, but it has a higher precedence
than all the math, comparison, and logical operations. This means you have to be careful about
correctly parenthesizing function arguments.
For example:
sin x + 1

is evaluated as:
(sin x) + 1

In general, you have to put arguments that are expressions inside parentheses, as in:
sin (x + 1)
atan2 (y - 1) (z - 1)

This rule has one exception, the unary minus. It is recognized as one type of <operand> you don’t
have to parenthesize. For example:
sin -x

is interpreted as:
sin (-x)
678 Chapter 5 | Names, Literal Constants, and Expressions

Code Layout
The end-of-line layout rules, as described in the Source Code Layout and Continuation Lines (p. lvii)
topic, mean an end-of-line indicates the end of a function call if the line ends at the end of a
complete argument.
You cannot simply break up a function call with many arguments into several lines, because each
line becomes a separate expression, almost certainly causing an error. Use the “\” continuation
character in this situation:
foo = standardMaterial twosided:on shininess:34 \
diffuseMap:baz \
opacityMap:bar \
bumpMap:boo

Special Notes About Function Calls

Functions in MAXScript are just another value that can be stored in variables and arrays, and passed
to other functions as arguments. Such functions are sometimes called higher-order functions. All
built-in functions, and functions that MAXScript defines based on the 3ds max object classes, are
values stored in system global variables of the same name as the function. When you define a
scripted function, the function value is placed in a variable with the same name as the function. You
can use the value in these variables and work with them as you would with other values, such as
storing them in an array or passing them as arguments.
Because the function name is a variable that simply yields the function itself, functions that take no
arguments need to be called in a special way. For example, if you want to call a function
get_current_target that takes no arguments, you can not simply write:
t = get_current_target
This stores the get_current_target function value in variable t, rather than storing the
result of executing function get_current_target. Instead, you must use the “()” nullary
call operator:
t = get_current_target()
The function to be called is defined as an <operand> in the syntax for function calls. This
means that it can be an expression that is evaluated to get the function to call. For
example:
(if a > b then sin else cos) x -- conditional function choice
handlers[x] $box01 [1,1,1] -- get the function out of an array
 Special Notes About Function Calls 679

Block-Expressions
Block-expressions are the basic constructors for structured code. They allow you to group a sequence
of expressions and evaluate them in sequence as though they were a single expression. The syntax
for <block_expr> is:
( <expr> { (; | <eol>) <expr> } )
That is, a parenthesized sequence of expressions with each <expr> separated by either a
line break or a “;” semicolon.
MAXScript also allows empty block-expressions, (). This is useful when incrementally building code
in order to place an empty expression in a path to be filled in later. When evaluated, empty
expressions yield the value undefined.
Examples:
(
d = centre.x^2 - (p.x^2 + p.y^2)
newz = if d > 0 then sqrt d else p.z
print newz
)
if x < y then (print x; print y; u += 10; print u)

You can use a mixture of line breaks or semicolons:

(
print x; print y
u += 10
print u; print z
)

Because a block-expression is an <operand>, you can insert a block-expression anywhere you can
put an <operand>. This is unlike most languages which limit where you can put blocks of code to
only a few places. Further, because all constructs are expressions in MAXScript, a block-expression
yields a value defined to be the last <expr> in the block. This allows you to use a nested sequence
of expressions to compute an operand for some operation:
$box.pos.z =
(
d = x^2 - y^2
if d > 0 then sqrt d else z
)
Here, the result of the block-expression is the result of the final if expression, which is then assigned
to $box.pos.z.
Because the item in parentheses can be any <expr>, you can turn any construct in MAXScript into
an operand by putting it in parentheses. This allows you to write the following example, in which
the operand to be indexed is the conditional result of an if expression:
(if a > b then c else d)[n + 1]
680 Chapter 5 | Names, Literal Constants, and Expressions

As described in the Scope of Variables (p. 646) topic, top-level open parentheses in a script file or in
the Listener create a new variable scope. Any block-expressions with the top-level block-expression
do not create a new variable scope, even if the variable is explicitly declared as local in the inner
block-expression. A variable’s scope extends into any block-expressions within the variable’s scope.
If you declare a variable as local in a scope, the newly declared local variable hides any outer
variables with the same name. Any reference to that variable name later in the local variable’s scope
refers to the new local variable. At the end of the local variable’s scope, the next outer variable
becomes visible again. This is shown in the following script:
Script:
a=1
(
local a=2
(
local a=3
)
print a
)
a

Output:
1 -- result of line 1
3 -- output of line 7
3 -- result of block-expression lines 2 to 8
1 -- result of line 9

Any variable names used in a block-expression which have not been created at a higher scope level
are implicitly declared as local in the present scope. This can result in unexpected execution results
for scripts that are not set up correctly. For example, consider the following script:
(b=bend();addmodifier Objs b) -- create bend modifier and apply to objects
b.angle=10

The first time you execute this script, the following error message is generated:
-- Unknown property: “angle” in undefined

If you execute the script again, it works properly. The reason is there are actually two variables with
the name b – one is local to the block-expression and contains the bend modifier value, and the
other is global and has the value undefined. During the second execution, global b exists, so the
block-expression does not implicitly declare a new variable b, rather it uses the global variable b.
When writing scripts, it is also a good programming practice to explicitly declare as local all variables
unless you really want them to be global variables. There are several reasons for this practice:
• All the variable names used in the block or function will be together, which makes it easier to
find the variable names and helps prevent using incorrect names in the script.
• If more than one script is executing at the same time (for example, you are running a scripted
utility and have a scripted controller in the scene) and both scripts use the same global variable
 Special Notes About Function Calls 681

name, the two scripts can interfere with one another. This can cause apparently random failures
of one or both scripts.
• You are sure you are using the correct variable in the event that a variable with the same name
has already been declared at a higher scope, and you won’t inadvertently change the higher-
level variable’s value.
• Values of variables explicitly defined as local are displayed in error call stack trace-backs.
• In 3ds max R2.5, if a 3ds max class, a MAXScript method, or a MAXScript read-only global
variable has the same name as an implicitly declared local variable, a MAXScript runtime error
will be generated if an assignment to that variable name occurs. Since the variable name already
existed with a global scope, an implicitly declared local variable was not created. Since one or
more new 3ds max classes will be created by any third party plug-ins the user has loaded, you
were not be able to tell ahead of time if a variable name was a global variable name. In
3ds max 4, if the MAXScript compiler detects that the first reference to such a variable is an
assignment, it will implicitly declare a local variable, rather than leaving it as a reference to a
read-only system global. For example, executing the following expression in 3ds max R2.5
would result in a value of Box, since Box is a 3ds max object class. In 3ds max 4, MAXScript
detects that the first use of variable box is an assignment and creates an implicitly declared local
variable box. The result of this expression in 3ds max 4 is the value undefined.
(if false do box=10;box)

Context Expressions
Context expressions are the parts of the MAXScript syntax that are most specifically designed for use
with 3ds max. Context expressions are mirrors of some of the most important abstractions in the
3ds max user interface - the animate button, the time-line slider, the working coordinate system,
and so on. Context expressions make it as easy to create animation and perform geometry
manipulation in MAXScript as these tools do in the user interface.
The basic idea for this is a prefix is supplied that sets up a context for the evaluation of its expression.
For example:
animate on
(
move $box01 [20, 0, 0]
rotate $box02 45 x_axis
)
682 Chapter 5 | Names, Literal Constants, and Expressions

This effectively “turns on” the animate button for the duration of its block-expression. The move
and rotate will automatically generate keyframes, just as would happen if you turned the animate
button on in the 3ds max user interface and moved objects around. Another kind of context
expression has a prefix for setting the current animation time, as though you had moved the time
slider. If we mix the two forms together, like this:
animate on
(
at time 0 $box01.position = [-100, 0, 0]
at time 100 $box01.position = [100, 0, 0]
)

you can see how to do keyframe animation in MAXScript.

The full syntax for <context_expr> is:

<context> { , <context> } <expr>

where <context> is one of:

[ with ] animate <boolean>
at level <node>
in <node>
at time <time>
[ in ] coordsys <coordsys>
about <center_spec>
[ with ] undo <boolean>

Examples:
-- randomly jiggle each object in the selection around + or - 20 units
in coordsys local selection.pos = random [-20,20,20] [20,20,20]

-- rotate all the boxes 30 degrees about the y_axis of $foo

about $foo rotate $box* 30 y_axis

-- generate a keyframed animation of $foo randomly chasing $baz

animate on
for t in 0 to 100 by 5 do
at time t
$foo.pos = $baz.pos + random [-10,-10,-10] [10,10,10]

The individual context expressions are described in the following topics:

animate (p. 683)
at level, in (p. 684)
at time (p. 685)
coordsys (p. 685)
about (p. 686)
undo (p. 687)
 animate 683

See also
Cascading Contexts (p. 688)
Nested Contexts (p. 688)
Sticky Contexts (p. 689)

animate
The [ with ] animate <boolean_expr> context corresponds to setting the Animate button in the
3ds max user interface. Placing an expression, operation, or block-expression within an animate on
context causes keyframes to be generated whenever an animatable property of a 3ds max object is
changed, regardless of the actual state of the Animate button. Likewise, placing an expression
within an animate off context prevents keyframes from being generated whenever an animatable
property of a 3ds max object is changed. Expressions that change an animatable property of a
3ds max object, and are not within an animate context, will generate keyframes only if the Animate
button is on.
Setting the animate context on or off does not affect the state of the Animate button. The state of
the Animate button can be queried and set using the animButtonState global variable. The user
can be prevented from changing the state of the Animate button using the animButtonEnabled
global variable.
Examples:
loadheight=obj.pos.z

-- lift object, no key generated

animate off
obj.pos.z=loadheight+LiftHeight

-- Create key at time tStart to keep object lifted until that time.
-- If tStart != 0, a key will also automatically be created at frame 0.
-- Then create a key at time tEnd to drop the object
with animate on
( at time tStart obj.pos.z=loadheight+LiftHeight
at time tEnd obj.pos.z=loadheight
)
684 Chapter 5 | Names, Literal Constants, and Expressions

at level, in
The at level <node> and in <node> contexts set the specified node to be the effective root for
any pathnames specified, or scene objects created, in the context. These contexts automatically
prefix the specified node to any pathnames in the context. They also set the specified node to be the
parent for any scene objects created in the context.
To be able to use pathnames within level contexts to name objects anywhere in the scene, you can
override the current working level by using a rooted pathname. A rooted pathname has an extra “/”
before the first-level name and indicates “start at the actual root of the object tree”. For example:
scale $/baz/* [1,1,2]
operates on the object baz in the actual top level, not just as a child of the current
working level.
You can also use this rooted pathname form to force a pathname to only consider top-level objects
when you name a single object. For example:
$foo
looks throughout the whole scene, at all levels for an object named foo, but,
$/foo
will only look for a top-level object named foo.
Examples:
in $mannequin01...LClav...hand -- set context to hand
$mannequin01.spine.LClav.arm.hand
( rotate $thumb1 15 y_axis -- rotate hand’s child
-- thumb
rotate $finger11 10 y_axis -- rotate hand’s child
-- first finger
PalmCenter=$finger21.parent.pos -- get hand’s position
PalmCenter+=(LHandPos-$finger21.pos)/2. -- calculate center of
-- palm
dummy name:”palmLink” pos:PalmCenter -- create a dummy there,
-- dummy is a child of
-- the hand
)

in $dummy
( sphere name:”ear1” pos:[10,10,10] -- create automatically as
-- children of $dummy
sphere name:”ear2” pos:[-10,10,10]
scale $foo/* [1,1,2] -- look for ‘foo’ as a child
-- of $dummy
)
 at time 685

at time
The at time <time> context corresponds to the 3ds max time slider. Any animatable property
references will yield their interpolated values for the specified time. If the Animate button is on, or
the script is also in an animate on context, keyframes are generated at the specified time when an
animatable property of a 3ds max object is changed.
Setting an at time context does not affect the 3ds max time slider. The time associated with the
time slider can be queried and set using the sliderTime global variable.
Examples:
-- generate a keyframed animation of $foo randomly chasing $baz
animate on
for t in 0 to 100 by 5 do
at time t
$foo.pos = $baz.pos + random [-10,-10,-10] [10,10,10]

coordsys
The [ in ] coordsys <coordsys_spec> context corresponds to the current reference coordinate
system list in the main 3ds max toolbar. Prefixing an expression, operation, or block-expression with
a coordsys context causes 3D coordinate operations to be interpreted in the specified coordinate
system. Moving, scaling, or rotating objects, or setting transform-related properties within a
coordsys context operate in relation to the given coordsys. Accessing coordinate properties such
as position, center, rotation axis, and so on, within a coordsys context causes those values to be
delivered relative to the given coordsys.
The following forms are supported:
[ in ] coordsys world
use the world space coordinate system
[ in ] coordsys local
use the object’s local coordinate system
[ in ] coordsys parent
use the object’s parent’s coordinate system
[ in ] coordsys grid
use the active grid’s coordinate system
[ in ] coordsys screen
use the currently active viewport’s coordinate system
[ in ] coordsys <node>
use the specified node’s local coordinate system - this is equivalent to the “pick”
coordinate system capability in the 3ds max user interface
[ in ] coordsys <matrix3>
use the coordinate system specified by the given 3D matrix
686 Chapter 5 | Names, Literal Constants, and Expressions

Examples:
-- randomly jiggle each object in the selection around +/- 20 units
in coordsys local selection.pos = random [-20,20,20] [20,20,20]

-- rotate objects in parent’s coordinate system

in coordsys parent rotate selection (EulerAngles 0 0 90)

about
The about <center_spec> context is the MAXScript equivalent of the rotate/scale transform
center list on the main 3ds max toolbar. It defines the center point about which any scale or rotation
operation is performed within its context. Note that, like the center list in 3ds max, this sets only
the center point for the operation, not the axis. The axis is taken from the current working
coordinate system set using the coordsys context expression:
about selection
rotates/scales about the center of the current selection
about pivot
rotates/scales about each object’s pivot point
about coordsys
rotates/scales about the center of the current working coordinate system set using the
coordsys context expression
about <node>
rotates/scales about the pivot point of the given object
about <matrix3>
rotates/scales about the center of the coordinate system specified by the given 3D matrix
about <point3>
rotates/scales about the given point with coordinate system and axes taken from the
current working coordinate system.
Examples:
-- rotate all the boxes 30 degrees about the y_axis of $foo
about $foo rotate $box* 30 y_axis

-- rotate each planet 45 degrees around its parent

in coordsys parent about coordsys rotate $planets* 45 z_axis
 undo 687

undo
The undo <boolean> context provides control over whether scripted scene changes will be
undoable. By default, the operations performed in MAXScript are undoable. This means that
scene-modifying commands typed in the Listener are undoable by default. Making this a
context-controlled activity allows you to decide when the undo overhead is to be taken.
Example:
undo on
(
delete $box*
delete $sphere*
clearUndoBuffer()
)

The undoable operations appear as items labeled “MAXScript” in the 3ds max Undo menu. It is
important to note that the granularity of the undoable operations is at the level of entire undo
clauses. In the previous example, one entry is added to the Undo stack containing both deletes as a
single operation. Choosing undo for this entry in the Undo menu causes both deletes to be undone.
Therefore, you can control the granularity of an undo by choosing the appropriate undo block
expression groupings.
You can invoke an undo from MAXScript with the max command:
max undo

When you script very large scene changes, you should consider turning undo off as it is quite easy
to fill up the Undo stack and consume substantial amounts of memory. Disabling undo can improve
performance in this situation. If the actions your script performs could interfere with entries already
in the Undo stack, you should explicitly clear the Undo stack before enabling undo. An entry in the
Undo stack generally expects the scene to be in the state it was when the entry was placed in the
Undo stack. If you interrupt the storing of Undo stack entries, and modify the scene in an
incompatible way (such as deleting an object that an entry assumes is still around), a 3ds max crash
is likely if you then try to perform an undo.
Using the following functions you can control the undo and scene save states in 3ds max:
clearUndoBuffer()
empties the Undo stack, both providing a way to reset the undo state and another way to
control the save-changes requester.
setSaveRequired <boolean>
lets you set the 3ds max system “dirty” flag. If this flag is set or there are entries in the
Undo stack, you are asked if you want to save the scene file on a File > New or File > Reset.
getSaveRequired()
returns true if the 3ds max system “dirty” flag is set to true or if the Undo buffer is not
empty. If the Undo buffer if not empty, this function will still return true, even if you just
called setSaveRequired false.
688 Chapter 5 | Names, Literal Constants, and Expressions

Normally, if there are entries in the Undo stack when the scene is closed, 3ds max will prompt with
a save-changes requester. In some cases, where you are controlling undo in MAXScript, you may
want to force the need for a save-changes prompt.

Cascading Contexts
You can cascade a set of context prefixes, optionally separated by commas, onto one subject
expression, effectively applying all the contexts (in order) to the subject expression. For example:
animate on, at time (t+1), with undo off, coordsys local
(
...
)

All the context forms are true expressions, yielding the value of their subject expression, so:
pos0 = at time 35 $box01.position
pos1 = at time 75 $box01.position
assigns the box01 position at time’s 35 and 75 to variables pos0 and pos1. This is
particularly useful with the at time context, as you can very easily do across-time
computations. The operand to an at time context can be any valid time value (numbers
are taken as frames for convenience), including sub-frame times down to the tick level.
The animation system in 3ds max will interpolate animated parameters at these fine levels
so you can easily do sub-frame simulation computations.

Nested Contexts
All context expressions remember the prior setting of the context when they are set, and restore the
original setting when the expression completes. Therefore, you can nest context clauses in any way
you want, including contexts of the same type to override an outer setting.
Example:
with animate on, at time t
(
move ... -- all these place keys
rotate ...
animate off -- turn off animate for a bit
(
move ... -- working maneuvers, these don’t effect animation
rotate ...
) -- animate on is restored here
scale ... -- place keys again
...
)
 Sticky Contexts 689

Further, all the contexts are dynamically scoped. Any code inside a context expression, any functions
that code calls, and functions they call down to any level, are executed in the current prevailing
context. So, a function can move an object and place keyframes at a certain time when called from
one client and do no keyframing when called from another client, depending on how the callers
have set up the contexts. Of course, the called function can explicitly set its own contexts if it wants
to, overriding those that may have been set up by the caller.

Sticky Contexts
You can force the settings of contexts such as coordsys, animate, time, and so on, to be “sticky.”
The settings will stay active for any code execution that follows, up until the point you change them
or override them with a context prefix for an expression. This is particularly useful when working
in the Listener, allowing you to set a context and then perform several interactive operations in that
context without prefixing each with the desired context construct. Establishing a sticky context is
accomplished with the set construct:
set <context>
where <context> is one of the MAXScript context prefixes: animate, time, in,
coordsys, about, level, or undo.
Example:
set animate on
set time 30f
move $foo [80,0,0]
scale $baz [1,1,3]
$bar.bend.angle += 23
...
set animate off
set time off
This turns animate on and sets the current time to frame 30 after which any number of interactive
operations can be performed that will generate animation at frame 30. The modes are then returned
to default. As shown in this example, certain the MAXScript contexts permit syntactic variants to
make the set construct read clearly. In particular, these are:
set time <value> | off -- variant of at time <time>
set level <node> -- variant of at level <node>

The time context can be set to off, signifying the current value of the 3ds max time slider is to
be used.
All the set constructs are expressions that yield the context setting that was in force at the time the
new context was set. This allows you to simulate the standard nested forms of these constructs by
storing the old context in a variable and using that to restore the context later. For example:
oc = set coordsys parent -- remember old coordsys
rotate $foo (quat 30 z_axis)
...
set coordsys oc -- restore it
690 Chapter 5 | Names, Literal Constants, and Expressions

You can also force several of the contexts back to their default states by specifying #default as their
parameter. The set constructs for which you can specify #default are: animate, in, coordsys,
and level.
When using the set undo on construct to enable the undoing of scripted changes in the Listener,
undo granularity is a top-level expression. Every time you evaluate an expression or sequence of
selected expressions with the ENTER or Number-Pad ENTER key, a single entry is added to the
Undo stack.
Chapter 6: Controlling Program Flow

MAXScript has several <expr> expression forms used to explicitly control the flow of execution.
They are:
<if_expr>
<case_expr>
<do_loop>
<while_loop>
<for_loop>
<loop_exit>
<try_expr>

These expression forms correspond to the standard control constructs found in many programming
languages. Each is described in its own topic:
If Expression (p. 692)
Case Expression (p. 693)
While and Do Loops (p. 694)
For Loop (p. 694)
Loop Exit (p. 697)
Try Expression (p. 697)
Additionally, there are several constructs for implicitly controlling program flow. The when
construct is used for scripting general change handlers, so you can write scripts that respond to user
operations such as object moves, vertex edits, object deletions, name changes, and so on. Callback
mechanisms are used to have a function called when certain specific events occur. See the Change
Handlers and When Constructs (p. 1650) topic for more information. The on construct is used when
scripting rollouts or tools or plugins, so the script can respond to events, often user-generated, in
those constructs. See the Utility and Rollout Properties, Methods, and Event Handlers (p. 1474) topic for
more information.
692 Chapter 6 | Controlling Program Flow

If Expression
The if expression is used to conditionally execute an expression based on the result of a boolean
test expression. The syntax for an <if_expr> is one of:
if <expr> then <expr> [else <expr> ]
if <expr> do <expr>

Examples:
if a > b do (print d; print e)
a = (if d == 0 then 0 else a / d)

The first <expr> is a test expression that must evaluate to true or false, such as a comparison or
logical expression. If the result is true, the then or do <expr> is evaluated and its value is returned
as the result of the <if_expr>. If the result is false, the optional else <expr> is evaluated and
its value is returned as the result of the <if_expr>. If there is no else or the do form is used, the
<if_expr> returns the value undefined.
The do form is provided particularly for use during interactive sessions in the MAXScript Listener.
When you enter expressions for immediate evaluation into the Listener, MAXScript determines if
your expression is complete and then evaluates it. If you use the optional else form in the Listener
and you want to omit the else <expr>, MAXScript continues to “wait and see” if you enter an
else <expr>. The line break after the then <expr> is legal and does not cause MAXScript to
evaluate the current line right away. As an example, if the following script is entered in Listener, the
first line will not evaluate until you enter the second line:
if match x y then print x
print “hello”

When you use the optional else form inside a block or another expression, MAXScript can
determine from the code that follows it if you omitted the optional else. Use the do form for if
statements without an else as top-level commands in the Listener:
if match x y do print x

As described in the Expressions (p. 667) topic, anywhere you can write an <expr> expression, you
can write any construct in MAXScript. In statement-based languages, there is usually one syntax for
if statements and a separate one for conditional expressions. In MAXScript, a single syntax is used
for both cases. For example, the following two lines of code are both valid, and their meaning should
be obvious:
if a > b then print c else print d
x = if a > b then c else d

You can also write the following line, containing a nested if expression and a nested assignment,
which is itself an expression:
x = if (if a > b then c else d) < e then f else (g = 23)
 Case Expression 693

Case Expression
The case expression is used to select an expression to be evaluated from a set of labeled expressions
based on a test value compared against the labels.
Only the first expression whose label matches the test expression is evaluated. All labels must be
comparable to the test expression. Labeled expressions can be block-expressions, so you can use the
case expression as a case statement, choosing between blocks of code to execute.
The syntax for <case_expr> is:
case [ <expr> ] of ( <cases> )
where <expr> is the test expression and <cases> is a sequence of labeled expressions:
<factor>: <expr>
default: <expr>

Examples:
new_obj = case copy_type.state of
(
2: copy $foo
3: instance $foo
default: reference $foo
)

A special label, default, can be optionally used to tag the expression that will be evaluated if no
other labels match the test expression. If the default label is not used, and no label matches the
test expression, the case expression returns a value of undefined.
The labels are <factors> - elements such as number literals, name literals, string literals, variables,
or block-expressions. When a case expression is evaluated, the test expression is evaluated once,
then each label expression is evaluated in order until one is found that compares equally to the test
expression value. The expression it labels is then evaluated and this becomes the result of the case
expression. No further labels are evaluated or tested.
The test expression is optional. If it is not supplied, the labels are expected to be Boolean values or
expressions, and the first label evaluated as true determines the chosen case. In this variant, it is
common to use expressions as labels, so be sure to parenthesize them. For example:
case of
(
(a > b): print “a is big”
(b < c): print “b is little”
(c <= d*3): ...
default: ...
)
694 Chapter 6 | Controlling Program Flow

While and Do Loops

while and do loops are used to repeatedly execute an expression until a test expression evaluates as
false. The while loop and do loop are simple variants of one another. The syntax is:
do <expr> while <expr>
while <expr> do <expr>

Both loops repeat the do <expr> as long as the while <expr> evaluates to the value true. The do
form evaluates the do <expr> at least once, evaluating the test expression at the end of each loop.
The while form evaluates the test expression at the start of each loop and may not loop at all.
Both forms return as their value the result of the do <expr> from the last successful loop iteration.
The while form will return the value undefined if the test expression immediately returns false.
Examples:
while x > 0 do
( print x
x -= 1
)

while not eof f do print (read_value f)

do
( exchanged=false
for i=1 to imax do
( j=i+gap
if (compare array[j] array[i]) do
(swap array[j] array[i]; exchanged=true)
)
) while exchanged

See also
Skipping Loop Iterations (p. 696)
Loop Exit (p. 697)

For Loop
The for loop iterates through a range of numbers, time values, or a sequenced collection of values,
such as an array or object set. The syntax for the for loop is:
for <var_name> ( in | = ) <sequence> ( do | collect ) <expr>
where <var_name> is the name of the loop index variable that holds the loop value, and
<sequence> is the source of values for the loop. The <sequence> can be one of the
following:
<expr> to <expr> [ by <expr> ] [where <expr> ]
<expr> [ where <expr> ]
 For Loop 695

Examples:
for i = 1 to 10 do print i -- sequence numbers
for item in table1 do x = x + item.height -- sequence an array
for t in 0f to 100f by 5f do ... -- sequence time (given as
-- frames, here)
bigones = for obj in $box* -- you can sequence pathnames!
where obj.height > 100 collect obj -- collect the big boxes into
-- an array

The first <sequence> form is the standard number loop, the first <expr> value is the start value,
the to <expr> value is the limit value and the optional by <expr> value is the loop value
increment. The allowable value types are integer, float and time. If the by value isn’t given it
defaults to 1.
The second form of <sequence> takes a sequencable collection, such as an array (p. 666) or ObjectSet
(p. 781), and iterates through all its values, assigning successive elements in the collection to the
loop value each time through the loop. MAXScript contains several sequence collections, including
PathName values (p. 780), the current selection set, the children of a node, and the stack of modifiers
on an object. See also the Collections (p. 773) topic for caveats when using a collection in a for loop.
Each <sequence> source form takes an optional where <expr> which must evaluate to true or
false. The where expression is evaluated at the beginning of each loop and only executes the loop
body for that loop value if the where expression is true.
The do <expr> form simply evaluates the body expression once for each value in the sequence. The
loop variable is visible to the code in the body expression as though it was declared locally and
initialized to the successive loop values each time. When the do <expr> form of a for loop is used
as an expression, its return value is always OK.
The collect <expr> form gathers the expression values from the loop iterations and stores them
in an array, which is then yielded as the value of the overall for loop. This, for example, is a good
way to gather procedural selections of objects from a scene. If the where expression is used with the
collect form of the for loop, only the values from those iterations for which the where expression
is true are collected. This can be used to collect a filtered sub-set of the iterated values. You can also
achieve this collection filtering in a for loop that does not use a where expression by yielding the
special value dontCollect for those iterations that should not be added to the collection.
As described in the Scope of Variables (p. 646) topic, a for loop creates a new scope context. The for
loop index variable’s scope is always the extent of the for loop, even if another variable of the same
name already exists. Once the for loop exits, the for loop index variable is no longer accessible.
The scope of any variables created in a for loop is always the extent of the for loop. This is shown
in the following example:
696 Chapter 6 | Controlling Program Flow

Script:
obj=$box01
avg_pos=[0,0,0]
offset_pos=[100,100,0]
for obj in $* do -- new for loop index variable obj
-- created even though a variable named
-- obj already exists, scope is for loop
( pos=obj.pos-offset_pos -- new variable pos created, scope is for
-- loop offset_pos already exists outside
-- for loop, its value will be used
avg_pos += pos -- avg_pos already exists outside for
-- loop, its value will be used
) -- for loop index since variable obj goes
-- out of scope
avg_pos /= $*.count

See also
Skipping Loop Iterations (p. 696)
Loop Exit (p. 697)

Skipping Loop Iterations

MAXScript provides a continue construct that allows you to jump to the end of a for, do, or while
loop body <expr> and resume with the next loop iteration. Its syntax is:
continue

Examples:
for i=1 to 8 do (if i == 5 do continue; print i) -- prints 1..4, 6..8

while not eof f do -- read until reach end of file

( local line=readline f -- read in a line
if line[1] == “-” do continue -- if comment, skip to next line
line1=parser1 line -- call function parser1
processobjs line1 -- call function processobjs
)

If a continue is executed in a for ... collect loop, the expression result for that loop iteration
is not collected in the array of body values.
Example:
for i=1 to 8 collect (if i == 5 do continue; i) -- returns #(1, 2, 3, 4, 6, 7, 8)
 Loop Exit 697

Loop Exit
MAXScript provides an exit construct for breaking out of for, do, and while loops prematurely,
even though the loop test expression is still true. This is often useful to simplify the loop test
expression, and still use error or other complex termination tests in the body <expr> of the loop.
Its syntax is:
exit [with <expr> ]

Example:
while x < y do
( local delta = x - y
if delta <= 0 then exit -- time to bail
$foo.pos.x = compute_x (foo / delta)
x += 0.1
)

The optional with <expr> lets you specify what the overall value of the loop expression should be
if the loop exits prematurely. If you don’t specify an exit value, the loop returns the value
undefined upon exit.
Exiting a for ... do loop using a with <expr> results in a value of OK.
Exiting a for ... collect loop using a with <expr> results in the array of body values collected
up to the point of exit.

Try Expression
MAXScript provides simple exception-handling with the try expression, a simplified form of the
C++ exception-handling scheme. The try expression lets you bracket a piece of code and catch any
runtime errors. This allows you to respond appropriately or take corrective action, rather than let
MAXScript halt the execution of your script and print an error message. The syntax for the try
expression is:
try <protected_expr> catch <on_err_expr>
The <protected_expr> is executed and any errors that occur are trapped and the
<on_err_expr> is executed. If the <protected_expr> is a block-expression, the block-
expression stops executing at the point of the error. If there are no errors in the protected
expression, the <on_err_expr> is not executed. This is a very simple error-trapping
scheme, but limited heavily by the fact that you cannot get at any error codes or
information about the error that occurred.
698 Chapter 6 | Controlling Program Flow

Example:
f = openFile “foo.dat”
try
while not eof f do read_some_data f
catch
( messageBox “bad data in foo.dat”
results = undefined
)
close f

In this example, any errors in reading or processing the data in the read_some_data() function
are trapped, then a Message box is displayed and some clean-up is done. This is a good example of
a use for the simple error-trapping.
There is also an associated function, throw(), which can be used to generate your own runtime
error and pass on an error you caught when doing some interim clean-up, or do a non-local jump.
It has the form:
throw <error_message_string> [ <value> ]
throw()

If you have no intervening catches in your script, calling throw() with error message arguments
will cause a runtime error to be signaled and MAXScript will report the error message using its
standard error reporting. The optional second argument can be any value you want printed with the
error message, perhaps the object involved in the error. This second argument can not be specified
if the throw is in the body of a catch() and will generate a compile error if present.
If the try/catch is within another try expression, calling throw() will cause the catch expression
associated with the outer try expression to be executed. If you have no intervening catches in your
script, calling throw() will cause MAXScript to continue running the script from just after the top-
most set of parenthesis surrounding the try/catch, or will stop the currently running script if there
are no parenthesis surrounding the try/catch.
If you want to catch an error, perhaps to do some clean-up processing, and then pass the error on to
outer handlers or MAXScript for error reporting, you can call throw() with no arguments. This
throws the current error again and must only be done inside a catch expression. For example:
Script:
try
( i=10
try ( i.x=1 ) -- will generate a run-time error
catch
( print “Bad Error” -- error message printed
try (i.pos=[0,0,0]) -- will also generate a run-time error
catch (throw()) -- throw() will cause outer catch
-- to execute
)
)
catch (print “Really Bad Error Occurred”) -- error message printed
Chapter 7: Creating Functions

Functions are defined in MAXScript using the function definition expression. The syntax for
<function_def> is:
[mapped] (function | fn) <name> { <parameter> } = <expr>
in which <name> is the name of the function. The optional sequence of <parameter>s
can be one of:
<name>
<name>: [ <operand> ] -- keyword parameter with
-- optional default value

and the <expr> after the ‘=’ (equal sign) is the body of the function.
The function <name> is actually used to name a variable into which a value representing the
function is placed. When you call a function by using its name, you are accessing its definition in a
variable of that name. The scope of the function name variable is the current MAXScript scope.
The parameters for a function are either positional or keyword. Positional parameters are defined with
a simple <name> and must be placed before any keyword parameters. Keyword parameters have a ‘:’
(colon) after the name and an optional default value. The caller of the function can optionally
supply keyword arguments in any order. Those not supplied will be set to the default value given, or
the special value unsupplied if a default value is not given.
Using the mapped prefix on a function definition marks this function to be automatically mapped
over collections. This means the function will be automatically called repeatedly on the elements of
a collection if the collection is given as the first argument to the function. This allows you to define
scripted functions that behave in a similar manner to the mapped built-in functions, such as copy,
delete, move, and so on, which can be applied to an object set, path name pattern, or array. See the
Collections (p. 773) topic for more information.
700 Chapter 7 | Creating Functions

Examples:
function add a b = a + b

fn factorial n = if n <= 0 then 1 else n * factorial(n - 1)

mapped function rand_color x =

x.wireColor = random (color 0 0 0) (color 255 255 255)

fn starfield count extent:[200,200,200] pos:[0,0,0] =

(
local f = pos - extent / 2,
t = pos + extent / 2
for i = 1 to count do
sphere name:”star” \
radius:(random 0.1 2.0) \
position:(random f t) \
segs:4 smooth:false
)

A scripted function returns as its value the value of the body <expr>. If the body is a block-
expression, the function evaluates to the value of the last expression in the block.
A function can be called recursively (that is, the function can call itself), as is the factorial
function in the previous examples.
If you need to locate the source of a scripted function, you can use the showSource() function. It
displays a script Editor containing the source file in which the function was defined and positioned
at the function’s definition. The form is:
showSource <fn>

This is useful for browsing definitions if you are working on many scripted functions, that were
perhaps defined in several script files loaded with fileIn() or Run Script in the MAXScript
utility.

See also
Function Variables (p. 701)
Function Parameters (p. 702)
The Return Expression (p. 705)
Special Notes about Function Calls (p. 678)
 Function Variables 701

Function Variables
When you define a function, the following events occur:
• The function definition is evaluated, creating a function value.
• The function <name> is used to declare a new variable with that name.
• The function value is placed into that variable.
• The function value is returned as the result of the function definition expression.
Because the function itself is a value stored in a variable, you not only can call the function through
the function name variable. By simply referring the function’s variable you can also assign the
function value to another variable, store it in an array, or pass it as an argument to another function.
Example:
-- some 3D surface functions
fn saddle x y = sin x * sin y
fn sombrero x y = cos (x^2 + y^2) / (1 + (x^2 + y^2))
print (saddle 1 1) -- try one out
surface_functions[1] = saddle -- store the functions in an array
surface_functions[2] = sombrero
z = (surface_functions[i]) 10 10 -- call one of them from within
-- the array
build_math_mesh sombrero -- pass one in to a higher-order
-- function

The scope of a function variable is the current MAXScript scope context. The variables used inside a
function have a local scope, unless the variable was already defined at a higher scope or is declared
as global in the function. An exception to this is the function parameter variables, which always
have a local scope.
When writing scripts, it is good programming practice to explicitly declare your local and global
variables. Implicit declaration is provided as a short-hand, typically used when working in the
Listener interactively or developing short scripts. When developing extended scripts, explicitly
declaring variables can reduce errors and improve readability of the code. It is also recommend that
you declare as local all variables unless you really want them to be global variables. The reasons for
this are described in the Scope of Variables (p. 646) topic.
If a function variable is assigned to another variable, a reference to the function value is stored in
that variable. Thus while a function variable may no longer be in scope, the function itself still is if
the variable it is assigned to has a scope that extends outside the current MAXScript scope context.
702 Chapter 7 | Creating Functions

Examples:
fn funcA which =
( if which == 1 then
fn saddle x y = sin x * sin y
else
fn sombrero x y = cos (x^2 + y^2) / (1 + (x^2 + y^2))
)
myfunc=funcA 2
z=myfunc 10 10

In the above example, the scope of variables saddle and sombrero is local to funcA, and the
variables are out of scope outside the function. The return value of funcA is either the function value
saddle() or sombrero(), and is assigned to variable myfunc. As also can be seen in this example,
you can define a function within any expression.

See also
Scope of Variables (p. 646)
Function Calls (p. 675)

Function Parameters
The parameters to a function are implicitly declared as local variables at the head of the function
body, and are initialized with the arguments given by the caller. The parameters have a scope that
extends to the end of the function body <expr>. They can be assigned to and hidden by nested local
variables with the same name, as can other local variables.
Keyword parameters can be given default values in the function definition, implicitly making them
optional to the caller. If the caller does not supply one of the keyword arguments, it is initialized to
the default value upon function entry. The default values are specified after the ‘:’ (colon).
If a keyword parameter is defined with no default value and is not supplied by the caller, it is
initialized to the special value unsupplied. You can check for this value in the body of your
function and handle missing required keyword argument errors accordingly.
Example:
fn foo a b: c: d: =
(
if c == unsupplied then print “Where’s the c: argument??”
...
)

As described in the Reference Assignment (p. 653) topic, MAXScript uses an assignment called reference
assignment. In a function, each parameter variable contains a reference to the value passed to the
function by the caller. Assigning to a parameter variable places a new reference in the parameter
variable, and has no effect on the variable values in the caller - it is an entirely local action. An
exception to this is if the parameter value is a compound value such as an 3D Point, string, or array,
and you assign a new value to one of the components of the compound value. In this case, the
 Function Parameters 703

variable’s reference does not change, and the changed compound value will still be referenced by
the variable in the caller.
While in some cases you may want a function to return multiple values, it typically is not a good
practice to do this by assigning to the components of a parameter variable compound value. To
manipulate a compound value passed as a parameter, a compound value needs to be created in the
caller and passed to the function, which can give results as shown in this example:
Script:
fn getXYZset val =
( val.x=random -100 100
val.y=random 100 100
val.z=random val.x val.y
)
( v1=[0,0,0]
v4=v1
getXYZSet v1
format “v1= %; v4= %\n” v1 v4
getXYZSet v4
format “v1= %; v4= %\n” v1 v4
)

Output:
getXYZset() -- result lines 1 to 5
v1= [-84,100,78.1224]; v4= [-84,100,78.1224] -- output line 10
v1= [10,100,18.6575]; v4= [10,100,18.6575] -- output line 12
OK -- result lines 6 to 12

Note that it appears the value for both variables v1 and v4 are set in the calls to getXYZset, even
though only one variable is being passed. The reason for this is in line 8 variable v4 is initialized to
the value of v1. What actually occurs is that in line 7 a reference to a Point3 value of [0,0,0] is
created, and this reference is stored in v1. In line 8, that same reference is retrieved from v1 and
assigned to v4. Rather than storing two different values, both v1 and v4 reference the same value.
When you set the components of the compound value in getXYZset, the reference to the Point3
value is not being changed, and both variables still reference that value.
704 Chapter 7 | Creating Functions

The proper way to return multiple values from a function is to have the return value of the function
be an array or a structure. For example:
Script:
fn readDataFile filename =
( f=openfile filename
data=#()
avg=0
nVals=0
while not eof f do
( val = readvalue f
append data val
avg += val
nVals += 1
)
close f
#(data,(avg/nVals))
)
result=readDataFile “c:\\datafiles\\run1.dat”
data=result[1]
avg=result[2]

Normally, if you are writing a function that is operating on a compound value which is passed as a
parameter, you should make a copy of the value. This prevents the value in the caller from
inadvertently being changed. For example:
Script:
fn uppercase instring =
( local upper, lower, outstring
upper=”ABCDEFGHIJKLMNOPQRSTUVWXYZ”
lower=”abcdefghijklmnopqrstuvwxyz”
outstring=copy instring -- operate on copy of instring
for i=1 to outstring.count do
( j=findString lower outstring[i]
if j != undefined do outstring[i]=upper[j]
)
return outstring
)
 The Return Expression 705

The Return Expression

As with the loop constructs, you can break out of a function body block-expression prematurely in
MAXScript, and return a result without evaluating the remaining portion of the block. For this
purpose, you use the return expression:
return <expr>

If a return expression is evaluated in the course of running a function body, the function exits
immediately and yields the value given in the return <expr>.
Note that it is unnecessary and somewhat inefficient to place a return expression at the end of a
function body to return an expression value. Instead, simply place the result expression at the end
of a function body.
If a return <expr> is used in a mapped function and a collection is passed as the first argument to
the function, the value returned will be OK rather than <expr>.
As a special case, you can exit a script controller’s script using a return <expr>.
Example:
fn find_root twod_fn =
(
local root, last_root
while true do
(
...
if abs(root - last_root) < epsilon then return root
...
)
)
706 Chapter 7 | Creating Functions
Chapter 8: Structure Definition

You can create your own compound values in MAXScript using structure definitions. Structure
definitions let you define the layout of new ‘classes’ of values that you can then create and work
with in your code. The syntax for a structure definition is:
struct <struct_name> ( <member> { , <member> } )
where each <member> can be one of:
<name> [ = <expr> ] -- name and optional initial value
<function_def>

Example:
struct person (name, height, age, sex)
defines a new ‘person’ class. You create values of this class using the ‘person’ constructor:
bill = person name:”Bill” height:72 age:34 sex:#male
creates an instance of the person class, storing the instance in variable bill.
Member name is initialized to the string value “Bill”, height to the integer value
72, age to the integer value 34, and sex to the name value #male.
joe = person name:”Joseph” sex:#male
creates an instance of the person class, storing the instance in variable joe.
Member name is initialized to the string value “Joseph” and sex to the name
value #male. Since the height and age members are not assigned values, and do
not have optional initial values supplied in the structure definition, they default
to a value of undefined.
You access structured values using the standard property accessing syntax in MAXScript:
bill.age -> 34
joe.age -> undefined
joe.age = bill.age - 4

Structure definitions are useful as an alternative to arrays when you have a fixed, usually small
number of independent components and the code to work with them is much clearer when they
can be referenced by property name, rather than by index number.
708 Chapter 8 | Structure Definition

As with function definitions, a structure definition actually creates a value to represent the
definition and stores it in a variable of the same name as the structure. You can therefore store the
structure definitions in other compound objects or pass them as function arguments The
classOf() function returns this structure definition value when applied to these values, so you can
use it to test the definition of structure instances at runtime. For example:
classOf bill -> person

The struct value constructors are just like function calls and take positional argument initializers
as well as keyword initializers. The elements of the new struct are filled-in in order from any
positional arguments and then by name from any keyword arguments.
For example, given the following struct definition,
struct foo (name, age, height, hair=”brown”)

you can create instances, in several ways:

f1 = foo “bill” 23 72 -- fills in name, age, height in order
f2 = foo age:45 name:”sam” -- random named initializers
f3 = foo “mary” hair:”red” -- first name, then keywords

There is one method associated with struct values:

copy <struct>
Creates a copy of the structure. The copy made is what is called a shallow copy - only a copy
of the upper-level value itself (that is, the struct value) is created. Copies aren’t made of
compound values stored in the structure, rather the same compound value is stored in
both struct values. This can be seen in the following example, where changing a
component value of a compound value in a copy of a struct value also changes value in
the original struct value:
Script:
struct test (pos1, pos2) -- define a structure
testval = test [1,2,3] [4,5,6] -- create struct value
testval_copy=copy testval -- copy the struct value
testval_copy.pos1.x=10 -- change component value of a compound
-- value in the copy
testval -- look at original struct value

Output:
#Struct:test( -- result line 1
pos1:<data>,
pos2:<data>)
#test(pos1:[1,2,3], pos2:[4,5,6]) -- result line 2
#test(pos1:[1,2,3], pos2:[4,5,6]) -- result line 3
10 -- result line 4
#test(pos1:[10,2,3], pos2:[4,5,6]) -- result line 6
 Defining Local Functions in Structures 709

Defining Local Functions in Structures

You can define local functions in structures, providing a convenient mechanism for packaging a set
of related functions and avoiding possible name conflicts when many global functions are defined,
possibly by several separate scripts. For example:
struct foo
(
a, b, c,
fn baz n = sqrt (n + 1),
fn bar x y = print (x ^ 2 + y ^ 2)
)

This defines a structure definition foo with 3 elements named a, b, and c, and two local functions,
bar and baz. You can access these functions as properties of either the structure definition value
itself or an instance of the foo structure:
p = foo.baz q -- access as property of the structure definition value
foo.bar x y

f = foo 2 3 4
f.bar x y -- access as property of the structure instance

Local functions declared in a structure definition can make references to the member data variables
defined in the structure, such that when that member function in some instance of the structure is
called, the references access the members of that instance. This allows you to initialize and maintain
data structures for the structure functions within the structure itself. An example of including
functions that use members of the structure is shown in the following script.
Script:
struct RandVals
( RndVals=#(), ptr, seedVal,
fn generateRV num fromVal toVal =
( if seedVal != undefined do seed seedVal
RndVals=for i=1 to num collect random fromVal toVal
ptr=1
RndVals
),
fn deleteRv =
( RndVals=#()
ptr=undefined
undefined
),
fn getNextRV =
( if Nvals == 0 do return undefined
val=RndVals[ptr]
ptr += 1
if ptr > RndVals.count do ptr=1
val
),
fn sortRV = (sort RndVals),
710 Chapter 8 | Structure Definition

fn setSeed val = (SeedVal = val),

fn setPointer val =
( if val > 0 and val <= RndVals.count then
(ptr=val;true)
else
false
)
)
MyRandomVals= RandVals()
MyRandomVals.setSeed 12345
MyRandomVals.generateRV 10 0 100
MyRandomVals.getNextRV()
MyRandomVals.sortRV()
MyRandomVals.setPointer 1
MyRandomVals.getNextRV()
MyRandomVals.deleteRv()

Output:
#Struct:RandVals( -- result of struct def lines 1 to 29
generateRV:<fn>,
sortRV:<fn>,
RndVals:<data>,
deleteRv:<fn>,
getNextRV:<fn>,
seedVal:<data>,
setSeed:<fn>,
setPointer:<fn>,
ptr:<data>)
#RandVals(RndVals:#(), ptr:undefined, seedVal:undefined) -- result line 30
12345 -- result line 31
#(23, 59, 79, 68, 17, 72, 84, 16, 89, 72) -- result line 32
23 -- result line 33
#(16, 17, 23, 59, 68, 72, 72, 79, 84, 89) -- result line 34
true -- result line 35
16 -- result line 36
undefined -- result line 37

In this script, the structure has 3 data members and 6 function members. Note the references to the
structure data members in the generateRV() function. In line 30, an instance of the RndVals
structure is created and stored in variable MyRandomVals. In line 31, the setSeed() function in the
structure instance is called, which initializes the random seed variable by storing the specified value
in data member seedVal in the structure instance. In line 32, the generateRV() function in the
structure instance is called, which initializes the random number using the seed value specified by
setSeed(), sets up and stores an array of random numbers in data member RndVals, updates data
member ptr, and then returns the random number array.
Local functions defined in structures are not stored in every instance of the structure. The local
function is stored once in the structure definition and references to them in the instances refer to
their definitions in the structure definition.
 Structure Inherited Methods 711

Structure Inherited Methods

All structures inherit from the Value (p. 713) class and so structure instances implement the Value
methods print(), format(), classOf(), superClassOf(), isKindOf(), ==, and !=. The
copy() method is the only method not inherited from Value that structures implement. It yields a
top-level copy of the structure you call it on, meaning that you get a new, separate structure instance
containing the same element values as the original and then you can modify that copy
independently. The element values are not themselves copies, so for example, if one of the elements
was an array, the copy would reference that same array, not a copy of that array.
712 Chapter 8 | Structure Definition
Chapter 9: Values

The Value class is the root class for all MAXScript classes. It supplies methods and operators that any
class can use.
As described in the Properties, Methods, Operators, and Literals (p. lxiv) topic, each class can specify
external interfaces for the class. These external interfaces are broken up into the following
categories:
• Literals: Any literal form for objects of the class.
• Constructors: The various ways you can create objects of the class.
• Properties: Accessible parameters for objects of the class.
• Operators: Defines the math and other symbolic operators that are defined on values in
the class.
• Methods: Defines all the functions you can call for objects of the class.
In the description of each class in MAXScript, each of these external interfaces are documented.
In the syntax forms given for methods, operators, and properties, the types of argument or property
values are specified using the <type_name> convention, in which type_name describes the type of
value that is allowable for that argument or property. You can, of course, use an arbitrary expression
for these values, as long as it evaluates to a value of the right type. For example, <boolean> means
either the true or false Boolean values.
Also indicated for function calls are those that are automatically mapped over collections. This
means that the function will be automatically called repeatedly on the elements of a collection if
the collection is given as the first argument to the function. See the Collections (p. 773) topic for more
information.
714 Chapter 9 | Values

Value Common Properties, Operators, and Methods

Operators:
<value> == <value>
compare if equal
<value> != <value>
compare if not equal
<value> as <class>
Converts the value to an instance of given class. See the description for each class for valid
conversions. All values can be converted to class String, which yields a string with the
printed representation of the value.
Methods:
print <value> [ to:<stream> ] [#noMap] -- mappable
where <stream> is
( <filestream> | <stringstream> | <windowstream> )

Prints single value to Listener or optional filestream (p. 763), stringstream (p. 766), or
windowstream (p. 767), followed by a line break. If the argument value is a Collection
(p. 773), and #noMap is not specified, each value in the collection is printed out on a
separate line. If #noMap is specified, the collection value is printed out on a single line. The
printed form of all basic data value types, except for BigArray, are directly readable by the
readValue() and readExpr() functions, making it simpler to read back in values
printed to a file by MAXScript. If the pre-3ds max R3 print forms are required for
compatibility with existing scripts, you can set the system global variable
options.oldPrintStyles to true.
format <format_string> { <value> } [ to:<stream> ]
Prints one or more values to Listener or optional filestream, stringstream, or
windowstream, using the format string as a template. The format string is a string that can
contain plain text to print interspersed with the ‘%’ (percent) metacharacter. Each
occurrence of a ‘%’ is replaced by the printed representation of the successive argument
values following the format string. For example:
format “name:%, pos:%\n” obj.name obj.pos

generates something like:

name: box01, pos: [0, 150.0, 0.5]
format does not automatically append a line break to the output stream, so you
can build up a line from several format calls and generally control layout better.
An explicit ‘\n’ newline escape character sequence is needed to place a line break
in the output stream. Other escape character sequences are documented in the
String Literals (p. 660) topic.
 Value Common Properties, Operators, and Methods 715

classOf <value>
Returns the value’s class. Each type of value has its own class. If the value is a Node value,
classOf() returns the class of the world state object (the state of the node at the top of its
stack). See the Node : MAXWrapper (p. 820) topic for more information.
Note:
To avoid a conflict between a user class value in global variable named ‘rollout’ and MAXScript
reserved word ‘rollout’ which always introduces a rollout definition the class variable name for a
rollout is RolloutClass.
So, for a rollout foo you’d now say “if classOf foo == RolloutClass”.
superClassOf <value>
Returns the value’s superclass. A value’s superclass is the class from which the value’s class
was derived.
isKindOf <value> <class>
Returns true if value has given class or inherits from class.
isStructDef <value>
Returns true if the value is a structure definition
isStruct <value>
Returns true if the value is a structure instance
isController <value>
Returns true if the value is a controller
getHashValue <value> <Integer oldHaskValue>
If the value is one of the supported value types, returns an integer hash value that is a
factor of the value and oldHaskValue. If the value type is not supported, returns a value of
undefined. The supported value types are:
Float
Integer
String
BitArray
Point3
Ray
Quat
AngAxis
EulerAngles
Matrix3
Point2
Color
Arrays containing any of the above value types
716 Chapter 9 | Values

Working with Values

Print and Format:
The print() and format() functions are straightforward. The format function is used when any
formatting of the output is desired, or if you want to print multiple values on a line. When printing
a value using either of these functions, a string representation of the value is printed. This is not the
object name for those objects with names (for example a 3ds max object or material). In the
following example, variable b contains a reference to a 3ds max Box object that has a material
applied:
Script:
print b
print b.name
print b.material
print b.material.name

Output:
$Box:Box01 @ [-74.353745,0.000001,-19.931978]
“Box01”
Material #1:Standard
“Material #1”

The printed results above also reflect the result of a <value> as string operation, that is the result
is a string representation of the object rather than the object name.
classOf, superClassOf, and isKindOf
The following table shows the hierarchy of classes and superclasses for a variable that contains a
reference to a 3ds max Box object (i.e., b=box()).

ClassOf SuperClassOf and isKindOf

b Box GeometryClass
box GeometryClass Node
GeometryClass Node MAXWrapper
Node MAXWrapper Value
MAXWrapper Value Value
Value Value Value

The isKindOf() and classOf() functions are useful for filtering objects from a set. For example,
either of the following will collect all objects of class box into variable allBoxes:
allBoxes=for obj in $* where (isKindOf obj box) do collect obj

allBoxes=#()
for obj in $* do (if classOf obj == box then append allBoxes obj)
 Number Values 717

One of the named parameters to the interactive node selection functions is filter, which allows
you to specify a function that returns a value of true if an object can be selected. The classOf,
superClassOf, and isKindOf functions are frequently used in these functions. For example, the
following function limits the choices to shape objects:
fn shape_filt obj = isKindOf obj Shape

For an example of such a usage, see the Pickbutton (p. 1504) topic.

Basic Data Values

Number Values (p. 717)
String Values (p. 722)
Name Values (p. 727)
BooleanClass Values (p. 728)
Color Values (p. 729)
Point3 Values (p. 731)
Point2 Values (p. 736)
Ray Values (p. 737)
Quat Values (p. 738)
AngleAxis Values (p. 741)
EulerAngles Values (p. 742)
Matrix3 Values (p. 744)
BigMatrix Values (p. 748)
Box2 Values (p. 750)
BitArray Values (p. 791)
ArrayParameter Values (p. 770)

Number Values
Integer : Number
Float : Number
The Number class provides standard arithmetic capabilities to MAXScript. The two Number types,
Integer and Float, can be freely intermixed and MAXScript will convert as necessary. They both
support all the following operators and methods. Also see the Number Literals (p. 660) topic.
Literals:
[-]{<digit>}[.{<digit>}[(e | E)[+ | -]{<digit>}+] -- decimal number
0x{<hex_digit>}+ -- hexadecimal number
718 Chapter 9 | Values

Example Literals:
123
123.45
-0.00345
1.0e-6
0x0E
0xFFE0
.1

Operators:
<number> + <number>
<number> - <number>
<number> * <number>
<number> / <number>
Standard arithmetic operations. If both numbers are integers, the result is a non-rounded
integer. If one or both numbers are floats, both arguments are widened to floats and the
result is a float.
<number> ^ <number>
Raise the first number to the power given by the second number. If the first number is an
integer, the result is a rounded integer.
- <number>
unary minus
<number> == <number>
<number> != <number>
<number> > <number>
<number> < <number>
<number> >= <number>
<number> <= <number>
Standard number comparison operations.
<number> as <class>
Converts the number to an instance of the given class. Allowed classes are:
Float
Integer
String
Time (number taken as frames)

Methods:
copy <number>
Creates a new copy of the number value. This method exists primarily to support
copying arrays.
abs <number>
Returns the absolute value of the number. The result is the same type as the argument.
mod <number1> <number2>
Modulo arithmetic, the remainder when number1 is divided by number2. The result is
always a float.
 Number Values 719

ceil <number>
Returns the nearest whole number greater than or equal to number. The result is always
a float.
floor <number>
Returns the nearest whole number less than or equal to number. The result is always
a float.
acos <number>
asin <number>
atan <number>
atan2 <number> <number>
cos <number>
cosh <number>
sin <number>
sinh <number>
tan <number>
tanh <number>
Standard trigonometric functions. Angles are represented in degrees. The result is always
a float.
exp <number>
log <number>
log10 <number>
pow <number> <number>
sqrt <number>
Standard transcendental functions. The result is always a float.
random <number> <number>
Returns a pseudo random number inclusively between the two arguments. Return value
type is the type of the first argument.
seed <number>
Reseeds the random number generator using the specified value.
degToRad <number>
Returns the conversion of the number from degrees to radians. The result is always a float.
radToDeg <number>
Returns the conversion of the number from radians to degrees. The result is always a float.
bit.and <integer1> <integer2>
Returns the <integer> result of AND-ing the bits in integer1 and integer2
bit.or <integer1> <integer2>
Returns the <integer> result of OR-ing the bits in integer1 and integer2
bit.xor <integer1> <integer2>
Returns the <integer> result of XOR-ing the bits in integer1 and integer2
bit.not <integer1>
Returns the <integer> result of flipping the bits in integer1
720 Chapter 9 | Values

bit.shift <integer1> <integer2>

Returns the <integer> result of shifting the bits in integer1 by integer2 places. If integer2 is
positive, the bits are shifted to the left, if negative, to the right. The highest order bit is not
carried when shifting to the left (unsigned shift operation).
bit.set <integer1> <integer2> <boolean>
Returns an <integer> result where bit integer2 of integer1 is set to the specified boolean
value. Bit 1 is the lowest order (least significant) bit.
bit.flip <integer1> <integer2>
Returns an <integer> result where bit integer2 of integer1 is flipped. Bit 1 is the lowest
order (least significant) bit.
bit.get <integer1> <integer2>
Returns the <boolean> state of the integer2 bit of integer1. Bit 1 is the lowest order (least
significant) bit.
bit.intAsChar <integer>
Returns a <string> result of length 1 containing the character corresponding to the integer
value. Only the lowest order 8-bits (16-bits for localized versions of 3ds max) of the integer
areused.
bit.charAsInt <string>
Returns the <integer> value corresponding to the first character of the string.
bit.intAsHex <integer>
Returns a <string> value containing the hex representation of the integer.
Notes:
The range of valid Integers in MAXScript is -2,147,483,648 to 2,147,483,647. If you perform
calculations that result in integers outside of this range, you will get integer overflow errors that are
not detected by MAXScript. You must take care in designing your code to prevent or detect this
overflow yourself. The result of an overflow is typically a large number of the wrong sign. Dividing
an integer by 0 will result in a MAXScript system exception.
A Float in MAXScript has an absolute value range of is 1.18E-38 to 3.40E38, with a precision of one
part in 1.0E7. If you perform calculations that result in floats with an absolute value less than this
range, the result will be stored as 0.0. If you perform calculations that result in floats with an
absolute value larger than this range, the result will be stored as a special value that represents
infinity, 1.#INF. Adding, subtracting, or multiplying a number by 1.#INF results in a value of
1.#INF. Dividing a number by 1.#INF results in a value of 0.0. Dividing 0.0 by 0.0 or 1.#INF by
1.#INF, multiplying 1.#INF by 0, or 1.#INF from 1.#INF results in a special value that represents
an indeterminate number, -1.#IND. Adding, subtracting, multiplying, or dividing a number by -
1.#IND results in a value of -1.#IND.
 Number Values 721

When you display or print a Float, MAXScript prints the value to the 6th significant digit. The
following table shows examples of values stored to a MAXScript variable, the value as stored, and
the value as displayed.

Input Value Stored Value Displayed Value

1.23456789 1.23456788 1.23457
1.1 1.10000002 1.1
1.01 1.00999999 1.01
1.001 1.00100004 1.001
1.0001 1.00010001 1.0001
1.00001 1.00001001 1.00001
1.000001 1.00000095 1.0
1.0000001 1.00000011 1.0
1.00000001 1.00000000 1.0
100017.911 100017.914 100018.0

Examples:
The following script shows the use of various literals, constructors, properties, operators, and
methods of the Number class.
Script:
-- numbers test bed
i=10 -- assign integers to variables
j=20
i/j -- integer divide, result is integer
i=i as float -- convert i to a float
i/j -- float divide, result is float
i += 1 -- increment i by 1
if i < j do i=2.^3 -- if i is less than j, set i to 2 to the 3rd power
mod j i -- return remainder of j divided by i
cos 30.0 -- return cosine of 30 degrees
sqrt j -- return square root of j
seed 12345 -- seed the random number generator
for k=1 to 5 do print (random i j) -- print out 3 random numbers
722 Chapter 9 | Values

Output:
10 -- result of line 2
20 -- result of line 3
0 -- result of line 4 (10/20)
10.0 -- result of line 5
0.5 -- result of line 6 (10./20)
11.0 -- result of line 7
8.0 -- result of line 8 (2.^3)
4.0 -- result of line 9
0.866025 -- result of line 10
4.47214 -- result of line 11 (sqrt 20)
OK -- result of line 12
10.7775 -- output from line 13 (random 8. 20)
15.0183
17.4467
16.1027
10.1344
OK -- result of line 13

String Values
The String class defines the characteristics of character strings. The character strings can be of
any length.
Literal:
“<characters>”
See the String Literals (p. 660) topic for a description of String literals.
Constructors:
<value> as string
Converts any value into its string representation.
Properties:
<string>.count : Integer, read-only
The number of characters in the string.
Operators:
<string> + <string>
Returns a new string that is the concatenation of the two strings.
<string> == <string>
<string> != <string>
<string> > <string>
<string> < <string>
<string> >= <string>
<string> <= <string>
Standard lexical string comparisons (case sensitive). To perform a case insensitive
comparison, first convert the strings to Name values.
<string>[<index_number>]
Returns indexed character as a single-character string, index starts at 1.
 String Values 723

<string>[<index_number>] = <single_character_string>
Sets indexed character to character given.
<string> as <class>
Converts the string to an instance of the given class. You can convert a string into a Name
value using the as operator, for example:
“Foo” as name -- returns #foo

You can also convert strings to numbers using the as operator. For example:
“123.4” as float -- returns 123.4

You can use any of the Number classes as a target class - Number, Float, or Integer. If you
use Number, the appropriate class will be used depending on the syntax of the number in
the string.
You can convert a string to a StringStream value using the as operator. For example:
“$box01” as stringstream -- returns the string as a stringstream

Converting a string to a StringStream value allows you to read through a string using the
MAXScript’s text file I/O operations. See the StringStream Values (p. 766) topic for a
description of StringStreams.
Methods:
copy <string>
Creates a new copy of the string value. For example:
newstr = copy oldstr

The new value contains a copy of the text contents of the copied string, and is
independent of the copied string.
execute <string>
Compiles and evaluates the contents of the string as a MAXScript expression and returns
the result of the evaluation. For example:
execute “2 + 2” -- yields the value 4

str = “$foo.ffd_2x2x2.control_point_” +
n as string + “ = [1,1,1]”

execute str

The result of an execute() call is the result of the last expression in the string argument.
724 Chapter 9 | Values

You can use execute() as a temporary work-around to the current limitation in naming
scene objects - there is currently no way to name an object using a computed name. For
example:
obj = execute (”$foo/” + child_name)

would retrieve the child of $foo named in the variable child_name. Here’s a more
complex example:
side = “left”
finger = 2
limb = “arm”
obj = execute (”$torso/” + limb + “/” +
side + “/finger/” +
finger as string)

The scope of variables used in the evaluated string is global and not the scope in effect
when the execute() method is executed. So if you call execute() within a function,
scripted utility, or anywhere where the scope is not global, you will need to explicitly
specify the scope of any variables used in the string that is executed. In the following
example, the scope of variable posObj is local to utility myUtil, so the string needs to
specify the variable’s name as being in myUtil’s scope:
Utility myUtil “My Utility”
(
...
local posObj
...
fn test obj =
( local i, j, thisCont
...
thisCont=execute (”myUtil.posObj.’”+j+”‘pos.controller”)
...
)

In general, you cannot access locals from outside of an object, except for top-level locals in
rollouts, utilities, tools and plug-ins (because they are semi-permanent and are stored with
these objects). Function parameters and locals are dynamic and stack-based and not
accessible as properties of the function definition.
For more information on variable scope, see the Scope of Variables (p. 646) and Accessing
Locals and Other Items in a Rollout from External Code (p. 1480) topics.
GetTextExtent <string>
Returns a Point2 value containing the size of the string in pixels if it was displayed in a
command panel.
findString <string> <search_string>
Returns the index of search_string in string or undefined if not found. For example:
findString “Thanks for all the fish!” “all” -- returns 12
 String Values 725

filterString <string> <token_string>

Parses string based on token_string and returns an array of strings. filterString
splits the input string into substrings based on the characters given in token_string,
and returns each substring as a member of the array. The token_string is simply a list of
‘splitter characters’ - when the string is scanned, any occurrence of any of the tokens is
regarded as the start of a substring. This function is useful for file import/export scripts, or
for any type of manual parsing. For example:
filterString “MAX Script, is-dead-funky” “, -”

would return
#(”MAX”,”Script”,”is”,”dead”,”funky”)

replace <string> <from_integer> <length_integer> <new_string>

Returns a new string where the substring in string starting at index from_integer, and
of length length_integer, is replaced with the new_string. new_string can be any
length. The sum of from_integer and length_integer must be less than the length of
string. An example usage is:
s=”1234567890”
s1=replace s 5 3 “inserted string” -- returns “1234inserted string890”

substring <string> <from_integer> <length_integer>

Returns a new string consisting of the substring in string starting at index
from_integer, and of length length_integer. If the sum of from_integer and
length_integer is greater than the length of string, a shorter string is returned
containing as many characters as are available in the source. If a negative value is specified
for length_integer, the remainder of the string starting from from_integer is
returned. For example:
s = “Balerofon”
ss = substring s 5 3 -- returns “rof”
ss = substring s 5 -1 -- returns “rofon”
ss = substring s 5 100 -- returns “rofon”

matchPattern <string> pattern:<pattern_string> \

[ ignoreCase:<boolean> ]
Returns true if string is matched by the wild card pattern_string, false otherwise.
The comparison is case-insensitive unless ignoreCase:false is specified. For example:
s=”text1”
matchPattern s pattern:”text?” -- returns true
matchPattern s pattern:”T*” -- returns true
matchPattern s pattern:”T*” ignoreCase:false -- returns false
matchPattern s pattern:”s*” -- returns false

Examples:
The following script shows the use of various literals, constructors, properties, operators, and
methods of the String class.
726 Chapter 9 | Values

Script:
-- strings test bed
fn uppercase instring = -- beginning of function definition
( local upper, lower, outstring -- declare variables as local
upper=”ABCDEFGHIJKLMNOPQRSTUVWXYZ” -- set variables to literals
lower=”abcdefghijklmnopqrstuvwxyz”
--
-- create an unique copy of the string referenced by instring, and store
-- reference to unique copy in outstring
outstring=copy instring
--
-- increment from 1 to number of character in string
for i=1 to outstring.count do
--
-- see if the single character at index i in outstring is present in string lower
-- If so, j equals position in string lower. If not, j equals undefined
( j=findString lower outstring[i]
--
-- if character was found in lower, replace with corresponding character in upper
if (j != undefined) do outstring[i]=upper[j]
)
outstring -- value of outstring will be returned as function result
)-- end of fn uppercase
--
s1=”AbCdEfGh” -- set variable to literal
s2=uppercase s1 -- call function uppercase, passing s1 as parameter
if s1 == s2 do print “strings s2 and s3 are the same” -- compare strings
if s1 != s2 do print “strings s1 and s2 are different”
--
theObject=”sphere” -- set variable to literal
theRadius= (random 10. 100.) as string -- convert number to string
-- concatenate strings and execute string
myObject=execute (theObject + “ radius:” + theRadius)

Output:
uppercase() -- result to function definition
“AbCdEfGh” -- result of line 24
“ABCDEFGH” -- result of line 25
undefined -- result of line 26 - strings not equal,
-- and no else expression in if expression
“strings s1 and s2 are different” -- output from line 27
“strings s1 and s2 are different” -- result of line 27
“sphere” -- result of line 29
“75.4091” -- result of line 30
$Sphere:Sphere01 @ [0.0,0.0,0.0] -- result of line 32. Execute function
-- created a sphere object
 Name Values 727

Name Values
The Name class defines the characteristics of names. Names are primarily used as parameters in
function calls to signify one of a set of options.
Literal:
#<var_name>
See the Names (p. 657) topic for a description of Name literals.
Constructors:
<string> as name
Converts a String value into a name
Operators:
<name> == <name>
<name> != <name>
<name> < <name>
<name> > <name>
<name> <= <name>
<name> >= <name>
Comparison of names is caseless alphabetic. Among other things, this allows arrays of
names to be sorted using the array sort function.
Examples:
The following script shows the use of various literals, constructors, and operators of the Name class.
Script:
-- name test bed
name1=#Hello -- set variable to name literal
name2=”HELLO” as name -- convert string to name
if name1 == name2 do print “names are equal” -- compare the names
box_props=getpropnames box -- get the properties of box class
sort box_props -- sort the property names

Output:
#Hello -- result of line 2
#Hello -- result of line 3
“names are equal” -- output from line 4
“names are equal” -- result of line 4
-- following are the results of lines 5 and 6
#(#height, #length, #lengthsegs, #width, #widthsegs, #mapCoords, #heightsegs)
#(#height, #heightsegs, #length, #lengthsegs, #mapCoords, #width, #widthsegs)
728 Chapter 9 | Values

BooleanClass Values
The BooleanClass class defines the characteristics of values that can only have one of two states.
Literals:
true
false
on -- equivalent to true
off -- equivalent to false

Operators:
not <boolean>
true if boolean=false, false if boolean=true
<boolean> and <boolean>
true if both boolean values are true
<boolean> or <boolean>
true if either boolean value is true
Notes:
The boolean and and or evaluations are non-strict. This means that only the first boolean may be
evaluated to determine the overall result:
• If the first operand is false in an and expression, the result must be false, therefore, the second
operand is not evaluated.
• If the first operand is true in an or expression, the result must be true, therefore, the second
operand is not evaluated.
This saves execution time and enables useful shorthand notation. For example, if you want to
calculate ‘sin a’ if the value of variable ‘a’ isn’t undefined, you could use the example below:
if a != undefined and sin a > 0 then ..

Examples:
The following script shows the use of various literals and operators of the BooleanClass class.
Script:
-- boolean test bed
bool1=true -- set variables to boolean literals
bool2=on
if bool1 and bool2 do print “booleans are equal” -- compare the booleans
-- define an “exclusive or” function - returns true if only one of the
-- inputs is true
fn xor b1 b2 = (not (b1 and b2)) and (b1 or b2)
xor false false -- evaluate 4 combinations of inputs to xor
xor false true
xor true false
xor true true
 Color Values 729

Output:
true -- result of line 2
true -- result of line 3
“booleans are equal” -- output from line 4
“booleans are equal” -- result of line 4
xor() -- function definition
false -- result of line 8
true -- result of line 9
true -- result of line 10
false -- result of line 11

Color Values
All the places that colors turn up in MAXScript (such as wireColor, light color, etc.) are represented
by instances of the Color class. You can also use Point3 values as color specifiers.
Literals:
red
green
blue
white
black
orange
yellow
brown
gray
predefined MAXScript globals
Constructors:
color <r> <g> <b> [ <a> ]
r,g,b and optional alpha are float values in the range 0 to 255
<point3> as color
interprets x as r, y as g, z as b
Properties:
<color>.red or .r : Float
<color>.green or .g : Float
<color>.blue or .b : Float
<color>.alpha or .a : Float
color component properties
<color>.hue or .h : Float
<color>.saturation or .s : Float
<color>.value or .v : Float
derived properties
730 Chapter 9 | Values

Operators:
<color> == <color>
<color> != <color>

<color> + <color_or_number>
<color> - <color_or_number>
<color> * <color_or_number>
<color> / <color_or_number>
Channel-by-channel math operations. Numbers operate on r,g,b,a channels equally.
- <color>
unary minus
Methods:
copy <color>
Creates a new copy of the color value. For example:
newClr = copy oldClr

The new value contains a copy of the input color value, and is independent of the input
color value.
random <from_color> <to_color>
Returns a random color between the given colors. The alpha component of the result will
always be 255.
composite <color1> <color2>
Composites color1 over color2 through color1’s alpha. This function is equivalent to:
color1 + color2*((255. - color1.alpha)/255.)

-- 3D Noise Functions
noise3 <color>
noise4 <color> <phase_float>
turbulence <color> <frequency_float>
fractalNoise <color> <H_float> <lacunarity_float> <octaves_float>
See the Point3 Values (p. 731) topic for a description of the noise functions.
Notes:
The component values of a Color value (r, g, b, and a) are normally in the range 0.0 to 255.0.
However values outside this range are permissible. When color values outside the normal range are
used in 3ds max, 3ds max clamps the values to the range of 0.0 to 255.0.
Examples:
The following script shows the use of various literals, constructors, properties, operators, and
methods of the Color class.
 Point3 Values 731

Script:
-- color test bed
magenta=color 255 255 0 255 -- create colors using constructors
aqua = [0, 255, 255] as color
aqua.v /= 2. -- reduce “strength” of aqua color
aqua
aqua.alpha=128 -- set aqua to 50% opacity
aqua
lightGray=white/4 -- create light gray color by dividing
-- each component of white by 4
composite aqua lightGray -- composite light gray over aqua
random black white -- generate a random color

Output:
(color 255 255 0) -- result of line 2. Note that if
-- alpha=255 it is not displayed
(color 0 255 255) -- result of line 3
127.5 -- result of line 4 - value property of aqua
(color 0 127.5 127.5) -- result of line 5 - color of aqua
128 -- result of line 6 - alpha property of aqua
(color 0 127.5 127.5,128) -- result of line 7 - color of aqua
(color 63.75 63.75 63.75) -- result of line 8 - each component divided by 4
(color 31.75 159.25 159.25 159.75) -- result of line 10
(color 170.944 109.543 74.1957) -- result of line 11

Point3 Values
The Point3 class defines the characteristics of points in 3D space. These values are also known as 3D
vectors, and contain 3 component floating point numbers. All the coordinates passed to and from
3ds max are in these values. See also 2D and 3D Point Literals (p. 665).
Literals:
[ <expr>, <expr>, <expr> ]

Example Literals:
[x, y, z]
[10, 10, 10]
[sin x, cos y, tan z]
x_axis -- equivalent to [1,0,0]
y_axis -- equivalent to [0,1,0]
z_axis -- equivalent to [0,0,1]

Constructors:
point3 <x> <y> <z>
<color> as point3
732 Chapter 9 | Values

Properties:
<point3>.x : Float -- the x coordinate
<point3>.y : Float -- the y coordinate
<point3>.z : Float -- the z coordinate

Operators:
<point3> == <point3>
<point3> != <point3>

<point3> + <point3_or_number>
<point3> - <point3_or_number>
<point3> * <point3_or_number>
<point3> / <point3_or_number>
Standard vector arithmetic. If the second operand is a number, the operation is performed
on each component of the value.
<point3> * <matrix3>
Transforms point3 into the coordinate system specified by matrix3.
<point3> * <quat>
rotates point3
- <point3>
unary minus
Methods:
copy <point3>
Creates a new copy of the point3 value. For example:
newPos = copy oldPos

The new value contains a copy of the input point3 value, and is independent of the input
point3 value.
length <point3>
Returns the length of the vector.
dot <point3> <point3>
Returns the vector dot product.
cross <point3> <point3>
Returns the vector cross product.
normalize <point3>
Returns the point3 value normalized such that the vector length equals 1.
distance <point3> <point3>
Returns the distance between the points - length of (point 2 – point 1).
random <point3> <point3>
Generates a pseudo-random point between the given points.
arbAxis <point3>
Returns a Matrix3 value representing an arbitrary axis system using point3 as the
“up” direction.
 Point3 Values 733

matrixFromNormal <point3>
Returns a Matrix3 value with the normal specified by the given point as the Z axis. The
translation portion of the Matrix3 value will be [0,0,0]. The components of the scale
portion are the inverse of the values required to normalize the point3 value. For example,
MatrixFromNormal [0,0,1]
MatrixFromNormal [0,1,1]

will return
(matrix3 [1,0,0], [0,1,0], [0,0,1], [0,0,0])
(matrix3 [0,-0.707107,0.707107] [1.41421,0,0] [0,1,1] [0,0,0])

-- 3D Noise Functions
noise3 <point3>
A floating point noise function over 3D space, implemented by a pseudo-random tricubic
spline. The return value is in the range -1.0 to +1.0. Given the same point3 value, the
noise3() function always returns the same value.
noise4 <point3> <phase_float>
The same function as noise3 in which the phase can be varied using the second parameter.
The return value is in the range -1.0 to +1.0.
turbulence <point3> <frequency_float>
This is a simple fractal-loop turbulence built on top of the noise3 function. The second
parameter controls the frequency of the turbulence. The return value is in the range 0.0 to
+1.0.
fractalNoise <point3> <H_float> <lacunarity_float> <octaves_float>
This is a fractal function of 3D space implemented using fractional Brownian motion. The
function is homogeneous and isotropic. It returns a float.
The parameters are as follows:
point3 - The point in space at which the noise is computed.
H_float - The fractal increment parameter in the range [0,1]. When H_float is 1 the
function is relatively smooth; as H_float goes to 0, the function approaches white noise.
lacunarity_float - The gap between successive frequencies, best set at 2.0.
octaves_float - The number of frequencies in the function.
All the noise functions are based on code and algorithms in the book “Texturing and Modeling:
A Procedural Approach”, Musgrave, Peachey, Perlin and Worley. Academic Press,
ISBN: 0-12-228760-6.
734 Chapter 9 | Values

Examples:
The following script shows the use of various literals, constructors, properties, operators, and
methods of the Point3 class.
The following script was written as a test bed for the noise functions. This script displays a 2
dimensional slice of the noise function output as a bitmap. By changing the noise parameters in
lines 4 through 10, and specifying which noise function to evaluate in line 12, you can see the effects
of changes in the parameters and using different noise functions.
Script:
-- noise functions test bed
b_width=320 -- specify size of bitmap
b_height=320
size=10. -- total distance covered by each row and column
z=0. -- z coordinate of 2D slice
phase=0.5 -- noise4 parameter
frequency=10. -- turbulence parameter
fract_interval=.5 -- fractalNoise parameters
lacunarity=2.
octaves=5
--
whichfunc=1 -- 1 = noise3; 2 = noise4; 3 = turbulence; 4 = fractalNoise
--
b=bitmap b_width b_height -- create the bitmap
for h=0 to (b_height-1) do -- step through each row of the bitmap
( h_norm=(h as float/(b_height-1))*size -- calculate y coordinate
row = for w=0 to (b_width-1) collect -- collect row of pixel colors
( w_norm=(w as float/(b_width-1))*size -- calculate x coordinate
noise_val = case whichfunc of -- store result of selected function
( 1: noise3 [w_norm, h_norm , z]
2: noise4 [w_norm, h_norm , z] phase
3: turbulence [w_norm, h_norm , z] frequency
4: fractalNoise [w_norm, h_norm , z] fract_interval lacunarity octaves
)
noise_val = 0.5*(1.+noise_val) -- convert output range to 0. to 1.
white*noise_val -- and multiply by color white
)
setpixels b [0,h] row -- store row of pixels in bitmap
)
display b -- display bitmap in VFB
 Point3 Values 735

Output:
The following figures show the bitmap generated by the above script for each noise function type.

noise3

noise4

turbulence
736 Chapter 9 | Values

fractalNoise

Point2 Values
The Point2 class defines the characteristics of points in 2D space. This class is a 2D version of Point3
and is used in utility rollout positioning parameters and for accessing Bitmap values, etc. See also 2D
and 3D Point Literals (p. 665).
Literals:
[ <expr>, <expr> ]

Example Literals:
[x, y]
[10, 20]
[sin x, cos x]
Constructors:
point2 <x> <y> -- x and y are numbers
<point3> as point2 -- created from the x and y components of the point3
Properties:
<point2>.x : Float
<point2>.y : Float
Operators:
<point2> == <point2>
<point2> != <point2>

<point2> + <point2_or_number>
<point2> - <point2_or_number>
<point2> * <point2_or_number>
<point2> / <point2_or_number>
Standard vector arithmetic. If the second operand is a number it does scalar arithmetic on
vector.
- <point2>
unary minus
 Ray Values 737

Methods:
copy <point2>
Creates a new copy of the point2 value. For example:
newPoint = copy oldPoint

The new value contains a copy of the input point2 value, and is independent of the input
point2 value.
random <point2> <point2>
Generates a pseudo-random point between the given points.
length <point2>
Returns the length of the vector.
distance <point2> <point2>
Returns the distance between the points - length of (point 2 – point 1).
normalize <point2>
Returns the point2 value normalized such that the vector length equals 1.

Ray Values
The Ray class defines the characteristics of a ray in 3D space. A ray has two Point3 components, one
defining a start position and the other a direction vector for the ray.
Constructors:
ray <pos_point3> <dir_point3>
Returns a new ray with given position and direction vector.
<node> as ray
Takes a scene object that has a target, such as a tape measure or a target camera and returns
a ray from the object to the target. Returns undefined if the object has no target.
Properties:
<ray>.pos : Float
<ray>.position : Float -- pos and position are synonyms
<ray>.dir : Point3 -- unit normalized direction vector

Methods:
copy <ray>
Creates a new copy of the ray value. For example:
newRay = copy oldRay

The new value contains a copy of the input ray value, and is independent of the input
ray value.
738 Chapter 9 | Values

Quat Values
The Quat class provides a compact representation for orientation in three space and provides
methods to perform Quaternion algebra. Quaternions are used to store object rotations in 3ds max.
A quaternion is made up of four terms: a real scalar part which specifies the amount of rotation and
an imaginary vector part which defines the axis of rotation. If the quaternion is normalized, the
scalar term equals the cosine of half the angle of rotation, the vector term is the axis of rotation, and
the magnitude of the vector term equals the sine of half the angle of rotation.
Interpolation between two key frame orientations is much easier using quaternions and produces
smooth and natural motion. Unlike Euler angles, no numerical integration is necessary; quaternions
provide an analytic result (no approximations).
Rotations in MAXScript follow the right-hand-rule, namely positive angles rotate counter-clockwise
about positive axes, consistent with the convention in the 3ds max UI.
Constructors:
quat <x_float> <y_float> <z_float> <w_float>
The x, y, z values make up the vector portion. w is the angle of rotation about the vector.
quat <degrees_float> <axis_point3>
<angleaxis> as quat
<eulerangle> as quat
<matrix3> as quat -- extracts the rotation component as a quat

Properties:
<quat>.w : Float
<quat>.x : Float
<quat>.y : Float
<quat>.z : Float
quaternion complex components as Floats
<quat>.angle : Float
<quat>.axis : Point3
derived properties - an angle in degrees and a rotation axis
Operators:
<quat> + <quat>
<quat> - <quat>
<quat> * <quat_or_number>
<quat> / <number>
- <quat>
Quaternion algebra
<quat> * <matrix3>
Quaternion algebra using rotation portion of the matrix3
<quat> == <quat>
<quat> != <quat>
<quat> as <class>
quats can convert to Matrix3’s, Angleaxis’s, Eulerangle’s
 Quat Values 739

Methods:
copy <quat>
Creates a new copy of the quat value. For example:
newQuat = copy oldQuat

The new value contains a copy of the input quat value, and is independent of the input
quat value.
isIdentity <quat>
Returns true if the quaternion is equal to the identity quaternion (x=y=z=0.0; w=1.0).
normalize <quat>
Returns a normalized quat, dividing each term of the input quat by a scale factor such that
the resulting sum of the squares of all parts equals unity.
inverse <quat>
Returns the inverse of the quaternion (1/q).
conjugate <quat>
Returns the conjugate of a quaternion.
logN <quat>
Returns the natural logarithm of UNIT quaternion.
exp <quat>
Returns the exponentiated quaternion (where q.w=0).
slerp <start_quat> <end_quat> <number>
Returns a spherical linear interpolation of UNIT quaternions. As number goes from 0 to 1,
the returned value goes from start_quat to end_quat.
LnDif <p_quat> <q_quat>
Returns the “log difference” of two quaternions as:
logN ((inverse p_quat)*q_quat)

qCompA <prev_quat> <now_quat> <next_quat>

Compute a, the term used in Boehm-type interpolation:
a = now_quat * exp(-(1 / 4)*(logN((inverse now_quat)*next_quat)+
logN((inverse now_quat)*prev_quat)))

squad <p_quat> <a_quat> <b_quat> <q_quat> <number>

slerp (slerp p_quat q_quat number) \
(slerp a_quat b_quat number) \
(2*(1-number)*number)

qorthog <quat> <axis_point3>

Returns quat rotated by 180 degrees (quaternion space metric) about the specified axis
axis_point3.
transform <quat> <matrix3>
Returns the transformation of the specified quaternion by the specified matrix.
740 Chapter 9 | Values

squadrev <angle_number> <axis_point3> <start_quat> \

<start_tangent_quat> <end_tangent_quat> \
<end_quat> <number>
Returns quaternion interpolation for angles > 2PI where angle_number is angle of
rotation, and axis_point3 is axis of rotation. As number goes from 0 to 1, the returned
value goes from start_quat to end_quat.
random <quat> <quat>
Returns a random rotation between the two quats, using Slerp.
Related Methods:
quatToEuler <quat> order:<eulertype_integer>
eulerToQuat <eulerAngle> order:<eulertype_integer>
Convert between quat and euler angle values. The optional order parameter specifies the
order of application of the angles. If not specified, XYZ ordering is used. Its value can be
any of the following:
1 - XYZ
2 - XZY
3 - YZX
4 - YXZ
5 - ZXY
6 - ZYX
7 - XYX
8 - YZY
9 - ZXZ

getEulerQuatAngleRatio <quat1> <quat2> \

<eulerAngles1> <eulerAngles2> \
[angle:<eulertype_integer>]
When converting a series of quat values to eulerAngles values, it is possible for sign flips to
occur in the eulerAngles values. This is due to the fact that one single quat value can be
expressed through many different eulerAngles values. This flip can be detected by based
on the eulerAngles/quat ratio. The eulerAngles/quat ratio is the relation of the angle
difference in eulerAngles space to the angle difference in quat space. If this ratio is bigger
than PI the rotation between the two quat to eulerAngles conversions. This method
returns the eulerAngles/quat angle ratio between the two quat to eulerAngles conversions
as a float value. The actual detection of the flip is dependent on the amount of rotation in
between conversions. The smaller the amount of rotation, the more accurate the detection
is. The parameters to this method are:
quat1 and quat2 are the previous and current rotation values.
eulerAngles1 and eulerAngles2 are the previous and current converted
rotation angles.
 AngleAxis Values 741

The optional eulertype_integer parameter specifies the order of application of the

angles. If not specified, XYZ ordering is used. Its value can be any of the following:
1 - XYZ
2 - XZY
3 - YZX
4 - YXZ
5 - ZXY
6 - ZYX
7 - XYX
8 - YZY
9 – ZXZ

AngleAxis Values
The AngleAxis class provides a representation for orientation in 3D space using an angle in degrees
and a rotation axis. This class is similar to a quaternion, except that a normalized quaternion only
represents -PI to +PI rotation. Angles can be greater than 360 and so specify multiple revolutions,
unlike quaternions. Rotations follow the right-hand-rule.
Constructors:
angleaxis <degrees_float> <axis_point3>
<quat> as angleaxis
<eulerangle> as angleaxis
<matrix3> as angleaxis
extracts the rotation component as an angleaxis
Operators:
<angleaxis> == <angleaxis>
<angleaxis> != <angleaxis>
<angleaxis> as <class>
AngleAxis can convert to Matrix3’s, Quat’s, Eulerangle’s
Properties:
<angleaxis>.angle : Float
<angleaxis>.axis : Point3
<angleaxis>.numrevs : Integer

Methods:
copy <angleaxis>
Creates a new copy of the angleaxis value. For example:
newAngleAxis = copy oldAngleAxis

The new value contains a copy of the input angleaxis value, and is independent of the
input angleaxis value.
random <angleaxis> <angleaxis>
Random rotation in degrees, but uses quat Slerp, so loses multiple revolution angles.
742 Chapter 9 | Values

EulerAngles Values
The EulerAngles class provides a representation for orientation in 3D space using rotation angles in
degrees about each axis. Angles can be greater than 360 and so specify multiple revolutions.
Rotations follow the right-hand-rule.
Constructors:
eulerAngles <x_degrees> <y_degrees> <z_degrees>
<quat> as eulerAngles
<angleAxis> as eulerAngles
<matrix3> as eulerAngles
Extracts the rotation component as an eulerAngles.
Operators:
<eulerAngles> == <eulerAngles>
<eulerAngles> != <eulerAngles>
<eulerAngles> as <class>
eulerAngles can convert to Matrix3, Quat, angleAxis values
Properties:
<eulerAngles>.x : Float
<eulerAngles>.y : Float
<eulerAngles>.z : Float
Rotation about each primary axis in float degrees
Methods:
copy <eulerAngles>
Creates a new copy of the eulerAngles value. For example:
newEulerAngles = copy oldEulerAngles

The new value contains a copy of the input eulerAngles value, and is independent of the
input eulerAngles value.
random <eulerAngles> <eulerAngles>
Random rotation between the eulerAngles, but uses quat Slerp, so loses multiple
revolution angles.
 EulerAngles Values 743

quatToEuler <quat> order:<eulertype_integer>

eulerToQuat <eulerAngle> order:<eulertype_integer>
Convert between quat and euler angle values. The optional order parameter specifies the
order of application of the angles. If not specified, XYZ ordering is used. Its value can be
any of the following:
1 - XYZ
2 - XZY
3 - YZX
4 - YXZ
5 - ZXY
6 - ZYX
7 - XYX
8 - YZY
9 - ZXZ

getEulerQuatAngleRatio <quat1> <quat2> \

<eulerAngles1> <eulerAngles2> \
[angle:<eulertype_integer>]
When converting a series of quat values to eulerAngles values, it is possible for sign flips to
occur in the eulerAngles values. This is due to the fact that one single quat value can be
expressed through many different eulerAngles values. This flip can be detected by based
on the eulerAngles/quat ratio. The eulerAngles/quat ratio is the relation of the angle
difference in eulerAngles space to the angle difference in quat space. If this ratio is bigger
than PI the rotation between the two quat to eulerAngles conversions. This method
returns the eulerAngles/quat angle ratio between the two quat to eulerAngles conversions
as a float value. The actual detection of the flip is dependent on the amount of rotation in
between conversions. The smaller the amount of rotation, the more accurate the detection
is. The parameters to this method are:
quat1 and quat2 are the previous and current rotation values.
eulerAngles1 and eulerAngles2 are the previous and current converted
rotation angles.
The optional eulertype_integer specifies the order of application of the angles. If
not specified, XYZ ordering is used. Its value can be any of the following:
1 - XYZ
2 - XZY
3 - YZX
4 - YXZ
5 - ZXY
6 - ZYX
7 - XYX
8 - YZY
9 - ZXZ
744 Chapter 9 | Values

getEulerMatAngleRatio <matrix3_1> <matrix3_2> \

<eulerAngles1> <eulerAngles2> \
[angle:<eulertype_integer>]
This method parallels the getEulerQuatAngleRatio() method. This method is
identical to getEulerQuatAngleRatio() with the exception that matrix3 values are
passed rather than quat values.

Matrix3 Values
The Matrix3 class implements a 4x3 3D transformation matrix object. The transform matrix is a 3D
homogeneous matrix typically used to hold object coordinate systems and transformations.
Constructors:
matrix3 <row1_point3> <row2_point3> <row3_point3> <row4_point3>
matrix from row vectors
matrix3 0
zero matrix
matrix3 1
identity matrix
<quat> as matrix3
<angleaxis> as matrix3
<eulerangles> as matrix3
rotation matrices
rotateXMatrix <number> -- all angles in degrees
rotateYMatrix <number>
rotateZMatrix <number>
rotation matrices
transMatrix <point3>
translation matrix
scaleMatrix <point3>
scale matrix
rotateYPRMatrix <yaw_number> <pitch_number> <roll_number>
Returns a Matrix3 value for use as a rotation transformation by specifying yaw, pitch and
roll angles. All angles are in degrees.
matrixFromNormal <point3>
Returns a Matrix3 value with the normal specified by the given point as the Z axis. The
translation portion of the Matrix3 value will be [0,0,0]. The components of the scale
portion are the inverse of the values required to normalize the point3 value. For example,
MatrixFromNormal [0,0,1]
MatrixFromNormal [0,1,1]

will return
(matrix3 [1,0,0], [0,1,0], [0,0,1], [0,0,0])
(matrix3 [0,-0.707107,0.707107] [1.41421,0,0] [0,1,1] [0,0,0])
 Matrix3 Values 745

Operators:
<matrix3> + <matrix3>
<matrix3> - <matrix3>
<matrix3> * <matrix3>
<matrix3> as <class>
Matrix3’s can convert to Quat’s, AngleAxis, EulerAngles using the matrix’s rotation
component
Properties:
<matrix3>.row1 : Point3
<matrix3>.row2 : Point3
<matrix3>.row3 : Point3
<matrix3>.row4 : Point3
<matrix3>.translation : Point3
read/write access to rows. Row4 is the translation.
<matrix3>.rotationpart : Quat, read-only
<matrix3>.translationpart : Point3, read-only
<matrix3>.scalerotationpart : Quat, read-only
<matrix3>.scalepart : Point3, read-only
access to various transforms, with the remaining transforms zero-ed out.
<matrix3>.determinantsign : Integer, read-only
returns sign of the matrix’s determinant
Methods:
copy <matrix3>
Creates a new copy of the matrix3 value. For example:
newMatrix3 = copy oldMatrix3

The new value contains a copy of the input matrix3 value, and is independent of the input
matrix3 value.
isIdentity <matrix3>
Returns true if the matrix is equal to the identity matrix.
inverse <matrix3>
Returns the inverse of the matrix.
xformMat <transform_matrix3> <space_matrix3>
Returns the transform matrix transformed into a particular space. For example, say you
have a rotation you want to apply, but you want to perform the rotation in another
coordinate system. To do this, you typically transform into the space of the coordinate
system, then apply the transformation, and then transform out of that coordinate system.
This method transformats matrix transform_matrix3 into the space of matrix
space_matrix3. The resulting matrix3 value is calculated as space_matrix3 *
transform_matrix3 * inverse(space_matrix3).
746 Chapter 9 | Values

identity <matrix3> -- mapped function

Sets the input matrix or matrices to the identity matrix. If the parameter is a single matrix,
this function returns an identity matrix. If the parameter is an array of matrices, this
function returns the value OK. In both cases, the input matrix3 values are replaced with
the identity matrix.
zero <matrix3> -- mapped function
Sets the input matrix or matrices to the zero matrix. If the parameter is a single matrix, this
function returns an zero matrix. If the parameter is an array of matrices, this function
returns the value OK. In both cases, the input matrix3 values are replaced with the zero
matrix.
orthogonalize <matrix3> -- mapped function
Sets the input matrix or matrices to the an “unbiased” orthogonalization of the matrix. An
orthogonal matrix has an axis system where each axis is 90 degrees from the others (it’s
not skewed). If the parameter is a single matrix, this function returns the orthogonalized
matrix. If the parameter is an array of matrices, this function returns the value OK. In both
cases, the input matrix3 value(s) are replaced with the orthogonalized matrix value(s).
translate <matrix3> <point3> -- mapped function
Applies an incremental translation transformation to the input matrix or matrices. This is
equivalent to multiplying on the RIGHT by the transform. If the matrix3 parameter is a
single matrix, this function returns the transformed matrix. If the parameter is an array of
matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are
replaced with the transformed matrix value(s).
rotateX <matrix3> <number> -- mapped functions -- all angles in degrees
rotateY <matrix3> <number>
rotateZ <matrix3> <number>
rotate <matrix3> <quat>
Applies an incremental rotation transformation to the input matrix or matrices. This is
equivalent to multiplying on the RIGHT by the transform. If the matrix3 parameter is a
single matrix, this function returns the transformed matrix. If the parameter is an array of
matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are
replaced with the transformed matrix value(s).
scale <matrix3> <point3> [ <boolean> ] -- mapped function
Applies an incremental scale transformation to the input matrix or matrices. This is
equivalent to multiplying on the RIGHT by the transform. If <boolean> is true, the
translation component is scaled. If <boolean> is false the translation component is
unaffected. When 3ds max was originally written there was a bug in the code for this
method where the translation portion of the matrix was not being scaled. This meant that
when a matrix was scaled the bottom row was not scaled. Thus it would always scale about
the local origin of the object, but it would scale the world axes. When this bug was
discovered, dependencies existed in the code upon this bug. Thus it could not simply be
fixed because it would break the existing code that depended upon it working the
incorrect way. To correct this boolean parameter was added. If it is set to true, the
translation component will be scaled correctly. If not specified, the boolean defaults to
 Matrix3 Values 747

false, and the code behaves the old way. If the matrix3 parameter is a single matrix, this
function returns the transformed matrix. If the parameter is an array of matrices, this
function returns the value OK. In both cases, the input matrix3 value(s) are replaced with
the transformed matrix value(s).
preTranslate <matrix3> <point3> -- mapped function
Applies an incremental translation transformation to the input matrix or matrices. This is
equivalent to multiplying on the LEFT by the transform. If the matrix3 parameter is a
single matrix, this function returns the transformed matrix. If the parameter is an array of
matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are
replaced with the transformed matrix value(s).
preRotateX <matrix3> <number> -- mapped functions -- all angles in degrees
preRotateY <matrix3> <number>
preRotateZ <matrix3> <number>
preRotate <matrix3> <quat>
Applies an incremental rotation transformation to the input matrix or matrices. This is
equivalent to multiplying on the LEFT by the transform. If the matrix3 parameter is a
single matrix, this function returns the transformed matrix. If the parameter is an array of
matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are
replaced with the transformed matrix value(s).
preScale <matrix3> <point3> [ <boolean> ] -- mapped function
Applies an incremental scale transformation to the input matrix or matrices. This is
equivalent to multiplying on the LEFT by the transform. If <boolean> is true, the
translation component is scaled. If <boolean> is false the translation component is
unaffected. If not specified, the boolean defaults to false. If the matrix3 parameter is a
single matrix, this function returns the transformed matrix. If the parameter is an array of
matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are
replaced with the transformed matrix value(s).
Related Methods:
getEulerMatAngleRatio <matrix3_1> <matrix3_2> \
<eulerAngles1> <eulerAngles2> \
[angle:<eulertype_integer>]
When converting a series of matrix3 values to eulerAngles values, it is possible for sign
flips to occur in the eulerAngles values. This is due to the fact that one single matrix3
value can be expressed through many different eulerAngles values. This flip can be
detected by based on the eulerAngles/matrix3 ratio. The eulerAngles/matrix3 ratio is the
relation of the angle difference in eulerAngles space to the angle difference in matrix3
space. If this ratio is bigger than PI the rotation between the two matrix3 to eulerAngles
conversions. This method returns the eulerAngles/matrix3 Angle ratio between the two
matrix3 to eulerAngles conversions as a float value. The actual detection of the flip is
dependent on the amount of rotation in between conversions. The smaller the amount of
rotation, the more accurate the detection is. The parameters to this method are:
748 Chapter 9 | Values

matrix3_1 and matrix3_2 are the previous and current transform matrix values.
eulerAngles1 and eulerAngles2 are the previous and current converted
rotation angles.
The optional eulertype_integer specifies the order of application of the angles. If
not specified, XYZ ordering is used. Its value can be any of the following:
1 - XYZ
2 - XZY
3 - YZX
4 - YXZ
5 - ZXY
6 - ZYX
7 - XYX
8 - YZY
9 - ZXZ

BigMatrix Values, BigMatrixRowArray Values

The BigMatrix class implements an MxN matrix for situations and calculations where the usual 4x3
Matrix3 class is not adequate. The BigMatrixRowArray class implements an N element vector. Each
row in a BigMatrix value is a BigMatrixRowArray value. Only Float values can be stored in the
elements of a BigMatrixRowArray.
Constructors:
BigMatrix <rows> <columns>
Properties:
<BigMatrix>.rows : Integer, read-only
<BigMatrix>.columns : Integer, read-only
Operators:
<BigMatrix> + <BigMatrix> -- both BigMatrix values must have same size
<BigMatrix>[<int_row>] -- returns BigMatrixRowArray of indexed row
<BigMatrixRowArray>[<int_column>] -- returns float value of indexed column
<BigMatrixRowArray>[<int_column>] = <float_value> -- sets value in the indexed
column

Because accessors are themselves operands, these definitions are recursive, which means
that you can string accessors together:
<BigMatrix>[<int_row>][<int_column>] -- returns float value of indexed row and column
<BigMatrix>[<int_row>][<int_column>] = <float_value> -- sets value in the matrix
Methods:
invert <BigMatrix>
Inverts the matrix in place, i.e., the input BigMatrix itself is modified. The return value is
also the inverted matrix. Note that this method only works if this matrix is “square”, i.e. if
m = n.
 BigMatrix Values, BigMatrixRowArray Values 749

transpose <BigMatrix>
Returns the transpose of <BigMatrix>, i.e. result BigMatrix[i][j] =
BigMatrix[j][i].
clear <BigMatrix>
Frees all the elements and sets the matrix size to be 0x0
setSize <BigMatrix> <rows> <columns>
Deletes the current elements and sets the size of the matrix to rows x columns.
identity <BigMatrix> -- mapped function
If the number of rows and columns are equal, this method sets the matrix to the identity
(diagonal elements = 1, all other elements = 0). If the number of rows and columns are not
equal, it does nothing. If the parameter is an array of matrices, this function returns the
value OK. In both cases, the input BigMatrix value(s) are set to the identity.
Notes:
A BigMatrix object is a compound object, similar to an array of arrays. All of the BigMatrix methods
operate directly on the components of the input BigMatrix. As described in the Reference Assignment
(p. 653) topic, this can cause complications to occur if a BigMatrix object referenced by more than
one variable. If you assign a new value to an element of the matrix, or use any of the BigMatrix
methods, the same object is still referenced by the variables. This can be seen in the following
example.
Script:
bm1=bigmatrix 2 2
for i=1 to 2 do for j=1 to 2 do bm1[i][j]=random 0 10
bm2=bm1
invert bm1
bm2

Output:
#BigMatrix( -- result of line 1, contents of bm1
[0.00,0.00],
[0.00,0.00]
)
OK -- result of line 2
#BigMatrix( -- result of line 3, contents of bm2
[4.00,6.00],
[4.00,9.00]
)
#BigMatrix( -- result of line 4, contents of bm1
[0.75,-0.50],
[-0.33,0.33]
)
#BigMatrix( -- result of line 5, contents of bm2
[0.75,-0.50],
[-0.33,0.33]
)
750 Chapter 9 | Values

Box2 Values
The Box2 class describes a 2D rectangular region using integer coordinates. The Box2 class provides
methods that return individual coordinates of the box, scale and translate it, retrieve its center,
modify its size, and determine if points are inside the box. Box2 values are primarily used in the
viewport graphics methods described in the Viewport Drawing Methods (p. 1592) topic.
Constructors:
Box2 <x_integer> <y_integer> <w_integer> <h_integer>
Constructs a Box2 with the upper left corner at [x,y] with width w and height h.
Box2 <upperleft_point2> <lowerRight_point2>
Constructs a Box2 object from the specified corners.
Properties:
<Box2>.x : Integer
<Box2>.y : Integer
<Box2>.w : Integer
<Box2>.h : Integer
<Box2>.left : Integer, alias of x property
<Box2>.right : Integer
<Box2>.top : Integer, alias of y property
<Box2>.bottom : Integer
<Box2>.center : Point2, read-only
The right property is calculated as right = x + w – 1. The bottom property is
calculated as bottom = y + h – 1. Setting the right or bottom property will normally
change the w and h properties, respectively. However, if right is set less than left, the
right and left values will be swapped, and then the new value will be used as the left
value. Likewise, if bottom is set less than top, the bottom and top values will be swapped,
and then the new value will be used as the top value.
Operators:
<Box2> == <Box2>
<Box2> != <Box2>
Standard comparison operators. Two Box2 values are equal if all of their component values
are equal.
Methods:
scale <Box2> <float>
Scales the coordinates of the box about the center of the box.
translate <Box2> <point2>
Translates the coordinates of the box by the distance specified.
contains <Box2> <point2>
Determines if the point2 value is contained within the Box2. Returns true if the point is
inside the Box2 or on the Box2 edge; otherwise false.
rectify <Box2>
Adjusts the coordinates of the box such that top < bottom and left < right.
 Time Values 751

empty <Box2>
Sets the Box2 to a special “empty” value.
isEmpty <Box2>
Returns true if the Box2 contains the special “empty” value, false otherwise.

Time Data Values

The Time data value types are:
Time Values (p. 751)
Interval Values (p. 752)

Time Values
The Time class implements animation time in MAXScript. Time values reflect the properties of
animation time in 3ds max. Resolution is in ticks, with 4800 ticks per second. You can work with
time as ticks, frames, h.m.s, or normalized time.
You can intermix numbers and time values in time computations defined below. The rule is that
numbers are always interpreted as frame counts, with floating point numbers specifying fractional
frames. The numbers are always converted to tick-based time values internally and so have an
ultimate resolution of 4800 ticks per second.
You can do time arithmetic and comparisons using numbers as well as time values and convert
between time and (frame) numbers using the as operator. See also Time Literals (p. 662).
Literals:
[-]{<decimal_number>[m | s | f | t]}+ -- minutes/sec/frames/ticks
[-]{<digit>}:{<digit>}[.{<digit>}] -- SMPTE mins:secs.frame
[-]<decimal_number>n -- active segment normalized time

Example Literals:
2.5s -- 2.5 seconds
1m15s -- 1 minute 15 seconds
2m30s5f2t -- 2 minutes 30 seconds 5 frames 2 ticks
125f -- 125 frames
17.25f -- 17.25 frames
1f20t -- 1 frame 20 ticks
2:10.0 -- 2 minutes 10 seconds 0 frames (SMPTE)
0:0.29 -- 29 frames (SMPTE)
Constructor:
normTime <float> -- time from normal fraction

Properties:
<time>.ticks : Time as ticks
<time>.frame : Time as frames
<time>.normalized : Time as normalized fraction of active segment
752 Chapter 9 | Values

Operators:
<time> + <time>
<time> - <time>
- <time>
<time> * <number>
<time> / <number>
scale time
<time> == <time>
<time> != <time>
<time> > <time>
<time> >= <time>
<time> < <time>
<time> <= <time>
<time> as <class>
You can coerce a time to a Number - you get the time in ticks.
Methods:
random <time> <time>
abs <time>

Examples:
sliderTime = 30
t2 = n as time
if currentTime == 45 then ...

Some of the examples above refer to system global variables. See the 3ds max System Globals (p. 630)
topic for more details.

Interval Values
An Interval class represents an interval of time. It has two time value components, start and end.
The time values can be numbers or Times, numbers being interpreted as frame counts.
Constructor:
interval <start_time> <end_time>

Properties:
<interval>.start : Time
<interval>.end : Time
 Undefined Value 753

Examples:
t = animationRange.start + 5

orig_anim_range=animationRange -- store original animation range

animationRange=interval 0 100000 -- set real long animation range
-- assign script controller, controllers range is the current
-- animation range
ControlObj.scale.controller=scale_script()
-- assign a script to the controller
ControlObj.scale.controller.script = controlscript
-- reset animationRange back to original value
animationRange=orig_anim_range

Some of the examples above refer to system global variables. See the 3ds max System Globals (p. 630)
topic for more details.

Special Data Values

Undefined Value (p. 753)
Ok Value (p. 754)
Unsupplied Value (p. 754)
DontCollect Value (p. 754)

Undefined Value
The Undefined class implements the value used in uninitialized variables and array members. There
is one distinguished instance of the Undefined class in the reserved system variable undefined.
Constructor:
undefined

Examples:
-- check to see if MyLight has a target
if MyLight.target != undefined then
-- distance from light to target
dist=distance MyLight.pos MyLight.target.pos
else
-- distance from light to [0,0,0]
dist=length MyLight.pos

-- set CH_Hand1 to undefined so can test later to see if deleted

deleteChangeHandler CH_Hand1; CH_Hand1=undefined
754 Chapter 9 | Values

Ok Value
The Ok class implements the void value returned by some functions and expressions that don’t have
a meaningful value to return. There is one distinguished instance of the OK class in the reserved
system variable OK.

Unsupplied Value
The Unsupplied class implements the value used to initialize unsupplied keyword parameters to
functions. There is one distinguished instance of the Unsupplied class in the reserved system
variable unsupplied. You can test to see whether a caller has supplied an optional keyword
argument by comparing it with unsupplied.
Constructor:
unsupplied

Examples:
fn walk_tree obj parent: =
( if parent == unsupplied then
...
else
...
...
)

DontCollect Value
The dontCollect value is used in for loops to signal that the value is not to be collected. See For
Loop (p. 694) for details. dontCollect is a separate distinguished instance of the Undefined class,
and so will fail in the way the undefined value does if used in computations.
Constructor:
dontCollect

Examples:
-- collect all spheres with radius less than 5
little_spheres =
for i in $* collect
if classOf i == sphere and i.radius < 5 then i else dontCollect
 DontCollect Value 755

Bitmap Values
The Bitmap class provides storage of and low-level access to 3ds max bitmaps.
Bitmaps can be temporary objects that are resident only in memory, or they can be associated with
a file on disk. Those bitmaps associated with files have a non-null .fileName property and are
either load-only or save-only, but not both (this is with respect to file I/O; all bitmaps in memory
can have their pixels modified by the setPixel() functions). You make load-only bitmaps with the
openBitmap() and selectBitmap() functions. You make temporary or save-only bitmaps with
the bitmap() constructor, or with the render(), copy(), or getChannelAsMask() functions. To
make them savable, they must have a valid file name, supplied either on the constructor with a
fileName: parameter or by setting the .fileName property.
Constructors:
bitmap <width <height> [ filename:<filename_string> ] \
[ numframes:<integer> ] \
[ color:<color> ] \
[ gamma:<float> ] \
[ pixelAspect:<float> ]
Creates an empty bitmap. The bitmap value returned is a savable bitmap.
The filename: parameter allows you to set the name of the file the bitmap will be saved
to using the save method. Specifying an existing bitmap file name does not load the
contents of the bitmap file into the bitmap value.
The numframes: parameter allows you to create a multi-frame bitmap.
The color: parameter allows you to set the initial color of all pixels in the bitmap. For
example:
b = bitmap 320 240 color:white

The gamma: parameter allows you to set the gamma for the newly created bitmap. For
example:
b = bitmap 320 240 gamma:1.9
render camera:c to:b

The pixelAspect: parameter allows you to set the pixel aspect for the newly created
bitmap.
Note that it is not possible to change the gamma or pixel aspect of a bitmap once created,
though you can copy one bitmap into a newly created one that has a different gamma or
pixel aspect to achieve this effect.
openBitMap <filename_string>
Returns a bitmap value containing the contents of the specified bitmap file. If the specified
bitmap file does not exist, a runtime error is generated. The bitmap value returned is a
load-only bitmap.
756 Chapter 9 | Values

selectBitMap [ caption:<open_dialog_title_string> ]
This method displays a Image Input selection browser for the user to select a bitmap file.
Returns a bitmap value containing the contents of the selected bitmap file, or the value
undefined if the user presses Cancel in the browser. The bitmap value returned is a
load-only bitmap.
copy <bitmap>
Copies an existing bitmap, creating an unique instance of the bitmap. If the source bitmap
is load-only, the bitmap value returned is a temporary bitmap value, with a null filename
and just one frame. If the source is a multi-frame file, it snaps the current frame into the
new copy, which becomes frame 0.
Properties:
<bitmap>.filename : String
Lets you get or set the file name associated with the bitmap.
<bitmap>.palette : Array
Yields an array of 256 colors (a bug in the current 3ds max SDK prevents working with
paletted files of other than 256 entries). Take care accessing this array with colors indexes
retrieved by the getIndexedPixels() function described below, because these indexes
are 0-based and MAXScript array indexes are 1-based. Yields undefined if the bitmap is
not paletted. Currently you cannot create a paletted bitmap in MAXScript, however you
can read and write to a pre-existing paletted bitmap.
<bitmap>.frame : Integer
Get and set the current frame number in a multi-frame file. Setting this property is
permitted only on load-only bitmaps. The frame number is 0-based for inherently multi-
frame files, such as .avi and .mov.
<bitmap>.numframes : Integer
The number of frames in a multi-frame file, yields 1 for a single image file.
<bitmap>.height : Integer, read-only
Returns bitmap’s height in pixels.
<bitmap>.width : Integer, read-only
Returns bitmap’s width in pixels.
<bitmap>.gamma : Float, read-only
Returns bitmap’s gamma value.
<bitmap>.aspect : Float, read-only
Returns the bitmap’s pixel aspect. Note that this is the aspect of the pixel, not the aspect of
the bitmap image.
Methods:
display <bitmap>
Opens a virtual frame buffer (VFB) displaying the image. Changes to the bitmap are not
automatically displayed to the VFB. To update the VFB, you need to call this function
again. Setting the frame property does cause the VFB to update. Each bitmap has its own
VFB, i.e., if you display two different bitmaps, two VFBs will be displayed.
 DontCollect Value 757

unDisplay <bitmap>
Close the VFB associated with the bitmap if open.
save <bitmap> [frame:<integer>]
Saves current state of the bitmap. Make sure the file name has been set first. When saving
multi-frame image files, the effect of the frame: keyword parameter is different
depending on the type of output file. Inherently multi-frame files, such as .avi and .mov,
ignore the frame: parameter and always write to the next output file frame in sequence
on each save(); you cannot randomly write frames or rewrite frames already saved.
Saving image sequences (such as .bmp, jpg, .tga) requires supplying the frame: parameter
and causes the frame number to be appended to the output file name for each frame saved.
This effectively generates a sequence of image files suitable for building an IFL. The output
file remains open until you call close on the bitmap.
The save() function can only be called on a savable bitmap. You will get a runtime error
if you attempt to save a bitmap opened with openBitmap() or selectBitmap().
close <bitmap>
Closes the bitmap file associated with the bitmap if it is open for output. A bitmap file is
opened for output when you call save on the bitmap value the first time. If a VFB
associated with the bitmap is open, it will be closed. This function also frees all memory
allocated by the bitmap, including the internal pixel frame buffer. If you are generating
many bitmaps, say in a rendering loop, you can use the close() function to free these
often large amounts of memory, that won’t otherwise be released until the next garbage
collection.
copy <source_bitmap> <dest_bitmap>
Copies the source bitmap to the destination bitmap. If the size of the two bitmaps is
different, the image will be scaled to fit the destination bitmap.
gotoFrame <bitmap> <frame>
Position multi-frame file (avi, flc, etc.) to frame frame. This method is permitted only on
load-only bitmaps. The frame number is 0-based for inherently multi-frame files, such as
.avi and .mov. Updates VFB if open.
getPixels <bitmap> <coord_point2> <num_pixels>
Retrieve a sequence of pixels from a row in the bitmap as an array of color values. The
coord_point2 argument specifies the starting pixel coordinate with [0,0] at the top-left-
hand pixel. The .x component of the Point2 coordinate is the column, and the .y
component is the row. The sequence must come from one row only; you cannot retrieve a
sequence of pixels that spans multiple rows. Using any out of-bounds coordinates or
retrieving over row boundaries will fail and yield an empty array.
setPixels <bitmap> <coord_point2> <color_value_array>
Sets the sequence of pixels in a row in the bitmap starting at the Point2 coordinate to the
values in the given array. The .x component of the Point2 coordinate is the column, and
the .y component is the row. The number of pixels to set is taken from the size of the
array. As with getPixels(), you cannot set pixel sequences across a row boundary.
758 Chapter 9 | Values

getIndexedPixels <bitmap> <coord_point2> <num_pixels>

Retrieve a row of pixels as an array of palette index numbers. The coord_point2 argument
specifies the starting pixel coordinate with 0,0 at the top-left-hand pixel. The index
numbers are origin 0. Note that this is in keeping with indexed color conventions but not
MAXScript’s. Take care accessing any retrieved palette array using these numbers because
the retrieved palette is returned as a MAXScript array and these arrays use 1-based indexes.
You cannot get pixels sequences that cross row boundaries.
setIndexedPixels <bitmap> <coord_point2> <number_array>
Sets the row of pixels starting at the Point2 coordinate to the color indexes in the given
array. The number of pixels to set is taken from the size of the array. The color indexes are
zero-based. You cannot set pixels sequences that cross row boundaries.
getChannel <bitmap> <coord_point2> <chan_name>
Retrieves the g-buffer channel data for the named channel for the pixel specified by 2D
coordinate. The chan_name argument specifies the channel identifier, chosen from the
following:
#zDepth
#matID
#objectID
#UVCoords
#normal
#unClamped
#coverage
#node
#shaderColor
#shaderTransparency
#velocity
#weight

If the bitmap contains the requested channel, the returned value is always an array of
values, one for each layer present in the channel at that pixel, ordered from front to back.
If the bitmap does not contain the requested channel, the function returns the value
undefined. Typically, you get bitmaps containing channels by opening .rla files or using
the MAXScript render() function with the channels: parameter supplied. You will get
multiple values in the array if the front objects have any transparency. For example:
getChannel bm [x,y] #zDepth

might return:
#(-354.413, -354.467, -355.271, -1e+030)

indicating there is a front surface with non-zero transparency at depth -354.413, another
at -354.467 and a final one at -355.271. The –1e+30 value represents the background image
plane. You could retrieve the #node channel (if it was generated) to get the actual scene
objects at those depths, eg:
getChannel bm [x,y] #node
 DontCollect Value 759

might return:
#($Sphere:Sphere02 @ [-4.7,24.3,0.0], $Sphere:Sphere02 @ [-
4.7,24.3,0.0],$Sphere:Sphere01 @ [-8.3,56.2,5.7])

The type of values returned in the array depend of the channel, as follows:
#zDepth : <float>
#matID : <integer>
#objectID : <integer>
#UVCoords : <point2>
#normal : <point3>
#unClamped : <color>
#coverage : <float>
#node : <node>
#shaderColor : <color>
#shaderTransparency : <color>
#velocity : <point2>
#weight : <color>

See the 3ds max Software Development Kit Help file for information on the data stored in
the g-buffer channels.
getChannelAsMask <bitmap> <chan_name> [to:<bitmap>] \
[fileName:”filename_string”] [pixelAspect:<float>] \
[gamma:<float>] [layer:<integer>] [invert:<boolean>] \
[node:<node> | objectID:<integer> | matID:<integer>] \
[velocity:#angle | #magnitude] | [angle:<float>]
Builds and returns a separate 8-bit gray-level bitmap, suitable for use as a mask in
materials, maps, effects, and so on. This bitmap corresponds roughly to the display you see
in the visual frame buffer if you select a g-buffer channel to view. In addition, you can
cause this mask to be masked itself to a selected node, object ID or material ID. The
parameters are as follows:
<bitmap>
The source bitmap containing the source g-buffer channel data.
<chan_name>
The channel from which to generate a mask. The chan_name values are as described
for the getChannel() method. Note that the mask is a single 8 bit value while the
channel may be a complex value of some kind. In each case, a mapping to 8 bits is
performed. Unless noted differently below, this mapping is the same mapping as in
used by 3ds max to generate monochrome images in the Virtual Frame Buffer.
to:<bitmap>
Specifies an existing bitmap to write the mask into. Its width and height must match
the source bitmap.
fileName:”filename_string”
Specifies the file name associated with the generated bitmap.
gamma:<float>
Specifies the generated bitmap’s gamma value.
760 Chapter 9 | Values

pixelAspect:<float>
Specifies the generated bitmap’s pixel aspect. Note that this is the aspect of the pixel,
not the aspect of the bitmap image.
layer: <integer>
Specifies the channel layer of the source bitmap to extract data from. Defaults to 1.
invert:<boolean>
If true, inverts the generated bitmap. Defaults to false.
node:<node>
objectID:<integer>
matID:<integer>
Specifies a sub-mask. If one of these parameters is supplied, the generated mask is
clipped to contain data only in pixels where the given node, objectID or materialID is
visible. To use this sub-masking, you must ensure the #node, #objectID or #matID
channel is present in the source bitmap. Further, if the #coverage channel is present
in the source bitmap, the sub-mask is anti-aliased by the coverage data.
velocity:#angle | #magnitude
angle:<float>
These parameters can only be specified if the selected channel is #velocity. The
default velocity parameter value is #magnitude. These parameters control the
generated bitmap as follows:
velocity:#angle
Generated bitmap pixel values are proportional to angle of pixel movement
direction, with an angle of direction of 0 degrees (horizontal to the right)
mapping to a luminance value of 0, 180 degrees mapping to a luminance value of
127, and 360 degrees mapping to a luminance value of 255.
velocity:#magnitude
Generated bitmap pixel values are proportional to velocity magnitude. High
velocities are darker than low velocities.
angle:<float>
Generated bitmap pixel values are proportional to movement direction deviation
from the given angle, with a luminance value of 255 at the exact angle and falling
off to a luminance value of 0 at 10 degrees from the specified angle. The specified
angle is relative to 0 being horizontal to the right.
Related Methods:
setSilentMode <boolean>
Sets Silent mode on or off. If Silent mode is off, any errors occurring during bitmap input
or output will result in an error message dialog being displayed by the 3ds max bitmap I/O
routines. If Silent mode is on, error message dialogs are not displayed. Returns a boolean
signifying the prior Silent mode state.
The Silent mode state is an internal 3ds max state, and other 3ds max plug-ins can turn
this state on or off. It is recommended that if you use this method that you turn the state
on or off saving the return value, perform the bitmap input or output, and then restore the
state to its original value.
 DontCollect Value 761

silentMode()
Returns a boolean signifying the Silent mode state.
selectSaveBitMap [ caption:<open_dialog_title_string> ]
Displays a 3ds max bitmap save dialog and returns the fully-specified file path name as a
string. Returns undefined if the user cancels out of the bitmap save dialog.
freeSceneBitmaps()
Frees up all the memory used by the image file bitmap caches. This is useful if memory is
fragmented with a lot of different bitmaps and you want to have just the ones currently
active reloaded.
getBitmapOpenFileName caption:<title> filename:<seed_filename_string>
getBitmapSaveFileName caption:<title> filename:<seed_filename_string>
Displays the bitmap file selection dialog. Both functions return a fully-specified file path
name or undefined if the user cancels out. If an existing file name is selected using the
getBitmapSaveFileName() function, a File Exists/Confirm Overwrite dialog will be
displayed. Note: The getBitmapOpenFileName() function does not require that an existing
file name be selected - i.e., a file name is returned if the user types a file name that does not
exist. If necessary, you should check the file name that is returned to ensure the file exists.
Notes:
When you open a bitmap file, an entire frame is loaded into memory. When you are finished
processing a bitmap, it is a good idea to either call close() on the bitmap or assign the value
undefined to the variable storing the bitmap value, and then manually run garbage collection
(gc()), so that it’s memory can be released. Another technique for conserving memory when using
the render() or getChannelAsMask() functions repeatedly is to use the to:<bitmap> keyword
argument which allows those functions to overwrite an existing bitmap’s pixel image with the new
rendering or mask.
There currently is no access to the properties associated with the bitmap output plug-ins. This means
that you cannot set the codec used for .avi files, nor the setup parameters for .rla and .tga files. The
properties used are the properties that were last used when saving that file type in 3ds max.
Examples:
The following script shows how to properly create and save a multi-frame image file.
762 Chapter 9 | Values

Script:
theTeapot=teapot() -- something to render
animate on at time 10 \ -- set animate and time context
rotate theTeapot 180 z_axis -- rotate the teapot
cam=targetcamera pos:[200,0,100] \ -- camera pointed at teapot
target:theTeapot
renderFrames=#{1,3,5..12} -- specify frames to render
b=bitmap 160 120 filename:”c:\\t.avi” -- create a new bitmap
for i = 1 to renderFrames.count do -- loop though renderFrames
( if renderFrames[i] then -- if supposed to render frame...
( at time i -- set time context
render 160 120 camera:cam to:b -- render to bitmap frame
save b -- save each frame as you advance
) -- if you save AFTER the loop,
-- just the last frame is saved.
)
close b -- close the output file. This will
-- also get rid of the reference to
-- the bitmap value and free its
-- memory.

Output:
$Teapot:Teapot01 @ [0,0,0] -- result of line 1
OK -- result of lines 2 and 3
$Target_Camera:Camera01 @ [200,0,100] -- result of lines 4 and 5
#{1, 3, 5..12} -- result of line 6
BitMap:c:\t.avi -- result of line 7
OK -- result of for loop, lines 8 to 15
OK -- result of line 16

The following script reads a bitmap file, and outputs a script to Listener that implements a function
that will recreate the same bitmap. This function can then be copied into your script. This is useful
for building button images in MAXScript, so that you don’t need to distribute bitmap files along
with your script.
Script:
(
b=selectbitmap() -- open image file browser
bname=”bitmap_”+(getfilenamefile b.filename) -- build name from filename
w=b.width -- get properties of bitmap
h=b.height
format “----------\nfn load_% = (\n” bname -- start defining function
format “local %=bitmap % %\n” bname w h -- create bitmap in function
-- write out a function that unpacks an integer into a pixel color
format “fn unpack val = for p in val collect (r=p/256^2; g=p/256-r*256; b=mod p
256; color r g b)\n”
for r=0 to h-1 do -- for each row in the bitmap
-- have function write the column of pixels to the bitmap
( format “setpixels % [0,%] (unpack #(” bname r
pixels=getpixels b [0,r] w -- read in the column of pixels
for c=1 to w do -- loop through each pixel
 FileStream Values 763

( p=pixels[c] -- get the pixel

-- pack the pixel into an integer and write it out
format “%” (((p.r as integer)*256+(p.g as integer))*256+(p.b as integer))
if c != w then -- if not at end of data
format “, “ -- write a comma
else
format “))\n” -- else close out the line
)
)
format “return %\n” bname -- function returns the bitmap
format “)\n----------\n” -- finish off function definition
)

Output:
----------
fn load_bitmap_convert = (
local bitmap_convert=bitmap 4 4
fn unpack val = for p in val collect (r=p/256^2; g=p/256-r*256; b=mod p 256; color
r g b)
setpixels bitmap_convert [0,0] (unpack #(12632256, 12632256, 12632256, 12632256))
setpixels bitmap_convert [0,1] (unpack #(255, 255, 255, 255))
setpixels bitmap_convert [0,2] (unpack #(255, 255, 255, 255))
setpixels bitmap_convert [0,3] (unpack #(255, 12632256, 12632256, 12632256))
return bitmap_convert
)
----------

Also see the example in the Point3 Values (p. 731) topic for another usage of class Bitmap.

Stream Values
Stream values are used to format and hold character data. You can read and write character data to
Stream values. The types of Stream values are:
FileStream Values (p. 763)
StringStream Values (p. 766)
WindowStream Values (p. 767)

FileStream Values
A FileStream class implements text file input and output in MAXScript. A FileStream value
represents an open text file in MAXScript. Text file I/O is performed by calling functions on the
FileStream value.
Constructors:
createFile <filename_string>
creates a new file and returns a <filestream> value. If the specified file cannot be
created, the value undefined is returned.
764 Chapter 9 | Values

openFile <filename_string> [ mode:<mode_string> ]

opens an existing file and returns a <filestream> value. If the specified file does not
exist, the value undefined is returned. The optional mode_string can be “a” to mean
open an existing file for append output, or “r” to mean open file read-only.
openEncryptedFile <filename> <key>
opens the encrypted file using the given integer key and returns a FileStream value that
you can then do read calls on, exactly as you can on FileStreams returned from the
openFile() function. See the Encrypted Files (p. 1647) topic for details on encrypted files.
Methods:
readLine <filestream>
read next line, return as string
readChar <filestream>
read next char, return as string
readChars <filestream> <char_count>
reads the specified number of characters and returns them in a string.
readDelimitedString <filestream> <string>
takes a delimiter character (as a string) and reads in characters until the delimiter is found
(or end-of-file is reached) and returns the characters in a string.
skipToString <filestream> <string>
takes a character string and scans forward in the file until it finds an occurrence of the
string and positions the file just after that string. If the string is not found, the function
returns the value undefined.
skipToNextLine <filestream>
positions the input file at the beginning of the next line
filePos <filestream>
retrieve the current offset into the file
seek <filestream> <integer>
position the file at the given offset so that subsequent I/O will start there.
eof <filestream>
return true if there is no more data in the file, false otherwise.
flush <filestream>
ensure all output to file is on disk, flushes the memory buffers.
close <filestream>
flushes the memory buffers and closes the file
For the following methods, see the description of the execute() method in the String Values (p. 722)
topic for information on the scope of variables used in the evaluated expressions.
readValue <filestream>
read and evaluate the next MAXScript <operand> from the file
readExpr <filestream>
read and evaluate the next MAXScript <expr> from the file
 FileStream Values 765

execute <filestream>
read and evaluate all the expressions left in the file.
The differences between the above methods can be seen in the following example. In this
example, a stringstream value is created that contains a string containing two expressions
– random 0. 1. and random red blue. The readValue, readExpr, and execute
methods are then used with the stringstream as the argument.
Script:
s=stringstream “random 0. 1.;random red blue”
readvalue s -- read and evaluate the first value
readvalue s -- read and evaluate the second value
seek s 0 -- position at beginning of stringstream
readexpr s -- read and evaluate the first expression
readexpr s -- read and evaluate the second expression
seek s 0 -- position at beginning of stringstream
execute s -- evaluate all expressions

Output:
StringStream:”random 0. 1.;random red blue” -- result line 1
random() -- result line 2 (evaluated “random”)
0.0 -- result line 3 (evaluated “0.”)
OK -- result line 4
0.448042 -- result line 5 (evaluated “random 0. 1.”)
(color 86.476 0 163.24) -- result line 6 (evaluated “random red blue”)
OK -- result line 7
(color 30.2417 0 143.636) -- result line 7 (evaluated all expressions,
-- returns result of last expression)

Associated Methods:
print <value> to: <filestream>
format <fmt_string> { <value> } to: <filestream>

See the Value Common Properties, Operators, and Methods (p. 714) topic for a description of
these methods.

See also
External File Methods (p. 1645)
File Name Parsing (p. 1644)
Standard Open and Save File Dialogs (p. 1643)
766 Chapter 9 | Values

StringStream Values
The StringStream class allows you to construct and parse strings using all the text file I/O functions.
For example, you can set up a StringStream and build it up by performing prints and formats to it,
just as you would to a text file. Conversely, you can convert a String into a StringStream and then
work through it using functions like readLine(), readValue(), skipToString(), etc. Since
Strings are easily converted to and from StringStreams, this is often a convenient way to work on
large, complex strings.
The StringStream class can be used in conjunction with the AppData accessing functions for storing
and retrieving large and complex amounts of script-generated data permanently within a 3ds max
scene file.
Constructors:
stringStream <initial_string>
<string> as stringStream
convert existing String to StringStream.
See also the String Literals (p. 660) and String Values (p. 722) topics.
Operators:
<stringstream> as string
convert StringStream to a String
Methods:
copy <stringstream>
create a separate copy of the StringStream
Associated Methods:
print <value> to:<stringstream>
format “<fmt_string>“ {values} to:<stringstream>
The print() and format() functions provide a way to build up a StringStream a piece at
a time. As with text file output, each call to print or format appends to existing text, the
StringStream dynamically grows as needed. Note that you can reposition output streaming
using the seek() function documented below.
The following functions are identical to the text file input functions available for text FileStream
values. See the FileStream Values (p. 763) class documentation for details. When called on
StringStream instances, they read progressively through the string extracting successive values and
lines and characters, etc.
readValue <stringstream>
readExpr <stringstream>
readLine <stringstream>
readChar <stringstream>
readChars <stringstream> <number>
readDelimitedString <stringstream> <string>
skipToString <stringstream> <string>
skipToNextLine <stringstream>
execute <stringstream>
 WindowStream Values 767

filePos <stringstream>
seek <stringstream> <pos>
eof <stringstream>
close <stringstream>
flush <stringstream>

The close() and flush() functions are provided for consistency with file I/O but are not
necessary for StringStreams and do nothing if called.

WindowStream Values
The WindowStream class allows you to output strings to a script Editor window. This is useful for
directing output to a separate window for ease of inspection, editing, or later saving to a file.
Constructors:
newScript()
Opens an empty script Editor window and returns a WindowStream value.
Associated Methods:
print <value> to:<windowstream>
format “<fmt_string>“ {values} to:<windowstream>
Output to a WindowStream is inserted at the current cursor position in that window.
Notes:
When using the format() function with a WindowStream, a new line in the Editor window is not
displayed until an end-of-line character (“\n”)is output.
Examples:
debug = newScript()
...
print $foo to:debug
...
format “name is %\n” obj.name to:debug

MAXKey Values
Certain controllers (keyframeable controllers) store their animation values as keys. As seen by
MAXScript, keys are stored in a MAXKeyArray. The MAXKeyArray for a keyframeable controller is
accessed via the .keys property of the controller.
For more information on MAXKeyArrays, see the MAXKeyArray Values (p. 793) topic.

See also
MAXKey Common Properties, Operators, and Methods (p. 768)
Working with MAXKey Values (p. 769)
768 Chapter 9 | Values

MAXKey Common Properties, Operators, and Methods

Constructor:
addNewKey <controller> <time> [ #select ] [ #interpolate ]
Adds a new key to the controller track at the time specified. The new key is also selected in
the track view if the #select optional argument is specified. The value for the new key is
taken from the previous key, unless the #interpolate argument is specified in which
case the value is the interpolated controller value at that time.
getKey <controller> <index_integer>
Returns the indexed key as a MAXKey instance.
<key_array>[<index_integer>]
where <key_array> is:
<controller>.keys
<node>.<animatable_property>.keys

Properties:
For keys associated with all keyframeable controller types, the following properties are accessible:
<key>.time Time -- time value or number (interpreted as frames)
<key>.selected Boolean -- specifies whether the key is selected. Read/write
access.

The .time property is read-only for the keys for some controllers, and read/write for the keys of
other controllers. The controller type description specifies whether the .time property is read-only
or read/write. For controllers where the key .time property is read/write, the following properties
are also available:
<key>.value varies -- class determined by its containing controller

Methods:
copy <key>
Creates a copy of the key value. This copy is not independent of the original key, as a key
value always references a key in a controller. This method exists primarily to support
copying of arrays.
The keys on Bézier, TCB, and Barycentric Morph controllers have additional properties and
methods. See the Bezier Controller Keys (p. 1310), TCB Controller Keys (p. 1335), and Barycentric Morph
Controller Keys (p. 1308) topics for details.

See also
MAXKeyArray Values (p. 793)
Controller Common Properties, Operators, and Methods (p. 1289)
Value Common Properties, Operators, and Methods (p. 714)
 Working with MAXKey Values 769

Working with MAXKey Values

Changing the .time property of a key may cause it to go out of time order relative to the other keys
in the controller. You must call the sortKeys() function on the controller or associated
MAXKeyArray once all key time manipulations of this kind is complete so that animation will
perform correctly.
The class of a key’s value property is determined by the controller it is in, for example, a
linear_float key has a float .value, a tcb_rotation key has a quaternion .value, etc. The
properties are all settable and support the math-assignment operators and nested-property access.
Here are some examples:
$foo.pos.keys[2].time += 20f -- change time of single key
$foo.pos.keys.time += 20f -- change time of all keys
$box1.uvw_map.center.keys[2].value.x += 20
for k in $baz.bend.angle.keys do k.value *= 1.1

In some cases, the actual value stored in a key is not the value shown in the command panels, shown
in Track View, the value returned by the .value property of the key, or the value returned when
accessing the property to which the key’s controller is assigned. Instead, a scaling factor is applied
to the key’s value before the value is made “visible”. For example, percentages are normally
displayed with a range of 0-100, rotation angles are in degrees, colors are [0-255,0-255,0-255]. The
unscaled key values for percentages are normally in a range of 0-1, rotation angles in radians, and
colors are [0-1,0-1,0-1].
In the description of properties for each class, the scaling factor, if any, is identified for each property.
Take for example the following properties for the PArray class:
<PArray>.X_Spin_Vector Float default: 1.0 -- animatable
<PArray>.Spin_Time_Variation Float default: 0.0 -- animatable, percentage
<PArray>.Spin_Phase Float default: 0.0 -- animatable, angle
<PArray>.viewPercent Float default: 10.0 -- percentage

The .X_Spin_Vector property does not apply any scaling to its controller keys. The
.Spin_Time_Variation property applies percentage scaling to its controller keys (displayed as
percentage, stored as fraction). The .Spin_Phase property applies angle scaling to its controller
keys (displayed as degrees, stored as radians). The .viewPercent property is stored internally with
a percentage scaling factor, but since this property is not animatable, this scaling it invisible to
MAXScript.
Normally this scaling is not of concern when programming in MAXScript, but there are two cases
where it must be taken into account. The first is when using script controllers, and is described in
the Script Controllers (p. 1329) topic.
770 Chapter 9 | Values

The second case is when one controller is applied as the controller for two or more properties. The
scaling is an attribute of the animatable property, not the controller, so in (the admittedly rare)
situations in which a controller is shared by several animatables that have different scaling,
unexpected results will occur if you do not take into account the scaling factor. An example of this
is shown in the following script, where the same controller is shared between three differently scaled
properties.
Script:
obj=PArray()
cont=bezier_float()
obj.X_Spin_Vector.controller=cont
obj.Spin_Time_Variation.controller=cont
obj.Spin_Phase.controller=cont
obj.X_Spin_Vector=1
obj.X_Spin_Vector -- no scaling
obj.Spin_Time_Variation -- percentage
obj.Spin_Phase -- angle

Output:
$PArray:PArray03 @ [0,0,0] -- result line 1
Controller:Bezier_Float -- result line 2
Controller:Bezier_Float -- result line 3
Controller:Bezier_Float -- result line 4
Controller:Bezier_Float -- result line 5
1 -- result line 6
1.0 -- result line 7, unscaled
100.0 -- result line 8, percentage scaled, 1 = 100%
57.2958 -- result line 9, angle scaled, 1 radian = 57.2958
degrees

If you do assign the same controller to properties with different scaling factors, you should take care
to access the .value property through the correct animatable property - this provides a scaling
context for the access operation.

ArrayParameter Values
Certain plug-ins in 3ds max store parameter data in a form that is accessible by MAXScript as
ArrayParameters. As such, you can access the parameter data by index and iterate over the
parameter data.
Constructors:
<MAXWrapper>.parameter
Where the parameter contains an ArrayParameter.
Properties:
<ArrayParameter>.count
Returns the number of values in the ArrayParameter. Read-only in most cases, with
exceptions noted in the MAXWrapper object description where an adjustable
ArrayParameter is used.
 Working with MAXKey Values 771

Operators:
<ArrayParameter>[<integer>]
Returns element of ArrayParameter. Indexes start at 1.
<ArrayParameter>[<integer>] = <value>
Sets element of ArrayParameter to value.
Notes:
Each ArrayParameter can only contain data of a certain type (for example, Float), or a controller that
matches that data type. The showProperties() function indicates these array parameters as
<type> array, for example, int array, texmap array, etc.
A plug-in can also define parameter names which point to specific entries in one of its
ArrayParameters. For example, mapAmounts is a property of Standard materials containing an
ArrayParameter. Each element in this ArrayParameter contains the map amount for one of the map
channels. For easier access in a script, the Standard .ambientMapAmount property is provided as an
alias for mapAmounts[1] (along with aliases for all the other common maps). You can access the
controller for the ambientMapAmount alias either via the .controller property on the alias or on
the .mapAmounts[1] property. For example, either:
$foo.material.ambientMapAmount.controller

or
$foo.material.mapAmounts[1].controller

will get the controller on the ambient map amount material property.
Examples:
The following script shows the use of showProperties() to show the data type for elements of
ArrayParameters, access to ArrayParameter elements, and a case of a plug-in defining parameter
names which point to a specific entry in one of its ArrayParameters.
Script:
m=CompositeMaterial() -- create a Composite material
showproperties m -- show the properties for the material
m.amount -- show value of parameter amount
m.amount[1] *= .5 -- reduce the value for one element
m=standard() -- create a Standard material
showproperties m -- show it’s properties
m.ambientMapAmount=13 -- set the value for one element via its alias
m.mapAmounts[1] -- and show the element was changed
772 Chapter 9 | Values

Output:
compositematerial:Composite -- result line 1
.materialList (Material : material array -- output line 2
.mixType (Composite Type) : int array -- ArrayParameter elements are
integer
.mapEnables (Map Enable) : bool array -- ArrayParameter elements are
boolean
.amount : float array -- ArrayParameter elements are
float
OK -- result line 2
#(100, 100, 100, 100, 100, 100, 100, 100, 100, 100) -- result line 3
50.0 -- result line 4
Standardmaterial:Standard -- result line 5
.mapEnables (Map Enables) : bool array -- pruned output line 6
.maps : texmap array
.mapAmounts (Map Amounts) : percent array
.ambientMap (alias for maps[0])
.ambientMapAmount (alias for mapAmounts[0])
.ambientMapEnable (alias for mapEnables[0])
.bumpMap (alias for maps[8])
.bumpMapAmount (alias for mapAmounts[8])
.bumpMapEnable (alias for mapEnables[8])
13 -- result line 7
13.0 -- result line 8
Chapter 10: Collections

Many of the values you work with in MAXScript are sequenced collections, notably arrays, wild-card
pathname selections, and the built-in object sets. In the manner of most operating system shell
command languages, MAXScript will automatically apply appropriate operations to each of the
members in these target collections.
Examples:
hide $lights/key* -- hide all the ‘key’ lights in the scene
$box*.position = [0,0,0] -- recenter all boxes
delete dead_objects -- delete all the objects in the array
-- ‘dead_objects’
obj.pos.keys.intangent=#fast -- set in tangent to fast for all obj’s position keys
lights.value *= 0.8 -- turn down all the lights 20%

MAXScript determines whether to perform a mapped operation by looking at the first argument to
a function or the target in a property assignment to see if it is a sequenced collection. In the case of
a function call, it also looks to see if the function is of the appropriate kind, evaluates all the other
argument expressions once only. MAXScript then calls the function on each of the members of the
first argument collection passing along the other evaluated arguments. In the case of a property
assignment, it evaluates the right-hand-expression once only and assigns the value to the named
property of each of the elements in the target value collection.
This means that every element in the collection must be a valid target for the function or have the
named property in question. If MAXScript comes across an inappropriate target it will report an error
and stop the automatic operation.
Except for certain common properties, MAXScript currently only allows automatic collection
mapping of property assignment one level deep. For example, the following will perform collection
mapping across the objects ObjectSet:
objects.pos = [0,0,0] -- move all objects to world center
774 Chapter 10 | Collections

If the last level specified is one of the following component names, the automatic collection
mapping is performed on the preceeding property:
.angle
.b
.blue
.axis
.controller
.g
.green
.isAnimated
.keys
.r
.red
.track
.x
.x_rotation
.y
.y_rotation
.z
.z_rotation

For example:
objects.pos.z = 0.0 -- move all objects to world XY plane

This behavior of calling a function on all the elements of a collection is known as mapping in
computer science. In the description of each collection type, you will find those kinds of sequenced
collections that can be mapped over identified as mappable. In the descriptions of the various
functions and operators throughout this document, those that act on each element in a collection
are labeled mapped. In general, the functions that are mapped are those that have some side-effect
on the value they take, such as moves, and deletes and hides. Others, like the test function
isHidden(), are not mapped because it would be pointless.
All mapped functions defined by MAXScript, such as copy(), delete(), or move(), take an
optional last argument, #noMap. This causes the functions not to be mapped when called on
collection arguments such as arrays. When used with copy() on arrays in particular, this will return
a top-level copy of the array itself and not perform an individual copy() on each element of
the array.
You can make your own mapped scripted functions by preceding the function definition with the
reserved word mapped, for example:
mapped function rand_color x = (x.wireColor = random black white)

This causes such functions to be automatically called repeatedly on the elements of a collection if a
collection is given as the first argument to the function. The #noMap argument is not applicable to
user-written functions.
 775

As described in the For Loop (p. 694) topic, a for loop can be set up to iterate through a collection
set assigning successive elements in the collection to the loop value each time through the loop. For
loops can also be set up to return an array collection set as its result.
Examples:
for item in table1 do x = x + item.height -- sequence an array

bigones = for obj in $box* -- you can sequence pathnames!

where obj.height > 100 collect obj -- collect the big boxes
-- into an array

When iterating through a collection set using a for loop, or when passing a collection to a mapped
function, care must be taken not to reorder or remove elements in the collection set within the for
loop or function. Take for an example a script that is supposed to convert all of the selected splines
into NURBS curves. Two scripts that do not execute properly are:
for obj in selection do ( convertToNURBSCurve obj)
convertToNURBSCurve selection

The reason neither of these lines execute properly is that the convertToNURBSCurve() function
clears the current selection. So only the first spline is passed to convertToNURBSCurve() and
converted. Since convertToNURBSCurve() is a built-in function, there is no way to modify this
behavior. To get around this problem, you need to first “snapshot” the selection collection set as an
array using the as operator, or use the getCurrentSelection() function, which returns the
current selection set as an array. Two scripts that execute properly are:
for obj in (selection as array) do ( convertToNURBSCurve obj)
convertToNURBSCurve (getCurrentSelection())

Collection Types
Array Values (p. 776)
PathName Values (p. 780)
ObjectSet Values (p. 781)
SelectionSet Values (p. 785)
SelectionSetArray Values (p. 783)
NodeChildrenArray Values (p. 785)
VertexSelection Values (p. 786)
FaceSelection Values (p. 788)
EdgeSelection Values (p. 790)
776 Chapter 10 | Collections

KeyArray Values (p. 793)

MAXNoteKeyArray Values (p. 794)
ModifierArray Values (p. 794)
MaterialLibrary Values (p. 795)
NURBSSet Values (p. 797)

Array Values
An array is a variable length indexable sequence of values. The values in an array can be of any type.
Array values are mappable.
Literals:
#(<value>, <value>, ...)
#() -- an empty array
See also Array Literals (p. 666).
Constructors:
<collection> as array
Convert collection to an array.
Properties:
<array>.count : Integer, read-only
Returns number of elements in array.
Operators:
<array>[<integer>]
Returns element of array. Indexes start at 1.
<array>[<integer>] = <value>
Sets element of array to value, growing array as necessary.
<array> + <collection>
Like join except a completely new array is constructed containing all the elements of the
first and second operands
For example:
a = #(1,2,3,4)
join a #(5,6,7,8)
(cameras as array) + lights
props = getPropNames Node
join props getPropNames (classOf $foo)
join props getPropNames $foo $dynamicOnly
sort props
 Array Values 777

Methods:
append <array> <value>
Append value to array, growing it as necessary.
copy <array> [#noMap] -- mapped
Creates a copy of all the elements in the array. Returns a value of OK. If #noMap is specified,
the copy made is what is called a shallow copy - only a copy of the upper-level value itself
(that is, the array value) is created. Copies aren’t made of values stored in the array, rather
a reference to the same value is stored in both array values.
deleteItem <array> <number>
Delete element indexed by number from array, shrinking it in size by 1.
join <array> <collection>
Appends all the elements of the second argument to the array (first) argument.
sort <array>
Sorts the elements of the array into ascending order. All the elements must be comparable.
findItem <array> <value>
Does a MAXScript ‘==’ comparison between elements in the array and the target object
and then returns the index of the first occurrence of the given value in the array or zero if
the value is not in the array.
Values such as Point3s and Strings match if they have the same contents.
insertItem <value> <array> <integer>
Inserts the value at the specified index in the array, growing the array if necessary
qsort <array> <function> [start:<integer>] [end:<integer>] [user-defined key args
passed to function]
Sorts the array using the specified function for element-by-element comparison. The
comparison function must take 2 values as arguments, and return a number < 0 if the first
value is less than thesecond value, 0 if the values are equivalent, and a number > 0 if the
first value is greater than the second value. The entire array is sorted unless a start or end
value is specified.
For example, the following script generates 10 random positions, and then sorts the
positions based on their distance from [0,0,0]:
positions=for i=1 to 10 collect (random [0,0,0] [100,100,0])
qsort positions (fn distFrom0 v1 v2 = (length v1)-(length v2))
778 Chapter 10 | Collections

All key arguments are now passed to the comparison function. This allows you to do
things like an indexed sort:
fn compareFN v1 v2 valArray: =
(local v1i = valArray[v1]
local v2i = valArray[v2]
(length v1i)-(length v2i)
)
positions=for i=1 to 10 collect (random [0,0,0] [100,100,0])
indexArray = for i = 1 to positions.count collect i
qsort indexArray compareFN valArray:positions
for i = 1 to positions.count do print positions[indexArray[i]]

amin ( <array> | {value} )

Returns minimum value of items in the array or of the argument values. If the array size is
zero orno arguments are specified, the value undefined is returned. Examples:
myMin1 = amin #(5,1,4,2,8)
myMin2 = amin 5 1 4 2 8

amax ( <array> | {value} )

Returns maximum value of items in the array or of the argument values. If the array size is
zero orno arguments are specified, the value undefined is returned.
Notes:
As described in the Reference Assignment (p. 653) topic, the elements in an array are stored by
reference rather than by value. When you operate directly on array elements, and the reference to
the array is stored in more than one place, unexpected results may occur. An example of this is
shown in the following script.
Script:
RandomSets=#() -- create array
RandomSet=#() -- create array
for i=1 to 3 do -- loop i
( for j=1 to 3 do -- for each i loop j
RandomSet[j]=random 1 100 -- set array element to random value
print RandomSet #nomap -- print array of random values
RandomSets[i]=RandomSet -- store random value array in array
)
print RandomSets -- print array of arrays of random values

Output:
#() -- result of line 1
#() -- result of line 2
#(33, 47, 31) -- output from line 6, i=1
#(4, 52, 39) -- output from line 6, i=2
#(52, 36, 23) -- output from line 6, i=3
OK -- result of for loop, lines 3 to 8
#(52, 36, 23) -- 3 lines of output from line 7
#(52, 36, 23)
#(52, 36, 23)
OK -- result of line 9
 Array Values 779

As can be seen in the output lines 7 to 9, all the elements of array RandomSets contain the same
values, which is not the result as expected from the output shown on lines 3 to 5. The reason the
same values are stored in each element of RandomSets is only one array value is actually ever created
for RandomSet (in line 2), and line 5 of the script is only changing the elements of that array value.
Thus each element of RandomSets is actually pointing at the exact same value. The easiest fix for
the above script is to move line 2 into the for i loop expression, thereby creating a new array value
which will then be stored in RandomSets.
Script:
RandomSets=#()
for i=1 to 3 do
( RandomSet=#() -- create a new array value for RandomSet
for j=1 to 3 do
RandomSet[j]=random 1 100
print RandomSet #nomap
RandomSets[i]=RandomSet
)
print RandomSets

Output:
#()
#(89, 27, 88)
#(87, 87, 10)
#(74, 27, 64)
OK
#(89, 27, 88)
#(87, 87, 10)
#(74, 27, 64)
OK

You can convert object sets and wild-card pathnames to arrays using the as operator. This has the
effect of taking a “snapshot” into the array of the current objects in the set or those matched by the
pathname, so that you can then later work on that collection of objects without worrying if the set
or match has changed. This is similar to named selection sets in the 3ds max user interface, and can
be used, for example, to keep track of selections as you work interactively with MAXScript. If the
user deletes from the scene any of the objects in the array, you will get an error if you try to map
operations over the array.
Examples:
sel1 = selection as array
boxes_at_load = $box* as array
snap_children = $torso...* as array
original_cameras = cameras as array
780 Chapter 10 | Collections

PathName Values
PathNames provide the mechanism for naming objects in the 3ds max scene. See also the Pathname
Literals (p. 662) topic. Pathname values are mappable.
Example Literals:
$box01
$torso/left_upper_arm/left_lower_arm
$*box*
$torso/*
$torso...*

Properties:
<pathname>.center : Point3, read-only
Returns center of bounding box of all objects in pathname.
<pathname>.max : Point3, read-only
Returns maximum corner of bounding box.
<pathname>.min : Point3, read-only
Returns minimum corner of bounding box.
<pathname>.count : Integer, read-only
Returns number of objects in set. This property is only valid for wild-carded pathnames,
i.e., a pathname that could contain more than one scene object.
Operators:
<pathname>[<integer>] -- accesses member of collection. Indexes start at 1.
<pathname> as array -- converts pathname collection to an array

Associated Methods:
isDeleted <MAXWrapper_object>
This function yields the result true if the object has been deleted and false if it still
exists in the scene. Using the function only makes sense in situations where references to
3ds max objects are held in variables or arrays or passed as parameters and you want to
determine whether the object has been deleted from the scene. Performing an operation
on a deleted 3ds max object referenced in a variable or array otherwise generates an
exception. Any kind of 3ds max object can be tested in this way, scene objects, modifiers,
controllers, materials, etc.
For example:
myBoxes = $box* as array -- store list of all boxes in array myBoxes
...
-- <one or more objects in the selection are deleted
-- by the user or other scripts>
...
for obj in myBoxes
where not isDeleted obj do
move obj [10,0,0]
 ObjectSet Values 781

Notes:
The order of sequencing is consistent in a stable scene but somewhat arbitrary - it depends on how
3ds max stores its object hierarchy internally which is affected mostly by order of additions and
deletions to and from the scene.
MAXScript lets you set up a ‘working level’ in the 3ds max scene hierarchy that affects pathnames
and coordinate systems and object creation. You do this with a <level_expr>, one of the many
context expressions that are described in the Context Expressions (p. 681) topic.
Examples:
a = $*feet*[i] -- retrieves the i’th object in the *feet*’s

-- tell me what things inside dummy have a non-identity scale

for obj in $dummy...*
where obj.scale != [1,1,1]
do format “% has non-identity scale: %\n” obj.name obj.scale

-- place $foo’s pivot point at the max corner of the set of ‘box*’ objects.
$foo.pivot = $box*.max

in $dummy
(
sphere name:”ear1” pos:[10,10,10] -- create as children of $dummy
sphere name:”ear2” pos:[-10,10,10]
scale $foo/* [1,1,2] -- looks for ‘foo’ as a child of $dummy
)

ObjectSet Values
ObjectSets represent the main scene object categories in 3ds max. The “constructors” below are all
reserved system variables. ObjectSet values are mappable.
Constructors:
objects -- all the objects
geometry -- the standard 3ds max categories...
lights
cameras
helpers
shapes
systems
spacewarps
selection -- the current selection

Properties:
<objectset>.center : Point3, read-only
Returns center of bounding box of all objects in set.
<objectset>.max : Point3, read-only
Returns maximum corner of bounding box.
782 Chapter 10 | Collections

<objectset>.min : Point3, read-only

Returns minimum corner of bounding box.
<objectset>.count : Integer, read-only
Returns number of objects in set.
Operators:
<objectset>[<integer>] -- accesses member of collection. Indexes start at 1.
<objectset> as array -- converts objectset collection to an array

Associated Methods:
clearSelection()
Clears current scene node selection.
deselect <PathName>
Deselects given node(s). For example:
deselect $box*

deselects all items whose names start with “box”.

select <PathName>
Deselects any current selection first, then selects the node(s) you specified.
selectMore <PathName>
Adds the specified node(s) to the current selection.
getCurrentSelection()
Returns the current selection as an array. This is equivalent to selection as array, but can be
significantly faster if there are very large numbers of objects in the scene.
Notes:
ObjectSets are actually special types of value that denote their sets, stored in reserved system
variables of the same name, so you can assign them to other variables and pass them around as
function arguments, etc. When storing an ObjectSet to a variable, the ObjectSet value is stored rather
than the objects in the ObjectSet. To store the objects currently in the ObjectSet to a variable, first
convert the ObjectSet to an array using the as operator.
You can use ObjectSets as the root of a pathname, like this:
$helpers/d*
which limits the pathname searching to the object set you’ve specified. So, in the above
example, it will name only helper objects that start with ‘d’.
The order of sequencing is consistent in a stable scene but somewhat arbitrary - it depends on how
3ds max stores its object hierarchy internally which is effected mostly by order of additions and
deletions to and from the scene.
 SelectionSetArray Values 783

The lights and cameras object sets include the target objects, if any, for the lights and cameras. If
you want to change a property value for all the lights or cameras, you will need process each object
in the ObjectSet individually, testing to make sure it is a light or camera. For example, to increase
the multiplier property value for all lights, you would say:
for obj in lights do
if iskindof obj light do
obj.multiplier *= 1.3

Examples:
s = selection[1] -- grab the first object in the
-- current selection
move camera[2] [x, y, z + 10] -- move the second camera

-- select everything within a 100 units of $foo

for o in objects where distance o $foo < 100 do selectmore o

SelectionSetArray Values
The SelectionSetArray class has only one instance, selectionSets, which is an array of all the named
selection sets in the current scene. The named selection sets correspond to the selection sets in the
Named Selection Set drop-down list on the 3ds max toolbar. Also see the SelectionSet Values (p. 785)
topic. SelectionSet values are mappable.
Constructors:
selectionSets

Properties:
<selectionsetarray>.count : Integer, read-only
Returns number of named selection sets.
Operators:
<selectionsetarray>[<set_name>]
Accesses member of collection by named selection set name. set_name can be either a
String or Name value.
<selectionsetarray>[<set_index_integer>]
Accesses member of collection by index number. Indexes start at 1.
<selectionsetarray>[<set_name>] = <node_array>
Create or replace named selection set with name set_name, which can be either a String
or Name value. node_array must be an array of nodes.
Methods:
deleteItem <selectionsetarray> <set_name>
Delete the named selection set with name set_name, which can be either a String or
Name value.
784 Chapter 10 | Collections

Associated Methods:
getNumNamedSelSets()
Returns number of named selection sets as an integer.
getNamedSelSetName <set_index_integer>
Returns name of the indexed named selection set as a string. <set_index_integer> is 1
based.
getNamedSelSetItemCount <set_index_integer>
Returns name of the indexed named selection set as a string. <set_index_integer> is 1
based.
getNamedSelSetItem <set_index_integer> <node_index_integer>
Returns indexed node in the indexed named selection set as a node.
<set_index_integer> and <node_index_integer> are 1 based.
Examples:
You access an individual selection set by indexing the selectionSets array with its name or index:
set1 = selectionSets[”my set 1”]

You can then use that set just as you would use any other object set in MAXScript, such as selection,
objects, lights, etc. For example,
move set1 [10,0,0]
moves all the objects in the set across 10 in x.
You can use strings or MAXScript names (starting with #) interchangeably as indexes for the
selectionSets array, or you can use an integer as an index if you want to loop over all the sets,
for example:
selectionSets[#set2].wireColor = red
for i in 1 to selectionSets.count do
saveNodes selectionSets[i] (”set” + i as string + “.max”)

You can change, add and delete new Name Selection Sets by using the standard array methods on
the selectionSets array:
selectionSets[”new set”] = selection -- snap the current selection
selectionSets[”old spheres”] = $sphere* -- all the current objects named
-- “sphere*”
selectionSets[#foo] = #(obj1, obj2, obj3)
deleteItem selectionSets “old set” -- delete the set named “old set”
 SelectionSet Values 785

SelectionSet Values
A SelectionSet represents the named scene node selection sets in the Named Selection Sets
drop-down list in the 3ds max toolbar. Also see the SelectionSetArray Values (p. 783) topic.
SelectionSet values are mappable.
Constructors:
selectionSets[<set_name>] -- set by string or name value
selectionSets[<index>] -- set by order in drop-down list

Operators:
<selectionset>[<integer>] -- retrieve nth object in set

Properties:
<selectionset>.center : Point3, read-only
Returns center of bounding box of all objects in set.
<selectionset>.max : Point3, read-only
Returns maximum corner of bounding box.
<selectionset>.min : Point3, read-only
Returns minimum corner of bounding box.
<selectionset>.count : Integer, read-only
Returns number of objects in set.
Notes:
Unlike ObjectSet, you cannot use SelectionSet as the root of a pathname.
The order of sequencing is consistent in a stable scene but somewhat arbitrary - it depends on how
3ds max stores its object hierarchy internally which is effected mostly by order of additions and
deletions to and from the scene.

NodeChildrenArray Values
A NodeChildrenArray represents the direct children of a scene node as a virtual array. As such, you
can iterate over the children, apply mapped functions to them and obtain certain properties such as
count and bounding box info. Also see the General Node Properties (p. 836) topic. NodeChildrenArray
values are mappable.
Constructors:
<node>.children

Properties:
<nodechildrenarray>.center : Point3, read-only
Returns center of bounding box of children.
<nodechildrenarray>.max : Point3, read-only
Returns maximum corner of bounding box.
786 Chapter 10 | Collections

<nodechildrenarray>.min : Point3, read-only

Returns minimum corner of bounding box.
<nodechildrenarray>.count : Integer, read-only
Returns number of objects in set.
Operators:
<nodechildrenarray>[<integer>] -- retrieve nth child

Methods:
append <nodechildrenarray> <node>
Makes the specified node a child of the node NodeChildrenArray was constructed from.
deleteItem <nodechildrenarray> <node>
Removes specified node as a child of the node NodeChildrenArray was constructed from.
Notes:
Unlike ObjectSets, you cannot use NodeChildrenArray as the root of a pathname.
The order of sequencing is consistent in a stable scene but somewhat arbitrary - it depends on how
3ds max stores its object hierarchy internally which is effected mostly by order of additions and
deletions to and from the scene.

VertexSelection Values
A VertexSelection represents a set of vertices for a scene mesh node as a virtual array. As such, you
can access a vertex by index, iterate over the vertices, and apply mapped functions to the vertices.
See also Editable_Mesh (p. 1041). The VertexSelection array is dynamic, i.e., its contents will change
as the vertices or selected vertices of the mesh node change. VertexSelection values are mappable.
Constructors:
<mesh>.selectedVerts -- the currently selected vertices of the mesh object
<mesh>.verts -- all of the vertices of the mesh object, read-only

Properties:
<vertexselection>.count : Integer, read-only
Returns the number of vertices in the VertexSelection array.
<vertexselection>.selSetNames : Array of names, read-only
Returns an array of names of the current vertex-level named selection sets for the object
the VertexSelection is associated with.
The following properties are present for singleton selections (of the form $foo.verts[n]):
<vertexselection>.index : Integer, read-only
Returns the index of the selected element in the mesh, e.g.,
$foo.selectedVerts[2].index
returns the vertex index of the 2nd vertex in the current selection.
 VertexSelection Values 787

<vertexselection>.pos : Point3
Returns or sets the position of the selected element in the mesh, e.g.,
$foo.verts[i].pos = $baz.verts[j].pos + [10,0,0]

Note that iterating over a selection yields singleton selections in the loop body:
sv = for i in $foo.selectedVerts collect i.index
sv contains selected vertices as array
Operators:
<mesh>.selectedVerts = (<array> | <bitarray>)
Selects the specified vertices.
<vertexselection>[<integer>]
Retrieves the indexed vertex as a singleton VertexSelection. Index starts at 1
<vertexselection>[<integer>] = <point3>
Sets the position of the indexed vertex.
<vertexselection>[(<integer_array> | <bitarray>)]
Retrieves the indexed vertices as a VertexSelection. Index starts at 1.
<vertexselection>[(<#name> | <string>)]
Retrieves the vertex-level named selection set, where the name of the named selection set
can be specified as a name or string value.
<vertexselection>[(<#name> | <string>)] = (<vertexselection> | <integer_array> |
<bitarray>)
Sets the vertex-level named selection set to the specified vertices. The name of the named
selection set can be specified as a name or string value, and the vertices can be specified as
an array, bitArray, or a VertexSelection from the same object.
Methods:
move <vertexselection> <point3>
Moves the vertices in the VertexSelection.
select <vertexselection>
Selects the vertices in the VertexSelection.
deselect <vertexselection>
Deselects the vertices in the VertexSelection.
delete <vertexselection>
Deletes the vertices in the VertexSelection.
append <vertexselection> (<vertexselection> | <integer>)
Appends the vertex or vertices to the VertexSelection.
findItem <vertexselection> (<vertexselection[<integer>] | <integer>)
Returns the selection index of the matching item or 0 if not found. The item is selection
index or singleton VertexSelection.
788 Chapter 10 | Collections

Examples:
-- move vertices in ‘mouth’ named selection set
move $foo.verts[#mouth] [0,0,10]
-- select vertices in ‘front verts’ set
select $baz.verts[”front verts”]
-- set ‘baz’ named selection set to given vertices
$foo.verts[#baz] = #(1,3,4,5,10)
-- set ‘cursel’ set to current selection
$baz.verts[#cursel] = $baz.selectedVerts
-- all the names of the vertex-level named selection sets for object $foo
$foo.verts.selSetNames
-- print out all vertex-level named selection sets
for n in $.verts.selSetNames do print $.verts[n]

FaceSelection Values
A FaceSelection represents a set of faces for a scene mesh node as a virtual array. As such, you can
access a face by index, iterate over the faces, and apply mapped functions to the faces. See also
Editable_Mesh (p. 1041). The FaceSelection array is dynamic, i.e., its contents will change as the faces
or selected faces of the mesh node change. FaceSelection values are mappable.
Constructors:
<mesh>.selectedFaces -- the currently selected faces of the mesh object
<mesh>.Faces -- all of the faces of the mesh object, read-only

Properties:
<faceselection>.count : Integer, read-only
Returns the number of faces in the FaceSelection array.
<faceselection>.selSetNames : Array of names, read-only
Returns an array of names of the current face-level named selection sets for the object the
FaceSelection is associated with.
The following property is present for singleton selections (of the form $foo.faces[n]):
<faceselection>.index : Integer, read-only
Returns the index of the selected element in the mesh, e.g.,
$foo.selectedFaces[2].index
returns the face index of the 2nd face in the current selection.
Note that iterating over a selection yields singleton selections in the loop body:
sf = for i in $foo.selectedFaces collect i.index
sf contains selected faces as array
Operators:
<mesh>.selectedFaces = (<array> | <bitarray>)
Selects the specified faces.
<faceselection>[<integer>]
Retrieves the indexed face as a singleton FaceSelection. Index starts at 1.
 FaceSelection Values 789

<faceselection>[<integer>] = <point3>
Sets the vertices of the indexed face to the vertex indices specified in the point3 value.
<faceselection>[(<integer_array> | <bitarray>)]
Retrieves the indexed faces as a FaceSelection. Index starts at 1.
<faceselection>[(<#name> | <string>)]
Retrieves the face-level named selection set, where the name of the named selection set
can be specified as a name or string value.
<faceselection>[(<#name> | <string>)] = (<faceselection> | <integer_array> |
<bitarray>)
Sets the face-level named selection set to the specified faces. The name of the named
selection set can be specified as a name or string value, and the faces can be specified as an
array, bitArray, or a FaceSelection from the same object.
Methods:
move <faceselection> <point3>
Moves the faces in the FaceSelection.
select <faceselection>
Selects the faces in the FaceSelection.
deselect <faceselection>
Deselects the faces in the FaceSelection.
delete <faceselection>
Deletes the faces in the FaceSelection.
append <faceselection> (<faceselection> | <integer>)
Appends the face(s) to the FaceSelection.
findItem <faceselection> (<faceselection[<integer>] | <integer>)
Returns the selection index of the matching item or 0 if not found. The item is selection
index or singleton FaceSelection.
Examples:
-- move faces in ‘mouth’ named selection set
move $foo.faces[#mouth] [0,0,10]
-- select faces in ‘front faces’ set
select $baz.faces[”front faces”]
-- set ‘baz’ named selection set to given faces
$foo.faces[#baz] = #(1,3,4,5,10)
-- set ‘cursel’ set to current selection
$baz.faces[#cursel] = $baz.selectedFaces
-- all the names of the face-level named selection sets for object $foo
$foo.faces.selSetNames
-- print out all face-level named selection sets
for n in $.faces.selSetNames do print $.faces[n]
790 Chapter 10 | Collections

EdgeSelection Values
An EdgeSelection represents a set of edges for a scene mesh node as a virtual array. As such, you can
access an edge by index, iterate over the edges, and apply mapped functions to the edges. See also
Editable_Mesh (p. 1041). The EdgeSelection array is dynamic, i.e., its contents will change as the
edges or selected edges of the mesh node change. EdgeSelection values are mappable.
Constructors:
<mesh>.selectedEdges -- the currently selected edges of the mesh object
<mesh>.Edges -- all of the edges of the mesh object, read-only

Properties:
<edgeselection>.count : Integer, read-only
Returns the number of edges in the edge array.
<edgeselection>.selSetNames : Array of names, read-only
Returns an array of names of the current edge-level named selection sets for the object the
EdgeSelection is associated with.
The following property is present for singleton selections (of the form $foo.edges[n]):
<edgeselection>.index : Integer, read-only
Returns the index of the selected element in the mesh, e.g.,
$foo.selectedEdges[2].index
returns the edge index of the 2nd edge in the current selection.
Note that iterating over a selection yields singleton selections in the loop body:
se = for i in $foo.selectedVerts collect i.index
se contains selected edges as array
Operators:
<mesh>.selectedEdges = (<array> | <bitarray>)
Selects the specified edges.
<edgeselection>[<integer>]
Retrieves the indexed edge as a singleton EdgeSelection. Index starts at 1
<edgeselection>[(<integer_array> | <bitarray>)]
Retrieves the indexed edges as a EdgeSelection. Index starts at 1.
<edgeselection>[(<#name> | <string>)]
Retrieves the edge-level named selection set, where the name of the named selection set
can be specified as a name or string value.
<edgeselection>[(<#name> | <string>)] = (<faceselection> | <integer_array> |
<bitarray>)
Sets the edge-level named selection set to the specified edges. The name of the named
selection set can be specified as a name or string value, and the edges can be specified as an
array, bitArray, or a EdgeSelection from the same object.
 BitArray Values 791

Methods:
move <edgeselection> <point3>
Moves the edges in the EdgeSelection.
select <edgeselection>
Selects the edges in the EdgeSelection.
deselect <edgeselection>
Deselects the edges in the EdgeSelection.
delete <edgeselection>
Deletes the edges in the EdgeSelection.
append <edgeselection> (<edgeselection> | <integer>)
Appends the edge(s) to the EdgeSelection.
findItem <edgeselection> (<edgeselection[<integer>] | <integer>)
Returns the selection index of the matching item or 0 if not found. The item is selection
index or singleton EdgeSelection.
Examples:
-- move edges in ‘mouth’ named selection set
move $foo.edges[#mouth] [0,0,10]
-- select edges in ‘front edges’ set
select $baz.edges[”front edges”]
-- set ‘baz’ named selection set to given edges
$foo.edges[#baz] = #(1,3,4,5,10)
-- set ‘cursel’ set to current selection
$baz.edges[#cursel] = $baz.selectedEdges
-- all the names of the edge-level named selection sets for object $foo
$foo.edges.selSetNames
-- print out all edge-level named selection sets
for n in $.edges.selSetNames do print $.edges[n]

BitArray Values
The MAXScript BitArray class provides direct access to 3ds max’s SDK BitArray class. The SDK
BitArray is used throughout 3ds max to compactly encode selections as a string of bits.
Literals:
#{ <selection> } -- these are curly-brackets

where <selection> is a comma-separated list of the following:

<integer> -- integers must be > 0
<integer> .. <integer>

For example, #{1, 5, 10..200, 302} says that the bits 1, 5, 10 to 200, and 302 are “turned on”.
When used in connection with selections in 3ds max (such as vertex or face or control vertex)
the “on” bits imply the elements or sub-objects with those indexes are selected.
792 Chapter 10 | Collections

Properties:
<bitarray>.count : Integer, read-only
Returns the largest possible index held in the BitArray at that point in time. This value is
independent of whether any particular indexes are selected or not. BitArrays grow
dynamically as needed to accommodate the indexes used on it, just as with arrays.
Operators:
<bitarray>[<integer>] -- yields true if selected, else false
<bitarray>[<integer>] = <boolean> -- sets or clears indexed bit
<bitarray> + <bitarray> -- union (”OR” operation)
<bitarray> - <bitarray> -- difference
-<bitarray> -- invert the bitarray

Methods:
append <bitarray> <integer>
Adds index to bitarray, growing bitarray if necessary.
join <bitarray> <bitarray>
Union (”OR” operation) of the two bitarrays.
findItem <bitarray> <integer>
Yields index <integer> if selected, 0 otherwise.
deleteItem <bitarray> <integer>
Clears the index selection.
copy <bitarray>
Creates an independent copy of the bitarray.
Notes:
BitArrays can be used interchangeable with ordinary #(...) arrays (p. 776) of index numbers where
ever a selection array is applicable, such as in mesh sub-object selections, for example:
$foo.verts[#{20..1023}] -- selects all vertices between 20 and 1023

You can sequence over BitArrays with a for-loop, which yields a sequence of index numbers
corresponding to the currently selected items.
for i in #{2..200} do print i -- print the numbers between 2 & 200

You can perform an “AND” operation between two BitArrays by inverting the difference between
them. For example:
a=#{1..5}
b=#{3..10}
c=-(a-b) -- result in c is #{3..5}
 MAXKeyArray Values 793

MAXKeyArray Values
A MAXKeyArray represents all the keyframe keys in a 3ds max controller track. See also the MAXKey
Values (p. 767), Working with MAXKey Values (p. 769), and Controller Common Properties, Operators, and
Methods (p. 1289) topics. MAXKeyArray values are mappable.
Constructors:
<node>.<animatable_property>.keys
The key array can be accessed using the keys property on an animated 3ds max object
property. Examples:
$foo.position.keys
$foo.twist.angle.keys

If the 3ds max object parameter is not yet animated (i.e., no controller has been assigned
to the parameter), a value of undefined is returned.
<controller>.keys
The key array can be accessed using the keys property on a controller. Examples:
$foo.position.controller.keys
$foo[3][1].keys

Properties:
<key_array>.count : Integer, read-only
Returns the number of keys in the key array.
Operators:
<key_array>[<index_integer>]
Returns a MAXKey (p. 767) value representing the indexed key in the key array. Indexes
start at 1.
Methods:
append <key_array> <key>
Appends key to key array.
deleteItem <key_array> <index_integer>
Deletes the indexed key. Key indexes are 1-based.
addNewKey <key_array> <time> [ #select ]
Adds a new key to the key array at the time specified. The value for the new key is the
interpolated controller value at the specified time. The new key is also selected if the
#select optional argument is specified. The value for the new key is the interpolated
controller value at that time. addNewKey() will not add a key if a key already exists at the
specified time. The return value in this case is the key located at the specified time.
deleteKeys <key_array> [ #allKeys ] [ #selection ]
Deletes keys from the controller according to the optional symbolic argument supplied.
#allKeys (default): deletes all keys in the controller.
#selection: deletes the currently selected keys
794 Chapter 10 | Collections

deleteKey <key_array> <index_integer>

Deletes the indexed key. Key indexes are 1-based.
moveKeys <key_array> <time> [ #selection ]
Moves all keys by the time given. If #selection is specified, move the current selection
otherwise move all keys.
sortKeys <key_array>
Re-sorts keys according to their times. Some MAXKey operations can result in out of order
keys and this function must be called to correctly order keys.
Notes:
All of the above methods may re-sequence keys in the key array and so cause existing keys to take
on different indexes, because key array indexes are time positional. Take care when inserting and
deleting keys into arrays that have individual keys in variables and other containers -- MAXKey
values are defined internally in terms of this index and so may point to different keys if you
re-arrange the keys in a controller.
MAXKeyArrays also support mapped property assignment on their contents in the same way that
pathname and array collections do on their contents. So, for example:
$box01.pos.keys.time += 10f
bumps all key times by 10 frames, and,
$cyl23.bend.angle.keys.value *= 1.2
scales all the bend angle key values up by 1.2.
Example:
keys = $box01.bend.angle.keys
for t in 0f to 100f by 10f do addNewKey keys t

MAXNoteKeyArray Values
A MAXNoteKeyArray represents all the note keys in a 3ds max note track. This value is described in
Note Track Access (p. 816). MAXNoteKeyArray values are mappable.

ModifierArray Values
A ModifierArray represents the modifiers present on a scene node as an array. As such, you can access
a modifier by index, iterate over the modifiers, and apply mapped functions to the modifiers. See
also Modifiers (p. 1095). ModifierArray values are mappable.
Constructors:
<node>.modifiers

Properties:
<modifierarray>.count : Integer, read-only
Returns the number of modifiers in the modifier array.
 MaterialLibrary Values 795

Operators:
<modifierarray>[<integer>]
Retrieves indexed modifier. Index is 1-based with 1 being the modifier on the top of the
modifier stack.
<modifierarray>[( <name> | <string> )]
Retrieves named modifier using modifier name as string or name.

MaterialLibrary Values
A MaterialLibrary contains a table of materials as an array. The 3ds max system global variables
currentMaterialLibrary and sceneMaterials contain MaterialLibrary instances. System
global variable meditMaterials strictly speaking is not a MaterialLibrary value, rather it is a virtual
array of the materials in the Material Editor sample slots. In most cases, meditMaterials can be
considered a MaterialLibrary value, with the exception that you can assign a material or textureMap
value to a meditMaterials element. MaterialLibrary values are mappable.
Constructors:
currentMaterialLibrary -- system global
sceneMaterials -- system global, the materials in the scene
meditMaterials -- system global, the materials in material editor

materialLibrary { <material> }
Creates a temporary material library. You can add materials to this library with the append
function, but there is currently no way to save it or make it the current library.
Properties:
<mat_lib>.count : Integer, read-only
Returns the number of materials in the library.
Operators:
<mat_lib>[ <integer> | <name> | <string> ]
Retrieves a material from the material library. Material libraries can be indexed just like
arrays with an integer index, or by using the material name as a Name or String value.
<mat_lib>[ <integer> | <name> | <string> ] = ( <material> | <textureMap> )
Assigns the specified material or textureMap to the material library. Material libraries can
be indexed just like arrays with an integer index, or by using the material name as a Name
or String value. If the material library is indexed by an index value, and the index value is
larger than the size of the material library, a runtime error is generated. If the material
library is indexed by a material name, and the material name is not already present in the
material library, the material or textureMap is appended to the material library.
meditMaterials[<slot_index_integer>]
Returns the material or textureMap in the indexed material editor slot. Valid
<slot_index_integer> values are 1 through 24.
796 Chapter 10 | Collections

meditMaterials[<slot_index_integer>] = ( <material> | <textureMap> )

Assigns the specified material or textureMap to the indexed material editor slot. Valid
<slot_index_integer> values are 1 through 24. For example:
meditMaterials[3]= standard()

Methods:
append <mat_lib> <material>
Append the specified material to the material library. This method is not applicable to the
meditMaterials material library.
deleteItem <mat_lib> ( <integer> | <name> | <string> )
Delete the specified material from the material library. The material can be specified as the
indexed material in the material library, as a String, or as a Name. This method is not
applicable to the meditMaterials material library.
findItem <mat_lib> <material>
Returns the index of the material in the material library or zero if the material is not in the
material library.
Associated Methods:
getMeditMaterial <slot_index_integer>
Returns the top level material or textureMap in the specified material editor slot. Valid
<slot_index_integer> values are 1 through 24. For example:
foo = getMeditMaterial 3

setMeditMaterial <slot_index> ( <material> | <textureMap> )

Complements the getMeditMaterial function allowing you to place a material or
textureMap into the numbered material editor slot.
loadDefaultMatLib()
Loads the default 3ds max material library file.
loadMaterialLibrary <filename_string>
Loads the named 3ds max material library file, which becomes the current material library.
If the file name does not have a fully specified directory path, the function searches
through all the currently configured bitmap paths. Returns true if the loads succeeds,
false if it fails.
saveMaterialLibrary <filename_string>
Saves the current material library into the named file. Returns true if the save succeeds,
false if it fails.
fileOpenMatLib()
This method displays the File Open dialog and allows the user to select a material library
to load. Note: If the Material/Map Browser is open when fileOpenMatLib() is called, the
Material/Map Browser display is not updated.
fileSaveAsMatLib()
Displays the standard Save File As dialog to allow the user to save the current
material library.
 NURBSSet Values 797

fileSaveMatLib()
If the current material library has been saved previously (has been named) this method
saves the material library to the same file. Otherwise it displays the standard Save File As
dialog to allow the user to save the current material library.
getMatLibFileName()
Returns the current material library file name as a String value.
Examples:
You can use the standard array indexing accessors to get and set materials in the library.
MaterialLibraries also allow you to use name and string literals as indexes to get at materials in them
by name:
$foo.material = currentMaterialLibrary[”Rough Gold”]
for m in sceneMaterials do print m.name
append currentMaterialLibrary $baz.material

NURBSSet Values
A NURBSSet is used rto create NURBS objects, or retrieve data from existing NURBS objects. The
NURBSSet acts as a container for the various NURBSObject derived entities (points, curves, surfaces)
used to make up the set. This value is described in NURBSSet : Value (p. 1450). NURBSSet values are
mappable.
798 Chapter 10 | Collections
Chapter 11: 3ds max Objects

Identifying and Accessing MAXScript Classes

and Properties
The largest set of classes and functions in MAXScript are those that provide access to the elements
in the 3ds max application and in your scene. This section has several topics that discuss the use of
these 3ds max-specific classes and functions. One important family of classes is the MAXWrapper
Value (p. 808) class that give you access to the scene objects, lights, cameras, modifiers, controllers,
materials, etc., in 3ds max scenes.
The topics in this section are:
Class and Object Inspector Functions (p. 799)
Dynamic Properties (p. 805)
Indexed Access to Animatable Properties (p. 806)
Third-Party Plug-In Classes (p. 808)

Class and Object Inspector Functions

MAXScript provides a number of built-in functions that display information about the classes that
are accessible in your particular 3ds max installation. These functions are useful as an online
reference for the core 3ds max classes and provide the only way of determining what properties in
Third-Party plug-in classes (p. 808) are accessible.
apropos:
The apropos() function is used to search for and print out information about global variables by
name pattern and class of contents. This function has the form:
apropos <pattern_string> [ to:<stream> ]

The <pattern_string> argument is a string containing a wild-card pattern for matching against
global variables. The pattern form is:
<variable_name_pattern_string[:class_name_pattern_string]>
800 Chapter 11 | 3ds max Objects

that is, a global variable name pattern optionally followed by a ‘:’ and a class name pattern. If the
optional class name pattern is given, it restricts the printout to globals containing values of the
specified classes. The apropos() function assumes a wild-card ‘*’ at the start and end of each
pattern, implying a ‘contains’ pattern match. The pattern strings can contain name characters and
‘*’s and ‘?’s.
The output consists of the global variable name, a tag in () indicating if the variable is a system or
const (unchangeable) variable and the class of the value currently in it, followed by a printed
representation of that value.
Examples:
apropos “light” -- any variables with ‘light’ in the variable name
apropos “:float” -- any variables containing float values
apropos ““ to:f -- dump all variables to the stream f
apropos “controller:super” -- the list of controller superclasses
apropos “foo:control” -- any variables whose name contains ‘foo’
-- and that contain controller classes

Here’s a fragment of the first example’s output:

lights (const ObjectSet): $lights
lightLevel (system Float): 1.0
Sunlight (const MAXClass): Sunlight
Directionallight (const MAXClass): Directionallight
lightLevelController (system Control): Controller:Bezier_Float
light (const MAXSuperClass): light
NewLight (const Primitive): NewLight()
lightTintColor (system Color): (color 255 255 255)
Volume_Light (const MAXClass): Volume_Light
lightTintColorController (system Control): Controller:Bezier_Color
gw.getMaxLights (Primitive): getMaxLights()
gw.setLight (Primitive): setLight()

showClass:
The showClass() function prints information about a specified 3ds max class or classes. It has the
following form:
showClass <pattern_string> [ to:<stream> ]
where <pattern_string> is a string containing a wild-card pattern to match against
3ds max class names, superclass names and property names, and the optional
to:<stream> keyword argument specifies a Stream Value (p. 763) to output the display to.
The pattern string has this form:
“<class_name>[ :<superclass_name> ][ .<property_name> ]”
 Class and Object Inspector Functions 801

Examples:
showClass “path*” -- all 3ds max classes starting ‘path’
showClass “noise.*” -- all the accessible properties on the
-- Noise texture map
showClass “*:mod*” -- all the modifier classes
showClass “*.*rad*” -- all the classes with a property name
-- containing ‘rad’
showClass “*.*” to:f -- everything, out to a file
showClass “*:*controller*” -- all the classes that have
-- “controller” in their superclass
-- name

In the output from the last example, the controllers include 3ds max’s core controllers and any
3rd-party plug-in controllers. In some cases, embedded controllers for some complex plug-ins may
be visible in the showClass() listing (such as for character studio and HyperMatter). You should
not attempt to create and use these controllers individually, this may result in system exceptions.
If you leave out the superclass pattern (the ‘:’ part), it matches all superclasses. If you leave out the
property pattern (the ‘.’ part), you only get class names printed.
Note:
This function only displays matching MAXWrapper classes (nodes, modifiers, materials, etc.), not
the foundation classes in MAXScript (float, integer, array, point3, etc.).
The following shows examples of the output of showClass():
Script:
showclass “box*” -- show all classes whose name starts with “box”
showclass “box.*” -- show all properties for class box

Output:
Box : GeometryClass {10,0} -- start of output from line 1
BoxGizmo : helper {3bc31904,67d74ec9}
OK -- result returned from line 1
Box : GeometryClass {10,0} -- start of output from line 2
.height : float
.length : float
.lengthsegs : integer
.width : float
.widthsegs : integer
.mapCoords : boolean
.heightsegs : integer
OK -- result returned from line 2

showProperties:
The showProperties() function is used to display the properties for a specific object that is an
instance of one of the MAXWrapper classes. It can be used in place of showClass() in situations
where you have an actual object in hand. Unlike showClass(), it can display the dynamic properties
(p. 805) that may appear in individual objects as you work on them in the scene, such as the sub-
controllers in a list controller or the animated control points in an FFD modifier.
802 Chapter 11 | 3ds max Objects

The showProperties() function has the form:

showProperties <maxwrapper_object> [ <property_pattern> ] [ to:<stream> ]
where <maxwrapper_object> is the 3ds max entity to be inspected, the optional
<property_pattern> is a wild-card pattern that names the properties to be inspected,
and the optional to:<stream> keyword argument specifies a Stream Value (p. 763) to
output the display to.
If the property name pattern is not supplied, all properties are listed.
Examples:
showProperties $foo.bend -- show properties of the bend modifier on
object foo

ffdmod = $baz.’FFD_box__4x4x4’ -- point to the FFD modifier on object baz

showProperties ffdmod “disp*” to:log -- show properties starting with “disp” in the
-- FFD modifier

showProperties $foo.pos.controller -- sub controllers in a position list

controller

Note:
When the 3ds max entity specified is a node (for example $box01), this function only displays the
properties of base object. It does not show the properties of the transform controllers, modifiers, or
materials applied to the object. To display the properties for one of these objects, that object must
be specified as the 3ds max entity as shown in the above examples.
The following shows examples of the output of showProperties:
Script:
b=box() -- create a box
ffd_mod=ffdBox() -- create a ffdBox modifier
addmodifier b ffd_mod -- apply ffdBox modifier to the box
showproperties b -- show all properties for the box
showproperties ffd_mod -- show all properties for the ffdBox modifier

Output:
$Box:Box07 @ [0.0000,0.0000,0.0000] -- result from line 1
FFD_box__4x4x4:FFD(box) 4x4x4 -- result from line 2
OK -- result from line 3
.height : float -- start of output from line 4
.length : float
.lengthsegs : integer
.width : float
.widthsegs : integer
.mapCoords : boolean
.heightsegs : integer
OK -- result from line 4
.dispLattice (Lattice) : boolean -- start of output from line 5
.dispSource (Source Volume) : boolean
.deformType (<unknown>) : integer
.falloff : float
 Class and Object Inspector Functions 803

.tension : float
.continuity : float
.inPoints (Inside Points) : boolean
.outPoints (Outside Points) : boolean
.offset : float
.lattice_transform : transform
OK -- result from line 5

getPropNames:
The getPropNames() function is similar to showProperties(), except it returns the property
names for a specific object as an array. Unlike showProperties(), you can specify whether to
return only the names of dynamic properties (p. 805) of the object.
The getPropNames function has the form:
getPropNames <maxwrapper_obj> [ #dynamicOnly ]

The getPropNames() function returns an array of the property names accessible on the object. For
example, if a FFD(Box) modifier with animated control points is applied to a sphere,
getPropNames $sphere01.’FFD(box) 4x4x4’

could yield:
#(#dispLattice, #dispSource, #deformType, #falloff, #tension, #continuity,
#inPoints, #outPoints, #offset, #Lattice_Transform, #Control_Point_49,
#Control_Point_50, #Control_Point_51, #Control_Point_52, #Control_Point_53)

Note:
When the 3ds max entity specified is a node (for example $box01), this function only returns the
properties of base object. It does not return the properties of the transform controllers, modifiers, or
materials applied to the object. To return the properties for one of these objects, that object must be
specified as the 3ds max entity as shown in the above examples.
If you call getPropNames() on MAXWrapper classes such as Box, Line, or Bend, it will return the
properties common to all instances of that class. If you call getPropNames() on a 3ds max entity,
it will return the properties currently defined for that entity. If you add the optional keyword
#dynamicOnly to the getPropNames() call for an entity, it returns the dynamic properties unique
to that instance.
For example,
getPropNames $sphere01.’FFD(box) 4x4x4’ #dynamicOnly

could yield:
#(#Lattice_Transform, #Control_Point_49, #Control_Point_50, #Control_Point_51,
#Control_Point_52, #Control_Point_53)

Note that the property names for the lattice transform and control points which was returned by
the previous example is not returned when #dynamicOnly is specified. These properties are unique
to the specific FFD modifier.
804 Chapter 11 | 3ds max Objects

As a special case, you can also call getPropNames() on the superclass ‘Node’ to get the list of
properties common to all scene nodes such as .position, .name, or .wireColor. For example:
getPropNames node

getProperty and setProperty:

The getProperty() and setProperty() functions allow you to access and set properties using
computed property names: These form for each of these functions are:
getProperty <obj> <property_name>
setProperty <obj> <property_name> <value>

The property name can be either a name, for example #length, or a string, for example “length”,
so you can construct property names with string operations.
Examples:
getProperty foo #x -- equiv. to foo.x
setProperty $foo “radius” 23 -- equiv. to $foo.radius = 23
getProperty $foo.ffd_2x2x2 (”control_point_” + n as string)

The getPropNames() function can be used in conjunction with the getProperty() function to
implement object ‘dumping’ tools that can iterate over all the properties of an arbitrary object and
output them as required. For example,
for p in getPropNames $foo do
format “% = %\n” p (getProperty $foo p)

Similar functions for accessing and setting the values of property-assigned controllers are:
getPropertyController <value> <string_or_name>
setPropertyController <value> <string_or_name> <controller>

Get and set the controller assigned to the named property of the value. If no controller has been
assigned to the property, a value of undefined is returned.
SubAnims and ParamBlocks:
3ds max stores all of properties for objects in structures called subAnims. In some cases, a subAnim
will contain nested subAnims. An example of this can be seen with the Standard material. If you
apply a Standard material to an 3ds max object, and then expand the object’s tracks in Track View
to display the material, you will see three Track View nodes - Parameters, Maps, and Shader. Each of
these nodes is a subAnim defined in the Standard material’s class. Expanding the tracks for these
three nodes, you will see various properties listed. These properties are defined in each of the nested
subAnims in a structure called a ParamBlock.
MAXScript automatically finds animatable properties in all ParamBlocks associated with an object.
To access these properties, you use the same nesting as shown in Track View when referencing those
properties in MAXScript. For example, you would access the Ambient Color property in a Standard
material in MAXScript as:
$box01.material.shader.diffuse_color
 Dynamic Properties 805

For more information about accessing animatable properties in MAXScript, see also Indexed Access to
Animatable Properties in 3ds max Objects (p. 806).
The properties accessible on the various kinds of values is documented for each class. Many of the
foundation classes in MAXScript (such as point3, color, etc.) support a special kind of nested-
property assignment which allows sub-properties on object properties, such as the .x, .y, and .z
coordinates in a node’s .position property, to be individually and directly set. See the Nested Object
Properties (p. 815) topic for details.

Dynamic Properties
In addition to the properties listed in the reference, MAXScript provides access to the dynamic
properties in 3ds max entities, those properties that are specific to an individual object and depend
on the operations you’ve performed on that object in the 3ds max scene. These includes such things
as animatable modifier sub-objects like gizmos and FFD control points and sub-controllers like those
in a List controller or P/R/S Transform or Path controller.
These correspond to the many animatable parameters and sub-objects that you see in the Track View
for an object; if you can see them in the Track View they will be visible as either static or dynamic
properties in the MAXScript value that corresponds to that object.
The property name you specify is matched against the sub-animatable name (as it would be seen in
the Track View or sub-object drop-down) using the standard MAXScript conventions of mapping
spaces to ‘_’ underscores and ignoring case when dealing with 3ds max class and property names.
You can also simply leave out the spaces in any dynamic property names.
Example:
p = $foo.bend.center
$baz.taper.gizmo.rotation = quat 30 z_axis
$foo.pos.controller.bezier_position = [10,0,0]

Because these properties are dynamic and may change as controllers are replaced and sub-objects
become animated, they may vary from object to object and so are not reported in the properties
section of the showClass() function output. Instead, you can use the built-in function
showProperties() which will display the accessible properties on a 3ds max entity including the
currently visible dynamic properties. Both functions are described in the Class and Object Inspector
Functions (p. 799) topic.
806 Chapter 11 | 3ds max Objects

Indexed Access to Animatable Properties in 3ds max Objects

As an alternative to using named property accesses, you can access in an object any animatable
property that is visible as a track in Track View by indexing the 3ds max object value as though it
were an array. This simplifies such tasks as iterating over all the animatable properties in an object
and accessing sub-controllers that don’t have unique names, such as within list controllers.
Properties:
<maxwrapper_object>.numSubs : Integer, read-only
Yields the number of accessible sub-animatables, or tracks, in an object. This is the number
of immediate children subAnims, and may include as yet invisible tracks in the track view,
such as visibility tracks on a node or yet-to-be animated vertices in an FFD. This property
operates on any MAXWrapper subclass.
Methods:
getSubAnimName <maxwrapper_object> <index>
getSubAnimNames <maxwrapper_object>
Provides access to the Track View names of subAnims. The getSubAnimName() function
takes a subAnim index and returns a Name instance. The getSubAnimNames() function
returns an array of names in subAnim index order.
getSubAnim <maxwrapper_object> <index>
Returns the indexed subAnim. See the index operator below.
Operators:
<maxwrapper_object>[<index_number>]
Returns the indexed subAnim. You can apply the index operator, [<index_number>], to
any MAXWrapper object (nodes, modifiers, controllers, materials, etc.) to access a
numbered subAnim. For example:
for i in 1 to $foo.numSubs do print $foo[i] -- iterate them
$bar.position.controller[3] -- third subAnim in a position list controller
ffd_mod[i].value -- position of i’th FFD control point

You cannot set subAnims with the index operator, this is a read-only access.
-- SubAnim Class
MAXScript defines a SubAnim class, instances of which provide a general representation for sub-
animatables. Whenever you use the index operator on a 3ds max object, it returns a SubAnim
instance. For example:
$box01[3] -> SubAnim:Transform
The third subAnim in a node is typically the transform track.
Properties:
<subAnim>.value : Value
The current value of the track subAnim, equivalent to <controller>.value. Returns
undefined if no appropriate value exists or the track has not yet been assigned a
 Indexed Access to Animatable Properties in 3ds max Objects 807

controller. The .value property yields the value at the current MAXScript time. You can
assign to this value to set the track’s value at that time.
<subAnim>.controller : Controller
The controller for the track SubAnim. Returns undefined if a controller has not yet been
assigned or if the SubAnim is not animatable. You can assign a new controller to a track by
assigning to the .controller property of its subAnim.
<subAnim>.keys : KeyArray, read-only
Yields the key array for that track or undefined if not keyable or a controller has not yet
been assigned. This property is read-only.
<subAnim>.isAnimated : Boolean, read-only
Yields true if there is an animated controller present. This property is read-only.
<subAnim>.object : MAXWrapper, read-only
Yields the subAnim object, or undefined if not assigned. This property is read-only. The
.object property may return any kind of MAXWrapper object, depending on what the
parent object decides to put there. For example, <node>[1].object is the visibility
controller or undefined if not yet assigned, <node>[2].object contains the bindings of
any space warps bound to the node, or undefined if none have been bound,
<node>[3].object is the transform controller, <node>[4].object is the node’s object,
either the modified object if there are modifiers present or the base object if not,
<node>[5].object is the material assigned to the node or undefined if no material has
been assigned, and <node>[6].object is the Image Motion Blur Multiplier controller or
undefined if not yet assigned,. For example:
b = box()
b[4].object -- returns a reference to the Box base object

<subAnim>.numSubs : Integer, read-only

The number of immediate subAnim children.
If you attempt to access subAnim properties, such as .value, .numSubs, .category, etc., on
certain subAnims that had yet to be assigned controllers, such as scene node visibility tracks, these
properties return null values such as 0, or undefined, as appropriate.
Methods:
getSubAnim <subAnim> <index>
Returns the indexed subAnim. See the index operator below.
Operators:
<subAnim>[<index_number>]
Returns the indexed subAnim. You can work down through nested subAnims (nested
tracks) by indexing into subAnims themselves. For example,
$box01[3][2]

yields the rotation track subAnim since <node>[3] is always the transform track and the
second track in it is always the rotation track. Indexing a SubAnim always yields another
SubAnim. For those familiar with SubAnims in the 3ds max SDK, it should be noted that
808 Chapter 11 | 3ds max Objects

MAXScript SubAnims descend automatically through ‘hidden’ subAnim levels, reflecting

the structure seen in Track View.
Note that you can get at the base object’s Track View parameters by indexing into the base
object:
b=box()
getSubAnimNames b[4] -- returns #(#length, #width, #height, ...)
b[4][2].value -- returns current width value
i = 3
b[4][i].controller = float_list() -- assign height controller

Third-Party Plug-In Classes

The MAXWrapper Value (p. 808) classes are the core 3ds max classes that are supported directly
within MAXScript. Many of the kinds of 3ds max objects you will work with are provided through
3rd-party plug-ins for 3ds max, they are not built directly in to MAXScript.
For these classes, an automatic plug-in detector scans for plug-ins that MAXScript doesn’t internally
know about and attempts to provide MAXScript access to them. This includes new core classes in
new releases of 3ds max that MAXScript doesn’t internally know about, and 3rd-party plug-ins (such
as HyperMatter, Sand Blaster, Surface Tools, etc.). Not all parameters and properties of the detected
plug-ins are accessible. In general, the detector will only find animatable parameters on these plug-
ins, and in some cases none at all, if the plug-in uses non-standard parameter coding.
You can use the class and object inspector functions (p. 799) in MAXScript to browse through the
3ds max core and 3rd-party classes accessible in MAXScript.

MAXWrapper : Value
The MAXWrapper class is the superclass of all classes in MAXScript that represent 3ds max objects,
such as scene nodes, modifiers, materials, etc. MAXWrapper values contain references to the
associated 3ds max objects that allow it keep track of the object. This allows MAXScript to know
when a 3ds max object is transformed, deleted by the user, or its properties are changed.
The properties, operators, and methods that are common to all classes derived directly from the
MAXWrapper class are described in the MAXWrapper Common Properties, Operators, and Methods
(p. 809) topic.
The following classes are derived directly from the MAXWrapper class. Other classes are derived from
these classes, and inherit the properties and methods defined for the MAXWrapper class.
 MAXWrapper Common Properties, Operators, and Methods 809

See also
Node (p. 820)
Modifier and SpacewarpModifier (p. 1095)
Material (p. 1203)
Atmospheric (p. 1337)
Controllers (p. 1300)
Render Effect (p. 1347)

MAXWrapper Common Properties, Operators, and Methods

The following properties and methods are applicable to any value that is derived from MAXWrapper.
Properties:
The following MAXWrapper value and class properties give you access to the plug-in category, such
as Standard Primitives, Extended Primitives, or Particle Systems:
<MAXWrapperobject>.category Name, read-only
<maxclass>.category Name, read-only
<maxsuperclass>.categories Array, read-only
The category property returns a Name value containing the category. You can use it on
either a 3ds max object class, such as Line, Box, or Fog, or on an instance of any 3ds max
object class. For scene nodes, the category usually corresponds to one of the names in the
drop down list in the Create panel. These are the categories such as
#Standard_Primitives, #Compound_Objects, and #Particles_Only.
For modifiers, the category determines which group the modifier appears in the Configure
Button Sets/Modifiers list. These are the categories such as #MAX_STANDARD, #MAX_EDIT,
and #MAX_SURFACE.
For textures, the category determines which group the texture appears in the Material/Map
Browser. These are the categories such as #2D (2D maps), #3D (3D maps), and #COMP
(Compositors).
The categories property can be used on any of the 3ds max object superclasses, such as
Shape, GeometryClass, Helper, SpacewarpObject, TextureMap, or Modifier, to get a list of
the available categories for that superclass, returned as an array of Names. For example:
$line01.category -- returns #Splines
Gengon.category -- returns #Extended_Primitives
Shape.categories -- returns #(#Shape, #Splines, #NURBS_Curves)
810 Chapter 11 | 3ds max Objects

<MAXWrapperobject>.classID
<maxclass>.classID
The classID property retrieves the internal 3ds max Class ID of the MAXWrapper classes
and objects. The value returned is an array containing two numbers, PartA and PartB of
the 3ds max internal class ID. For a MAXWrapper object, the value returned is the Class ID
of the class the object is an instance of. For example,
Box.classID -- returns #(16, 0)

b=box()
b.classID -- returns #(16, 0)

The combination of the PartA and PartB numbers is guaranteed to be unique for
each class.
<MAXWrapperObject>.superClassID
<maxclass>.superClassID
Retrieves the 3ds max superclass ID of the MAXWrapper classes and objects.
Methods:
copy <MAXWrapper_object>
The copy() function is implemented by all the 3ds max objects available in MAXScript,
such as scene objects, controllers, modifiers, materials, etc. You can use this function to
make a clone of the source object, for example in situations where you want individual
copies or you want to make a shared object unique. For example:
addModifier $foo $baz.bend

will cause foo to share the bend modifier on baz, whereas:

addModifier $foo (copy $baz.bend)

will give foo a separate clone of the bend modifier on baz. Any changes to the bend
modifier on foo will not affect baz and vice versa.
In the next example, we set up several objects all sharing a single rotation controller:
c = bezier_rotation()
$foo.rotation.controller = c
$baz.rotation.controller = c
$bar.rotation.controller = c

To later make one of the controllers unique, you could do this:

$baz.rotation.controller =
copy $baz.rotation.controller

When the MAXWrapper object is not a scene node, the copy is only created in MAXScript
memory. When the MAXWrapper object is a scene node, a new scene node is created
which is visible and accessible by the user in the 3ds max viewports.
 MAXWrapper Common Properties, Operators, and Methods 811

exprForMAXObject <MAXWrapper_object>
Returns a string containing a MAXScript expression that will ‘name’ the specified
MAXWrapper object using property access and indexes as needed. For example, if you
have in variable m a bend modifier on a scene object named “foo”, then:
exprForMAXObject m

would yield the string:

“$foo.bend”

This method is an exposure of an internal method that macro recorder uses, and its output
will vary depending on the macro recorder options.
b=box()
--> $Box:Box02 @ [0.000000,0.000000,0.000000]
c=b.pos.controller
--> Controller:Bezier_Position
exprformaxobject c
--> “$Box02.pos.controller”
bm=bend()
--> Bend:Bend
addmodifier b bm
--> OK
exprformaxobject bm
--> “$Box02.modifiers[#Bend]”
Here, changing the macro recorder options from “Explicit scene object names” to
“Selection-relative scene object names”, yeilds:
exprformaxobject bm
--> “$.modifiers[#Bend]”

createInstance <maxclass> [keyarg1:v] [keyarg2:v] ...

This method is used to directly create the ‘base objects’ that you see in a Node (or any
other object). The main use for this is to create temporary geometry base objects from
which meshes will be extracted to help create the meshes for scripted geometry primitive
plug-ins. The optional <keyargs> are the same base-object keyword arguments as can be
supplied for the class constructor. These are typically the parameters of the base object. For
example:
b = createInstance Box length:10 height:40 width:20

creates an instance of a Box. This box will not appear in the 3ds max viewports, as it is not
a node. It only contains the geometry associated with the Box object. You can get at the
mesh representation of these instanced objects with the mesh property, which yields a
TriMesh value.
replaceInstances <old_MAXWrapper> <new_MAXWrapper>
Replaces all instances of the old MAXWrapper with the new MAXWrapper. Old and new
MAXWrapper must have the same superclass.
Minimal error checking, use with extreme caution.
812 Chapter 11 | 3ds max Objects

-- Dependencies
An important internal mechanism in 3ds max defines the dependency relationship between
3ds max objects. For example, a material depends on its various maps, a path controller depends on
its percent controller, a scene node depends on its base object, etc. The following method returns
the MAXWrapper objects that depend on a specified MAXWrapper object.
refs.dependents <MAXWrapper_object>
Returns an array of the other 3ds max MAXWrapper objects depend on the specified
MAXWrapper object. The specified MAXWrapper object can be any MAXWrapper object,
such as a scene node, controller, material, modifier, etc.
For example:
refs.dependents $foo.material.diffuseMap

could return:
#(Material_#3, Material_#2, Map_#2:Noise, Material_#1)

which shows that the diffuseMap in $foo is referenced in material #1, material #2, material
#3, and noise TextureMap #2.
Example:
The following example shows several objects being created, and sets up controllers on the objects
which depend on other objects.
Script:
theSphere=sphere () -- create a sphere
theCone=cone radius1:0 radius2:20 -- create a cone
theHelix=helix height:100 pos:[100,100,0] -- create a helix
theCone.target=theSphere -- assign theSphere as target of theCone
-- a lookat controller is automatically
-- assigned to theCone
-- assign path controller to theSphere, path to follow is the helix
theSphere.position.controller=path path:theHelix
refs.dependents theSphere -- show dependents of the sphere
refs.dependents theCone -- show dependents of the cone
refs.dependents theHelix -- show dependents of the helix

Output:
$Sphere:Sphere02 @ [0,0,0] -- result line 1
$Cone:Cone02 @ [0,0,0] -- result line 2
$Helix:Helix02 @ [100,100,0] -- result line 3
$Sphere:Sphere02 @ [0,0,0] -- result line 4
Controller:Path -- result line 8
#(Controller:Look_At, $Cone:Cone02 @ [0,0,0]) -- result line 9
#() -- result line 10
-- following is output of line 11
#(Controller:Path, Controller:Position_Rotation_Scale, $Sphere:Sphere02 @ [0,0,0],
Controller:Look_At, $Cone:Cone02 @ [0,0,0])
 Access to MAXWrapper AppData 813

See also
Access to MAXWrapper AppData (p. 813)
Nested Object Controller Functions (p. 814)
Nested Object Properties (p. 815)
Note Track Access (p. 816)

Access to MAXWrapper AppData

The AppData access methods give a simple form of access to the AppData capability in the 3ds max
SDK. The AppData mechanism provides a way for plug-ins to attach arbitrary data to any 3ds max
object in a scene, such as nodes, materials, modifiers, controllers, etc., that is permanently stored
with that object in the 3ds max scene file.
The following methods are used to read and store AppData for a MAXWrapper object:
setAppData <MAXWrapper_object> <integer_ID> <string>
Sets the AppData item of the given ID number on the given 3ds max object to the
<string> value. This creates a new item if needed or replaces the string contents if an
item of that ID already exists.
getAppData <MAXWrapper_object> <integer_ID>
Returns the AppData item string of the given ID number from the given 3ds max object.
Returns the value undefined if the ID’d item is not present.
deleteAppData <MAXWrapper_object> <integer_ID>
Deletes the AppData item if the given ID number from the given 3ds max object.
clearAllAppData <MAXWrapper_object>
Clears out all MAXScript-related AppData items from the given MAXWrapper object.
You can add as many AppData strings as you like to an object--you assign them each an integer
identification number when they are first added and access them later using those IDs.
AppData strings can be attached to any MAXWrapper subclass instance, including scene nodes,
modifiers, controllers, materials, atmospherics, etc. Note that the AppData is stored in the scene file
only if its object is in the scene--if, for example, you create a material in MAXScript and do not assign
it to any object or the material editor, it will not be saved in the scene file nor will its AppData.
If you want to associate certain AppData strings with the scene as a whole, it is recommended that
you create a hidden dummy node with a unique name and attach the scene AppData to that node.
814 Chapter 11 | 3ds max Objects

AppData in its full generality allows the C++ plug-in developer to store arbitrary binary data with an
object. This is not directly possible with MAXScript, so the approach taken is to store and retrieve
AppData text strings that can be built-up or parsed into complex MAXScript objects using a
StringStream Value (p. 766). For example, to store some numbers in an array on a scene node, you
might do the following:
ss = StringStream ““
for v in data_values do print v to:ss
setAppData $foo 1 ss

and read them back after the scene has been saved and reloaded as follows:
ss = StringStream (getAppData $foo 1)
data_values = #()
while not eof ss do
append data_values (readValue ss)

Nested Object Controller Functions

Certain time and keyframe functions on controllers can be called on any 3ds max object or
collection of 3ds max objects. If called in this way, they apply recursively to all the nested controllers
within that object and on any on sub-objects and sub-controllers within those objects. In this way,
they work in a manner similar to the object-level tracks in the 3ds max Track View that allow you
to manipulate keys and time for all the sub-objects and sub-controllers within them.
The time and controller functions that work this way are:
deleteTime
reverseTime
scaleTime
insertTime
setTimeRange
addNewKey
deleteKeys
selectKeys
deselectKeys
moveKeys
sortKeys
reduceKeys
addEaseCurve
deleteEaseCurve
setBeforeORT
setAfterORT
enableORTs

The above functions can be called on any 3ds max object collection (such as a wild-card pathname
or object set or array of objects ) and will recursively apply to all animation within those objects. For
more information see Time and Key Functions on Object Hierarchies (p. 1299) and Controller Time
Functions (p. 1292).
 Nested Object Properties 815

Examples:
insertTime $box01.xform 0f 10f
-- all keys after 0f in all controllers in the XForm modifier are moved by 10f
insertTime $box01 0f 10f
-- all keys after 0f in box01 are moved (transform, creation, modifiers)
selectKeys $box02.xform.gizmo.rotation.controller 0f 100f
-- selects keys in 0-100f. If controller is Euler, will select x, y and z keys
deleteTime $box* 10f 10f
-- delete 10f at frame 10 in all keys in all objects named $box* (works with
-- any pathname or array of objects)
insertTime $box03.children 0f 10f
-- inserts time in all controllers of all children of $box03
reduceKeys $box01.modifiers
-- applies key reductions to all controllers in all modifiers in $box01 (leaves
-- transform and creation parameters alone)

Nested Object Properties

Several of the properties on 3ds max objects contain values that are themselves compound, for
example <node>.pos yields a Point3, which itself contains x, y and z properties. MAXScript
provides a mechanism that lets you modify these nested properties on MAXWrapper objects in place
such that assignment to them will affect that nested property on the 3ds max object. This
mechanism depends on the nested property being accessed in one, cascaded property access. For
example:
$foo.pos.x += 23 -- move the node 23 units in x
$baz.rotation.angle *= 2 -- double the rotation

If you first get the intermediate value into some variable and then set the property on that value,
the change will not be reflected in the original object, the connection is only maintained within a
single cascaded property access. For example:
p = $foo.pos -- get foo’s position as a ‘detached’ point3
p.x += 23 -- set the x prop of that point, it doesn’t know
-- about foo anymore, foo’s pos is not changed

In this case, you would have to explicitly re-assign the free-standing point to $foo’s position to affect
$foo:
$foo.pos = p -- set foo’s new position

In general, any property on a MAXWrapper object that is itself a foundation compound value such
as a Point3 or Quat will yield a free-standing value when simply accessed and supports object sub-
property assignment in cascaded property assignment.
816 Chapter 11 | 3ds max Objects

Note Track Access

All MAXWrapper objects can have one or more note tracks assigned to them. These note tracks are
visible in Track View as children of the MAXWrapper object. Note tracks provide a way for plug-ins
to attach data to any 3ds max object in a scene, such as nodes, materials, modifiers, controllers, etc.,
that is permanently stored with that object in the 3ds max scene file. This data is stored in note keys,
and a note track can contain any number of note keys.
The structure of note tracks is similar to the structure of key-able animation controllers. A note track
is an instance of the class, and has a property called keys. The value returned by accessing the keys
property is a MAXNoteKeyArray. The MAXNoteKeyArray contains the note keys. The keys
themselves are accessed as if the MAXNoteKeyArray was an array.

See also
Notetrack Values (p. 816)
MAXNoteKeyArray Values (p. 817)
MAXNoteKey Values (p. 818)
Working with Note Tracks (p. 818)

Notetrack Values
The following methods are related to creating, adding, deleting Note tracks. See the
MAXNoteKeyArray Values (p. 817) and MAXNoteKey Values (p. 818) topics for information on
accessing the contents of Note tracks.
Constructor:
notetrack <name_string>
Creates a new, empty note track with the specified name. The name is only used to
differentiate different note tracks in MAXScript but is not visible in 3ds max.
Properties:
<noteTrack>.keys MAXNoteKeyArray
<noteTrack>.name String
Methods:
getNoteKeyTime <notetrack> <index>
Returns the time of indexed note key.
getNoteKeyIndex < notetrack > <time>
Returns the index of the note key at the specified time.
Associated Methods:
addNoteTrack <MAXWrapper_object> <NoteTrack>
Adds a new note track to the MAXWrapper object.
deleteNoteTrack <MAXWrapper_object> <NoteTrack>
Deletes specified note track from the MAXWrapper object.
 MAXNoteKeyArray Values 817

hasNoteTracks <MAXWrapper_object>
Deletes specified note track from the MAXWrapper object.
numNoteTracks <MAXWrapper_object>
Returns the number of note tracks applied to the MAXWrapper object as an integer.
getNoteTrack <MAXWrapper_object> <index_integer>
Returns the indexed note track applied to the MAXWrapper object. Index is 1-based.

MAXNoteKeyArray Values
A MAXNoteKeyArray represents all the note keys in a 3ds max note track. See also MAXNoteKey
Values (p. 818) and Notetrack Values (p. 816). MAXNoteKeyArray values are mappable.
Constructors:
<NoteTrack>.keys
The note key array can be constructed by accessing the keys property on the note track.
Example:
nt=getNoteTrack $foo.position.controller 1 -- get first note track on
controller
ntk=nt.keys -- note key array for note track

Properties:
<NoteKeyArray>.count : Integer, read-only
returns the number of objects in set
Operators:
<NoteKeyArray>[<index_integer>] -- accesses member of collection. Indexes start
at 1.
Methods:
addNewNoteKey <NoteKeyArray> <time>
Adds a new note key to the note key array at the time specified. The value for the new note
key is a null string. Returns the note key added.
deleteNoteKeys <NoteKeyArray> ( #allKeys | #selection )
Deletes note keys from the note key array according to the optional symbolic argument
supplied.
#allKeys: deletes all keys in the note key array.
#selection: deletes the currently selected note keys
deleteNoteKey <NoteKeyArray> <index_integer>
Deletes the indexed note key. Key indexes are 1-based.
sortNoteKeys <NoteKeyArray>
Re-sorts note keys according to their times. Some MAXNoteKey operations can result in
out of order note keys and this function must be called to correctly order note keys.
818 Chapter 11 | 3ds max Objects

Associated Methods:
getNoteKeyTime <notetrack> <index>
Returns the time of indexed note key.
getKeyIndex < notetrack > <time>
Returns the index of the note key at the specified time.

MAXNoteKey Values
Note tracks store their notes as MAXNoteKeys. As seen by MAXScript, note keys are stored in a
MAXNoteKeyArray. The MAXNoteKeyArray for a note track is accessed via the keys property of the
note track.
For more information on MAXNoteKeyArrays, see the MAXNoteKey Values (p. 818) topic.
Constructor:
addNewNoteKey <MAXNoteKeyArray> <time> [ #select ]
Adds a new note key to the note track at the time specified. The new note key is also
selected in the track view if the #select optional argument is specified. The value for the
new note key is a null string.
<MAXNoteKeyArray>[<index_integer>]

Properties:
<MAXNoteKey>.time Time -- time value or number (interpreted as frames)
<MAXNoteKey>.selected Boolean -- specifies whether the key is selected. Read/
write access.
<MAXNoteKey>.value String -- string contained in the note key

Working with Note Tracks

Changing the time property of a note key may cause it to go out of time order relative to the other
keys in the controller. You must call the sortKeys() function on the controller or associated
MAXNoteKeyArray once all key time manipulations of this kind is complete so that animation will
perform correctly.
Example:
Script:
s = sphere() -- create a sphere
--
ntp1 = NoteTrack “PosNT1” -- create a note track
ntp2 = NoteTrack “PosNT2” -- create another note track
addNoteTrack s.pos.controller ntp1 -- apply first note track to sphere’s pos
controller
addNoteTrack s.pos.controller ntp2 -- apply second note track to sphere’s pos
controller
numNoteTracks s.pos.controller -- check number of note tracks on pos
controller
 Working with Note Tracks 819

hasNoteTracks s.pos.controller -- test to see if pos controller has note

tracks
--
addNewNoteKey ntp1.keys 20 #select -- add key to first note track, and select the
key
addNewNoteKey ntp1.keys 40 -- add another key to first note track
--
n = getNoteTrack s.pos.controller 1 -- retrieve first note track on the pos
controller
nk=n.keys -- retrieve an instance of the note track key
array
--
nk[2].value = “Yo What’s Up” -- set value for second note key
nk[2].time = 10 -- change the time for second note key. Now
first key
nk[1].selected = true -- select the first note key
sortNoteKeys nk -- changed the time of the note keys, so re-
sort
nk.count -- check number of keys
nk -- display the note keys
--
-- To delete the note tracks and note keys
deleteNoteKey nk 1 -- delete first note key
deleteNoteKeys n.keys #allKeys -- delete all the note keys
deleteNoteTrack s.pos.controller ntp1 -- remove note track from pos controller
deleteNoteTrack s.pos.controller ntp2 -- remove note track from pos controller

Output:
$Sphere:Sphere02 @ [0.0,0.0,0.0] -- result line 1
Notetrack:PosNT1 -- result line 3
Notetrack:PosNT2 -- result line 4
OK -- result line 5
OK -- result line 6
2 -- result line 7
true -- result line 8
#Note key(1 @ 20f) -- result line 10
#Note key(2 @ 40f) -- result line 11
Notetrack: -- result line 13
#keys(20f, 40f) -- result line 14
“Yo What’s Up” -- result line 16
10 -- result line 17
true -- result line 18
OK -- result line 19
2 -- result line 20
#keys(10f, 20f) -- result line 21
OK -- result line 24
OK -- result line 25
OK -- result line 26
OK -- result line 27
820 Chapter 11 | 3ds max Objects

Node : MAXWrapper
Nodes represent 3ds max scene objects such as geometry, cameras, shapes, etc. Each kind of 3ds max
scene object is represented by a class that inherits from Node.
The classes derived directly from the Node class are described in the Node Subclasses (p. 849) topic.
Other classes are derived from these classes, and inherit the properties and methods defined for the
Node class.
The properties, operators, and methods that are common to all classes derived directly from the
Node class are described in the Node Common Properties, Operators, and Methods (p. 820) topic.
The Node class is derived from the MAXWrapper class, and inherits the properties and methods
defined for that class. These properties and methods are described in the MAXWrapper Common
Properties, Operators, and Methods (p. 809) topic.

Node Common Properties, Operators, and Methods

The following properties and methods are applicable to any value that is derived from Node.
Constructors:
<non_wild_card_pathname>
identifies a unique node in the scene
<objectset>[<integer>]
<wild_card_pathname>[<integer>]
n’th scene object in collection
<node_constructor> [ name: <string> ] \
[ prefix: <string> ] \
[ material: <material> ] \
[ target: <node> ] \
[ pos: <point3> ] \ -- default [0,0,0]
[ position: <point3> ] \ -- synonym for pos
[ rotation: <quat> ] \ -- default 0 rotation
[ scale: <point3> ] \ -- default 100% scale
[ pivot: <point3> ] \ -- default normal node pivot
location
[ transform: <matrix3> ] \ -- default identity
[ isSelected: <boolean> ] \ -- default false
[ dir: <point3> ] -- set local z direction

The position and rotation values are relative to the current active grid if ‘coordsys grid’ is
the current working coordinate system.
A <node_constructor> is one of the scene node classes listed in Node Subclasses (p. 849),
such as box, sphere, quadPatch, splineShape, etc. For example:
b = box name:”foo” position:[10,10,10] height:20
 Working with Note Tracks 821

All of the node constructors can take the above optional keyword arguments, along with
any of general node properties or any of the properties for the particular node class as
keyword arguments.
The name keyword can be used to specify the name for the created node. 3ds max allows
the same name to be used for more than one node.
The prefix keyword can be used in place of the name keyword argument to specify the
start of the node name from which 3ds max will generate a unique name by adding a
series of digits, as it does when creating objects interactively.
For example:
for i in 1 to 100 do sphere prefix:”baz”
creates 100 spheres, giving each a unique name beginning with “baz”, such as
$baz01, $baz02, $baz03, etc.
The material keyword can be used to apply the specified material to the created node.
The target keyword can be used to automatically apply a LookAt controller to the node’s
transform track, and set the specified node as the LookAt target.
The transformation arguments, pos, scale, rotation, and pivot, are applied to the new
object in the order they are specified in the constructor call, so you can control transform
order. The pos, scale, and rotation arguments are mutually exclusive with the
transform argument which can be used as an alternative way to set the node’s complete
transform matrix in one go.
Note: Exercise care if you specify the target keyword. When you specify a target object,
3ds max stores with the target object the last object it was assigned as a target of. If you
delete the target object, the behavior of 3ds max is to also delete the object looking at it. If
the target object is a targetobject class object, deleting an object looking at it will also
delete the target object, even if another object is also looking at it.
Properties:
See the General Node Properties (p. 836) and Node Transform Properties (p. 841) topics for details about
the properties accessible on scene nodes.
Methods:
Most node methods are automatically mapped over node collections.
IsValidNode <var>
Returns true if <var> is a node value, and the node has not been deleted. Otherwise, it
returns false.
move <node> <point3> -- mapped
scale <node> <point3> -- mapped
rotate <node> <angle> <axis_point3> -- mapped -- angle in degrees
rotate <node> <quat> -- mapped
rotate <node> <eulerangles> -- mapped
all the transform operations operate in the current working coordinate system. See Context
Expressions (p. 681).
822 Chapter 11 | 3ds max Objects

copy <node> -- mapped

reference <node> -- mapped
instance <node> -- mapped
All the clone operations can take any of the standard node creation optional keyword
arguments which are applied after the node has been copied.
These functions clone all the original node’s transform controllers and keys and the
visibility controller and its keys if a visibility track has been assigned.
snapshot <node> -- mapped
This function provides functionality similar to the SnapShot tool in 3ds max. It generates
a new node that contains a copy of the world-state mesh of the source <node> at the time
that the snapshot is made. Any existing modifiers are collapsed out of the new node and
the mesh snapshot accounts for any space warps currently applied. As with the clone
methods (copy, reference and instance,) you can add any of the standard node creation
keyword arguments, such as pos:, name:, etc. The following example achieves an
animation-based snapshot similar to the SnapShot tool in 3ds max:
for t in 0 to 100 do at time t snapshot $foo

delete <node> -- mapped

Deletes the specified node(s).
instanceReplace <dest_node> <src_node> -- mapped
referenceReplace <dest_node> <src_node> -- mapped
Lets you turn existing nodes into instances and references to other nodes. You can use
these, for example, to replace the geometry of one node with another, perhaps for
implementing custom level-of-detail tools.
The <dest_node> is turned into an instance or reference to the <src_node>. As a new
instance, existing geometry and modifiers are removed and replaced by the <src_node>’s,
but all the node-related properties are kept, such as material, transform, visibility, name,
etc. As a new reference, the base object for the <dest_node> becomes the world-state of
the <src_node>, such that any changes to the src_node will affect the <dest_node>, but
changes to the <dest_node> are local to it.
It is possible to develop a custom scripted version of the File/Replace function with these
functions and the mergeMAXFile() function by temporarily changing the name of a
node in the current scene, merging in that named node from another, making the first
node an instance of the newly merged node with instanceReplace(), deleting the
newly merged node and renaming the old node back again.
Both these functions are collection mapped, so you can make a selection of objects all
instance or reference the same object, for example:
instanceReplace $foo* $baz
makes all the foo* objects be instances of baz’s geometry and modifier stack.
attachObjects <node1> <node2> [ move:<boolean> ]
Makes <node2> a child of <node1>. Resets the current location of <node2> to the
location of <node1> unless move:false is specified.
 Working with Note Tracks 823

getTMController <node>
Returns the transform controller for the node.
bindSpaceWarp <node> <spacewarp_node>
Binds the scene node to the space warp object scene node. Space warp bindings show up in
the modifier stack and can be accessed like any other modifier. Use the
deleteModifier() function to unbind objects from space warps. See the Modifier and
SpacewarpModifier (p. 1095) topic for more information about working with the modifier
stack.
getPolygonCount <node>
Returns a 2 element array containing the current number of faces for the node in the first
element, and the current number of vertices for the node in the second element. The
number of faces and vertices returned are the number that would be present if the node
was converted to a mesh object.
isShapeObject <node>
Returns true if the node is a shape object, false otherwise
numSurfaces <node>
Returns the number of parametric surfaces in the object. At the current time, Loft objects
are the only objects where more than one surface is present (ie. loft of a donut).
isSurfaceUVClosed <node> <surface_index_integer>
Returns a 2 element array indicating if the parametric surface is closed in the U and V
dimensions (ie. a torus is closed in both U and V). Note that not all objects have this
method implemented, and will return a default value of #(true, true).
getTransformAxis <node> <index>
Returns the transform axis of the indexed axis system of the node as a <matrix3> value.
Normally a node justhas 1 transform axis. In some cases (like being in the Local Reference
Coordinate System, in object SO mode, and having multiple SO selected), multiple
transform axes exist. If index > the number of transform axis, the transform for the first
transform axis is returned.
The transform returned by this method can be used in an “in coordsys” context and an
“about” context to move, rotate, or scale an object about the current 3ds max UI Reference
Coordinate System and Center.
824 Chapter 11 | 3ds max Objects

For example:
fn axisRotate obj rotation =
(local axis
local objA = if classof obj == objectSet or classof obj == array then obj
else #(obj)
if getCoordCenter() != #local then
(axis = getTransformAxis objA[1] 0
for obj1 in objA do in coordsys axis about axis rotate obj1 rotation
)
else
(for obj1 in objA do
(axis = getTransformAxis obj1 0
in coordsys axis about axis rotate obj1 rotation
)
)
)

invalidateTM <node>
Invalidates the node’s transformation matrix cache.
invalidateTreeTM <node>
Invalidates the node’s transformation matrix cach and notify the node’s subtree that the
transformation matrix has changed.
The following MAXScript function can be used to force an update of an object whose
transform is partially controlled by a scripted controller (such as a script controller on the
position track):
mapped fn TMInvalidate obj =
(at time (currenttime-1) obj.transform
nodeInvalRect obj
invalidateTreeTM obj
redrawViews()
)

invalidateWS <node>
Invalidates the node’s world space cache.
getNodeByName <string> exact:<boolean>
Returns first <node> with the specified name. String case is insensitive unless
exact:true.
Default is exact:false
snapshotAsMesh <node>
Returns world state of node as a <mesh> value.
 Working with Note Tracks 825

getInheritanceFlags <node>
setInheritanceFlags <node> (#all | #none | <bitarray>) keepPos:<boolean>
Get and set the inheritance flags for the specified node as an <bitarray>. If a bit is on,
the corresponding inheritance is turned on. The order of the bits is:
#{POS_X,POS_Y,POS_Z,ROT_X,ROT_Y,ROT_Z,SCALE_X,SCALE_Y,SCALE_Z}
If keepPos:false is specified, the node may move when an inheritance is turned on
or off.
getTransformLockFlags <node>
setTransformLockFlags <node> (#all | #none | <bitarray>)
Get and set the transform lock flags for the specified node as an <bitarray>. If a bit is on,
the corresponding transform lock is turned on. The order of the bits is:
#{POS_X,POS_Y,POS_Z,ROT_X,ROT_Y,ROT_Z,SCALE_X,SCALE_Y,SCALE_Z}
-- Render-Related Methods
getInheritVisibility <node>
Returns true if the node inherits the visibility of its parent object (if any), false if not.
setInheritVisibility <node> <boolean>
Sets whether the node inherits the visibility of its parent object (if any). If <boolean> is
true, node inherits visibility. If <boolean> is false the node does not inherit visibility.
getVisController <node>
Returns an instance of the node’s visibility controller. Returns undefined if the node does
not have a visibility track.
getImageBlurMultController <node>
Returns the node’s Image Motion Blur Multiplier controller. Returns undefined if not
Image Motion Blur Multiplier controller has been assigned to the node.
setImageBlurMultiplier <node> <time> <number>
Sets the node’s Image Motion Blur Multiplier value at the specified time to the specified
value
setImageBlurMultController <node> <controller>
Sets the node’s Image Motion Blur Multiplier controller to the specified controller
setMotBlur <node> <integer>
Sets which type of motion blur to use for node. If <integer> = 1, None. If <integer> =
2, Object Motion Blur. If <integer> = 3, Image Motion Blur.
setRenderable <node> <boolean>
Sets whether the node is renderable. If <boolean> is true, node is renderable. If
<boolean> is false the node is not renderable.
getRenderID <node>
Returns the RenderID of the node. A value of 65535 is returned if the scene has not yet
been rendered, or the node is not renderable. The RenderIDs of the nodes are output to the
NODE_RENDER_ID g-buffer channel by the renderer.
setRenderID <node> <integer>
Sets the RenderID of the node to the specified value. This value is not “sticky” - it is not
saved with the scene, and it will be replaced by the renderer when the next render occurs.
826 Chapter 11 | 3ds max Objects

-- Group-Related Methods
group <node> [ name:<string> ] [ prefix:<string> ] \
[ select:<boolean> ] -- mapped
Makes a group of the given nodes and returns the group node. You can optionally specify
the group name or group name prefix. Not specifying a name or specifying a group name
prefix ensures that the group name assigned is unique. Specifying select:true selects
the group after it is made.
For example:
group $box* name:”boxes”
makes a group of all box*’s named “boxes”.
group selection
groups current selection.
ungroup <group_head_node> -- mapped
Ungroups one level of a group node.
For example:
ungroup $group01
ungroups group $group01
explodeGroup <group_head_node> -- mapped
Ungroups all levels in a group node.
isGroupHead <node>
Returns true if node is group head, false otherwise.
isGroupMember <node>
Returns true if node is in a group, false otherwise.
isOpenGroupMember <node>
Returns true if <node> is a member of a group, and that group is open.
isOpenGroupHead <node>
Returns true if <node> is the head of a group, and that group is open.
setGroupOpen <group_head_node> <boolean>
Sets whether the group is set as open or closed. If <boolean> is true, the group is set as
open. If <boolean> is false the group is closed.
 Working with Note Tracks 827

*** Use the following methods with care. You can place nodes in states that are impossible to
accomplish using the 3ds max user interface. ***
setGroupMember <node> <boolean>
Sets whether the node is a group member or not. If <boolean> is true, node is set as a
group member. If <boolean> is false, and the node is a group member, the node is set as
not being a group member and is unlinked from the group head.
Note: If you set a node to be a group member using this method, you need to set the node
to be a child of a group head. Otherwise, the node name is not shown in the Select By
Name dialog. For example:
setGroupHead $dummy01 true
append $group03.children $dummy01

setGroupHead <node> <boolean>

Sets whether the node is flagged as a group head or not. If <boolean> is true, node is
flagged as a group head. If <boolean> is false, the node is set as not being a group head.
Note: If you flag a node as a group head using this method, the node’s mesh will not be
displayed in the viewports, and its properties will not be shown in the Modify panel. If
you flag a group head node as not being a group head using this method, you will not be
able to Open or Explode the group via the Group menu command.
Example:
-- create a set of spheres, group them, and test group head and member of group
mySpheres=for i=1 to 5 collect sphere pos:(random [-100,-100,0] [100,100,0])
group MySpheres name:”MyGroup”
isGroupHead $MyGroup -- returns true
isGroupMember $sphere01 -- returns true

-- check to see if group is open. Open group and test member of group
isOpenGroupHead $MyGroup -- returns false
setGroupHeadOpen $MyGroup true
isOpenGroupMember $sphere01 -- returns false

-- create a new set of spheres, append the group to the set, and then group them all
NewSpheres=for i=1 to 3 collect sphere pos:(random [-100,-100,0] [100,100,0])
append NewSpheres $MyGroup
group NewSpheres name:”BiggerGroup”

-- open the group head, test member of group, and then close the groups.
setGroupHeadOpen $BiggerGroup true
isOpenGroupMember $MyGroup
setGroupHeadOpen $MyGroup false
setGroupHeadOpen $BiggerGroup false
828 Chapter 11 | 3ds max Objects

-- Node Viewport State Methods

hide <node> -- mapped
unhide <node> -- mapped
freeze <node> -- mapped
unfreeze <node> -- mapped
flagForeground <node> <boolean> -- mapped
Controls the disposition of scene nodes in the viewport foreground/background planes, so
you can influence interactive performance on a node. Nodes placed in the foreground
plane are redrawn individually and so interactive changes to them through spinners in
scripted rollout panels are much faster.
The boolean argument puts the scene node(s) into the foreground plane if true, or into
the background plane if false. You should be judicious in putting nodes in the
foreground plane, because putting too many objects in the foreground plane reduces the
foreground plane’s effectiveness. Remember to unflag objects when you don’t need to
interactively control them any more.
getTrajectoryOn <node>
Returns true if Trajectory is shown for the node, false otherwise.
setTrajectoryOn <node> <boolean>
Sets whether Trajectory is shown for the node. If <boolean> is true, Trajectory is shown.
If <boolean> is false, Trajectory is not shown.
isBoneOnly <node>
Returns true if the node’s showLinksOnly property is true.
getCVertMode <node>
Returns true if node is displayed using vertex colors in shaded viewports, false
otherwise.
setCVertMode <node> <boolean>
Sets whether to display the effect of assigned vertex colors for the node in shaded
viewports. If <boolean> is true, node is displayed using vertex colors. If <boolean> is
false, node is displayed using the material or wireframe color.
getShadeCVerts <node>
Returns true if the vertex color display for the node is shaded in the viewports, false
otherwise.
setShadeCVerts <node> <boolean>
Sets whether the vertex color display for the node is shaded in the viewports. When true,
the colors are unshaded and appear in their pure RGB values. When false, the colors
appear like any other assigned color in the viewports.
 Working with Note Tracks 829

-- Node Selection Methods

clearSelection()
clearNodeSelection [ redraw:<boolean> ]
Deselects all currently selected scene nodes. Scene is redrawn unless redraw:false is
specified.
deselect <node> -- mapped
Deselects the given node(s).
For example:
deselect $box*
deselects all items whose names start with “box”.
deselectNode <node>
Deselects a single node
select <node> -- mapped
Deselects any currently selected objects and then selects the node(s) you specified.
selectMore <node> -- mapped
Adds the node(s) to the set of selected objects. If you want to build a set of selected objects
from scratch in a loop, you can use clearSelection() to clear the selection before
entering the loop, and use selectMore() in the loop to add objects to the set of selected
objects.
-- Modifier Stack Related Methods
validModifier [ <node> | <objectset> | <group> ] <modifier>
Tests whether a particular modifier may be added the given <node> or to all of the objects
in the objectset or group. Returns true if so, false if not.
The validModifier() method operates exactly as does the Modify panel in determining
modifier applicability. Any modifier that takes a deformable object will return true for all
scene objects except Helpers. This corresponds to the Modify panel’s behavior of allowing
modifiers such as Bend, Taper, etc. to be applied to lights and cameras, space warp objects,
etc., as well as geometry types like box, sphere, etc., but not helpers such as dummys or
bones.
The validModifier() method will return true if an empty <objectset> is specified, or
if a <group> is specified and the modifier is valid for all members of the group. In these
cases, applying the modifier using the addModifier() method will fail, because the
<objectset> is empty in the first case, or because the modifier cannot be applied to the
dummy object that is the parent object of the objects in the group. You will need to test for
these conditions in your script, or use the modPanel.addModToSelection() method
described in the Modify Panel (p. 1572) topic.
addModifier <node> <modifier> [before:index] -- mapped
Applies the modifier to all instances of the node(s) to which the function is applied. The
optional before: keyword argument can be used to insert the modifier into the node’s
modifier stack just before the indexed modifier, counting from the top of the stack. The
added modifier will apply to any appropriate active sub-object selection in the node only if
830 Chapter 11 | 3ds max Objects

the node is currently selected and open in the Modify panel at the desired sub-object level.
You can use the 3ds max System global variable, subObjectLevel to test and set the level
for the object currently open in the Modify panel. For example:
max modify mode -- open mod panel
select $box01 -- select box01 into mod panel
subObjectLevel = 3 -- subobject level to Face
addModifier $box01 (ffd_2x2x2()) -- add FFD mod to those faces

If <node> is a collection, an instance of the modifier is placed on each of the nodes in the
collection. Unlike interactively applying a modifier to a selection, the position and size of
each modifier instance’s gizmo corresponds to position and size of the node the modifier
instance is applied to. To apply a modifier to a collection in the same manner that 3ds max
applies modifiers, use the modPanel.addModToSelection() method described in the
Modify Panel (p. 1572) topic.
Also see the Modifier and SpacewarpModifier (p. 1095) topic for more details.
deleteModifier <node> <modifier_or_index> -- mapped
Lets you delete modifiers from the modifier stack. Takes either a modifier value which is
present on the <node> stack, or an index specifying the index of the modifier to delete,
counting from the top of the stack.
collapseStack <node> -- mapped
Collapses the modifiers out of a stack, leaving a resultant editable mesh as the base object
of the node(s). If there are no modifiers in the stack when this is called, no action is taken.
If you want to force an object to be an editable mesh, use the function convertToMesh().
-- Node Modifier Transform Context Methods
getModContextTM <node> <modifier>
Returns a Matrix3 value giving the modifier’s context transform for the local coordinates
used in modifier sub-object gizmos. Accessing the transform properties of a modifier sub-
object such as a gizmo or a center in MAXScript yields values that are relative to that
modifier’s context transform, equivalent to the values shown in track view for those
properties. If the modifier is not operating on a sub-object selection, such as a face or
vertex selection, or if the modifier was interactively applied to an object selection, this
context TM is the local coordinate space of the object itself. However, if the modifier is
operating on either an object selection set or a sub-object selection, the context transform
gives the position and orientation of that selection, and so you can use the
getModContextTM() function to get the world-space transform properties of any of its
sub-objects.
 Working with Note Tracks 831

getModContextBBoxMin <node> <modifier>

getModContextBBoxMax <node> <modifier>
These functions complement the getModContextTM() function and can be used to derive
the world-space coordinates of the bounding box of the modifier context. This can be
used, for example, to determine the bounds of a modifier operating on a sub-selection or
the bounds of an FFD lattice. This is particularly useful for scripting FFD control point
placement, since these control points live in a 0-to-1 lattice space--the mod context
bounding box gives the world space bounds of this lattice space allowing you to compute
scaled lattice space coordinates from world coordinates. The functions return Point3
values for the minimum and maximum extents of the bounding box.
See the Modifier Sub-Object Transform Properties (p. 1099) topic for examples of using the above
methods.
-- Node Conversion Methods
convertToMesh <node> -- mapped
This function converts appropriate scene object types into Editable Meshes. It is similar to
collapseStack() in that it will remove all modifiers present, but unlike
collapseStack() it will always replace the base object with an editable mesh version,
even if there are no modifiers present.
convertToMesh() can be applied to any object that an Edit Mesh modifier can work on,
such as geometry and shapes, but not helpers, space warps, lights, etc. If the object cannot
be converted, the function returns undefined.
convertToSplineShape <node> -- mapped
Converts the given scene node to a SplineShape object. If the object cannot be converted
(typically, if it is not a shape), the function returns undefined. Any modifiers present will
be collapsed. The collapseStack() function can also be used as can the collapse button
in the modifier stack dialog in 3ds max; both generate a SplineShape, but will only do so if
there is at least one modifier present.
canConvertTo <node> <class>
Allows you to test whether a given node is convertible into a given class. Returns true or
false. For example:
if canConvertTo $foo NURBSSurface then ...

The kinds of classes you can convert objects to are the generic editable forms including
Mesh, SplineShape, NURBSCurve, NURBSSurface, etc.
convertTo <node> <class> -- mapped
This function is a general form of the existing specific conversion functions such as
convertToMesh(), convertToSplineShape(), etc. For example,
convertToSplineShape() can be written:
convertTo $circle01 SplineShape

If the conversion is not supported, the function returns the value undefined.
832 Chapter 11 | 3ds max Objects

convertToNURBSSurface <node> -- mapped

convertToNURBSCurve <node> -- mapped
These functions work on those primitive geometry and shape classes that support
conversion to NURBS (such as boxes, spheres, circles, lines, etc.). If an object does not
support conversion, the function returns undefined.
-- Node Utility Methods
isDeleted <MAXWrapper_object>
This function yields the result true if the object has been deleted and false if it still
exists in the scene. Using the function only makes sense in situations where references to
3ds max objects are held in variables or arrays or passed as parameters and you want to
determine whether the object has been deleted from the scene. Performing an operation
on a deleted 3ds max object referenced in a variable or array otherwise generates an
exception. Any kind of 3ds max object can be tested in this way, scene objects, modifiers,
controllers, materials, etc.
For example:
sel = selection as array -- snapshot selection
...
-- <one or more objects in the selection are deleted,
-- by the user or other scripts>
...
for obj in sel
where not isDeleted obj do
move obj [10,0,0]

distance <node> <node>

Computes the distance between the pivot points of the two specified nodes.
intersectRay <node> <ray>
Computes the closest intersection of the ray and the surface of the given node. Returns
another Ray which defines the position of intersection in 3D space and the surface normal
direction vector at that point. The intersection test respects the face normals of the node,
i.e. if a face’s normal points away from the ray’s source, an intersection test is not
performed on that face. intersectRay() works if the world state of the node (the state of
the node at the top of the node’s stack) has a surface, such as an editable mesh, a Standard,
Extended, or Compound Primitive, or a Patch or NURBS surface object. Splines and NURBS
curves do not have a surface. Returns undefined if the ray doesn’t intersect the node, the
faces it does intersect point away from the ray’s position, or the node does not have a
surface.
 Working with Note Tracks 833

intersectRayEx <node> <ray>

Takes a ray and computes the closest intersection to the surface of the given node. It
returns an array with the following three elements.
1.A Ray defining the position of intersection in 3-space and the surface normal direction
vector at the point.
2.The index of the face the ray intersects with
3.The barycentric coordinates of the face that was hit.
This method only works if the world state of the node is a mesh, either because it started as
an editable mesh or because it has modifiers applied that convert the node to a mesh.
Unlike intersectRay(), this method will not work if the node is a Standard or Extended
Primitive - the node’s stack must evaluate to a mesh. The intersection test respects the face
normals of the node, i.e. if a face’s normal points away from the ray’s source, an
intersection test is not performed on that face. Returns undefined if the ray doesn’t
intersect the node, the faces it does intersect point away from the ray’s position, or the
node isn’t a mesh.
Barycentric coordinates are the coordinates relative to the triangular face. The barycentric
coordinates of a point p relative to a triangle describe that point as a weighted sum of the
vertices of the triangle. If the barycentric coordinates are b0, b1, and b2, then:
p = b0*p0 + b1*p1 + b2*p2;

where p0, p1, and p2 are the positions of the vertices of the triangle. The Point3 returned
by this method has the barycentric coordinate stored in its three component values. The
coordinate is relative to the triangular face that was intersected. Barycentric coordinates
can also be used to interpolate any quantity whose value is known at the vertices of the
triangle.
Following is an example of finding the UV coordinates at the intersection point:
Script:
s = sphere material:(standardMaterial diffuseMap:(checker()))
showTextureMap s.material s.material.diffuseMap on
--
-- Add a normal modifier to make the sphere into a mesh
addModifier s (normalModifier())
r = ray [-100,5,0] (s.center-[-100,5,0])
--
-- Get the Intersection details
arr = (intersectRayEx s r)
--
-- Create a dummy at the point of intersection
dummy pos:(arr[1]).pos
--
-- Get the texture face
tf = getTVFace s arr[2]
--
-- Get the UVW verts of the face
tv1 = getTVert s tf.x
834 Chapter 11 | 3ds max Objects

tv2 = getTVert s tf.y

tv3 = getTVert s tf.z
--
-- Calculate the texture vertices at point of intersection from
-- the barycentric coordinates
tv = tv1*arr[3].x + tv2*arr[3].y + tv3*arr[3].z
--
-- Delete the modifier
deleteModifier s 1

intersects <node> <node>

Returns true if the bounding boxes of the two specified nodes overlap, or false if they
do not overlap.
printStack <node>
Prints a representation of the current modifier stack for the given node.
-- Node User Properties
getUserProp <node> <key_string>
Retrieves the node’s user property with the given key as a string. <key_string> is either a
String or a Name value. If the key does not exist, a value of undefined is returned.
setUserProp <node> <key_string> <value>
Sets the node’s user property with the given key to the given value.
getUserPropBuffer <node>
Retrieves the entire user property buffer as a string containing all the user property
settings. This is effectively the contents of the User Defined Properties box in the 3ds max
Object Properties dialog.
setUserPropBuffer <node> <string>
Sets the user property buffer to the given string.
See the Node User-Defined Properties and Methods (p. 848) topic for more information on
these methods.
-- Inverse Kinematics Properties
The following methods get and set the node’s IK values as seen in the Hierarchy panel, Object
Parameters rollout.
getRotTaskWeight <node>
Returns the rotation binding weight for the node.
setRotTaskWeight <node> <float>
Sets the rotation binding weight for the node.
getPosTaskWeight <node>
Returns the position binding weight for the node.
setPosTaskWeight <node> <float>
Sets the position binding weight for the node.
getTaskAxisState <node> <pos_or_rot_integer> <axis_integer>
Returns true or false to indicate if the specified axis is turned on for position or rotation
binding. If an axis is turned off, the specified axis is no longer influenced by the follow
 Working with Note Tracks 835

object or the IK Controller Position end effector. <pos_or_rot_integer> sets whether

the method returns the position state or the rotation state: 0 specifies position; 1 specifies
rotation. <axis_integer> sets the axis to check: 0 specifies X, 1 specifies Y, 2 specifies Z.
setTaskAxisState <node> <pos_or_rot_integer> <axis_integer> <boolean>
Sets the axis state for position or rotation binding to the specified boolean value. See
getTaskAxisState() for a description of the parameters.
mirrorIKConstraints <node> <axis_integer> <pos_or_rot_integer>
Mirrors the specified IK constraints on the specified node’s transform controller about the
specified axis. <axis_integer> specifies the axis of reflection: 0 for X, 1 for Y, 2 for Z.
<pos_or_rot_integer> specifies which type of constraints are being mirrored: 0 for
position, 1 for rotation.
nodeIKParamsChanged <node>
Call this method when one of the node level IK parameters has been changed.
OKToBindToNode <ik_node> <node>
Returns true if the <ik_node> can be bound to the <node> as a follow object, false
otherwise. If the <ik_node> is not part of an IK system, this method always returns true.
This method tests <node> to see if its transform is in any way already dependent on the IK
system, and returns false if it is.
Miscellaneous Methods:
classOf <node>
Returns the class of the world state of the node (the state of the node at the top of its
stack). If no modifiers are applied to the base object, the class returned is the class of the
base object. If modifiers are applied to the base object, the class returned is the class of the
node as it exits the last modifier. For example, if you apply a Bend modifier to a Box, the
Bend modifier converts the incoming Box primitive to a mesh, and the class returned by
classOf is Editable_Mesh. You can get the class of the base object in all cases by using
classOf <node>.baseObject.
isPointSelected <node> <point_index>
Returns true if the specified point is selected, false if not. The definition of a ‘point’ varies
depending on the object type. For meshes, it is the mesh vertex. For a spline, it is the knot.
For NURBS objects, it is the vertex or control point.
pointSelection <node> <point_index>
Returns a floating point weighted point selection if the object supports soft selections.
Most object types just return 1.0 if the point is selected and 0.0 if not. Only NURBS and
Editable Mesh objects currently support weighted point selection.
nodeInvalRect <node>
Invalidates the rectangle in the viewports that the node is occupying. Rectangles flagged as
invalid will be update on the next screen redraw.
stopCreating <node>
This method stops the creation of the current object, if any. This method is primarily used
to ensure that a NURBS objects is fully created, which it until the creation is stopped. This
method will also deactivated any activated object create buttons in the Create panel.
836 Chapter 11 | 3ds max Objects

Associated Methods:
uniqueName <prefix>
Generates a unique scene node name from a prefix string by adding a series of digits, in
the same manner the 3ds max does as you create objects in the scene. This name is only
guaranteed to be unique until the next scene node creation. For example:
$foo.name = uniqueName “foo”

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
General Node Properties (p. 836)
Node Transform Properties (p. 841)
Node User-Defined Properties and Methods (p. 848)
Nested Object Properties (p. 815)
Class and Object Inspector Functions (p. 799)
Dynamic Properties (p. 805)
Node Subclasses (p. 849)
NURBS Node Properties and Methods (p. 1397)

General Node Properties

All the properties listed here are accessible on any node subclass. Unless otherwise noted, these
properties can not be animated.
<node>.name String default: varies
Get or set the scene object’s name.
<node>.baseObject A subclass of Node default: varies -- read-only
Retrieve the base object in a scene node. This has relevance in nodes that have modifiers
present that change the node type as it is processed up the stack. For example, a line with
an extrude modifier starts out as a Shape and turns into an Editable Mesh at the top of the
stack, its so-called world state. The baseObject property gives you access to the base
object in the modifier stack. Because the classOf() function on scene node objects
returns the class of the world state object (the top of the stack), you can use the
baseObject property to determine the class of the original object used to create the node.
This property is read-only.
<node>.material Material default: undefined
Get or set the object’s material.
 General Node Properties 837

<node>.parent Node default: undefined

Get or set the parent of the object. If the object is a top-level object, accessing the parent
property will return undefined. For example,
foo_mom = $foo.parent
$foo.parent = $baz

Setting the this property has the effect of detaching <node> from its original parent and
attaching it as a child of the specified node.
You can detach an object and make it a top-level object by assigning undefined to the
parent property:
$foo.parent = undefined

<node>.children NodeChildrenArray default: undefined

This yields a special array subclass, NodeChildrenArray. See the NodeChildrenArray Values
(p. 785) topic. A NodeChildrenArray can be accessed using normal MAXScript array
indexing and can be sequenced over in a for loop or with collection-mapped functions, for
example:
c = $foo.children[i]
move $foo.children [10,10,10]
for c in $baz.children do print c

You can get the number of children via the count property:
num_children = $foo.children.count

You cannot directly set a child by indexing into NodeChildrenArray, but you can
append new children using the append() function and delete children using the
deleteItem() function:
$foo.children[$foo.children.count+1]=$baz -- does not work
append $foo.children $baz -- works
deleteItem $foo.children $baz -- removes $baz as child

The ordering of child indexes corresponds to the ordering shown in the 3ds max hierarchy
view, which is the order in which the children were added to the parent.
<node>.mesh TriMesh
For scene nodes or base objects that are Editable Mesh objects, or are convertable to
Editable Mesh objects, this property yields a TriMesh containing a copy of the source
object’s mesh after any modifiers have been applied, but before any space warps have been
applied. This property is read-only unless the scene node or base object is an Editable Mesh
object, in which case the specified TriMesh replaces the base object. See the Editable_Mesh :
GeometryClass and TriMesh : Value (p. 1041) topic for more information on TriMesh and
Editable Mesh.
838 Chapter 11 | 3ds max Objects

-- Target/LookAt Related Properties

<node>.isTarget Boolean default: false
Returns true if then node is the target of another object’s LookAt controller, false if it is
not. If the object is the automatically created target object of a light’s or camera’s LookAt
controller, and you set this property to false, you can delete the target object without
causing the light or target to be deleted.
<node>.lookAt Node default: undefined
Get a node that is looking at <node>, or set a node to look at <node>. This is the converse
of the <node>.target property. If <node> is not the target of some object’s LookAt
controller, the value undefined is returned. If <node> is the target of more than one
object, only one such object is returned. If this property is used to set <node> as the target
of another object, a LookAt controller is automatically assigned to that object.
<node>.target Node default: undefined
Get or set the target node for <node>’s LookAt controller. Returns undefined if there is no
target or the node does not have a LookAt controller. If this property is used to set an
object as the target of <node>, a LookAt controller is automatically assigned to <node>.
Exercise care if you assign a node to the target property. When you specify a target
object, 3ds max stores with the target object the last object it was assigned as a target of. If
you delete the target object, the behavior of 3ds max is to also delete the object looking at
it. If the target object is a targetobject class object, deleting an object looking at it will also
delete the target object, even if another object is also looking at it.
<node>.targetDistance Float default: undefined
Get or set the distance from the node to its target. Returns undefined if <node> does not
have a target. Setting this property moves the target along the object-to-target vector to
the distance specified. For example,
$spot01.targetDistance
$cam2.targetDistance = 100

-- Viewport Related Properties

<node>.isSelected Boolean default: false
Get or set whether the node is selected.
<node>.isHidden Boolean default: false
Get or set whether the node is flagged as hidden in the viewports. A node may be hidden
even if this property is false. If the node’s category is marked as hidden in the Hide by
Category rollout in the Display panel, or if the node is flagged as frozen and Hide Frozen
Objects is on in the Hide rollout in the Display panel, the node will be hidden regardless of
this property’s value.
<node>.xray Boolean default: false
Get or set whether the node is displayed in See Through mode in shaded viewports.
<node>.ignoreExtents Boolean default: false
Get or set whether the extents of the node is ignored when performing a zoom extents.
 General Node Properties 839

<node>.boxMode Boolean default: false

Get or set whether the node is displayed in box mode in the viewports.
<node>.allEdges Boolean default: false
Get or set whether all the node’s edges are displayed in the viewports.
<node>.backFaceCull Boolean default: false
Get or set whether the node’s back faces are culled (not displayed) in the viewports.
<node>.wireColor Color default: random color
Get or set the node’s wireframe color
<node>.showLinks Boolean default: false
Get or set whether to display a wireframe representation of the hierarchical link(s) from
the node to its children.
<node>.showLinksOnly Boolean default: false
Get or set whether to display only the wireframe representation of the hierarchical link(s)
for the node. Setting this property to true also sets showLinks to true.
<node>.isFrozen Boolean default: false
Get or set whether the node is frozen in the viewports.
<node>.showTrajectory Boolean default: false
Get or set whether the node’s trajectory is displayed in the viewports.
<node>.showVertexColors Boolean default: false
Get or set whether to display the effect of assigned vertex colors for the node in shaded
viewports.
<node>.vertexColorsShaded Boolean default: false
Get or set whether the vertex color display for the node is shaded in the viewports. When
true, the colors are unshaded and appear in their pure RGB values. When false, the
colors appear like any other assigned color in the viewports.
<node>.isDependent Boolean default: false
Returns true if the node has its dependent flag set, otherwise returns false. A node is
dependent in the sense of 3ds max’s Views/Show Dependencies mode. When the Modify
panel is open, Show Dependencies will show all the nodes that are dependent on the
current modifier or object being editing by highlighting them in green, and the dependent
flag for the node is set. This property will always return false if the Modify panel is
closed, or if Views/Show Dependencies is off. This property is read-only.
-- Rendering Related Properties
<node>.castShadows Boolean default: true
Get or set whether the node casts shadows when rendered. This property parallels the Cast
Shadows property in an object’s right-click Object Properties dialog.
<node>.receiveShadows Boolean default: true
Get or set whether the node casts shadows when rendered. This property parallels the
Receive Shadows property in an object’s right-click Object Properties dialog.
840 Chapter 11 | 3ds max Objects

<node>.gbufferChannel Integer default: 0

Get or set the node’s g-buffer Object ID channel value. Valid object ID values in 3ds max
range from 0 to 65535. This property parallels the G-Buffer Object Channel property in an
object’s right-click Object Properties dialog.
<node>.visibility Boolean default: true -- animatable
This is a boolean property (unlike its value as a signed float in the 3ds max Track View) -
true or on denotes visible, false or off invisible. Animate this property to control an
node’s visibility at render-time, for example:
animate on
(
at time 0 $foo.visibility = on
at time 35 $foo.visibility = off
at time 57 $foo.visibility = on
)

The controller for this property is stored in the 1st subAnim of the node. You can access
this controller as:
<node>[1].controller -- the visibility controller

You can also get a node’s visibility controller using the getVisController() method.
<node>.inheritVisibility Boolean default: true
Get or set whether the node inherits the visibility of its parent object (if any). This
property parallels the Inherit Visibility property in an object’s right-click Object Properties
dialog.
<node>.renderable Boolean default: true
Get or set whether the node is renderable.
<node>.renderOccluded Boolean default: false
Get or set whether to Render Occluded Objects behind the node. This property parallels
the Render Occluded Objects property in an object’s right-click Object Properties dialog.
<node>.motionBlurOn Boolean default: true
Get or set whether motion blur is enabled for the object. This property parallels the
Motion Blur Enabled property in an object’s right-click Object Properties dialog.
<node>.motionBlurOnController Controller default: undefined
Get or set the motion blur on/off controller used for the node.
<node>.motionBlur Name default: #none
Get or set the type of motion blur to be used for the node. Valid parameter values are:
#none, #object, and #image. For backward compatibility, this property can also be set to
false for none or true for object motion blur. This property parallels the Motion Blur
type specified in an object’s right-click Object Properties dialog.
 Node Transform Properties 841

<node>.imageMotionBlurMultiplier Float default: 1.0 -- animatable

Get or set the node’s image motion blur multiplier value. The controller for this property is
stored in the 6th subAnim of the node. You can access this controller as:
<node>[6].controller -- the imageMotionBlurMultiplier controller

You can also get and set a node’s imageMotionBlurMultiplier controller using the
getImageBlurMultController() and setImageBlurMultController() methods.
<node>.rcvcaustics Boolean default: true
Get or set whether the node receives caustics. Caustics are not supported by the 3ds max
scanline renderer.
<node>.generatecaustics Boolean default: false
Get or set whether the node generates caustics. Caustics are not supported by the 3ds max
scanline renderer.
<node>.rcvGlobalIllum Boolean default: true
Get or set whether the node receives global illumination. Global illumination is not
supported by the 3ds max scanline renderer.
<node>.generateGlobalIllum Boolean default: false
Get or set whether the node generates global illumination. Global illumination is not
supported by the 3ds max scanline renderer.

Node Transform Properties

Unless otherwise noted, the following transform properties are always interpreted with respect to
the current working coordinate system as defined by the currently active coordsys context (p. 681).
The default coordsys is world. The pos, rotation, and scale properties of a node are aliases to
the corresponding subcontroller for the node’s transform controller. If the transform controller does
not have one of these subcontrollers, accessing the corresponding node property will result in an
“Unknown property” error message. For example, the LookAt controller does not have a Rotation
subcontroller, and the IK controller does not have any subcontrollers. You can still access the
transform values using the Matrix3 properties of the node’s transform property, for example,
objpos=obj.transform.translationpart.
<node>.transform : Matrix3 -- can read/write to. If written to,
: the Matrix3 value is decomposed into its
: position, rotation, and scale values, and these
: values are stored in the respective position,
: rotation, and scale controllers, if those
: controllers exist and can be written to.

<node>.pos : Point3 -- can use .position synonym throughout

<node>.pos.controller : Controller -- can use .track synonym throughout
<node>.pos.isAnimated : Boolean, read-only -- true if position is animated
<node>.pos.keys : MAXKeyArray
<node>.pos.track : Controller -- synonym of .pos.controller

<node>.rotation : Quat
842 Chapter 11 | 3ds max Objects

<node>.rotation.x_rotation : X rotation of node

<node>.rotation.y_rotation
<node>.rotation.z_rotation
<node>.rotation.controller
<node>.rotation.isAnimated
<node>.rotation.keys
<node>.rotation.track
: Y rotation of node
: Z rotation of node
: Controller -- can use .track synonym throughout
: Boolean, read-only -- true if rotation is animated
: MAXKeyArray
: Controller -- synonym of .rotation.controller

<node>.scale : Point3 -- fraction

<node>.scale.controller : Controller -- can use .track synonym throughout
<node>.scale.isAnimated : Boolean, read-only -- true if scale is animated
<node>.scale.keys : MAXKeyArray
<node>.scale.track : Controller -- synonym of .scale.controller

<node>.dir : Point3 -- local z-axis direction vector

Rotates node so that the node’s Z axis points in the specified direction. The node is rotated
around its Z axis such that the Y axis points as much as possible in the world -Z direction.
<node>.max : Point3, read-only -- max coordinates of node’s
bounding box
<node>.min : Point3, read-only -- min coordinates of node’s
bounding box
<node>.center : Point3 -- coordinates of center of node’s bounding box

<node>.transform : Matrix3 -- node’s main transformation matrix

Note that rotation in the internal transformation matrices is left-handed in contradiction
to the 3ds max user interface and MAXScript. Take care when mixing rotation derived
from these matrices and rotation used in rotation-related functions or from rotation
properties.
<node>.pivot : Point3 -- node’s pivot point position

<node>.objectOffsetPos : Point3
<node>.objectOffsetRot : Quat
<node>.objectOffsetScale : Point3
Node geometry’s position, rotation, and scale offset from the pivot in world coordinates.
<node>.objectTransform : Matrix3, read-only
Node geometry’s offset in world coordinates.

See also
Using Node Transform Properties (p. 843)
 Using Node Transform Properties 843

Using Node Transform Properties

This topic provides information on three transforms related to nodes -- the Node Transform Matrix,
the Object-Offset Transform Matrix, and the Object Transform Matrix. The Node and Object-Offset
Transform Matrices are stored by 3ds max. The Object Transform Matrix is derived from these two
matrices. This topic also presents information on how these transforms are constructed and how
they are used by 3ds max, and how they can be accessed and manipulated in MAXScript.
The Pivot Point -- The Node Transform Matrix
The transform center, or pivot point, is the location about which a rotation takes place, or to and
from which a scale occurs. All nodes in 3ds max have a pivot point. You can think of the pivot point
as representing a node’s local center and local coordinate system. The pivot point of a node is used
for a number of purposes:
• As the center for rotation and scaling.
• Defines the transform origin for linked children.
• Defines the joint location for Inverse Kinematics.
The thing that most users think of as the pivot point -- graphically represented in 3ds max by the
axis tripod that is displayed when a node is selected and the coordinate system is set to local -- is
actually just a visual representation of the node’s transform matrix.
The node’s transform matrix is what is controlled by the transform controller that places the node
in the scene. The transform controller controls the transform relative to the node’s parent.
Construction of the Node Transform Matrix for the PRS Transform Controller
The PRS controller uses sub-controllers to create the final transform. There are three sub-controllers
-- one for Position, one for Rotation, and one for Scale. The PRS controller is passed the transform
matrix of the node’s parent. If the node has no parent, the matrix starts out as the identity matrix.
The PRS controller first calls the position controller, then the rotation controller, then the scale
controller. First the position controller pre-multiplies the input matrix is by the position value. If the
matrix passed is the identity matrix, this is equivalent to setting the bottom row (the translation
row) of the matrix. Next, the rotation controller pre-multiplies the matrix by the rotation value.
Finally, the scale controller pre-multiplies the matrix by the scale value.
Some position controllers can actually apply more than just position to the matrix. For example, the
Path Controller, when the Follow switch is active, actually applies some rotation to have the node
remain tangent to the path it is following. Thus when the rotation controller receives the matrix,
the matrix already has some rotation applied.
The matrix, after the position, rotation and scale controllers have updated it, becomes the Node
Transform Matrix 3ds max uses to position, rotate and scale nodes in the scene. Thus, the entire
transform is:
Node Transform Matrix = Controller Scale * Controller Rotation *
Controller Position * Parent Transform Matrix
844 Chapter 11 | 3ds max Objects

The Object-Offset Transform Matrix

The Object-Offset Transform Matrix provides an offset of the geometry of an object from its node.
One can see a node’s pivot point graphically represented in 3ds max by selecting a node, going to
the Hierarchy branch of the Hierarchy panel, selecting the ‘Pivot’ button, and choosing either the
‘Affect Pivot Only’ or ‘Affect Object Only’ button. This displays a large axis tripod that shows the
location and orientation of the node’s pivot point. By choosing one of these buttons, and using the
Move/Rotate/Scale toolbar controls, a user can manipulate the position of the geometry of the object
independent of the pivot point. Or they may manipulate the pivot point independent of the
geometry of the object.
The way the user is able to independently manipulate the pivot and the object is managed internally
using the Object-Offset Transform Matrix. The Object-Offset Transform Matrix affects how the
geometry of the object is related to the node. The Object-Offset Transform Matrix transforms the
geometry of the object itself some amount from the node.
To understand how the Object-Offset Transform Matrix is used, consider the following example
from the 3ds max user interface. In the Hierarchy branch under ‘Pivot’, when the user has chosen
the ‘Affect Object Only’ button they are free to move the geometry of the object around
independent of the node. The pivot point does not move -- only how the geometry of the object is
oriented relative to the pivot. What is happening internally is that the Object-Offset Transform
Matrix is being manipulated. This transform is simply an additional offset that is applied to the
geometry of the object that is independent of the node. The Object-Offset Transform Matrix is not
inherited by any child nodes.
As another example consider the use of the ‘Affect Pivot Only’ button. This mode lets the user move
the pivot without affecting the position of the geometry of the object. When the user moves the
pivot point, what is actually happening is the Node Transform Matrix is being altered (to re-orient
the pivot point), then the Object-Offset Transform Matrix is adjusted to counter the node transform.
This lets the geometry of the object stay in the same place while the pivot point moves around.
Construction of the Object-Offset Transform Matrix
The Object-Offset Transform Matrix consists of separate position, rotation and scale transforms. Like
the Node Transform Matrix, these are applied by pre-multiplying position, then rotation, then scale.
Thus the Object-Offset Transform Matrix is:
Object-Offset Transform Matrix = Offset Scale * Offset Rotation * Offset Position

Unlike the Node Transform Matrix, the Object-Offset Transform Matrix is not inherited by children
of the node.
 Using Node Transform Properties 845

The Object Transform Matrix

The Object Transform Matrix is the transform matrix an object’s geometry needs to be multiplied by
to transform it into world space. This transform matrix includes the parent transform, the Node
Transform, and the Object Offset Transform. Thus, the entire transform used to transform the points
of any object is:
Object Transform Matrix = Object-Offset Transform Matrix * Node Transform Matrix

This matrix could be used, for example, if you have a mesh object and wanted to get the world space
coordinate of one of its vertices. You could do this by taking the vertex coordinate in object space
and multiplying it by the Object Transform Matrix.
Using the Node Transforms in MAXScript
The node transform properties are derived from and modify the values of the transform controllers
associated with the node, they are not associated directly with the node’s main transformation
matrix. This has a number of consequences:
1. Assigning to a transform property (such as pos or rotation) with animation enabled plants
keyframes only in the associated controller. If you modify the node’s transform matrix directly,
keyframes are generated for all the transform controllers for that node.
2. Rotation properties and in fact all rotation-related functions in MAXScript reflect the direction
convention used in the 3ds max user interface. This convention is the right-hand rule, namely,
positive angles rotate counter-clockwise about positive axes. Internally, however, 3ds max stores
rotations in node matrices using the left-hand rule. It is important to remember this inversion
when working directly with node transform matrices using the transform and
objectTransform properties. You’ll need to invert rotations (for example, by multiplying axes
by [-1,-1,-1] or using the inverse() function on quaternions) when mixing them with 3ds max
and MAXScript standard rotations.
3. Certain controllers, such as the path controller with bank or follow enabled, affect the rotation
of a node by adjusting the node’s transform matrix directly and this rotation is not reflected in
rotation controller values. This means, in this example for instance, that bank and follow
rotations are not directly accessible through the rotation property, you need to access them
directly in the node’s transformation matrix using something like:
r = $foo.transform.rotationPart

which returns a quaternion. Remember, however, that the 3ds max rotation direction
convention is not reflected when directly accessing a transform matrix, so to use this value in
other rotation operations you would need to invert it:
$baz.rotation = inverse r

A node’s transform property contains the Node Transform Matrix, and reflects the position,
rotation, and scale of the node’s pivot point. Accessing the pivot property will return the same
value as the pos property. Setting the pivot property will move the pivot point location to the
specified coordinates, however the node’s geometry will not be moved.
846 Chapter 11 | 3ds max Objects

A node’s objectoffsetpos, objectoffsetrot, and objectoffsetscale properties contain the

component parts of the Object-Offset Transform Matrix. A node’s objecttransform property
contains the Object Transform Matrix. Since this matrix is a combination of the Node Transform and
Object-Offset Transform Matrices, this property is read only. Note that these properties are always
returned in the World coordinate system context.
The following script shows the initial node transform properties for a 25x25x25 box created at
[75,75,0], after moving the pivot point to [50,50,0], and after rotating only the pivot point 35
degrees about the Z axis. Also shown is the position of one of the box’s vertices after each transform.
Script:
fn DumpXForms obj =
( -- output node transform properties
format “%:\t%\n” “transform” obj.transform
format “%:\t%\n” “position “ obj.pos
format “%:\t%\n” “rotation “ obj.rotation
-- output node’s pivot point location
format “%:\t%\n” “pivot “ obj.pivot
-- output object offsets
format “%:\t%\n” “objectoffsetpos “ obj.objectoffsetpos
format “%:\t%\n” “objectoffsetrot “ obj.objectoffsetrot
format “%:\t%\n” “objectoffsetscale” obj.objectoffsetscale
-- output object transform
format “%:\t%\n” “objecttransform “ obj.objecttransform
-- output vertex position in local and world coordinates
format “%:\t%\n” “vert 1 (local) “ (in coordsys local getvert obj 1)
format “%:\t%\n” “vert 1 (world1) “ (in coordsys world getvert obj 1)
-- calculate and output vertex position in world coordinates
local v_pos=(in coordsys local getvert obj 1)* obj.objecttransform
format “%:\t%\n” “vert 1 (world2) “ v_pos
)
--
-- define function for rotating only the pivot point
fn RotatePivotOnly obj rotation=
( local rotValInv=inverse (rotation as quat)
animate off in coordsys local obj.rotation*=RotValInv
obj.objectoffsetrot*=RotValInv
obj.objectoffsetpos*=RotValInv
)
--
(
b=box pos:[75,75,0] -- create a 25x25x25 box, vertex 1 at [62.5,62.5,0] (world)
convertToMesh b -- convert box to mesh so we can access the vertex location
DumpXForms b -- print transforms
b.pivot=[50,50,0] -- move pivot only to [50,50,0]
DumpXForms b -- print transforms
RotatePivotOnly b (EulerAngles 0 0 35) -- rotate pivot only 35 degrees about local
Z
DumpXForms b -- print transforms
)
 Using Node Transform Properties 847

Output:
DumpXForms() -- function definition
RotatePivotOnly()-- function definition
transform: (matrix3 [1,0,0], [0,1,0], [0,0,1], [75,75,0]) -- initial transforms
position : [75,75,0]
rotation : (quat 0 0 0 1)
pivot : [75,75,0]
objectoffsetpos : [0,0,0]
objectoffsetrot : (quat 0 0 0 1)
objectoffsetscale: [1,1,1]
objecttransform : (matrix3 [1,0,0], [0,1,0], [0,0,1], [75,75,0])
vert 1 (local) : [-12.5,-12.5,0]
vert 1 (world1) : [62.5,62.5,0]
vert 1 (world2) : [62.5,62.5,0]
transform: (matrix3 [1,0,0], [0,1,0], [0,0,1], [50,50,0]) -- transforms after
move
position : [50,50,0]
rotation : (quat 0 0 0 1)
pivot : [50,50,0]
objectoffsetpos : [25,25,0]
objectoffsetrot : (quat 0 0 0 1)
objectoffsetscale: [1,1,1]
objecttransform : (matrix3 [1,0,0], [0,1,0], [0,0,1], [75,75,0])
vert 1 (local) : [-12.5,-12.5,0]
vert 1 (world1) : [62.5,62.5,0]
vert 1 (world2) : [62.5,62.5,0]
transform: (matrix3 [0.819152,0.573576,0], [-0.573576,0.819152,0], [0,0,1],
[50,50,0]) -- transforms after rotate
position : [50,50,0]
rotation : (quat 0 0 0.300706 0.953717)
pivot : [50,50,0]
objectoffsetpos : [34.8182,6.13939,0]
objectoffsetrot : (quat 0 0 0.300706 0.953717)
objectoffsetscale: [1,1,1]
objecttransform : (matrix3 [1,0,0], [0,1,0], [0,0,1], [75,75,0])
vert 1 (local) : [-12.5,-12.5,0]
vert 1 (world1) : [62.5,62.5,0]
vert 1 (world2) : [62.5,62.5,0]
848 Chapter 11 | 3ds max Objects

Node User-Defined Properties and Methods

The functions described in this topic give you access to scene object user properties, accessible in the
3ds max user interface in the User Defined tab in the Object Properties Dialog. There are two ways
to access and set the user defined properties in the Object Properties dialog -- either as one single
string representing the entire contents or as key/property pairs in the form:
<key1> = <property1>
<key2> = <property2>
...
where the keys are identifiers (Name or String values) and the properties can be numbers,
booleans (true/false) or text strings. There are two MAXScript methods for setting and
getting individual keyed properties, and two methods that let you treat the property text
as a single big string.
Caution: There is currently a bug in the get/set property functions in the 3ds max SDK for text string
properties that truncates retrieved string properties at the first space character in the string value.
The <node> methods are:
getUserProp <node> <key_string>
retrieves the node’s user property with the given key as a string. <key_string> is either a
String or a Name value. If the key does not exist, a value of undefined is returned.
setUserProp <node> <key_string> <value>
sets the node’s user property with the given key to the given value
getUserPropBuffer <node>
retrieves the entire user property buffer as a string containing all the user property settings.
This is effectively the contents of the User Defined Properties box in the 3ds max Object
Properties dialog
setUserPropBuffer <node> <string>
sets the user property buffer to the given string
The following two example code fragments save and load user properties for objects in a scene.
The first code fragment creates a file and loops through all objects outputting for each the object
name and user property buffer string. Note that the object name goes out in a form that will come
back in (via a readValue()) as a direct reference to a scene object. Also, the user property string is
output using print() so it will be in a quoted form to be read as one (long) string literal by a
corresponding readValue().
The second code fragment reads in the file created by the first piece and applies the user properties
to any same-named object in the current scene. Note that readValue() can read in pathnames
($<name>) and will yield either the named scene object or undefined if the named object is not in
the scene. The readValue() function can also read in a multiline string literal in one pass.
 Node User-Defined Properties and Methods 849

-- create file and for all objects,

-- dump object name and user props
f = createFile “foo.dat”
for o in objects do
(
format “$%\n” o.name to:f -- output name in a pathname form
print (getUserPropBuffer o) to:f -- output buffer as a string literal
)
close f

-- open file and read in object names and

-- user properties to set
f = openFile “foo.dat”
while not eof f do
(
o = readValue f -- read object
if o != undefined then -- if present, read and set user prop string
setUserPropBuffer o (readValue f)
)
close f

Node Subclasses
In the following node subclasses, the properties listed can all be specified as optional constructor
keyword arguments with defaults as shown, along with the common keyword arguments for all
node constructors, listed in the Node : MAXWrapper (p. 820) topic. The property listings show name,
type and Constructor default value. The following list displays the 3ds max node subclasses:
GeometryClass (p. 850)
Shape (p. 944)
Light (p. 966)
Camera (p. 974)
Helper (p. 977)
SpacewarpObject (p. 992)
850 Chapter 11 | 3ds max Objects

GeometryClass : Node
The following list shows the 3ds max geometry class objects:
-- Standard Primitives
Box (p. 853)
Cone (p. 858)
Cylinder (p. 859)
Geosphere (p. 862)
Plane (p. 867)
Pyramid (p. 869)
Sphere (p. 872)
Teapot (p. 875)
Torus (p. 875)
Tube (p. 878)
-- Extended Primitives
Capsule (p. 855)
ChamferBox (p. 856)
ChamferCyl (p. 857)
C_Ext (p. 854)
Gengon (p. 861)
Hedra (p. 863)
L_Ext (p. 865)
OilTank (p. 866)
Prism (p. 868)
RingWave (p. 870)
Spindle (p. 873)
TargetObject (p. 874)
Torus_Knot (p. 877)
-- Compound Objects
OldBoolean (p. 887)
Boolean2 (p. 887)
Conform (p. 889)
Connect (p. 889)
Loft (p. 890)
Morph (p. 891)
 Node User-Defined Properties and Methods 851

Scatter (p. 891)

ShapeMerge (p. 893)
Terrain (p. 894)
-- Particle Systems
Blizzard (p. 906)
PArray (p. 913)
PCloud (p. 923)
Snow (p. 931)
Spray (p. 933)
SuperSpray (p. 935)
-- Patch Grids
QuadPatch (p. 903)
TriPatch (p. 904)
-- NURBS Surfaces
NURBSSurf (p. 943)
Point_Surf (p. 943)
-- Dynamics Objects
Damper (p. 880)
Spring (p. 883)
-- Doors
BiFold (p. 897)
Pivot (p. 899)
SlidingDoor (p. 901)
-- Windows
Awning (p. 897)
Casement (p. 898)
Fixed (p. 899)
Pivoted (p. 900)
Projected (p. 901)
SlidingWindow (p. 902)
-- AEC Extended Objects
Terrain (p. 894)
852 Chapter 11 | 3ds max Objects

GeometryClass Common Properties, Operators, and Methods

The mesh operations underlying the Boolean Compound Object in 3ds max are accessible in
MAXScript. They appear as operators (+, -, *) that you can apply to any two scene objects that are
convertible to meshes. These objects are all GeometryClass objects with the exception of the particle
systems. The operators are:
<node1> + <node2> -- the union of node1 and node2
<node1> - <node2> -- the subtraction of node2 from node1
<node1> * <node2> -- the intersection of node1 and node2

Example:
$foo - $baz
$sphere01 + $sphere02 + $sphere03 + $sphere04

The Boolean operators change the first operand to be the result of the operation and leave the
second operand untouched. So, in the first example, the $foo node is changed to an Editable Mesh
object containing the result of the difference operation. In the second example, $sphere01 is
successively unioned with each of the other spheres - $sphere01 contains the compound result and
the other spheres are left standing.
Note that unlike the Boolean compound object in 3ds max, this operation destructively modifies the
first operand - you cannot retrieve the original first operand after the Boolean operation is
performed. You can effectively keep the first operand by using a copy function, for example,
result = (copy $foo) - $baz
will put a modified copy of $foo into the variable result, leaving the original $foo
unchanged.

Geometry - Standard and Extended Objects

The following list displays the standard and extended objects:
Box (p. 853)
Capsule (p. 855)
ChamferBox (p. 856)
ChamferCyl (p. 857)
Cone (p. 858)
Cylinder (p. 859)
C_Ext (p. 854)
Gengon (p. 861)
Geosphere (p. 862)
Hedra (p. 863)
L_Ext (p. 865)
OilTank (p. 866)
 Box : GeometryClass 853

Plane (p. 867)

Prism (p. 868)
Pyramid (p. 869)
RingWave (p. 870)
Sphere (p. 872)
Spindle (p. 873)
TargetObject (p. 874)
Teapot (p. 875)
Torus (p. 875)
Torus_Knot (p. 877)
Tube (p. 878)

Box : GeometryClass
Constructor:
box ...

Properties:
<Box>.length Float default: 25.0 -- animatable
Sets the length of the box object.
<Box>.width Float default: 25.0 -- animatable
Sets the width of the box object.
<Box>.height Float default: 25.0 -- animatable
Sets the height of the box object.
<Box>.lengthsegs Integer default: 1 -- animatable, alias:
Length_Segments
Sets the number of divisions along the length of the object.
<Box>.widthsegs Integer default: 1 -- animatable, alias: Width_Segments
Sets the number of divisions along the width of the object.
<Box>.heightsegs Integer default: 1 -- animatable, alias:
Height_Segments
Sets the number of divisions along the height of the object.
<Box>.mapcoords Boolean default: false
When on, generates coordinates for applying mapped materials to the box.
854 Chapter 11 | 3ds max Objects

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

C_Ext : GeometryClass
Constructor:
c_ext ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<C_Ext>.Back_Length Float default: 0.0 -- animatable
Sets the length of the back edge.
<C_Ext>.Side_Length Float default: 0.0 -- animatable
Sets the length of the side edge.
<C_Ext>.Front_Length Float default: 0.0 -- animatable
Sets the length of the front edge.
<C_Ext>.Back_Width Float default: 0.0 -- animatable
Sets the width of the back edge.
<C_Ext>.Side_Width Float default: 0.0 -- animatable
Sets the width of the side edge.
<C_Ext>.Front_Width Float default: 0.0 -- animatable
Sets the width of the front edge.
<C_Ext>.height Float default: 0.0 -- animatable
Sets the overall height of the object.
<C_Ext>.Back_Segments Integer default: 1 -- animatable
The number of segments along the back edge of the object.
<C_Ext>.Side_Segments Integer default: 1 -- animatable
The number of segments along the side edge of the object.
<C_Ext>.Front_Segments Integer default: 1 -- animatable
The number of segments along the front edge of the object.
<C_Ext>.Width_Segments Integer default: 1 -- animatable
The number of segments along the width of the object.
<C_Ext>.Height_Segments Integer default: 1 -- animatable
The number of segments along the height of the object.
Note:
The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.
 Capsule : GeometryClass 855

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Capsule : GeometryClass
Constructor:
capsule ...

Properties:
<Capsule>.radius Float default: 15.0 -- animatable
The radius of the capsule.
<Capsule>.height Float default: 25.0 -- animatable
The height of the capsule.
<Capsule>.heighttype Integer default: 1
Set what .height specifies:
Overall
Centers (not including domed caps)
<Capsule>.sides Integer default: 24 -- animatable
Sets the number of sides around the capsule. Higher numbers shade and render as true
circles with Smooth on. Lower numbers create regular polygonal objects with Smooth off.
<Capsule>.heightsegs Integer default: 1 -- animatable; alias:
height_segments
The number of divisions along the capsule’s major axis.
<Capsule>.smooth Boolean default: true -- animatable
When on, blends the faces of the capsule, creating a smooth appearance in rendered views.
<Capsule>.smooth_on Integer default: 1 -- animatable
Smooth_on is an integer alias of smooth:
OFF
ON
<Capsule>.sliceon Boolean default: false -- animatable
Turns on/off the Slice function.
<Capsule>.slice_on Integer default: 0 -- animatable
Slice_on is an integer alias of sliceon:
OFF
ON
856 Chapter 11 | 3ds max Objects

<Capsule>.slicefrom Float default: 0.0 -- animatable, angle; alias:

slice_from
Sets the starting angle (on the local Z-axis) for slicing.
<Capsule>.sliceto Float default: 0.0 -- animatable, angle; alias:
slice_to
Sets the angle (on the local Z-axis) to slice to.
<Capsule>.mapCoords Boolean default: false
When on, sets up the required coordinates for applying mapped materials to the capsule.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

ChamferBox : GeometryClass
Constructor:
chamferBox ...

Properties:
<ChamferBox>.length Float default: 0.1 -- animatable
The length of the object.
<ChamferBox>.width Float default: 0.1 -- animatable
The width of the object.
<ChamferBox>.height Float default: 0.1 -- animatable
The height of the object.
<ChamferBox>.Fillet Float default: 0.01 -- animatable
Slices off the edges of the chamferbox. The higher the number, the more filleted the
chamferbox becomes.
<ChamferBox>.Length_Segments Integer default: 1 -- animatable
The number of divisions along the length of the object.
<ChamferBox>.Width_Segments Integer default: 1 -- animatable
The number of divisions along the width of the object.
<ChamferBox>.Height_Segments Integer default: 1 -- animatable
The number of divisions along the height of the object.
<ChamferBox>.Fillet_Segments Integer default: 3 -- animatable
The number of segments in the filleted edges of the box. Adding fillet segments increases
the edge roundness.
 ChamferCyl : GeometryClass 857

Note:
The Generate Mapping Coordinates and Smooth properties are not accessible to MAXScript in
3ds max 4.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

ChamferCyl : GeometryClass
Constructor:
chamferCyl ...

Properties:
<ChamferCyl>.radius Float default: 0.0 -- animatable
The radius of the chamfered cylinder.
<ChamferCyl>.height Float default: 0.0 -- animatable
The dimension along the central axis. Negative values create the chamfered cylinder below
the construction plane.
<ChamferCyl>.Fillet Float default: 0.0 -- animatable
Slices off the edges of the chamfered cylinder. The higher the number, the more filleted
the cylinder becomes.
<ChamferCyl>.Height_Segments Integer default: 1 -- animatable
The number of divisions along the corresponding axis.
<ChamferCyl>.Fillet_Segments Integer default: 1 -- animatable
The number of segments in the filleted edges of the box. Adding fillet segments curves the
edges, producing a chamfered cylinder.
<ChamferCyl>.sides Integer default: 12 -- animatable
The number of sides around the chamfered cylinder. Higher numbers shade and render as
true circles with Smooth on. Lower numbers create regular polygonal objects with
Smooth off.
<ChamferCyl>.Cap_Segments Integer default: 1 -- animatable
The number of concentric divisions along the center of the chamfered cylinder’s top and
bottom
<ChamferCyl>.Smooth Boolean default: true -- animatable
When on, blends the faces of the chamfered cylinder, creating a smooth appearance in
rendered views.
858 Chapter 11 | 3ds max Objects

<ChamferCyl>.Smooth_On Integer default: 1 -- animatable

Integer alias for .smooth:
OFF
ON
<ChamferCyl>.SliceOn Boolean default: false -- animatable
Turn on/off the slice function.
<ChamferCyl>.Slice_On Integer default: 0 -- animatable
Integer alias for .slice_on:
OFF
ON
<ChamferCyl>.Slice_From Float default: 0.0 -- animatable, angle
Sets the starting angle (on the local Z-axis) for slicing.
<ChamferCyl>.Slice_To Float default: 0.0 -- animatable, angle
Sets the angle (on the local Z-axis) to slice to.
Note:
The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Cone : GeometryClass
Constructor:
cone ...

Properties:
<Cone>.radius1 Float default: 15.0 -- animatable, alias: Radius_1
The first radius of the cone.
<Cone>.radius2 Float default: 0.0 -- animatable, alias: Radius_2
The second radius of the cone.
<Cone>.height Float default: 25.0 -- animatable
Height along the central axis. Negative values create the cone below the construction
plane.
<Cone>.heightsegs Integer default: 5 -- animatable, alias:
Height_Segments
The number of divisions along the cone’s major axis.
 Cylinder : GeometryClass 859

<Cone>.capsegs Integer default: 1 -- animatable, alias: Cap_Segments

The number of concentric divisions around the center of the cone’s top and bottom.
<Cone>.sides Integer default: 24 -- animatable
The number of sides around the cone. Higher numbers shade and render as true circles
with Smooth selected. Lower numbers create regular polygonal objects with Smooth off.
<Cone>.smooth Boolean default: true -- animatable
When on, blends the faces of the cone, creating a smooth appearance in rendered views.
<Cone>.slice Boolean default: false -- animatable, alias: sliceon
Turns on/off slice function.
<Cone>.Slice_On Integer default: 0
Integer alias for .slice:
OFF
ON
<Cone>.sliceFrom Float default: 0.0 -- animatable, angle, alias:
Slice_From
Sets the starting angle (on the local Z-axis) for slicing.
<Cone>.sliceTo Float default: 0.0 -- animatable, angle, alias: Slice_To
Sets the angle (on the local Z-axis) to slice to.
<Cone>.mapCoords Boolean default: false
When on, sets up required coordinates for applying mapped materials to the cone.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Cylinder : GeometryClass
Constructor:
cylinder ...

Properties:
<Cylinder>.radius Float default: 15.0 -- animatable
The radius of the cylinder.
<Cylinder>.height Float default: 25.0 -- animatable
Height along the central axis. Negative values create the cylinder below the construction
plane.
<Cylinder>.heightsegs Integer default: 1 -- animatable, alias:
Height_Segments
The number of divisions along the cylinder’s major axis.
860 Chapter 11 | 3ds max Objects

<Cylinder>.capsegs Integer default: 1 -- animatable, alias:

Cap_Segments
The number of concentric divisions around the center of the cylinder’s top and bottom.
<Cylinder>.sides Integer default: 24 -- animatable
The number of sides around the cylinder. With Smooth on, higher numbers shade and
render as true circles. With Smooth off, lower numbers create regular polygonal objects.
<Cylinder>.smooth Boolean default: true -- animatable
When on, the faces of the cylinder are blended together, creating a smooth appearance in
rendered views.
<Cylinder>.slice Boolean default: false -- animatable, alias: sliceon
Turns on/off slice function.
<Cylinder>.Slice_On Integer default: 0
Integer alias for .slice:
OFF
ON
<Cylinder>.sliceFrom Float default: 0.0 -- animatable, angle, alias:
Slice_From
Sets the starting angle (on the local Z-axis) for slicing.
<Cylinder>.sliceTo Float default: 0.0 -- animatable, angle, alias:
Slice_To
Sets the angle (on the local Z-axis) to slice to.
<Cylinder>.mapCoords Boolean default: false
When on, sets up the required coordinates for applying mapped materials to the cylinder.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Gengon : GeometryClass 861

Gengon : GeometryClass
Generic polygon.
Constructor:
gengon ...

Properties:
<Gengon>.sides Integer default: 5 -- animatable
The number of sides around the gengon. Higher numbers shade and render as true circles
with Smooth on. Lower numbers create regular polygonal objects with Smooth off.
<Gengon>.radius Float default: 0.0 -- animatable
The radius of the gengon.
<Gengon>.Fillet Float default: 0.0 -- animatable
The width of the fillet area.
<Gengon>.height Float default: 0.0 -- animatable
Height along the central axis. Negative values create the gengon below the construction
plane.
<Gengon>.Side_Segments Integer default: 1 -- animatable
The number of divisions around the gengon.
<Gengon>.Height_Segments Integer default: 1 -- animatable
The number of divisions along the gengon’s major axis.
<Gengon>.Fillet_Segments Integer default: 1 -- animatable
The number of divisions for the edge filleting. The higher this setting, the rounder the
fillet appears.
Note:
The Generate Mapping Coordinates and Smooth properties are not accessible to MAXScript in
3ds max R4.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
862 Chapter 11 | 3ds max Objects

Geosphere : GeometryClass
Constructor:
geosphere ...

Properties:
<GeoSphere>.creationMethod Integer default: 1 -- alias: Creation_Method
Sets the creation method:
Diameter (Draws a geosphere from edge to edge.)
Center (Draws a geosphere from the center out.)
<GeoSphere>.typeInPos Point3 default: [0,0,0]
The point3 position of the geosphere.
<GeoSphere>.typeInRadius Float default: 25.0
The radius of the geosphere.
<GeoSphere>.radius Float default: 25.0 -- animatable
The radius of the geosphere.
<GeoSphere>.segs Integer default: 4 -- animatable, alias:
segments
The total number of faces in the geosphere. The number of faces in a geosphere is equal to
the sides of the base polyhedron times the segments squared.
Lower segment values work best. Using the maximum segment value of 200 can generate
up to 800,000 faces, impairing performance.
<GeoSphere>.baseType Integer default: 2 -- alias: Base_Type
Sets the type of basic geometry for the geosphere:
Tetra (Based on a four-sided tetrahedron. The triangular facets can vary in shape and size.
The sphere can be divided into four equal segments.)
Octa (Based on an eight-sided octahedron. The triangular facets can vary in shape and size.
The sphere can be divided into eight equal segments.)
Icosa (Based on a 20-sided icosahedron. The facets are all equally sized equilateral
triangles. The sphere can be divided into any number of equal segments, based on
multiples and divisions of 20 faces.)
<GeoSphere>.smooth Boolean default: true -- animatable
When on, applies smoothing groups to the surface of the sphere.
<GeoSphere>.hemisphere Boolean default: false -- animatable
When on, creates a half-sphere.
<GeoSphere>.baseToPivot Boolean default: false -- alias: Base_to_Pivot
Sets the pivot point location. When on, the pivot is at the bottom of the sphere. When off,
the pivot is at the center of the sphere. This option has no effect when Hemisphere is on.
<GeoSphere>.mapCoords Boolean default: false -- alias:
Generate_mapping_coords
When on, applies default mapping coordinates to the geosphere.
 Hedra : GeometryClass 863

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Hedra : GeometryClass
Constructor:
hedra ...

Properties:
<Hedra>.family Integer default: 0
Sets the type of polyhedron to create:
Tetra (Creates a tetrahedron)
Cube/Octa (Creates a cubic or octahedral polyhedron, depending on parameter settings.)
Dodec/Icos (Creates a dodecahedron or icosahedron, depending on parameter settings.)
Star1 (Creates a star-like polyhedra.)
Star2 (Creates a different star-like polyhedra.)
<Hedra>.p Float default: 0.0 -- animatable, alias: Q_Value
<Hedra>.q Float default: 0.0 -- animatable, alias: P_Value
Interrelated parameters that provide a two-way translation between the vertices and facets
of a polyhedron. They share the following:
• Range of possible values is 0.0 through 1.0.
• The combined total of the P and Q values can be equal to or less than 1.0.
• Extremes occur if either P or Q is set to 1.0; the other is automatically set to 0.0.
• Midpoint occurs when both P and Q are 0.
In the simplest terms, P and Q change the geometry back and forth between vertices and
facets. At the extreme settings for P and Q, one parameter represents all vertices, the other
represents all facets. Intermediate settings are transition points, with the midpoint an even
balance between the two parameters.
<Hedra>.scalep Float default: 1.0 -- animatable
Controls the axis of reflection for the p facet of a polyhedron.
<Hedra>.scaleq Float default: 1.0 -- animatable
Controls the axis of reflection for the q facet of a polyhedron.
<Hedra>.scaler Float default: 1.0 -- animatable
Controls the axis of reflection for the r facets of a polyhedron.
<Hedra>.P_Scale Float default: 100.0
Controls the axis of reflection for the p facet of a polyhedron.
864 Chapter 11 | 3ds max Objects

<Hedra>.Q_Scale Float default: 100.0

Controls the axis of reflection for the q facet of a polyhedron.
<Hedra>.R_Scale Float default: 100.0
Controls the axis of reflection for the r facets of a polyhedron.
<Hedra>.vertices Integer default: 0 -- alias: vertType
Sets the internal geometry of each facet of the polyhedron:
Basic (Facets are not subdivided beyond the minimum.)
Center (Each facet is subdivided by placing an additional vertex at its center, with edges
from each center point to the facet corners.)
Center & Sides (Each facet is subdivided by placing an additional vertex at its center, with
edges from each center point to the facet corners, as well as to the center of each edge.
Compared to Center, Center & Sides doubles the number of faces in the polyhedron.)
<Hedra>.radius Float default: 25.0 -- animatable
The radius of any polyhedron in current units.
<Hedra>.mapCoords Boolean default: false
When on, sets up required coordinates for applying mapped materials to the hedra.
Note:
The (scalep, scaleq, scaler) and (P_Scale, Q_Scale, R_Scale) sets of scale parameters are
aliases of each other, except that the first set is stored as fractions, and the second set is stored as
percentages. This second set of parameters are those shown in the command panels and in
Track View.
In order to access the vertices property for hedra, you need to access the property via the
baseobject property of the node. This is because vertices is also a property name for all nodes,
and conflicts with the hedra’s vertices property. For example:
MyHedra.baseobject.vertices=1 -- set Vertices option to Center

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 L_Ext : GeometryClass 865

L_Ext : GeometryClass
Constructor:
l_ext ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<L_Ext>.Side_Length Float default: 0.0 -- animatable
The length of the side edge.
<L_Ext>.Front_Length Float default: 0.0 -- animatable
The length of the front edge.
<L_Ext>.Side_Width Float default: 0.0 -- animatable
The width of the side edge.
<L_Ext>.Front_Width Float default: 0.0 -- animatable
The width of the front edge.
<L_Ext>.height Float default: 0.0 -- animatable
The height of the object.
<L_Ext>.Side_Segments Integer default: 1 -- animatable
Number of segments along the side edge.
<L_Ext>.Front_Segments Integer default: 1 -- animatable
Number of segments along the front edge.
<L_Ext>.Width_Segments Integer default: 1 -- animatable
Number of segments along the width of the object.
<L_Ext>.Height_Segments Integer default: 1 -- animatable
Number of segments along the height of the object.
Note:
The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
866 Chapter 11 | 3ds max Objects

OilTank : GeometryClass
Constructor:
oilTank ...

Properties:
<OilTank>.radius Float default: 0.0 -- animatable
The radius of the oiltank.
<OilTank>.height Float default: 0.0 -- animatable
The height along the central axis. Negative values create the oiltank below the
construction plane.
<OilTank>.Cap_Height Float default: 0.0 -- animatable
Sets the height of the convex caps. The minimum value is 2.5% of the Radius setting. The
maximum value is the Radius setting, unless the absolute value of the Height setting is less
than the double Radius setting, in which case cap height cannot exceed half of the
absolute value of the Height setting.
<OilTank>.blend Float default: 0.0 -- animatable
When greater than 0, creates a bevel at the edge of the caps.
<OilTank>.sides Integer default: 12 -- animatable
Sets the number of sides around the oiltank. To create a smoothly rounded object, use a
higher number of sides and turn Smooth on. To create an oiltank with flat sides, use a
lower number of sides and turn Smooth off.
<OilTank>.Height_Segments Integer default: 1 -- animatable
Sets the number of divisions along the oiltank’s major axis.
<OilTank>.Smooth_On Integer default: 1 -- animatable
Turn on/off smooth:
OFF
ON
<OilTank>.Slice_On Integer default: 0 -- animatable
Turn on/off slice:
OFF
ON
<OilTank>.Slice_From Float default: 0.0 -- animatable, angle
Sets the starting angle (on the local Z-axis) for slicing.
<OilTank>.Slice_To Float default: 0.0 -- animatable, angle
Sets the angle (on the local Z-axis) to slice to.
Note:
The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.
 Plane : GeometryClass 867

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Plane : GeometryClass
Constructor:
plane ...

Properties:
<Plane>.typeinCreationMethod Integer default: 0 -- alias: Creation_Method
Set the creation method:
Rectangle (Creates the plane primitive from one corner to the diagonally opposite corner,
interactively setting different values for length and width.)
Square (Creates a square plane where length and width are equal.)
<Plane>.typeinPos Point3 default: [0,0,0]
Position of the plane in the World Space Coordinate system.
<Plane>.typeinLength Float default: 25.0
Length of the plane object.
<Plane>.typeinWidth Float default: 25.0
Width of the plane object.
<Plane>.length Float default: 25.0 -- animatable
Length of the plane object.
<Plane>.width Float default: 25.0 -- animatable
Width of the plane object.
<Plane>.lsegs Integer default: 4 -- animatable, alias:
Length_Segments
Number of divisions along the length of the plane object.
<Plane>.wsegs Integer default: 4 -- animatable, alias:
Width_Segments
Number of divisions along the width of the plane object.
<Plane>.density Float default: 1.0 -- animatable
Specifies the factor by which the number of segments in both length and width are
multiplied at render time.
<Plane>.renderScale Float default: 1.0 -- animatable, alias:
Render_Scale
Specifies the factor by which both length and width are multiplied at render time. Scaling
is performed from the center outward.
868 Chapter 11 | 3ds max Objects

<Plane>.mapCoords Boolean default: false -- alias: Mapping

When on, generates coordinates for applying mapped materials to the box.
Note:
The renderScale property is a multiplier applied to the Plane’s length and width property values
at render time.
The density property is a multiplier applied to the Plane’s lsegs and wsegs property values at
render time.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Prism : GeometryClass
Constructor:
prism ...

Properties:
<Prism>.side1Length Float default: 25.0 -- animatable, alias: Side_1_Length
Sets the length of triangle’s first side.
<Prism>.side2Length Float default: 25.0 -- animatable, alias: Side_2_Length
Sets the length of triangle’s second side.
<Prism>.side3Length Float default: 25.0 -- animatable, alias: Side_3_Length
Sets the length of triangle’s third side.
<Prism>.height Float default: 10.0 -- animatable
The height of the prism’s central axis.
<Prism>.side1Segs Integer default: 1 -- animatable, alias: Side_1_Segments
The number of divisions along the first side.
<Prism>.side2Segs Integer default: 1 -- animatable, alias: Side_2_Segments
The number of divisions along the second side.
<Prism>.side3Segs Integer default: 1 -- animatable, alias: Side_3_Segments
The number of divisions along the third side.
<Prism>.heightsegs Integer default: 1 -- animatable, alias: Height_Segments
The number of divisions along the central axis.
<Prism>.mapCoords Boolean default: false
When on, sets up the required coordinates for applying mapped materials to the prism.
 Pyramid : GeometryClass 869

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Pyramid : GeometryClass
Constructor:
pyramid ...

Properties:
<Pyramid>.width Float default: 25.0 -- animatable
The width of the pyramid.
<Pyramid>.depth Float default: 25.0 -- animatable
The depth of the pyramid.
<Pyramid>.height Float default: 25.0 -- animatable
The height of the pyramid.
<Pyramid>.widthsegs Integer default: 1 -- animatable, alias:
Width_Segments
The number of divisions along the width of the pyramid.
<Pyramid>.depthSegs Integer default: 1 -- animatable, alias:
Depth_Segments
The number of divisions along the depth of the pyramid.
<Pyramid>.heightsegs Integer default: 1 -- animatable, alias:
Height_Segments
The number of divisions along the height of the pyramid.
<Pyramid>.mapCoords Boolean default: false
When on, sets up required coordinates for applying mapped materials to the pyramid.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
870 Chapter 11 | 3ds max Objects

RingWave : GeometryClass
Constructor:
ringwave ...

Note: This class is not available in 3D Studio VIZ.

Properties:
Note: Some of the properties can be entered using more than one syntax. They are listed together in
the following list. Either syntax can be used, they are connected.
<RingWave>.’max diameter’ Float default: 500.0 -- animatable; alias:
radius
The outside radius of the ringwave.
<RingWave>.’Radius Segs’ Integer default: 1 -- animatable; alias:
radial_Segments
The segment count between the inner and outer surfaces in the direction of radius.
<RingWave>.’ring width’ Float default: 1.0 -- animatable; alias:
Ring_Width
The mean ring width as measured inward from the outer radius.
<RingWave>.’ring segments’ Integer default: 200 -- animatable; alias:
sides
The number of segments in the circumferential direction for both the inner, outer, and
end (cap) surfaces.
<RingWave>.height Float default: 0.0 -- animatable
The height of the ringwave along its major axis.
<RingWave>.’Height Segs’ Integer default: 1 -- animatable; alias:
Height_Segments
The number of segments in the direction of the height.
<RingWave>.Repeat Integer default: 2 -- animatable
Repeat = 0 - Cyclic Growth; 1 - Grow and Stay; 2 - No Growth
<RingWave>.’time on’ Integer default: 0 -- animatable; alias: Start_Time
The time where the ringwave appears, and begins to grow.
<RingWave>.’time growing’ Integer default: 9600 -- alias: Grow_Time
The time after .’time on’ that the ringwave takes to reach full size.
<RingWave>.’display until’ Integer default: 16000 -- animatable; alias:
End_Time
The time after which the ringwave disappears.
<RingWave>.’Outer Edge Breakup’ Boolean default: false -- alias:
Outer_Edge_Breakup
Turns on breakup of the outer edge.
<RingWave>.’Major Cycles Outer’ Integer default: 1 -- alias:
Outer_Edge_Major_Cycles
The number of major waves around the outer edge.
 RingWave : GeometryClass 871

<RingWave>.’Major Cycle Flux Outer’ Float default: 0.0 -- animatable; alias:

Outer_Edge_Major_Flux
The size of the major waves, expressed as a percentage of the unmodulated width.
<RingWave>.’Major Cycle Flux Per Outer’ Integer default: 16000 -- animatable;
alias: Outer_Edge_Major_Crawl_Time
The time each major wave takes to move around the outer circumference of the RingWave.
<RingWave>.’Minor Cycles Outer’ Integer default: 1 -- alias:
Outer_Edge_Minor_Cycles
The number of random-sized smaller waves in each major cycle.
<RingWave>.’Minor Cycle Flux Outer’ Float default: 0.0 -- animatable;
alias: Outer_Edge_Minor_Flux
The average size of the smaller waves, expressed as a percentage of the unmodulated
width.
<RingWave>.’Minor Cycle Flux Per Outer’ Integer default: -16000 -- animatable;
alias: Outer_Edge_Minor_Crawl_Time
The time each minor wave takes to move across its respective major wave.
<RingWave>.’Inner Edge Breakup’ Boolean default: true -- alias:
Inner_Edge_Breakup
Turns on the breakup of the inner edge.
<RingWave>.’Major Cycles Inner’ Integer default: 11 -- alias:
Inner_Edge_Major_Cycles
The number of major waves around the inner edge.
<RingWave>.’Major Cycle Flux Inner’ Float default: 25.0 -- animatable;
alias: Inner_Edge_Major_Flux
The size of the major waves, expressed as a percentage of the unmodulated width.
<RingWave>.’Major Cycle Flux Per Inner’ Integer default: 19360 -- animatable;
alias: Inner_Edge_Major_Crawl_Time
The time each major wave takes to move around the inner circumference of the RingWave.
<RingWave>.’Minor Cycles Inner’ Integer default: 29 -- alias:
Inner_Edge_Minor_Cycles
The average size of the smaller waves, expressed as a percentage of the unmodulated
width.
<RingWave>.’Minor Cycle Flux Inner’ Float default: 10.0 -- animatable;
alias: Inner_Edge_Minor_Flux
The average size of the smaller waves, expressed as a percentage of the unmodulated
width.
<RingWave>.’Minor Cycle Flux Per Inner’ Integer default: -4320 -- animatable;
alias: Inner_Edge_Minor_Crawl_Time
The time each minor wave takes to move across its respective major wave.
<RingWave>.repeats Integer default: 2 -- radio button number
The number of times the ringwave cycle repeats.
872 Chapter 11 | 3ds max Objects

<RingWave>.’Mapping Coords’ Boolean default: false

When on, assigns mapping coordinates to the ringwave.
<RingWave>.Smoothing Boolean default: false
When on, smooths the surface of the ringwave.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Sphere : GeometryClass
Constructor:
sphere ...

Properties:
<Sphere>.radius Float default: 25.0 -- animatable
The radius of the sphere.
<Sphere>.segs Integer default: 16 -- animatable, alias: segments
The number of polygonal divisions for the sphere.
<Sphere>.smooth Boolean default: true -- animatable
When on, blends the faces of the sphere, creating a smooth appearance in rendered views.
<Sphere>.hemisphere Float default: 0.0 -- animatable
Increasing values progressively “cut off” the sphere, starting at the base, to create a partial
sphere. Values range from 0.0 to 1.0. The default is 0.0, producing a full sphere. A setting
of 0.5 produces a hemisphere, and 1.0 reduces the sphere to nothing.
<Sphere>.chop Integer default: 0
Sets whether the hemisphere is ‘chopped’ or ‘squashed’:
Chop (Reduces the number of vertices and faces in the sphere by “chopping” them out as
the hemisphere is cut off.)
Squash (Maintains the number of vertices and faces in the original sphere, “squashing” the
geometry into a smaller and smaller volume toward the top of the sphere. Since the
geometry is maintained, you can use different versions of a squashed sphere for morph
objects.)
<Sphere>.slice Boolean default: false
When on, uses the From and To angles to create a partial sphere. The effect is similar to
lathing a semicircular shape fewer than 360 degrees.
<Sphere>.sliceFrom Float default: 0.0 -- animatable, angle, alias:
Slice_From
The start angle (on the local Z-axis) for slicing.
 Spindle : GeometryClass 873

<Sphere>.sliceTo Float default: 0.0 -- animatable, angle, alias:

Slice_To
The stop angle (on the local Z-axis) for slicing.
<Sphere>.recenter Boolean default: false
When on, moves a sphere upward along its local Z axis so the pivot point is at its base.
When off, the pivot point is on the construction plane at the center of the sphere.
<Sphere>.mapCoords Boolean default: false
When on, generates coordinates for applying mapped materials to the box.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Spindle : GeometryClass
Constructor:
spindle ...

Properties:
<Spindle>.radius Float default: 0.0 -- animatable
The radius of the spindle.
<Spindle>.height Float default: 0.0 -- animatable
The height of the spindle, along the central axis. Negative values create the spindle below
the construction plane.
<Spindle>.Cap_Height Float default: 0.0 -- animatable
The height of the conical caps. The minimum value is 0.1; the maximum value is 1/2 the
absolute value of the Height setting.
<Spindle>.blend Float default: 0.0 -- animatable
When greater than 0, creates a bevel at the edge of the caps.
<Spindle>.sides Integer default: 12 -- animatable
The number of sides around the spindle. Higher numbers shade and render as true circles
with Smooth on. Lower numbers create regular polygonal objects with Smooth off.
<Spindle>.Cap_Segments Integer default: 5 -- animatable
The number of concentric divisions along the center of the spindle’s top and bottom.
<Spindle>.Height_Segments Integer default: 1 -- animatable
The number of divisions along the spindle’s major axis.
874 Chapter 11 | 3ds max Objects

<Spindle>.Smooth_On Integer default: 1 -- animatable

Turns on/off smooth:
OFF
ON
<Spindle>.Slice_On Integer default: 0 -- animatable
Turn on/off slice:
OFF
ON
<Spindle>.Slice_From Float default: 0.0 -- animatable, angle
The start angle (on the local Z-axis) for slicing.
<Spindle>.Slice_To Float default: 0.0 -- animatable, angle
The stop angle (on the local Z-axis) for slicing.
Note:
The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TargetObject : GeometryClass
The generic target for cameras, spotlights, tape measure helpers, etc. In MAXScript, you must
explicitly construct a target for those objects that need one. For example:
c = targetCamera pos:[x,y,z] target:(targetObject pos:[xt, yt, zt])

Constructor:
targetObject ...

Properties:
There are no additional properties for TargetObject.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Teapot : GeometryClass 875

Teapot : GeometryClass
Constructor:
teapot ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Teapot>.radius Float default: 25.0 -- animatable
The radius of the teapot.
<Teapot>.segs Integer default: 4 -- animatable, alias: segments
The number of divisions for the teapot or its individual parts.
<Teapot>.smooth Boolean default: true -- animatable
When on, blends faces of the teapot, creating a smooth appearance in rendered views.
<Teapot>.body Boolean default: true -- animatable
When on, the body of the teapot is included in the object.
<Teapot>.handle Boolean default: true -- animatable
When on, the handle of the teapot is included in the object.
<Teapot>.spout Boolean default: true -- animatable
When on, the spout of the teapot is included in the object.
<Teapot>.lid Boolean default: true -- animatable
When on, the lid of the teapot is included in the object.
<Teapot>.mapCoords Boolean default: false
When on, sets up required coordinates for applying mapped materials to the teapot.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Torus : GeometryClass
Constructor:
torus ..

Properties:
<Torus>.segs Integer default: 24 -- animatable, alias: segments
The number of radial divisions around the torus. By reducing this number, you can create
polygonal rings instead of circular ones.
876 Chapter 11 | 3ds max Objects

<Torus>.radius1 Float default: 25.0 -- animatable, alias: Radius_1

The distance from the center of the torus to the center of the cross-sectional circle. This is
the radius of the torus ring.
<Torus>.radius2 Float default: 10.0 -- animatable, alias: Radius_2
The radius of the cross-sectional circle.
<Torus>.tubeRotation Float default: 0.0 -- animatable, angle
The degree of rotation. Vertices are uniformly rotated about the circle running through the
center of the torus ring. Positive and negative values for this setting “roll” the vertices in
either direction over the surface of the torus.
<Torus>.tubeTwist Float default: 0.0 -- animatable, angle, alias: Twist
The degree of twist. Cross sections are progressively rotated about the circle running
through the center of the torus. Beginning with twist, each successive cross section is
rotated until the last one has the number of degrees specified.
<Torus>.sides Integer default: 12 -- animatable
The number of sides on the cross-sectional circle of the torus. By reducing this number,
you can create prism-like cross sections instead of circular ones.
<Torus>.smooth Integer default: 0 -- animatable
Select the level of smoothing:
None (Turns off smoothing entirely, producing prism-like facets on the torus.)
Sides (Smoothes the edges between adjacent segments, producing smooth bands running
around the torus.)
All (Produces complete smoothing on all surfaces of the torus.)
Segments (Smoothes each segment individually, producing ring-like segments along the
torus.)
<Torus>.slice Boolean default: false -- animatable
When on, creates a portion of a sliced torus rather than the entire 360 degrees.
<Torus>.sliceFrom Float default: 0.0 -- animatable, angle, alias:
Slice_From
The angle where the torus slice begins.
<Torus>.sliceTo Float default: 0.0 -- animatable, angle, alias: Slice_To
The angle where the torus slice ends.
<Torus>.mapCoords Boolean default: false
When on, sets up required coordinates for applying mapped materials to the torus.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Torus_Knot: GeometryClass 877

Torus_Knot: GeometryClass
Constructor:
torus_knot ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Torus_Knot>.Base_Curve Integer default: 0
Select the base curve for the Torus Know object:
Knot (The torus interweaves itself.)
Circle (The base curve is a circle, resulting in a standard torus if parameters are left at their
defaults.)
<Torus_Knot>.radius Float default: 0.0 -- animatable
The radius of the base curve.
<Torus_Knot>.segments Integer default: 120 -- animatable
The number of segments around the perimeter of the torus.
<Torus_Knot>.p Float default: 2.0 -- animatable
Describe up and around-the-center winding numbers.
<Torus_Knot>.q Float default: 3.0 -- animatable
Describe down and around-the-center winding numbers.
<Torus_Knot>.Warp_Count Float default: 0.0 -- animatable
The number of “points” in a star shape around the curve.
<Torus_Knot>.Warp_Height Float default: 0.0 -- animatable
The height of the “points” given as a percentage of the base curve radius.
<Torus_Knot>.radius2 Float default: 10.0 -- animatable
The radius of the cross section of the torus knot object.
<Torus_Knot>.sides Integer default: 12 -- animatable
The number of sides around the cross section.
<Torus_Knot>.Eccentricity Float default: 1.0 -- animatable
The ratio of the major to minor axes of the cross section. A value of 1 provides a circular
cross section, while other values create elliptical cross sections.
<Torus_Knot>.Twist Float default: 0.0 -- animatable
The number of times the cross section twists around the base curve.
<Torus_Knot>.Lumps Float default: 0.0 -- animatable
The number of bulges in the torus knot.
<Torus_Knot>.Lump_Height Float default: 0.0 -- animatable
The height of the lumps, as a percentage of the radius of the cross section.
<Torus_Knot>.Lump_Offset Float default: 0.0 -- animatable, angle
The offset of the start of the lumps, measured in degrees. The purpose of this value is to
animate the lumps around the torus.
878 Chapter 11 | 3ds max Objects

<Torus_Knot>.smooth Integer default: 2

Set smoothing in the torus knot:
None (The torus knot is faceted.)
Sides (Smoothes only the adjacent sides of the torus knot.)
All (The torus knot is faceted.)
<Torus_Knot>.Gen_UV Integer default: 0
Turn on/off generate mapping coordinates
OFF
ON
<Torus_Knot>.U_Tile Float default: 1.0 -- animatable
Tile the mapping coordinates along U.
<Torus_Knot>.V_Tile Float default: 1.0 -- animatable
Tile the mapping coordinates along V.
<Torus_Knot>.U_Offset Float default: 0.0 -- animatable
Offset the mapping coordinates along U.
<Torus_Knot>.V_Offset Float default: 0.0 -- animatable
Offset the mapping coordinates along V.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Tube : GeometryClass
Constructor:
tube ...

Properties:
<Tube>.radius1 Float default: 25.0 -- animatable, alias: Radius_1
The first radius for the tube.
<Tube>.radius2 Float default: 20.0 -- animatable, alias: Radius_2
The second radius for the tube.
Note: The larger radius specifies the outside radius of the tube, while the smaller specifies
the inside radius.
<Tube>.height Float default: 50.0 -- animatable
The dimension along the central axis. Negative values create the tube below the
construction plane.
 Tube : GeometryClass 879

<Tube>.heightsegs Integer default: 1 -- animatable, alias: Height_Segments

The number of divisions along the tube’s major axis.
<Tube>.capsegs Integer default: 1 -- animatable, alias: Cap_Segments
The number of concentric divisions around the center of the tube’s top and bottom.
<Tube>.sides Integer default: 24 -- animatable
The number of sides around the tube. Higher numbers shade and render as true circles
with Smooth on. Lower numbers create regular polygonal objects with Smooth off.
<Tube>.smooth Boolean default: true -- animatable
When on, faces of the tube are blended together, creating a smooth appearance in
rendered views.
<Tube>.slice Boolean default: false -- animatable
Enables/Disables the Slice feature, which removes part of the tube’s circumference.
<Tube>.Slice_On Integer default: 0
Integer alias of slice:
OFF
ON
<Tube>.sliceFrom Float default: 0.0 -- animatable, angle, alias: Slice_From
The angle where the tube slice begins.
<Tube>.sliceTo Float default: 0.0 -- animatable, angle, alias: Slice_To
The angle where the tube slice ends.
<Tube>.mapCoords Boolean default: false
When on, sets up required coordinates for applying mapped materials to the tube.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Geometry - Dynamics Objects

The following list displays the dynamics objects:
Damper (p. 880)
Spring (p. 883)
880 Chapter 11 | 3ds max Objects

Damper : GeometryClass
Constructor:
damper ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Damper>.End_Placement_Method Integer default: 1
Set binding method for damper:
Reference Objects (Choose this option when binding the damper to two objects.)
Free Spring (Choose this when using the damper as a simple object that’s not bound to
others or used in a dynamics simulation.)
<Damper>.Free_Damper_Height Float default: 2.0 -- animatable
The distance between the bottom center of the base and the top center of the piston when
the damper is not bound.
<Damper>.Renderable_Spring Integer default: 1
Turn on/off renderability of the damper:
not renderable
renderable
<Damper>.Generate_Mapping_Coordinates Integer default: 0
Turn on/off mapping coordinates for the object:
OFF
ON
<Damper>.Base_Stud_Diameter Float default: 0.5 -- animatable
The diameter of the base, or “mount” of the damper.
<Damper>.Base_Stud_Height Float default: 0.2 -- animatable
The height of the base.
<Damper>.Cylinder_Diameter Float default: 1.0 -- animatable
The diameter of the main housing of the damper.
<Damper>.Cylinder_Height Float default: 1.0 -- animatable
The height of the main housing.
<Damper>.Cylinder_Sides Integer default: 8 -- animatable
The number of sides of both the base and the main housing.
<Damper>.Cylinder_Fillet_1 Float default: 0.0 -- animatable
The size of the fillet on the lower edge of the main housing.
<Damper>.Cylinder_Fillet_1_Segments Integer default: 0 -- animatable
The number of segments for Fillet 1. The higher this setting, the rounder the fillet profile
appears.
<Damper>.Cylinder_Fillet_2 Float default: 0.0 -- animatable
The size of the fillet on the upper edge of the main housing.
 Damper : GeometryClass 881

<Damper>.Cylinder_Fillet_2_Segments Integer default: 0 -- animatable

The number of segments for Fillet 2. The higher this setting, the rounder the fillet profile
appears.
<Damper>.Inside_Diameter Float default: 0.0 -- animatable
The inside diameter of the main housing, which is actually a tube rather than a cylinder.
<Damper>.Smooth_Cylinder Integer default: 1
Turn on/off smoothing for the base and the main housing:
OFF
ON
<Damper>.Piston_Diameter Float default: 0.2 -- animatable
The diameter of the piston.
<Damper>.Piston_Height Float default: 1.0 -- animatable
The height of the piston.
<Damper>.Piston_Sides Integer default: 6 -- animatable
The number of sides in the piston.
<Damper>.Smooth_Piston Integer default: 1
Turn on/off smoothing for the piston:
OFF
ON
<Damper>.Enable_Boot Integer default: 0
Turn this on to add the boot to the damper:
OFF
ON
The boot is an optional component of the damper that’s similar to the rubber “accordion”
boot found on various types of dampers, such as shock absorbers. The boot acts like a
bound dynamic object, in that one of its ends is bound to the main housing, while the
other is bound to the piston. Thus, as the piston moves within the housing, the boot
expands and contracts to follow.
<Damper>.Boot_Small_Diameter Float default: 0.25 -- animatable
The minimum diameter of the boot. This and the next parameter affect the depth of the
accordion folds in the boot.
<Damper>.Boot_Large_Diameter Float default: 1.0 -- animatable
The maximum diameter of the boot.
<Damper>.Boot_Sides Integer default: 8 -- animatable
The number of sides making up the boot.
<Damper>.Boot_Folds Integer default: 4 -- animatable
The number of accordion folds (bulges) along the height of the boot.
<Damper>.Boot_Fold_Resolution Integer default: 4 -- animatable
The number of segments in each fold.
882 Chapter 11 | 3ds max Objects

<Damper>.Boot_Stop_Diameter Float default: 0.4 -- animatable

The diameter of the stop, which is the ring at the top of the boot.
<Damper>.Boot_Stop_Height Float default: 0.2 -- animatable
The thickness (height) of the stop ring.
<Damper>.Boot_Stop_Setback Float default: 0.2 -- animatable
The distance of the stop ring from the top of the piston.
<Damper>.Boot_Stop_Fillet Float default: 0.0 -- animatable
The size of the fillet on the upper edge of the stop ring.
<Damper>.Boot_Stop_Fillet_Segements Integer default: 0 -- animatable
The number of segments the stop fillet. The higher this setting, the round the fillet profile
appears.
<Damper>.Smooth_Boot Integer default: 1
Turn on/off smoothing for the boot:
OFF
ON
<Damper>.Dynamics_Object_Type Integer default: 0
Select which object is dynamic:
Damper (Select this option to use the damper object as a damper rather than an actuator.)
Actuator (Choose this when using the damper object as an Actuator.)
<Damper>.Drag Float default: 0.0 -- animatable
The force per unit linear speed.
<Damper>.Drag_Units Integer default: 0
Sets the units of drag:
Pounds per inch/second
Newtons per meter/second
<Damper>.Damper_Direction Integer default: 2
Set the directional operation of the damper:
Compression Only (The damper reacts only to compression forces.)
Extension Only (The damper reacts only to expansion forces.)
Both (The damper reacts to both compression and expansion forces.)
<Damper>.Force Float default: 0.0 -- animatable
The amount of force exerted between the two bound objects. Positive values push the
objects apart, while negative values pull them together.
<Damper>.Force_Units Integer default: 0
Set the units of force:
Pounds
Newtons
 Spring : GeometryClass 883

Note:
The Reference End Point objects cannot be specified in MAXScript in 3ds max R4.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Spring : GeometryClass
Constructor:
spring ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Spring>.End_Placement_Method Integer default: 1
Set the end placement method:
Reference Objects (Choose this when binding the spring to two objects.)
Free Spring (Choose this when using the spring as a simple object that’s not bound to
other objects or used in a dynamics simulation.)
<Spring>.Free_Spring_Height Float default: 1.0 -- animatable
The straight-line height or length of the spring when it is not bound. This is not the actual
length of the spring’s wire.
<Spring>.Diameter Float default: 1.0 -- animatable
The overall diameter of the spring, as measured at the center of the wire. (The diameter of
the wire itself has no effect on this setting.)
<Spring>.Number_of_Turns Float default: 1.0 -- animatable
The number of full 360-degree turns in the spring.
<Spring>.Turn_Direction Integer default: 0
Sets the direction of the turns in the spring:
counterclockwise
clockwise
<Spring>.Segmentation_Method Integer default: 0
Sets the segmentation method of the springs:
Automatic Segments (Choose this option to force each turn of the spring to contains the
same number of segments. Thus, if you increase the number of turns, the number of
segments also increases.)
884 Chapter 11 | 3ds max Objects

Manual Segments (When this option is chosen, length of the spring contains a fixed
number of segments, no matter how many turns in the spring. Thus, as you increase the
number of turns, you must manually increase the number of segments to maintain a
smooth curve.)
<Spring>.Segments_Per_Turn Integer default: 16 -- animatable
The number of segments in each 360-degree turn of the spring.
<Spring>.Segments_Along_Turn Integer default: 16 -- animatable
The total number of manual segments in the spring.
<Spring>.Smooth_Spring Integer default: 0
Set smoothing method for spring:
All (All surfaces are smoothed.)
None (No smoothing is applied.)
Sides (Smoothing runs along the length of the wire, but not around its perimeter.)
Segments (Smoothing runs around the perimeter of the wire, but not along its length.)
<Damper>.Renderable_Spring Integer default: 1
When on, the object appears in the rendering; when off, the object does not appear:
Not renderable
Renderable
<Spring>.Wire Integer default: 0 -- animatable
Set the shape of the wire:
Round
Rectangular
D-Section
<Spring>.Generate_Mapping_Coordinates Integer default: 0
Turn on/off generate texture coordinates
OFF
ON
<Spring>.Round_Wire_Diameter Float default: 0.2 -- animatable
The diameter of the wire.
<Spring>.Round_Wire_Side_Count Integer default: 6 -- animatable
The number of sides that make up the cross section of the round wire.
<Spring>.Rectangular_Wire_Width Float default: 0.2 -- animatable
Determines the width of the rectangular cross section.
<Spring>.Rectangular_Wire_Depth Float default: 0.2 -- animatable
Determines the depth of the rectangular cross section.
<Spring>.Rectangular_Wire_Fillet_Size Float default: 0.0 -- animatable
When combined with .Rectangular_Fillet_Sides, this lets you fillet (round) the
corners of the cross section.
 Spring : GeometryClass 885

<Spring>.Rectangular_Fillet_Sides Integer default: 0 -- animatable

The number of segments in the fillet.
<Spring>.Rectangular_Wire_Rotation_Angle Float default: 0.0 -- animatable,
angle
Rotates the angle of the cross section along the entire length of the spring.
<Spring>.D_Section_Wire_Width Float default: 0.2 -- animatable
Determines the width of the cross section.
<Spring>.D_Section_Wire_Depth Float default: 0.2 -- animatable
Determines the depth of the cross section.
<Spring>.D_Section_Round_Sides Integer default: 4 -- animatable
The number of segments that make up the rounded side of the D-shape.
<Spring>.D_Section_Wire_Fillet_Size Float default: 0.0 -- animatable
When combined with .D_Section_Wire_Fillet_Sides, this lets you fillet (round) the
corners of the cross section.
<Spring>.D_Section_Wire_Fillet_Sides Integer default: 0 -- animatable
The number of segments in the fillet.
<Spring>.D_Section_Wire_Rotation_Angle Float default: 0.0 -- animatable,
angle
Rotates the angle of the cross section along the entire length of the spring.
<Spring>.Dynamics_Spring_Free_Height Float default: 1.0 -- animatable
Specifies the height (or length) at which the spring is “relaxed” and therefore contributes
no force--either compression or extension.
<Spring>.Dynamics_K_Constant_Value Float default: 1.0 -- animatable
The amount of force exerted per unit change in length with respect to the Relaxed Hgt
value. This could also be described as the measure of force-per-units-change in length as
compared to the Relaxed Length.
<Spring>.Dynamics_K_Constant_Units Integer default: 0
Sets the Units for the K constant:
Pounds per inch
Newtons per meter
<Spring>.Dynamics_Spring_Direction Integer default: 0
Lets you specify the type of force you want the spring to exert. While most springs actually
provide both compression and extension force, if your simulation requires only one, you
can save calculation time by using one instead of both.
Compression Only (This type of spring provides only expansive force when its length is
shorter than the specified Free Length.)
886 Chapter 11 | 3ds max Objects

Extension Only (Provides contractive force when its length is greater than the specified
Free Length.)
Both (Provides both expansive and contractive force, depending on the variation from
Relaxed Hgt.)
<Spring>.Generate_Texture_Coordinates Integer default: 0
Turn on/off generate texture coordinates:
OFF
ON
Note:
The Reference End Point objects cannot be specified in MAXScript in 3ds max R4.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Geometry - Compound Objects

The following list displays the compound objects:
OldBoolean (p. 887)
Boolean2 (p. 887)
Conform (p. 889)
Connect (p. 889)
Loft (p. 890)
Morph (p. 891)
Scatter (p. 891)
ShapeMerge (p. 893)
Terrain (p. 894)
 OldBoolean : GeometryClass 887

OldBoolean : GeometryClass
Constructor:
OldBoolean compound objects are not constructable by MAXScript. Boolean objects created in
previous versions of 3ds max use this class when they are loaded, and then the OldBoolean
object is automatically converted to the new Boolean2 class. See the Boolean2 (p. 887) topic for
a constructable boolean object.

Boolean2 : GeometryClass
Constructor:
boolObj.createBooleanObject <operand_A> [ <operand_B> <add_method> <mat_method> ]
Creates a Boolean2 object using node <operand_A> and an optional node <operand_B>.
<add_method> specifies how <operand_B> is to be used as follows:
1 - instance, operand is an instance of the original node
2 - reference, operand is a reference to original node
3 - copy, operand is a copy of original node
4 - move, original node should be deleted

<mat_method> specifies how the materials of the two operands are to be handled as
follows:
1 - combines materials without changing them or the ID’s
2 - matches ID’s to materials, then combines materials
3 - matches materials to ID’s, then combines them
4 - discards original material, uses new node’s instead
5 - discards new node’s material, uses original

Properties:
The following properties are available only after the boolean2 object has been created. The
values shown for the properties are those for a boolean2 object created from two spheres. The
operand transforms are in the local coordinate system of the boolean2 object.
<bool_obj>.Sphere02 SubAnim default: SubAnim:Sphere02
<bool_obj>.Operand_A_Transform SubAnim default: SubAnim:Operand_A_Transform
<bool_obj>.Sphere01 SubAnim default: SubAnim:Sphere01
<bool_obj>.Operand_B_Transform SubAnim default: SubAnim:Operand_B_Transform

Methods:
boolObj.setOperandB <bool_obj> <operand_B> <add_method> <mat_method>
sets operand B. The values for <add_method> and <mat_method> are describe above.
boolObj.getOperandSel <bool_obj> <integer>
boolObj.setOperandSel <bool_obj> <integer> <boolean>
these methods get and set whether operand_A and operand_B are selected in the Operands
list. <integer> = 1 - operand_A, 2 - operand_B
888 Chapter 11 | 3ds max Objects

boolObj.getBoolOp <bool_obj>
boolObj.setBoolOp <bool_obj> <integer>
these methods get and set the boolean Operation Type. Valid values are:
1 - Union
2 - Intersection
3 - Subtraction (A-B)
4 - Subtraction (B-A)
5 - Cut

boolObj.getBoolCutType <bool_obj>
boolObj.setBoolCutType <bool_obj> <integer>
these methods get and set the boolean Cut Type. The value for this property only has an
effect if the Operation Type is Cut. The Cut Types are:
1 - Refine
2 - Split
3 - Remove Inside
4 - Remove Outside

boolObj.getDisplayResult <bool_obj>
boolObj.setDisplayResult <bool_obj> <boolean>
these methods get and set whether Results or Operands are displayed. If true, Result is
displayed. If false, Operands are displayed.
boolObj.getShowHiddenOps <bool_obj>
boolObj.setShowHiddenOps <bool_obj> <boolean>
these methods get and set whether Results + Hidden Operands are displayed. If true,
Results + Hidden Operands are displayed. If false, the Results or Operands as specified
using boolObj.SetDisplayResult() are displayed.
boolObj.getUpdateMode <bool_obj>
boolObj.setUpdateMode <bool_obj> <integer>
these methods get and set the Update mode as follows:
1 - Always
2 - When Rendering
3 - Manually

boolObj.getOptimize <bool_obj>
boolObj.setOptimize <bool_obj> <boolean>
these methods get and set whether vertices are to be welded on the boolean result

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Conform : GeometryClass 889

Conform : GeometryClass
Constructor:
Conform compound objects are not constructable by MAXScript in 3ds max 4.
Properties:
<Conform>.Projection_Distance Float default: 1.0 -- animatable
The distance a vertex in the Wrapper object will move from its original location if it does
not intersect the Wrap-To object.
<Conform>.Standoff_Distance Float default: 1.0 -- animatable
The distance maintained between the vertex of the Wrapper object and the surface of the
Wrap-To object
The following properties are available only after the conform object has been created. The values
shown for the properties are those for a conform object created from two spheres. The operand
transforms are in the local coordinate system of the conform object.
<Conform>.S_Sphere02 SubAnim default: SubAnim:S_Sphere02
<Conform>.Operand_A_Transform SubAnim default: SubAnim:Operand_A_Transform
<Conform>.D_Sphere01 SubAnim default: SubAnim:D_Sphere01
<Conform>.Operand_B_Transform SubAnim default: SubAnim:Operand_B_Transform

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Connect : GeometryClass
Constructor:
Connect compound objects are not constructable by MAXScript in 3ds max 4.
Properties:
<Connect>.segments Integer default: 0 -- animatable
The number of segments in the connecting bridge.
<Connect>.tension Float default: 0.5 -- animatable
Controls the curvature in the connecting bridge. A value of 0 provides no curvature, while
higher values create curves that attempt to more smoothly match the surface normals on
either end of the connecting bridge.
890 Chapter 11 | 3ds max Objects

The following properties are available only after the connect object has been created. The values
shown for the properties are those for a connect object created from two spheres. Similar
SubAnims would be created if additions operands were used. The operand transforms are in the
local coordinate system of the connect object.
<Connect>.Op_0__Sphere02 SubAnim default: SubAnim:Op_0__Sphere02
<Connect>.Op_0_Transform SubAnim default: SubAnim:Op_0_Transform
<Connect>.Op_1__Sphere01 SubAnim default: SubAnim:Op_1__Sphere01
<Connect>.Op_1_Transform SubAnim default: SubAnim:Op_1_Transform

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Loft : GeometryClass
Constructor:
Loft compound objects are not constructable by MAXScript in 3ds max 4.
Properties:
<Loft>.Def_Scale_X SubAnim default: SubAnim:Def_Scale_X
<Loft>.Def_Scale_Y SubAnim default: SubAnim:Def_Scale_Y
<Loft>.Def_Twist SubAnim default: SubAnim:Def_Twist
<Loft>.Def_Teeter_X SubAnim default: SubAnim:Def_Teeter_X
<Loft>.Def_Teeter_Y SubAnim default: SubAnim:Def_Teeter_Y
<Loft>.Def_Bevel SubAnim default: SubAnim:Def_Bevel
<Loft>.Def_Fit_X SubAnim default: SubAnim:Def_Fit_X
<Loft>.Def_Fit_Y SubAnim default: SubAnim:Def_Fit_Y

These SubAnims contain the deformation curves of the loft object. You cannot create or access
points in these curves unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the property.
The following properties are available only after the loft object has been created. The values
shown for the properties are those for a loft object created from an ellipse (the path) and a circle
(the shape).
<loft>.ellipse SubAnim default: SubAnim:Ellipse
<Loft>.circle SubAnim default: SubAnim:Circle

These SubAnims contain the parameters of the path and shape objects, respectively. If multiple
shapes are used in a loft, each of these shape objects will have a corresponding SubAnim.
 Morph : GeometryClass 891

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Morph : GeometryClass
Constructor:
createMorphObject <source_node>
Modification of Morph objects, including setting the morph keys and adding morph
targets, is performed using methods associated with the Morph controller. See the
MorphController (p. 1302) topic for a description of these methods.
Properties:
The following properties are available only after the morph object has been created. The values
shown for the properties are those for a morph object created from three spheres.
<Morph>.M_Sphere01 SubAnim default: SubAnim:M_Sphere01
<Morph>.M_Sphere02 SubAnim default: SubAnim:M_Sphere02
<Morph>.M_Sphere03 SubAnim default: SubAnim:M_Sphere03
<Morph>.Morph Barycentric_Morph_Controller default:
Controller:Barycentric_Morph_Controller

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Scatter : GeometryClass
Constructor:
Scatter compounds are not constructable by MAXScript in 3ds max 4.
Properties:
<Scatter>.Duplicates Integer default: 1 -- animatable
The number of scattered duplicates of the source object.
<Scatter>.Base_Scale Float default: 100.0 -- animatable,
percentage
Alters the scale of the source object, affecting each duplicate identically. This scale occurs
before any other transforms.
892 Chapter 11 | 3ds max Objects

<Scatter>.Vertex_Chaos Float default: 0.0 -- animatable

Applies a random perturbation to the vertices of the source object.
<Scatter>.Animation_Offset Time default: 0f -- animatable
The number of frames by which each source object duplicate’s animation is offset from the
previous duplicate.
<Scatter>.x_rotation Float default: 0.0 -- animatable
The maximum random rotational offset you want about the local X-axis of each duplicate.
<Scatter>.y_rotation Float default: 0.0 -- animatable
The maximum random rotational offset you want about the local Y-axis of each duplicate.
<Scatter>.z_rotation Float default: 0.0 -- animatable
The maximum random rotational offset you want about the local Z-axis of each duplicate.
<Scatter>.X_Translation Float default: 0.0 -- animatable
The maximum random movement you want along the X-axis of each duplicate.
<Scatter>.Y_Translation Float default: 0.0 -- animatable
The maximum random movement you want along the Y-axis of each duplicate.
<Scatter>.Z_Translation Float default: 0.0 -- animatable
The maximum random movement you want along the Z-axis of each duplicate.
<Scatter>.A_Translation_on_Face Float default: 0.0 -- animatable
The first barycentric coordinate on the surface of the face, upon which duplicates are
translated.
<Scatter>.B_Translation_on_Face Float default: 0.0 -- animatable
The second barycentric coordinate on the surface of the face, upon which duplicates are
translated.
<Scatter>.N_Translation_on_Face Float default: 0.0 -- animatable
The offset along the normal of the face, upon which duplicates are translated.
<Scatter>.Local_X_Scaling Float default: 0.0 -- animatable
The percent of random scaling along the X-axis of each duplicate.
<Scatter>.Local_Y_Scaling Float default: 0.0 -- animatable
The percent of random scaling along the X-axis of each duplicate.
<Scatter>.Local_Z_Scaling Float default: 0.0 -- animatable
The percent of random scaling along the X-axis of each duplicate.
The following properties are available only after the Scatter object has been created. The values
shown for the properties are those for a Scatter object created from two boxes. The operand
transforms are in the local coordinate system of the Scatter object.
<Scatter>.S_Box04 SubAnim default: SubAnim:S_Box04
<Scatter>.Operand_A_Transform SubAnim default: SubAnim:Operand_A_Transform
<Scatter>.D_Box05 SubAnim default: SubAnim:D_Box05
<Scatter>.Operand_B_Transform SubAnim default: SubAnim:Operand_B_Transform

Note:
Many properties associated with Scatter are not accessible to MAXScript in 3ds max 4.
 ShapeMerge : GeometryClass 893

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

ShapeMerge : GeometryClass
Constructor:
ShapeMerge compound objects are not constructable by MAXScript in 3ds max 4.
Properties:
<ShapeMerge>.Operation_Type Integer default: 1
Set the shapemerge operation type:
Cookie Cutter (Cuts the shape out of the mesh object’s surface.)
Merge (Merges the shape with the surface of the mesh object.)
<ShapeMerge>.Remove_Interior_Exterior Integer default: 0
Reverses the effect of Cookie Cutter or Merge. With the Cookie Cutter option, the effect is
obvious. When Invert is off, the shape is a hole in the mesh object. When Invert is on, the
shape is solid and the mesh is missing. When you’re using Merge, Invert reverses the sub-
object mesh selection.
Invert OFF
Invert ON
<ShapeMerge>.Output_Sub_Mesh_Selection Integer default: 0
Sets which selection level is output:
None (Outputs the full object.)
Vertex (Outputs the vertices defined by the spline of the shape.)
Edge (Outputs the edge of the merged shape.)
Face (Outputs the faces within the merged shape.)
The following properties are available only after the ShapeMerge object has been created. The
values shown for the properties are those for a ShapeMerge object created from a sphere and a
circle. SubAnims similar to the Circle01 SubAnim would be created if additions operands were
used. The operand transforms are in the local coordinate system of the ShapeMerge object.
<ShapeMerge>.mesh__sphere01 SubAnim default: SubAnim:Mesh__Sphere01
<ShapeMerge>.mesh_transform SubAnim default: SubAnim:Mesh_Transform
<ShapeMerge>.shape_1__circle01 SubAnim default: SubAnim:Shape_1__Circle01
<ShapeMerge>.shape_1_transform SubAnim default: SubAnim:Shape_1_Transform
894 Chapter 11 | 3ds max Objects

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Terrain : GeometryClass
Constructor:
Terrain()

Properties:
<Terrain>.Form Integer default: 1
Set the terrain form:
Graded Surface (Creates a graded surface of the mesh over the contours.)
Graded Solid (Creates a graded surface with skirts around the sides and a bottom surface.
This represents a solid that is visible from every direction.)
Layered Solid (Creates a “wedding cake” or laminated solid similar to cardboard
architectural models.)
<Terrain>.stitchBorder Boolean default: false
Turn on/off stitch border.
<Terrain>.retriangulate Boolean default: false
Turn on/off retriangulate.
<Terrain>.display Integer default: 0
Select the type of display for the terrain object:
Terrain (Displays only the triangulated mesh over the contour line data.)
Contours (Displays only the contour line data of the terrain object.)
Both (Displays both the triangulated mesh and the contour line data of the terrain object.)
<Terrain>.update Integer default: 0
Set update settings for the terrain object:
Always (Updates the terrain object immediately when you change an operand, including
the original object of an instanced or referenced operand.)
When Rendering (Updates the terrain object when you render the scene or when you force
an update. With this option, viewports won’t show current geometry unless you.)
Manually (Updates the terrain object when you force an update.)
 Terrain : GeometryClass 895

Note:
The following properties of terrain compound objects cannot be operated on with MAXScript in
3ds max R4. However, they can be used by MAXScript in 3D Studio VIZ.
<Terrain>.numOps Integer default: 0
The number of contour operands. Read-only.
<Terrain>.horizSimplification Integer default: 0
horizSimplification = 0 – No Simplification; 1 – Use 1/2 of Points; 2 - Use 1/4 of Points; 3 –
Interpolate Points * 2; 4 - Interpolate Points * 4
<Terrain>.vertSimplification Integer default: 0
vertSimplification = 0 - No Simplification; Use 1/2 of Lines; 2 - Use 1/4 of Lines
The following properties are available only after the terrain object has been created. The values
shown for the properties are those for a terrain object created from three circles. The operand
transforms are in the local coordinate system of the terrain object.
<Terrain>.Op_0__Circle01 SubAnim default: SubAnim:Op_0__Circle01
<Terrain>.Op_0_Transform SubAnim default: SubAnim:Op_0_Transform
<Terrain>.Op_1__Circle02 SubAnim default: SubAnim:Op_1__Circle02
<Terrain>.Op_1_Transform SubAnim default: SubAnim:Op_1_Transform
<Terrain>.Op_2__Circle03 SubAnim default: SubAnim:Op_2__Circle03
<Terrain>.Op_2_Transform SubAnim default: SubAnim:Op_2_Transform

Note:
All properties other than Form are not accessible in 3ds max.
Methods:
The following methods are available in 3DS VIZ:
terrainOps.addOperand <terrain> <node>
Appends a node as a contour operand to the terrain. Note this is done in ‘Move’ mode, so
the the supplied node is deleted after the addition. To simulate other modes, use
appropriate MAXScript functions. For example,
terrainOps.addOperand $terrain01 (instance $line03)

terrainOps.deleteOperand <terrain> <index_integer>

Deletes the indexed operand, index_integer is 1-based.
terrainOps.getOperand <terrain> <index_integer>
Returns the indexed contour operand as a 3ds max base object (not a node),
index_integer is 1-based.
896 Chapter 11 | 3ds max Objects

terrainOps.getOperandTM <terrain> <index_integer>

Returns the indexed operand’s local transformation matrix as a Matrix3 value. This
transformation matrix is relative to the terrain’s node transformation matrix.
terrainOps.setOperandTM <terrain> <index_integer> <matrix3>
Sets the indexed operand’s local transformation matrix. This transformation matrix is
relative to the terrain’s node transformation matrix.
terrainOps.update <terrain>
Forces a terrain update for those in manual update mode.
Note:
The above methods are defined in the Landform DLL and so will only be present if the Landform
DLL has been loaded. In installations set up with delayed plugin loading enabled, this will happen
automatically if there are any existing terrain objects in the scene or a terrain object is created in the
user interface or via MAXScript.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Geometry - Doors and Windows

The following list displays the door and window objects:
Awning (p. 897)
BiFold (p. 897)
Casement (p. 898)
Fixed (p. 899)
Pivot (p. 899)
Pivoted (p. 900)
Projected (p. 901)
SlidingDoor (p. 901)
SlidingWindow (p. 902)
 Awning : GeometryClass 897

Awning : GeometryClass
Constructor:
awning ...

Properties:
<Awning>.height Float default: 0.0 -- animatable
<Awning>.width Float default: 0.0 -- animatable
<Awning>.depth Float default: 0.0 -- animatable
<Awning>.Horizontal_Frame_Width Float default: 2.0 -- animatable
<Awning>.Vertical_Frame_Width Float default: 2.0 -- animatable
<Awning>.Frame_Thickness Float default: 0.5 -- animatable
<Awning>.Glazing_Thickness Float default: 0.25 -- animatable
<Awning>.Rail_Width Float default: 1.0 -- animatable
<Awning>.Number_of_Panels Integer default: 1
<Awning>.Percent_Open Integer default: 0 -- animatable
<Awning>.Generate_Mapping_Coords Boolean default: false

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

BiFold : GeometryClass
Constructor:
bifold ...

Properties:
<BiFold>.height Float default: 0.0 -- animatable
<BiFold>.width Float default: 0.0 -- animatable
<BiFold>.depth Float default: 0.0 -- animatable
<BiFold>.Double_Doors Integer default: 0
Double_Doors = 0 - false; 1 - true
<BiFold>.Flip_Swing Boolean default: false
<BiFold>.Flip_Hinge Boolean default: false
<BiFold>.open Float default: 0.0 -- animatable
<BiFold>.Create_Frame Boolean default: true
<BiFold>.Frame_Width Float default: 2.0 -- animatable
<BiFold>.Frame_Depth Float default: 1.0 -- animatable
<BiFold>.Door_Offset Float default: 0.0 -- animatable
<BiFold>.Generate_Mapping_Coords Boolean default: false
<BiFold>.Leaf_Thickness Float default: 2.0 -- animatable
<BiFold>.Stiles_Top_Rail Float default: 4.0 -- animatable
898 Chapter 11 | 3ds max Objects

<BiFold>.Bottom_Rail Float default: 12.0 -- animatable

<BiFold>.Number_of_Panels_Horizontally Integer default: 1
<BiFold>.Number_of_Panels_Vertically Integer default: 1
<BiFold>.Muntin Float default: 2.0 -- animatable
<BiFold>.Panel_Type Integer default: 1
Panel_Type = 0 - None; 1 - Glass; 2 - Beveled
<BiFold>.Glass_Thickness Float default: 0.25 -- animatable
<BiFold>.Bevel_Angle Float default: 45.0 -- animatable
<BiFold>.Panel_Thickness_1 Float default: 0.25 -- animatable
<BiFold>.Panel_Thickness_2 Float default: 0.5 -- animatable
<BiFold>.Panel_Middle_Thickness Float default: 0.25 -- animatable
<BiFold>.Panel_Width_1 Float default: 1.0 -- animatable
<BiFold>.Panel_Width_2 Float default: 0.5 -- animatable

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Casement : GeometryClass
Constructor:
casement ...

Properties:
<Casement>.height Float default: 0.0 -- animatable
<Casement>.width Float default: 0.0 -- animatable
<Casement>.depth Float default: 0.0 -- animatable
<Casement>.Horizontal_Frame_Width Float default: 2.0 -- animatable
<Casement>.Vertical_Frame_Width Float default: 2.0 -- animatable
<Casement>.Frame_Thickness Float default: 0.5 -- animatable
<Casement>.Glazing_Thickness Float default: 0.25 -- animatable
<Casement>.Panel_Width Float default: 1.0 -- animatable
<Casement>.Number_of_Casements Integer default: 1
Number_of_Casements = 1 - One; 2 - Two
<Casement>.Percent_Open Integer default: 0 -- animatable
<Casement>.Opens_to_Inside Boolean default: false
<Casement>.Generate_Mapping_Coords Boolean default: false
 Fixed : GeometryClass 899

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Fixed : GeometryClass
Constructor:
fixed ...

Properties:
<Fixed>.height Float default: 0.0 -- animatable
<Fixed>.width Float default: 0.0 -- animatable
<Fixed>.depth Float default: 0.0 -- animatable
<Fixed>.Horizontal_Frame_Width Float default: 2.0 -- animatable
<Fixed>.Vertical_Frame_Width Float default: 2.0 -- animatable
<Fixed>.Frame_Thickness Float default: 0.5 -- animatable
<Fixed>.Glazing_Thickness Float default: 0.25 -- animatable
<Fixed>.Rail_Width Float default: 1.0 -- animatable
<Fixed>.Number_of_Panels_Horizontally Integer default: 1
<Fixed>.Number_of_Panels_Vertically Integer default: 1
<Fixed>.Chamfered_Profile Boolean default: false
<Fixed>.Generate_Mapping_Coords Boolean default: false

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Pivot : GeometryClass
Constructor:
pivot ...

Properties:
<pivot>.height Float default: 0.0 -- animatable
<pivot>.width Float default: 0.0 -- animatable
<pivot>.depth Float default: 0.0 -- animatable
<pivot>.Double_Doors Integer default: 0
Double_Doors = 0 - false; 1 - true
900 Chapter 11 | 3ds max Objects

<pivot>.Flip_Swing Boolean default: false

<pivot>.Flip_Hinge Boolean default: false
<pivot>.Open__degrees Float default: 0.0 -- animatable
<pivot>.Create_Frame Boolean default: true
<pivot>.Frame_Width Float default: 2.0 -- animatable
<pivot>.Frame_Depth Float default: 1.0 -- animatable
<pivot>.Door_Offset Float default: 0.0 -- animatable
<pivot>.Generate_Mapping_Coords Boolean default: false
<pivot>.Leaf_Thickness Float default: 2.0 -- animatable
<pivot>.Stiles_Top_Rail Float default: 4.0 -- animatable
<pivot>.Bottom_Rail Float default: 12.0 -- animatable
<pivot>.Number_of_Panels_Horizontally Integer default: 1
<pivot>.Number_of_Panels_Vertically Integer default: 1
<pivot>.Muntin Float default: 2.0 -- animatable
<pivot>.Panel_Type Integer default: 1
Panel_Type = 0 - None; 1 - Glass; 2 - Beveled
<pivot>.Glass_Thickness Float default: 0.25 -- animatable
<pivot>.Bevel_Angle Float default: 45.0 -- animatable
<pivot>.Panel_Thickness_1 Float default: 0.25 -- animatable
<pivot>.Panel_Thickness_2 Float default: 0.5 -- animatable
<pivot>.Panel_Middle_Thickness Float default: 0.25 -- animatable
<pivot>.Panel_Width_1 Float default: 1.0 -- animatable
<pivot>.Panel_Width_2 Float default: 0.5 -- animatable

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Pivoted : GeometryClass
Constructor:
pivoted ...

Properties:
<Pivoted>.height Float default: 0.0 -- animatable
<Pivoted>.width Float default: 0.0 -- animatable
<Pivoted>.depth Float default: 0.0 -- animatable
<Pivoted>.Horizontal_Frame_Width Float default: 2.0 -- animatable
<Pivoted>.Vertical_Frame_Width Float default: 2.0 -- animatable
<Pivoted>.Frame_Thickness Float default: 0.5 -- animatable
<Pivoted>.Glazing_Thickness Float default: 0.25 -- animatable
<Pivoted>.Rail_Width Float default: 1.0 -- animatable
<Pivoted>.Vertical_Rotation Boolean default: false
<Pivoted>.Percent_Open Integer default: 0 -- animatable
<Pivoted>.Generate_Mapping_Coords Boolean default: false
 Projected : GeometryClass 901

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Projected : GeometryClass
Constructor:
projected ...

Properties:
<projected>.height Float default: 0.0 -- animatable
<projected>.width Float default: 0.0 -- animatable
<projected>.depth Float default: 0.0 -- animatable
<projected>.Horizontal_Frame_Width Float default: 2.0 -- animatable
<projected>.Vertical_Frame_Width Float default: 2.0 -- animatable
<projected>.Frame_Thickness Float default: 0.5 -- animatable
<projected>.Glazing_Thickness Float default: 0.25 -- animatable
<projected>.Rail_Width Float default: 1.0 -- animatable
<projected>.Middle_Height Float default: 0.0 -- animatable
<projected>.Bottom_Height Float default: 0.0 -- animatable
<projected>.Percent_Open Integer default: 0 -- animatable
<projected>.Generate_Mapping_Coords Boolean default: false

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SlidingDoor : GeometryClass
Constructor:
slidingDoor ...

Properties:
<SlidingDoor>.height Float default: 0.0 -- animatable
<SlidingDoor>.width Float default: 0.0 -- animatable
<SlidingDoor>.depth Float default: 0.0 -- animatable
<SlidingDoor>.Flip_Swing Boolean default: false
<SlidingDoor>.Flip_Hinge Boolean default: false
<SlidingDoor>.open Float default: 0.0 -- animatable
<SlidingDoor>.Create_Frame Boolean default: true
902 Chapter 11 | 3ds max Objects

<SlidingDoor>.Frame_Width Float default: 2.0 -- animatable

<SlidingDoor>.Frame_Depth Float default: 1.0 -- animatable
<SlidingDoor>.Door_Offset Float default: 0.0 -- animatable
<SlidingDoor>.Generate_Mapping_Coords Boolean default: false
<SlidingDoor>.Leaf_Thickness Float default: 2.0 -- animatable
<SlidingDoor>.Stiles_Top_Rail Float default: 4.0 -- animatable
<SlidingDoor>.Bottom_Rail Float default: 12.0 -- animatable
<SlidingDoor>.Number_of_Panels_Horizontally Integer default: 1
<SlidingDoor>.Number_of_Panels_Vertically Integer default: 1
<SlidingDoor>.Muntin Float default: 4.0 -- animatable
<SlidingDoor>.Panel_Type Integer default: 1
Panel_Type = 0 - None; 1 - Glass; 2 - Beveled
<SlidingDoor>.Glass_Thickness Float default: 0.25 -- animatable
<SlidingDoor>.Bevel_Angle Float default: 45.0 -- animatable
<SlidingDoor>.Panel_Thickness_1 Float default: 0.25 -- animatable
<SlidingDoor>.Panel_Thickness_2 Float default: 0.5 -- animatable
<SlidingDoor>.Panel_Middle_Thickness Float default: 0.25 -- animatable
<SlidingDoor>.Panel_Width_1 Float default: 1.0 -- animatable
<SlidingDoor>.Panel_Width_2 Float default: 0.5 -- animatable
<SlidingDoor>.Double_Doors Integer default: 0

Note:
The Double_Doors property is not used by SlidingDoor.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SlidingWindow : GeometryClass
Constructor:
slidingWindow ...

Properties:
<SlidingWindow>.height Float default: 0.0 --
animatable
<SlidingWindow>.width Float default: 0.0 --
animatable
<SlidingWindow>.depth Float default: 0.0 --
animatable
<SlidingWindow>.Horizontal_Frame_Width Float default: 2.0 --
animatable
<SlidingWindow>.Vertical_Frame_Width Float default: 2.0 --
animatable
 QuadPatch : GeometryClass 903

<SlidingWindow>.Frame_Thickness Float default: 0.5 --

animatable
<SlidingWindow>.Glazing_Thickness Float default: 0.25 --
animatable
<SlidingWindow>.Rail_Width Float default: 1.0 --
animatable
<SlidingWindow>.Number_of_Panels_Horizontally Integer default: 1
<SlidingWindow>.Number_of_Panels_Vertically Integer default: 1
<SlidingWindow>.Chamfered_Profile Boolean default: false
<SlidingWindow>.Hung Boolean default: true
<SlidingWindow>.Percent_Open Integer default: 0 --
animatable
<SlidingWindow>.Generate_Mapping_Coords Boolean default: false

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Geometry - Patch Objects

The following list displays the patch objects:
QuadPatch (p. 903)
TriPatch (p. 904)

QuadPatch : GeometryClass
Constructor:
quadpatch ...

Properties:
<QuadPatch>.length Float default: 25.0 -- animatable
The patch length.
<QuadPatch>.width Float default: 25.0 -- animatable
The patch width.
<QuadPatch>.lengthsegs Integer default: 1 -- animatable, alias:
Length_Segments
The number of facets along the length of the grid.
<QuadPatch>.mapCoords Boolean default: false
When on, applies mapping coordinates to the grid.
<QuadPatch>.widthsegs Integer default: 1 -- animatable, alias:
Width_Segments
The number of facets along the width of the grid.
904 Chapter 11 | 3ds max Objects

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TriPatch : GeometryClass
Constructor:
TriPatch ...

Properties:
<TriPatch>.length Float default: 25.0 -- animatable
The length of the patch.
<TriPatch>.width Float default: 25.0 -- animatable
The width of the patch.
<TriPatch>.mapCoords Boolean default: false
When on, applies mapping coordinates to the grid.

See also
GeometryClass Common Properties, Operators, and Methods (p. 852)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Geometry - Particle Systems

The following list displays the particle system objects:
Blizzard (p. 906)
PArray (p. 913)
PCloud (p. 923)
Snow (p. 931)
Spray (p. 933)
SuperSpray (p. 935)
Note: Particle Systems are not available in 3D Studio VIZ.
 Particle System Common Properties, Operators, and Methods 905

Particle System Common Properties, Operators, and Methods

Eight <node> functions work with particle system objects in 3ds max to allow you to get or set
individual particle information. These functions return or set information about particles at the time
set by the current ‘at time’ context clause, or the current time slider if there is not time context
active.
A quick note about how the particle systems in 3ds max work will help you use these functions. The
particle system keeps an array of particles big enough to hold all those alive at any one time. Each
particle is identified by an index in this array. When one dies, it may be ‘born’ again sometime later
and appear to be a different particle. Over the course of an animation, the same ‘particle’ may live
and die many times as its indexed slot in the array gets re-used. Some of the functions described
below use this index to identify particles, so you can have a situation where the ‘same’ particle (by
index) becomes a new particle in the animation as its slot gets re-used. The way you can check this
is by looking at the ‘age’ of the particle - if it cycles around to zero (or a lower number depending
on time resolution), you know it has become a ‘new’ particle. If a particle is actually not alive at a
given time, for example at the beginning of an animation or when you set up an ‘explosive’
emission, the functions below that get position, velocity and age return undefined. This tells you
that the particle is not currently alive.
Here are the particle system functions:
particleCount <particlesys_node>
Returns the number of current particle slots in the system as an integer. This value is the
number of particles that are to be drawn to the viewports unless the scene is currently
being rendered. If the scene is being rendered, the number returned can be either the
render count or the viewport count, depending on whether the particle system has been
evaluated for rendering or not.
particleSize <particlesys_node>
Returns the size of the particles in the system as float. This is set in the particle system
parameter rollout - there is one size for all particles in a particle system. If you are using
these functions to attach objects to particles, you can of course, make the individual
objects any size you want.
particlePos <particlesys_node> <particle_index_integer>
Returns the position coordinate of the indexed particle at the current time as a point3.
Indexes are 1-based. The coordinate returned is in the current working coordinate system.
Returns undefined if the particle is not alive at the current time.
particleVelocity <particlesys_node> <particle_index_integer>
Returns the current velocity vector for the indexed particle as a point3. The vector
returned is rotated into the current working coordinate system. Returns undefined if the
particle is not alive at the current time.
particleAge <particlesys_node> <particle_index_integer>
Returns the current age of the indexed particle as a time value, relative to when it was last
born. Remember, particles get recycled and you can detect this by looking at the age value
cycling round. Returns undefined if the particle is not alive at the current time.
906 Chapter 11 | 3ds max Objects

Blizzard : GeometryClass
Constructor:
blizzard ...

Note: This class is not available in 3D Studio VIZ.

Properties:
-- Basic Parameters
<Blizzard>.Emitter_Width Float default: 0.0 --
animatable
The width of the emitter icon.
<Blizzard>.Emitter_Length Float default: 0.0 --
animatable
The width of the emitter icon.
<Blizzard>.emitterHidden Boolean default: false
When on, hides the emitter in viewports. When off, the emitter is displayed in viewports.
The emitter is never rendered.
<Blizzard>.viewType Integer default: 0
Set the display icon for particles in the viewport:
Dots (Displays the particles as dots.)
Ticks (Displays the particles as crosses.)
Mesh (Displays the particles as mesh objects. This results in slower viewport redraws.)
Bbox (For instanced geometry only, this displays each instanced particle, whether a single
object, a hierarchy, or a group, as a bounding box.)
<Blizzard>.viewPercent Float default: 10.0 --
percentage, alias: Percentage_Displayed
Sets the percentage of particles displayed in the viewport.
-- Particle Generation
<Blizzard>.quantityMethod Integer default: 0
Set the method by which the number of particles is determined over time:
Use Rate (Specifies a fixed number of particles emitted per frame.)
Use Total (Specifies a total number of particles formed over the life of the system.)
Tip: Generally, Use Rate is best for a continuous flow of particles, like a trail of pixie dust,
while Use Total is better for bursts of particles over a short period of time.
<Blizzard>.Birth_Rate Integer default: 10 --
animatable
The number of particles emitted per frame.
<Blizzard>.Total_Number Integer default: 100
The total number of particles to be emitted.
 Blizzard : GeometryClass 907

<Blizzard>.speed Float default: 10.0 --

animatable
The velocity of the particle at birth, along the normal, in units traveled per frame.
<Blizzard>.Speed_Variation Float default: 0.0 --
animatable, percentage
Percentage of variation to the speed of emission for each particle.
<Blizzard>.tumble Float default: 0.0 --
animatable
Amount of random rotation of the particles.
<Blizzard>.Tumble_Rate Float default: 0.0 --
animatable
Speed at which the particles rotate.
<Blizzard>.Emitter_Start Time default: 0f
The frame at which particles begin to exist in the scene.
<Blizzard>.Emitter_Stop Time default: 30f
The last frame at which particles are emitted.
<Blizzard>.Display_Until Time default: 100f
Time at which all particles will disappear, regardless of other settings.
<Blizzard>.life Time default: 30f --
animatable
The lifespan of each particle from the time of creation.
<Blizzard>.Life_Variation Time default: 0f --
animatable
The number of frames by which the life of each particle can vary from the norm.
<Blizzard>.subsampleCreationTime Boolean default: false
When on, enables the addition of a time offset to the equations of motion that prevents
puffing in time.
<Blizzard>.subsampleEmitterTranslation Boolean default: true
If the object-based emitter is moving in space, particles are created at integral times at
positions along the geometry’s path between renderable positions. This prevents puffing
in space.
<Blizzard>.subsampleEmitterRotation Boolean default: true
If the emitter is rotating, turn this on to avoid puffing and produce smooth spiral effects.
<Blizzard>.size Float default: 1.0 --
animatable
The target size for all particles in the system.
<Blizzard>.Size_Variation Float default: 0.0 --
animatable, percentage
The percentage by which the size of each particle may vary from the norm.
<Blizzard>.Growth_Time Time default: 10f
The number of intervals over which the particle grows from being very small (0.1a system
constant) to the Size value.
908 Chapter 11 | 3ds max Objects

<Blizzard>.Fade_Time Time default: 10f

The number of intervals over which the particle will shrink to 1/10th its Size setting prior
to its death.
<Blizzard>.seed Integer default: 0 --
alias: Random_Seed
By changing the Seed value, you achieve different results using otherwise identical particle
settings.
-- Particle Type
<Blizzard>.particleType Integer default: 0
The type of particle emitted:
Standard Particle (Uses one of several standard particle types, such as triangle, cube, tetra,
and so on.)
MetaParticles (Uses Metaball particles. These are particle systems in which the individual
particles blend together in blobs or streams.)
Instanced Geometry (Generates particles that are instances of either an object, a linked
hierarchy of objects, or a group.)
<Blizzard>.standardParticle Integer default: 0
standardParticle = 0 - Triangle; 1 - Cube; 2 - Special; 3 - Facing; 4 - Constant; 5 - Tetra; 6 -
SixPoint; 7 - Sphere
<Blizzard>.Metaparticle_Tension Float default: 1.0 --
animatable
Determines the tightness of the particles, with regard to their tendency to blend with
other particles. The higher the Tension, the harder the blobs, and the harder it is for them
to merge.
<Blizzard>.Metaparticle_Tension_Variation Float default: 0.0 --
animatable, percentage
The percent of variation of the Tension effect.
<Blizzard>.metaballRenderCoarsness Float default: 0.5 --
alias: Metaparticle_Coarseness
The coarseness for metaparticles in the rendered scene.
<Blizzard>.metaballViewCoarsness Float default: 1.0
The coarseness for the viewport display.
<Blizzard>.metaballAutoCoarsness Boolean default: true
When this is on, the rendering coarseness is automatically set, based on the size of the
particles, and the viewport coarseness is set to about twice that of the rendering
coarseness.
<Blizzard>.Bubble_Amplitude Integer default: 0
Turns on/off One Connected Blob.
OFF
ON
 Blizzard : GeometryClass 909

<Blizzard>.instancingObject Node default: undefined

The object which is instanced.
<Blizzard>.instanceSubTree Boolean default: false
Turn this on when you want to include the linked children of the picked object in the
particle. If the picked object is a group, all children of the group are included.
<Blizzard>.instanceKeyOffsetType Integer default: 0
Set the animation offset keying:
None (Each particle duplicates the timing of the original object. As a result, the animation
of all particles will be identically timed.)
Birth (The firstborn particle is an instance of the current animation of the source object at
the moment of that particle’s birth. Each subsequent particle then use the same start time
for the animation.)
Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each
particle is born using the same animation as the source object at the time of birth, but
with a random offset of frames, based on the .instanceFrameOffset value.)
<Blizzard>.instanceFrameOffset Integer default: 0 --
alias: Animation_Offset_Amount
The property value is the UI value times the number of ticks per frame. The number of
ticks per frame is accessible via the ticksPerFrame system global variable.
<Blizzard>.mappingType Integer default: 0
Specifies how a mapped material affects the particles:
Time (Maps particles over time.)
Distance (Maps particles over a distance.)
Emitter Fit Planar (Maps particles at birth, based on their point of emission from the
rectangular Blizzard emitter icon. The UV range of the mapped material runs from 0 to 1
over the width and length of the emitter.)
<Blizzard>.Mapping_Time_Base Time default: 30f --
animatable
The number of frames from the birth of the particle that it takes to complete one mapping
of the particle.
<Blizzard>.Mapping_Distance_Base Float default: 100.0 --
animatable
The distance, in units, from the birth of the particle that it takes to complete one mapping
of the particle.
<Blizzard>.materialSource Integer default: 0
Updates the material carried by the particle system, using the source specified:
Icon (The particles use the material currently assigned to the particle system icon.)
Instanced Geometry (The particles use the material assigned to the instanced geometry.)
910 Chapter 11 | 3ds max Objects

-- Rotation and Collision

<Blizzard>.Spin_Time Time default: 30f --
animatable
The number of frames for one rotation of a particle. If set to 0, no rotation takes place.
<Blizzard>.Spin_Time_Variation Float default: 0.0 --
animatable, percentage
The percent of variation of the Spin Time.
<Blizzard>.Spin_Phase Float default: 0.0 --
animatable, angle
The initial particle rotation, in degrees.
<Blizzard>.Spin_Phase_Variation Float default: 0.0 --
animatable, percentage
The percent of variation of the Phase.
<Blizzard>.spinAxisType Integer default: 0
The spin axis for the particles:
Random (The spin axis for each of the particles is random.)
User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.)
<Blizzard>.X_Spin_Vector Float default: 1.0 --
animatable
Spin vector of the X-axis.
<Blizzard>.Y_Spin_Vector Float default: 0.0 --
animatable
Spin vector of the Y-axis.
<Blizzard>.Z_Spin_Vector Float default: 0.0 --
animatable
Spin vector of the Z-axis.
<Blizzard>.Spin_Axis_Variation Float default: 0.0 --
animatable, angle
The amount, in degrees, by which the spin axis of each particle may vary from the
specified X Axis, Y Axis, and Z Axis settings.
<Blizzard>.Interparticle_Collisions_On Integer default: 0
Turn on/off interparticle collisions:
OFF
ON
<Blizzard>.Interparticle_Collision_Steps Integer default: 2
The number of intervals per rendering interval, during which an inter-particle collision
test is conducted. The higher the value, the more accurate the simulation, but the slower
the simulation will run.
<Blizzard>.Interparticle_Collision_Bounce Float default: 100.0 --
animatable, percentage
The degree to which speed is recovered after a collision.
 Blizzard : GeometryClass 911

<Blizzard>.Interparticle_Collision_Bounce_Variation Float default: 0.0 --

animatable, percentage
The percentage of random variation of the Bounce value, applied to the particles.
-- Object Motion Inheritance
<Blizzard>.motionInfluence Float default: 100.0 --
animatable, alias: Object_Motion_Inheritance
The percent of particles that inherit the motion of the object-based emitter at the moment
of particle formation.
<Blizzard>.motionMultiplier Float default: 1.0 --
animatable, alias: Object_Motion_Multiplier
Modifies the amount by which the emitter motion affects the particle motion. This can be
a positive or negative number.
<Blizzard>.motionVariation Float default: 0.0 --
animatable, percentage; alias: Object_Motion_Multiplier_Variation
Percentage of variation of the Multiplier value.
-- Particle Spawn
<Blizzard>.spawnType Integer default: 0
Determines what happens to particles at either collision or death:
None (Particles act as they normally would. That is, upon collision, they either bounce or
stick, depending on Particle Bounce settings in the deflector, and on death they disappear.)
Die After Collision (Particles disappear when they strike a deflector to which they’re
bound, such as the SDeflector.)
Spawn on Collision (Spawn effects take place upon collision with a bound deflector.)
Spawn on Death (Spawn effects take place at the end of each particle’s life.)
Spawn Trails (Particles are spawned from existing particles at each frame of that
particle’s life.)
<Blizzard>.Die__X_frames_after_collision Time default: 0f --
animatable
The life, in frames, that the particle will persist after the collision. Setting this to 0 (the
default) causes particles to vanish immediately after the collision.
<Blizzard>.Die__X_frames_after_collision_variation Float default: 0.0 --
animatable, percentage
Varies the Persist value of each particle, when Persist is greater than 0. This lets you
“feather” the dying off of the particle density.
<Blizzard>.Spawn_Affects Integer default: 100
The percentage of particles that will spawn. Reducing this reduces the number of particles
that produce spawned particles.
<Blizzard>.Spawn_Multiplier_Variation Float default: 0.0 --
percentage
Percentage range by which the Multiplier value will vary, frame by frame.
912 Chapter 11 | 3ds max Objects

<Blizzard>.Spawn_Direction_Chaos Float default: 0.0 --

animatable
The amount by which the direction of the spawned particle can vary from the direction of
the parent particle. A setting of 0 means no variance. A setting of 100 causes the spawned
particle to travel in any random direction. A setting of 50 causes the spawned particle to
deviate from its parent’s path by up to 90 degrees.
<Blizzard>.Spawn_Speed_Chaos Float default: 0.0 --
animatable
The range of a percentage of change in the speed of the spawned particle relative to its
parent. A value of 0 means no change.
<Blizzard>.spawnSpeedType Integer default: 0
Sets the type of speed applied to spawn particles:
Slow (Applies the .spawn_Speed_Chaos value randomly to slow the speed of the
spawned particles.)
Fast (Randomly speeds up particles based on the .spawn_Speed_Chaos value.)
Both (Some particles speed up, while others slow down, based on the
.spawn_Speed_Chaos value.)
<Blizzard>.spawnInheritVelocity Boolean default: false
When on, spawned particles inherit the speed of their parents, in addition to the effect of
the .spawn_Speed_Chaos value.
<Blizzard>.spawnSpeedFixed Boolean default: false
When on, uses the .spawn_Speed_Chaos value as a set value, rather than as a range
applied randomly to each particle.
<Blizzard>.lifespanValueQueue Array default: #()
lifespanValueQueue is an array of integers which correspond to lifespan values for each
spawned generation of particles.
<Blizzard>.objectMutationQueue Array default: #()
objectMutationQueue is an array of nodes which correspond to instanced-object
particle types. Each generation of spawning will use the next node as its object type.

See also
Particle System Common Properties, Operators, and Methods (p. 905)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 PArray : GeometryClass 913

PArray : GeometryClass
Constructor:
parray ...

Note: This class is not available in 3D Studio VIZ.

Properties:
-- Basic Parameters
<PArray>.emitter Node default: undefined
The object which acts as an emitter.
<PArray>.formation Integer default: 0 --
alias: Emitter_Distribution
Set the emitter distribution type:
Over Entire Surface (Emits particles randomly over the entire surface of the object-based
emitter.)
Along Visible Edges (Emits particles randomly from the visible edges of the object.)
At All Vertices (Emits particles from the vertices of the object.)
At Distinct Points (Places a specified number of emitter points randomly over the surface
of the object.)
At Face Centers (Emits particles from the center of each triangular face.)
<PArray>.numDistinctPoints Integer default: 20 --
alias: Number_of_Emitters
The number of emitter points used when At Distinct Points is chosen.
<PArray>.Use_Selected_Subobjects Integer default: 0 --
animatable
With mesh-based emitters, this limits the source of the particle stream to the sub-object
selection passed up the modifier stack in the object-based emitter.
OFF
ON
<PArray>.iconsize Float default: 20.0 --
alias: Emitter_Width
The width of the emitter icon.
<PArray>.iconHidden Boolean default: false
When on, hides the emitter in viewports. When off, the emitter is displayed in viewports.
The emitter is never rendered.
<PArray>.viewType Integer default: 0
Set the display icon for particles in the viewport:
Dots (Displays the particles as dots.)
Ticks (Displays the particles as crosses.)
914 Chapter 11 | 3ds max Objects

Mesh (Displays the particles as mesh objects. This results in slower viewport redraws.)
Bbox (For instanced geometry only, this displays each instanced particle, whether a single
object, a hierarchy, or a group, as a bounding box.)
<PArray>.viewPercent Float default: 10.0 --
percentage, alias: Percentage_Displayed
The percentage of particles displayed in the viewport.
-- Particle Generation
<PArray>.quantityMethod Integer default: 0
Set the method by which the number of particles is determined over time:
Use Rate (Specifies a fixed number of particles emitted per frame.)
Use Total (Specifies a total number of particles formed over the life of the system.)
Tip: Generally, Use Rate is best for a continuous flow of particles, like a trail of pixie dust,
while Use Total is better for bursts of particles over a short period of time.
<PArray>.Birth_Rate Integer default: 10 --
animatable
The number of particles emitted per frame.
<PArray>.Total_Number Integer default: 100
The total number of particles to be emitted.
<PArray>.speed Float default: 10.0 --
animatable
The velocity of the particle at birth, along the normal, in units traveled per frame.
<PArray>.Speed_Variation Float default: 0.0 --
animatable, percentage
Percentage of variation to the speed of emission for each particle.
<PArray>.Divergence_Angle Float default: 10.0 --
animatable, angle
Applies an angular degree of variation by which each particle’s velocity can vary from the
emitter normal.
<PArray>.Emitter_Start Time default: 0f
The frame at which particles begin to exist in the scene.
<PArray>.Emitter_Stop Time default: 30f
The last frame at which particles are emitted.
<PArray>.Display_Until Time default: 100f
Time at which all particles will disappear, regardless of other settings.
<PArray>.life Time default: 30f --
animatable
The lifespan of each particle from the time of creation.
<PArray>.Life_Variation Time default: 0f --
animatable
The number of frames by which the life of each particle can vary from the norm.
 PArray : GeometryClass 915

<PArray>.subsampleCreationTime Boolean default: false

When on, enables the addition of a time offset to the equations of motion that prevents
puffing in time.
<PArray>.subsampleEmitterTranslation Boolean default: true
If the object-based emitter is moving in space, particles are created at integral times at
positions along the geometry’s path between renderable positions. This prevents puffing
in space.
<PArray>.subsampleEmitterRotation Boolean default: true
If the emitter is rotating, turn this on to avoid puffing and produce smooth spiral effects.
<PArray>.size Float default: 1.0 --
animatable
The target size for all particles in the system.
<PArray>.Size_Variation Float default: 0.0 --
animatable, percentage
The percentage by which the size of each particle may vary from the norm.
<PArray>.Growth_Time Time default: 10f
The number of intervals over which the particle grows from being very small (0.1a system
constant) to the Size value.
<PArray>.Fade_Time Time default: 10f
The number of intervals over which the particle will shrink to 1/10th its Size setting prior
to its death.
<PArray>.seed Integer default: 0 --
alias: Random_Seed
By changing the Seed value, you achieve different results using otherwise identical particle
settings.
-- Particle Type
<PArray>.particleType Integer default: 0
The type of particle emitted:
Standard Particle (Uses one of several standard particle types, such as triangle, cube, tetra,
and so on.)
MetaParticles (Uses Metaball particles. These are particle systems in which the individual
particles blend together in blobs or streams.)
Object Fragments (Creates particles out of fragments of an object.)
Instanced Geometry (Generates particles that are instances of either an object, a linked
hierarchy of objects, or a group.)
916 Chapter 11 | 3ds max Objects

<PArray>.standardParticle Integer default: 0

Set the type of particle used when standard particles is selected:
Triangle (Renders each particle as a triangle. Use Triangle particles with noise opacity for
steam or smoke.)
Cube (Renders each particle as a cube.)
Special (Each particle consists of three intersecting 2D squares. These are effective when
you use a face-map material, optionally along with an opacity map, to create the effect of a
three-dimensional particle.)
Facing (Renders each particle as a square that always faces the view. Use with an
appropriate opacity map for bubbles or snowflakes.)
Constant (Provides a particle that remains the same size, in pixels, specified by the size
value. This size never changes, regardless of its distance from the camera. Note that this
particle type can only be displayed in the viewports as a dot or a tick. If you turn on this
option while Mesh is selected, the viewport display is automatically switched to Ticks.)
Tetra (Renders each particle as a mapped tetrahedron, whose tail points toward the normal
vector of the emission, and whose head points away. Use Tetra particles for raindrops or
sparks.)
SixPoint (Renders each particle as a six-pointed, two-dimensional star.)
Sphere (Renders each particle as a sphere.)
<PArray>.Metaparticle_Tension Float default: 1.0 --
animatable
Determines the tightness of the particles, with regard to their tendency to blend with
other particles. The higher the Tension, the harder the blobs, and the harder it is for them
to merge.
<PArray>.Metaparticle_Tension_Variation Float default: 0.0 --
animatable, percentage
The percent of variation of the Tension effect.
<PArray>.metaballRenderCoarsness Float default: 0.5 --
alias: Metaparticle_Coarseness
The coarseness for metaparticles in the rendered scene.
<PArray>.metaballViewCoarsness Float default: 1.0
The coarseness for the viewport display.
<PArray>.metaballAutoCoarsness Boolean default: true
When this is on, the rendering coarseness is automatically set, based on the size of the
particles, and the viewport coarseness is set to about twice that of the rendering
coarseness.
 PArray : GeometryClass 917

<PArray>.fragmentMethod Integer default: 0

Method for object fragment particles:
All Faces (Each face of the object becomes a particle. This results in triangular particles.)
Number of Chunks (The object breaks into irregular fragments.)
Smoothing Angle (The fragments are broken based on the angles between face normals, as
specified in the fragSmoothingAngle value. Generally, the higher the value, the fewer
the number of fragments.)
<PArray>.Fragment_Thickness Float default: 1.0
Sets the thickness of the fragments. At 0, the fragments are single-sided with no thickness.
When greater than 0, the fragments are extruded, at fragmentation time, by the amount
specified. The outer and inner surfaces of the fragment use identical smoothing, which is
picked up from the object-based emitter. The edges of the fragments are not smoothed.
<PArray>.fragChunkMinimum Integer default: 100 --
alias: Fragment_Count
Determines a number of “seed” faces in the geometry. Each seed face collects connecting
faces surrounding it until all available faces are exhausted. Any leftover faces become
unique particles, thus increasing the minimum number of fragments.
<PArray>.fragSmoothingAngle Float default: 0.0
Sets the amount of smoothing angle.
<PArray>.instancingObject Node default: undefined
The object which is instanced.
<PArray>.instanceSubTree Boolean default: false
Turn this on when you want to include the linked children of the picked object in the
particle. If the picked object is a group, all children of the group are included.
<PArray>.instanceKeyOffsetType Integer default: 0
Set the animation offset keying:
None (Each particle duplicates the timing of the original object. As a result, the animation
of all particles will be identically timed.)
Birth (The firstborn particle is an instance of the current animation of the source object at
the moment of that particle’s birth. Each subsequent particle then use the same start time
for the animation.)
Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each
particle is born using the same animation as the source object at the time of birth, but
with a random offset of frames, based on the .instanceFrameOffset value.)
<PArray>.instanceFrameOffset Integer default: 0 --
alias: Animation_Offset_Amount
The property value is the UI value times the number of ticks per frame. The number of
ticks per frame is accessible via the ticksPerFrame system global variable.
918 Chapter 11 | 3ds max Objects

<PArray>.mappingType Integer default: 0

Specifies how a mapped material affects the particles:
Time (Maps particles over time.)
Distance (Maps particles over a distance.)
<PArray>.Mapping_Time_Base Time default: 30f --
animatable
The number of frames from the birth of the particle that it takes to complete one mapping
of the particle.
<PArray>.Mapping_Distance_Base Float default: 100.0 --
animatable
The distance, in units, from the birth of the particle that it takes to complete one mapping
of the particle.
<PArray>.materialSource Integer default: 0
Updates the material carried by the particle system, using the source specified:
Icon (The particles use the material currently assigned to the particle system icon.)
Picked Emitter (The particles use the material assigned to the distribution object.)
Instanced Geometry (The particles use the material assigned to the instanced geometry.)
<PArray>.fragOutsideMatID Integer default: 0
Specifies which face ID number is assigned to the outside faces of the fragments. This
defaults to 0, which is not a valid ID number, forcing the outside of the particle fragments
to use whatever material is currently assigned to the associated faces. Thus, if your
distribution object already has several submaterials assigned to its outer faces, these
materials are retained by using ID 0. If you want a single, specific submaterial, you can
assign it by changing this value.
<PArray>.fragEdgeMatID Integer default: 2
Specifies which submaterial ID number is assigned to the edges of the fragments.
<PArray>.fragBackMatID Integer default: 3
Specifies which submaterial ID number is assigned to the back sides of the fragments.
-- Rotation and Collision
<PArray>.Spin_Time Time default: 0f --
animatable
The number of frames for one rotation of a particle. If set to 0, no rotation takes place.
<PArray>.Spin_Time_Variation Float default: 0.0 --
animatable, percentage
The percent of variation of the Spin Time.
<PArray>.Spin_Phase Float default: 0.0 --
animatable, angle
The initial particle rotation, in degrees.
<PArray>.Spin_Phase_Variation Float default: 0.0 --
animatable, percentage
The percent of variation of the Phase.
 PArray : GeometryClass 919

<PArray>.spinAxisType Integer default: 0

The spin axis for the particles:
Random (The spin axis for each of the particles is random.)
Direction of Travel/Mblur (Rotates the particles about a vector formed by the direction in
which they’re moving.)
User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.)
<PArray>.Blur_Stretch Integer default: 0 --
animatable
When greater than 0, the particles stretch along the travel axis, depending on their speed.
Specifically, the Stretch value specifies the percent of their length per each unit of the
Speed setting (in the Particle Motion group). Thus, if you set Stretch to 2 while Speed is set
at 10, the particles are stretched 20 percent longer than their original size along the axis of
their travel. This value is only available when you choose Direction of Travel/Mblur.
<PArray>.X_Spin_Vector Float default: 1.0 --
animatable
Spin vector of the X-axis.
<PArray>.Y_Spin_Vector Float default: 0.0 --
animatable
Spin vector of the Y-axis.
<PArray>.Z_Spin_Vector Float default: 0.0 --
animatable
Spin vector of the Z-axis.
<PArray>.Spin_Axis_Variation Float default: 0.0 --
animatable, angle
The amount, in degrees, by which the spin axis of each particle may vary from the
specified X Axis, Y Axis, and Z Axis settings.
<PArray>.Interparticle_Collisions_On Integer default: 0
Turn on/off interparticle collisions:
OFF
ON
<PArray>.Interparticle_Collision_Steps Integer default: 2
The number of intervals per rendering interval, during which an inter-particle collision
test is conducted. The higher the value, the more accurate the simulation, but the slower
the simulation will run.
<PArray>.Interparticle_Collision_Bounce Float default: 100.0 --
animatable, percentage
The degree to which speed is recovered after a collision.
<PArray>.Interparticle_Collision_Bounce_Variation Float default: 0.0 --
animatable, percentage
The percentage of random variation of the Bounce value, applied to the particles.
920 Chapter 11 | 3ds max Objects

-- Object Motion Inheritance

<PArray>.motionInfluence Float default: 100.0 --
animatable, alias: Object_Motion_Inheritance
The percent of particles that inherit the motion of the object-based emitter at the moment
of particle formation.
<PArray>.motionMultiplier Float default: 1.0 --
animatable, alias: Object_Motion_Multiplier
Modifies the amount by which the emitter motion affects the particle motion. This can be
a positive or negative number.
<PArray>.motionVariation Float default: 0.0 --
animatable, percentage; alias: Object_Motion_Multiplier_Variation
Percentage of variation of the Multiplier value.
-- Bubble Motion
<PArray>.Bubble_Amplitude Float default: 0.0 --
animatable
The distance the particle moves off its usual velocity vector as it travels.
<PArray>.Bubble_Amplitude_Variation Float default: 0.0 --
animatable, percentage
The percent of Amplitude variation applied to each particle.
<PArray>.Bubble_Period Time default: 100000f --
animatable
The cycle time for one complete oscillation of a particle through the bubble “wave.” A
recommended value might be 20-30 intervals.
<PArray>.Bubble_Period_Variation Float default: 0.0 --
animatable, percentage
The percent of Period variation for each particle.
<PArray>.Bubble_Phase Float default: 0.0 --
animatable, angle
The initial displacement of the bubble pattern along the vector.
<PArray>.Bubble_Phase_Variation Float default: 0.0 --
animatable, percentage
The percent of Phase variation for each particle.
-- Particle Spawn
<PArray>.spawnType Integer default: 0
Determines what happens to particles at either collision or death:
None (Particles act as they normally would. That is, upon collision, they either bounce or
stick, depending on Particle Bounce settings in the deflector, and on death they disappear.)
Die After Collision (Particles disappear when they strike a deflector to which they’re
bound, such as the SDeflector.)
 PArray : GeometryClass 921

Spawn on Collision (Spawn effects take place upon collision with a bound deflector.)
Spawn on Death (Spawn effects take place at the end of each particle’s life.)
Spawn Trails (Particles are spawned from existing particles at each frame of that
particle’s life.)
<PArray>.Die__X_frames_after_collision Time default: 0f --
animatable
The life, in frames, that the particle will persist after the collision. Setting this to 0 (the
default) causes particles to vanish immediately after the collision.
<PArray>.Die__X_frames_after_collision_variation Float default: 0.0 --
animatable, percentage
Varies the Persist value of each particle, when Persist is greater than 0. This lets you
“feather” the dying off of the particle density.
<PArray>.Spawn_Generations Integer default: 1
The number of spawns beyond the original particle generation. For example, if this is set
to 1, and you’re spawning at death, one spawning will occur beyond the original lifespan
of each particle.
<PArray>.Spawn_Affects Integer default: 100
The percentage of particles that will spawn. Reducing this reduces the number of particles
that produce spawned particles.
<PArray>.Spawn_Multiplier Integer default: 1
Multiplies the number of particles spawned at each spawning event.
<PArray>.Spawn_Multiplier_Variation Float default: 0.0 --
percentage
Percentage range by which the Multiplier value will vary, frame by frame.
<PArray>.Spawn_Direction_Chaos Float default: 0.0 --
animatable, percentage
The amount by which the direction of the spawned particle can vary from the direction of
the parent particle. A setting of 0 means no variance. A setting of 100 causes the spawned
particle to travel in any random direction. A setting of 50 causes the spawned particle to
deviate from its parent’s path by up to 90 degrees.
<PArray>.Spawn_Speed_Chaos Float default: 0.0 --
animatable
Random percentage range of scaling of the spawned particles relative to their parents, and
dependent on the options below.
<PArray>.spawnSpeedType Integer default: 0
Sets the type of speed applied to spawn particles:
Slow (Applies the .spawn_Speed_Chaos value randomly to slow the speed of the
spawned particles.)
Fast (Randomly speeds up particles based on the .spawn_Speed_Chaos value.)
Both (Some particles speed up, while others slow down, based on the
.spawn_Speed_Chaos value.)
922 Chapter 11 | 3ds max Objects

<PArray>.spawnInheritVelocity Boolean default: false

When on, spawned particles inherit the speed of their parents, in addition to the effect of
the .spawn_Speed_Chaos value.
<PArray>.spawnSpeedFixed Boolean default: false
When on, uses the .spawn_Speed_Chaos value as a set value, rather than as a range
applied randomly to each particle.
<PArray>.Spawn_Scale_Chaos Float default: 0.0 --
animatable
The range of a percentage of change in the speed of the spawned particle relative to its
parent. A value of 0 means no change.
<PArray>.spawnScaleType Integer default: 0
The type of speed scaling for the spawned particles:
Slow (Applies the speed factor randomly to slow the speed of the spawned particles.)
Fast (Randomly speeds up particles based on the speed factor.)
Both (Some particles speed up, while others slow down, based on the speed factor.)
<PArray>.spawnScaleFixed Boolean default: false
When on, uses the .spawn_Scale_Chaos value as a set value, rather than as a range
applied randomly to each particle.
<PArray>.lifespanValueQueue Array default: #()
lifespanValueQueue is an array of integers which correspond to lifespan values for each
spawned generation of particles.
<PArray>.Spawn_Lifespan Integer default: 0
Value that sets initial lifespan of spawned particles.
<PArray>.objectMutationQueue Array default: #()
objectMutationQueue is an array of nodes which correspond to instanced-object
particle types. Each generation of spawning will use the next node as its object type.

See also
Particle System Common Properties, Operators, and Methods (p. 905)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 PCloud : GeometryClass 923

PCloud : GeometryClass
Constructor:
pcloud ...

Note: This class is not available in 3D Studio VIZ.

Properties:
-- Basic Parameters
<PCloud>.emitter Node default: undefined
The object which acts as an emitter.
<PCloud>.formation Integer default: 0
Set the emitter formation:
Box Emitter
Sphere Emitter
Cylinder Emitter
Object-based Emitter
<PCloud>.Emitter_Rad_Len Float default: 0.0 --
animatable
The radius of a spherical or cylindrical icon, and the length of a box icon.
<PCloud>.Emitter_Width Float default: 0.0 --
animatable
The width of a box emitter.
<PCloud>.Emitter_Height Float default: 0.0 --
animatable
The height of a box or cylindrical emitter.
<PCloud>.emitterHidden Boolean default: false
Hides the emitter in the viewport, when on.
Note: the emitter is never rendered.
<PCloud>.viewType Integer default: 0
Set the display icon for particles in the viewport:
Dots (Displays the particles as dots.)
Ticks (Displays the particles as crosses.)
Mesh (Displays the particles as mesh objects. This results in slower viewport redraws.)
Bbox (For instanced geometry only, this displays each instanced particle, whether a single
object, a hierarchy, or a group, as a bounding box.)
<PCloud>.viewPercent Float default: 10.0 --
percentage, alias: Percentage_Displayed
The percentage of particles displayed in the viewport.
924 Chapter 11 | 3ds max Objects

-- Particle Generation
<PCloud>.quantityMethod Integer default: 0
Set the method by which the number of particles is determined over time:
Use Rate (Specifies a fixed number of particles emitted per frame.)
Use Total (Specifies a total number of particles formed over the life of the system.)
Tip: Generally, Use Rate is best for a continuous flow of particles, like a trail of pixie dust,
while Use Total is better for bursts of particles over a short period of time.
<PCloud>.Birth_Rate Integer default: 10 --
animatable
The number of particles emitted per frame.
<PCloud>.Total_Number Integer default: 100
The total number of particles to be emitted.
<PCloud>.speed Float default: 0.0 --
animatable
The velocity of the particle at birth, along the normal, in units traveled per frame.
<PCloud>.Speed_Variation Float default: 0.0 --
animatable, percentage
Percentage of variation to the speed of emission for each particle.
<PCloud>.motionType Integer default: 0
Set the particle’s motionType
Random Direction (This option emits particles in random directions.)
Enter Vector (The direction of the particles is determined by a vector defined by the three
X, Y, and Z vectors.)
Reference Object (Emits particles in the direction of the local Z axis of a specified object.)
<PCloud>.Direction_Vector_X Float default: 1.0 --
animatable
The particle direction vectors for the X-axis.
<PCloud>.Direction_Vector_Y Float default: 0.0 --
animatable
The particle direction vectors for the Y-axis.
<PCloud>.Direction_Vector_Z Float default: 0.0 --
animatable
The particle direction vectors for the Z-axis.
<PCloud>.motionReferenceObject Node default: undefined
The object used as the reference object.
<PCloud>.directionVariation Float default: 0.0 --
animatable, percentage, alias: Speed_Direction_Variation
Percentage of variation to the direction when you choose either the Direction Vector or
Reference Object option.
<PCloud>.Emitter_Start Time default: 0f
The frame at which particles begin to exist in the scene.
 PCloud : GeometryClass 925

<PCloud>.Emitter_Stop Time default: 0f

The last frame at which particles are emitted.
<PCloud>.Display_Until Time default: 100f
Time at which all particles will disappear, regardless of other settings.
<PCloud>.life Time default: 101f --
animatable
The lifespan of each particle from the time of creation.
<PCloud>.Life_Variation Time default: 0f --
animatable
The number of frames by which the life of each particle can vary from the norm.
<PCloud>.size Float default: 1.0 --
animatable
The target size for all particles in the system.
<PCloud>.Size_Variation Float default: 0.0 --
animatable, percentage
The percentage by which the size of each particle may vary from the norm.
<PCloud>.Growth_Time Time default: 0f
The number of intervals over which the particle grows from being very small (0.1a system
constant) to the Size value.
<PCloud>.Fade_Time Time default: 0f
The number of intervals over which the particle will shrink to 1/10th its Size setting prior
to its death.
<PCloud>.seed Integer default: 0 --
alias: Random_Seed
By changing the Seed value, you achieve different results using otherwise identical particle
settings.
-- Particle Type
<PCloud>.particleType Integer default: 0
The type of particle emitted:
Standard Particle (Uses one of several standard particle types, such as triangle, cube, tetra,
and so on.)
MetaParticles (Uses Metaball particles. These are particle systems in which the individual
particles blend together in blobs or streams.)
Instanced Geometry (Generates particles that are instances of either an object, a linked
hierarchy of objects, or a group.)
<PCloud>.standardParticle Integer default: 0
Set the type of particle used when standard particles is selected:
Triangle (Renders each particle as a triangle. Use Triangle particles with noise opacity for
steam or smoke.)
Cube (Renders each particle as a cube.)
926 Chapter 11 | 3ds max Objects

Special (Each particle consists of three intersecting 2D squares. These are effective when
you use a face-map material, optionally along with an opacity map, to create the effect of a
three-dimensional particle.)
Facing (Renders each particle as a square that always faces the view. Use with an
appropriate opacity map for bubbles or snowflakes.)
Constant (Provides a particle that remains the same size, in pixels, specified by the size
value. This size never changes, regardless of its distance from the camera. Note that this
particle type can only be displayed in the viewports as a dot or a tick. If you turn on this
option while Mesh is selected, the viewport display is automatically switched to Ticks.)
Tetra (Renders each particle as a mapped tetrahedron, whose tail points toward the normal
vector of the emission, and whose head points away. Use Tetra particles for raindrops or
sparks.)
SixPoint (Renders each particle as a six-pointed, two-dimensional star.)
Sphere (Renders each particle as a sphere.)
<PCloud>.Metaparticle_Tension Float default: 1.0 --
animatable
Determines the tightness of the particles, with regard to their tendency to blend with
other particles. The higher the Tension, the harder the blobs, and the harder it is for them
to merge.
<PCloud>.Metaparticle_Tension_Variation Float default: 0.0 --
animatable, percentage
The percent of variation of the Tension effect.
<PCloud>.metaballRenderCoarsness Float default: 0.5 --
alias: Metaparticle_Coarseness
The coarseness for metaparticles in the rendered scene.
<PCloud>.metaballViewCoarsness Float default: 1.0
The coarseness for the viewport display.
<PCloud>.metaballAutoCoarsness Boolean default: true
When this is on, the rendering coarseness is automatically set, based on the size of the
particles, and the viewport coarseness is set to about twice that of the rendering
coarseness.
<PCloud>.instancingObject Node default: undefined
The object which is instanced.
<PCloud>.instanceSubTree Boolean default: false
Turn this on when you want to include the linked children of the picked object in the
particle. If the picked object is a group, all children of the group are included.
<PCloud>.instanceKeyOffsetType Integer default: 0
Set the animation offset keying:
None (Each particle duplicates the timing of the original object. As a result, the animation
of all particles will be identically timed.)
 PCloud : GeometryClass 927

Birth (The firstborn particle is an instance of the current animation of the source object at
the moment of that particle’s birth. Each subsequent particle then use the same start time
for the animation.)
Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each
particle is born using the same animation as the source object at the time of birth, but
with a random offset of frames, based on the .instanceFrameOffset value.)
<PCloud>.instanceFrameOffset Integer default: 0 --
alias: Animation_Offset_Amount
The property value is the UI value times the number of ticks per frame. The number of
ticks per frame is accessible via the ticksPerFrame system global variable.
<PCloud>.mappingType Integer default: 0
Specifies how a mapped material affects the particles:
Time (Maps particles over time.)
Distance (Maps particles over a distance.)
<PCloud>.Mapping_Time_Base Time default: 30f --
animatable
The number of frames from the birth of the particle that it takes to complete one mapping
of the particle.
<PCloud>.Mapping_Distance_Base Float default: 100.0 --
animatable
The distance, in units, from the birth of the particle that it takes to complete one mapping
of the particle.
<PCloud>.materialSource Integer default: 0
Updates the material carried by the particle system, using the source specified:
Icon (The particles use the material currently assigned to the particle system icon.)
Instanced Geometry (The particles use the material assigned to the instanced geometry.)
-- Rotation and Collision
<PCloud>.Spin_Time Time default: 0f --
animatable
The number of frames for one rotation of a particle. If set to 0, no rotation takes place.
<PCloud>.Spin_Time_Variation Float default: 0.0 --
animatable, percentage
The percent of variation of the Spin Time.
<PCloud>.Spin_Phase Float default: 0.0 --
animatable, angle
The initial particle rotation, in degrees.
<PCloud>.Spin_Phase_Variation Float default: 0.0 --
animatable, percentage
The percent of variation of the Phase.
<PCloud>.spinAxisType Integer default: 0
The spin axis for the particles:
928 Chapter 11 | 3ds max Objects

Random (The spin axis for each of the particles is random.)

Direction of Travel/Mblur (Rotates the particles about a vector formed by the direction in
which they’re moving.)
User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.)
<PCloud>.Blur_Stretch Integer default: 0 --
animatable
When greater than 0, the particles stretch along the travel axis, depending on their speed.
Specifically, the Stretch value specifies the percent of their length per each unit of the
Speed setting (in the Particle Motion group). Thus, if you set Stretch to 2 while Speed is set
at 10, the particles are stretched 20 percent longer than their original size along the axis of
their travel. This value is only available when you choose Direction of Travel/Mblur.
<PCloud>.X_Spin_Vector Float default: 1.0 --
animatable
Spin vector of the X-axis.
<PCloud>.Y_Spin_Vector Float default: 0.0 --
animatable
Spin vector of the Y-axis.
<PCloud>.Z_Spin_Vector Float default: 0.0 --
animatable
Spin vector of the Z-axis.
<PCloud>.Spin_Axis_Variation Float default: 0.0 --
animatable, angle
The amount, in degrees, by which the spin axis of each particle may vary from the
specified X Axis, Y Axis, and Z Axis settings.
<PCloud>.Interparticle_Collisions_On Integer default: 0
Turn on/off interparticle collisions:
Off
On
<PCloud>.Interparticle_Collision_Steps Integer default: 2
The number of intervals per rendering interval, during which an inter-particle collision
test is conducted. The higher the value, the more accurate the simulation, but the slower
the simulation will run.
<PCloud>.Interparticle_Collision_Bounce Float default: 100.0 --
animatable, percentage
The degree to which speed is recovered after a collision.
<PCloud>.Interparticle_Collision_Bounce_Variation Float default: 0.0 --
animatable, percentage
The percentage of random variation of the Bounce value, applied to the particles.
 PCloud : GeometryClass 929

-- Object Motion Inheritance

<PCloud>.motionInfluence Float default: 100.0 --
animatable, alias: Object_Motion_Inheritance
The percent of particles that inherit the motion of the object-based emitter at the moment
of particle formation.
<PCloud>.motionMultiplier Float default: 1.0 --
animatable, alias: Object_Motion_Multiplier
Modifies the amount by which the emitter motion affects the particle motion. This can be
a positive or negative number.
<PCloud>.motionVariation Float default: 0.0 --
animatable, percentage; alias: Object_Motion_Multiplier_Variation
Percentage of variation of the Multiplier value.
-- Bubble Motion
<PCloud>.Bubble_Amplitude Float default: 0.0 --
animatable
The distance the particle moves off its usual velocity vector as it travels.
<PCloud>.Bubble_Amplitude_Variation Float default: 0.0 --
animatable, percentage
The percent of Amplitude variation applied to each particle.
<PCloud>.Bubble_Period Time default: 100000f --
animatable
The cycle time for one complete oscillation of a particle through the bubble “wave.” A
recommended value might be 20-30 intervals.
<PCloud>.Bubble_Period_Variation Float default: 0.0 --
animatable, percentage
The percent of Period variation for each particle.
<PCloud>.Bubble_Phase Float default: 0.0 --
animatable, angle
The initial displacement of the bubble pattern along the vector.
<PCloud>.Bubble_Phase_Variation Float default: 0.0 --
animatable, percentage
The percent of Phase variation for each particle.
-- Particle Spawn
<PCloud>.spawnType Integer default: 0
Determines what happens to particles at either collision or death:
None (Particles act as they normally would. That is, upon collision, they either bounce or
stick, depending on Particle Bounce settings in the deflector, and on death they disappear.)
Die After Collision (Particles disappear when they strike a deflector to which they’re
bound, such as the SDeflector.)
930 Chapter 11 | 3ds max Objects

Spawn on Collision (Spawn effects take place upon collision with a bound deflector.)
Spawn on Death (Spawn effects take place at the end of each particle’s life.)
Spawn Trails (Particles are spawned from existing particles at each frame of that
particle’s life.)
<PCloud>.Die__X_frames_after_collision Time default: 0f --
animatable
The life, in frames, that the particle will persist after the collision. Setting this to 0 (the
default) causes particles to vanish immediately after the collision.
<PCloud>.Die__X_frames_after_collision_variation Float default: 0.0 --
animatable, percentage
Varies the Persist value of each particle, when Persist is greater than 0. This lets you
“feather” the dying off of the particle density.
<PCloud>.Spawn_Generations Integer default: 1
The number of spawns beyond the original particle generation. For example, if this is set
to 1, and you’re spawning at death, one spawning will occur beyond the original lifespan
of each particle.
<PCloud>.Spawn_Multiplier Integer default: 1
Multiplies the number of particles spawned at each spawning event.
<PCloud>.Spawn_Direction_Chaos Float default: 0.0 --
animatable, percentage
The amount by which the direction of the spawned particle can vary from the direction of
the parent particle. A setting of 0 means no variance. A setting of 100 causes the spawned
particle to travel in any random direction. A setting of 50 causes the spawned particle to
deviate from its parent’s path by up to 90 degrees.
<PCloud>.Spawn_Speed_Chaos Float default: 0.0 --
animatable
Random percentage range of scaling of the spawned particles relative to their parents, and
dependent on the options below.
<PCloud>.spawnSpeedType Integer default: 0
Sets the type of speed applied to spawn particles:
Slow (Applies the .spawn_Speed_Chaos value randomly to slow the speed of the
spawned particles.)
Fast (Randomly speeds up particles based on the .spawn_Speed_Chaos value.)
Both (Some particles speed up, while others slow down, based on the
.spawn_Speed_Chaos value.)
<PCloud>.spawnInheritVelocity Boolean default: false
When on, spawned particles inherit the speed of their parents, in addition to the effect of
the .spawn_Speed_Chaos value.
<PCloud>.spawnSpeedFixed Boolean default: false
When on, uses the .spawn_Speed_Chaos value as a set value, rather than as a range
applied randomly to each particle.
 Snow : GeometryClass 931

<PCloud>.Spawn_Scale_Chaos Float default: 0.0 --

animatable
The range of a percentage of change in the speed of the spawned particle relative to its
parent. A value of 0 means no change.
<PCloud>.spawnScaleType Integer default: 0
The type of speed scaling for the spawned particles:
Slow (Applies the speed factor randomly to slow the speed of the spawned particles.)
Fast (Randomly speeds up particles based on the speed factor.)
Both (Some particles speed up, while others slow down, based on the speed factor.)
<PCloud>.spawnScaleFixed Boolean default: false
When on, uses the .spawn_Scale_Chaos value as a set value, rather than as a range
applied randomly to each particle.
<PCloud>.lifespanValueQueue Array default: #()
lifespanValueQueue is an array of integers which correspond to lifespan values for each
spawned generation of particles.
<PCloud>.Spawn_Lifespan Integer default: 0
Value that sets initial lifespan of spawned particles.
<PCloud>.objectMutationQueue Array default: #()
objectMutationQueue is an array of nodes which correspond to instanced-object
particle types. Each generation of spawning will use the next node as its object type.

See also
Particle System Common Properties, Operators, and Methods (p. 905)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Snow : GeometryClass
Constructor:
snow ...
Note: This class is not available in 3D Studio VIZ.
Properties:
<Snow>.viewportcount Integer default: 100
Maximum number of particles displayed in viewports at any given frame.
<Snow>.rendercount Integer default: 100
Maximum number of particles that can appear in a single frame when you render it.
<Snow>.flakesize Float default: 2.0 -- animatable, alias: Flake_Size
Size of a particle in the active units.
932 Chapter 11 | 3ds max Objects

<Snow>.speed Float default: 10.0 -- animatable

Initial velocity of each particle as it leaves the emitter. Particles travel at this speed unless
they are affected by a particle system space warp.
<Snow>.variation Float default: 2.0 -- animatable
Varies the initial speed and direction of particles. The greater the Variation, the broader the
area of snowfall.
<Snow>.tumble Float default: 0.0 -- animatable
Amount of random rotation for snowflake particles. This parameter can range from 0 to 1.
At 0, flakes do not rotate; at 1, they rotate the most. The axis of rotation is generated
randomly for each particle.
<Snow>.tumblescale Float default: 1.0 -- animatable, alias:
Tumble_Rate
Speed at which snowflakes rotate. The greater the Tumble Rate, the faster the rotation.
<Snow>.display Integer default: 0
Set how particles are displayed in viewports:
Flakes (star-shaped snowflakes)
Dots
Ticks
<Snow>.render Integer default: 0
Set how particles are rendered:
Six Point (Each particle is rendered as a six-pointed star. Each side of the star is a face to
which you can assign a material.)
Triangle (Each particle is rendered as a triangle. Only one side of the triangle is a face to
which you can assign a material.)
Facing (Particles are rendered as square faces whose width and height equal Flake Size.
Facing particles are provided especially for use with material maps.)
<Snow>.start Time default: 0f -- alias: starttime
Number of the first frame where particles appear.
<Snow>.lifetime Time default: 30f -- alias: life
The lifetime of a particle, in number of frames.
<Snow>.birthrate Time default: 0f -- animatable, alias: Birth_Rate
The number of new particles born per frame. If this is less than or equal to the maximum
sustainable rate, the particle system generates an even flow of particles. If it is greater than
the maximum rate, the particle system generates particles in bursts.
<Snow>.constant Boolean default: true
When on, Birth Rate is unavailable and the birth rate used equals the maximum
sustainable rate. When off, Birth Rate is available. Turning Constant off does not mean
that the birth rate varies automatically; the birth rate remains constant unless you animate
the Birth Rate parameter.
<Snow>.emitterwidth Float default: 25.0 -- animatable, alias: width
The width of the emitter.
 Spray : GeometryClass 933

<Snow>.emitterheight Float default: 25.0 -- animatable, alias: length

The height of the emitter.
<Snow>.hideemitter Boolean default: false
When on, the emitter is hidden in the viewports.
Note: The emitter is never rendered.

See also
Particle System Common Properties, Operators, and Methods (p. 905)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Spray : GeometryClass
Constructor:
spray …
Note: This class is not available in 3D Studio VIZ.
Properties:
<Spray>.viewportcount Integer default: 100
Maximum number of particles displayed in viewports at any given frame.
<Spray>.rendercount Integer default: 100
Maximum number of particles that can appear in a single frame when you render it.
<Spray>.dropsize Float default: 2.0 -- animatable, alias: Drop_Size
Size of a particle in the active units.
<Spray>.speed Float default: 10.0 -- animatable
Initial velocity of each particle as it leaves the emitter. Particles travel at this speed unless
they are affected by a particle system space warp.
<Spray>.variation Float default: 2.0 -- animatable
Varies the initial speed and direction of particles. The greater the Variation, the broader the
area of snowfall.
<Spray>.display Integer default: 0
Set how particles are displayed in viewports:
Drops (streaks)
Dots
Ticks
934 Chapter 11 | 3ds max Objects

<Spray>.render Integer default: 0

Set how particles are rendered:
Tetrahedron (Particles are rendered as long tetrahedrons, with the length you specify in
the Drop Size parameter. Tetrahedron is the default setting for rendering. It provides a
basic simulation of water drops.)
Facing (Particles are rendered as square faces whose width and height equal Drop Size.
Facing particles are provided especially for use with material maps.)
<Spray>.start Time default: 0f -- alias: starttime
Number of the first frame where particles appear.
<Spray>.lifetime Time default: 30f -- animatable, alias: life
The lifetime of a particle, in number of frames.
<Spray>.birthrate Time default: 0f -- animatable, alias:
Birth_Rate
The number of new particles born per frame. If this is less than or equal to the maximum
sustainable rate, the particle system generates an even flow of particles. If it is greater than
the maximum rate, the particle system generates particles in bursts.
<Spray>.constant Boolean default: true
When on, Birth Rate is unavailable and the birth rate used equals the maximum
sustainable rate. When off, Birth Rate is available. Turning Constant off does not mean
that the birth rate varies automatically; the birth rate remains constant unless you animate
the Birth Rate parameter.
<Spray>.emitterheight Float default: 25.0 -- animatable, alias: length
The height of the emitter.
<Spray>.emitterwidth Float default: 25.0 -- animatable, alias: width
The width of the emitter.
<Spray>.hideemitter Boolean default: false
When on, the emitter is hidden in the viewports.
Note: The emitter is never rendered.

See also
Particle System Common Properties, Operators, and Methods (p. 905)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 SuperSpray : GeometryClass 935

SuperSpray : GeometryClass
Constructor:
superSpray ...

Note: This class is not available in 3D Studio VIZ.

Properties:
-- Basic Parameters
<SuperSpray>.Off_Axis Float default: 0.0 --
animatable, angle
Affects the angle of the particle stream off the Z axis (along the plane of the X axis).
<SuperSpray>.Axis_Spread Float default: 0.0 --
animatable, angle
Affects the spread of the particles away from the emission vector (along the plane of the X
axis).
<SuperSpray>.Off_Plane Float default: 0.0 --
animatable, angle
Affects the angle of emission about the Z axis. This has no effect if Off_Axis is set to 0.
<SuperSpray>.Plane_Spread Float default: 0.0 --
animatable, angle
Affects the spread of the particles about the Off_Plane axis. This has no effect if
Off_Axis is set to 0.
<SuperSpray>.iconsize Float default: 20.0 --
alias: Emitter_Width
Size of the emitter icon.
<SuperSpray>.iconHidden Boolean default: false
When on, hides the emitter in viewports. When off, the emitter is displayed in viewports.
The emitter is never rendered.
<SuperSpray>.viewType Integer default: 0
Set the display icon for particles in the viewport:
Dots (Displays the particles as dots.)
Ticks (Displays the particles as crosses.)
Mesh (Displays the particles as mesh objects. This results in slower viewport redraws.)
Bbox (For instanced geometry only, this displays each instanced particle, whether a single
object, a hierarchy, or a group, as a bounding box.)
<SuperSpray>.viewPercent Float default: 10.0 --
percentage, alias: Percentage_Displayed
The percentage of particles displayed in the viewport.
936 Chapter 11 | 3ds max Objects

-- Particle Generation
<SuperSpray>.quantityMethod Integer default: 0
Set the method by which the number of particles is determined over time:
Use Rate (Specifies a fixed number of particles emitted per frame.)
Use Total (Specifies a total number of particles formed over the life of the system.)
Tip: Generally, Use Rate is best for a continuous flow of particles, like a trail of pixie dust,
while Use Total is better for bursts of particles over a short period of time.
<SuperSpray>.Birth_Rate Integer default: 10 --
animatable
The number of particles emitted per frame.
<SuperSpray>.Total_Number Integer default: 100
The total number of particles to be emitted.
<SuperSpray>.speed Float default: 10.0 --
animatable
The velocity of the particle at birth, along the normal, in units traveled per frame.
<SuperSpray>.Speed_Variation Float default: 0.0 --
animatable, percentage
Percentage of variation to the speed of emission for each particle.
<SuperSpray>.Emitter_Start Time default: 0f
The frame at which particles begin to exist in the scene.
<SuperSpray>.Emitter_Stop Time default: 30f
The last frame at which particles are emitted.
<SuperSpray>.Display_Until Time default: 100f
Time at which all particles will disappear, regardless of other settings.
<SuperSpray>.life Time default: 30f --
animatable
The lifespan of each particle from the time of creation.
<SuperSpray>.Life_Variation Time default: 0f --
animatable
The number of frames by which the life of each particle can vary from the norm.
<SuperSpray>.subsampleCreationTime Boolean default: false
When on, enables the addition of a time offset to the equations of motion that prevents
puffing in time.
<SuperSpray>.subsampleEmitterTranslation Boolean default: true
If the object-based emitter is moving in space, particles are created at integral times at
positions along the geometry’s path between renderable positions. This prevents puffing
in space.
<SuperSpray>.subsampleEmitterRotation Boolean default: true
If the emitter is rotating, turn this on to avoid puffing and produce smooth spiral effects.
<SuperSpray>.size Float default: 1.0 --
animatable
The target size for all particles in the system.
 SuperSpray : GeometryClass 937

<SuperSpray>.Size_Variation Float default: 0.0 --

animatable, percentage
The percentage by which the size of each particle may vary from the norm.
<SuperSpray>.Growth_Time Time default: 10f
The number of intervals over which the particle grows from being very small (0.1a system
constant) to the Size value.
<SuperSpray>.Fade_Time Time default: 10f
The number of intervals over which the particle will shrink to 1/10th its Size setting prior
to its death.
<SuperSpray>.seed Integer default: 0 --
alias: Random_Seed
By changing the Seed value, you achieve different results using otherwise identical particle
settings.
-- Particle Type
<SuperSpray>.particleType Integer default: 0
The type of particle emitted:
Standard Particle (Uses one of several standard particle types, such as triangle, cube, tetra,
and so on.)
MetaParticles (Uses Metaball particles. These are particle systems in which the individual
particles blend together in blobs or streams.)
Instanced Geometry (Generates particles that are instances of either an object, a linked
hierarchy of objects, or a group.)
<SuperSpray>.standardParticle Integer default: 0
Set the type of particle used when standard particles is selected:
Triangle (Renders each particle as a triangle. Use Triangle particles with noise opacity for
steam or smoke.)
Cube (Renders each particle as a cube.)
Special (Each particle consists of three intersecting 2D squares. These are effective when
you use a face-map material, optionally along with an opacity map, to create the effect of a
three-dimensional particle.)
Facing (Renders each particle as a square that always faces the view. Use with an
appropriate opacity map for bubbles or snowflakes.)
Constant (Provides a particle that remains the same size, in pixels, specified by the size
value. This size never changes, regardless of its distance from the camera. Note that this
particle type can only be displayed in the viewports as a dot or a tick. If you turn on this
option while Mesh is selected, the viewport display is automatically switched to Ticks.)
938 Chapter 11 | 3ds max Objects

Tetra (Renders each particle as a mapped tetrahedron, whose tail points toward the normal
vector of the emission, and whose head points away. Use Tetra particles for raindrops or
sparks.)
SixPoint (Renders each particle as a six-pointed, two-dimensional star.)
Sphere (Renders each particle as a sphere.)
<SuperSpray>.Metaparticle_Tension Float default: 1.0 --
animatable
Determines the tightness of the particles, with regard to their tendency to blend with
other particles. The higher the Tension, the harder the blobs, and the harder it is for them
to merge.
<SuperSpray>.Metaparticle_Tension_Variation Float default: 0.0 --
animatable, percentage
The percent of variation of the Tension effect.
<SuperSpray>.metaballRenderCoarsness Float default: 0.5 --
alias: Metaparticle_Coarseness
The coarseness for metaparticles in the rendered scene.
<SuperSpray>.metaballViewCoarsness Float default: 1.0
The coarseness for the viewport display.
<SuperSpray>.metaballAutoCoarsness Boolean default: true
When this is on, the rendering coarseness is automatically set, based on the size of the
particles, and the viewport coarseness is set to about twice that of the rendering
coarseness.
<SuperSpray>.instancingObject Node default: undefined
The object which is instanced.
<SuperSpray>.instanceSubTree Boolean default: false
Turn this on when you want to include the linked children of the picked object in the
particle. If the picked object is a group, all children of the group are included.
<SuperSpray>.instanceKeyOffsetType Integer default: 0
Set the animation offset keying:
None (Each particle duplicates the timing of the original object. As a result, the animation
of all particles will be identically timed.)
Birth (The firstborn particle is an instance of the current animation of the source object at
the moment of that particle’s birth. Each subsequent particle then use the same start time
for the animation.)
Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each
particle is born using the same animation as the source object at the time of birth, but
with a random offset of frames, based on the .instanceFrameOffset value.)
<SuperSpray>.instanceFrameOffset Integer default: 0 --
alias: Animation_Offset_Amount
The property value is the UI value times the number of ticks per frame. The number of
ticks per frame is accessible via the ticksPerFrame system global variable.
 SuperSpray : GeometryClass 939

<SuperSpray>.mappingType Integer default: 0

Specifies how a mapped material affects the particles:
Time (Maps particles over time.)
Distance (Maps particles over a distance.)
<SuperSpray>.Mapping_Time_Base Time default: 30f --
animatable
The number of frames from the birth of the particle that it takes to complete one mapping
of the particle.
<SuperSpray>.Mapping_Distance_Base Float default: 100.0 --
animatable
The distance, in units, from the birth of the particle that it takes to complete one mapping
of the particle.
-- Rotation and Collision
<SuperSpray>.Spin_Time Time default: 30f --
animatable
The number of frames for one rotation of a particle. If set to 0, no rotation takes place.
<SuperSpray>.Spin_Time_Variation Float default: 0.0 --
animatable, percentage
The percent of variation of the Spin Time.
<SuperSpray>.Spin_Phase Float default: 0.0 --
animatable, angle
The initial particle rotation, in degrees.
<SuperSpray>.Spin_Phase_Variation Float default: 0.0 --
animatable, percentage
The percent of variation of the Phase.
<SuperSpray>.spinAxisType Integer default: 0
The spin axis for the particles:
Random (The spin axis for each of the particles is random.)
Direction of Travel/Mblur (Rotates the particles about a vector formed by the direction in
which they’re moving.)
User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.)
<SuperSpray>.Blur_Stretch Integer default: 0 --
animatable
When greater than 0, the particles stretch along the travel axis, depending on their speed.
Specifically, the Stretch value specifies the percent of their length per each unit of the
Speed setting (in the Particle Motion group). Thus, if you set Stretch to 2 while Speed is set
at 10, the particles are stretched 20 percent longer than their original size along the axis of
their travel. This value is only available when you choose Direction of Travel/Mblur.
<SuperSpray>.X_Spin_Vector Float default: 1.0 --
animatable
Spin vector of the X-axis.
940 Chapter 11 | 3ds max Objects

<SuperSpray>.Y_Spin_Vector Float default: 0.0 --

animatable
Spin vector of the Y-axis.
<SuperSpray>.Z_Spin_Vector Float default: 0.0 --
animatable
Spin vector of the Z-axis.
<SuperSpray>.Spin_Axis_Variation Float default: 0.0 --
animatable, angle
The amount, in degrees, by which the spin axis of each particle may vary from the
specified X Axis, Y Axis, and Z Axis settings.
<SuperSpray>.Interparticle_Collisions_On Integer default: 0
Turn on/off interparticle collisions:
OFF
ON
<SuperSpray>.Interparticle_Collision_Steps Integer default: 2
The number of intervals per rendering interval, during which an inter-particle collision
test is conducted. The higher the value, the more accurate the simulation, but the slower
the simulation will run.
<SuperSpray>.Interparticle_Collision_Bounce Float default: 100.0 --
animatable, percentage
The degree to which speed is recovered after a collision.
<SuperSpray>.Interparticle_Collision_Bounce_Variation Float default: 0.0 --
animatable, percentage
The percentage of random variation of the Bounce value, applied to the particles.
-- Object Motion Inheritance
<SuperSpray>.motionInfluence Float default: 100.0 --
animatable, alias: Object_Motion_Inheritance
The percent of particles that inherit the motion of the object-based emitter at the moment
of particle formation.
<SuperSpray>.motionMultiplier Float default: 1.0 --
animatable, alias: Object_Motion_Multiplier
Modifies the amount by which the emitter motion affects the particle motion. This can be
a positive or negative number.
<SuperSpray>.motionVariation Float default: 0.0 --
animatable, percentage; alias: Object_Motion_Multiplier_Variation
Percentage of variation of the Multiplier value.
-- Bubble Motion
<SuperSpray>.Bubble_Amplitude Float default: 0.0 --
animatable
The distance the particle moves off its usual velocity vector as it travels.
<SuperSpray>.Bubble_Amplitude_Variation Float default: 0.0 --
animatable, percentage
The percent of Amplitude variation applied to each particle.
 SuperSpray : GeometryClass 941

<SuperSpray>.Bubble_Period Time default: 100000f -

- animatable
The cycle time for one complete oscillation of a particle through the bubble “wave.” A
recommended value might be 20-30 intervals.
<SuperSpray>.Bubble_Period_Variation Float default: 0.0 --
animatable, percentage
The percent of Period variation for each particle.
<SuperSpray>.Bubble_Phase Float default: 0.0 --
animatable, angle
The initial displacement of the bubble pattern along the vector.
<SuperSpray>.Bubble_Phase_Variation Float default: 0.0 --
animatable, percentage
The percent of Phase variation for each particle.
-- Particle Spawn
<SuperSpray>.spawnType Integer default: 0
Determines what happens to particles at either collision or death:
None (Particles act as they normally would. That is, upon collision, they either bounce or
stick, depending on Particle Bounce settings in the deflector, and on death they disappear.)
Die After Collision (Particles disappear when they strike a deflector to which they’re
bound, such as the SDeflector.)
Spawn on Collision (Spawn effects take place upon collision with a bound deflector.)
Spawn on Death (Spawn effects take place at the end of each particle’s life.)
Spawn Trails (Particles are spawned from existing particles at each frame of that
particle’s life.)
<SuperSpray>.Die__X_frames_after_collision Time default: 0f --
animatable
The life, in frames, that the particle will persist after the collision. Setting this to 0 (the
default) causes particles to vanish immediately after the collision.
<SuperSpray>.Die__X_frames_after_collision_variation Float default: 0.0 --
animatable, percentage
Varies the Persist value of each particle, when Persist is greater than 0. This lets you
“feather” the dying off of the particle density.
<SuperSpray>.Spawn_Affects Integer default: 100
The percentage of particles that will spawn. Reducing this reduces the number of particles
that produce spawned particles.
<SuperSpray>.Spawn_Multiplier_Variation Float default: 0.0 --
percentage
Percentage range by which the Multiplier value will vary, frame by frame.
942 Chapter 11 | 3ds max Objects

<SuperSpray>.Spawn_Direction_Chaos Float default: 0.0 --

animatable, percentage
The amount by which the direction of the spawned particle can vary from the direction of
the parent particle. A setting of 0 means no variance. A setting of 100 causes the spawned
particle to travel in any random direction. A setting of 50 causes the spawned particle to
deviate from its parent’s path by up to 90 degrees.
<SuperSpray>.Spawn_Speed_Chaos Float default: 0.0 --
animatable
Random percentage range of scaling of the spawned particles relative to their parents, and
dependent on the options below.
<SuperSpray>.spawnSpeedType Integer default: 0
Sets the type of speed applied to spawn particles:
Slow (Applies the .spawn_Speed_Chaos value randomly to slow the speed of the
spawned particles.)
Fast (Randomly speeds up particles based on the .spawn_Speed_Chaos value.)
Both (Some particles speed up, while others slow down, based on the
.spawn_Speed_Chaos value.)
<SuperSpray>.spawnInheritVelocity Boolean default: false
When on, spawned particles inherit the speed of their parents, in addition to the effect of
the .spawn_Speed_Chaos value.
<SuperSpray>.spawnSpeedFixed Boolean default: false
When on, uses the .spawn_Speed_Chaos value as a set value, rather than as a range
applied randomly to each particle.
<SuperSpray>.Spawn_Scale_Chaos Float default: 0.0 --
animatable
The range of a percentage of change in the speed of the spawned particle relative to its
parent. A value of 0 means no change.
<SuperSpray>.spawnScaleType Integer default: 0
The type of speed scaling for the spawned particles:
Slow (Applies the speed factor randomly to slow the speed of the spawned particles.)
Fast (Randomly speeds up particles based on the speed factor.)
Both (Some particles speed up, while others slow down, based on the speed factor.)
<SuperSpray>.spawnScaleFixed Boolean default: false
When on, uses the .spawn_Scale_Chaos value as a set value, rather than as a range
applied randomly to each particle.
<SuperSpray>.lifespanValueQueue Array default: #()
lifespanValueQueue is an array of integers which correspond to lifespan values for each
spawned generation of particles.
<SuperSpray>.objectMutationQueue Array default: #()
objectMutationQueue is an array of nodes which correspond to instanced-object
particle types. Each generation of spawning will use the next node as its object type.
 NURBSSurf : GeometryClass 943

See also
Particle System Common Properties, Operators, and Methods (p. 905)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Geometry - NURBS Objects

The following list displays the NURBS objects:
NURBSSurf (p. 943)
Point_Surf (p. 943)

NURBSSurf : GeometryClass
NURBSSurfs are NURBS surface objects defined by CVs (control vertices). All NURBS objects are
created through the special NURBS descriptor classes (see Working with NURBS (p. 1384)) and the
NURBSSurf class is used typically in object class testing with the classOf() function. Scene objects
created as NURBSSurf objects in the 3ds max user interface have the class NURBSSurf.
Constructor:
NURBSNode <nurbs_set> ...
See Creating New NURBS Objects (p. 1389) for details.
Properties:
Properties for NURBSSurf objects are accessed through a NURBSSet descriptor object. See
Working with NURBS (p. 1384) for more details.

See also
NURBS Node Properties and Methods (p. 1397)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Point_Surf : GeometryClass
Point_Surfs are NURBS surface objects defined by interpolated points. All NURBS objects are created
through the special NURBS descriptor classes (see Working with NURBS (p. 1384)) and the Point_Surf
class is used typically in object class testing with the classOf() function. Scene objects created as
Point Surface objects in the 3ds max user interface have the class Point_Surf.
Constructor:
NURBSNode <nurbs_set> ...
See Creating New NURBS Objects (p. 1389) for details.
944 Chapter 11 | 3ds max Objects

Properties:
<Point_Surf>.thickness Float default: 1.0 -- animatable
Rendered thickness of the surface.
<Point_Surf>.sides Integer default: 12 -- animatable
Rendered sides of the surface.
<Point_Surf>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
Other properties for Point Surfaces are accessed through a NURBSSet descriptor object. See
Working with NURBS (p. 1384) for more details.

See also
NURBS Node Properties and Methods (p. 1397)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Shape : Node
The following list shows the 3ds max shape class objects:
--Splines
Arc (p. 949)
Circle (p. 950)
Donut (p. 951)
Ellipse (p. 953)
Helix (p. 954)
Line (p. 955)
NGon (p. 957)
Rectangle (p. 958)
Section (p. 959)
Star (p. 960)
Text (p. 962)
--NURBS Curves
CV_Curve (p. 964)
Point_Curve (p. 965)
 Shape Common Properties, Operators, and Methods 945

Shape Common Properties, Operators, and Methods

General Methods:
numKnots <shape> [ <spline_index_integer> ]
Returns the number of knots (also known vertices or control points) in the indexed spline
as an integer. If the spline index is not specified, returns the number of knots in the entire
shape.
for example:
y = donut()
numKnots y

Interpolation Methods
There are a number of interpolation functions that operate on shape scene objects. They provide
capabilities such as stepping along a curve within a shape getting coordinates on the curve, getting
curve lengths or determining the closest point on a curve to a given coordinate. These are useful for
placing cloned objects along a curve or keeping a set of objects in formation near a ‘spine’ curve as
it animates, etc.
The interpolators all take a shape scene object (for example, a line), an optional curve number in
case there are several curves in the shape, defaulting to 1, and a parameter in the range 0.0 to 1.0,
that specifies a spot on the curve as a proportion along its length. There are two types of interpolator
provided:
• One interpolator matches the 3ds max Path controller in which the percentage along the path
is not uniform, but weighted by the vertex spacing. This simple interpolation is interpolating
based on parameter space. If a spline has 4 segments, the first segment is parameter values 0-
0.25, the second 0.25-0.5, the third 0.5-0.75 and the fourth 0.75-1.0. This is regardless of the
length of each segment.
• Another interpolator that gives you a uniform interpolation along the length of the curve. This
interpolation normalizes the parameter space to distance along the length of a spline. So
parameter space 0 is the start, 1.0 is the end and 0.5 is halfway along the actual length of the
curve.
The non-uniform Path interpolator in 3ds max gives rise to the varying velocity of a path-animated
object when the path has unevenly spaced control points. The arc-length interpolators provided
here give a uniform placing along the curve no matter how uneven the control point placement.
The advantage of the Path interpolator is that it is computationally much more efficient than a
uniform arc-length interpolator. The length interpolator uses some caches to speed it up, but you
have to help manage them in the way described below.
The optional steps: keyword argument for the methods listed below lets you specify the integration
steps. The default steps value is 5 times the curve’s 3ds max unit length, which usually is more than
enough. For example, if a curve has a length of 100 3ds max units, the default step size would be
500. The interpolation algorithm has an accuracy of no better than + or - (1/steps) 3ds max units.
These methods employ a cache to speed up their operation in the common case where you step
946 Chapter 11 | 3ds max Objects

gradually along a single curve. The cache remembers the state for the last point on the curve and
picks up there if you call again on the same curve at the same animation time. This can
exponentially speed up interpolation processing. However, MAXScript does not have a way of
knowing if you’ve edited the curve from one call to the next, so you have to be sure to reset the cache
with the resetLengthInterp() method if the user can edit the curve between calls in your code.
All coordinates are in the current coordinate system.
pathInterp <shape> [ <curve_num> ] <parameter>
Return a point3 coordinate on the numbered curve (defaults to 1) corresponding to the
parameter value (0.0 to 1.0) that matches the 3ds max Path controller percentage (vertex-
based) interpolation.
lengthInterp <shape> [ <curve_num> ] <parameter> [ steps:<integer> ]
Return a point3 coordinate on the numbered curve (defaults to 1) corresponding to the
parameter value (0.0 to 1.0) that is that fraction along the curve’s total length.
resetLengthInterp()
Clear length interpolation cache. Use this if the curve you are length-interpolating along
might have been edited between calls.
curveLength <shape> [ <curve_num> ]
Return the arc length of the numbered curve. This length does not reflect any transform
level scaling performed on the shape.
pathTangent <shape> [ <curve_num> ] <parameter>
Return the tangent direction vector at the 3ds max Path (vertex-based) interpolated point
along the specified curve. You can use this function, for example, to set an object’s
direction to follow the curve.
lengthTangent <shape> [ <curve_num> ] <parameter> [ steps:<integer> ]
Return the tangent direction vector at the arc-length-interpolated point along the
specified curve. You can use this function to set an object’s direction to follow the curve.
nearestPathParam <shape> [ <curve_num> ] <point3> [ steps:<integer> ]
Return the interpolation parameter value (0.0 to 1.0) corresponding to the point along the
curve that is closest to the given <point3> coordinate. The parameter is given as a
3ds max Path (vertex-based) interpolation parameter value. You can then use pathInterp
with this value to find the nearest point’s coordinates, or use one of the following
functions for converting between arc-length parameters and 3ds max Path percentage
parameters.
pathToLengthParam <shape> [ <curve_num> ] <parameter> [ steps:<integer> ]
Return the uniform arc-length length parameter corresponding to the given 3ds max Path
(vertex-based) parameter for this curve.
lengthToPathParam <shape> [ <curve_num> ] <parameter> [ steps:<integer> ]
Return the 3ds max Path (vertex-based) parameter corresponding to the given uniform arc-
length parameter for this curve.
 Spline Shape Common Properties, Operators, and Methods 947

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Shapes - Splines
The following list shows the 3ds max spline shape class objects:
Arc (p. 949)
Circle (p. 950)
Donut (p. 951)
Ellipse (p. 953)
Helix (p. 954)
Line (p. 955)
NGon (p. 957)
Rectangle (p. 958)
Section (p. 959)
Star (p. 960)

Spline Shape Common Properties, Operators, and Methods

The following properties methods apply to all spline shape objects.
Properties:
<spline>.renderable Boolean default: false
When on, the shape is rendered using a 12-sided circle as a cross section.
<spline>.thickness Float default: 1.0
The diameter of the rendered spline.
<spline>.mapCoords Boolean default: false
When on, applies mapping coordinates. The U coordinate is wrapped once around the
thickness of the spline, while the V coordinate is mapped once along the length of the
spline. Tiling is achieved via the tiling parameters of the material.
Note:
Since renderable is a property for all nodes, a name conflict exists between the renderable
property for nodes and the renderable property for splines. MAXScript handles the conflict for this
property differently than for all other cases where an object class property name conflicts with a
node level property name. Normally, you would access the node level property as a property of the
node, and the object property as a property of the baseobject property of the node. The
renderable property however is always applied to the spline object’s renderable property rather
than the node’s renderable property.
948 Chapter 11 | 3ds max Objects

So, looking in the Object Properties dialog, $.renderable=false turns off renderable at the node level.
To turn off the spline’s renderable property, you need to say $.baseobject.renderable=false.
Methods:
The following methods are defined for 3D Studio VIZ.
applyOffset <spline_shape_node> <offset_float>
For each spline in the shape, makes a copy of the spline, offset on all sides to the distance
in units specified by offset_float. If a spline is open, the resulting spline and its outline
will make a single closed spline. Negative offset_float values create an offset spline to
the left of the spline (as the spline is drawn from its start to its finish). The
spline_shape_node is converted to a SplineShape (Editable Spline) if it is not already a
SplineShape.
measureOffset <spline_shape_node> <point3>
Returns a Float value whose absolute value is the distance from point3 to the closest
point on a spline in the shape. The sign of the value is positive if the point3 position is to
the left of the spline (as the spline is drawn from its start to its finish). The value returned
by this method can usually be used as the offset_float parameter in applyOffset()
to have an offset spline pass through the point3 position. If the closest point on a spline
in the shape is an endpoint of an open spline, the offset spline will not pass through the
point3 position.
trimextend <fixed_node_array> <alterable_node_array> \
[trim: <boolean> ] [extend: <boolean>] [infinite: <boolean>] \
[project: #view | #3D | #grid]
If trim is true (the default), …otherwise …If extend is true (the default), …otherwise …If
infinite is false (the default), … , otherwise …Project can be one of the following Name
values:
#view (the default) –
#3D –
#grid -
Broken. Document when working.

See also
Shape Common Properties, Operators, and Methods (p. 945)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Arc : Shape 949

Arc : Shape
Constructor:
arc ...

Properties:
<Arc>.radius Float default: 25.0 -- animatable
The arc radius.
<Arc>.from Float default: 45.0 -- animatable
Location of the start point as an angle measured from the local positive X axis.
<Arc>.to Float default: 135.0 -- animatable
Location of the end point as an angle measured from the local positive X axis.
<Arc>.pie Boolean default: false
When on, creates a closed spline in the form of a pie. The start point and end point are
connected to the center with straight segments.
<Arc>.reverseBooleandefault: false
When on, the direction of the arc spline is reversed, and the first vertex is placed at the
opposite end of an open arc. As long as the shape remains an original shape (and not an
editable spline), you can switch its direction by toggling reverse. Once the arc is
converted to an editable spline, you can use Reverse at the Spline sub-object level to
reverse direction.
<Arc>.steps Integer default: 6
Number of divisions between each vertex.
<Arc>.optimize Boolean default: true
When on, removes unneeded steps from straight segments in the spline.
<Arc>.adaptive Boolean default: false
When on, sets the number of steps for each spline to produce a smooth curve. Straight
segments always receive 0 steps.
<Arc>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
<Arc>.thickness Float default: 1.0 -- animatable
Diameter of the rendered spline.
<Arc>.sides Float default: 12.0 -- animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<Arc>.viewport_thickness Float default: 1.0
Diameter of the viewport spline.
<Arc>.viewport_sides Integer default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a
square cross section, for example.
<Arc>.viewport_angle Float default: 0.0
The rotational position of the cross-section in the viewports.
950 Chapter 11 | 3ds max Objects

<Arc>.DisplayRenderMesh Boolean default: false

When on, displays the mesh generated by the spline in the viewports.
<Arc>.UseViewportSettings Boolean default: false
When on, displays the mesh generated by the Viewport settings.
<Arc>.DisplayRenderSettings Boolean default: true
When on, displays the mesh generated by the render settings.
<Arc>.renderableBoolean default: true
When on, the spline is displayed in the rendered scene.
<Arc>.mapCoordsBoolean default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the
thickness of the spline; the V coordinate is mapped once along the length of the spline.
Note:
The Reverse property is not accessible to MAXScript in 3ds max 4.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947)
Shape Common Properties, Operators, and Methods (p. 945)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Circle : Shape
Constructor:
circle ...

Properties:
<Circle>.radius Float default: 25.0 -- animatable
The radius of the circle.
<Circle>.steps Integer default: 6
The number of divisions between each vertex.
<Circle>.optimize Boolean default: true
When on, removes unneeded steps from straight segments in the spline.
<Circle>.adaptive Boolean default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve.
Straight segments always receive 0 steps.
<Circle>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
<Circle>.thickness Float default: 1.0 -- animatable
Diameter of the rendered spline.
 Donut : Shape 951

<Circle>.sides Float default: 12.0 -- animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<Circle>.viewport_thickness Float default: 1.0
Diameter of the viewport spline.
<Circle>.viewport_sides Integer default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a
square cross section, for example.
<Circle>.viewport_angle Float default: 0.0
The rotational position of the cross-section in the viewports.
<Circle>.DisplayRenderMesh Booleandefault: false
When on, displays the mesh generated by the spline in the viewports.
<Circle>.UseViewportSettings Boolean default: false
When on, displays the mesh generated by the Viewport settings.
<Circle>.DisplayRenderSettings Boolean default: true
When on, displays the mesh generated by the render settings.
<Circle>.renderableBoolean default: true
When on, the spline is displayed in the rendered scene.
<Circle>.mapCoordsBoolean default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the
thickness of the spline; the V coordinate is mapped once along the length of the spline.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947)
Shape Common Properties, Operators, and Methods (p. 945)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Donut : Shape
Constructor:
donut ...

Properties:
<Donut>.radius1 Float default: 35.0 -- animatable
Sets the radius of the first circle.
<Donut>.radius2 Float default: 25.0 -- animatable
Sets the radius of the second circle.
<Donut>.steps Integer default: 6
The number of divisions between each vertex.
952 Chapter 11 | 3ds max Objects

<Donut>.optimize Boolean default: true

When on, removes unneeded steps from straight segments in the spline
<Donut>.adaptive Boolean default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve.
Straight segments always receive 0 steps.
<Donut>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
<Donut>.thickness Float default: 1.0 -- animatable
Diameter of the rendered spline.
<Donut>.sides Float default: 12.0 -- animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<Donut>.viewport_thickness Float default: 1.0
Diameter of the viewport spline.
<Donut>.viewport_sides Integer default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a
square cross section, for example.
<Donut>.viewport_angle Float default: 0.0
The rotational position of the cross-section in the viewports.
<Donut>.DisplayRenderMesh Boolean default: false
When on, displays the mesh generated by the spline in the viewports.
<Donut>.UseViewportSettings Boolean default: false
When on, displays the mesh generated by the Viewport settings.
<Donut>.DisplayRenderSettings Boolean default: true
When on, displays the mesh generated by the render settings.
<Donut>.renderable Boolean default: true
When on, the spline is displayed in the rendered scene.
<Donut>.mapCoords Boolean default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the
thickness of the spline; the V coordinate is mapped once along the length of the spline.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947)
Shape Common Properties, Operators, and Methods (p. 945)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Ellipse : Shape 953

Ellipse : Shape
Constructor:
ellipse ...

Properties:
<Ellipse>.length Float default: 25.0 -- animatable
The size of the Ellipse along the local Y axis.
<Ellipse>.width Float default: 35.0 -- animatable
The size of the Ellipse local X axis.
<Ellipse>.steps Integer default: 6
The number of divisions between each vertex.
<Ellipse>.optimize Boolean default: true
When on, removes unneeded steps from straight segments in the spline.
<Ellipse>.adaptive Boolean default: false
When on, Adaptive sets the number of steps for each spline to produce a smooth curve.
Straight segments always receive 0 steps.
<Ellipse>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
<Ellipse>.thickness Float default: 1.0 -- animatable
Diameter of the rendered spline.
<Ellipse>.sides Float default: 12.0 -- animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<Ellipse>.viewport_thickness Float default: 1.0
Diameter of the viewport spline.
<Ellipse>.viewport_sides Integer default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a
square cross section, for example.
<Ellipse>.viewport_angle Float default: 0.0
The rotational position of the cross-section in the viewports.
<Ellipse>.DisplayRenderMesh Boolean default: false
When on, displays the mesh generated by the spline in the viewports.
<Ellipse>.UseViewportSettings Boolean default: false
When on, displays the mesh generated by the Viewport settings.
<Ellipse>.DisplayRenderSettings Boolean default: true
When on, displays the mesh generated by the render settings.
<Ellipse>.renderableBoolean default: true
When on, the spline is displayed in the rendered scene.
<Ellipse>.mapCoordsBoolean default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the
thickness of the spline; the V coordinate is mapped once along the length of the spline.
954 Chapter 11 | 3ds max Objects

See also
Spline Shape Common Properties, Operators, and Methods (p. 947)
Shape Common Properties, Operators, and Methods (p. 945)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Helix : Shape
Constructor:
helix ...

Properties:
<Helix>.radius1 Float default: 35.0 -- animatable
The radius for the Helix start.
<Helix>.radius2 Float default: 15.0 -- animatable
The radius for the Helix end.
<Helix>.height Float default: 25.0 -- animatable
The height of the Helix.
<Helix>.turns Float default: 2.0 -- animatable
The number of turns the Helix makes between its start and end points.
<Helix>.bias Float default: 0.0 -- animatable
Forces the turns to accumulate at one end of the helix. A bias of -1.0 forces the turns
towards the start of the helix, a bias of 0.0 evenly distributes the turns between the ends,
and a bias of 1.0 forces the turns towards the end of the helix.
<Helix>.direction Integer default: 0
Set the direction the helix turns:
Clockwise
Counterclockwise
<Helix>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
<Helix>.thickness Float default: 1.0 -- animatable
Diameter of the rendered spline.
<Helix>.sides Float default: 12.0 -- animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<Helix>.viewport_thickness Float default: 1.0
Diameter of the viewport spline.
 Line : Shape 955

<Helix>.viewport_sides Integer default: 12

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a
square cross section, for example.
<Helix>.viewport_angle Float default: 0.0
The rotational position of the cross-section in the viewports.
<Helix>.DisplayRenderMesh Boolean default: false
When on, displays the mesh generated by the spline in the viewports.
<Helix>.UseViewportSettings Boolean default: false
When on, displays the mesh generated by the Viewport settings.
<Helix>.DisplayRenderSettings Boolean default: true
When on, displays the mesh generated by the render settings.
<Helix>.renderableBoolean default: true
When on, the spline is displayed in the rendered scene.
<Helix>.mapCoordsBoolean default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the
thickness of the spline; the V coordinate is mapped once along the length of the spline.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947)
Shape Common Properties, Operators, and Methods (p. 945)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Line : Shape
Constructor:
line ...

Properties:
<Line>.steps Integer default: 6
The number of divisions between each vertex.
<Line>.optimize Boolean default: true
When on, removes unneeded steps from straight segments in the spline.
<Line>.adaptive Boolean default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve.
Straight segments always receive 0 steps.
<Line>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
<Line>.thickness Float default: 1.0 -- animatable
Diameter of the rendered spline.
956 Chapter 11 | 3ds max Objects

<Line>.sides Float default: 12.0 -- animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<Line>.viewport_thickness Float default: 1.0
Diameter of the viewport spline.
<Line>.viewport_sides Integer default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a
square cross section, for example.
<Line>.viewport_angle Float default: 0.0
The rotational position of the cross-section in the viewports.
<Line>.DisplayRenderMesh Boolean default: false
When on, displays the mesh generated by the spline in the viewports.
<Line>.UseViewportSettings Boolean default: false
When on, displays the mesh generated by the Viewport settings.
<Line>.DisplayRenderSettings Boolean default: true
When on, displays the mesh generated by the render settings.
<Line>.renderableBoolean default: true
When on, the spline is displayed in the rendered scene.
<Line>.mapCoordsBoolean default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the
thickness of the spline; the V coordinate is mapped once along the length of the spline.
Note:
The Line shape is equivalent to a SplineShape shape. All the properties and methods associated with
SplineShape are also valid on a Line shape. These properties and methods are described in the
SplineShape : Shape (p. 1079) topic.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947)
Shape Common Properties, Operators, and Methods (p. 945)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 NGon : Shape 957

NGon : Shape
Constructor:
ngon ...

Properties:
<NGon>.radius Float default: 25.0 -- animatable
The NGon radius.
<NGon>.scribe Integer default: 0
Sets whether the NGon is:
Circumscribed (Radius is measured from the center to the sides of the NGon)
Inscribed (Radius is measured from the center to the corners of the NGon)
<NGon>.sides Integer default: 6 -- animatable
Number of sides and vertices used by the NGon.
<NGon>.corner_Radius Float default: 0.0 -- animatable
Degree of rounding to apply to the corners of the NGon. A setting of 0 specifies a standard
unrounded corner.
<NGon>.circular Boolean default: true -- animatable
When on, specifies a circular NGon.
<NGon>.steps Integer default: 6
The number of divisions between each vertex.
<NGon>.optimize Boolean default: true
When on, removes unneeded steps from straight segments in the spline.
<NGon>.adaptive Boolean default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve.
Straight segments always receive 0 steps.
<NGon>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
<NGon>.radiusFloat default: 1.0 -- animatable
<NGon>.thickness Float default: 1.0 -- animatable
Radius of the rendered spline.
<NGon>.sides Float default: 12.0 -- animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<NGon>.viewport_thickness Float default: 1.0
Diameter of the viewport spline.
<NGon>.viewport_sides Integer default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a
square cross section, for example.
<NGon>.viewport_angle Float default: 0.0
The rotational position of the cross-section in the viewports.
958 Chapter 11 | 3ds max Objects

<NGon>.DisplayRenderMesh Boolean default: false

When on, displays the mesh generated by the spline in the viewports.
<NGon>.UseViewportSettings Boolean default: false
When on, displays the mesh generated by the Viewport settings.
<NGon>.DisplayRenderSettings Boolean default: true
When on, displays the mesh generated by the render settings.
<NGon>.renderableBoolean default: true
When on, the spline is displayed in the rendered scene.
<NGon>.mapCoordsBoolean default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the
thickness of the spline; the V coordinate is mapped once along the length of the spline.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947)
Shape Common Properties, Operators, and Methods (p. 945)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Rectangle : Shape
Constructor:
rectangle ...

Properties:
<Rectangle>.length Float default: 10.0 -- animatable
The size of the rectangle along the local Y axis.
<Rectangle>.width Float default: 25.0 -- animatable
The size of the rectangle along the local X axis.
<Rectangle>.Corner_Radius Float default: 0.0 -- animatable; alias:
cornerRadius
Creates rounded corners. When set to 0, the rectangle contains 90-degree corners.
<Rectangle>.steps Integer default: 6
The number of divisions between each vertex.
<Rectangle>.optimize Boolean default: true
When on, removes unneeded steps from straight segments in the spline.
<Rectangle>.adaptive Boolean default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve.
Straight segments always receive 0 steps.
<Rectangle>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
 Section : Shape 959

<Rectangle>.thickness Float default: 1.0 -- animatable

Radius of the rendered spline.
<Rectangle>.sides Float default: 12.0 -- animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<Rectangle>.viewport_thickness Float default: 1.0
Diameter of the viewport spline.
<Rectangle>.viewport_sides Integer default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a
square cross section, for example.
<Rectangle>.viewport_angle Float default: 0.0
The rotational position of the cross-section in the viewports.
<Rectangle>.DisplayRenderMesh Boolean default: false
When on, displays the mesh generated by the spline in the viewports.
<Rectangle>.UseViewportSettings Boolean default: false
When on, displays the mesh generated by the Viewport settings.
<Rectangle>.DisplayRenderSettings Boolean default: true
When on, displays the mesh generated by the render settings.
<Rectangle>.renderableBoolean default: true
When on, the spline is displayed in the rendered scene.
<Rectangle>.mapCoordsBoolean default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the
thickness of the spline; the V coordinate is mapped once along the length of the spline.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947)
Shape Common Properties, Operators, and Methods (p. 945)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Section : Shape
Constructor:
section ...

Properties:
<Section>.length Float default: 0.0 -- animatable
The length of the displayed section rectangle.
<Section>.width Float default: 0.0 -- animatable
The width of the displayed section rectangle.
960 Chapter 11 | 3ds max Objects

Note:
The Section Parameters rollout item properties are not accessible to MAXScript in 3ds max 4.
A bug prevents a Section shape from being properly collapsed to a SplineShape in some cases. This
only happens when a Section shape is created inside a loop and is being converted to a SplineShape.
To collapse to a SplineShape, a viewport redraw must be performed after the Section shape is created.
An example of creating contour lines from an object is:
Script:
meshSelected = sphere() -- object to create contours of
minZ = meshSelected.min.z -- get min and max Z positions
maxZ = meshSelected.max.z
numLevels = 10 -- the number of contours
delta = (maxZ - minZ) / (numLevels + 1) -- the number of steps
for currentZ = minZ to maxZ by delta do -- start loop...
( s = section pos:[0, 0, currentZ] -- create Section
max views redraw -- this line needed to get around bug
convertToSplineShape s -- convert Section to SplineShape
s.renderable = true -- set to renderable
)

See also
Spline Shape Common Properties, Operators, and Methods (p. 947)
Shape Common Properties, Operators, and Methods (p. 945)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Star : Shape
Constructor:
star ...

Properties:
<Star>.radius1 Float default: 25.0 -- alias: Radius_1
The radius of the inner vertices of the star.
<Star>.radius2 Float default: 12.0 -- alias: Radius_2
The radius of the outer vertices of the star.
<Star>.points Integer default: 6 -- alias: numPoints
The number of points on the star. The valid range is from 3 to 100.
<Star>.distort Float default: 0.0 -- alias: Distortion
Rotates the outer vertices about the center of the star. This produces a saw-tooth affect.
<Star>.fillet1Floatdefault: 0.0
Rounds the inner vertices (the valleys) of the star.
 Star : Shape 961

<Star>.fillet2Floatdefault: 0.0
Rounds the outer vertices (the points) of the star.
<Star>.steps Integer default: 6
The number of divisions between each vertex.
<Star>.optimize Boolean default: true
When on, removes unneeded steps from straight segments in the spline.
<Star>.adaptive Boolean default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve.
Straight segments always receive 0 steps.
<Star>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
<Star>.thickness Float default: 1.0 -- animatable
Radius of the rendered spline.
<Star>.sides Float default: 12.0 -- animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<Star>.viewport_thickness Float default: 1.0
Diameter of the viewport spline.
<Star>.viewport_sides Integer default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a
square cross section, for example.
<Star>.viewport_angle Float default: 0.0
The rotational position of the cross-section in the viewports.
<Star>.DisplayRenderMesh Boolean default: false
When on, displays the mesh generated by the spline in the viewports.
<Star>.UseViewportSettings Boolean default: false
When on, displays the mesh generated by the Viewport settings.
<Star>.DisplayRenderSettings Boolean default: true
When on, displays the mesh generated by the render settings.
<Star>.renderableBoolean default: true
When on, the spline is displayed in the rendered scene.
<Star>.mapCoords Boolean default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the
thickness of the spline; the V coordinate is mapped once along the length of the spline.
Note:
The Fillet_Radius_1 and Fillet_Radius_2 properties are not accessible to MAXScript in 3ds max 4.
In order to access the points property for Star, you need to access the property via the baseobject
property of the node. This is because points is also a property name for all nodes, and conflicts with
the Star’s points property. For example:
MyStar.baseobject.points=10 -- set number of Star points to 10
962 Chapter 11 | 3ds max Objects

See also
Spline Shape Common Properties, Operators, and Methods (p. 947)
Shape Common Properties, Operators, and Methods (p. 945)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Text : Shape
Constructor:
text ...

Properties:
<text>.font String default: “Arial”
Choose from a list of all fonts available to 3ds max.
<text>.italic Boolean default: false
Turn on/off italicized text.
<text>.underline Boolean default: false
Turn on/off underlined text.
<text>.alignmentIntegerdefault: 1
Sets the alignment of text:
Align Left (Aligns text to the left side of its bounding box.)
Center (Aligns text to the center of its bounding box.)
Align Right (Aligns text to the right side of its bounding box.)
Justify (Spaces all lines of text to fill the extents of the bounding box.)
<text>.size Float default: 100.0 -- animatable
Te text height where the height measuring method is defined by the active font.
<text>.kerning Float default: 0.0 -- animatable
The kerning (the distance between letters).
<text>.leading Float default: 0.0 -- animatable
The leading (the distance between lines).
<text>.text String default: “3ds max Text”
The text displayed in the viewport.
<text>.steps Integer default: 6
The number of divisions between each vertex.
<text>.optimize Boolean default: true
When on, removes unneeded steps from straight segments in the spline.
<text>.adaptive Boolean default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve.
Straight segments always receive 0 steps.
 Text : Shape 963

<text>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.
<text>.thickness Float default: 1.0 -- animatable
Radius of the rendered spline.
<text>.sides Float default: 12.0 -- animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<text>.viewport_thickness Float default: 1.0
Diameter of the viewport spline.
<text>.viewport_sides Integer default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a
square cross section, for example.
<text>.viewport_angle Float default: 0.0
The rotational position of the cross-section in the viewports.
<text>.DisplayRenderMesh Boolean default: false
When on, displays the mesh generated by the spline in the viewports.
<text>.UseViewportSettings Boolean default: false
When on, displays the mesh generated by the Viewport settings.
<text>.DisplayRenderSettings Boolean default: true
When on, displays the mesh generated by the render settings.
<text>.renderableBoolean default: true
When on, the spline is displayed in the rendered scene.
<text>.mapCoordsBoolean default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the
thickness of the spline; the V coordinate is mapped once along the length of the spline.
Note:
The Manual Update and Alignment properties are not accessible to MAXScript in 3ds max 4.
In 3DS VIZ, the default value for property Text is “VIZ Text”

See also
Spline Shape Common Properties, Operators, and Methods (p. 947)
Shape Common Properties, Operators, and Methods (p. 945)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
964 Chapter 11 | 3ds max Objects

Shapes - NURBS Curves

The following list shows the 3ds max NURBS Curves shape class objects:
CV_Curve (p. 964)
Point_Curve (p. 965)

CV_Curve : Shape
CV_Curves are NURBS curve objects defined by CVs (control vertices). All NURBS objects are created
through the special NURBS descriptor classes (see Working with NURBS (p. 1384)) and the CV_Curve
class is used typically in object class testing with the classOf() function. Scene objects created as
CV Curve shape objects in the 3ds max user interface have the class CV_Curve.
Constructor:
NURBSNode <nurbs_set> ...
See Creating New NURBS Objects (p. 1389) for details.
Properties:
<CV_Curve>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
<CV_Curve>.thickness Float default: 1.0 -- animatable
Diameter of the rendered curve.
<CV_Curve>.sides Float default: 12.0 -- animatable
Sets the number of sides for the curve mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<CV_Curve>.renderableBoolean default: true
When on, the curve is displayed in the rendered scene.
<CV_Curve>.mapCoordsBoolean default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the
thickness of the curve; the V coordinate is mapped once along the length of the curve.
Additional Properties for CV curves are accessed through a NURBSSet descriptor object. See
Working with NURBS (p. 1384) for more details.

See also
Shape Common Properties, Operators, and Methods (p. 945)
NURBS Node Properties and Methods (p. 1397)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Point_Curve : Shape 965

Point_Curve : Shape
Point_Curves are NURBS curve objects defined by interpolated points. All NURBS objects are
created through the special NURBS descriptor classes (see Working with NURBS (p. 1384)) and the
Point_Curve class is used typically in object class testing with the classOf() function. Scene
objects created as Point Curve shape objects in the 3ds max user interface have the class
Point_Curve.
Constructor:
NURBSNode <nurbs_set> ...
See Creating New NURBS Objects (p. 1389) for details.
Properties:
<Point_Curve>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
<Point_Curve>.thickness Float default: 1.0 -- animatable
Diameter of the rendered curve.
<Point_Curve>.sides Float default: 12.0 -- animatable
Sets the number of sides for the curve mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<Point_Curve>.renderableBoolean default: true
When on, the curve is displayed in the rendered scene.
<Point_Curve>.mapCoordsBoolean default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the
thickness of the NURBS curve; the V coordinate is mapped once along the length of the
curve.
Additional properties for point curves are accessed through a NURBSSet descriptor object. See
Working with NURBS (p. 1384) for more details.

See also
Shape Common Properties, Operators, and Methods (p. 945)
NURBS Node Properties and Methods (p. 1397)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
966 Chapter 11 | 3ds max Objects

Light : Node
The following list shows the 3ds max light class objects:
DirectionalLight (p. 970)
FreeSpot (p. 971)
OmniLight (p. 972)
TargetSpot (p. 973)
TargetDirectionalLight (p. 972)

See also
Light Common Properties, Operators, and Methods (p. 966)

Light Common Properties, Operators, and Methods

The following properties apply to all light types except for the Free_Point and Target_Point light
types present in 3D Studio VIZ.
<light>.type Name default: #freeDirect
the valid type values are:
#omni
#freeSpot
#targetSpot
#freeDirect
#targetDirect

<light>.enabled Boolean default: true -- alias: on

Turns the light on and off. When on, shading and rendering use the light to illuminate the
scene. When off, the light is not used in shading or rendering.
<light>.excludeList Array default: #()
Objects in this array are excluded from the effects of the light.
<light>.includeList Array default: undefined
Objects in this array receive the effects of the light.
<light>.inclExclType Integer default: 3
Select the type of object in the Include/Exclude list:
Illumination
Shadow Casting
Both
<light>.castShadows Boolean default: false
When on, the light will cast shadows on objects.
<light>.rgb Color default: (color 180 180 180) --
animatable, alias: color
The red, green, and blue components of the light’s color.
 Light Common Properties, Operators, and Methods 967

<light>.hsv Point3 default: [0,0,180]

Hue, Saturation, and Value color of light.
<light>.hue Integer default: 0
Hue component of hsv.
<light>.saturation Integer default: 0
Saturation component of hsv.
<light>.value Integer default: 180
Value component of hsv.
<light>.multiplier Float default: 1.0 -- animatable
Amplifies the power of the light by a positive or negative amount.
<light>.contrast Float default: 0.0 -- animatable
Adjusts the contrast between the diffuse and ambient areas of the surface. Leave this set to
0 for normal contrast. Increase the value to increase the contrast for special effects: for
example, the harsh light of outer space.
<light>.softenDiffuseEdge Float default: 0.0 -- animatable,
alias: Diffuse_Soften
Increasing the value of Soften Diffuse Edge softens the edge between the diffuse and
ambient portions of a surface. This helps eliminate edges that can appear on a surface
under certain circumstances.
<light>.affectDiffuse Boolean default: true
When on, the light affects the diffuse properties of an object’s surface. When off, the light
has no effect on the diffuse surface.
<light>.affectSpecular Boolean default: true
When on, the light affects the specular properties of an object’s surface. When off, the
light has no effect on the specular properties.
<light>.ambientOnly Boolean default: false
When on, the light affects only the ambient component of the illumination.
<light>.projector Boolean default: false
Turn on to project projectorMap.
<light>.projectorMap TextureMap default: undefined
Assigning a TextureMap to projectorMap causes a new subAnim named
Projection_Map to be created for the light. This subAnim contains the properties of the
TextureMap.
<light>.useShadowProjectorMap Boolean default: false
When on, the light will project a map.
<light>.nearAttenStart Float default: 0.0 -- alias:
animatable, alias: Attenuation_Near_Start
The distance at which the light begins to fade in.
<light>.nearAttenEnd Float default: 40.0 -- alias:
animatable, alias: Attenuation_Near_End
The distance at which the light reaches its full value.
968 Chapter 11 | 3ds max Objects

<light>.useNearAtten Boolean default: false

Enables/Disables near attenuation for the light.
<light>.showNearAtten Boolean default: false
When on, displays the near attenuation range settings in viewports. For spotlights,
attenuation ranges appear as lens-shaped sections of the cone. For directional lights, the
ranges appear as circular sections of the cone. For omni lights and spot or directional lights
with Overshoot turned on, the ranges appear as spheres.
<light>.farAttenStart Float default: 80.0 -- animatable,
alias: Attenuation_Far_Start
The distance at which the light begins to fade out.
<light>.farAttenEnd Float default: 200.0 -- animatable,
alias: Attenuation_Far_End
The distance at which the light has faded to zero.
<light>.useFarAtten Boolean default: false
Enables/Disables far attenuation for the light.
<light>.showFarAtten Boolean default: false
Displays the far attenuation range settings in viewports. For spotlights, attenuation ranges
appear as lens-shaped sections of the cone. For directional lights, the ranges appear as
circular sections of the cone. For omni lights and spot or directional lights with Overshoot
turned on, the ranges appear as spheres.
<light>.attenDecay Integer default: 1
The type of decay to use:
None (Applies no decay. The light maintains full strength from its source to infinity, unless
you turn on far attenuation.)
Inverse (Applies inverse decay. The formula is luminance=R0/R, where R0 is the radial
source of the light if no attenuation is used, or the Near End value of the light if
Attenuation is used. R is the radial distance of the illuminated surface from R0.)
Inverse Square (Applies inverse-square decay. The formula for this is (R0/R)2. This is
actually the “real-world” decay of light, but you might find it too dim in the world of
computer graphics.)
<light>.DecayRadius Float default: 40.0 -- animatable,
alias: Decay_Falloff
The distance over which the decay occurs.
<light>.useGlobalShadowSettings Boolean default: false
Turn on to use global settings for shadows cast by this light. Turn off to enable individual
control of the shadows.
<light>.raytracedShadows Boolean default: false
When true, ray traced shadows are produced. When false, shadow-mapped shadows are
produced.
<light>.ShadowColor Color default: (color 0 0 0) -- animatable,
alias: Shadow_Color
The color of shadows cast by this light.
 Light Common Properties, Operators, and Methods 969

<light>.shadowMultiplier Float default: 1.0 -- animatable,

alias: Shadow_Density
<light>.shadowProjectorMap TextureMap default: undefined
Assigning a TextureMap to shadowProjectorMap causes a new subAnim named
Shadow_Projection_Map to be created for the light. This subAnim contains the
properties of the TextureMap.
<light>.lightAffectsShadow Boolean default: false
When on, blends the light’s color with the shadow color (or shadow colors, if the shadow
is mapped).
<light>.atmosShadows Boolean default: true
When on, atmospheric effects cast shadows as the light passes through them.
<light>.atmosOpacity Float default: 100.0 -- animatable,
percentage, alias: Atmosphere_Opacity
Adjusts the opacity of the shadows. This value is a percentage.
<light>.atmosColorAmt Float default: 100.0 -- animatable,
percentage, alias: Atmosphere_Color_Amount
Adjusts the amount that the atmosphere’s color is blended with the shadow color.
If Shadow Maps are being used (raytracedShadows = false), the shadow properties are:
<light>.mapBias Float default: 1.0 -- animatable,
alias: map_bias
Moves the shadow toward or away from the shadow-casting object (or objects).
<light>.mapSize Integer default: 512 -- animatable,
alias: map_size
Sets the size (in pixels squared) of the shadow map that’s computed for the light.
<light>.sampleRange Float default: 4.0 -- animatable,
alias: map_range
Determines how much area within the shadow is averaged. This affects how soft the edge
of the shadow is.
<light>.absoluteMapBias Boolean default: false -- animatable
When on, the bias for the shadow map is not normalized, but is instead based on a fixed
scale expressed in 3ds max units. This value does not change during an animation. You
must choose the value, based on the size of the scene extents.
When off, the bias is computed relative to the rest of the scene, and then normalized to
1.0. This provides a common starting bias value in scenes of any size. If the scene extents
change, this internal normalization can vary from frame to frame.
<light>.absolute_Bias Integer default: 0 -- integer alias of
absoluteMapBias
970 Chapter 11 | 3ds max Objects

If Ray Traced Shadows are being used (raytracedShadows = true), the shadow properties are:
<light>.raytraceBias Float default: 0.2 -- animatable
Moves the shadow toward or away from the shadow-casting object (or objects). If the Bias
value is too low, shadows can “leak” through places they shouldn’t, produce moire
patterns or making out-of-place dark areas on meshes. If Bias is too high, shadows can
“detach” from an object. If the Bias value is too extreme in either direction, shadows
might not be rendered at all.
<light>.maxDepth Integer default: 7 -- animatable
Adjusts the depth of the quadtree used by the raytracer. Greater quadtree depth values can
improve ray-tracing time at the cost of memory use. However, there is a depth value where
the performance improvement is offset by the time it takes to generate the quadtree itself.
This depends on the geometry of the scene.
Note:
Setting includelist or excludelist sets the other to undefined.
Assigning a Projector TextureMap adds a subAnim to the properties list. The properties of the
subAnim are the properties of the TextureMap.
The Attenuation Parameters/Decay/Show and Shadow Parameters/Map/Enable properties are not
accessible by MAXScript in 3ds max 4.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

DirectionalLight : Light
Constructor:
directionalLight ...

Properties:
<DirectionalLight>.aspect Float default: 1.0 -- animatable,
alias: Aspect_Ratio
The aspect ratio for the rectangular light beam.
<DirectionalLight>.falloff Float default: 45.0 -- animatable
The size of a light’s falloff. The Falloff value is measured in 3ds max units.
<DirectionalLight>.showCone Boolean default: false
Turns display of the cone on or off.
<DirectionalLight>.hotspot Float default: 43.0 -- animatable
The size of a light’s cone. The Hotspot value is measured in 3ds max units.
 FreeSpot : Light 971

<DirectionalLight>.overShoot Boolean default: false

When overshoot is on, the light casts light in all directions. However, projections and
shadows occur only within its falloff cone.
<DirectionalLight>.coneShape Integer default: 1 -- alias: lightShape
The shape of the falloff and hotspot areas:
Circle
Rectangle

See also
Light Common Properties, Operators, and Methods (p. 966)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

FreeSpot : Light
Constructor:
freeSpot ...

Properties:
<Freespot>.aspect Float default: 1.0 -- animatable, alias:
Aspect_Ratio
The aspect ratio for the rectangular light beam.
<Freespot>.falloff Float default: 45.0 -- animatable
The angle of a light’s falloff. The Falloff value is measured in degrees.
<Freespot>.showCone Boolean default: false
Turns display of the cone on or off.
<Freespot>.hotspot Float default: 43.0 -- animatable
The angle of a light’s cone. The Hotspot value is measured in degrees.
<Freespot>.overShoot Boolean default: false
When on, the light casts light in all directions. However, projections and shadows occur
only within its falloff cone.
<Freespot>.coneShape Integer default: 1 -- alias: lightShape
The shape of the falloff and hotspot areas:
Circle
Rectangle
972 Chapter 11 | 3ds max Objects

See also
Light Common Properties, Operators, and Methods (p. 966)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

OmniLight : Light
Constructor:
omniLight ...

Properties:
There are no additional properties for OmniLight.

See also
Light Common Properties, Operators, and Methods (p. 966)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TargetDirectionalLight : Light
Constructor:
targetDirectionalLight ...

Properties:
<TargetDirectionallight>.aspect Float default: 1.0 -- animatable,
alias: Aspect_Ratio
The aspect ratio for the rectangular light beam.
<TargetDirectionallight>.falloff Float default: 45.0 -- animatable
The angle of a light’s falloff. The Falloff value is measured in degrees.
<TargetDirectionallight>.showCone Boolean default: false
Turns display of the cone on or off.
<TargetDirectionallight>.hotspot Float default: 43.0 -- animatable
The angle of a light’s cone. The Hotspot value is measured in degrees.
<TargetDirectionallight>.overShoot Boolean default: false
When on, the light casts light in all directions. However, projections and shadows occur
only within its falloff cone.
 TargetSpot : Light 973

<TargetDirectionallight>.coneShape Integer default: 1 -- alias:

lightShape
The shape of the falloff and hotspot areas:
Circle
Rectangle
Note:
In MAXScript, you must explicitly construct a target for those objects that need one. For example:
c = TargetDirectionallight pos:[x,y,z] target:(targetObject pos:[xt, yt, zt])

See also
Light Common Properties, Operators, and Methods (p. 966)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TargetSpot : Light
Constructor:
targetSpot ...

Properties:
<Targetspot>.aspect Float default: 1.0 -- animatable, alias:
Aspect_Ratio
The aspect ratio for the rectangular light beam.
<Targetspot>.falloff Float default: 45.0 -- animatable
The angle of a light’s falloff. The Falloff value is measured in degrees.
<Targetspot>.showCone Boolean default: false
Turns display of the cone on or off.
<Targetspot>.hotspot Float default: 43.0 -- animatable
The angle of a light’s cone. The Hotspot value is measured in degrees.
<Targetspot>.overShoot Boolean default: false
When on, the light casts light in all directions. However, projections and shadows occur
only within its falloff cone.
<Targetspot>.coneShape Integer default: 1 -- alias: lightShape
The shape of the falloff and hotspot areas:
Circle
Rectangle
Note:
In MAXScript, you must explicitly construct a target for those objects that need one. For example:
c = Targetspot pos:[x,y,z] target:(targetObject pos:[xt, yt, zt])
974 Chapter 11 | 3ds max Objects

See also
Light Common Properties, Operators, and Methods (p. 966)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Camera : Node
The following list displays the camera objects:
FreeCamera (p. 976)
TargetCamera (p. 976)

See also
Camera Common Properties, Operators, and Methods (p. 974)

Camera Common Properties, Operators, and Methods

Properties:
The following properties apply to all camera types:
<camera>.fov Float default: 45.0 -- animatable, angle
Determines how wide an area the camera views.
<camera>.orthoProjection Boolean default: false
When on, the camera view looks just like a User view. When off, the camera view is the
standard perspective-like view.
<camera>.type Name default: #free
The type of camera:
#free - Free Camera (Target view can be set in any direction)
#target - Target Camera (Camera will always align view with target object)
<camera>.showCone Boolean default: false
Displays the cone (actually a pyramid) defined by a camera’s field of view. The cone
appears in the other viewports but does not appear in a camera viewport.
<camera>.showHorizon Boolean default: false
Displays the horizon line. A dark gray line appears at the level of the horizon in the
camera’s viewport.
<camera>.nearrange Float default: 0.0 -- animatable; alias:
Near_Env_Range
The near range for atmospheric effects.
<camera>.farrange Float default: 1000.0 -- animatable; alias:
Far_Env_Range
The far range for atmospheric effects.
 Camera Common Properties, Operators, and Methods 975

<camera>.clipManually Boolean default: false

Turn on to define clipping planes. When Clip Manually is off, geometry closer to the
camera than 3 units is not displayed.
<camera>.nearclip Float default: 1.0 -- animatable, alias:
near_clip
Objects closer than the near clipping plane are invisible to the camera.
<camera>.farclip Float default: 1000.0 -- animatable, alias:
far_clip
Objects farther than the far clipping plane are invisible to the camera.
<camera>.showRanges Boolean default: false
When on, displays yellow rectangles within the camera’s cone to show the Near and Far
range settings.
<camera>.targetDistance Float default: 160.0 -- animatable, alias:
Target_Distance
Sets a point to use as an invisible target.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Note:
The fov parameter value is the horizontal FOV in degrees.
The Vertical and Diagonal FOV and Lens values are based on the horizontal FOV and the current
renderer Aperture Width.
You can use the following function to calculate the Vertical FOV from the Horizontal FOV:
fn GetCamVFOV theCamera =
( local r_aspect=(renderWidth as float)/renderHeight
2.*atan(tan(theCamera.fov/2.)/r_aspect)
)

Examples:
The following script changes the fov of specified camera to simulate a “zoom extents all” for the
camera.
Script:
fn ZE_Cam cam objs =
( local max2, fov, asp, v -- declare local variables
-- define a function that returns the maximum value of a set of values in an array
fn maxof vals = (local v=vals[1]; for v1 in vals do (if v1 > v do v=v1);v)
fov=0 -- initialize the fov value
asp=(renderWidth as float)/renderHeight -- calculate the renderer’s image aspect
ratio
in coordsys cam -- work in coordinate system of the
camera
976 Chapter 11 | 3ds max Objects

( for obj in objs where obj != cam do -- loop across all objects except the
camera
( if obj.min.z >=0 do continue -- if object is behind camera, skip it
-- get max value of the object’s bounding box, correcting for the image
aspect ratio
-- in the y values
v = maxof #((abs obj.max.x),(abs obj.min.x),(abs (obj.max.y*asp)),(abs
(obj.min.y*asp)))
fov = maxof #(fov,(2*atan(-v/obj.min.z))) -- increase fov if needed
)
)
cam.fov=fov -- set the camera’s fov to the new fov
value
)
--test bed --
cam=$camera01 -- specify the camera to “zoom extent all” on
ZE_Cam cam $* -- call the function, passing the camera and an object set
containing all objects

FreeCamera : Camera
Constructor:
freecamera ...
Properties:
There are no additional properties for FreeCamera.

See also
Camera Common Properties, Operators, and Methods (p. 974)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TargetCamera : Camera
Constructor:
targetCamera ...

Properties:
There are no additional properties for TargetCamera.
 TargetCamera : Camera 977

See also
Camera Common Properties, Operators, and Methods (p. 974)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Helper : Node
The following list shows the helper objects:
-- Standard
Bone (p. 978)
Compass (p. 979)
Dummy (p. 979)
Grid (p. 980)
Point (p. 980)
Protractor (p. 981)
Tape (p. 981)
-- Atmospheric
BoxGizmo (p. 982)
CylGizmo (p. 983)
SphereGizmo (p. 983)
-- Camera Match
CamPoint (p. 984)
-- VRML 1.0/VRBL
Inline (p. 984)
LOD (p. 985)
VRML_VRBL (p. 985)
-- VRML97
Anchor (p. 986)
AudioClip (p. 986)
Background (p. 987)
Billboard (p. 987)
FogHelper (p. 987)
InlineHelper (p. 988)
LODHelper (p. 988)
NavInfo (p. 988)
978 Chapter 11 | 3ds max Objects

ProxSensor (p. 989)

Sound (p. 989)
TouchSensor (p. 990)
TimeSensor (p. 990)

Helper - Standard
The following list shows the standard helper objects:
Bone (p. 978)
Compass (p. 979)
Dummy (p. 979)
Grid (p. 980)
Point (p. 980)
Protractor (p. 981)
Tape (p. 981)

Bone : Helper
Constructor:
bone ...
Properties:
There are no additional properties for Bone.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Note:
The Bone helper object is used by 3ds max to represent the nodes in a Bones system. In 3ds max 4,
it is not possible to create a Bones system using IK controllers on the Bones’ nodes.
You can create a hierarchy of Bone helper objects which use the standard PRS transform controller
for each node. For example:
b0 = bone pos:[x,y,z]
in b0 b1 = bone pos:[x1,y1,z1]
in b1 b2 = bone pos:[x2,y2,z2]
in b2 b3 = bone pos:[x3,y3,z3]
 Compass : Helper 979

You can rearrange bone hierarchies using the parent property.

When a hierarchy of Bone helper objects is built, the showLinks and showLinksOnly properties
are automatically set to true.

Compass : Helper
Constructor:
compass ...

Properties:
There are no additional properties for Compass.
Note:
The Show Compass Rose and Radius properties are not accessible to MAXScript in 3ds max 4.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Dummy : Helper
Constructor:
dummy ...

Properties:
<Dummy>.boxsize Point3 default: [10,10,10]
Icon size.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
980 Chapter 11 | 3ds max Objects

Grid : Helper
Constructor:
grid ...

Properties:
<grid>.length Float default: 50.0 -- animatable
Length of the grid.
<grid>.width Float default: 50.0 -- animatable
Width of the grid.
<grid>.grid Float default: 10.0 -- animatable
The size of the smallest square in the visible grid.
Note:
The Active Color and Display properties are not accessible to MAXScript in 3ds max 4.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Point : Helper
Constructor:
point ...

Properties:
<Point>.axisLength Float default: 20.0
Sets the length of the tripod axis.
<Point>.size Float default: 20.0 -- animatable
Sets the size of of the point helper.
<Point>.centermarker Boolean default: false -- animatable
When turned on, a small X marker is displayed at the center of the point helper object.
<Point>.axistripod Boolean default: false -- animatable
When this is turned on, an axis tripod with ‘x’, ‘y’, and ‘z’ labels is displayed.
<Point>.cross Boolean default: true -- animatable
When this is turned on, an axis aligned cross is displayed.
<Point>.box Boolean default: false -- animatable
When this is turned on, a square box is displayed centered at the center of the point
helper object.
 Protractor : Helper 981

<Point>.constantscreensize Boolean default: false -- animatable

When this is turned on, the point object remains the same size in screen space regardless
of how much the user zooms in or out.
<Point>.drawontop Boolean default: false -- animatable
When this is on, the point helper object draws lines with the Z buffer turned off (which
usually causes it to appear in front of other objects).

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Protractor : Helper
Constructor:
protractor ...

Properties:
There are no additional properties for Protractor.
Note:
There is not a way to set the Protractor reference objects using MAXScript in 3ds max 4.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Tape : Helper
Constructor:
tape ...
Properties:
<Tape>.length Float default: 50.0 -- animatable
Length of the tape object.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
982 Chapter 11 | 3ds max Objects

Note:
To construct a tape, you have to create its target node first (using the targetObject constructor),
and then construct the tape giving it the target:
tape pos:p target:(targetObject pos:q)

The length property shows the tape length set in the 3ds max user interface, not the true
distance from the tape to its target. The following function can be used to return this distance:
fn getTapeDist TapeObj = distance TapeObj TapeObj.target

An example usage is:

getTapeDist $tape01

Helper - Atmospheric
The following list shows the atmospheric helper objects:
BoxGizmo (p. 982)
CylGizmo (p. 983)
SphereGizmo (p. 983)

BoxGizmo : Helper
Constructor:
boxGizmo ...

Properties:
<BoxGizmo>.length Float default: 0.0 -- animatable
Length of the box gizmo.
<BoxGizmo>.width Float default: 0.0 -- animatable
Width of the box gizmo.
<BoxGizmo>.height Float default: 0.0 -- animatable
Height of the box gizmo.
<BoxGizmo>.seed Integer default: 0 -- alias: parameter
Base value used to generate the atmospheric effect. Each apparatus in the scene should
have a different seed. If more than one apparatus uses the same seed and same
atmospheric effect, they will produce nearly identical results.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 CylGizmo : Helper 983

CylGizmo : Helper
Constructor:
cylGizmo ...

Properties:
<CylGizmo>.radius Float default: 0.0 -- animatable
Radius of cylinder gizmo object.
<CylGizmo>.height Float default: 0.0 -- animatable
Height of cylinder gizmo object.
<CylGizmo>.seed Integer default: 0 -- alias: parameter
Base value used to generate the atmospheric effect. Each apparatus in the scene should
have a different seed. If more than one apparatus uses the same seed and same
atmospheric effect, they will produce nearly identical results.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SphereGizmo : Helper
Constructor:
sphereGizmo ...

Properties:
<SphereGizmo>.radius Float default: 0.0 -- animatable
Radius of sphere gizmo object.
<SphereGizmo>.hemisphere Integer default: 0
When turned on, the bottom half of the SphereGizmo is discarded, creating a hemisphere:
OFF
ON
<SphereGizmo>.seed Integer default: 0
Base value used to generate the atmospheric effect. Each apparatus in the scene should
have a different seed. If more than one apparatus uses the same seed and same
atmospheric effect, they will produce nearly identical results.
984 Chapter 11 | 3ds max Objects

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Helper - Camera Match

The following list shows the camera match helper objects:
CamPoint (p. 984)

CamPoint : Helper
Constructor:
camPoint ...

Properties:
<CamPoint>.showAxis Boolean default: true
When on, an axis tripod is displayed with the camera point object.
<CamPoint>.axisLength Float default: 20.0
The length of the axis tripod.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Helper - VRML 1.0/VRBL

The following list shows the VRML 1.0/VRBL helper objects:
Inline (p. 984)
LOD (p. 985)
VRML_VRBL (p. 985)

Inline : Helper
Constructor:
inline ...

Properties:
There are no additional properties for Inline.
 LOD : Helper 985

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

LOD : Helper
Constructor:
lod ...

Properties:
There are no additional properties for LOD.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

VRML_VRBL : Helper
Constructor:
vrml_vrbl ...

Properties:
There are no additional properties for VRML_VRBL.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Helper - VRML97
The following list shows the VRML97 helper objects:
Anchor (p. 986)
AudioClip (p. 986)
Background (p. 987)
Billboard (p. 987)
FogHelper (p. 987)
986 Chapter 11 | 3ds max Objects

InlineHelper (p. 988)

LODHelper (p. 988)
NavInfo (p. 988)
ProxSensor (p. 989)
Sound (p. 989)
TouchSensor (p. 990)
TimeSensor (p. 990)

Anchor : Helper
Constructor:
anchor ...

Properties:
There are no additional properties for Anchor.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

AudioClip : Helper
Constructor:
audioClip ...

Properties:
There are no additional properties for AudioClip.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Background : Helper 987

Background : Helper
Constructor:
background ...

Properties:
There are no additional properties for Background.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Billboard : Helper
Constructor:
billboard ...

Properties:
There are no additional properties for Billboard.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

FogHelper : Helper
Constructor:
fogHelper ...

Properties:
There are no additional properties for FogHelper.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
988 Chapter 11 | 3ds max Objects

InlineHelper : Helper
Constructor:
inlineHelper ...

Properties:
There are no additional properties for InlineHelper.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

LODHelper : Helper
Constructor:
lodHelper ...

Properties:
There are no additional properties for LODHelper.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

NavInfo : Helper
Constructor:
navInfo ...

Properties:
There are no additional properties for NavInfo.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 ProxSensor : Helper 989

ProxSensor : Helper
Constructor:
proxSensor ...

Properties:
There are no additional properties for ProxSensor.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Sound : Helper
Constructor:
sound ...

Properties:
There are no additional properties for Sound.
Variables:
WAVsound.filename
Get/set Sound track filename as <string>. There currently is not a way to perform and
Remove Sound via MAXScript
WAVsound.start
Get/set Sound track range start time as <time>.
WAVsound.end
A read only variable to get the Sound track range end time as a <time> value.
WAVsound.mute
Get/set whether Sound track is active as <boolean>.
WAVsound.isPlaying
A read only variable that returns whether the Sound track is currently playing as a
<boolean> value.
Methods:
WAVsound.scrub <interval>
Plays back the specified time interval of the Sound track.
990 Chapter 11 | 3ds max Objects

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TimeSensor : Helper
Constructor:
timeSensor ...

Properties:
There are no additional properties for TimeSensor.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TouchSensor : Helper
Constructor:
touchSensor ...

Properties:
There are no additional properties for TouchSensor.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Bones : System 991

System : Node
System objects are not creatable by MAXScript. Once a system object in created in 3ds max, various
properties associated with the system are accessible by MAXScript.
The 3ds max system objects are:
Bones (p. 991)
Sunlight (p. 991)
RingArray (p. 992)
Note: Only the Sunlight class is available in 3D Studio VIZ.

Bones : System
Note: This class is not available in 3D Studio VIZ.
Bones system objects are not creatable by MAXScript.
A Bones system is comprised of the Bone Helper (p. 978) objects, a master IK controller, and slave IK
controllers. The slave IK controllers are used as the transform controller for all nodes in the IK
system, and the master IK controller controls the individual slave IK controllers. The methods
associated with the IK controller are described in the IK_ControllerMatrix3Controller :
Matrix3Controller (p. 1313) topic.

Sunlight : System
Sunlight system objects are not creatable by MAXScript.
A Bones system is comprised of a Compass Helper (p. 979) object and a TargetDirectionalLight (p. 972)
object. The TargetDirectionalLight’s transform is controlled by a set of float controllers, which are
sub-controllers of a non-accessible position controller (a Sunlight_Slave_Controller position
controller). These float controllers can be accessed as subAnims of the TargetDirectionalLight node.
These float controllers, and their subAnim index number, are:
Solar_Time - subAnim[3]
Solar_Date - subAnim[4]
Latitude - subAnim[5]
Longitude - subAnim[6]
Orbital_Scale - subAnim[7]

For example, if node $Sun01 is the light for a Sunlight system, the Solar_Time controller can be
accessed as:
solarTimeCont=$Sun01[3].object
992 Chapter 11 | 3ds max Objects

RingArray : System
Note: This class is not available in 3D Studio VIZ.
RingArray system objects are not creatable by MAXScript.
A RingArray system is comprised of a Dummy Helper (p. 979) object, a variable number of Box (p. 853)
objects, a master controller, and Slave_Control controllers. The Slave_Control controllers are used
as the transform controller for all Boxes in the RingArray system, and the master controller controls
the individual Slave_Control controllers. The methods associated with the Slave_Control controller
are described in the Slave_Controller : Matrix3Controller (p. 1333) topic.

SpacewarpObject : Node
Note: Spacewarp objects are not available in 3D Studio VIZ.
The following list shows the space warp objects:
-- Geometric/Deformable
Bomb (p. 993)
Conform (p. 995)
SpaceDisplace (p. 996)
SpaceFFDBox (p. 998)
SpaceFFDCyl (p. 999)
SpaceRipple (p. 1001)
SpaceWave (p. 1002)
-- Particles and Dynamics
Gravity (p. 1003)
Motor (p. 1004)
PBomb (p. 1006)
Push (p. 1008)
Wind (p. 1010)
-- Modifier-Based
SpaceBend (p. 1011)
SpaceNoise (p. 1012)
SpaceSkew (p. 1014)
SpaceStretch (p. 1015)
SpaceTaper (p. 1016)
SpaceTwist (p. 1017)
 Bomb : SpacewarpObject 993

-- Dynamics Interface
PDynaFlect (p. 1019)
SDynaFlect (p. 1020)
UDynaFlect (p. 1022)
-- Particles Only
Deflector (p. 1024)
Path_Follow (p. 1025)
POmniFlect (p. 1027)
SDeflector (p. 1030)
SOmniFlect (p. 1031)
UDeflector (p. 1033)
UOmniFlect (p. 1034)

Spacewarp - Geometric/Deformable
Note: Spacewarp objects are not available in 3D Studio VIZ.
The following list shows the geometric/deformable space warp objects:
Bomb (p. 993)
Conform (p. 995)
SpaceDisplace (p. 996)
SpaceFFDBox (p. 998)
SpaceFFDCyl (p. 999)
SpaceRipple (p. 1001)
SpaceWave (p. 1002)

Bomb : SpacewarpObject
Constructor:
bomb ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Bomb>.strength Float default: 1.0 -- animatable
The power of the bomb. Larger values make the particles fly farther. The closer an object is
to the bomb, the greater the effect of the bomb.
<Bomb>.spin Float default: 0.0 -- animatable
The rate at which fragments rotate, in revolutions per second.
994 Chapter 11 | 3ds max Objects

<Bomb>.falloff Float default: 100.0 -- animatable

The distance from the bomb, in world units, of the effect of the bomb. Fragments past this
distance are not affected by the Strength and Spin settings, but are affected by the Gravity
setting.
<Bomb>.fallOffEnable Boolean default: false
Turn on to use the Falloff setting. The falloff range appears as a yellow, tri-hooped sphere.
<Bomb>.minFragmentSize Integer default: 1
The minimum number of faces per fragment to be randomly generated by the
“explosion.”
<Bomb>.maxFragmentSize Integer default: 1
The maximum number of faces per fragment to be randomly generated by the
“explosion.”
<Bomb>.Gravity Float default: 1.0 -- animatable
The acceleration due to gravity. Note that gravity is always in the direction of the world Z
axis. You can have negative gravity.
<Bomb>.chaos Float default: 0.0 -- animatable
Adds random variation to the explosion to make it less uniform. A setting of 0.0 is totally
uniform; 1.0 is a realistic setting. A value greater than 1.0 makes the explosion extra
chaotic.
<Bomb>.detonation Time default: 5f
The frame at which the bomb goes off. Bound objects are unaffected before this time.
<Bomb>.seed Integer default: 0
Change to alter randomly generated numbers in the bomb. You can achieve a different
bomb effect by changing Seed while maintaining the other settings.
Associated Methods:
bindSpaceWarp <node> <bomb_node>

Associated Binding Modifier:

BombBinding
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 ConformSpaceWarp : SpacewarpObject 995

ConformSpaceWarp : SpacewarpObject
Constructor:
conformSpaceWarp ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<ConformSpaceWarp>.Projection_Distance Float default: 0.0 -- animatable
The distance a vertex in the bound object moves from its original location if it does not
intersect the target object.
<ConformSpaceWarp>.Standoff_Distance Float default: 1.0 -- animatable
The distance maintained between the vertex and the surface of the target object.
<ConformSpaceWarp>.Selected_Verts Integer default: 0 -- animatable
When on, only the sub-object selection of vertices on the Stack are pushed. When off, all
vertices in the object are pushed regardless of the Stack selection:
OFF
ON
<ConformSpaceWarp>.Icon_Size Float default: 0.0
The size of the icon.
Note:
There is not a way to set the Wrap To Object using MAXScript in 3ds max 4.
Associated Methods:
bindSpaceWarp <node> <conformSpaceWarp_node>

Associated Binding Modifier:

SpaceConform
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
996 Chapter 11 | 3ds max Objects

SpaceDisplace : SpacewarpObject
Constructor:
spaceDisplace ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Spacedisplace>.strength Float default: 0.0 -- animatable
When set to 0.0, the Displace warp has no effect. Values greater than 0.0 displace object
geometry or particles away from the position of the Displace space warp object. Values less
than 0.0 displace geometry toward the warp.
<Spacedisplace>.decay Float default: 0.0 -- animatable
By default, the Displace warp has the same strength throughout world space. Increasing
Decay causes displacement strength to diminish as distance increases from the position of
the Displace warp object.
<Spacedisplace>.lumCenterEnable Boolean default: false
Turn on/off use of the luminance center.
<Spacedisplace>.lumCenter Float default: 0.5 -- animatable
By default, the Displace space warp centers the luminance by using medium (50%) gray as
the zero displacement value. Gray values greater than 128 displace in the outward
direction (away from the Displace warp object) and gray values less than 128 displace in
the inward direction (toward the Displace warp object).
<Spacedisplace>.bitmap Bitmap default: undefined
Bitmap assigned to use for displacement.
<Spacedisplace>.map TextureMap default: undefined
Texture map assigned to use for displacement.
<Spacedisplace>.blur Float default: 0.0 -- animatable
Increase this value to blur or soften the effect of the bitmapped displacement.
<Spacedisplace>.maptype Integer default: 0
The map projection type:
Planar (Projects the map from a single plane.)
Cylindrical (Projects the map as if it were wrapped around the cylinder.)
Spherical (Projects the map from a sphere, with singularities at the top and bottom of the
sphere, where the bitmap edges meet at the sphere’s poles.)
Shrink Wrap (Truncates the corners of the map and joins them all at a single pole, creating
one singularity.)
<Spacedisplace>.length Float default: 1.0 -- animatable
The length of the bounding box on the space warp gizmo.
<Spacedisplace>.width Float default: 1.0 -- animatable
The width of the bounding box on the space warp gizmo.
 SpaceDisplace : SpacewarpObject 997

<Spacedisplace>.height Float default: 1.0 -- animatable

The height of the bounding box on the space warp gizmo.
<Spacedisplace>.U_Flip Boolean default: false
When on, reverses the orientation of the map along the U-axis.
<Spacedisplace>.U_Tile Float default: 1.0 -- animatable
The number of times the map repeats along the U-axis.
<Spacedisplace>.V_Flip Boolean default: false
When on, reverses the orientation of the map along the V-axis.
<Spacedisplace>.V_Tile Float default: 1.0 -- animatable
The number of times the map repeats along the U-axis.
<Spacedisplace>.W_Flip Boolean default: false
When on, reverses the orientation of the map along the W-axis.
<Spacedisplace>.W_Tile Float default: 1.0 -- animatable
The number of times the map repeats along the U-axis.
The following properties are defined for SpaceDisplace, but are not used:
<Spacedisplace>.axis Integer default: 0
<Spacedisplace>.cap Boolean default: false
<Spacedisplace>.useMap Boolean default: false
<Spacedisplace>.applyMap Boolean default: false

Associated Methods:
bindSpaceWarp <node> <spaceDisplace_node>

Associated Binding Modifier:

DisplaceBinding
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.
Note:
When a TextureMap is assigned to map, a Displacement_Map subAnim is added to the parameters.
The parameters of the subAnim correspond to the TextureMap properties.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
998 Chapter 11 | 3ds max Objects

SpaceFFDBox : SpacewarpObject
Constructor:
spaceFFDBox ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<SpaceFFDBox>.length Float default: 0.0 -- animatable
Sets the length of the lattice.
<SpaceFFDBox>.width Float default: 0.0 -- animatable
Sets the width of the lattice.
<SpaceFFDBox>.height Float default: 0.0 -- animatable
Sets the length of the lattice.
<SpaceFFDBox>.dispLattice Boolean default: true -- alias: Lattice
When turned on, lines are drawn connecting the control points to make a grid.
<SpaceFFDBox>.dispSource Boolean default: false -- alias: Source_Volume
When on, the control points and lattice are displayed in their unmodified state.
<SpaceFFDBox>.deformType Integer default: 0
Specifies which vertices are affected by the FFD:
Only In Volume (Only vertices that lie inside the source volume are deformed. Vertices
outside the source volume are not affected.)
All Vertices (All vertices are deformed regardless of whether they lie inside or outside the
source volume, depending on the .falloff value.)
<SpaceFFDBox>.falloff Float default: 0.0 -- animatable
The distance from the lattice that the FFD effect will decrease to zero. When this value is
set to 0, it’s effectively turned off, and there is no falloff; that is, all vertices are affected
regardless of their distance from the lattice. The units of the Falloff parameter are specified
relative to the size of the lattice: A falloff of 1 means that the effect will go to 0 for points
that are a lattice width/length/height away from the lattice (depending on which side they
are on).
<SpaceFFDBox>.tension Float default: 25.0 -- animatable
Sets the tension of the deformation splines.
<SpaceFFDBox>.continuity Float default: 25.0 -- animatable
Sets the continuity of the deformation splines.
Associated Methods:
bindSpaceWarp <node> <spaceFFDBox_node>
 SpaceFFDCyl : SpacewarpObject 999

Associated Binding Modifier:

FFD_Binding
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.
Note:
The number of control points in a SpaceFFDBox created by MAXScript is always 4x4x4.
There is no method for assigning controllers to the FFD control points, nor is there a method for
assigning the number or accessing the number of Length, Width, and Height points using
MAXScript in 3ds max 4.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation
(p. 1461) for details on accessing the control points in an FFD.

SpaceFFDCyl : SpacewarpObject
Constructor:
spaceFFDCyl ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<SpaceFFDCyl>.radius Float default: 0.0 -- animatable
Sets the radius of the lattice.
<SpaceFFDCyl>.height Float default: 0.0 -- animatable
Sets the height of the lattice.
<SpaceFFDCyl>.dispLattice Boolean default: true -- alias: Lattice
When on, lines are drawn connecting the control points to make a grid.
<SpaceFFDCyl>.dispSource Boolean default: false -- alias: Source_Volume
When on, the control points and lattice are displayed in their unmodified state.
<SpaceFFDCyl>.deformType Integer default: 0
Specifies which vertices are affected by the FFD:
Only In Volume (Only vertices that lie inside the source volume are deformed. Vertices
outside the source volume are not affected.)
All Vertices (All vertices are deformed regardless of whether they lie inside or outside the
source volume, depending on the .falloff value.)
1000 Chapter 11 | 3ds max Objects

<SpaceFFDCyl>.falloff Float default: 0.0 -- animatable

The distance from the lattice that the FFD effect will decrease to zero. When this spinner is
set to 0, it’s effectively turned off, and there is no falloff; that is, all vertices are affected
regardless of their distance from the lattice. The units of the Falloff parameter are specified
relative to the size of the lattice: A falloff of 1 means that the effect will go to 0 for points
that are a lattice width/length/height away from the lattice (depending on which side they
are on).
<SpaceFFDCyl>.tension Float default: 25.0 -- animatable
Sets the tension of the deformation splines.
<SpaceFFDCyl>.continuity Float default: 25.0 -- animatable
Sets the continuity of the deformation splines.
Associated Methods:
bindSpaceWarp <node> <spaceFFDCyl_node>

Associated Binding Modifier:

FFD_Binding
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.
Note:
The number of control points in a SpaceFFDCyl is always 4x8x4.
There is no method for assigning controllers to the FFD control points, nor is there a method for
assigning the number or accessing the number of Side, Radial, and Height points using MAXScript
in 3ds max 4.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation
(p. 1461) for details on accessing the control points in an FFD.
 SpaceRipple : SpacewarpObject 1001

SpaceRipple : SpacewarpObject
Constructor:
spaceRipple ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Spaceripple>.amplitude1 Float default: 5.0 -- animatable, alias: Amplitude_1
Ripple amplitude along the ripple warp object’s local X axis. Amplitude is expressed in
active units.
<Spaceripple>.amplitude2 Float default: 5.0 -- animatable, alias: Amplitude_2
Ripple amplitude along the ripple warp object’s local Y axis. Amplitude is expressed in
active units.
<Spaceripple>.wavelength Float default: 25.0 -- animatable, alias: Wave_Length
The length of each wave, in active units.
<Spaceripple>.phase Float default: 0.0 -- animatable
Offsets the phase of the wave from its origin at the ripple object’s center. Whole values
have no effect; only fractional values do. Animating this parameter makes the ripple
appear to travel through space.
<Spaceripple>.decay Float default: 0.0 -- animatable
When set to 0.0, the ripple has the same amplitude or amplitudes throughout world space.
Increasing the Decay value causes amplitude to diminish as distance increases from the
position of the ripple warp object.
<Spaceripple>.circles Integer default: 10
The number of circles in the ripple icon.
<Spaceripple>.segments Integer default: 16
The number of segments (pie slices) in the ripple icon.
<Spaceripple>.divisions Integer default: 4
Adjusts the size of the ripple icon without altering the ripple effect as scaling would.
Associated Methods:
bindSpaceWarp <node> <spaceRipple_node>

Associated Binding Modifier and Properties:

RippleBinding
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. The following property is associated with this binding
modifier:
<RippleBinding>.Flexibility Float default: 1.0
1002 Chapter 11 | 3ds max Objects

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SpaceWave : SpacewarpObject
Constructor:
spaceWave ...
Note: This class is not available in 3D Studio VIZ.
Properties:
<Spacewave>.amplitude1 Float default: 5.0 -- animatable, alias: Amplitude_1
Wave amplitude along the wave warp object’s local X axis.
<Spacewave>.amplitude2 Float default: 5.0 -- animatable, alias: Amplitude_2
Wave amplitude along the wave warp object’s local Y axis.
<Spacewave>.wavelength Float default: 25.0 -- animatable, alias: Wave_Length
The length of each wave along the wave’s local Y axis, in active units.
<Spacewave>.phase Float default: 0.0 -- animatable
Offsets the phase of the wave from its origin at the wave object’s center. Whole values have
no effect; only fractional values do. Animating this parameter makes the wave appear to
travel through space.
<Spacewave>.decay Float default: 0.0 -- animatable
When set to 0.0, the wave has the same amplitude or amplitudes throughout world space.
Increasing the Decay value causes amplitude to diminish as distance increases from the
position of the wave warp object.
<Spacewave>.circles Integer default: 4
The number of side segments along the wave object’s local X dimension.
<Spacewave>.segments Integer default: 20
The number of segments along the wave object’s local Y dimension.
<Spacewave>.divisions Integer default: 10
Adjusts the size of the wave icon without altering the wave effect as scaling would.
Associated Methods:
bindSpaceWarp <node> <spaceWave_node>

Associated Binding Modifier and Properties:

WaveBinding
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. The following property is associated with this binding
modifier:
<WaveBinding>.Flexibility Float default: 1.0
 Gravity : SpacewarpObject 1003

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Spacewarp - Particles and Dynamics

Note: Spacewarp objects are not available in 3D Studio VIZ.
The following list shows the particles and dynamics space warp objects:
Gravity (p. 1003)
Motor (p. 1004)
PBomb (p. 1006)
Push (p. 1008)
Wind (p. 1010)

Gravity : SpacewarpObject
Constructor:
gravity ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Gravity>.strength Float default: 1.0 -- animatable
Increasing Strength increases the effect of gravity; that is, how objects move in relation to
the Gravity icon’s direction arrow. Strength less than 0.0 creates negative gravity, which
repels particles moving in the same direction and attracts particles moving in the opposite
direction. When Strength is set to 0.0, the Gravity space warp has no effect.
<Gravity>.decay Float default: 1.0 -- animatable
When Decay is set to 0.0, the Gravity space warp has the same strength throughout world
space. Increasing the Decay value causes gravity strength to diminish as distance increases
from the position of the gravity warp object.
<Gravity>.gravitytype Integer default: 0
Set the type of gravity effect:
0 – Planar
1 - Spherical
<Gravity>.showRangeBooleandefault: false
When on, and when the decay value is greater than 0.0, icons in the viewports indicate
the range at which the force of gravity is half the maximum value.
1004 Chapter 11 | 3ds max Objects

<Gravity>.iconsize Float default: 10.0 -- animatable

Size of the Gravity warp object icon, in active units. You set the initial size when you drag
to create the Gravity object. This value does not change the gravity effect.
<Gravity>.hoopson Boolean default: true
When on, and when the decay value is greater than 0.0, icons in the viewports indicate
the range at which the force of gravity is half the maximum value. For the Planar option,
the indicators are two planes; for use the Spherical option, the indicator is a double-
hooped sphere.
Associated Methods:
bindSpaceWarp <node> <gravity_node>

Associated Binding Modifier:

GravityBinding
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Motor : SpacewarpObject
Constructor:
motor ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Motor>.On_Time Time default: 0f
The frame at which the motor effect begins.
<Motor>.Off_Time Time default: 30f
The frame at which the motor effect ends.
<Motor>.Basic_Torque Float default: 1.0 -- animatable
The amount of force exerted by the space warp.
<Motor>.units Integer default: 0
The unit of measure for the basic torque setting:
Newton-meters
Pound-feet
Pound-inches
 Motor : SpacewarpObject 1005

<Motor>.Feedback_On Integer default: 0

When on, the force varies depending on the speed of the affected objects relative to the
specified Target Speed. When off, the force remains constant, regardless of the speed of the
affected objects:
OFF
ON
<Motor>.Reversible Integer default: 0
When on, if the object’s speed exceeds the Target Speed setting, the force is reversed:
OFF
ON
<Motor>.Target_Revs Float default: 100.0 -- animatable
The maximum revolutions before the feedback takes effect.
<Motor>.Revs_Units Integer default: 1
The unit of measure for the target revolutions:
RPH
RPM
RPS
<Motor>.Control_Gain Float default: 50.0 -- animatable
Specifies how quickly the force adjusts to approaching the target speed. If set to 100%, the
correction is immediate. If set lower, a slower and “looser” response occurs.
<Motor>.Enable_Variation Integer default: 0
Turn on to enable the variations:
OFF
ON
<Motor>.Variation_Period_1 Time default: 0.625f
The time over which the noise variation makes a full cycle.
<Motor>.Amplitude_1 Float default: 100.0 -- animatable
The strength of the variation (in percent).
<Motor>.Variation_Phase_1 Float default: 0.0 -- animatable, angle
Offsets the variation pattern.
<Motor>.Variation_Period_2 Time default: 0.625f
Provides an additional variation pattern to increase the noise.
<Motor>.Amplitude_2 Float default: 100.0 -- animatable
The strength of the variation of the second wave in (percent).
<Motor>.Variation_Phase_2 Float default: 0.0 -- animatable, angle
Offsets the variation pattern of the second wave.
1006 Chapter 11 | 3ds max Objects

<Motor>.Range_Enable Integer default: 0

When on, limits the range of the effect to a sphere, displayed as a tri-hooped sphere. The
effect falls off increasingly as the particles near the boundary of the sphere.
OFF
ON
<Motor>.Range_Value Float default: 1000.0 -- animatable
The radius of the range of the effect, in units.
<Motor>.Icon_Size Float default: 0.0
The size of the Motor icon. This is for display purposes only, and does not alter the Motor
effect.
Associated Methods:
bindSpaceWarp <node> <motor_node>

Associated Binding Modifier:

MotorMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

PBomb : SpacewarpObject
Constructor:
pbomb ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<PBomb>.symmetry Integer default: 0
The shape, or pattern of the blast effect:
Spherical (The blast force radiates outward from the PBomb icon in all directions. The icon
looks like a spherical anarchist’s bomb.)
Cylindrical (The blast force radiates outward from and normal to the central axis, or core
of the cylindrical icon. The icon looks like a stick of dynamite with a fuse.)
Planar (The blast force radiates both up and down, perpendicular to the plane of the
planar icon. The icon looks like a plane with arrows pointing up and down along the
direction of the blast force.)
 PBomb : SpacewarpObject 1007

<PBomb>.chaos Float default: 10.0 -- percentage

The blast forces vary for each particle or each frame, an effect similar to Brownian motion,
with a rate of change in the direction of force equal to the rendering interval rate.
<PBomb>.Start_Time Time default: 30f
The frame number at which the impulse forces are first applied to the particles.
<PBomb>.Lasts_For Time default: 1f
The number of frames, beyond the first, over which the forces are applied. This value
should typically be a small number, such as between 0 and 3.
<PBomb>.strength Float default: 1.0 -- animatable
The change in velocity along the blast vector, in units per frame. Increasing Strength
increases the speed with which the particles are blown away from the bomb icon.
<PBomb>.Decay_Type Integer default: 1
Sets the decay type:
Unlimited Range (The effects of the bomb icon reach all bound particles throughout the
scene. This option ignores the Range setting, which specifies the distance of the PBomb
effect.)
Linear (The impulse forces decay linearly between the full Strength setting to a value of 0
at the specified Range setting.)
Exponential (The impulse forces decay exponentially between the full Strength setting to a
value of 0 at the specified Range setting.)
<PBomb>.range Float default: 1000.0 -- animatable
The maximum distance, in units, over which the PBomb icon affects the bound particle
system. If the Range is large enough to reach only a portion of the particle system, only
that part of the system is affected.
<PBomb>.Icon_Size Float default: 0.0
The overall size of the PBomb icon.
Associated Methods:
bindSpaceWarp <node> <pbomb_node>

Associated Binding Modifier:

PBombMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1008 Chapter 11 | 3ds max Objects

PushSpaceWarp : SpacewarpObject
Constructor:
pushSpaceWarp ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<PushSpaceWarp>.On_Time Time default: 0f
The frame in which the space warp begins its effect.
<PushSpaceWarp>.Off_Time Time default: 30f
The frame in which the space warp ends its effect.
<PushSpaceWarp>.Basic_Force Float default: 1.0 -- animatable
The amount of force exerted by the space warp.
<PushSpaceWarp>.units Integer default: 0
The unit of force used by the basic force:
Newtons
Pounds
<PushSpaceWarp>.Feedback_On Integer default: 0
When on, the force varies depending on the speed of the affected objects relative to the
specified Target Speed. When off, the force remains constant, regardless of the speed of the
affected objects:
OFF
ON
<PushSpaceWarp>.Reversible Integer default: 0
When on, if the object’s speed exceeds the Target Speed setting, the force is reversed
OFF
ON
<PushSpaceWarp>.Target_Speed Float default: 100.0 -- animatable
The maximum speed in units per frame before the Feedback takes effect.
<PushSpaceWarp>.Control_Gain Float default: 50.0 -- animatable
Specifies how quickly the force adjusts to approaching the target speed. If set to 100
percent, the correction is immediate. If set lower, a slower and “looser” response occurs.
<PushSpaceWarp>.Enable_Variation Integer default: 0
Turn on/off variations:
OFF
ON
<PushSpaceWarp>.Variation_Period_1 Time default: 0.625f -- animatable
The time over which the noise variation makes a full cycle.
<PushSpaceWarp>.Amplitude_1 Float default: 100.0 -- animatable
The strength of the variation (in percent).
 PushSpaceWarp : SpacewarpObject 1009

<PushSpaceWarp>.Variation_Phase_1 Float default: 0.0 -- animatable, angle

Offsets the variation pattern.
<PushSpaceWarp>.Variation_Period_2 Time default: 0.625f -- animatable
Provides an additional variation pattern (a second wave) to increase the noise.
<PushSpaceWarp>.Amplitude_2 Float default: 100.0 -- animatable
The strength of the variation of the second wave (in percent).
<PushSpaceWarp>.Variation_Phase_2 Float default: 0.0 -- animatable, angle
Offsets the variation pattern of the second wave
<PushSpaceWarp>.Range_Enable Integer default: 0
When on, limits the range of the effect to a sphere, displayed as a tri-hooped sphere. The
effect falls off increasingly as the particles near the boundary of the sphere.
OFF
ON
<PushSpaceWarp>.Range_Value Float default: 1000.0 -- animatable
The radius of the range of the effect, in units.
<PushSpaceWarp>.Icon_Size Float default: 0.0
The size of the Push icon. This is for display purposes only, and does not alter the Push
effect.
Associated Methods:
bindSpaceWarp <node> <pushSpaceWarp_node>

Associated Binding Modifier:

PushMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1010 Chapter 11 | 3ds max Objects

Wind : SpacewarpObject
Constructor:
wind ...
Note: This class is not available in 3D Studio VIZ.
Properties:
<Wind>.strength Float default: 1.0 -- animatable
Increasing Strength increases the wind effect. Strength less than 0.0 creates a suction. It
repels particles moving in the same direction and attracts particles moving in the opposite
direction. When Strength is 0.0, the Wind warp has no effect.
<Wind>.decay Float default: 1.0 -- animatable
When Decay is set to 0.0, the Wind warp has the same strength throughout world space.
Increasing the Decay value causes wind strength to diminish as distance increases from the
position of the Wind warp object.
<Wind>.windtype Integer default: 0
Sets the type of wind:
Planar
Spherical
<Wind>.turbulence Float default: 1.0 -- animatable
Causes particles to change course randomly as the wind blows them. The greater the value,
the greater the turbulence effect.
<Wind>.frequency Float default: 1.0 -- animatable
When set greater than 0.0, causes turbulence to vary periodically over time. This subtle
effect is probably not visible unless your bound particle system generates a large number of
particles.
<Wind>.windScale Float default: 0.0 -- animatable
Scales the turbulence effect. When Scale is small, turbulence is smoother and more regular.
As Scale increases, turbulence grows more irregular and wild.
<Wind>.showRange Boolean default: false
When on, and when the decay value is greater than zero, icons appear in the viewports
that represent the range at which the force of wind is half the maximum value.
<Wind>.iconsize Float default: 10.0 -- animatable
Size of the Wind warp object icon, in active units.
<Wind>.hoopson Boolean default: false
When turned on, icons appear in the viewports that represent the range at which the force
of wind is half the maximum value. When you use the Planar option, the indicators are
two planes; when you use the Spherical option, the indicator is a double-hooped sphere.
 SpaceBend : SpacewarpObject 1011

Associated Methods:
bindSpaceWarp <node> <wind_node>

Associated Binding Modifier:

WindBinding
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Spacewarp - Modifier-Based
Note: Spacewarp objects are not available in 3D Studio VIZ.
The following list shows the Modifier-Based space warp objects:
SpaceBend (p. 1011)
SpaceNoise (p. 1012)
SpaceSkew (p. 1014)
SpaceStretch (p. 1015)
SpaceTaper (p. 1016)
SpaceTwist (p. 1017)

SpaceBend : SpacewarpObject
Constructor:
spaceBend ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<SpaceBend>.length Float default: 0.0 -- animatable
The length of the warp object.
<SpaceBend>.width Float default: 0.0 -- animatable
The width of the warp object.
<SpaceBend>.height Float default: 0.0 -- animatable
The height of the warp object.
1012 Chapter 11 | 3ds max Objects

<SpaceBend>.decay Float default: 0.0 -- animatable

When is set to 0, there is no decay, and the space warp affects its bound object regardless
of its distance from the object. When you increase the decay, the effect on the bound
object falls off exponentially.
<SpaceBend>.angle Float default: 0.0 -- animatable
The angle to bend from the vertical plane.
<SpaceBend>.direction Float default: 0.0 -- animatable
Te direction of the bend relative to the horizontal plane.
<SpaceBend>.Lower_Limit Float default: 0.0 -- animatable, alias: Lowerlimit
Te lower boundary in world units from the bend center point beyond which the bend no
longer affects geometry.
<SpaceBend>.Upper_Limit Float default: 0.0 -- animatable, alias: Upperlimit
The upper boundary in world units from the bend center point beyond which the bend no
longer affects geometry.
Associated Methods:
bindSpaceWarp <node> <spaceBend_node>

Associated Binding Modifier:

SimpleOSMToWSMMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SpaceNoise : SpacewarpObject
Constructor:
spaceNoise ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<SpaceNoise>.length Float default: 0.0 -- animatable
The length of the warp object.
<SpaceNoise>.width Float default: 0.0 -- animatable
The width of the warp object.
<SpaceNoise>.height Float default: 0.0 -- animatable
The height of the warp object.
 SpaceNoise : SpacewarpObject 1013

<SpaceNoise>.decay Float default: 0.0 -- animatable

When is set to 0, there is no decay, and the space warp affects its bound object regardless
of its distance from the object. When you increase the decay, the effect on the bound
object falls off exponentially.
<SpaceNoise>.seed Integer default: 0 -- animatable
Generates a random start point from the number you set. Especially useful in creating
terrain, because each setting can produce a different configuration.
<SpaceNoise>.scale Float default: 100 -- animatable
The size of the noise effect (not strength). Larger values produce smoother noise, lower
values more jagged noise.
<SpaceNoise>.fractal Integer default: 0 -- animatable
When on, produces a fractal effect based on current settings:
OFF
ON
<SpaceNoise>.Rough Float default: 0.0 -- animatable
Determines the extent of fractal variation. Lower values are less rough than higher values.
<SpaceNoise>.iterations Float default: 6.0 -- animatable
The number of iterations (or octaves) used by the fractal function. Fewer iterations use less
fractal energy and generate a smoother effect. An iteration of 1.0 is the same as turning
Fractal off.
<SpaceNoise>.phase Integer default: 0 -- animatable
Shifts the start and end points of the underlying wave.
<SpaceNoise>.strength Point3 default: [0,0,0] -- animatable
The strength of the noise effect along each of three axes. Enter a value for at least one of
these axes to produce a noise effect.
Note:
Since scale is a property for all nodes, a name conflict exists between the scale property for nodes
and the scale property for SpaceNoise. To access the SpaceNoise scale property, you need to access
this property as a property of a node’s baseObject property. For example:
sn=spaceNoise()
sn.baseObject.scale=150

The Animate Noise property is not accessible using MAXScript in 3ds max 4.
Associated Methods:
bindSpaceWarp <node> <spaceNoise_node>

Associated Binding Modifier:

SimpleOSMToWSMMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.
1014 Chapter 11 | 3ds max Objects

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SpaceSkew : SpacewarpObject
Constructor:
spaceSkew ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<SpaceSkew>.length Float default: 0.0 -- animatable
The length of the warp object.
<SpaceSkew>.width Float default: 0.0 -- animatable
The width of the warp object.
<SpaceSkew>.height Float default: 0.0 -- animatable
The height of the warp object.
<SpaceSkew>.decay Float default: 0.0 -- animatable
When is set to 0, there is no decay, and the space warp affects its bound object regardless
of its distance from the object. When you increase the decay, the effect on the bound
object falls off exponentially.
<SpaceSkew>.amount Float default: 0.0 -- animatable
The angle to skew from the vertical plane.
<SpaceSkew>.direction Float default: 0.0 -- animatable
The direction of the skew relative to the horizontal plane.
<SpaceSkew>.Lower_Limit Float default: 0.0 -- animatable
The lower limit boundaries in world units from the skew center point, beyond which the
skew no longer affects the geometry.
<SpaceSkew>.Upper_Limit Float default: 0.0 -- animatable
The upper limit boundaries in world units from the skew center point, beyond which the
skew no longer affects the geometry.
Associated Methods:
bindSpaceWarp <node> <spaceSkew_node>

Associated Binding Modifier:

SimpleOSMToWSMMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.
 SpaceStretch : SpacewarpObject 1015

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SpaceStretch : SpacewarpObject
Constructor:
spaceStretch ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<SpaceStretch>.length Float default: 0.0 -- animatable
The length of the warp object.
<SpaceStretch>.width Float default: 0.0 -- animatable
The width of the warp object.
<SpaceStretch>.height Float default: 0.0 -- animatable
The height of the warp object.
<SpaceStretch>.decay Float default: 0.0 -- animatable
When is set to 0, there is no decay, and the space warp affects its bound object regardless
of its distance from the object. When you increase the decay, the effect on the bound
object falls off exponentially.
<SpaceStretch>.Stretch Float default: 0.0 -- animatable
The base scale factor for all three axes. The scale factor derived from the Stretch value
varies according to the sign of the value:
Positive stretch values define a scale factor equal to Stretch+1. For example, a stretch value
of 1.5 yields a scale factor of 1.5+1=2.5, or 250 percent.
Negative stretch values define a scale factor equal to -1/(Stretch-1). For example, a stretch
value of -1.5 yields a scale factor of -1/(-1.5-1)=0.4, or 40 percent.
<SpaceStretch>.Amplify Float default: 0.0 -- animatable
The scale factor applied to the minor axes. Amplify generates a multiplier using the same
technique as stretch. The multiplier is then applied to the Stretch value before the scale
factor for the minor axes is calculated.
<SpaceStretch>.from Float default: 0.0 -- animatable
The boundary of the stretch effect along the negative Stretch Axis. The Lower Limit can be
0 or any negative number.
<SpaceStretch>.to Float default: 0.0 -- animatable
The boundary of the stretch effect along the positive Stretch Axis. The Upper Limit can be
0 or any positive number.
1016 Chapter 11 | 3ds max Objects

Associated Methods:
bindSpaceWarp <node> <spaceStretch_node>

Associated Binding Modifier:

SimpleOSMToWSMMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SpaceTaper : SpacewarpObject
Constructor:
spaceTaper ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<SpaceTaper>.length Float default: 0.0 -- animatable
The length of the warp object.
<SpaceTaper>.width Float default: 0.0 -- animatable
The width of the warp object.
<SpaceTaper>.height Float default: 0.0 -- animatable
The height of the warp object.
<SpaceTaper>.decay Float default: 0.0 -- animatable
When is set to 0, there is no decay, and the space warp affects its bound object regardless
of its distance from the object. When you increase the decay, the effect on the bound
object falls off exponentially.
<SpaceTaper>.amount Float default: 0.0 -- animatable
The extent to which the ends are scaled. Amount is a relative value with a maximum of 10.
<SpaceTaper>.curvature Float default: 0.0 -- animatable
Applies a curvature to the sides of the Taper gizmo, thus affecting the shape of the tapered
object. Positive values produce an outward curve along the tapered sides, negative values
an inward curve. At 0, the sides are unchanged.
 SpaceTwist : SpacewarpObject 1017

<SpaceTaper>.symmetry Integer default: 0

When on, produces a symmetrical taper around the primary axis. A taper is always
symmetrical around the effect axis:
OFF
ON
<SpaceTaper>.Lower_Limit Float default: 0.0 -- animatable
The lower limit boundaries in world units from the taper center point, beyond which the
taper no longer affects the geometry.
<SpaceTaper>.Upper_Limit Float default: 0.0 -- animatable
The upper limit boundaries in world units from the taper center point, beyond which the
taper no longer affects the geometry.
Associated Methods:
bindSpaceWarp <node> <spaceTaper_node>

Associated Binding Modifier:

SimpleOSMToWSMMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SpaceTwist : SpacewarpObject
Constructor:
spaceTwist ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<SpaceTwist>.length Float default: 0.0 -- animatable
The length of the warp object.
<SpaceTwist>.width Float default: 0.0 -- animatable
The width of the warp object.
<SpaceTwist>.height Float default: 0.0 -- animatable
The height of the warp object.
1018 Chapter 11 | 3ds max Objects

<SpaceTwist>.decay Float default: 0.0 -- animatable

When is set to 0, there is no decay, and the space warp affects its bound object regardless
of its distance from the object. When you increase the decay, the effect on the bound
object falls off exponentially.
<SpaceTwist>.angle Float default: 0.0 -- animatable
The amount of twist around the vertical axis.
<SpaceTwist>.bias Float default: 0.0 -- animatable
Causes the twist rotation to bunch up at either end of the object. When the parameter is
negative, the object twists closer to the gizmo center. When the value is positive, the
object twists more away from the gizmo center. When the parameter is 0, the twisting is
uniform.
<SpaceTwist>.Lower_Limit Float default: 0.0 -- animatable
The lower limit for the twist effect.
<SpaceTwist>.Upper_Limit Float default: 0.0 -- animatable
The upper limit for the twist effect.
Associated Methods:
bindSpaceWarp <node> <spaceTwist_node>

Associated Binding Modifier:

SimpleOSMToWSMMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Spacewarp - Dynamics Interface

Note: Spacewarp objects are not available in 3D Studio VIZ.
The following list shows the Modifier-Based space warp objects:
PDynaFlect (p. 1019)
SDynaFlect (p. 1020)
UDynaFlect (p. 1022)
 PDynaFlect : SpacewarpObject 1019

PDynaFlect : SpacewarpObject
Constructor:
PDynaFlect ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<PDynaFlect>.Time_On Time default: 0f
Specifies the frame at which the deflection begins.
<PDynaFlect>.Time_Off Time default: 100f -- animatable
Specifies the frame at which the deflection ends.
<PDynaFlect>.Reflects Float default: 10000.0 -- animatable
Specifies the percentage of particles to be reflected by the PDynaFlect.
<PDynaFlect>.bounce Float default: 1.0 -- animatable
This multiplier specifies how much of the initial speed of the particle is maintained after
collision with the PDynaFlect.
<PDynaFlect>.Bounce_Variation Float default: 0.0 -- animatable
Specifies the variation of Bounce applied to the range of particles.
<PDynaFlect>.chaos Float default: 0.0 -- animatable
Applies a random variation to the bounce angle.
<PDynaFlect>.Velocity_Inheritance Float default: 1.0 -- animatable
Determines how much of a moving PDynaFlect’s speed is applied to reflected or refracted
particles.
<PDynaFlect>.Particle_Mass Float default: 1.0 -- animatable
Specifies the mass based on the chosen unit.
<PDynaFlect>.Particle_Mass_Units Integer default: 0
Sets the mass unit for particles:
Gram
Kilogram
Pound
<PDynaFlect>.width Float default: 0.0 -- animatable
Specify the width of the PDynaFlect icon. This is for display purposes only and does not
influence the deflector effect.
<PDynaFlect>.height Float default: 0.0 -- animatable
Specify the height of the PDynaFlect icon. This is for display purposes only and does not
influence the deflector effect.
1020 Chapter 11 | 3ds max Objects

Associated Methods:
bindSpaceWarp <node> <PDynaFlect_node>

Associated Binding Modifier:

PDynaFlectMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SDynaFlect : SpacewarpObject
Constructor:
SDynaFlect ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<SDynaFlect>.’time on’ Integer default: 0 -- animatable; alias:
time_on
The time at which the deflection begins.
<SDynaFlect>.’time off’ Integer default: 16000 -- animatable; alias:
time_off
The time at which the deflection ends.
<SDynaFlect>.affects Float default: 10000.0 -- animatable; percentage;
alias: reflects
The percentage of particles to be reflected by the PDynaFlect.
<SDynaFlect>.bouncevar Float default: 0.0 -- animatable;
percentage; alias: bounce_variation
The variation of Bounce applied to the range of particles.
<SDynaFlect>.inheritVelocity Float default: 1.0 -- animatable: alias:
velocity_inheritance
Determines how much of a moving PDynaFlect’s speed is applied to reflected or refracted
particles.
<SDynaFlect>.mass Float default: 1.0 -- animatable; alias:
particle_mass
The mass based on the chosen unit.
 SDynaFlect : SpacewarpObject 1021

<SDynaFlect>.’mass units’ Integer default: 0 -- animatable; alias:

particle_mass_units
The unit to use for particle mass values:
Gram
Kilogram
Pound
<SDynaFlect>.’force in x’ Float default: 0.0 -- animatable
Force applied along the X-axis.
<SDynaFlect>.’force in y’ Float default: 0.0 -- animatable
Force applied along the Y-axis.
<SDynaFlect>.’force in z’ Float default: 0.0 -- animatable
Force applied along the Z-axis.
<SDynaFlect>.’apply at x’ Float default: 0.0 -- animatable
Location on the X-axis where force is applied.
<SDynaFlect>.’apply at y’ Float default: 0.0 -- animatable
Location on the Y-axis where force is applied.
<SDynaFlect>.’apply at z’ Float default: 0.0 -- animatable
Location on the Z-axis where force is applied.
<SDynaFlect>.number Integer default: 0 -- animatable
Number of particles.
<SDynaFlect>.friction Float default: 0.0 -- animatable
When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and
there’s no change in the particle behavior. As the friction value increases, particles begin to
rebound at incorrect angles and with greater speed.
<SDynaFlect>.collider Undefined default: undefined -- max object
Node which particles deflect off of.
<SDynaFlect>.bounce Float default: 1.0 -- animatable
Multiplier that specifies how much of the initial speed of the particle is maintained after
collision with the SDynaFlect.
<SDynaFlect>.chaos Float default: 0.0 -- animatable
Applies a random variation to the bounce angle.
<SDynaFlect>.radius Float default: 0.0 -- animatable
Radius of the SdynaFlect icon. This setting also alters the effect of the deflection, because
particles bounce off the perimeter of the icon.
1022 Chapter 11 | 3ds max Objects

Associated Methods:
bindSpaceWarp <node> <SDynaFlect_node>

Associated Binding Modifier:

SDynaFlectMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

UDynaFlect : SpacewarpObject
Constructor:
UDynaFlect ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<UDynaFlect>.’time on’ Integer default: 0 -- animatable; alias: time_on
Time at which the deflector turns on.
<UDynaFlect>.’time off’ Integer default: 1600000 -- animatable; alias:
time_off
Time at which the deflector turns off.
<UDynaFlect>.affects Float default: 10000.0 -- animatable; percentage;
alias: reflects
The percentage of particles to be reflected by the UDynaFlect.
<UDynaFlect>.bounce Float default: 1.0 -- animatable
This multiplier specifies how much of the initial speed of the particle is maintained after
collision with the UDynaFlect.
<UDynaFlect>.bouncevar Float default: 0.0 -- animatable;
percentage; alias: bounce_variation
The variation of Bounce applied to the range of particles.
<UDynaFlect>.chaos Float default: 0.0 -- animatable
Applies a random variation to the bounce angle.
<UDynaFlect>.Friction Float default: 0.0 -- animatable
When set to 0.0 (the default) the surface of the deflector is treated as frictionless, and
there’s no change in particle behavior. As Friction increases, particles begin to rebound at
incorrect angles and with greater speed.
 UDynaFlect : SpacewarpObject 1023

<UDynaFlect>.inheritVelocity Float default: 1.0 -- animatable; alias:

velocity_inheritance
Determines how much of a moving UDynaFlect’s speed is applied to reflected or refracted
particles.
<UDynaFlect>.mass Float default: 1.0 -- animatable; alias:
particle_mass
The mass value of the particle.
<UDynaFlect>.’mass units’ Integer default: 0 -- animatable; alias:
particle_mass_units
Sets the unit of mass to use:
Gram
Kilogram
Pound
<UDynaFlect>.’force in x’ Float default: 0.0 -- animatable
Force applied along the X-axis.
<UDynaFlect>.’force in y’ Float default: 0.0 -- animatable
Force applied along the Y-axis.
<UDynaFlect>.’force in z’ Float default: 0.0 -- animatable
Force applied along the Z-axis.
<UDynaFlect>.’apply at x’ Float default: 0.0 -- animatable
Location on the X-axis where force is applied.
<UDynaFlect>.’apply at y’ Float default: 0.0 -- animatable
Location on the Y-axis where force is applied.
<UDynaFlect>.’apply at z’ Float default: 0.0 -- animatable
Location on the Z-axis where force is applied.
<UDynaFlect>.number Integer default: 20 -- animatable
Number of particles.
<UDynaFlect>.collider Undefined default: undefined -- max object
Node which deflects particles.
<UDynaFlect>.radius Float default: 0.0 -- animatable; alias: icon_size
The size of the UDynaFlect icon.
Associated Methods:
bindSpaceWarp <node> <UDynaFlect_node>

Associated Binding Modifier:

UDynaFlectMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.
1024 Chapter 11 | 3ds max Objects

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Spacewarp - Particles Only

Note: Spacewarp objects are not available in 3D Studio VIZ.
The following list shows the Particles Only space warp objects:
Deflector (p. 1024)
Path_Follow (p. 1025)
POmniFlect (p. 1027)
SDeflector (p. 1030)
SOmniFlect (p. 1031)
UDeflector (p. 1033)
UOmniFlect (p. 1034)

Deflector : SpacewarpObject
Constructor:
deflector ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Deflector>.bounce Float default: 1.0 -- animatable
Controls the speed at which particles bounce off the deflector. At a setting of 1.0, particles
bounce off the deflector at the same speed they struck it. At 0.0, particles do not bounce at
all. At values between 0.0 and 1.0, particles bounce off the deflector at a speed reduced
from their initial speed. At values greater than 1.0, particles bounce off the deflector at a
speed greater than their initial speed.
<Deflector>.width Float default: 10.0 -- animatable
The deflector’s width.
<Deflector>.length Float default: 10.0 -- animatable
The deflector’s length.
<Deflector>.variation Float default: 0.0 -- animatable
The bounce variation.
<Deflector>.chaos Float default: 0.0 -- animatable
Angle variation after bounce.
<Deflector>.friction Float default: 0.0 -- animatable
Amount of friction applied to particle.
 Path_Follow : SpacewarpObject 1025

<Deflector>.inheritVelocity Float default: 0.0 -- animatable

Percentage of deflector’s motion inherited by the particle.
<Deflector>.quality Integer default: 20 -- animatable
Affects how well the system deflects particles. The lower the number, the more likely it is
to leak, but the faster it will go.
Associated Methods:
bindSpaceWarp <particlesys_node> <deflector_node>

Associated Binding Modifier:

DeflectorBinding
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Path_Follow : SpacewarpObject
Constructor:
path_Follow ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Path_Follow>.Range_Limited Integer default: 1
When off, the range of influence of the space warp is limited to the value set in
.range_value. When on, the space warp influences all bound particles in the scene,
regardless of their distance from the path object.
OFF
ON
<Path_Follow>.Range_Value Float default: 100.0 -- animatable
The range of influence when Unlimited Range is off. This is the distance between the path
object and the particle system. The position of the Path Follow space warp’s icon is
ignored.
1026 Chapter 11 | 3ds max Objects

<Path_Follow>.Spline_Follow_Type Integer default: 1

Set the follow type:
Along Offset Splines (The distance between the particle system and the path alter the effect
of the particle motion. If the first vertex of the spline is at the birthplace of the particle,
the particle follows the spline path. If you move the path away from the particle system,
the particles are affected by the offset.)
Along Parallel Splines (Particles follow a copy of the selected path, parallel to the particle
system. In this mode, the position of the path relative to the particle system does not
matter. The orientation of the path, however, affects the particle stream.)
<Path_Follow>.Constant_Speed Integer default: 0
When on, all particles travel at the same speed:
OFF
ON
<Path_Follow>.Tangent_Chaos Float default: 0.0 -- percentage
Causes particles to converge or diverge toward the path over time, or to simultaneously
converge and diverge. You specify the effect by choosing Converge, Diverge, or Both (see
following). This provides a tapering effect over the length of the path.
<Path_Follow>.Tang_Chaos_Var Float default: 0.0
The amount by which .tangent_chaos can vary for each particle.
<Path_Follow>.Tangent_Dir Integer default: 0
Set behavior of tangent chaos:
Converge (When .tangent_chaos is greater than 0, the particles move in toward the path
as they follow the path. The effect is that the stream tapers from larger to smaller over
time.
Diverge (Provides the opposite effect of Converge. The particles diverge from the path over
time.)
Both (Splits the particle stream, causing some particles to converge and others to diverge.)
<Path_Follow>.Spiral_Chaos Float default: 0.0
The number of turns by which particles spiral about the path. In conjunction with
.tangent_chaos, alters the diameter of the spiral.
<Path_Follow>.Spiral_Chaos_Var Float default: 0.0
The amount by which each particle can vary from the Spiral value.
<Path_Follow>.Spiral_Dir Integer default: 0
The direction of spiraling behavior:
Clockwise
Counterclockwise
Bidirectional (The stream is splits so that particles spiral in both directions.)
<Path_Follow>.Start_Time Time default: 0f
The frame at which Path Follow begins to influence the particles.
 POmniFlect : SpacewarpObject 1027

<Path_Follow>.Travel_Time Time default: 30f

The time each particle takes to traverse the path.
<Path_Follow>.Travel_Var Float default: 0.0 -- percentage
The amount by which each particle’s travel time can vary.
<Path_Follow>.Stop_Time Time default: 100f
The frame at which Path Follow releases the particles and no longer influences them.
<Path_Follow>.Icon_Size Float default: 0.0
The size of the Path Follow icon. Does not alter the Path Follow effect.
Note:
There is not a way to select the Path shape object using MAXScript in 3ds max 4.
The Seed parameter in not accessible using MAXScript in 3ds max 4.
Associated Methods:
bindSpaceWarp <particlesys_node> <path_Follow_node>

Associated Binding Modifier:

PathFollowMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

POmniFlect : SpacewarpObject
Constructor:
POmniFlect ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<POmniFlect>.deceleration Float default: 1.0 -- animatable
Sets the deceleration of particles.
<POmniFlect>.’decel var’ Float default: 0.0 -- animatable;
percentage
Affects the variation in deceleration of particles.
<POmniFlect>.friction Float default: 0.0 -- animatable; percentage
When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and
there’s no change in the particle behavior. As the friction value increases, particles begin to
rebound at incorrect angles and with greater speed.
1028 Chapter 11 | 3ds max Objects

<POmniFlect>.quality Integer default: 20 -- animatable

Affects how wells the system deflects particles. The lower the value, the more likely it is to
leak, but the faster it will go.
<POmniFlect>.collider Undefined default: undefined -- max object
Node which particles will deflect off of.
<POmniFlect>.’time on’ Integer default: 0 -- animatable; alias: time_on
The frame at which the deflection begins.
<POmniFlect>.’time off’ Integer default: 16000 -- animatable; alias:
time_off
The frame at which the deflection ends.
<POmniFlect>.affects Float default: 10000.0 -- animatable; alias:
reflects
The percentage of particles to be reflected by the POmniFlect.
Controller Scaling: (1 : 100.0)
<POmniFlect>.bounce Float default: 1.0 -- animatable
This multiplier specifies how much of the initial speed of the particle is maintained after
collision with the POmniFlect.
<POmniFlect>.bouncevar Float default: 0.0 -- animatable; alias:
bounce_variation
The variation of Bounce applied to the range of particles.
Controller Scaling: (1 : 100.0)
<POmniFlect>.chaos Float default: 0.0 -- animatable
Applies a random variation to the bounce angle. When set to 0.0 (no chaos), all particles
bounce off the POmniFlect surface perfectly (like banking pool balls). A non-zero setting
causes the deflected particles to scatter.
<POmniFlect>.Refracts Float default: 100.0 -- animatable
The percentage of particles not already reflected that will be refracted by the POmniFlect.
<POmniFlect>.’pass velocity’ Float default: 1.0 -- animatable;
alias: pass_velocity
Sets how much of a particle’s initial speed is maintained after passing through the
POmniFlect. The default setting of 1 retains the initial speed is retained, so there’s no
change. A setting of 0.5 reduces the speed by half.
<POmniFlect>.’passvel var’ Float default: 0.0 -- animatable;
percentage; alias: Pass_Velocity_Variation
Variation of Pass Velocity applied to the range of particles.
<POmniFlect>.refraction Float default: 50.0 -- animatable;
percentage; alias: distortion
Controls the angle of refraction. A value of 0 means there’s no refraction. A value of 100%
sets the angle of the particles to be parallel with the POmniFlect surface. A value of –100%
sets the angle perpendicular to the surface. The Distortion effect is reversed when particles
strike the POmniFlect from the back side.
 POmniFlect : SpacewarpObject 1029

<POmniFlect>.’refraction var’ Float default: 0.0 -- animatable;

percentage; alias: distortion_variation
Range of variation of the Distortion effect.
<POmniFlect>.Diffusion Float default: 0.0 -- animatable,
percentage
Applies a diffusion effect to the refraction by randomly modifying each particle’s
Distortion angle by the Diffusion angle. This effectively scatters the particles into a
hollow cone.
<POmniFlect>.’diffusion var’ Float default: 0.0 -- animatable;
percentage; alias: diffusion_variation
Range of variation of the Diffusion value.
<POmniFlect>.inheritVelocity Float default: 1.0 -- animatable;
alias: velocity_inheritance
Determines how much of a moving POmniFlect’s speed is applied to reflected or refracted
particles.
<POmniFlect>.spawn Float default: 100.0 -- animatable; percentage;
alias: spawn_percentage
The percentage of particles that can use spawn effects.
<POmniFlect>.Pass_Velocity Float default: 1.0 -- animatable
How much of the particle’s initial speed is maintained after passing through the
POmniFlect.
<POmniFlect>.Pass_Velocity_Variation Float default: 0.0 -- animatable,
percentage
The variation of the Pass Velocity setting applied to the range of particles.
<POmniFlect>.width Float default: 0.0 -- animatable
The width of the POmniFlect icon. This is for display purposes only and does not
influence the deflector effect.
<POmniFlect>.height Float default: 0.0 -- animatable
The height of the POmniFlect icon. This is for display purposes only and does not
influence the deflector effect.
Note:
getPropnames() and showProperties() show two sets of parameters called Pass_Velocity
and Pass_Velocity_Variation. The first set is for Refraction, the second for Spawn Effects Only
groups. Due to this sharing of property names, you cannot access the Spawn Effects Only
Pass_Velocity and Pass_Velocity_Variation using their property names. You can access the
value assigned to these parameters, and their controller if assigned, as subAnims 17 and 18 of the
base object.
Associated Methods:
bindSpaceWarp <particlesys_node> <POmniFlect_node>
1030 Chapter 11 | 3ds max Objects

Associated Binding Modifier:

POmniFlectMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SDeflector : SpacewarpObject
Constructor:
sdeflector ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<SDeflector>.friction Float default: 0.0 -- animatable
When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and
there’s no change in the particle behavior. As the friction value increases, particles begin to
rebound at incorrect angles and with greater speed.
<SDeflector>.collider UndefinedClass default: undefined -- max object
Node which particles deflect off of.
<SDeflector>.bounce Float default: 1.0 -- animatable
Determines the speed with which particles bounce off the deflector. At 1.0, the particles
bounce at the same speed as they approach. At 0, they don’t deflect at all.
<SDeflector>.bouncevar Float default: 0.0 -- animatable
The amount by which each particle can vary from the Bounce setting.
<SDeflector>.chaos Float default: 0.0 -- animatable
The amount of variation from the perfect angle of reflection (found when Chaos is set to
0.0). 100% induces a variation in reflection angle of up to 90 degrees
<SDeflector>.inheritVelocity Float default: 1.0 -- animatable; alias:
velocity_inheritance
When the value is greater than 0, the motion of the deflector affects particles as well as the
other settings. For example, to animate the SDeflector passing through a passive array of
particles, turn up this value to affect the particles.
<SDeflector>.radius Float default: 0.0 -- animatable
The diameter of the SDeflector icon. This setting also alters the effect of the deflection,
because particles bounce off the perimeter of the icon.
 SOmniFlect : SpacewarpObject 1031

Associated Methods:
bindSpaceWarp <particlesys_node> <sdeflector_node>

Associated Binding Modifier:

SDeflectMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SOmniFlect : SpacewarpObject
Constructor:
SOmniFlect ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<SOmniFlect>.’time on’ Integer default: 0 -- animatable; alias: time_on
Time at which the deflection starts.
<SOmniFlect>.’time off’ Integer default: 16000 -- animatable; alias:
time_off
Time at which the deflection ends.
<SOmniFlect>.affects Float default: 100.0 -- animatable, percentage;
alias: reflects
The percentage of particles to be reflected by the SOmniFlect.
<SOmniFlect>.bounce Float default: 1.0 -- animatable
This is a multiplier that specifies how much of the initial speed of the particle is
maintained after collision with the SOmniFlect. Using the default setting of 1.0 causes the
particle to rebound with the same speed as it collides. A real-world effect would usually be
less than 1.0. For a “flubber” effect, set greater than 1.0.
<SOmniFlect>.bouncevar Float default: 0.0 -- animatable, percentage;
alias: bounce_variation
The variation of Bounce applied to the range of particles.
<SOmniFlect>.chaos Float default: 0.0 -- animatable
Applies a random variation to the bounce angle. When set to 0.0 (no chaos), all particles
bounce off the SOmniFlect surface perfectly (like banking pool balls). A non-zero setting
causes the deflected particles to scatter.
1032 Chapter 11 | 3ds max Objects

<SOmniFlect>.Refracts Float default: 100.0 -- animatable,

percentage
The percentage of particles not already reflected that will be refracted by the SOmniFlect.
<SOmniFlect>.’pass velocity’ Float default: 1.0 -- animatable;
alias: pass_velocity
Defines how much of a particle’s initial speed is maintained after passing through the
SOmniFlect. The default setting of 1 retains the initial speed is retained, so there’s no
change. A setting of 0.5 reduces the speed by half.
<SOmniFlect>.’passvel var’ Float default: 0.0 -- animatable;
percentage; alias: pass_velocity_variation
Variation of the Pass Velocity setting applied to the range of particles.
<SOmniFlect>.refraction Float default: 50.0 -- animatable; percentage;
alias: distortion
Controls the angle of refraction. A value of 0 means there’s no refraction. A value of 100%
sets the angle of the particles to be parallel with the SOmniFlect surface. A value of –100%
sets the angle perpendicular to the surface. The Distortion effect is reversed when particles
strike the SOmniFlect from the back side.
<SOmniFlect>.’refraction var’ Float default: 0.0 -- animatable;
percentage; alias: distortion_variation
Range of variation of the Distortion effect.
<SOmniFlect>.Diffusion Float default: 0.0 -- animatable,
percentage
Applies a diffusion effect to the refraction by randomly modifying each particle’s
Distortion angle by the Diffusion angle. This effectively scatters the particles into a hollow
cone.
<SOmniFlect>.’diffusion var’ Float default: 0.0 -- animatable;
percentage; alias: diffusion_variation
Range of variation of the Diffusion value.
<SOmniFlect>.inheritVelocity Float default: 1.0 -- animatable; alias:
velocity_inheritance
Determines how much of a moving SOmniFlect’s speed is applied to reflected or refracted
particles.
<SOmniFlect>.deceleration Float default: 1.0 -- animatable
Sets the deceleration of particles.
<SOmniFlect>.’decel var’ Float default: 0.0 -- animatable; percentage
Sets the variation in deceleration of particles.
<SOmniFlect>.spawn Float default: 100.0 -- animatable; percentage;
alias: spawn_percentage
The percentage of particles that can use spawn effects.
<SOmniFlect>.friction Float default: 0.0 -- animatable; percentage
When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and
there’s no change in the particle behavior. As the friction value increases, particles begin to
rebound at incorrect angles and with greater speed.
 UDeflector : SpacewarpObject 1033

<SOmniFlect>.collider Undefined default: undefined -- max object

Node which particles deflect from.
<SOmniFlect>.radius Float default: 0.0 -- animatable
The radius of the SomniFlect icon.
Note:
getPropnames() and showProperties() show two sets of parameters called Pass_Velocity
and Pass_Velocity_Variation. The first set is for Refraction, the second for Spawn Effects Only
groups. Due to this sharing of property names, you cannot access the Spawn Effects Only
Pass_Velocity and Pass_Velocity_Variation using their property names. You can access the
value assigned to these parameters, and their controller if assigned, as subAnims 17 and 18 of the
base object.
Associated Methods:
bindSpaceWarp <particlesys_node> <SOmniFlect_node>

Associated Binding Modifier:

SOmniFlectMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

UDeflector : SpacewarpObject
Constructor:
uDeflector ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<UDeflector>.bounce Float default: 1.0 -- animatable
The speed with which particles bounce off the deflector. At 1.0, the particles bounce at the
same speed as they approach. At 0, they don’t deflect at all.
<UDeflector>.bouncevar Float default: 0.0 -- animatable
The amount by which each particle can vary from the Bounce setting.
<UDeflector>.chaos Float default: 0.0 -- animatable
The amount of variation from the perfect angle of reflection (found when Chaos is set to
0.0). 100% induces a variation in reflection angle of up to 90 degrees.
1034 Chapter 11 | 3ds max Objects

<UDeflector>.Friction Float default: 0.0 -- animatable, percentage

Determines the amount of tangential “stick” at the surface as particles bounce off the
deflector.
<UDeflector>.inheritVelocity Float default: 1.0 -- animatable; alias:
velocity_inheritance
When greater than 0, the motion of the deflector affects particles as well as the other
settings. For example, to animate the SDeflector passing through a passive array of
particles, increase this value to affect the particles.
<UDeflector>.radius Float default: 0.0 -- animatable; alias: icon_size
The size of the Udeflector icon.
<UDeflector>.collider Undefined default: undefined -- max object
Node which particles deflect from.
Note:
There is no way to set the Deflector object using MAXScript in 3ds max 4.
Associated Methods:
bindSpaceWarp <particlesys_node> <uDeflector_node>

Associated Binding Modifier:

UDeflectorMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

UOmniFlect : SpacewarpObject
Constructor:
UOmniFlect ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<UOmniFlect>.’time on’ Integer default: 0 -- animatable; alias: time_on
Time at which deflection starts.
<UOmniFlect>.’time off’ Integer default: 16000 -- animatable; alias:
time_off
Time at which deflection ends.
 UOmniFlect : SpacewarpObject 1035

<UOmniFlect>.affects Float default: 10000.0 -- animatable; percentage;

alias: reflects
Percentage of particles to be reflected by the UOmniFlect.
<UOmniFlect>.bounce Float default: 1.0 -- animatable
This multiplier specifies how much of the initial speed of the particle is maintained after
collision with the UOmniFlect.
<UOmniFlect>.bouncevar Float default: 0.0 -- animatable; percentage;
alias: bounce_variation
Specifies the variation of Bounce applied to the range of particles.
<UOmniFlect>.chaos Float default: 0.0 -- animatable
Applies a random variation to the bounce angle. When set to 0.0 (no chaos), all particles
bounce off the UOmniFlect surface perfectly (like banking pool balls). A non-zero setting
causes the deflected particles to scatter.
<UOmniFlect>.Refracts Float default: 100.0 -- animatable,
percentage
Specifies the percentage of particles not already reflected that will be refracted by the
UOmniFlect.
<UOmniFlect>.’pass velocity’ Float default: 1.0 -- animatable; alias:
pass_velocity
Specifies how much of a particle’s initial speed is maintained after passing through the
UOmniFlect.
<UOmniFlect>.’passvel var’ Float default: 0.0 -- animatable; percentage;
alias: pass_velocity_variation
Specifies the variation of Pass Velocity applied to the range of particles.
<UOmniFlect>.refraction Float default: 50.0 -- animatable; percentage;
alias: distortion
Controls the angle of refraction. A value of 0 means there’s no refraction. A value of 100%
sets the angle of the particles to be parallel with the UOmniFlect surface. A value of –100%
sets the angle perpendicular to the surface. The Distortion effect is reversed when particles
strike the UOmniFlect from the back side.
<UOmniFlect>.’refraction var’ Float default: 0.0 -- animatable;
percentage; alias: distortion_variation
Specifies a range of variation of the Distortion effect.
<UOmniFlect>.Diffusion Float default: 0.0 -- animatable,
percentage
Applies a diffusion effect to the refraction by randomly modifying each particle’s
Distortion angle by the Diffusion angle. This effectively scatters the particles into a hollow
cone.
<UOmniFlect>.’diffusion var’ Float default: 0.0 -- animatable;
percentage; alias: diffusion_variation
Specifies a range of variation of the Diffusion value.
1036 Chapter 11 | 3ds max Objects

<UOmniFlect>.Friction Float default: 0.0 -- animatable

When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and
there’s no change in the particle behavior. As the Friction value increases, particles begin
to rebound at incorrect angles and with greater speed.
<UOmniFlect>.inheritVelocity Float default: 1.0 -- animatable; alias:
velocity_inheritance
Determines how much of a moving UOmniFlect’s speed is applied to reflected or refracted
particles.
<UOmniFlect>.deceleration Float default: 1.0 -- animatable
The deceleration value for the particles.
<UOmniFlect>.’decel var’ Float default: 0.0 -- animatable; percentage
The range of variation in decelerations values.
<UOmniFlect>.spawn Float default: 100.0 -- animatable; percentage; alias:
spawn_percentage
Specifies the percentage of particles that can use spawn effects
<UOmniFlect>.Pass_Velocity Float default: 1.0 -- animatable
Specifies how much of the particle’s initial speed is maintained after passing through the
UOmniFlect.
<UOmniFlect>.Pass_Velocity_Variation Float default: 0.0 -- animatable,
percentage
Specifies the variation of the Pass Velocity setting applied to the range of particles.
<UOmniFlect>.radius Float default: 0.0 -- animatable; alias: icon_size
The size of the UOmniFlect icon.
<UOmniFlect>.collider UndefinedClass default: undefined -- max object
Node which particles deflect from.
Note:
getPropnames() and showProperties() show two sets of parameters called Pass_Velocity
and Pass_Velocity_Variation. The first set is for Refraction, the second for Spawn Effects Only
groups. Due to this sharing of property names, you cannot access the Spawn Effects Only
Pass_Velocity and Pass_Velocity_Variation using their property names. You can access the
value assigned to these parameters, and their controller if assigned, as subAnims 17 and 18 of the
base object.
Associated Methods:
bindSpaceWarp <particlesys_node> <UOmniFlect_node>

Associated Binding Modifier:

UOmniFlectMod
This modifier is automatically created by the bindSpaceWarp() method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.
 XRefObject : Node 1037

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

XRef Objects and Scenes

XRefObject : Node
A XRefObject value represents an XRef object in 3ds max. A XRefObject value is returned when the
xrefs.addNewXRefObject() function is called. There are two objects associated with an XRef
object in 3ds max – the non-proxy object and the proxy object. The proxy object is typically a lower
resolution object that is used as a standin for the non-proxy object in the viewports.
Constructor:
xrefs.addNewXRefObject <filename_string> <objectname_string> [#proxy]
Loads the specified node object from the specified scene file as an XRef object. The case of
objectname_string must match the object’s name in the scene file. If #proxy is
specified, the node object is loaded as the proxy object, otherwise it is loaded as the
non-proxy object.
The XRefObject is always loaded at world center.
Properties:
<XRefObject>.proxyFileName String default: varies
The file name of the proxy object.
<XRefObject>.fileName String default: varies
The file name of the non-proxy object.
<XRefObject>.currentFileName String default: varies
The file name of the non-proxy object if the useProxy property is false, the file name of
the proxy object if the useProxy property is true.
<XRefObject>.objectName String default: varies
The name of the proxy object.
<XRefObject>.proxyObjectName String default: varies
The name of the non-proxy object.
<XRefObject>.currentObjectName String default: varies
The name of the non-proxy object if the useProxy property is false, the name of the
proxy object if the useProxy property is true.
<XRefObject>.useProxy Boolean default: varies
If true, the proxy object will be displayed in the viewports, otherwise the non-proxy
object will be displayed. If the XRef object is added to the scene using the
xrefs.addNewXRefObject() method, this parameters default value will be true if
#proxy is specified, false otherwise.
1038 Chapter 11 | 3ds max Objects

<XRefObject>.renderProxy Boolean default: false

If true, the proxy object will be rendered, otherwise the non-proxy object will be
rendered.
<XRefObject>.updateMaterial Boolean default: false
If true, sets the Update Material option on.
<XRefObject>.ignoreAnimation Boolean default: false
If true, sets the Ignore Animation option on.
Methods:
updateXRef <XRefObject>
Reloads the XRef object.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

XRefScene Values
A XRefScene value represents a XRef Scene object in 3ds max. A XRefScene value is returned when
the xref.addNewXRefFile() and xref.getXRefFile() functions are called.
XRef Scene objects can be nested. For example, scene file A can contain an XRef Scene object
specifying XRef file B, and XRef file B can contain an XRef Scene object specifying XRef file C (eg: A
xrefs B, and B xrefs C). To provide access to the nested XRef scene objects, the applicable XRefScene
methods provide an optional root keyword parameter. If this argument is provided then these
methods act on the root node of the specified XRefScene value, otherwise they act on root node of
the current scene. To get to C from A, you load A and do something like:
bXref = xrefs.getXRefFile 1 -- taken from root node of current scene
cXref = xrefs.getXRefFile 1 root:bXref -- taken from root of bXref
cRoot = cXref.tree -- to get root of C

Constructor:
xrefs.addNewXRefFile <filename_string> [ #noLoad ] [root:<XRefScene>]
Adds a new XRef Scene object and returns a XRefScene value. If #noLoad is not specified,
the XRef Scene file is loaded immediately and the scene updated. If #noLoad is specified,
the scene is not updated until the user requests it. Use the updateXRef() method to load
the XRef Scene object.
If root:<XRefScene> is specified, the XRef Scene object is treated in the current file
during the current session as if it was an XRef Scene object in the file corresponding to the
XRefScene value specified. If the specified root XRef Scene object is reloaded, either
because the current scene was saved and then reloaded, or because updateXRef() was
executed on the root XRef Scene object, the XRef Scene object is deleted from the scene.
 XRefScene Values 1039

xrefs.getXRefFile <index> [root:<XRefScene>]

If root is not specified, returns the XRefScene value corresponding to the indexed XRef
Scene object in the XRef Scenes dialog. If the root:<XRefScene> is specified, the
XRefScene value corresponding to a nested XRef Scene object within the XRefScene’s XRef
Scene object is returned. The index is 1-based, and corresponds to the order of the XRef
Scene objects listed in the XRef Scenes dialog. You can use the
xrefs.getXRefFileCount() method to determine the number of XRef Scene objects in
the scene.
Properties:
<XRefScene>.filename String default: varies
The file name of the XRef Scene object. If you change this property to a new scene file
name, the objects in the specified file are displayed, replacing the objects from the initial
scene file.
<XRefScene>.tree Node
The root node of the XRef Scene object. This is a read-only property. You can access the
children objects in an XRef Scene object using this property. For example:
aXref=xrefs.getXRefFile 1 -- returns first XRef Scene object
aXref.tree.children -- objects in the XRef Scene object,
-- for example, may return:
-- #children($Box01, $Box02)
aXref.tree.children[1].width -- returns width value of $Box01

<XRefScene>.parent Node default: undefined

The parent of the XRef Scene object. By default this is undefined but can be set to any
node in the scene.
<XRefScene>.autoUpdate Boolean default: false
If true, automatic XRef file updating is on.
<XRefScene>.boxDisp Boolean default: false
If true, all nodes the in the XRef Scene object are displayed in Box display mode.
<XRefScene>.hidden Boolean default: false
If true, the XRef Scene object is hidden.
<XRefScene>.disabled Boolean default: false
If true, the XRef Scene object is disabled.
<XRefScene>.ignoreLights Boolean default: false
If true, the lights in the XRef Scene object will not be displayed.
<XRefScene>.ignoreCameras Boolean default: false
If true, the cameras in the XRef Scene object will not be displayed.
<XRefScene>.ignoreShapes Boolean default: false
If true, the shapes in the XRef Scene object will not be displayed.
<XRefScene>.ignoreHelpers Boolean default: false
If true, the helpers in the XRef Scene object will not be displayed.
<XRefScene>.ignoreAnimation Boolean default: false
If true, any animation in the XRef Scene object will be ignored.
1040 Chapter 11 | 3ds max Objects

Methods:
delete <XRefScene>
Deletes the XRef Scene object.
merge <XRefScene>
Merges the nodes in the XRef Scene object into the scene and deletes the XRef Scene
object.
updateXRef <XRefScene>
Tries to reload the XRef Scene object. Returns true if the operation is successful, false
otherwise.
flagChanged <XRefScene>
This method indicates that the specified XRef Scene object has been changed and should
be updated. Use the xrefs.updateChangedXRefs() method to update the changed
XRef Scene objects.
Associated Methods:
xrefs.getXRefFileCount [root:<XRefScene>]
If root is not specified, returns the total number of top-level XRef Scene objects in the
scene. If the root:<XRefScene> is specified, the total number of XRef Scene objects in
the nested XRef file within the XRefScene’s XRef file is returned.
xrefs.deleteAllXRefs [root:<XRefScene>]
If root is not specified, deletes all XRef Scene objects. If the root:<XRefScene> is
specified, only the specified XRefScene’s XRef Scene object, and its nested XRef Scene
objects, are deleted.
xrefs.updateChangedXRefs [#noRedraw] [root:<XRefScene>]
If root is not specified, updates all XRef Scene objects flagged as changed. If the
root:<XRefScene> is specified, only the specified XRefScene’s XRef Scene objects flagged
as changed are updated. If #noRedraw is specified, the viewports won’t be updated after
the XRef Scene objects are loaded. Returns true if the XRef Scene objects were loaded
okay, otherwise false.
xrefs.findUnresolvedXRefs [root:<XRefScene>]
If root is not specified, returns an array of file name strings for all the unresolved XRef
Scene objects. If the root:<XRefScene> is specified, only the unresolved XRef Scene
objects within the specified XRefScene’s XRef Scene object are returned.
xrefs.attemptUnresolvedXRefs [root:<XRefScene>]
If root is not specified, tries to load any XRef Scene objects that are currently unresolved.
If the root:<XRefScene> is specified, only the unresolved XRef Scene objects within the
specified XRefScene’s XRef Scene object are loaded.
 Editable_Mesh : GeometryClass and TriMesh : Value 1041

Editable Meshes, Splines, and Patches

Editable Meshes, Splines and Patches provide access to the basic components of meshes, splines, and
patches.
These classes are described in the following topics:
Editable_Mesh and TriMesh (p. 1041)
SplineShape (p. 1079)
Patch (p. 1088)

Editable_Mesh : GeometryClass and TriMesh : Value

Editable_Mesh is the class of node objects that are the result of collapsing a modifier stack to an
editable mesh object. Many of the mesh operations in MAXScript that modify meshes will only work
on Editable_Mesh scene nodes.
The TriMesh class is a MAXScript value wrapper for the low-level 3ds max SDK Mesh class used
extensively in mesh-based objects and modifiers in 3ds max. Meshes hold the actual vertex and face
arrays, and so on, in a triangular mesh. For example, an Editable_Mesh object contains an instance
of a Mesh. The prime purpose of the TriMesh class is to allow scripted primitive object plug-ins to
access and build the Mesh object inside geometry objects. This class has a large range of mesh
manipulation and construction functions, corresponding to the low-level mesh operations on
Editable Mesh scene nodes.
The properties and methods described in this topic are applicable to both Editable_Mesh objects and
TriMesh values are signified by a value type of <mesh>. The properties and methods applicable to
just TriMesh values are signified by a value type of <trimesh>.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Class and Object Inspector Functions (p. 799)
Scripting Vertex and Control Point Animation (p. 1461)
Note:
1. Only the update() function updates the mesh’s internal caches and images in 3ds max
viewports. This is because updates can be computationally expensive and you don’t want them
performed on every function call. However, you must make sure you do call the update()
function after a series of changes and before the mesh is to be worked on in 3ds max or by other
functions in MAXScript.
2. Coordinates are given in the MAXScript working coordinate system.
1042 Chapter 11 | 3ds max Objects

3. If the update() function is called on an object that is selected and currently open in the Modify
panel, it will drop the current selection in order to avoid a potential crash in 3ds max, which at
the moment, does not support scripted changes to an object open in the Modify panel.
4. If you are creating or modifying a mesh, and have not yet run update() on the mesh, 3ds max
will crash if you minimize and then maximize the 3ds max window. This is because an only
partially created mesh is created, and the internal 3ds max mesh structure is left in an unstable
state.
Constructors (Editable_Mesh):
mesh [ length:<integer> ] [ width:<integer> ] \
[ lengthsegs:<integer> ] [ widthsegs:<integer> ]
Creates a flat rectangular mesh with the given size and number of segments. The default
length and width are 50, the default number of segments is 5.
mesh [ numverts:<number> ] [ numfaces:<number> ]
Creates a mesh of the given geometry but with no topology (i.e., no faces or edges). You
have to individually place the vertices and create the faces from the vertices. The default
number of vertices and faces are 36 and 50, respectively.
mesh vertices:<array_of_point3s> \
faces:<array_of_point3s> \
[ materialIDs:<array_of_integers> ] \
[ tverts:<array_of_point3s> ]
Creates a mesh from an array of vertices and faces. Each Point3 value in the vertices
array specifies the position of the vertex in the current coordinate system. Each Point3
value in the faces array specifies the 3 vertex indices that form the face. The
materialIDs array specifies the material ID to be assigned to each face. Each Point3 value
in the tverts array specifies the UVW coordinates of the texture vertices. See Texture
Mapping in the methods section for more information on texture vertices.
An example of construction a mesh using this form of the constructor is:
mesh vertices:#([0,0,0],[10,0,0],[0,10,0],[10,10,0]) \
faces:#([1,2,3],[2,4,3]) materialIDS:#(1,2)

collapseStack <node> -- mapped

Collapses the object space modifiers out of a stack, leaving a resultant Editable Mesh as the
base object of the node. If there are no object space modifiers in the stack when this is
called, no action is taken. So, if you want to force an object to be an editable mesh (for
example, for the mesh operation listed below), you can apply a null modifier and then
collapse the stack:
addModifier $foo (normalModifier())
collapseStack $foo

collapseStack() does not collapse the effect of any world space modifiers (including
bindings to space warps). The world space modifiers remain on the object’s stack. To
collapse an object to a mesh use the snapshot() method.
 Editable_Mesh : GeometryClass and TriMesh : Value 1043

snapshot <node> -- mapped

This function provides functionality similar to the SnapShot tool in 3ds max. It generates
a new node that contains a copy of the world-state mesh of the source <node> at the time
that the snapshot is made. Any existing modifiers are collapsed out of the new node and
the mesh snapshot accounts for any space warps currently applied.
convertToMesh <node> -- mapped
Converts appropriate scene object types into Editable Meshes. It is similar to
collapseStack() in that it will remove all object space modifiers present, but unlike
collapseStack() it will always replace the base object with an editable mesh version,
even if there are no modifiers present.
It can be applied to any object that an Edit Mesh modifier can work on, such as geometry
and shapes, but not helpers, space warps, lights, etc.
convertTo <node> [ TriMeshGeometry | Mesh ] -- mapped
Converts appropriate scene object types into Editable Meshes. Operates in an identical
manner to convertToMesh().
Constructors (TriMesh):
TriMesh()
Creates an empty TriMesh. Use the methods listed below to build the mesh.
<node>.mesh
Extracts a copy of a node’s world state if it is convertible to a mesh.
<editable_mesh_baseobject>.mesh
Extracts a copy of base object’s mesh.
<trimesh>.mesh
Extracts a copy of another TriMesh’s mesh.
Note:
GeometryClass boolean operations (p. 852) also create editable_mesh objects.
Operators:
The following operators perform boolean operations on meshes. These operations destructively
modify the first operand mesh to contain the boolean result, as do the same boolean <node>
operations.
<mesh> + <mesh> -- union
<mesh> - <mesh> -- difference
<mesh> * <mesh> -- intersection

Properties:
<mesh>.numverts Integer
Get or set the number of vertices
<mesh>.numfaces Integer
Get or set the number of faces
<mesh>.numtverts Integer
Get or set the number of texture vertices
1044 Chapter 11 | 3ds max Objects

<mesh>.numcpvverts Integer
Get or set the number of color-per-vertex vertices
<mesh>.mesh TriMesh
Reading this property yields a copy of the mesh, taken from after any modifiers are
applied, but before any space warps are applied. Assigning to this property sets the mesh to
the TriMesh value given. You can use this property, along with copy() and the
<node_or_baseobject>.mesh property to build a TriMesh from other objects’ meshes.
The following properties are not applicable to TriMeshes:
<mesh>.selectedVerts VertexArray
Get the currently selected vertices of the Editable_Mesh object. See VertexSelection Values
(p. 786).
<mesh>.verts VertexArray
Get all of the vertices of the Editable_Mesh object. See VertexSelection Values (p. 786).
<mesh>.selectedFaces FaceArray
Get the currently selected faces of the Editable_Mesh object. See FaceSelection Values
(p. 788).
<mesh>.Faces FaceArray
Get all of the faces of the Editable_Mesh object. See FaceSelection Values (p. 788).
<mesh>.selectedEdges EdgeArray
Get the currently selected edges of the Editable_Mesh object. See EdgeSelection Values
(p. 790).
<mesh>.Edges EdgeArray
Get all of the edges of the Editable_Mesh object. See EdgeSelection Values (p. 790).
<mesh>.displacementMapping Boolean
Get or set whether to perform displacement mapping for the Editable_Mesh object. There
is no corresponding user interface element for this property.
<mesh>.subdivisionDisplacement Boolean
Get or set whether to perform subdivision displacement for the Editable_Mesh object. This
property corresponds to the Subdivision Displacement checkbox in the Surface Properties
rollout.
<mesh>.splitMesh Boolean
Get or set whether to split the mesh during subdivision displacement. This property
corresponds to the Split Mesh checkbox in the Surface Properties rollout. Setting this
property will enable subdivisionDisplacement if it is set to false.
You can both read and assign to the above properties with the exception of the properties that return
a VertexSelection, FaceSelection, or EdgeSelection. If you assign numbers to them to add room for
more vertices or faces, the mesh will lose all current topology/geometry (i.e., vertices, faces, and
edges), assuming you want to rebuild it from scratch. If you want to retain the current topology/
geometry, use the setNumVerts(), setNumTVerts() and setNumFaces() methods described
below.
 Editable_Mesh : GeometryClass and TriMesh : Value 1045

Up to N vertex coordinates are available as properties on Editable_Mesh objects, where N is the

number of vertices in the mesh. A vertex is available as a property once a controller has been
assigned to the vertex. Controllers can be assigned to vertices using the animateVertex() method
described in the Scripting Vertex and Control Point Animation (p. 1461) topic. For example, if a sphere
object is collapsed to an Editable_Mesh, and some of its vertices are animated, the properties for the
vertices would be similar to:
$Sphere01.vertex_209 Point3 value: [7.9,-40.0,0.0] -- animatable
$Sphere01.vertex_210 Point3 value: [-7.8,-39.3,-7.9] -- animatable
$Sphere01.vertex_211 Point3 value: [0.0,-40.0,-7.9] -- animatable

Methods:
The following methods operate on the base object in a node if no object space modifiers are present.
If object space modifiers are present, the mesh get operations access the world-state mesh, after the
object space modifiers have been applied. The mesh set operations only work on base object
Editable Meshes and signal an error if there are object space modifiers present, informing you that
the mesh is not changeable when modifiers are present. You can convert objects to Editable Meshes
with the collapseStack(), snapshot(), and convertToMesh() methods. If there are no object
space modifiers present, both get and set operations work on the base editable mesh object.
Because the mesh get operations require a mesh, the combination of base object and modifiers must
yield a mesh at the top of the modifier stack. This excludes combinations such as Patch base-objects
and deformer modifiers such as bend and twist, because they pass a patch object, not a mesh up the
stack. Applying an Edit Mesh modifier always forces the world-state object to be a mesh.
If world space modifiers are present, the mesh get operations access the world-state mesh, after any
object space modifiers have been applied, but before the world space modifiers have been applied.
Currently you can not access the position of vertices as affected by world space modifiers. The mesh
set operations will work if only world space modifiers are applied to the object. Setting a vertices
position in such a case will set it’s position before the world space modifiers have been applied. You
can create a new mesh object using the snapshot() method which accounts for the effects of world
space modifiers.
The update() method makes any scripted changes to a base object mesh visible to 3ds max and you
must call this function at some point after modifying a mesh so that 3ds max sees a valid mesh.
Because this update can be a compute-intensive operation, it is made available as a separate function
so you perform many changes on a mesh and then invoke the update just once to signal all the
changes to 3ds max.
All vertex and face indexes start at 1, following the other indexing conventions in MAXScript. All
coordinates used are relative to the current working coordinate system.
-- General Methods
update <mesh> [ geometry:<boolean> ] [ topology:<boolean> ] \
[ normals:<boolean> ] -- mapped
The three optional keyword arguments provide control over the kind of updating done to
the mesh. If the geometry: argument is true, the geometry cache is rebuilt (normals and
edge list) and the mesh’s bounding box is invalidated. If the topology: argument is true,
1046 Chapter 11 | 3ds max Objects

the edge and strip databases will be rebuilt. If normals: is true, the face normals are
computed. All flags default to true, so that a simple call to update() causes a complete
reconstruction of all the caches.
attach <mesh> <node>
Corresponds to the mesh attach function in the Editable Mesh Modify panel allowing you
to construct a mesh by adding complete objects to it. Extracts the mesh from <node> (first
converting to a mesh if need), adds it to <mesh> which must be an Editable Mesh object
and then deletes <node>. The materials and material IDs in <node> are merged into
<node> using the default settings for the attach operation in the Editable Mesh Modify
panel. This method is not applicable to TriMeshes.
meshop.attach {<target_editable_mesh_node> | <target_mesh>}
{<source_node> | <source_mesh>} \ targetNode:<node=unsupplied>
sourceNode:<node=unsupplied> \ attachMat:<{#neither | #MatToID |
#IDToMat}=#neither> condenseMat:<boolean=true> \ deleteSourceNode:<boolean=true>
Attaches the source mesh to the target mesh. If the target or source is specified as a mesh
rather than a node, the mesh is attached using the local coordinate system of the mesh,
and no material correction is performed. To get around this, if the target or source is a
mesh, the corresponding targetNode or sourceNode named parameter is checked to
see if a node is specified and, if it is, the transform and material for that node is used. If the
source or target is specified as a node, the corresponding targetNode or sourceNode
named parameter is not checked. The attachMat and condenseMat options correspond
to the attach options in editable mesh.
condenseMat is applicable only if attachMat:#IDToMat is specified. If
deleteSourceNode:false is not specified, and the source was specified as a node, or as
a mesh and a sourceNode was specified, the source node is deleted after the attach.
Examples:
meshop.attach $.baseobject $sphere02 targetNode:$
meshop.attach $box01 $box02 attachMat:#IDToMat
condenseMat:true deleteSourceNode:false

meshop.getUIParam <mesh> <param_name>

meshop.getUIParam <node> [ <modifier_or_index> ] <param_name>
meshop.setUIParam <mesh> <param_name> { <float> | <boolean> }
meshop.setUIParam <node> [ <modifier_or_index> ] <param_name> { <number> |
<boolean> }
Get/set a user-interface value. The optional <modifier_or_index> identifies the Edit
Mesh modifier on the given scene object to set the parameter value for. These methods are
UI-dependent, and require that the specified editable mesh or Edit Mesh modifier be
currently displayed in the Modify panel. The valid param_name values, their meaning,
and parameter value type are:
#SelByVertSelection - By Vertex (boolean)
#IgBackSelection - Ignore Backfacing (boolean)
#IgnoreVisSelection - Ignore Visibile Edges (boolean)
 Editable_Mesh : GeometryClass and TriMesh : Value 1047

#PolyThreshSelection - Planar Threshold (number)

#SoftSelSoft Selection - Use Soft Selection (boolean)
#SSUseEDistSoft Selection - Edge Distance (boolean)
#SSEDistSoft Selection - Edge Distance (number) [note: if value hasn’t been changed,
returns a value of 0]
#SSBackSoft Selection - Ignore Backfacing (boolean) [note: this is the inverse of the UI
element]
#FalloffSoft Selection - Falloff (number)
#PinchSoft Selection - Pinch (number)
#BubbleSoft Selection - Bubble (number)
#WeldDistWeld - Distance (number)
#WeldBoxSizeWeld - Box Size in Pixels (number)
#ExtrudeTypeExtrude/Chamfer (boolean) [note: true - Group; false - Local]
#ShowVNormalsShow Vertex Normals (boolean)
#ShowFNormalsShow Face Normals (boolean)
#NormalSizeNormal Scale (number)

Vertex methods
meshop.breakVerts <Mesh mesh> <vertlist>
For each vertex in <vertlist>, N-1 new vertices are created at the same location, where N
is the number of faces using that vertex. Each of these faces will use one of these vertices.
meshop.chamferVerts <Mesh mesh> <vertlist> <float amount>
Chamfers the specified vertices by the specified amount.
meshop.cloneVerts <Mesh mesh> <vertlist>
Clones the specified vertices.
meshop.cutVert <Mesh mesh> <int start_vert> <point3 destination> <point3 projdir>
node:<node=unsupplied>
If <mesh> is a node, or if <mesh> is an Editable Mesh and <node> is specified,
destination and projdir are in the current coordinate system context. If <mesh> is an
Editable Mesh and <node> is not specified, destination and projdir are in the mesh’s
local coordinate system.
Returns the index of the new vertex if created, or undefined if no vertex was created.
meshop.deleteIsoVerts <Mesh mesh>
Deletes all vertices not used by a face.
meshop.deleteVerts <Mesh mesh> <vertlist>
Deletes the specified vertices.
1048 Chapter 11 | 3ds max Objects

meshop.detachVerts <Mesh mesh> <vertlist> delete:<boolean=true>

asMesh:<boolean=false>
Detaches the faces used by the specified vertices. If <delete> is true, the faces are deleted
after being detached. If <delete> is false, the faces are not deleted. If <asMesh> is true,
the faces are detached and returned as a Mesh value. If <asMesh> is false, the faces are
detached as an element in the mesh and a value of OK is returned.
meshop.getHiddenVerts <Mesh mesh>
Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices that are hidden.
meshop.getIsoVerts <Mesh mesh>
Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices that are not used
by a face.
meshop.getNumVerts <Mesh mesh>
Returns the number of vertices in the mesh.
meshop.getVert <Mesh mesh> <int vertIndex> node:<node=unsupplied>
Returns the position of the specified vertex. If <mesh> is a node, or if <mesh> is an Editable
Mesh or a Mesh value and <node> is specified, the position returned is in the current
coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is
not specified, the return value is in the mesh’s local coordinate system.
meshop.getVertexAngles <Mesh mesh> <vertlist>
This method calculates, for each vertex, the sum of the angles of this vertex’s corner in
each face it’s on. So for instance, a point lying in the middle of a grid would always have
vertex angle 2*PI, whereas a corner of a box would only have 270. Returns an array of
size=(#vertices in mesh). The array element for any vertices not specified in <vertlist>
will contain the value 0.
meshop.getVertsByColor <Mesh mesh> <color color> <float red_thresh> <float
green_thresh> <float blue_thresh> channel:<int=0>
Returns the vertices whose vertex color is within the color range as a <bitarray>. The
range values shouldbe in the range of 0 to 255.
meshop.getVertsByColor <Mesh mesh> <point3 uvw> <Float u_thresh> <Float v_thresh>
<Float w_thresh> channel:<int=0>
Returns the vertices whose vertex UVW is within the UVW range as a <bitarray>. The
range values shouldbe in the range of 0 to 1.
meshop.makeVertsPlanar <Mesh mesh> <vertlist>
Moves the specified vertices so that they are planar.
meshop.minVertexDistanceFrom <Mesh mesh> <int vertIndex> <vertlist>
Returns the minimal distance from <vertIndex> to the vertices specified in <vertlist>.
 Editable_Mesh : GeometryClass and TriMesh : Value 1049

meshop.minVertexDistancesFrom <Mesh mesh> <vertlist> <int iterations>

This function computes distances from selected vertices (as indicated by <vertlist>) to
non-selected ones along edge paths. Returns an array of size=(#vertices in mesh). Each
element in this array is set to -1 if there is no selection. Otherwise, selected vertices have
an array element value of 0; non-selected vertices that are <iterations> or fewer edges
away from a selected vertex are assigned the shortest edge-path distance to a selected
vertex; and non-selected vertices that are more than <iterations> edges away are set
to -1. If <iterations> is 0, the distances are computed from each vertex to the nearest
selected vertex, regardless of topology. This is a VERY EXPENSIVE ALGORITHM, which
takes almost 4 times as long for twice as many vertices. If <iterations> is non-zero, it
represents the number of edges one should “travel” in trying to find the nearest selected
vertex -- this means that it only takes twice as long for twice as many verts. (This is like the
Edge Distance parameter in EMesh’s Soft Selection dialog.)
meshop.moveVert <Mesh mesh> <vertlist> <point3 offset> node:<node=unsupplied>
Moves the specified vertices by <offset>. If <mesh> is a node, or if <mesh> is an Editable
Mesh or a Mesh value and <node> is specified, the offset is in the current coordinate
system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not
specified, the offset is in the mesh’s local coordinate system.
meshop.moveVertsToPlane <Mesh mesh> <vertlist> <point3 normal> <float offset>
node:<node=unsupplied>
Moves the specified vertices into the specified plane. The target plane is defined as all
points which, when DotProd’d with N, return offset. All vertices are moved along the
normal vector N. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value
and <node> is specified, the normal is in the current coordinate system context. If <mesh>
is an Editable Mesh or a Mesh value and <node> is not specified, the normal is in the
mesh’s local coordinate system.
meshop.setHiddenVerts <Mesh mesh> <vertlist>
Sets the specified vertices as hidden, and non-specified vertices as visible.
meshop.setNumVerts <Mesh mesh> <int>
Sets the number of vertices in the mesh. Any new vertices are created at [0,0,0] in the
mesh’s local coordinate system.
meshop.setVert <Mesh mesh> <vertlist> <point3 pos> node:<node=unsupplied>
Moves the specified vertices to the specified position. If <mesh> is a node, or if <mesh> is
an Editable Mesh or a Mesh value and <node> is specified, the position is in the current
coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is
not specified, the position is in the mesh’s local coordinate system.
meshop.setVertColor <Mesh mesh> <int mapChannel> <vertlist> <Color color>
Sets the vertex color for the specified vertices in the specified <mapChannel>.
meshop.weldVertsByThreshold <Mesh mesh> <vertlist> <float threshold>
Welds the specified vertices that are within the threshold distance.
1050 Chapter 11 | 3ds max Objects

meshop.weldVerts - renamed to weldVertSet

meshop.weldVertSet <Mesh mesh> <vertlist> weldpoint:<point3=unsupplied>
node:<node=unsupplied>
Welds the specified vertices. If <weldpoint> is specified, the resulting vertex is positioned
at that point. The result is put at the average location of the selected vertices. If <mesh> is
a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the
position is in the current coordinate system context. If <mesh> is an Editable Mesh or a
Mesh value and <node> is not specified, the position is in the mesh’s local coordinate
system. If <weldpoint> is not specified, the resulting vertex is positioned at the average
location of the specified vertices.

Vertex data methods

meshop.setNumVDataChannels <Mesh mesh> <Integer count> keep:<boolean=false>]
Sets the number of vertex data channels available. The number of vertex data channels can
be set from 0 to 100. The first ten channels are for Discreet’s use only. If keep is false or
not specified, the old channel data is discarded. If true, the old channel data is retained
after the resize. The predefined channels are:
channel 1: Soft Selection
channel 2: Vertex weights (for NURMS MeshSmooth)
channel 3: Vertex Alpha values
channel 4: Cornering values for subdivision use
meshop.getNumVDataChannels <Mesh mesh>
Returns the number of vertex data channels available as an <integer>.
meshop.setVDataChannelSupport <Mesh mesh> <Integer vdChannel> <Boolean support>
Sets whether the specified vertex data channel is supported or not. If support is true,
and thechannel support state is currently false, a new vertex data array of the same size
as the number of vertices in the mesh is allocated. If support is false, and the channel
support state is currently true, the existing vertex data channel array is deallocated. If
support and the current channel support state are both the same, no action is
performed. setNumVDataChannels() is automatically called if the specified vertex data
channel is not available. vdChannel index values are 1-based, with channels 1 and 2
being the Vertex Soft Selection and Vertex Weight channels.
meshop.getVDataChannelSupport <Mesh mesh> <Integer vdChannel>
Returns whether the specified vertex data channel is supported.
meshop.getVDataValue <Mesh mesh> <Integer vdChannel> <Integer vert_index>
Returns the floating point data value associated with vertex vert_index in vertex data
channel vdChannel as a <float>.
meshop.setVDataValue <Mesh mesh> <Integer vdChannel> <Integer vert_index> <Float
value>
Sets the floating point data value associated with vertex vert_index in vertex data
channel vdChannel.
 Editable_Mesh : GeometryClass and TriMesh : Value 1051

meshop.freeVData <Mesh mesh> <Integer vdChannel>

Deallocates the existing vertex data channel array and turns off the vertex data channel
support state.

Edge methods
meshop.chamferEdges <Mesh mesh> <edgelist> <float amount>
Chamfers the specified edges by the specified amount.
meshop.cloneEdges <Mesh mesh> <edgelist>
Clones the specified edges.
meshop.collapseEdges <Mesh mesh> <edgelist>
Collapses the specified edges.
meshop.cutEdge <Mesh mesh> <int edge1> <float prop1> <int edge2> <float prop2>
<point3 projdir> node:<node=unsupplied>
If <mesh> is a node, or if <mesh> is an Editable Mesh and <node> is specified, projdir is
in the current coordinate system context. If <mesh> is an Editable Mesh and <node> is not
specified, projdir is in the mesh’s local coordinate system.
Returns the index of the new vertex if created, or undefined if no vertex was created.
meshop.deleteEdges <Mesh mesh> <edgelist> delIsoVerts:<boolean=true>
Deletes the specified edges. If <delIsoVerts> is true, any isolated vertices are deleted.
meshop.divideEdge <Mesh mesh> <int edgeIndex> <float edgef>
visDiag1:<boolean=false> visDiag2:<boolean=false> fixNeighbors:<boolean=true>
split:<boolean=false>
Divides the specified edge at a fractional distance of <edgef> along its length.
<visDiag1> and <visDiag2> specify whether each of the two new edges will be visible.
If <fixNeighbors> is true, the face on the other side of this edge, that is, the “reverse
face”, should be divided as well to prevent the introduction of a seam. If <split> is true,
separate vertices for the two halves of the edge will be created, splitting the mesh open
along the diagonal(s).
meshop.divideEdges <Mesh mesh> <edgelist>
Divides all the specified edges in half, creating new points and subdividing faces.
meshop.edgeTessellate <Mesh mesh> <facelist> <float tension>
Tessellates the specified edges. This algorithm is exactly the one used in the Tessellate
modifier, when operating on Faces and Edge SO elements.
<tension> specifies the tension for the edge tessellation. This value should be fairly small,
between 0 and .5, and corresponds to the value in the Tessellate, Edit Mesh, or Editable
Mesh UI’s divided by 400.
meshop.extrudeEdges <Mesh mesh> <edgelist> <float height> dir:<{<point3 dir> |
#independent | #common}=#independent> node:<node=unsupplied>
Creates new edges corresponding to the specified edges, and then moves the new edges by
<height>. The direction the edges are moved is determined by <dir>. If <dir> is a
point3 value, the edges will be moved in that direction. (If <mesh> is a node, or if <mesh>
is an Editable Mesh or a Mesh value and <node> is specified, the direction is in the current
1052 Chapter 11 | 3ds max Objects

coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is
not specified, the direction is in the mesh’s local coordinate system.) If
dir:#independent is specified, the edges are moved based on the normals of the faces
using the edge. If dir:#common is specified, the edges are moved based on the normals of
the face clusters using the edge.
meshop.getEdgesUsingVert <Mesh mesh> <vertlist>
Returns a bitarray of size=(#edges in mesh) with bits set for all edges that use the specified
vertices.
meshop.getOpenEdges <Mesh mesh>
Returns a bitarray of size=(#edges in mesh) with bits set for all edges that are used by a
single face.
meshop.turnEdges - renamed to turnEdge, still showing in index
meshop.turnEdge <Mesh mesh> <int edgeIndex>
Turns the specified edge. Only works on edges that have a face on both sides. These two
faces are considered as a quad, where this edge is the diagonal, and remapped so that the
diagonal flows the other way, between the vertices that were opposite this edge on each
face.

Face methods
meshop.bevelFaces <Mesh mesh> <facelist> <float height> <float outline>
dir:<{<point3 dir> | #independent |
#common}=#independent> node:<node=unsupplied>
Moves the specified faces by <height> and outlines them by <outline>. The direction
the faces are moved is determined by <dir>. If <dir> is a point3 value, the faces will be
moved in that direction. (If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh
value and <node> is specified, the direction is in the current coordinate system context. If
<mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the direction is
in the mesh’s local coordinate system.) If dir:#independent is specified, the faces are
moved based on the individual face normals. If dir:#common is specified, the faces are
moved based on the face cluster normals.
meshop.cloneFaces <Mesh mesh> <facelist>
Clones the specified faces.
meshop.collapseFaces <Mesh mesh> <facelist>
Collapses the specified faces.
meshop.cutFace <Mesh mesh> <int face> <point3 start> <point3 destination> <point3
projdir> node:<node=unsupplied>
If <mesh> is a node, or if <mesh> is an Editable Mesh and <node> is specified, start,
destination, and projdir are in the current coordinate system context. If <mesh> is an
Editable Mesh and <node> is not specified, start, destination, and projdir are in the
mesh’s local coordinate system.
Returns the index of the new vertex if created, or undefined if no vertex was created.
 Editable_Mesh : GeometryClass and TriMesh : Value 1053

meshop.deleteFaces <Mesh mesh> <facelist> delIsoVerts:<boolean=true>

Deletes the specified faces. If <delIsoVerts> is true, any isolated vertices are deleted.
meshop.detachFaces <Mesh mesh> <facelist> delete:<boolean=true>
asMesh:<boolean=false>
Detaches the specified faces. If <delete> is true, the faces are deleted after being
detached. If <delete> is false, the faces are not deleted. If <asMesh> is true, the faces
are detached and returned as a Mesh value. If <asMesh> is false, the faces are detached as
an element in the mesh and a value of OK is returned.
meshop.divideFace <Mesh mesh> <int faceIndex> baryCoord:<point3=unsupplied>
Divides the specified face. If <baryCoord> is specified, the new vertex will be created at
the corresponding position. If <baryCoord> is not specified, the new vertex will be
created at the center of the face.
meshop.divideFaceByEdges <Mesh mesh> <int faceIndex> <int edge1Index> <float
edge1f> <int edge2Index> <float edge2f> fixNeighbors:<boolean=true>
split:<boolean=false>
Divides the specifed face. New vertices are created on the specified edges at the specified
fractional distance along their length. If <fixNeighbors> is true, the face on the other
side of the edges, that is, the “reverse faces”, should be divided as well to prevent the
introduction of a seam. If <split> is true, separate vertices for the two halves of the edges
will be created, splitting the mesh open along the diagonal(s).
meshop.divideFaces <Mesh mesh> <facelist>
Divides the specified faces, with new vertices created at the center of the faces.
meshop.explodeAllFaces <Mesh mesh> <float threshold>
“Explodes” the mesh into separate elements.
<threshold> specifies the angle between faces that indicates whether they should be in
the same or different element.
meshop.explodeFaces <Mesh mesh> <facelist> <float threshold>
“Explodes” the specified faces into separate elements.
<threshold> specifies the angle between faces that indicates whether they should be in
the same or different element.
meshop.extrudeFaces <Mesh mesh> <facelist> <float height> <float outline>
dir:<{<point3 dir> | #independent | #common}=#independent> node:<node=unsupplied>
Creates new faces corresponding to the specified faces, and then moves the new faces by
<height> and outlines them by <outline>. The direction the faces are moved is
determined by <dir>. If <dir> is a point3 value, the faces will be moved in that direction.
(If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is
specified, the direction is in the current coordinate system context. If <mesh> is an
Editable Mesh or a Mesh value and <node> is not specified, the direction is in the mesh’s
local coordinate system.) If dir:#independent is specified, the faces are moved based on
the individual face normals. If dir:#common is specified, the faces are moved based on the
face cluster normals.
1054 Chapter 11 | 3ds max Objects

meshop.getBaryCoords <Mesh mesh> <int faceIndex> <point3 pos>

node:<node=unsupplied>
The barycentric coordinates of the specified point in the plane of the specified face,
relative to the face. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value
and <node> is specified, the position is in the current coordinate system context. If
<mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in
the mesh’s local coordinate system.
meshop.getElementsUsingFace <Mesh mesh> <facelist> fence:<facelist=unsupplied>
Returns a bitarray of size=(#faces in mesh) with bits set for all faces in elements where at
least one face in the element is specified in <facelist>. If <fence> is specified, its faces
are considered as barriers to the element and are not processed.
meshop.getFaceCenter <Mesh mesh> <int faceIndex> node:<node=unsupplied>
Returns the face center of the specified face. If <mesh> is a node, or if <mesh> is an
Editable Mesh or a Mesh value and <node> is specified, the position is in the current
coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is
not specified, the position is in the mesh’s local coordinate system.
meshop.getFaceRNormals <Mesh mesh> <int faceIndex> node:<node=unsupplied>
Returns a three element array of the render normals for the face’s three vertices. If <mesh>
is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the
position is in the current coordinate system context. If <mesh> is an Editable Mesh or a
Mesh value and <node> is not specified, the position is in the mesh’s local coordinate
system.
meshop.getFacesUsingVert <Mesh mesh> <vertlist>
Returns a bitarray of size=(#faces in mesh) with bits set for all faces that use the specified
vertices.
meshop.getHiddenFaces <Mesh mesh>
Returns a bitarray of size=(#faces in mesh) with bits set for all faces that are hidden.
meshop.getNumFaces <Mesh mesh>
Returns the number of faces in the mesh.
meshop.getVertsUsedOnlyByFaces <Mesh mesh> <facelist>
Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices used by the
specified faces.
meshop.makeFacesPlanar <Mesh mesh> <facelist>
Moves the specified faces so that they are planar.
meshop.removeDegenerateFaces <Mesh mesh>
Deletes any degenerate faces in the mesh. A degenerate face has two or more equal vertex
indices.
 Editable_Mesh : GeometryClass and TriMesh : Value 1055

meshop.removeIllegalFaces <Mesh mesh>

Deletes any illegal faces in the mesh. An illegal face has one or more vertex indices that are
out of range.
meshop.setHiddenFaces <Mesh mesh> <facelist>
Sets the specified faces as hidden, and non-specified faces as visible.
meshop.setNumFaces <Mesh mesh> <int>
Sets the number of faces in the mesh.

Mesh methods
meshop.createPolygon <Mesh mesh> <vertIndex array> smGroup:<int=0> matID:<int=1>
Creates a set of faces using the specified vertices. The order of the vertices in the faces is
the order in the vertex array. The polygon may be nonconvex, but should be (roughly)
coplanar.
<smGroup> and <matID> specify the smoothing group data and material ID number
assigned to the new faces.
meshop.cut <Mesh mesh> <int edge1Index> <float edge1f> <int edge2Index> <float
edge2f> <point3 normal> fixNeighbors:<boolean=true> split:<boolean=true>
node:<node=unsupplied>
Cuts the mesh from a point on one edge to a point on another, along a line drawn by
looking at the mesh from a particular viewpoint.
<edge1Index> specifies the edge that the cut starts on.
<edge1f> specifies the fractional distance along the edge to start the cut from.
<edge2Index> specifies the edge that the cut ends on.
<edge2f> specifies the fractional distance along the edge to finish the cut on.
<normal> specifies the direction of view. The cut will take place on this “side” of the
mesh, in the plane formed by this vector and the direction from the start to the end.
If <fixNeighbors> is true, the faces on the other side of each end of the cut should be
split to prevent splits at the ends. If <split> is true, the cut will split the mesh apart. If
false, the cut will just refine the mesh by adding geometry. If <mesh> is a node, or if
<mesh> is an Editable Mesh or a Mesh value and <node> is specified, the normal is in the
current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and
<node> is not specified, the normal is in the mesh’s local coordinate system.
meshop.getPolysUsingVert <Mesh mesh> <vertlist> ignoreVisEdges:<boolean=false>
threshhold:<float=45.>
Returns a bitarray of size=(#faces in mesh) with bits set for all faces that are in ‘polygons’
containing the specified vertices. The definition of a polygon is all faces sharing invisible
edges with edge angles below the threshhold angle. The default threshhold angle is 45
degrees. If ignoreVisEdges is set to true, the edge visibility is ignored but the threshhold is
still relevant.
1056 Chapter 11 | 3ds max Objects

meshop.optimize <Mesh mesh> <float normalThreshold> <float edgeThreshold> <float

bias> <float maxEdge> saveMatBoundries:<boolean=true>
saveSmoothBoundries:<boolean=true> autoEdge:<boolean=true>
Reduces the mesh in complexity by reducing the number of faces based on a surface
normal threshold. Adjacent faces whose difference in surface normal angle falls below
<normalThreshold> will be collapsed into a single triangle. If <autoEdge> is true, when
the angle between adjacent surface normals is less than <edgeThreshold> the edge will
be invisible. When optimizing mesh objects, as the optimization increases, you can get
lots of long skinny ‘degenerate’ triangles (that cause rendering artifacts). Increasing
<bias> keeps triangles from becoming degenerate. The range of values is from 0 to 1
(where 0 turns bias off). Values close to 1 reduce the amount of optimization in favor of
maintaining equilateral triangles. A <maxEdge> value > 0 will prevent the optimize
function from creating edges longer than this value. If this parameter is <=0 no limit is
placed on the length of the edges. If <saveMatBoundries> is true, faces won’t be
collapsed across a material boundary. If <saveSmoothBoundries> is true, faces won’t be
collapsed across a dissimilar smoothing group boundary.
meshop.slice <Mesh mesh> <facelist> <point3 normal> <float offset>
separate:<boolean=false> delete:<boolean=false> node:<node=unsupplied>
Slices the mesh along the specified slicing plane. The slicing plane is defined as all points
which, when DotProd’d with <normal>, return <offset>. <normal> should be
normalized.
<separate> specifies whether the slice should separate the mesh into two separate
elements (true) or just refine the existing mesh by splitting faces (false).
<delete> specifies whether the slice should remove the portion of the mesh “below” the
slicing plane, where “below” is defined as the area where DotProd (p,<normal>) - <offset>
< 0. If <delete> is true, <separate> is ignored. If <mesh> is a node, or if <mesh> is an
Editable Mesh or a Mesh value and <node> is specified, the normal is in the current
coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is
not specified, the normal is in the mesh’s local coordinate system.
copy <trimesh>
Yields a copy of the source TriMesh.
delete <trimesh>
Clears out the TriMesh’s geometry and topology, effectively freeing its memory.
The following method is not applicable to TriMeshes:
animateVertex <mesh> <vertex_spec>
Applies controllers to the specified vertices of the Editable_Mesh, where <vertex_spec>
is one of:
<integer_index>
<integer_index_array>
#all
 Editable_Mesh : GeometryClass and TriMesh : Value 1057

By assigning controllers to the vertices, the vertices are added to the Master subAnim and
appear as animatables in the Track View, allowing further scripting of the vertices. For
example,
animateVertex $Sphere01 #all

The vertices to be animated are specified by index number or with the keyword #all to
animate all vertices.
See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point
Animation (p. 1461) for details on accessing the Editable_Mesh vertices. The controller
values assigned to the vertices is in object space. See the Using Node Transform Properties
(p. 843) topic for information on converting between world space to object space.
The setMesh() method enables bulk changes to a mesh via arrays of vertices, faces, tverts, etc.
setMesh() has the following forms:
setMesh <mesh> [ numverts:<integer> ] [ numfaces:<integer> ]
Resets the mesh to the given geometry but with no topology (i.e., no faces or edges). Any
current mesh data is lost. You have to individually place the vertices and create the faces
from the vertices. The default number of vertices and faces are 36 and 50, respectively.
setMesh <mesh> [ vertices:<array_of_point3s> ] \
[ faces:<array_of_point3s> ] \
[ materialIDs:<array_of_integers> ] \
[ tverts:<array_of_point3s> ]
Resets the mesh based on the given arrays. Only those portions of the mesh that are
specified are reset. For example, if only the vertices parameter is specified, the existing
face data is retained. Each Point3 value in the vertices array specifies the position of the
vertex in the current coordinate system. Each Point3 value in the faces array specifies the
3 vertex indices that form the face. The materialIDs array specifies the material ID to be
assigned to each face. Each Point3 value in the tverts array specifies the UVW
coordinates of the texture vertices. See Texture Mapping in the methods section for more
information on texture vertices.
setMesh <mesh> [ length:<integer> ] [ width:<integer> ] [ lengthsegs:<integer> ] \
[ widthhsegs:<integer> ]
Resets the mesh with a flat rectangular mesh with the given size and number of segments.
The default length and width are 50, the default number of segments is 5.
setMesh <mesh> <trimesh>
Sets the mesh to a copy of the source TriMesh.

Mapping methods – General

meshop.deleteIsoMapVertsAll <Mesh mesh>
For all mapping channels, deletes all mapping vertices that are not used by a mapping
face.
meshop.freeMapChannel <Mesh mesh> <int mapChannel>
Deletes the map vertex and face arrays for the specified channel, and sets their count to 0.
1058 Chapter 11 | 3ds max Objects

meshop.getMapFacesUsingMapVert <Mesh mesh> <int mapChannel> <mapVertlist>

Returns a bitarray of size=(#map faces for channel in mesh) with bits set for all map faces
that use the specified map vertices.
meshop.getMapVertsUsingMapFace <Mesh mesh> <int mapChannel> <mapFacelist>
Returns a bitarray of size=(#map vertices for channel in mesh) with bits set for all map
vertices that use the specified map faces.
meshop.setFaceAlpha <Mesh mesh> <int mapChannel> <facelist> <float alpha>
For the specified map channel, sets the map vertex color to (color <alpha> <alpha>
<alpha>) for the map vertices used by the map faces associated with the specified faces.
meshop.setFaceColor <Mesh mesh> <int mapChannel> <facelist> <color color>
For the specified map channel, sets the map vertex color to <color> for the map vertices
used by the map faces associated with the specified faces.
meshop.setVertAlpha <Mesh mesh> <int mapChannel> <vertlist> <float alpha>
For the specified map channel, sets the map vertex color to (color <alpha> <alpha>
<alpha>) for the specified map vertices.
meshop.setVertColor <Mesh mesh> <int mapChannel> <vertlist> <color color>
For the specified map channel, sets the map vertex color to <color> for the specified map
vertices.
meshop.setNumMaps <Mesh mesh> <int count> keep:<boolean=false>
Sets the number of map channels available. The number of map channels can be set from
2 to 100. Map channels 1 and 2 are the Vertex Color and default Texture Map channels. If
keep is false, the old mapping information is discarded. If true, the old mapping
information is retained after the resize.
meshop.getNumMaps <Mesh mesh>
Returns the number of map channels available as an <integer>.
meshop.setMapSupport <Mesh mesh> <Integer mapChannel> <Boolean support>
Sets whether the specified mapping channel is supported or not. If support is true, and
the channel support state is currently false, a new map face array of the same size as
the number of faces in the mesh is allocated, but no map vertex array is allocated. If
support is false, and the channel support state is currently true, existing map channel
face and vertex arrays are deallocated. If support and the current channel support state
are both the same, no action is performed. SetNumMaps() is automatically called if the
specified map channel is not available.
mapChannel index values are 0-based, with Map channels 0 and 1 being the Vertex Color
and default Texture Map channels.
meshop.getMapSupport <Mesh mesh> <Integer mapChannel>
Returns whether the specified map channel is supported. This signifies that a map face
arrayis present, but not necessarily a map vertex array.
 Editable_Mesh : GeometryClass and TriMesh : Value 1059

meshop.setNumMapVerts <Mesh mesh> <Integer mapChannel> <Integer count>

keep:<boolean=FALSE>
Sets the number of vertices for the map channel, initializing the map vertex array. If keep
is false or not specified, the old map vertex information is discarded. If true, the old
map vertex information is retained after the resize.
meshop.getNumMapVerts <Mesh mesh> <Integer mapChannel>
Returns the number of vertices for the map channel as an <integer>.
meshop.setNumMapFaces <Mesh mesh> <Integer mapChannel> <Integer count>
keep:<boolean=false> keepCount:<int=0>
Sets the number of faces for the map channel. If keep is false or not specified, the old
map face information is discarded. If true, the old map face information from the
number of faces specified by keepCount is retained after the resize. Dangerous to use with
map channels 0 and 1, so miminum mapChannel value is 2.
meshop.getNumMapFaces <Mesh mesh> <Integer mapChannel>
Returns the number of faces for the map channel as an <integer>.
meshop.setMapVert <Mesh mesh> <Integer mapChannel> <Integer index> <Point3 xyz>
Sets the coordinates of the specified map vertex.
meshop.getMapVert <Mesh mesh> <Integer mapChannel> <Integer index>
Returns the coordinates of the specified map vertex as a <point3>.
meshop.setMapFace <Mesh mesh> <Integer mapChannel> <Integer index> <Point3 face>
Sets the map vertices for the specified map face.
meshop.getMapFace <Mesh mesh> <Integer mapChannel> <Integer index>
Returns the vertices of the specified map face as a <point3>.
meshop.makeMapPlanar <Mesh mesh> <Integer mapChannel>
Applies a simple planar mapping to the specified channel. This is done by copying the
mesh topology and vertex locations into the map, resizing the face and vertex arrays if
necessary.
meshop.getIsoMapVerts <Mesh mesh> <Integer mapChannel>
Returns a <bitarray> with a bit set for each isolated map vertex (unrefereced by any map
face) for the specified channel.
meshop.deleteMapVertSet <Mesh mesh> <Integer mapChannel> {<BitArray set> | <Integer
index> | <integer array>}
Deletes the specified map vertices. Returns a <bitarray> with a bit set for each map face
that used one of the deleted map vertices. Normally, you should delete or modify the map
faces using the map vertices before deleting the map vertices, as after the vertex deletion
you can’t tell which vertex on a face was a vertex that was deleted.
meshop.freeMapVerts <Mesh mesh> <Integer mapChannel>
Deallocates the map vertex array and sets the number of map vertices to 0.
meshop.freeMapFaces <Mesh mesh> <Integer mapChannel>
Deallocates the map face array and sets the number of map faces to 0.
1060 Chapter 11 | 3ds max Objects

meshop.applyUVWMap <TriMesh mesh> {<#planar | #cylindrical | #spherical | #ball |

#box> | <#face>} \ utile:<float=1.0> vtile:<float=1.0> wtile:<float=1.0>
uflip:<boolean=false> vflip:<boolean=false> wflip:<boolean=false>
cap:<boolean=true> tm:<Matrix3=identity matrix>
channel:<int=1>
Applies the specified mapping type to the mapping channel.
utile/vtile/wtile - Number of tiles in the U/V/W directions.
uflip/vflip/wflip - U/V/W are mirrored if true.
cap - used with #cylindrical. If true, then any face normal that is pointing more
vertically than horizontally will be mapped using planar coordinates.
tm - defines the mapping space. As each point is mapped, it is multiplied by this
matrix, and then it is mapped.
channel - the mapping channel the mappingis applied to, defaults to channel 1.
meshop.buildMapFaces <Mesh mesh> <Integer mapChannel> <Boolean keep>
Sets the number of map faces to the number of mesh faces, retaining existing mapping
data if keep is true. Deletes any map vertices that are not used by the map faces.
meshop.defaultMapFaces <Mesh mesh> <Integer mapChannel> <Integer count>
Sets the number of map faces to the number of mesh faces, and the number of map
vertices to the number of mesh vertices. The map face vertices are set to the same vertex
index as the corresponding mesh face vertices (i.e., there will be a 1-to-1 correspondence
between map faces/vertices and the mesh faces/vertices). The map vertex UVW
coordinates are set to the normalized (0 to 1) position of the corresponding mesh vertex in
the mesh’s bounding box.

Mapping methods – Color per vertex channel (Channel 0)

meshop.getNumCPVVerts <Mesh mesh>
Returns the number of Color Per Vertex mapping channel vertices.
meshop.setNumCPVVerts <Mesh mesh> <int>
Sets the number of Color Per Vertex mapping channel vertices.

Mapping methods – Default texture mapping channel (Channel 1)

meshop.getNumTVerts <Mesh mesh>
Returns the number of Default Texture mapping channel vertices.
meshop.setNumTVerts <Mesh mesh> <int>
Sets the number of Default Texture mapping channel vertices.

Data methods – Vertex selection weight channel (Channel 1)

meshop.getVSelectWeight <Mesh mesh> <int vertIndex>
Returns the Vertex Selection Weight data value for the specified vertex.
meshop.setVSelectWeight <Mesh mesh> <vertlist> <float weight>
Sets the Vertex Selection Weight data value for the specified vertex.
 Editable_Mesh : GeometryClass and TriMesh : Value 1061

meshop.resetVSelectWeights <Mesh mesh>

Sets the Vertex Selection Weight data value to 1.0 for all vertices.
meshop.supportVSelectWeights <Mesh mesh>
Enables support of the Vertex Selection Weight channel.
meshop.freeVSelectWeights <Mesh mesh>
Deletes (deallocates) the Vertex Selection Weight data array.

Data methods – Vertex weight channel (Channel 2)

meshop.getVertWeight <Mesh mesh> <int vertIndex>
Returns the Vertex Weight data value for the specified vertex.
meshop.setVertWeight <Mesh mesh> <vertlist> <float weight>
Sets the Vertex Weight data value for the specified vertex.
meshop.resetVertWeights <Mesh mesh>
Sets the Vertex Weight data value to 1.0 for all vertices.
meshop.supportVertWeights <Mesh mesh>
Enables support of the Vertex Weight channel.
meshop.freeVertWeights <Mesh mesh>
Deletes (deallocates) the Vertex Weight data array.

Data methods – Vertex Alpha channel (Channel 3)

meshop.getVAlpha <Mesh mesh> <int vertIndex>
Returns the Vertex Alpha data value for the specified vertex.
meshop.setVAlpha <Mesh mesh> <vertlist> <float alpha>
Sets the Vertex Alpha data value for the specified vertex.
meshop.resetVAlphas <Mesh mesh>
Sets the Vertex Alpha data value to 1.0 for all vertices.
meshop.supportVAlphas <Mesh mesh>
Enables support of the Vertex Alpha channel.
meshop.freeVAlphas <Mesh mesh>
Deletes (deallocates) the Vertex Alpha data array.

Data methods – Vertex corner channel (Channel 4)

meshop.getVertCorner <Mesh mesh> <int vertIndex>
Returns the Vertex Corner data value for the specified vertex.
meshop.setVertCorner <Mesh mesh> <vertlist> <float weight>
Sets the Vertex Corner data value for the specified vertex.
meshop.resetVertCorners <Mesh mesh>
Sets the Vertex Corner data value to 0.0 for all vertices.
1062 Chapter 11 | 3ds max Objects

meshop.supportVertCorners <Mesh mesh>

Enables support of the Vertex Corner channel.
meshop.freeVertCorners <Mesh mesh>
Deletes (deallocates) the Vertex Corner data array.

Editable mesh UI property methods

meshop.getAffectBackfacing <Mesh mesh> -- editable mesh only
meshop.setAffectBackfacing <Mesh mesh> <boolean> -- editable mesh only
meshop.getBubble <Mesh mesh> -- editable mesh only
meshop.setBubble <Mesh mesh> <float> -- editable mesh only
meshop.getDisplacementMapping <Mesh mesh> -- editable mesh only
meshop.setDisplacementMapping <Mesh mesh> <boolean> -- editable mesh only
meshop.getExtrusionType <Mesh mesh> -- editable mesh only
meshop.setExtrusionType <Mesh mesh> <int> -- editable mesh only
meshop.getFalloff <Mesh mesh> -- editable mesh only
meshop.setFalloff <Mesh mesh> <float> -- editable mesh only
meshop.getIgnoreBackfacing <Mesh mesh> -- editable mesh only
meshop.setIgnoreBackfacing <Mesh mesh> <boolean> -- editable mesh only
meshop.getIgnoreVisEdges <Mesh mesh> -- editable mesh only
meshop.setIgnoreVisEdges <Mesh mesh> <boolean> -- editable mesh only
meshop.getNormalSize <Mesh mesh> -- editable mesh only
meshop.setNormalSize <Mesh mesh> <float> -- editable mesh only
meshop.getPinch <Mesh mesh> -- editable mesh only
meshop.setPinch <Mesh mesh> <float> -- editable mesh only
meshop.getPlanarThreshold <Mesh mesh> -- editable mesh only
meshop.setPlanarThreshold <Mesh mesh> <float> -- editable mesh only
meshop.getSelByVertex <Mesh mesh> -- editable mesh only
meshop.setSelByVertex <Mesh mesh> <boolean> -- editable mesh only
meshop.getShowFNormals <Mesh mesh> -- editable mesh only
meshop.setShowFNormals <Mesh mesh> <boolean> -- editable mesh only
meshop.getShowVNormals <Mesh mesh> -- editable mesh only
meshop.setShowVNormals <Mesh mesh> <boolean> -- editable mesh only
meshop.getSoftSel <Mesh mesh> -- editable mesh only
meshop.setSoftSel <Mesh mesh> <boolean> -- editable mesh only
meshop.getSplitMesh <Mesh mesh> -- editable mesh only
meshop.setSplitMesh <Mesh mesh> <boolean> -- editable mesh only
meshop.getSSEdgeDist <Mesh mesh> -- editable mesh only
meshop.setSSEdgeDist <Mesh mesh> <int> -- editable mesh only
meshop.getSSUseEdgeDist <Mesh mesh> -- editable mesh only
meshop.setSSUseEdgeDist <Mesh mesh> <boolean> -- editable mesh only
meshop.getSubdivisionAngle <Mesh mesh> -- editable mesh only
meshop.setSubdivisionAngle <Mesh mesh> <float> -- editable mesh only
meshop.getSubdivisionDisplacement <Mesh mesh> -- editable mesh only
meshop.setSubdivisionDisplacement <Mesh mesh> <boolean> -- editable mesh only
meshop.getSubdivisionDistance <Mesh mesh> -- editable mesh only
meshop.setSubdivisionDistance <Mesh mesh> <float> -- editable mesh only
meshop.getSubdivisionEdge <Mesh mesh> -- editable mesh only
meshop.setSubdivisionEdge <Mesh mesh> <float> -- editable mesh only
meshop.getSubdivisionMaxLevels <Mesh mesh> -- editable mesh only
meshop.setSubdivisionMaxLevels <Mesh mesh> <int> -- editable mesh only
 Editable_Mesh : GeometryClass and TriMesh : Value 1063

meshop.getSubdivisionMaxTriangles <Mesh mesh> -- editable mesh only

meshop.setSubdivisionMaxTriangles <Mesh mesh> <int> -- editable mesh only
meshop.getSubdivisionMethod <Mesh mesh> -- editable mesh only
meshop.setSubdivisionMethod <Mesh mesh> {#regular | #spatial | #curvature |
#spatialAndCurvature} -- editable mesh only
meshop.getSubdivisionMinLevels <Mesh mesh> -- editable mesh only
meshop.setSubdivisionMinLevels <Mesh mesh> <int> -- editable mesh only
meshop.getSubdivisionSteps <Mesh mesh> -- editable mesh only
meshop.setSubdivisionSteps <Mesh mesh> <int> -- editable mesh only
meshop.getSubdivisionStyle <Mesh mesh> -- editable mesh only
meshop.setSubdivisionStyle <Mesh mesh> {#tree | #grid | #delaunay} -- editable mesh
only
meshop.getSubdivisionView <Mesh mesh> -- editable mesh only
meshop.setSubdivisionView <Mesh mesh> <boolean> -- editable mesh only
meshop.getWeldPixels <Mesh mesh> -- editable mesh only
meshop.setWeldPixels <Mesh mesh> <int> -- editable mesh only
meshop.getWeldThreshold <Mesh mesh> -- editable mesh only
meshop.setWeldThreshold <Mesh mesh> <float> -- editable mesh only
-- Vertex Methods
getNumVerts <mesh>
Returns number of vertices as an integer, equivalent to using <mesh>.numverts
setNumVerts <mesh> <vert_index_integer> [ <boolean> ]
Set the number of vertices as specified. If the optional boolean argument is true, the
existing topology remains intact. If it is false or left off, the topology is lost.
getVert <mesh> <vert_index_integer>
Returns the position (in the current working coordinate system) of the indexed vertex as a
point3
setVert <mesh> <vert_index_integer> ( <point3> | <float> <float> <float> )
Sets the position coordinates of the indexed vertex as a point3 value, or 3 floats - X,Y,Z
deleteVert <mesh> <vert_index_integer>
Deletes the indexed vertex from the mesh and all faces that share the vertex. Renumbers
vertices and faces to account for the deletions. Also adjusts face vertex indexes as
necessary.
getNormal <mesh> <vert_index_integer>
Returns the normal at the indexed vertex’s position as a point3. The normal is based on
the faces that use the vertex and the smoothing groups assigned to those faces.
setNormal <mesh> <vert_index_integer> <point3>
Sets the indexed vertex’s normal vector
1064 Chapter 11 | 3ds max Objects

getVertSelection <node> [ <modifier_or_index> ] [ name:<name> ]

getVertSelection <mesh>
Returns the current vertex selection set, or the specified named selection set if the optional
name: parameter is specified, as a BitArray. The optional <modifier_or_index>
identifies the Edit Mesh or Mesh Select modifier on the given scene object from which the
selection BitArray is obtained. For example:
getVertSelection $foo $foo.modifiers[3]

If the optional <modifier_or_index> argument is not supplied, the <node> must be an

Editable Mesh object and the selection is taken from the base object. If
<modifier_or_index> is supplied, it must be either a modifier on the node or a number.
If it is a modifier, it must be either an Edit Mesh or a Mesh Select modifier. If it is a number,
it is used as an index into the Edit Mesh/Select Modifiers on the <node> starting from the
top of the stack. Note that this index does not count any other types of modifier present.
So, an index of 1 will always get the selection currently active at the top of the stack.
The function returns a BitArray that are the 1-based indexes of the vertices currently
selected, or the vertices specified by the named selection set, in the object by the given
modifier. For example:
getVertSelection $foo $foo.modifiers[3]

yields
#{2..5,9,25..27}

This is a snapshot of the selection -- the BitArray doesn’t change automatically as you
make different selections. Further, it reflects the current vertex selection whether or not
the modifier is in vertex sub-object selection mode (this selection is remembered and re-
established whenever you go back into vertex subobject mode). So, for example, if you
select some vertices then click out of vertex subobject mode, the whole object rather than
the selection is passed up the stack to the next modifier, but getVertSelection()
returns the selected vertices at the time the subobject mode was exited.
You might use the modifiers modifier array accessing scheme here if you’ve got many
edit mesh modifiers with non-unique names. You can also use a constructed string as an
index into the modifiers array, for example:
$foo.modifiers[”edit mesh” + i as string]
assuming the variable ‘i’ had some indexing value and the names were set up
thusly. ‘+’ on strings concatenates.
setVertSelection <node> [ <modifier_or_index> ] \
( <sel_bitarray> | <sel_array> ) \
[ name:<name> ] [ keep:<boolean> ]
setVertSelection <mesh> ( <sel_bitarray> | <sel_array> ) \
[ keep:<boolean> ]
Sets the vertex selections in an Editable Mesh base object, Mesh Select modifier, Edit Mesh
Modifier, or TriMesh. This mirrors the selection getting method above.
 Editable_Mesh : GeometryClass and TriMesh : Value 1065

The <modifier_or_index> argument is interpreted as for the get- form above, except
that only the Mesh Select modifier is supported for set operations.
For example:
setVertSelection $foo #{1..4,100..102}
setFaceSelection $foo \
(getFaceSelection $baz) keep:true

If the optional name: argument is specified, the vertices in the specified named selection
set in the Editable Mesh or Mesh Select modifier are selected. If the name: argument is not
specified, the selection index argument gives the indexes of the sub-object items to be
selected as either a BitArray or an array of integers. If the optional keep: keyword
argument is false or not supplied, any current selection will be replaced by the new one.
If the keep: keyword argument is true, the new selection is added to the current
selection. The name: argument is not applicable to TriMeshes.
Use the mesh update() function after making a group of selection changes in order to
make them visible to any modifiers on the object.
averageSelVertCenter <node> [ <modifier_or_index> ]
Returns the average position (center) of the selected vertices in the given mesh as a Point3.
If the object is not a mesh this method returns undefined. If no vertices are selected in the
mesh, a value of [0,0,0] is returned. This method is not applicable to TriMeshes.
The <modifier_or_index> argument is interpreted as for getVertSelection.
averageSelVertNormal <node> [ <modifier_or_index> ]
Returns the normalized average of the normals of the selected vertices in the given mesh
as a Point3. If the given node is not a mesh, it returns undefined. If no vertices are selected
in the mesh, or the averaged normal is [0,0,0], a value of [1,0,0] is returned. This method is
not applicable to TriMeshes.
The <modifier_or_index> argument is interpreted as for getVertSelection.
The vertex normals used in this method do not consider smoothing group data of the
faces that use the vertex.
-- Face Methods
getNumFaces <mesh>
Returns number of faces as an integer, equivalent to using <mesh>.numfaces
getFace <mesh> <face_index_integer>
Returns the face vertex indexes for the indexed face as a point3. Each component of the
point3 value contains a vertex index.
setFace <mesh> <face_index_integer> <vert_indices_point3>
Sets the face vertex indexes for the indexed face from a point3.
setFace <mesh> <face_index_integer> <vert_index_integer> \
<vert_index_integer> <vert_index_integer>
Sets the face vertex indexes for the indexed face from 3 vertex indexes.
1066 Chapter 11 | 3ds max Objects

deleteFace <mesh> <face_index_integer>

Deletes indexed face from the mesh. Renumbers faces accordingly.
collapseFace <mesh> <face_index_integer>
Deletes indexed face from the mesh, welding its 3 vertices together at the center of the
original face. Renumbers faces accordingly.
getFaceNormal <mesh> <face_index_integer>
Returns the normal of the indexed face as a point3.
setFaceNormal <mesh> <face_index_integer> <point3>
Sets the indexed face’s normal vector. As soon as you run update() on the mesh, this
value is overwritten.
getFaceMatID <mesh> <face_index_integer>
Returns the indexed face’s material ID as an integer.
setFaceMatID <mesh> <face_index_integer> <integer>
Sets the indexed face’s material ID.
getFaceSmoothGroup <mesh> <face_index_integer>
Returns the indexed face’s smoothing groups as a 32-bit integer. There are 32 possible
smoothing groups. Each bit in the returned value corresponds to a smoothing group. If a
bit is turned on, the face is part of that smoothing group. You can retrieve the list of
smoothing groups for a face as a BitArray using the following function:
fn getfacesmoothgroupB obj face =
( local sgroup_val=getfacesmoothgroup obj face
local sg_bitarray=#{}
if sgroup_val < 0 do
( sg_bitarray[32]=true
sgroup_val -= 2^31
)
for i = 1 to 31 do
( sg_bitarray[i]= (mod sgroup_val 2 > .5)
sgroup_val /= 2
)
sg_bitarray
)

setFaceSmoothGroup <mesh> <face_index_integer> <smoothing_group_integer>

Sets the indexed face’s smoothing groups. If you have a face’s desired smoothing groups as
a BitArray, you could set the face’s smoothing group data using the following function:
fn setfacesmoothgroupB obj face sg_bitarray =
( local sgroup_val=0
for i in sg_bitarray do sgroup_val += 2^(i-1)
setfacesmoothgroup obj face sgroup_val
update obj
)
 Editable_Mesh : GeometryClass and TriMesh : Value 1067

getFaceSelection <node> [ <modifier_or_index> ] [ name:<name> ]

getFaceSelection <mesh>
Retrieves the face selection set, or the specified named selection set if the optional name:
parameter is specified, as a BitArray. See the getVertSelection() method for more
information.
setFaceSelection <node> [ <modifier_or_index> ] \
( <sel_bitarray> | <sel_array> ) \
[ name:<name> ] [ keep:<boolean> ]
setFaceSelection <mesh> ( <sel_bitarray> | <sel_array> ) \
[ keep:<boolean> ]
Sets the face selections in an Editable Mesh base object, Mesh Select modifier, Edit Mesh
modifier, or TriMesh. This mirrors the selection getting method above. See the
setVertSelection() method for more information.
deselectHiddenFaces <mesh>
deselects the hidden faces in the mesh. This method is not applicable to TriMeshes.
extrudeFace <mesh> ( <index> | <bitarray> | <integer_array> | #selection ) \
<amount> <scale> \
[ dir:(<point3> | #common | #independent ) ]
Provides capabilities equivalent to the Extrude Face modifier. This function works only on
Editable Mesh nodes. The second argument defines which faces to extrude, either a single
face index, a BitArray of face indexes, an integer array of face indexes, or the name literal
#selection meaning the current face selection in the Editable Mesh. The <amount>
argument specifies the extrude distance and the <scale> specifies a % amount to scale
each face cluster.
If the optional dir: keyword argument is not specified, face clusters are extruded by
moving their vertices independently along the average normal at each vertex, as does the
Extrude Face modifier. If it is specified, it can be a point3 giving a direction vector in
which all vertices are moved, or it can be the value #independent which is the same as
the default direction, or it can be the value #common which extrudes face clusters along the
average normal of all the face normals in each cluster. #common is equivalent to the Group
Normal option in EditableMesh, and #independent is equivalent to the Local Normal
option. An example usage is:
s=sphere()
extrudeface s #{1..20} 10 100 dir:#independent
update s

meshop.getVertsUsingFace <Mesh mesh> <facelist>

Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices that are used by
the specified faces.
meshop.getEdgesUsingFace <Mesh mesh> <facelist>
Returns a bitarray of size=(#edges in mesh) with bits set for all edges that are used by the
specified faces.
1068 Chapter 11 | 3ds max Objects

meshop.getPolysUsingFace <Mesh mesh> <facelist> ignoreVisEdges:<boolean=false>

threshhold:<float=45.>
Returns a bitarray of size=(#faces in mesh) with bits set for all faces that are in ‘polygons’
containing the specified faces. The definition of a polygon is all faces sharing invisible
edges with edge angles below the threshhold angle. The default threshhold angle is 45
degrees. If ignoreVisEdges is set to true, the edge visibility is ignored but the
threshhold is still relevant.
meshop.autoSmooth <Mesh mesh> <facelist> <float threshold>
Smooths the specified faces based on the threshold angle.
meshop.unifyNormals <Mesh mesh> <facelist>
Unifies the normals of the specified faces.
meshop.flipNormals <Mesh mesh> <facelist>
Flips the normal of the specified faces.
<float> meshop.getFaceArea <Mesh mesh> <facelist>
Returns the area of the specified faces as a <float>.
-- Edge Methods
getEdgeVis <mesh> <face_index_integer> <edge_index_integer>
Returns the edge visibility for given edge (1,2,3) on indexed face as a boolean.
setEdgeVis <mesh> <face_index_integer> <edge_index_integer> <boolean>
Sets the edge visibility for given edge (1,2,3) on indexed face.
getEdgeSelection <node> [ <modifier_or_index> ] [ name:<name> ]
getEdgeSelection <mesh>
Retrieves the edge selection set, or the specified named selection set if the optional name:
parameter is specified, as a BitArray. See the getVertSelection() method for more
information.
setEdgeSelection <node> [ <modifier_or_index> ] \
( <sel_bitarray> | <sel_array> ) \
[ name:<name> ] [ keep:<boolean> ]
setEdgeSelection <mesh> ( <sel_bitarray> | <sel_array> ) \
[ keep:<boolean> ]
Sets the edge selections in an Editable Mesh base object, Mesh Select modifier, Edit Mesh
Modifier, or TriMesh. This mirrors the selection getting method above. See the
setVertSelection() method for more information.
deselectHiddenEdges <mesh>
Deselects the hidden edges in the mesh. This method is not applicable to TriMeshes.
meshop.getVertsUsingEdge <Mesh mesh> <edgelist>
Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices that are used by
the specified edges.
meshop.getFacesUsingEdge <Mesh mesh> <edgelist>
Returns a bitarray of size=(#faces in mesh) with bits set for all faces that use the specified
edges.
 Editable_Mesh : GeometryClass and TriMesh : Value 1069

meshop.getPolysUsingEdge <Mesh mesh> <edgelist> ignoreVisEdges:<boolean=false>

threshhold:<float=45.>
Returns a bitarray of size=(#faces in mesh) with bits set for all faces that are in ‘polygons’
containing the specified edges. The definition of a polygon is all faces sharing invisible
edges with edge angles below the threshhold angle. The default threshhold angle is 45
degrees. If ignoreVisEdges is set to true, the edge visibility is ignored but the
threshhold is still relevant.
meshop.getEdgesReverseEdge <Mesh mesh> <edgelist>
Returns a bitarray of size=(#edges in mesh) with bits set for all additional edges that use
the same vertices as the specified edges. These are edges on the adjacent faces.
Example:
Plane length:100 width:100 isSelected:on
convertTo $ TriMeshGeometry

max modify mode

subobjectLevel = 1
select $.verts[13]

-- get edges that use vertex 13

edges = meshop.getEdgesUsingVert $ (getVertSelection $)

-- select the vertices used by those edges

$.selectedVerts = meshop.getVertsUsingEdge $ edges
update $

-- not what we wanted, really want all vertices “surrounding” vertex 13

faces = meshop.getPolysUsingVert $ 13
$.selectedVerts = meshop.getVertsUsingFace $ faces
update $

-- or ...
faces = meshop.getFacesUsingVert $ #(13)
edges = meshop.getEdgesUsingFace $ faces

-- turn off all visible edges

for e in edges do edges[e]=not (getEdgeVis $ (1+(e-1)/3)(1+mod (e-1) 3))

-- get the edges on the adjacent faces that are the “reverse” of these edges

-- “OR” that bitarray with the initial edges bitarray

edges = (meshop.getEdgesReverseEdge $ edges) + edges

-- get the faces that use the edges, and “OR” that bitarray with the initial

-- face bitarray
faces = (meshop.getFacesUsingEdge $ edges) + faces
$.selectedVerts = meshop.getVertsUsingFace $ faces
update $
1070 Chapter 11 | 3ds max Objects

meshop.autoEdge <Mesh mesh> <edgelist> <float threshold> type:<{#SetClear | #Set |

#Clear}=#SetClear>
Sets/clears the edge visibility for the specified edges based on the threshold angle. Note: for
an edge to be autoEdged, both it and the “reverse” edge on the face sharing the edge
vertices must be specified in the edge specification.
Note:
3ds max defines an edge as the edge of a face. In any mesh object, the number of edges is 3 times
the number of faces. A face has 3 vertices, and the face edges connect these vertices. Edges 1, 2, and
3 are the edges between vertices 1 and 2, 2 and 3, and 3 and 1, respectively. The first edge in a mesh
is edge 1 on face 1, and the last edge is edge 3 on the last face. The following script selects all of the
visible edges in the specified mesh:
EdgeSelSet=#()
for face = 1 to obj.numfaces do
for edge = 1 to 3 do
if (getedgevis obj face edge) then
append EdgeSelSet (((face-1)*3)+edge)
setedgeselection obj EdgeSelSet
update obj

The following function returns the indices of the 2 vertices that define an edge as a Point2 value.
The two arguments to the function are a editable mesh node or TriMesh value and the edge index.
A value of undefined is returned if the first argument isn’t an editable mesh node or TriMesh value,
or if the edge index is out of range.
fn edgeVerts theObj theEdge =
( if not (classof theObj == Editable_mesh or
classof theObj == triMesh) do return undefined
if theEdge < 1 or theEdge > (theObj.numfaces*3) do return undefined
local theFace = ((theEdge-1)/3)+1
local theVerts = getFace theObj theFace
case ((mod (theEdge-1) 3) as integer) of
( 0: point2 theVerts.x theVerts.y
1: point2 theVerts.y theVerts.z
2: point2 theVerts.z theVerts.x
)
)

-- Texture Vertex Methods

getNumTVerts <mesh>
Returns number of texture vertices as an integer, equivalent to using <mesh>.numtverts
setNumTVerts <mesh> <number> [ <boolean> ]
Sets the number of texture vertices as specified. If the optional boolean argument is true,
the existing topology remains intact. If it is false or not supplied, the topology is lost.
getTVert <mesh> <tvert_index_integer>
Returns the UVW coordinates of the indexed texture vertex
 Editable_Mesh : GeometryClass and TriMesh : Value 1071

setTVert <mesh> <tvert_index_integer> ( <point3> | <x> <y> <z> )

Sets the UVW coordinates of the indexed texture vertex as a point3 value, or 3 floats -
U,V,W
getTVFace <mesh> <face_index_integer>
setTVFace <mesh> <face_index_integer> <vert_indices_point3>
setTVFace <mesh> <face_index_integer> <tvert_index_integer> \
<tvert_index_integer> <tvert_index_integer>
The getTVFace() and setTVFace() functions mirror the getFace() and setFace()
functions and are used to specify texture mapping topology in terms of texture vertices.
You can set up and access texture vertices with the getTVert(), setTVert(),
getNumTVerts(), and setNumTVerts() functions described above.
buildTVFaces <mesh> [ <boolean> ]
The buildTVFaces() function only needs to be called on meshes you are adding texture
vertices to yourself to create the internal texture face array. Meshes that 3ds max applies
mapping coordinates to maintain the TVFace array automatically. This is not done
automatically when you add texture vertices to meshes yourself so you need to call
buildTVFaces() explicitly whenever you change the texture vertex count, and
before you construct the texture faces. If the optional boolean argument is true, the
existing texture mapping remains intact. If it is false or not supplied, the existing texture
mapping is lost (all texture faces are rebuilt, with all three vertices of the texture face using
texture vertex 1).
numMapsUsed <mesh>
Returns the an upper limit on the number of texture map channels used by the given
node. This is at least 1+(highest channel in use). This method is used so a script that does
something to all map channels doesn’t always have to do it to every channel up to 99 (the
highest possible texture map channel), but rather only to this value. This method is not
applicable to TriMeshes.
Note:
The mesh class contains a list of texture vertices which are completely independent of the regular
vertices in the mesh. There is no correlation between the number of vertices in a mesh and the
number of texture vertices. In addition to the texture vertices there are also texture faces. There
needs to be one texture face for every regular face in the mesh.
Each texture face has three indices into the texture vertex array. The coordinates of a texture vertex
are UVW coordinates, and are accessed as Point3 values. The 3 components are U, V, and W, and
each component value is in the range of 0 to 1. An example script for creating planar texture
mapping on an object is shown in the Working with Editable Meshes (p. 1077) topic.
The texture vertex methods do not support multiple mapping channels in 3ds max 4.
1072 Chapter 11 | 3ds max Objects

-- Color-Per-Vertex Methods
getNumCPVVerts <mesh>
Returns number of color-per-vertex vertices as an integer, equivalent to using
<node>.numcpvverts
setNumCPVVerts <mesh> <integer> [ <boolean> ]
Sets the number of c-p-v vertices. If the optional boolean argument is true, the existing
topology remains intact. If it is false or not supplied, the topology is lost.
buildVCFaces <mesh> [ <boolean> ]
Builds the c-p-v face array after you have set the c-p-v vertex count. If the optional boolean
argument is true, the existing topology remains intact. If it is false or not supplied, the
topology is lost.
defaultVCFaces <mesh>
Sets the number of c-p-v vertices and c-p-v faces to match exactly the current mesh’s
geometry and topology and calls buildVCFaces()
getVertColor <mesh> <CPVvert_index_integer>
Returns the color of the indexed c-p-v vertex as a color
getVCFace <mesh> <CPVface_index_integer>
Returns the topology for the indexed c-p-v face as a point3 containing 3 c-p-v vertex
indexes
setVCFace <mesh> <CPVface_index_integer> <CPVvert_indices_point3>
Sets the indexed c-p-v face topology from a point3 containing 3 c-p-v vertex indexes
setVCFace <mesh> <CPVface_index_integer> <CPVvert_index_integer> \
<CPVvert_index_integer> <CPVvert_index_integer>
Sets the indexed c-p-v face topology from 3 c-p-v vertex index number arguments
The c-p-v vertex and face indexes are 1-based as with other mesh indexes in MAXScript.
Remember that you need to call update() on the mesh after making changes to it for the
changes to be reflected in the scene.
Note:
The mesh class contains a list of color vertices which are completely independent of the regular
vertices in the mesh. There is no correlation between the number of vertices in a mesh and the
number of color vertices. In addition to the color vertices there are also color faces. There needs to
be one color face for every regular face in the mesh.
Each color face has three indices into the color vertex array. The coordinates of a color vertex are
RGB coordinates, and are accessed as Color values.
The techniques for building and accessing color vertices and faces is virtually identical to the
techniques for building and accessing texture vertices and faces. An example script for creating
planar texture mapping on an object is shown in the Working with Editable Meshes (p. 1077) topic.
 Editable_Mesh : GeometryClass and TriMesh : Value 1073

-- Subdivision Displacement Surface Properties Methods

The following methods set the Subdivision Displacement Surface Properties for a mesh object. These
methods are not applicable to TriMeshes.
setSplitMesh <mesh> <boolean>
Turns on or off split mesh subdivision displacement for the mesh. Calling this function
will enable subdivisionDisplacement if it is set to false.
getSplitMesh <mesh>
Returns true if split mesh subdivision displacement is turned on for the mesh, false
otherwise.
setSubdivisionDisplacement <mesh> <boolean>
Turns on or off subdivision displacement for the mesh.
getSubdivisionDisplacement <mesh>
Returns true if subdivision displacement is turned on for the mesh, false if off.
displacementToPreset <mesh> ( #low | #medium | #high )
Sets the mesh subdivision parameters to the specified preset value set.
setDisplacementMapping <mesh> <boolean>
Turns on or off whether to perform displacement mapping for the mesh. There is no
corresponding user interface element for this method.
getDisplacementMapping <mesh>
Returns true if displacement mapping is turned on for the mesh, false if off.
-- Editable Mesh Modify Panel Command Modes and Operations
A suite of methods provide the ability for a script to invoke Editable Mesh and Edit Mesh Modify
panel modes and operations, corresponding to buttons available at various mesh sub-object levels.
These methods reside in the meshOps global structure. These methods effectively “push the button”
in the 3ds max Modify panel. In order to use these methods, the node must be selected and the
Modify panel open. In the description of these methods, the first argument
<editable_mesh_node_or_modifier> should be interpreted as either an Editable Mesh node
where the modifier stack level is at the base object, or an Edit Mesh modifier where the modifier
stack level is at the Edit Mesh. In all cases, the following methods work at the current sub-object
level, but only if that level is appropriate for the invoked operation.
If you have made scripted changes to the mesh you must call the update() method on the mesh
before calling these methods. You do not need to call update() after just calling one of these
methods, as 3ds max will take care of updating the mesh.
The follow methods invoke one of the ‘user-interaction’ button operations in the Editable Mesh
Modify panel, acting on the currently selected sub-objects. These methods highlight the
corresponding button in the Edit Geometry rollout and start the operation, at which point the user
interactively completes the operation. These methods return after starting the operation, and before
the user completes the operation, so care should be taken to ensure that your script does not
interfere with the operation. Invoking any of these methods is the same as clicking on the associated
button in the Modify panel. Calling a method when the operation is already in effect (either due to
1074 Chapter 11 | 3ds max Objects

a user action or a MAXScript command) causes the operation to be terminated and the highlight is
removed from the button.
In 3ds max 4, there is no access to the spinner field values in the Editable Mesh rollouts.
meshOps.startAttach <editable_mesh_node_or_modifier>
Enters “Attach” command mode - valid in Vertex, Face, Polygon, and Element Sub-Object
levels, and when not in Sub-Object mode.
meshOps.startBevel <editable_mesh_node_or_modifier>
Enters “Bevel” command mode - valid in Edge, Face, Polygon, and Element Sub-Object
levels.
meshOps.startChamfer <editable_mesh_node_or_modifier>
Enters “Chamfer” command mode - valid in Vertex and Edge Sub-Object levels.
meshOps.startCreate <editable_mesh_node_or_modifier>
Enters “Create” command mode, valid in Vertex, Face, Polygon, and Element Sub-Object
levels.
meshOps.startCut <editable_mesh_node_or_modifier>
Enters “Cut” command mode - valid in Edge, Face, Polygon, and Element Sub-Object
levels.
meshOps.startDivide <editable_mesh_node_or_modifier>
Divides selected edges into 2 edges, for selected face into 3 faces - valid in Edge, Face,
Polygon, and Element Sub-Object levels.
meshOps.startExtrude <editable_mesh_node_or_modifier>
Enters “Extrude” command mode - valid in Face, Polygon, and Element Sub-Object levels.
meshOps.startFlipNormalMode <editable_mesh_node_or_modifier>
Enters “Flip Normal” command mode - valid in Face, Polygon, and Element Sub-Object
levels.
meshOps.startSlicePlane <editable_mesh_node_or_modifier>
Enters “Slice Plane” command mode - valid in all Sub-Object levels, and when not in Sub-
Object mode.
meshOps.startTurn <editable_mesh_node_or_modifier>
Enters “Turn “ command mode - valid in Edge Sub-Object level.
meshOps.startWeldTarget <editable_mesh_node_or_modifier>
Enters “Weld Target “ command mode - valid in Vertex Sub-Object level.
The following methods invoke one of the ‘instantaneous’ button operations in the Editable Mesh
Modify panel, acting on the currently selected sub-objects:
meshOps.autoEdge <editable_mesh_node_or_modifier>
Automatically sets the edge visibility on the selected sub-objects - valid in Edge Sub-Object
level.
meshOps.break <editable_mesh_node_or_modifier>
Creates a new vertex for each face attached to the selected sub-objects - valid in Vertex
Sub-Object level.
 Editable_Mesh : GeometryClass and TriMesh : Value 1075

meshOps.collapse <editable_mesh_node_or_modifier>
Collapses the selected sub-objects - valid in Vertex, Edge, Face, Polygon, and Element Sub-
Object levels.
meshOps.createShapeFromEdges <editable_mesh_node_or_modifier>
Displays Create Shape dialog allowing the user to specify an object name, shape type, and
whether to ignore hidden edges. Valid in Edge Sub-Object level.
meshOps.delete <editable_mesh_node_or_modifier>
Deletes the selected sub-objects - valid in Vertex, Face, Polygon, and Element Sub-Object
levels.
meshOps.detach <editable_mesh_node_or_modifier>
Displays Detach dialog allowing the user to specify an object name or to detach as
element, and whether to clone the selected subobjects. Valid in Vertex, Face, Polygon, and
Element Sub-Object levels.
meshOps.explode <editable_mesh_node_or_modifier>
Displays Explode to Objects dialog allowing the user to specify an object name. Explodes
the selected faces into multiple elements or objects based on the angles of its edges. Valid
in Vertex, Face, Polygon, and Element Sub-Object levels.
meshOps.flipNormal <editable_mesh_node_or_modifier>
Flips the normal of the selected faces - valid in Face, Polygon, and Element Sub-Object
levels.
meshOps.gridAlign <editable_mesh_node_or_modifier>
Aligns the selected sub-objects to the construction plane - valid in Vertex, Edge, Face,
Polygon, and Element Sub-Object levels.
meshOps.hide <editable_mesh_node_or_modifier>
Hides the selected sub-objects - valid in Vertex, Face, Polygon, and Element Sub-Object
levels.
meshOps.invisibleEdge <editable_mesh_node_or_modifier>
Sets selected edges invisible. Valid in Vertex Sub-Object level.
meshOps.makePlanar <editable_mesh_node_or_modifier>
Forces all selected sub-objects to become coplanar - valid in Vertex, Edge, Face, Polygon,
and Element Sub-Object levels.
meshOps.removeIsolatedVerts <editable_mesh_node_or_modifier>
Deletes all isolated vertices in the object regardless of the current selection.
meshOps.selectOpenEdges <editable_mesh_node_or_modifier>
Selects all edges with only one face. Valid in Edge Sub-Object level.
meshOps.slice <editable_mesh_node_or_modifier>
Subdivides edges and faces based on Slice Plane. meshOps.startSlicePlane() must be
called to enter the “Slice Plane” command mode before slice is valid. Valid in all Sub-
Object levels, and when not in Sub-Object mode.
meshOps.tessellate <editable_mesh_node_or_modifier>
Tessellates the selected sub-objects - valid in Face, Polygon, and Element Sub-Object levels.
1076 Chapter 11 | 3ds max Objects

meshOps.unhideAll <editable_mesh_node_or_modifier>
Unhides the hidden sub-objects at the current Sub-Object level - valid in Vertex, Face,
Polygon, and Element Sub-Object levels.
meshOps.unifyNormal <editable_mesh_node_or_modifier>
Unifies the normals of the selected faces - valid in Face, Polygon, and Element Sub-Object
levels.
meshOps.viewAlign <editable_mesh_node_or_modifier>
Aligns all selected sub-objects to the 0,0,0 plane of the active viewport - valid in Vertex,
Edge, Face, Polygon, and Element Sub-Object levels.
meshOps.visibleEdge <editable_mesh_node_or_modifier>
Sets selected edges visible. Valid in Edge Sub-Object level.
meshOps.weld <editable_mesh_node_or_modifier>
Welds the selected vertices - valid in Vertex Sub-Object level.
The meshOps methods depend on the Modify panel being open and the desired object, either an
Editable Mesh base object or Edit Mesh modifier, being currently open in the panel. The meshOps
methods do not perform any operation if these conditions aren’t met. You will need to use
MAXScript functions like max modify mode or setCommandPanelTaskMode mode:#modify to
open the Modify panel, select <obj> to select the object, subObjectLevel = <n> to set the Sub-
Object level, and modPanel.setCurrentObject <obj_or_modifier> to establish the right
context for the new functions to operate. For example:
Script:
s=sphere() -- create a sphere
ConvertToMesh s -- convert to an Editable Mesh
s.selectedfaces=#{1..112} -- select half the faces
max modify mode -- open the Modify panel
select s -- select the sphere
modPanel.setCurrentObject s -- set modifier stack to the base object
-- (not really needed in this example)
subObjectLevel = 4 -- set Sub-Object level to polygon
meshOps.startExtrude s -- start the face extrude command mode,
-- highlighting its button in the Edit
-- Geometry rollout, at which point the
-- user interactively performs the extrude.

Another example is:

meshOps.Hide (modPanel.getCurrentObject())

which would invoke the Hide button operation on the current object open in the Modify panel if it
was an Edit Mesh modifier or Editable Mesh base object.
 Working with Editable Meshes 1077

Working with Editable Meshes

Flipping Face Normals
The following function flips the face normal for all faces in the specified mesh object.
Script:
fn FlipObjNormal obj =
( for f =1 to obj.numFaces do -- for each face in the mesh
( verts=getface obj f -- get its 3 vertices as a point3
local tmp=verts.x -- swap the first and third vertices
verts.x=verts.z -- which flips the normal
verts.z=tmp -- (right-hand rule), and
setface obj f verts -- store the new vertex order for the face
)
update obj -- update object so 3ds max sees the changes
)

Texture Vertices and Faces

The following script is an example of working with texture vertices and faces.
Script:
-- function to apply planar mapping to an object
-- direction parameter specifies the axis the mapping is
-- perpendicular to, and can have a value of #x, #y, or #z
--
fn ApplyPlanarMap obj direction =
( local oldcoordsys, normalize_pos
-- in this case, the number of texture vertices is equal to the
-- number of mesh vertices
obj.numtverts=obj.numverts
-- build the texture vertex faces
buildTVFaces obj
-- operate in objects coordinate space. Save original coord system so we
-- can restore later.
oldcoordsys=set coordsys local
-- for each vertex in mesh, get it’s position and normalize the position
-- to a range of [0,0,0] to [1,1,1]. This is the planar UVW space.
for v = 1 to obj.numverts do
( normalize_pos=((getvert obj v)-obj.min)/(obj.max-obj.min)
-- flip around position component values based on which direction the
-- planar mapping is perpendicular to
case direction of
(#x:( tmp=normalize_pos.x
normalize_pos.x=normalize_pos.y
normalize_pos.y=normalize_pos.z
normalize_pos.z=tmp
)
#y:( tmp=normalize_pos.y
normalize_pos.y=normalize_pos.z
normalize_pos.z=tmp
)
1078 Chapter 11 | 3ds max Objects

)
-- set the corresponding texture vertex “position”
settvert obj v normalize_pos
)
-- done “positioning” the texture vertices. Build the texture faces.
-- since in this case there is a 1-to-1 correspondence between mesh and
-- texture vertices, the vertex indices for a mesh face are also the
-- texture vertex indices for the texture faces.
for f = 1 to obj.numfaces do
setTVFace obj f (getface obj f)
-- all done. reset the coordinate system
set coordsys oldcoordsys
-- update the mesh so 3ds max sees the changes
update obj
)
--
-- test bed. Create a sphere, apply a material, set the diffuse map
-- to a 2x3 tiled checker map, turn on viewport display of the
-- checker texture map, and call the ApplyPlanarMap function
--
g=geosphere()
convertToMesh g
g.material=standard()
g.material.maps[2]=checker()
g.material.maps[2].coordinates.u_tiling=2
g.material.maps[2].coordinates.v_tiling=3
showTextureMap g.material g.material.maps[2] true
ApplyPlanarMap g #x

Output:
ApplyPlanarMap() -- output of function declaration lines 5 to 45
$GeoSphere:GeoSphere02 @ [0.0,0.0,0.0] -- output line 51
$Editable_Mesh:GeoSphere02 @ [0.0,0.0,0.0] -- output line 52
Standard:Standard -- output line 53
Checker:Checker -- output line 54
2 -- output line 55
3 -- output line 56
OK -- output line 57
OK -- output line 58
 SplineShape : Shape 1079

SplineShape : Shape
SplineShapes are the general editable versions of all the shape objects, in the same way that Editable
Meshes relate to geometry objects. They are the objects that a shape is converted to when you apply
an Edit Spline modifier and the result of collapsing a modifier stack on a shape base object.
MAXScript lets you construct SplineShapes from scratch, adding individual curves and controls
points or you can modify an existing shape by converting it to a SplineShape and using the methods
listed below.

See also
Shape Common Properties, Operators, and Methods (p. 945)
Spline Shape Common Properties, Operators, and Methods (p. 947)
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Class and Object Inspector Functions (p. 799)
Scripting Vertex and Control Point Animation (p. 1461)
Note:
1. You must convert existing shapes to SplineShapes in order to operate on them with the these
methods. Use the convertToSplineShape() function to do this.
2. Only the updateShape() function updates the shape’s internal caches and images in 3ds max
viewports. This is because updates can be computationally expensive and you don’t want them
performed on every function call. However, you must make sure you do call the
updateShape() function after a series of changes and before the shape is to be worked on in
3ds max or by other functions in MAXScript.
3. The in and out vectors for Bezier control points are given as vector handle coordinates, not as
true vectors as the names suggests.
4. Coordinates are given in the MAXScript working coordinate system - this is important to note
if you are familiar with the corresponding SDK spline functions which always work in object-
local coordinates.
5. If the updateShape() function is called on an object that is selected and currently open in the
Modify panel, it will drop the current selection in order to avoid a potential crash in 3ds max,
which at the moment, does not support scripted changes to an object open in the Modify panel.
6. If you are creating or modifying a spline object, and have not yet run updateShape() on the
spline, 3ds max will crash if you minimize and then maximize the 3ds max window. This is
because an only partially created spline is created, and the internal 3ds max spline structure is
left in an unstable state.
1080 Chapter 11 | 3ds max Objects

Properties:
<SplineShape>.angle Float default: 0.0 -- animatable
The rotational position of the cross-section in the renderer.
<SplineShape>.thickness Float default: 1.0 -- animatable
Diameter of the rendered spline.
<SplineShape>.sides Float default: 12.0 -- animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a
square cross section, for example.
<SplineShape>.viewport_thickness Float default: 1.0
Diameter of the viewport spline.
<SplineShape>.viewport_sides Integer default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a
square cross section, for example.
<SplineShape>.viewport_angle Float default: 0.0
The rotational position of the cross-section in the viewports.
<SplineShape>.DisplayRenderMesh Booleandefault: false
When on, displays the mesh generated by the spline in the viewports.
<SplineShape>.UseViewportSettings Boolean default: false
When on, displays the mesh generated by the Viewport settings.
<SplineShape>.DisplayRenderSettings Boolean default: true
When on, displays the mesh generated by the render settings.
<SplineShape>.numSplines Integer, read-only
The number of individual spline curves in the shape.
Up to 3*N vertex and tangent coordinates are available as properties, where N is the number of
vertices in the SplineShape. A vertex and its tangents are available as properties once a controller has
been assigned to the vertex. Controllers can be assigned to vertices using the animateVertex()
method described in the Scripting Vertex and Control Point Animation (p. 1461) topic. For example, if
a circle object is collapsed to a SplineShape, and some of its vertices are animated, the properties for
the vertices and tangents would be similar to:
$Circle01.Spline_1___InVec_1 Point3 value: [-75,33,0] -- animatable
$Circle01.Spline_1___Vertex_1 Point3 value: [-75,33,0] -- animatable
$Circle01.Spline_1___OutVec_1 Point3 value: [-50,0,0] -- animatable
$Circle01.Spline_1___InVec_2 Point3 value: [-20,-33,0] -- animatable
$Circle01.Spline_1___Vertex_2 Point3 value: [7,-66,0] -- animatable
$Circle01.Spline_1___OutVec_2 Point3 value: [32,-95,0] -- animatable
 SplineShape : Shape 1081

Methods:
-- Shape Methods
updateShape <shape>
Updates the shape’s internal caches and viewport display to account for all the changes
made by other functions in this kit. This update must be done before 3ds max or any other
code tries to work with a modified shape object.
The updateShape() function makes any scripted changes to a base object spline shape
propagate into the bottom of any modifier stack that is present. Note that there is no
check to warn you that modifications such as topology changes might invalidate modifiers
already in the stack. This is equivalent to opening and modifying the base object in a
Modify panel, ignoring its warnings about invalidating the object.
resetShape <shape>
Clears all the spline curves out of a shape
numSplines <shape>
Returns the number of spline curves in the shape as an integer. Equivalent to
<shape>.numSplines.
setFirstSpline <shape> <spline_index_integer>
Rolls the order of the splines in a shape around so that the numbered spline is the first
spline in the shape. This is useful when working with multi-spline shapes in the Lofter and
some other modifiers such as Surface Tools which are sensitive to spline order.
hideselectedsplines <shape>
Hides the selected splines in the shape.
hideselectedsegments <shape>
Hides the selected segments in the shape.
hideselectedverts <shape>
Hides the segments attached to the selected knots in the shape.
unhidesegments <shape>
Unhides all segments in the shape.
addAndWeld <to_shape> <from_shape> <weldthreshold_float>
Add the splines from one spline shape to the specified bezier shape. The weld threshold
will weld the endpoints of the new splines onto endpoints of existing ones if they are
within the distance specified.
bindKnot <shape> <isEnd_boolean> <splineId_integer> \
<segIndex_integer> <splineSegId_integer>
Binds the first or end knot of a spline to the midpoint of the specified segment. A bind acts
as a constraint, it constrains the first point or the end point of a spline to the mid point of
a segment. If <isEnd_boolean> is true the end knot of the spline is bound, otherwise
the first knot is bound. <splineId_integer> specifies the index of the spline the first/
end knot to bind belongs to, <segIndex_integer> specifies the index of the segment to
bind to, and <splineSegId_integer> specifies the index of the spline the bind to
segment belongs to.
1082 Chapter 11 | 3ds max Objects

unBindKnot <shape> <spline_index_integer> <isEnd_boolean>

Unbinds the specified end/first knot of the given spline
updateBindList <shape>
Called when the topology changes to update the bind list, for example when knots are
deleted from bound spline or the spline bound to.
materialID <shape> <spline_index_integer> <segment_index_integer>
Returns the material id for the given segment of the given shape object.
animateVertex <shape> <vertex_spec>
Applies controllers to the specified vertices and tangents of the splineshape, where
<vertex_spec> is one of:
<integer_index>
<integer_index_array>
#all

By assigning controllers to the vertices and tangents, the vertices and tangents are added
to the Master subAnim and appear as animatables in the Track View, allowing further
scripting of the vertices and tangents. For example,
animateVertex $Circle01 #all

The vertices to be animated are specified by index number or with the keyword #all to
animate all vertices.
See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point
Animation (p. 1461) for details on accessing the splineshape vertices and tangents. The
controller values assigned to the vertices and tangent handles is in object space. See the
Using Node Transform Properties (p. 843) topic for information on converting between world
space to object space.
-- Spline Methods
addNewSpline <shape>
Adds a new spline curve to the spline shape and returns an integer reflecting the spline
index of the newly added spline curve. Individual spline curves are given index numbers
starting at 1. The addNewSpline() function adds new spline curves to the end of the list
of curves in a shape.
getSplineSelection <shape>
Returns the indices of the selected splines in the shape as an array of integers.
setSplineSelection <shape> <spline_index_array> [ keep:<boolean> ]
Selects the splines specified by <spline_index_array> in the specified shape.
<spline_index_array> is an array of integers specifying the spline indices. Splines
already selected are de-selected unless keep:true is specified.
deleteSpline <shape> <spline_index_integer>
Deletes the indexed spline curve from the shape. The remaining curves are renumbered to
account for the deletion.
 SplineShape : Shape 1083

numSegments <shape> <spline_index_integer>

Returns the number of line segments in the indexed spline as an integer. This is the same
as the number of knots for closed splines and 1 less for open splines.
numKnots <shape> [ <spline_index_integer> ]
Returns the number of knots (also known vertices or control points) in the indexed spline
as an integer. If the spline index is not specified, returns the number of knots in the entire
shape.
isClosed <shape> <spline_index_integer>
returns true if the indexed spline is closed, false if it is open.
close <shape> <spline_index_integer>
closes the indexed spline.
open <shape> <spline_index_integer>
opens the indexed spline between its last and first knots.
reverse <shape> <spline_index_integer>
reverses the order of the knots in the indexed spline.
setFirstKnot <shape> <spline_index_integer> <knot_index_integer>
rolls the order of the knots in the indexed spline around so that the specified knot
becomes the first knot in the spline.
getSegLengths <splineShape> <spline_index> [cum:<boolean>] [byVertex:<boolean>]
[numArcSteps:<integer>]
Returns array of segment lengths or vertex distances by spline fraction and length, and
total spline length. Double precision calculations, very accurate. If cum:true, results are
cumulative, otherwise they are relative. If byVertex:true results are per vertex,
otherwise per segment.
Defaults: cum:false byVertex:false numArcSteps:100
subdivideSegment <splineShape> <spline_index> <seg_index> <divisions>
Divides the segment into the specified number of divisions. Double precision calculations,
very accurate.
interpCurve3D <splineShape> <spline_index> <param_float> [pathParam:<boolean>]
Returns a <point3> coordinate on the indexed curve. If pathParam:false, param is the
fraction of the spline length, otherwise it is a segment-based (path) fraction. Default is
pathParam:false
tangentCurve3D <splineShape> <spline_index> <param_float> [pathParam:<boolean>]
Returns a <point3> tangent on the indexed curve. If pathParam:false, param is the
fraction of the spline length, otherwise it is a segment-based (path) fraction. Default is
pathParam:false
-- Segment Methods
getSegmentType <shape> <spline_index_integer> <seg_index_integer>
Gets the segment type of the indexed segment in the indexed spline
setSegmentType <shape> <spline_index_integer> \
<seg_index_integer> ( #curve | #line )
Sets the segment type of the indexed segment in the indexed spline
1084 Chapter 11 | 3ds max Objects

refineSegment <shape> <spline_index_integer> \

<seg_index_integer> <seg_interp_param_float>
Adds a new knot to the indexed segment of the indexed curve at a place along the indexed
segment corresponding to the given segment interpolation parameter. This value is a float
in the range 0.0 to 1.0, specifying a proportion along the segment. The new knot
coordinates and in-vector and out-vector are automatically computed to maintain the
segment’s existing curvature. This is the primitive used by the refine function in the Edit
Spline modifier. You can use the MAXScript spline path interpolation functions to derive
segment parameters given that a curve’s path interpolation parameter is divided evenly
among the segments in a curve. (So given a path interpolation parameter u and a target
segment n in a spline of m segments, the segment parameter is u - (n-1)/m.) The
refineSegment() function returns the index of the newly inserted knot.
getSegSelection <shape> <spline_index_integer>
Returns the indices of the selected segments in the specified shape spline as an array of
integers.
setSegSelection <shape> <spline_index_integer> \
<segment_index_array> [ keep: <boolean> ]
Selects the segments specified by <segment_index_array> in the specified shape spline.
<segment_index_array> is an array of integers specifying the segment indices.
Segments already selected are de-selected unless keep:true is specified.
setMaterialID <splineShape> <spline_index> <seg_index> <matID>
Sets the material ID of the specified spline segment.
getMaterialID <splineShape> <spline_index> <seg_index>
Gets the material ID of the specified spline segment.
-- Knot Methods
addKnot <shape> <spline_index_integer> \
( #smooth | #corner | #bezier | #bezierCorner ) \
( #curve | #line ) <position_point3> \
[invec_point3 outvec_point3] [where_integer]
Adds a new knot (control point) to the indexed spline and returns an integer reflecting the
index of the newly added knot. The 3rd argument specifies the type of the knot, the 4th
specifies the type of the segment leaving the knot. The 5th specifies the coordinates for the
new point (given in the current working coordinate system). If the knot type is bezier or
bezierCorner, you must give the in-vector and out-vector handle coordinates as the 6th
and 7th arguments. In the same way as splines are indexed in a shape, knots are indexed
in a spline. The optional last argument lets you specify where in the knot order the new
knot is to be inserted, defaulting to the end of the spline if you leave this argument off.
deleteKnot <shape> <spline_index_integer> <knot_index_integer>
Deletes the indexed knot in the indexed spline. The remaining knots are renumbered to
account for the deletion.
getKnotType <shape> <spline_index_integer> <knot_index_integer>
Returns the knot type of the indexed knot in the indexed spline. The value is one of the
names #smooth, #corner, #bezier, or #bezierCorner.
 SplineShape : Shape 1085

setKnotType <shape> <spline_index_integer> <knot_index_integer> \

(#smooth | #corner | #bezier | #bezierCorner )
Sets the knot type of the indexed knot in the indexed spline. This is equivalent to the
right-mouse-button change you can make to spline control-points using the Edit Spline
modifier in 3ds max.
getKnotPoint <shape> <spline_index_integer> <knot_index_integer>
Retrieves the coordinates of the indexed knot as a point3 in the current working
coordinate system.
setKnotPoint <shape> <spline_index_integer> <knot_index_integer> <point3>
Sets the coordinates of the indexed knot in the indexed spline. Coordinates are given in
the current working coordinate system.
getInVec <shape> <spline_index_integer> <knot_index_integer>
Retrieves the coordinates of the in-vector handle for the indexed knot as a point3 in the
current working coordinate system.
setInVec <shape> <spline_index_integer> <knot_index_integer> <point3>
Sets the coordinates of the in-vector handle of the indexed knot. Coordinates are given in
the current working coordinate system.
getOutVec <shape> <spline_index_integer> <knot_index_integer>
Retrieves the coordinates of the out-vector handle for the indexed knot as a point3 in the
current working coordinate system.
setOutVec <shape> <spline_index_integer> <knot_index_integer> <point3>
Sets the coordinates of the out-vector handle of the indexed knot. Coordinates are given in
the current working coordinate system.
getKnotSelection <shape> <spline_index_integer>
Returns the indices of the selected knots in the specified shape spline as an array of
integers.
setKnotSelection <shape> <spline_index_integer> \
<knot_index_array> [keep: <boolean> ]
Selects the knots specified by <knot_index_array> in the specified shape spline.
<knot_index_array> is an array of integers specifying the knot indices. Knots already
selected are de-selected unless keep:true is specified.
-- Editable Spline Modify Panel Command Modes and Operations
A suite of methods provide the ability for a script to invoke Editable Spline, Line, and Edit Spline
Modify panel modes and operations, corresponding to buttons available at various shape sub-object
levels. These methods reside in the splineOps global structure. These methods effectively “push the
button” in the Modify panel. In order to use these methods, the node must be selected and the
Modify panel open. In the description of these methods, the first argument
<editable_spline_or_line_node_or_modifier> should be interpreted as either an Editable
Spline or Line node where the modifier stack level is at the base object, or an Edit Spline modifier
where the modifier stack level is at the Edit Spline. In all cases, the following methods work at the
current sub-object level, but only if that level is appropriate for the invoked operation.
1086 Chapter 11 | 3ds max Objects

If you have made scripted changes to the shape you must call the updateShape() method on the
mesh before calling these methods. You do not need to call updateShape() after just calling one
of these methods, as 3ds max will take care of updating the shape.
The following methods invoke one of the ‘user-interaction’ button operations in the Editable Spline
Modify panel, acting on the currently selected sub-objects. These methods highlight the
corresponding button in the Geometry rollout and start the operation, at which point the user
interactively completes the operation. These methods return after starting the operation, and before
the user completes the operation, so care should be taken to ensure that your script does not
interfere with the operation. Invoking any of these methods is the same as clicking on the associated
button in the Modify panel. Calling a method when the operation is already in effect (either due to
a user action or a MAXScript command) causes the operation to be terminated and the highlight is
removed from the button.
splineOps.startUnion <editable_spline_or_line_node_or_modifier>
Enters “Boolean Union” command mode - valid in Spline Sub-Object level. Only 1 closed
spline must be selected to enter this command mode.
splineOps.startSubtract <editable_spline_or_line_node_or_modifier>
Enters “Boolean Subtract” command mode - valid in Spline Sub-Object level. Only 1 closed
spline must be selected to enter this command mode.
splineOps.intersect <editable_spline_or_line_node_or_modifier>
Enters “Boolean Intersect” command mode - valid in Spline Sub-Object level. Only 1
closed spline must be selected to enter this command mode.
splineOps.startAttach <editable_spline_or_line_node_or_modifier>
Enters “Attach” command mode - valid in all Sub-Object levels, and when not in Sub-
Object mode.
splineOps.startBind <editable_spline_or_line_node_or_modifier>
Enters “Bind” command mode - valid in Vertex Sub-Object level.
splineOps.startBreak <editable_spline_or_line_node_or_modifier>
Enters “Break” command mode - valid in Vertex and Segment Sub-Object levels.
splineOps.startChamfer <editable_spline_or_line_node_or_modifier>
Enters “Chamfer” command mode - valid in Vertex Sub-Object level.
splineOps.startConnect <editable_spline_or_line_node_or_modifier>
Enters “Connect” command mode - valid in Vertex Sub-Object level.
splineOps.startCreateLine <editable_spline_or_line_node_or_modifier>
Enters “Create Line” command mode - valid in all Sub-Object levels, and when not in Sub-
Object mode.
splineOps.startCrossInsert <editable_spline_or_line_node_or_modifier>
Enters “CrossInsert” command mode - valid in Vertex Sub-Object level.
splineOps.startExtend <editable_spline_or_line_node_or_modifier>
Enters “Extend” command mode - valid in Spline Sub-Object level.
splineOps.startFillet <editable_spline_or_line_node_or_modifier>
Enters “Fillet” command mode - valid in Vertex Sub-Object level.
 SplineShape : Shape 1087

splineOps.startInsert <editable_spline_or_line_node_or_modifier>
Enters “Insert” command mode - valid in all Sub-Object levels, and when not in Sub-
Object mode.
splineOps.startOutline <editable_spline_or_line_node_or_modifier>
Enters “Outline” command mode - valid in Spline Sub-Object level.
splineOps.startRefine <editable_spline_or_line_node_or_modifier>
Enters “Refine” command mode - valid in Vertex and Segment Sub-Object levels. This
method does not turn off the Connect checkbox, so it is effectively the same as the
startRefineConnect() method.
splineOps.startRefineConnect <editable_spline_or_line_node_or_modifier>
Enters “Refine” command mode - valid in Vertex and Segment Sub-Object levels. This
method does not turn on the Connect checkbox, so it is effectively the same as the
startRefine() method.
splineOps.startTrim <editable_spline_or_line_node_or_modifier>
Enters “Trim” command mode - valid in Spline Sub-Object level.
The following methods invoke one of the ‘instantaneous’ button operations in the Editable Shape
Modify panel, acting on the currently selected sub-objects:
splineOps.attachMultiple <editable_spline_or_line_node_or_modifier>
Displays Attach Multiple dialog allowing the user to select multiple shapes to attach. Valid
in all Sub-Object levels, and when not in Sub-Object mode.
splineOps.close <editable_spline_or_line_node_or_modifier>
Closes the selected splines – valid in Spline Sub-Object level.
splineOps.cycle <editable_spline_or_line_node_or_modifier>
Cycles through the vertices of the spline, selecting each vertex. At least one vertex must be
selected before calling this method, or no vertex is selected. If more than one vertex is
selected when this method is called, the first vertex of the first shape is selected. Valid in
Vertex Sub-Object level.
splineOps.delete <editable_spline_or_line_node_or_modifier>
Deletes the selected sub-objects - valid in all Sub-Object levels.
splineOps.detach <editable_spline_or_line_node_or_modifier>
Displays Detach dialog allowing the user to specify an object name. Valid in all Sub-Object
levels.
splineOps.divide <editable_spline_or_line_node_or_modifier>
Divides the selected segments - valid in Segment Sub-Object level.
splineOps.explode <editable_spline_or_line_node_or_modifier>
Explodes the each segment in the selected splines into separate splines or objects. Valid in
Spline Sub-Object level.
splineOps.hide <editable_spline_or_line_node_or_modifier>
Hides the selected sub-objects - valid in all Sub-Object levels.
splineOps.makeFirst <editable_spline_or_line_node_or_modifier>
Makes the selected vertices the first vertex in the spline- valid in Vertex Sub-Object level.
1088 Chapter 11 | 3ds max Objects

splineOps.mirrorBoth <editable_spline_or_line_node_or_modifier>
Mirrors the selected splines horizontally and vertically – valid in Spline Sub-Object level.
splineOps.mirrorHoriz <editable_spline_or_line_node_or_modifier>
Mirrors the selected splines horizontally – valid in Spline Sub-Object level.
splineOps.mirrorVert <editable_spline_or_line_node_or_modifier>
Mirrors the selected splines vertically – valid in Spline Sub-Object level.
splineOps.reverse <editable_spline_or_line_node_or_modifier>
Reverses the order of vertices in the selected splines – valid in Spline Sub-Object level.
splineOps.unbind <editable_spline_or_line_node_or_modifier>
Unbinds the selected vertices - valid in Vertex Sub-Object level.
splineOps.unhideAll <editable_spline_or_line_node_or_modifier>
Unhides all hidden sub-objects -valid in all Sub-Object levels, and when not in Sub-Object
mode.
splineOps.weld <editable_spline_or_line_node_or_modifier>
Welds the selected vertices - valid in Vertex Sub-Object level.

Patch : GeometryClass
Patches are the general editable versions of all the patch objects, in the same way that Editable
Meshes relate to geometry objects. They are the objects that a patch is converted to when you apply
an Edit Patch modifier and the result of collapsing a modifier stack on a patch base object. While
MAXScript lets you construct patches, there are no properties or methods for accessing or modifying
the sub-objects (vertices, edges, and patches) within the patch object.
Constructor:
patch ...
To create a Patch scene object from scratch, you call the Patch constructor function, for
example:
patch pos:[10,10,10] name:”foo”

This creates an empty patch.

convertTo <node> patch -- mapped
Converts the given scene node to a Patch object. If the object cannot be converted
(typically, if it is not a geometry object), the function returns undefined. Any modifiers
present will be collapsed. The collapseStack() function can also be used as can the
collapse button in the modifier stack dialog in 3ds max; both generate a Patch, but will
only do so if there is at least one modifier present.
 Patch : GeometryClass 1089

Properties:
A control vertex and its tangents are available as properties once a controller has been assigned to
the control vertex. The number of tangents for a control vertex is the number of edges associated
with the control vertex. Controllers can not be assigned to the control vertices using MAXScript in
3ds max 4. If a TriPatch object is collapsed to a SplineShape, and some of its control vertices are
animated, the properties for the control vertices and tangents would be similar to:
$TriPatch01.Vertex_1 Point3 value: [-21.5,-6.4,0] -- animatable
$TriPatch01.Vertex_1_Vector_1 Point3 value: [-21.5,-2.1,0] -- animatable
$TriPatch01.Vertex_1_Vector_2 Point3 value: [-7.1,-6.4,0] -- animatable
$TriPatch01.Vertex_2 Point3 value: [21.5,-6.4,0] -- animatable
$TriPatch01.Vertex_2_Vector_1 Point3 value: [7.1,-6.4,0] -- animatable
$TriPatch01.Vertex_2_Vector_2 Point3 value: [7.1,-2.1,0] -- animatable

See also Class and Object Inspector Functions (p. 799) for details on accessing the patch vertices and
tangents. The controller values assigned to the vertices and tangent handles is in object space. See
the Using Node Transform Properties (p. 843) topic for information on converting between world space
to object space.
Methods:
getPatchSteps <editable_patch_node>
Returns the number of steps the patch uses in the viewports, and reflects the View Steps
spinner in the Modify panel.
setPatchSteps <editable_patch_node> <integer>
Sets the number of View Steps used by the editable patch object to the specified value.
Editable Patch Modify Panel Command Modes and Operations
A suite of methods provide the ability for a script to invoke Editable Patch and Edit Mesh Modify
panel modes and operations, corresponding to buttons available at various mesh sub-object levels.
These methods reside in the patchOps global structure. These methods effectively “push the
button” in the Modify panel. In order to use these methods, the node must be selected and the
Modify panel open. In the description of these methods, the first argument
<editable_patch_node_or_modifier> should be interpreted as either an Editable Patch node
where the modifier stack level is at the base object, or an Edit Patch modifier where the modifier
stack level is at the Edit Patch. In all cases, the following methods work at the current sub-object
level, but only if that level is appropriate for the invoked operation.
The follow methods invoke one of the ‘user-interaction’ button operations in the Editable Patch
Modify panel, acting on the currently selected sub-objects. These methods highlight the
corresponding button in the Geometry rollout and start the operation, at which point the user
interactively completes the operation. These methods return after starting the operation, and before
the user completes the operation, so care should be taken to ensure that your script does not
interfere with the operation. Invoking any of these methods is the same as clicking on the associated
button in the Modify panel. Calling a method when the operation is already in effect (either due to
a user action or a MAXScript command) causes the operation to be terminated and the highlight is
removed from the button.
1090 Chapter 11 | 3ds max Objects

patchOps.startAttach <editable_patch_node_or_modifier>
Enters “Attach” command mode - valid in all Sub-Object levels, and when not in Sub-
Object mode.
patchOps.startBevel <editable_patch_node_or_modifier>
Enters “Bevel” command mode - valid in Patch Sub-Object level.
patchOps.startBind <editable_patch_node_or_modifier>
Enters “Bind” command mode - valid in Vertex Sub-Object level.
patchOps.startCreate <editable_patch_node_or_modifier>
Enters “Create” command mode - valid in Vertex, Patch, and Element Sub-Object levels.
patchOps.startExtrude <editable_patch_node_or_modifier>
Enters “Extrude” command mode - valid in Patch Sub-Object level.
patchOps.startFlipNormalMode <editable_patch_node_or_modifier>
Enters “Flip Normal” command mode - valid in Patch and Element Sub-Object levels.
patchOps.startWeldTarget <editable_patch_node_or_modifier>
Enters “Weld Target” command mode - valid in Vertex Sub-Object level.
The following methods invoke one of the ‘instantaneous’ button operations in the Editable Patch
Modify panel, acting on the currently selected sub-objects:
patchOps.addTri <editable_patch_node_or_modifier>
Adds a TriPatch to the selected edge - valid in Edge Sub-Object level.
patchOps.addQuad <editable_patch_node_or_modifier>
Adds a QuadPatch to the selected edge - valid in Edge Sub-Object level.
patchOps.break <editable_patch_node_or_modifier>
Creates a new vertex for each patch attached to the selected sub-objects - valid in Vertex
and Edge Sub-Object levels.
patchOps.clearAllSG <editable_patch_node_or_modifier>
Clears the smoothing groups on the currently selected patches - valid in Face, Polygon,
and Element Sub-Object levels.
patchOps.createShapeFromEdges <editable_patch_node_or_modifier>
Displays Create Shape dialog allowing the user to specify an object name for the shape to
create from the selected edges. Valid in Edge Sub-Object level.
patchOps.delete <editable_patch_node_or_modifier>
Deletes the selected sub-objects - valid in all Sub-Object levels.
patchOps.detach <editable_patch_node_or_modifier>
Displays Detach dialog allowing the user to specify an object name. Valid in Patch Sub-
Object level.
patchOps.flipNormal <editable_patch_node_or_modifier>
Flips the normal of the selected patches - valid in Patch and Element Sub-Object levels.
patchOps.hide <editable_patch_node_or_modifier>
Hides the selected sub-objects - valid in all Sub-Object levels.
 Patch : GeometryClass 1091

patchOps.selectByID <editable_patch_node_or_modifier>
Display a Select By Material ID dialog and choose patches with the specified material ID -
valid in Patch and Element Sub-Object levels.
patchOps.selectBySG <editable_patch_node_or_modifier>
Display a Select By Smooth Groups dialog and choose patches with the specified
smoothing groupd IDs - valid in Patch and Element Sub-Object levels.
patchOps.selectOpenEdges <editable_patch_node_or_modifier>
Selects all edges with only one patch. Valid in Edge Sub-Object level.
patchOps.subdivide <editable_patch_node_or_modifier>
Divides the selected sub-objects - valid in Edge and Patch Sub-Object levels.
patchOps.unbind <editable_patch_node_or_modifier>
Unbinds the selected vertices - valid in Vertex Sub-Object level.
patchOps.unifyNormal <editable_patch_node_or_modifier>
Unifies the normals of the selected patches - valid in Patch and Element Sub-Object levels.
patchOps.unhideAll <editable_patch_node_or_modifier>
Unhides all hidden sub-objects -valid in all Sub-Object levels, and when not in Sub-Object
mode.
patchOps.weld <editable_patch_node_or_modifier>
Welds the selected vertices - valid in Vertex Sub-Object level.
There is now a new patch function containing a large number of functions for creating,
modifying and accessing patch objects.
The following functions are used to get and set the overall geometry of the patch.
Set keep:true to the setNumXXX functions for them to retain existing vertex/vector/patch/edge
data. This value defaults to false, which cleans out the geometry
patch.getNumVerts <obj> -> integer
patch.setNumVerts <obj> <num> [keep:<boolean>]
patch.getNumVecs <obj> -> integer
patch.setNumVecs <obj> <num> [keep:<boolean>]
patch.getNumPatches <obj> -> integer
patch.setNumPatches <obj> <num> [keep:<boolean>]
patch.getNumEdges <obj> -> integer
patch.setNumEdges <obj> <num> [keep:<boolean>]

The following functions get and set individual vertex and vector handle locations. The vertex and
vector coordinates are interpreted in MAXScript’s current working coordinate context. Consistent
with the rest of MAXScript, all vertex/patch/vector/edge indexes start numbering at 1.
patch.getVert <obj> <index> -> Point3
patch.setVert <obj> <index> <point3>
patch.getVec <obj> <index> -> Point3
patch.setVec <obj> <index> <point3>
1092 Chapter 11 | 3ds max Objects

The following two functions are the main mechanism for creating individual patches in the
patch mesh.
patch.makeQuadPatch <obj> <index> <va> <vab> <vba> <vb> <vbc> <vcb> <vc> <vcd>
<vdc> <vd> <vda> <vad> <i1> <i2> <i3> <i4> <sm>

where:
index = The index of the patch to create (0> = index < numPatches).
va = The first vertex.
vab = Vector ab.
vba = Vector ba.
vb = The second vertex.
vbc = Vector bc.
vcb = Vector cb.
vc = The third vertex.
vcd = Vector cd.
vdc = Vector dc.
vd = The fourth vertex.
vda = Vector da.
vad = Vector ad.
i1 = Interior 1.
i2 = Interior 2.
i3 = Interior 3.
i4 = Interior 4.
sm = The smoothing group mask
patch.makeTriPatch <obj> <index> <va> <vab> <vba> <vb> <vbc> <vcb> <vc> <vca> <vac>
<i1> <i2> <i3> <sm>

where:
index = The index of the patch to create (0> = index < numPatches).
va = The first vertex.
vab = Vector ab.
vba = Vector ba.
vb = The second vertex.
vbc = Vector bc.
vcb = Vector cb.
vc = The third vertex.
vca = Vector ca.
 Patch : GeometryClass 1093

vac = Vector ac.

i1 = Interior 1.
i2 = Interior 2.
i3 = Interior 3.
sm = The smoothing group mask
The following function forces all geometry and topology caches to be rebuilt, change notifications
to be sent and a screen redraw request to be flagged.You must call this function after making any
changes to a path object, before exiting the script. If you make the changes otherwise, an invalid
patch may be passed to MAX, possibly causing a crash. The patch.update() function is similar
in function and purpose to the update() function in mesh object scripting.
patch.update <obj>

The following functions give access to the topology of an existing patch object. They return either
indexes or arrays of indexes of the sub-objects requested. For example, getVertVecs() returns an
array of the vectors coming out of the specified vertex.
patch.getVertVecs <obj> <index> -> integer_array
patch.getVertPatches <obj> <index> -> integer_array
patch.getVertEdges <obj> <index> -> integer_array
patch.getVecVert <obj> <index> -> integer
patch.getVecPatches <obj> <index> -> integer_array
patch.getEdgeVert1 <obj> <index> -> integer
patch.getEdgeVert2 <obj> <index> -> integer
patch.getEdgeVec12 <obj> <index> -> integer
patch.getEdgeVec21 <obj> <index> -> integer

The following functions access and manipulate the texture mapping information in the patch
object.
patch.setNumMaps <obj> <num> [keep:<bool>] ->
patch.getNumMaps <obj> -> integer
patch.setMapSupport <obj> <map_chan> [init:<boolean>] ->
patch.getMapSupport <obj> <map_chan> -> boolean
patch.maxMapChannels <obj> ->
patch.setNumMapVerts <obj> <map_chan> <num> [keep:<boolean>]
patch.getNumMapVerts <obj> <map_index>
patch.setNumMapPatches <obj> <map_chan> <num> [keep:<boolean>]
patch.getMapVert <obj> <map_chan> <index>
patch.setMapVert <obj> <map_chan> <index> <point3>
patch.getMapPatch <obj> <map_chan> <index>
patch.setMapPatch <obj> <map_chan> <index> <index_array>
1094 Chapter 11 | 3ds max Objects

The following functions get and set the material ID for the patch object as a whole or for individual
patches.
patch.getMtlID <obj> -> integer
patch.setMtlID <obj> <mtl_id>
patch.getPatchMtlID <obj> <index> -> integer
patch.setPatchMtlID <obj> <patch_index> <mtl_id>

The following functions access and control viewport and renderer tesselation and visibility.
patch.setMeshSteps <obj> <steps>
patch.getMeshSteps <obj>
patch.setMeshStepsRender <obj> <steps>
patch.getMeshStepsRender <obj>
patch.setShowInterior <obj> <bool>
patch.getShowInterior <obj>
patch.setAdaptive <obj> <bool>
patch.getAdaptive <obj>

The following functions access topology info for the specified sub-object.
patch.getEdges <obj> <v1> [<v2>] -> integer_array
patch.getPatches <obj> <v1> [<v2>] -> integer_array
patch.getVectors <obj> <vert> -> integer_array

The following function transforms all the vertices and vectors in the patch object by the given
matrix. This transform happens in object local space.
patch.transform <obj> <matrix3>

The following functions perform various high-level operations on a patch object:

patch.weldVerts <obj> <threshold> <weldIdentical_bool> <startVert>
patch.weld2Verts <obj> <v1> <v2>
patch.weldEdges <obj>
patch.deletePatchParts <obj> <del_vert_bitarray> <del_patches_bitarray>
patch.clonePatchParts <obj> <patch_bit_array>
patch.subdivideEdges <obj> <propogate>
patch.subdividePatches <obj> <propogate>
patch.addTriPatch <obj>
patch.addQuadPatch <obj>

The following functions get and manipulate surface normal information. Again, normal vectors are
given in MAXScript’s current working coordinate context.
patch.patchNormal <obj> <patch>
patch.edgeNormal <obj> <edge>
patch.updatePatchNormals <obj>
patch.flipPatchNormal <obj> <patch>
patch.unifyNormals <obj>
patch.autoSmooth <obj> <angle> <useSel_bool> <preventIndirectSmoothing_bool>
 Patch : GeometryClass 1095

The following functions access and change the vertex and interior vertex types:
patch.changeVertType <obj> <vert> #corner|#coplanar
patch.getVertType <obj> <vert> -> #corner or #coplanar
patch.changePatchInteriorType <obj> <patch> #automatic|#manual
patch.getPatchInteriorType <obj> <patch> -> #automatic or #manual

The following function returns the current mesh tesselation for the patch object:
patch.getMesh <obj> -> mesh value

The following functions are used to interpolate individual patch surfaces. A tri-patch interpolation
takes u,v,w barycentric coordinates. A quad-patch takes u and c parameters. In both cases, the point
returns is given in the current MAXScript working coordinate context.
patch.interpTriPatch <obj> <patch> <u> <v> <w> -> point3
patch.interpQuadPatch <obj> <patch> <u> <v> -> point3

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Class and Object Inspector Functions (p. 799)
Scripting Vertex and Control Point Animation (p. 1461)

Modifier : MAXWrapper and SpacewarpModifier :

MAXWrapper
The Modifier and SpacewarpModifier families of classes can be created and added to an object’s
modifier stack using the addModifier() or modPanel.addModToSelection() methods. Unless
otherwise noted, the term modifier will be used to mean members of either class.
By making a single modifier and adding it to several objects, you are sharing the modifier between
the objects, as you would by applying a modifier to a selection of objects in the 3ds max user
interface. The constructors in the following classes can take any of the listed properties as optional
keyword arguments with the defaults as shown.
Existing modifiers can be accessed in two ways:
• As a property access on a <node>. When you access a property on a <node> scene object, such
as its name or position, or length, MAXScript will also consider modifiers on the object to be
properties, for example:
$box1.heightsegs -- get creation parameter
$box1.twist -- get the twist modifier
$box1.twist.angle -- the twist’s angle
1096 Chapter 11 | 3ds max Objects

You can then access modifier properties as subproperties on the modifier as shown. If the
modifier name has spaces in it, you can use the ‘_’ as space convention that pathnames use,
like this:
$box1.uvw_map -- to get the ‘UVW Map’ modifier

• This will work in simple situations, but there may be several modifiers with the same name, or
a modifier with the same name as a creation parameter (which is always looked for first). In this
situation you can use the modifier array mechanism, which yields an array of modifiers you can
index into:
$box1.modifiers -- get modifier array
$box1.modifiers[3] -- get the 3rd down the list
$box1.modifiers[#twist] -- get the one named “twist”
$box1.modifiers[”ffd 4x4x4”] -- get the FFD

As you can see from the examples, you can use both name literals and strings to index modifiers
by name in the table, so this is a way to get at modifiers with characters you cannot use in a
MAXScript property name.
The ordering is as you would see in the Modify panel, numbered starting at 1 from
top-to-bottom.
The classes derived directly from the Modifier and SpacewarpModifier classes are described in the
Modifier and SpacewarpModifier Types (p. 1100) topic.
The properties, operators, and methods that are common to all classes derived directly from the
Modifier and SpacewarpModifier classes are described in the Modifier Common Properties, Operators,
and Methods (p. 1096) topic.
The Modifier and SpacewarpModifier classes are derived from the MAXWrapper class, and inherits
the properties and methods defined for that class. These properties and methods are described in the
MAXWrapper Common Properties, Operators, and Methods (p. 809) topic.

Modifier Common Properties, Operators, and Methods

Properties:
All modifiers have the following properties:
<modifier>.name : string
get and set modifier name
<modifier>.enabled : boolean
<modifier>.enabledInViews : boolean
lets you control the modifier’s enabled/disabled state. These are read/write properties that
let you determine and set the enabled state of the given modifier, for example:
$foo.modifiers[2].enabled = false -- turn off 2nd modifier
The enabledInViews property controls viewport display, enabled controls both
viewport and rendered display.
 Patch : GeometryClass 1097

Associated Methods:
The modifier stack on a scene node can be manipulated using the following <node> methods:
validModifier ( <node> | <objectset>) <modifier>
Tests whether a particular modifier may be added the given <node> or <objectset>.
Returns true if so, false if not.
The validModifier() method operates exactly as does the Modify panel in determining
modifier applicability. Any modifier that takes a deformable object will return true for all
scene objects except Helpers. This corresponds to the Modify panel’s behavior of allowing
modifiers such as Bend, Taper, etc. to be applied to lights and cameras, space warp objects,
etc., as well as geometry types like box, sphere, etc., but not helpers such as dummys or
bones.
addModifier <node> <modifier> [before:index] -- mapped
adds the modifier to all instances of the node to which the function is applied. The
optional before: keyword argument can be used to insert the modifier into the node’s
modifier stack just before the indexed modifier, counting from the top of the stack. The
added modifier will apply to any appropriate active sub-object selection in the node only if
the node is currently selected and open in the Modify panel at the desired sub-object level.
You can use the 3ds max System global variable, subObjectLevel to test and set the level
for the object currently open in the Modify panel. For example:
max modify mode -- open mod panel
select $box01 -- select box01 into mod panel
subObjectLevel = 3 -- subobject level to Face
addModifier $box01 (ffd_2x2x2()) -- add FFD mod to those faces

If the before: keyword argument would place a modifier in an invalid position in the
stack, the modifier will be placed at the nearest valid position. For example, if you tried to
place a SpacewarpModifier class object below a Modifier class object, the
SpacewarpModifier object would be placed below any SpacewarpModifier objects, and
above any Modifier objects.
If <node> is a collection, an instance of the modifier is placed on each of the nodes in the
collection. Unlike interactively applying a modifier to a selection, the position and size of
each modifier instance’s gizmo corresponds to position and size of the node the modifier
instance is applied to. To apply a modifier to a collection in the same manner that 3ds max
applies modifiers, use the modPanel.addModToSelection() described in the Modify
Panel (p. 1572) topic.
A limitation of the addModifier() function is that it cannot generally apply modifiers to
sub-object selections, and so it disables any current sub-object levels. To apply a modifier
to a sub-object selection in the same manner that 3ds max applies modifiers, use the
modPanel.addModToSelection(). This function correctly observes the currently
selected sub-object level in the Modify panel.
1098 Chapter 11 | 3ds max Objects

deleteModifier <node> <modifier_or_index>

lets you delete modifiers from the modifier stack. Takes either a modifier value present on
the <node> stack, or an index specifying the index of the modifier to delete, counting
from the top of the stack.
collapseStack <node> -- mapped
collapses the modifiers out of a stack, leaving the appropriate resultant editable base class,
such as Editable Mesh, Editable Spline, NURBS Surface, etc., as the base object of the node.
If there are no modifiers in the stack when this is called, no action is taken. If you want to
force a stack collapse or conversion to editable base class form, use one of the node
conversion functions, such as convertToMesh(),convertToSplineShape(), etc. See
the methods section in Node Common Properties, Operators, and Methods (p. 820) for more
details.
getModContextTM <node> <modifier>
Returns a Matrix3 value giving the modifier’s context transform for the local coordinates
used in modifier sub-object gizmos. Accessing the transform properties of a modifier sub-
object such as a gizmo or a center in MAXScript yields values that are relative to that
modifier’s context transform, equivalent to the values shown in track view for those
properties. If the modifier is not operating on a sub-object selection, such as a face or
vertex selection, or if the modifier was interactively applied to an object selection, this
context TM is the local coordinate space of the object itself. However, if the modifier is
operating on either an object selection set or a sub-object selection, the context transform
gives the position and orientation of that selection, and so you can use
getModContextTM() to get the world-space transform properties of any of its sub-objects.
getModContextBBoxMin <node> <modifier>
getModContextBBoxMax <node> <modifier>
These functions complement the getModContextTM() function and can be used to derive
the world-space coordinates of the bounding box of the modifier context. This can be
used, for example, to determine the bounds of a modifier operating on a sub-selection or
the bounds of an FFD lattice. This is particularly useful for scripting FFD control point
placement, since these control points live in a 0-to-1 lattice space--the mod context
bounding box gives the world space bounds of this lattice space allowing you to compute
scaled lattice space coordinates from world coordinates. The functions return Point3
values for the minimum and maximum extents of the bounding box.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Modifier Sub-Object Transform Properties (p. 1099)
 Modifier Sub-Object Transform Properties 1099

Modifier Sub-Object Transform Properties

In MAXScript, the values of modifier sub-object transform properties, such as centers and gizmo
position, rotation and scale, are not given in the current working coordinate system, but rather are
typically in the coordinate system of the object to which it is applied. This is in contrast to scene
node transform properties. The values given are exactly as would be seen in the sub-object’s
corresponding track view or as might be referenced in an Expression controller track variable for that
sub-object property. To convert from local to world coordinates, you multiply the local coordinates
by the node’s objecttransform matrix. To convert from world to local coordinates, you multiple
the world coordinates by the inverse of the node’s objecttransform matrix. For example:
obj=box pos:[10,20,30]
addModifier obj (affect_region())
objTM=obj.objecttransform
modTM=getModContextTM obj obj.affect_region

-- calculate world coordinates of end point

obj.affect_region.end_point * (inverse modTM) * objTM

-- set end point at world coordinates [20,20,0]

obj.affect_region.end_point = [20,20,0] * modTM * (inverse objTM)

FFD Control Points

FFD control point sub-object properties are also accessible but have several special considerations.
The control points properties are named as they appear in the track view, subject to the MAXScript
convention of using ‘_’ underscores for spaces, so for example:
$foo.ffd_2x2x2.control_point_1
$baz.ffd_3x3x3.control_point_32 = [1,2,3]

There are two special considerations when accessing FFD control points. First, you can only access
control points that have ALREADY been animated by hand, or by using the animateVertex() or
the animateAll() MAXScript functions (see the Scripting Vertex and Control Point Animation
(p. 1461) topic). The FFD doesn’t actually create accessible control points until you do this, a
behavior that shows up in the track view in normal 3ds max use - you cannot actually place control
point keyframes in the track view until you’ve animated the control point.
Second, control point coordinates are in FFD lattice space. This is a normalized space, with [0,0,0] at
the lower left-hand corner (at control_point_1) and [1,1,1] at the opposite corner of the FFD lattice,
so you have to be careful about computing and scaling correct coordinates when you set them. This
is also reflected in the track view for FFD control points in normal 3ds max use - if you look at their
values in a keyframe property dialog or a function graph, they are in this normalized lattice space,
not world-space coordinates. You’d have to work in this space also if you tried to use expression
controllers to control FFDs. The modifier utility functions getModContextBBoxMin() and
getModContextBBoxMin() can be used to determine the world-space bounds of an FFD lattice
allowing you to compute scaled lattice space coordinates from world coordinates. See details on
these functions in the Modifier Common Properties, Operators, and Methods (p. 1096) topic. An example
1100 Chapter 11 | 3ds max Objects

of accessing and converting coordinate systems for FFD control points is shown in the following
script:
b=box pos:[10,20,0]
ffd=ffdbox()
addModifier b ffd
animateVertex ffd 64
cp64posL=ffd.control_point_64
objTM=b.objecttransform
modTM=(getModContextTM b ffd)*ffd.lattice_transform.value
modBBMin=getModContextBBoxMin b ffd
modBBMax=getModContextBBoxMax b ffd
cp64posW=(modBBMin+(cp64posL*(modBBMax-modBBMin)) * (inverse modTM) * objTM

Modifier and SpacewarpModifier Types

The following list shows the 3ds max Modifier and SpacewarpModifier class objects:
-- Modifier
Affect_Region (p. 1103)
Bend (p. 1104)
Bevel (p. 1106)
Bevel_Profile (p. 1108)
CameraMap (p. 1109)
Cap_Holes (p. 1110)
CrossSection (p. 1110)
DeleteMesh (p. 1111)
DeleteSpline (p. 1111)
Disp_Approx (p. 1111)
Displace_Mesh (p. 1198)
Edit_Mesh (p. 1114)
Edit_Patch (p. 1115)
Edit_Spline (p. 1115)
Extrude (p. 1115)
Face_Extrude (p. 1127)
FFDBox (p. 1117)
FFDCyl (p. 1119)
FFD_2x2x2 (p. 1121)
FFD_3x3x3 (p. 1123)
FFD_4x4x4 (p. 1124)
 Modifier Sub-Object Transform Properties 1101

FFD_Select (p. 1126)

Fillet_Chamfer (p. 1127)
Flex (p. 1128)
Lathe (p. 1133)
Lattice (p. 1135)
Linked_XForm (p. 1136)
MaterialByElement (p. 1136)
Material (p. 1137)
Melt (p. 1138)
MeshSmooth (p. 1139)
Mesh_Select (p. 1142)
Mirror (p. 1143)
Morpher (p. 1144)
NCurve_Sel (p. 1145)
Noise (p. 1145)
Normalize_Spline (p. 1146)
Normal (p. 1147)
NSurf_Sel (p. 1147)
Optimize (p. 1148)
PatchDeform (p. 1150)
PathDeform (p. 1151)
Preserve (p. 1152)
Push (p. 1153)
Relax (p. 1154)
Ripple (p. 1154)
Skew (p. 1155)
Skin (p. 1157)
Slice (p. 1165)
Smooth (p. 1166)
Spherify (p. 1167)
SplineSelect (p. 1167)
Squeeze (p. 1167)
STL_Check (p. 1169)
Stretch (p. 1170)
1102 Chapter 11 | 3ds max Objects

Surface (p. 1171)

SurfDeform (p. 1171)
Taper (p. 1173)
Tesselate (p. 1174)
Trim_Extend (p. 1175)
Twist (p. 1175)
Unwrap_UVW (p. 1176)
UVWMap (p. 1188)
UVW_XForm (p. 1187)
Vertex_Colors (p. 1191)
VertexPaint (p. 1191)
VolumeSelect (p. 1192)
Wave (p. 1194)
XForm (p. 1195)
-- SpacewarpModifier
The SpacewarpModifier classes are separated into two groups. The first group are those classes that
bind a node to a SpaceWarp (p. 992) node. The SpacewarpModifier classes in this group are not
directly created in MAXScript, but are rather created and applied to a node using the
bindSpaceWarp() method. The second group are those SpacewarpModifier classes that are created
and applied to a node like any other modifier.
-- Spacewarp Binding SpacewarpModifiers
SimpleOSMToWSMMod (p. 1196)
BombBinding (p. 1196)
DeflectorBinding (p. 1196)
DisplaceBinding (p. 1196)
FFD_Binding (p. 1196)
GravityBinding (p. 1196)
MotorMod (p. 1196)
PathFollowMod (p. 1196)
PBombMod (p. 1196)
PDynaFlectMod (p. 1196)
POmniFlectMod (p. 1196)
PushMod (p. 1196)
RippleBinding (p. 1196)
SDeflectMod (p. 1196)
 Affect_Region : Modifier 1103

SDynaFlectMod (p. 1196)

SOmniFlectMod (p. 1196)
SpaceConform (p. 1196)
UDeflectorMod (p. 1196)
UDynaFlectMod (p. 1196)
UOmniFlectMod (p. 1196)
WaveBinding (p. 1196)
WindBinding (p. 1196)
-- Other SpacewarpModifiers
Displace_Mesh (p. 1198)
Displace_NURBS (p. 1198)
MapScaler (p. 1198)
SpaceCameraMap (p. 1199)
SpacePatchDeform (p. 1199)
SpacePathDeform (p. 1200)
SpaceSurfDeform (p. 1201)
Surface_Mapper (p. 1202)

Modifiers

Affect_Region : Modifier
Constructor:
affect_region ...

Properties:
<Affect_Region>.falloff Float default: 20.0 -- animatable
Distance in current units from the center to the edge of a sphere defining the affected
region. Use higher falloff settings to achieve more gradual slopes, depending on the scale
of your geometry.
<Affect_Region>.Pinch Float default: 0.0 -- animatable
Raises and lowers the top point of the curve along the vertical axis. Sets the relative
“pointedness” of the region. When negative, a crater is produced instead of a point. At a
setting of 0, Pinch produces a smooth transition across this axis.
1104 Chapter 11 | 3ds max Objects

<Affect_Region>.Bubble Float default: 0.0 -- animatable

Expands and contracts the curve along the vertical axis. Sets the relative “fullness” of the
region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for
Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble
move the bottom of the curve below the surface, creating a “valley” around the base of the
region.
<Affect_Region>.ignoreBackfacing Booleandefault: off
When on, affects only those vertices whose face normals are in the same general direction
as the gizmo arrow. When turned off, all vertices in the Falloff group are affected.
<Affect_Region>.start_point Point3 default: [0,0,0] -- animatable
The starting point for the application of the affect region.
<Affect_Region>.end_point Point3 default: [0,0,25] – animatable
The end point for application of the affect region.
Methods:
AffectRegionVal <distance> <falloff> <pinch> <bubble>
The standard affect region function, based on a distance and the three affect region
parameters (same as the editable mesh). This function is a cubic curve which returns 1 at
distance 0, 0 if distance is greater than falloff, and other values for distance between 0 and
falloff.
Note:
The Ignore Back Facing property is not accessible to MAXScript in 3ds max 4.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Bend : Modifier
Constructor:
bend ...

Properties:
<Bend>.angle Float default: 0.0 -- animatable
The angle to bend from the vertical plane.
<Bend>.direction Float default: 0.0 -- animatable
The direction of the bend relative to the horizontal plane.
 Bend : Modifier 1105

<Bend>.axis Integer default: 2

Specifies the axis to be bent. Note that this axis is local to the Bend gizmo and not related
to the selected entity:
X
Y
Z
<Bend>.limit Boolean default: false
When on, applies limit constraints to the bend effect.
<Bend>.upperlimit Float default: 0.0 -- animatable, alias: Upper_Limit
The upper boundary in world units from the bend center point beyond which the bend no
longer affects geometry.
<Bend>.lowerlimit Float default: 0.0 -- animatable, alias: Lower_Limit
The lower boundary in world units from the bend center point beyond which the bend no
longer affects geometry.
<Bend>.center Point3 default: [0,0,0] -- animatable
You can translate and animate the center, altering the Bend gizmo’s shape, and thus the
shape of the bent object.
<Bend>.gizmo SubAnim
You can transform and animate the gizmo like any other object, altering the effect of the
Bend modifier.
<Bend.gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the gizmo object. Translating the gizmo translates its center an equal
distance.
<Bend.gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the gizmo object. Rotating the gizmo takes place with respect to its center.
<Bend.gizmo>.scale Point3 default: [1,1,1] -- animatable
The scaling of the gizmo object. Scaling the gizmo takes place with respect to its center.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1106 Chapter 11 | 3ds max Objects

Bevel : Modifier
Constructor:
bevel ...

Properties:
<Bevel>.Cap_Bottom Integer default: 1
When on, caps the end with the lowest local Z value (bottom) of the object. When turned
off, the bottom is open.
OFF
ON
<Bevel>.Cap_Top Integer default: 1
When on, caps the end with the highest local Z value (top) of the object. When turned off,
the end is left open.
OFF
ON
<Bevel>.Cap_Type Integer default: 0
Sets cap type:
Morph (Creates cap faces suitable for morphing.)
Grid (Creates cap faces in a grid pattern. This cap type deforms and renders better than
morph capping.)
<Bevel>.Side_Type Integer default: 0
Side type:
Linear Sides (Segment interpolation between levels follows a straight line.)
Curved Sides (Segment interpolation between levels follows a Bezier curve.)
<Bevel>.segments Integer default: 1 -- animatable
The number of intermediate segments between each level.
<Bevel>.Smooth_Levels Integer default: 0
Controls whether smoothing groups are applied to the sides of a beveled object. Caps
always use a different smoothing group than the sides. When turned on, smoothing
groups are applied to the sides, and the sides appear rounded. When turned off,
smoothing groups are not applied, and the sides appear as flat bevels.
OFF
ON
<Bevel>.Produce_Mapping_Coords Integer default: 0
When turned on, mapping coordinates are applied to the beveled object.
OFF
ON
 Bevel : Modifier 1107

<Bevel>.Keep_Lines_From_Crossing Integer default: 0

When on, this prevents outlines from crossing over themselves. This is accomplished by
inserting extra vertices in the outline and replacing sharp corners with a flat line segment.
OFF
ON
<Bevel>.Separation_Between_Lines Float default: 1.0 -- animatable
The distance to be maintained between edges.
<Bevel>.Starting_Outline Float default: 0.0 -- animatable
The distance the outline is offset from the original shape. A non-zero setting changes the
original shape’s size. Positive values make the outline larger and negative values make the
outline smaller.
<Bevel>.Level_1_Height Float default: 0.0 -- animatable
The distance of Level 1 above the Start level.
<Bevel>.Level_1_Outline Float default: 0.0 -- animatable
The distance to offset the Level 1 outline from the Start Outline.
<Bevel>.Use_Level_2 Integer default: 0
Adds a level after Level 1 when on.
OFF
ON
<Bevel>.Level_2_Height Float default: 0.0 -- animatable
The distance above Level 1.
<Bevel>.Level_2_Outline Float default: 0.0 -- animatable
The offset distance of the Level 2 outline from Level 1.
<Bevel>.Use_Level_3 Integer default: 0
Adds a level after the previous level. If Level 2 is not on, Level 3 is added after Level 1.
OFF
ON
<Bevel>.Level_3_Height Float default: 0.0 -- animatable
The distance above the previous level.
<Bevel>.Level_3_Outline Float default: 0.0 -- animatable
The offset distance of Level 3 from the previous level.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1108 Chapter 11 | 3ds max Objects

Bevel_Profile : Modifier
Constructor:
bevel_profile ...

Properties:
<Bevel_Profile>.Produce_Mapping_Coords Integer default: 0
When on, assigns UV coordinates.
OFF
ON
<Bevel_Profile>.Cap_Bottom Integer default: 1
When on, caps the end with the lowest local Z value (bottom) of the object. When turned
off, the bottom is open.
OFF
ON
<Bevel_Profile>.Cap_Top Integer default: 1
When on, caps the end with the highest local Z value (top) of the object. When turned off,
the end is left open.
OFF
ON
<Bevel_Profile>.Cap_Type Integer default: 0
Cap type:
Morph (Selects a deterministic method of capping that provides the same number of
vertices for morphing between objects.)
Grid (Creates gridded caps that are better for cap deformations.)
<Bevel_Profile>.Keep_Lines_From_Crossing Integer default: 0
When on, prevents beveled surfaces from self intersecting. This requires more processor
calculation and can be time-consuming in complex geometry.
OFF
ON
<Bevel_Profile>.Separation_Between_Lines Float default: 1.0 -- animatable
The distance that sides should be kept apart to prevent intersections.
<Bevel_Profile>.profile_gizmo SubAnim
You can move, scale, and rotate the gizmo to alter the effect of the bevel profile modifier
on the object.
<Bevel_Profile.Profile_Gizmo>.position Point3 default: [0,0,0] --
animatable
The position of the profile gizmo.
 CameraMap : Modifier 1109

<Bevel_Profile.Profile_Gizmo>.rotation Quat default: (quat 0 0 0 1) --

animatable
The rotation of the profile gizmo.
<Bevel_Profile.Profile_Gizmo>.scale Point3 default: [1,1,1] --
animatable
The scale of the profile gizmo.
Note:
There is no way to set the Profile shape using MAXScript in 3ds max 4.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

CameraMap : Modifier
Constructor:
cameraMap ...

Properties:
There are no additional properties for CameraMap.
Note:
There is no way to set the Camera using MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1110 Chapter 11 | 3ds max Objects

Cap_Holes : Modifier
Constructor:
cap_holes ...

Properties:
<Cap_Holes>.Smooth_New_Faces Integer default: 1
When on, assigns the same smoothing group number to all new faces. If possible, this will
be a smoothing group number not used elsewhere in the object.
OFF
ON
<Cap_Holes>.Smooth_With_Old_Faces Integer default: 0
Smoothes new triangular faces using the smoothing groups from bordering old faces. This
smoothes only one level in from the perimeter of the border of the hole, so you might
need to use both this and the Smooth New Faces option to properly smooth a large hole.
OFF
ON
<Cap_Holes>.Make_All_New_Edges_Visible Integer default: 0
When on, makes all of the edges visible in the new faces.
OFF
ON

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

CrossSection : Modifier
Constructor:
crossSection ...

Properties:
There are no additional properties for CrossSection.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 DeleteMesh : Modifier 1111

DeleteMesh : Modifier
Constructor:
deleteMesh ...

Properties:
There are no additional properties for DeleteMesh.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

DeleteSplineModifier : Modifier
Constructor:
deleteSplineModifier ...

Properties:
There are no additional properties for DeleteSplineModifier.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Disp_Approx : Modifier
Constructor:
disp_Approx ...

Properties:
There are no additional properties for Disp_Approx.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1112 Chapter 11 | 3ds max Objects

Displace : Modifier
Constructor:
displace ...

Properties:
<Displace>.strength Float default: 0.0 -- animatable
When set to 0.0, Displace has no effect. Values greater than 0.0 displace object geometry or
particles away from the position of the gizmo. Values less than 0.0 displace geometry
toward the gizmo.
<Displace>.decay Float default: 0.0 -- animatable
Varies the displacement strength with distance. By default, Displace has the same strength
throughout world space. Increasing Decay causes the displacement strength to diminish as
distance increases from the position of the Displace gizmo. This has the effect of
concentrating the force field near the gizmo, similar to the field around a magnet repelling
its opposite charge.
<Displace>.lumCenterEnable Boolean default: false
When on, the software uses .center to determine which level of gray Displace uses as
the zero displacement value.
<Displace>.center Float default: 0.5 -- animatable, alias:
lumCenter
By default, Displace centers the luminance by using medium (50 percent) gray as the zero
displacement value. Gray values greater than 128 displace in the outward direction (away
from the Displace gizmo) and gray values less than 128 displace in the inward direction
(toward the Displace gizmo). This value adjusts the default. With a Planar projection, the
displaced geometry is repositioned above or below the Planar gizmo.
<Displace>.bitmap Bitmap default: undefined
This bitmap is used for displacement.
<Displace>.map TextureMap default: undefined
This texture map is used for displacement.
<Displace>.blur Float default: 0.0 -- animatable
Blurs or softens the effect of the bitmapped displacement by increasing the value.
<Displace>.maptype Integer default: 0
Type of map projection:
Planar (Projects the map from a single plane.)
Cylindrical (Projects the map as if it were wrapped around the cylinder.)
Spherical (Projects the map from a sphere, with singularities at the top and bottom of the
sphere where the bitmap edges meet at the sphere’s poles.)
Shrink Wrap (Projects the map from a sphere, as Spherical does, but truncates the corners
of the map and joins them all at a single pole, creating only one singularity at the bottom.)
 Displace : Modifier 1113

<Displace>.cap Boolean default: false

When on, a copy of the map is projected from the ends of the cylinder.
<Displace>.length Float default: 1.0 -- animatable
The length of the displace gizmo’s bounding box.
<Displace>.width Float default: 1.0 -- animatable
The width of the displace gizmo’s bounding box.
<Displace>.height Float default: 1.0 -- animatable
The height of the displace gizmo’s bounding box.
Height has no effect on Planar mapping.
<Displace>.U_Tile Float default: 1.0 -- animatable
The number of times the bitmap repeats along the U-axis.
<Displace>.U_Flip Boolean default: false
When on, reverses the orientation of the map along the U-axis.
<Displace>.V_Tile Float default: 1.0 -- animatable
The number of times the bitmap repeats along the V-axis.
<Displace>.V_Flip Boolean default: false
When on, reverses the orientation of the map along the V-axis.
<Displace>.W_Tile Float default: 1.0 -- animatable
The number of times the bitmap repeats along the W-axis.
<Displace>.W_Flip Boolean default: false
When on, reverses the orientation of the map along the W-axis.
<Displace>.useMap Boolean default: false
When on, has Displace use the UV mapping set earlier in the stack. This has no effect if the
object is not mapped.
<Displace>.applyMap Boolean default: false
When on, applies the Displace UV mapping to the bound object. This lets you apply
material maps to the object using the same mapping coordinates as the modifier.
<Displace>.Map_or_Vertex_Color Integer default: 0
Specifies whether to apply the displacement projection to a mapping channel or a vertex
color channel:
Map Channel
Vertex Color Channel
<Displace>.Map_Channel Integer default: 1
The map channel to use for displacement projection.
<Displace>.axis Integer default: 2
Flips the alignment of the mapping gizmo along one of its three axes:
X
Y
Z
1114 Chapter 11 | 3ds max Objects

<Displace>.gizmo SubAnim
You can move, scale, and rotate the gizmo to alter the effect of the displacement modifier
on the object.
<Displace.Gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the displace gizmo.
<Displace.Gizmo>.rotation Quat default: (quat 0 0 -1 0) -- animatable
The rotation of the displace gizmo.
<Displace.Gizmo>.scale Point3 default: [1,1,1] -- animatable
The scaling of the displace gizmo.
Note:
The Gizmo property is not present until the Displace modifier has been applied to a node.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Edit_Mesh : Modifier
Constructor:
edit_mesh ...

Properties:
There are no additional properties for Edit_Mesh.
See the getVertSelection(), getFaceSelection(), and getEdgeSelection() functions in
the Editable_Mesh (p. 1041) topic for information about accessing the current selections in the
Edit_Mesh modifier.
See the Editable Mesh Modify Panel Command Modes and Operations section in the Editable_Mesh
(p. 1041) topic for information on invoking the various Edit_Mesh operations.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Edit_Patch : Modifier 1115

Edit_Patch : Modifier
Constructor:
edit_patch ...

Properties:
There are no additional properties for Edit_Patch.
See the Editable Patch Modify Panel Command Modes and Operations section in the Patch (p. 1088)
topic for information on invoking the various Edit_Patch operations.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Edit_Spline : Modifier
Constructor:
edit_spline ...

Properties:
There are no additional properties for Edit_Spline.
See the Editable Spline Modify Panel Command Modes and Operations section in the SplineShape
(p. 1079) topic for information on invoking the various Edit_Spline operations.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Extrude : Modifier
Constructor:
extrude ...

Properties:
<Extrude>.amount Float default: 25.0 -- animatable
The depth of the extrusion.
<Extrude>.segs Integer default: 1 -- animatable, alias: segments
The number of segments that will be created in the extruded object.
1116 Chapter 11 | 3ds max Objects

<Extrude>.capStart Boolean default: true

When on, generates a flat surface over the start of the extruded object.
<Extrude>.capEnd Boolean default: true
When on, generates a flat surface over the end of the extruded object.
<Extrude>.capType Integer default: 0
Cap type:
Morph (Arranges cap faces in a predictable, repeatable pattern, which is necessary for
creating morph targets. Morph capping can generate long, thin faces that don’t render or
deform as well as grid capping. Use morph capping primarily if you’re extruding multiple
morph targets.)
Grid (Arranges cap faces in a square grid trimmed at the shape boundaries. This method
produces a surface of evenly sized faces that can be deformed easily by other modifiers.
When you choose the Grid capping option, the grid lines are hidden edges rather than
visible edges.)
<Extrude>.output Integer default: 1
Set the output:
Patch (Produces an object that you can collapse to a patch object.)
Mesh (Produces an object that you can collapse to a mesh object.)
NURBS (Produces an object that you can collapse to a NURBS surface.)
<Extrude>.matIDsBoolean default: true
When on, assigns different material IDs to the sides and the caps of the extruded object.
Specifically, the sides receive ID 3, and the caps receive IDs 1 and 2.
<Extrude>.useShapeIDsBooleandefault: false
When on, the software uses the material ID values assigned to segments in the modified
object.
<Extrude>.smoothBoolean default: true
When on, applies smoothing to the extruded shape.
<Extrude>.mapCoords Boolean default: false
Creates the extruded object with mapping coordinates already applied. When Generate
Mapping Coordinates is turned on, additional mapping coordinates are applied to the end
caps placing a single 1 x 1 tile on each cap.
Note:
The Generate Material IDs, Use Shape IDs, and Smooth properties are not accessible to MAXScript
in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 FFDBox : Modifier 1117

FFDBox : Modifier
Constructor:
ffdBox ...

Properties:
<FFDBox>.dispLattice Boolean default: true -- alias: Lattice
Draws lines connecting the control points to make a grid.
<FFDBox>.dispSource Boolean default: false -- alias: Source_Volume
Displays the control points and lattice in their unmodified state.
<FFDBox>.deformType Integer default: 0
deformType = 0 - Only In Volume; 1 - All Vertices
<FFDBox>.falloff Float default: 0.0 -- animatable
Determines the distance from the lattice that the FFD effect will decrease to zero.
<FFDBox>.tension Float default: 25.0 -- animatable
Adjusts the tension of the deformation splines.
<FFDBox>.continuity Float default: 25.0 -- animatable
Adjusts the continuity of the deformation splines.
<FFDBox>.inPoints Boolean default: true -- alias: Inside_Points
Only control points inside the object are affected by Conform to Shape.
<FFDBox>.outPoints Boolean default: true -- alias: Outside_Points
Only control points outside the object are affected by Conform to Shape.
<FFDBox>.offset Float default: 0.05 -- animatable
The distance by which control points affected by Conform to Shape are offset from the
object surface.
<FFDBox>.lattice_transform SubAnim
<FFDBox.lattice_transform>.position Point3 default: [0,0,0] -- animatable
<FFDBox.lattice_transform>.rotation Quat default: (quat 0 0 0 1) -- animatable
<FFDBox.lattice_transform>.scale Point3 default: [1,1,1] -- animatable

Methods:
conformToShape <FFDBox>
conforms the control points of the FFD to the node the FFD is applied to. If an instance of
the FFD modifier has been applied to more than one object, no action is performed.
resetLattice <FFDBox>
resets the control points of the FFD to their default positions.
getDimensions <FFDBox>
setDimensions <FFDBox> <Point3>
Get and set the number of control points for the FFDBox modifier. The first component
value in the Point3 specifies the number of Width control points, the second the number
of Length control points, and the third the number of Height control points. The
minimum value for each component value is 2.
1118 Chapter 11 | 3ds max Objects

animateVertex <FFDBox> <control_point_spec>

Applies controllers to the specified control points of the FFD modifier, where
<control_point_spec> is one of:
<integer_index>
<integer_index_array>
#all

By assigning controllers to the control points, the control points are added to the Master
subAnim and appear as animatables in the Track View, allowing further scripting of the
control points. For example,
animateVertex $box01.modifier[1] #all

The control points to be animated are specified by index number or with the keyword
#all to animate all control points.
See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point
Animation (p. 1461) for details on accessing the control points in an FFD and Modifier Sub-
Object Transform Properties (p. 1099) for details on the coordinate system used for FFD
control points.
animateAll <FFDBox>
Applies controllers to all control points of the FFD modifier.
Note:
The default number of control points in a FFDBox created by MAXScript is 4x4x4.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Class and Object Inspector Functions (p. 799)
Scripting Vertex and Control Point Animation (p. 1461)
Modifier Sub-Object Transform Properties (p. 1099)
 FFDCyl : Modifier 1119

FFDCyl : Modifier
Constructor:
ffdCyl ...

Properties:
<FFDCyl>.dispLattice Boolean default: true -- alias: Lattice
Draws lines connecting the control points to make a grid.
<FFDCyl>.dispSource Boolean default: false -- alias: Source_Volume
Displays the control points and lattice in their unmodified state.
<FFDCyl>.deformType Integer default: 0
Deform type:
Only In Volume (Deforms vertices that lie inside the source volume. Vertices outside the
source volume are not affected.)
All Vertices (Deforms all vertices regardless of whether they lie inside or outside the source
volume depending on the value in the Falloff spinner. The deformation outside the
volume is a continuous extrapolation of the deformation inside the volume. Note that the
deformation can be extreme for points far away from the source lattice.)
<FFDCyl>.falloff Float default: 0.0 -- animatable
Determines the distance from the lattice that the FFD effect will decrease to zero.
<FFDCyl>.tension Float default: 25.0 -- animatable
Adjusts the tension of the deformation splines.
<FFDCyl>.continuity Float default: 25.0 -- animatable
Adjusts the continuity of the deformation splines.
<FFDCyl>.inPoints Boolean default: true -- alias: Inside_Points
Only control points inside the object are affected by Conform to Shape.
<FFDCyl>.outPoints Boolean default: true -- alias: Outside_Points
Only control points outside the object are affected by Conform to Shape.
<FFDCyl>.offset Float default: 0.05 -- animatable
The distance by which control points affected by Conform to Shape are offset from the
object surface.
<FFDCyl>.lattice_transform SubAnim

<FFDCyl.lattice_transform>.position Point3 default: [0,0,0] -- animatable

<FFDCyl.lattice_transform>.rotation Quat default: (quat 0 0 0 1) -- animatable
<FFDCyl.lattice_transform>.scale Point3 default: [1,1,1] -- animatable
1120 Chapter 11 | 3ds max Objects

Methods:
conformToShape <FFDCyl>
conforms the control points of the FFD to the node the FFD is applied to. If an instance of
the FFD modifier has been applied to more than one object, no action is performed.
resetLattice <FFDCyl>
resets the control points of the FFD to their default positions.
getDimensions <FFDCyl>
setDimensions <FFDCyl> <Point3>
sets the number of control points for the FFDCyl modifier. The first component value in
the Point3 specifies the number of Side control points, the second the number of Radial
control points, and the third the number of Height control points. The minimum
component values are 6, 2, and 2, respectively.
animateVertex <FFDCyl> <control_point_spec>
Applies controllers to the specified control points of the FFD modifier, where
<control_point_spec> is one of:
<integer_index>
<integer_index_array>
#all

By assigning controllers to the control points, the control points are added to the Master
subAnim and appear as animatables in the Track View, allowing further scripting of the
control points. For example,
animateVertex $box01.modifier[1] #all

The control points to be animated are specified by index number or with the keyword
#all to animate all control points.
See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point
Animation (p. 1461) for details on accessing the control points in an FFD and Modifier Sub-
Object Transform Properties (p. 1099) for details on the coordinate system used for FFD
control points.
animateAll <FFDCyl>
Applies controllers to all control points of the FFD modifier.
Note:
The default number of control points in a FFDCyl created by MAXScript is always 4x6x4.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Class and Object Inspector Functions (p. 799)
 FFD_2x2x2 : Modifier 1121

Scripting Vertex and Control Point Animation (p. 1461)

Modifier Sub-Object Transform Properties (p. 1099)

FFD_2x2x2 : Modifier
Constructor:
ffd_2x2x2 ...

Properties:
<FFD_2x2x2>.dispLattice Boolean default: true -- alias: Lattice
Draws lines connecting the control points to make a grid.
<FFD_2x2x2>.dispSource Boolean default: false -- alias: Source_Volume
Displays the control points and lattice in their unmodified state.
<FFD_2x2x2>.deformType Integer default: 0
Deform type:
Only In Volume (Deforms vertices that lie inside the source volume. Vertices outside the
source volume are not affected.)
All Vertices (Deforms all vertices, regardless of whether they lie inside or outside the source
volume.)
<FFD_2x2x2>.inPoints Boolean default: true -- alias: Inside_Points
Only control points inside the object are affected by Conform to Shape.
<FFD_2x2x2>.outPoints Boolean default: true -- alias: Outside_Points
Only control points outside the object are affected by Conform to Shape.
<FFD_2x2x2>.offset Float default: 0.05 -- animatable
The distance by which control points affected by Conform to Shape are offset from the
object surface.
<FFD_2x2x2>.lattice_transform SubAnim

<FFD_2x2x2.lattice_transform>.position Point3 default: [0,0,0] --

animatable
<FFD_2x2x2.lattice_transform>.rotation Quat default: (quat 0 0 0 1) --
animatable
<FFD_2x2x2.lattice_transform>.scale Point3 default: [1,1,1] --
animatable

Note:
The Falloff, Tension, and Continuity parameters are not accessible by MAXScript in 3ds max 4.
1122 Chapter 11 | 3ds max Objects

Methods:
conformToShape <FFD_2x2x2>
conforms the control points of the FFD to the node the FFD is applied to. If an instance of
the FFD modifier has been applied to more than one object, no action is performed.
resetLattice <FFD_2x2x2>
resets the control points of the FFD to their default positions.
animateVertex <FFD_2x2x2> <control_point_spec>
Applies controllers to the specified control points of the FFD modifier, where
<control_point_spec> is one of:
<integer_index>
<integer_index_array>
#all

By assigning controllers to the control points, the control points are added to the Master
subAnim and appear as animatables in the Track View, allowing further scripting of the
control points. For example,
animateVertex $box01.modifier[1] #all

The control points to be animated are specified by index number or with the keyword
#all to animate all control points.
See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point
Animation (p. 1461) for details on accessing the control points in an FFD and Modifier Sub-
Object Transform Properties (p. 1099) for details on the coordinate system used for FFD
control points.
animateAll <FFD_2x2x2>
Applies controllers to all control points of the FFD modifier.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Class and Object Inspector Functions (p. 799)
Scripting Vertex and Control Point Animation (p. 1461)
Modifier Sub-Object Transform Properties (p. 1099)
 FFD_3x3x3 : Modifier 1123

FFD_3x3x3 : Modifier
Constructor:
ffd_3x3x3 ...

Properties:
<FFD_3x3x3>.dispLattice Boolean default: true -- alias: Lattice
Draws lines connecting the control points to make a grid.
<FFD_3x3x3>.dispSource Boolean default: false -- alias: Source_Volume
Displays the control points and lattice in their unmodified state.
<FFD_3x3x3>.deformType Integer default: 0
Deform type:
Only In Volume (Deforms vertices that lie inside the source volume.)
All Vertices (Deforms all vertices, regardless of whether they lie inside or outside the source
volume.)
<FFD_3x3x3>.inPoints Boolean default: true -- alias: Inside_Points
Only control points inside the object are affected by Conform to Shape.
<FFD_3x3x3>.outPoints Boolean default: true -- alias: Outside_Points
Only control points outside the object are affected by Conform to Shape.
<FFD_3x3x3>.offset Float default: 0.05 -- animatable
The distance by which control points affected by Conform to Shape are offset from the
object surface.
<FFD_3x3x3>.lattice_transform SubAnim

<FFD_3x3x3.lattice_transform>.position Point3 default: [0,0,0] --

animatable
<FFD_3x3x3.lattice_transform>.rotation Quat default: (quat 0 0 0 1) --
animatable
<FFD_2x2x2.lattice_transform>.scale Point3 default: [1,1,1] --
animatable

Note:
The Falloff, Tension, and Continuity parameters are not accessible by MAXScript in 3ds max 4.
Methods:
conformToShape <FFD_3x3x3>
conforms the control points of the FFD to the node the FFD is applied to. If an instance of
the FFD modifier has been applied to more than one object, no action is performed.
resetLattice <FFDBox>
resets the control points of the FFD to their default positions.
1124 Chapter 11 | 3ds max Objects

animateVertex <FFD_3x3x3> <control_point_spec>

Applies controllers to the specified control points of the FFD modifier, where
<control_point_spec> is one of:
<integer_index>
<integer_index_array>
#all

By assigning controllers to the control points, the control points are added to the Master
subAnim and appear as animatables in the Track View, allowing further scripting of the
control points. For example,
animateVertex $box01.modifier[1] #all

The control points to be animated are specified by index number or with the keyword
#all to animate all control points.
See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point
Animation (p. 1461) for details on accessing the control points in an FFD and Modifier Sub-
Object Transform Properties (p. 1099) for details on the coordinate system used for FFD
control points.
animateAll <FFD_3x3x3>
Applies controllers to all control points of the FFD modifier.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Class and Object Inspector Functions (p. 799)
Scripting Vertex and Control Point Animation (p. 1461)
Modifier Sub-Object Transform Properties (p. 1099)

FFD_4x4x4 : Modifier
Constructor:
ffd_4x4x4 ...

Properties:
<FFD_4x4x4>.dispLattice Boolean default: true -- alias: Lattice
Draws lines connecting the control points to make a grid.
<FFD_4x4x4>.dispSource Boolean default: false -- alias: Source_Volume
Displays the control points and lattice in their unmodified state.
 FFD_4x4x4 : Modifier 1125

<FFD_4x4x4>.deformType Integer default: 0

Deform type:
Only In Volume (Deforms vertices that lie inside the source volume.)
All Vertices (Deforms all vertices, regardless of whether they lie inside or outside the source
volume.)
<FFD_4x4x4>.inPoints Boolean default: true -- alias: Inside_Points
Only control points inside the object are affected by Conform to Shape.
<FFD_4x4x4>.outPoints Boolean default: true -- alias: Outside_Points
Only control points outside the object are affected by Conform to Shape.
<FFD_4x4x4>.offset Float default: 0.05 -- animatable
The distance by which control points affected by Conform to Shape are offset from the
object surface.
<FFD_4x4x4>.lattice_transform SubAnim

<FFD_4x4x4.lattice_transform>.position Point3 default: [0,0,0] --

animatable
<FFD_4x4x4.lattice_transform>.rotation Quat default: (quat 0 0 0 1) --
animatable
<FFD_4x4x4.lattice_transform>.scale Point3 default: [1,1,1] --
animatable

Note:
The Falloff, Tension, and Continuity parameters are not accessible by MAXScript in 3ds max 4.
Methods:
conformToShape <FFD_4x4x4>
conforms the control points of the FFD to the node the FFD is applied to. If an instance of
the FFD modifier has been applied to more than one object, no action is performed.
resetLattice <FFDBox>
resets the control points of the FFD to their default positions.
animateVertex <FFD_4x4x4> <control_point_spec>
Applies controllers to the specified control points of the FFD modifier, where
<control_point_spec> is one of:
<integer_index>
<integer_index_array>
#all

By assigning controllers to the control points, the control points are added to the Master
subAnim and appear as animatables in the Track View, allowing further scripting of the
control points. For example,
animateVertex $box01.modifier[1] #all
1126 Chapter 11 | 3ds max Objects

The control points to be animated are specified by index number or with the keyword
#all to animate all control points.
See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point
Animation (p. 1461) for details on accessing the control points in an FFD and Modifier Sub-
Object Transform Properties (p. 1099) for details on the coordinate system used for FFD
control points.
animateAll <FFD_4x4x4>
Applies controllers to all control points of the FFD modifier.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Class and Object Inspector Functions (p. 799)
Scripting Vertex and Control Point Animation (p. 1461)
Modifier Sub-Object Transform Properties (p. 1099)

FFD_Select : Modifier
Constructor:
ffd_select ...

Properties:
There are no additional properties for FFD_Select.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Face_Extrude : Modifier 1127

Face_Extrude : Modifier
Constructor:
face_extrude ...

Properties:
<Face_Extrude>.amount Float default: 0.0 -- animatable
The extent of the extrusion.
<Face_Extrude>.scale Float default: 100.0 -- animatable
Scales each cluster of selected faces independently about its center.
<Face_Extrude>.extrude_center Point3 default: [0,0,0] -- animatable; alias:
extrudeFromCenter
Extrudes each vertex radially from the point.
Note:
The Extrude From Center parameter is not accessible by MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Fillet_Chamfer : Modifier
Constructor:
fillet_chamfer ...

Properties:
There are no additional properties for Fillet_Chamfer.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1128 Chapter 11 | 3ds max Objects

Flex : Modifier
Constructor:
flex ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Flex>.flex Float default: 1.0 -- animatable
Sets the amount of flex and bend. Larger values increase the effect. Range=0 to 1000.
<Flex>.strength Float default: 3.0 -- animatable
Sets the spring strength. A value of 100 is rigid. Range=0 to 100.
<Flex>.sway Float default: 7.0 -- animatable
Sets the time for the object to come to rest. Lower values increase the time for the object to
come to rest. Range=0 to 100.
<Flex>.chase Boolean default: true
Turns chase springs on/off.
<Flex>.center Boolean default: true
Turns the use of weights on/off.
<Flex>.solver Integer default: 0
The type of solver that will be used:
Euler Solver
Mid-point solver
Runnge Kutta
The higher the solver number, the more accurate/stable it is, and the slower it will run.
<Flex>.samples Integer default: 5 -- animatable
The number of samples per frame that the solver will use. The higher the number, the
more accurate and stable; at the cost of a slower system.
<Flex>.stretch Float default: 5.0 -- animatable
This parameter slaves to the stretch strength/sway fields. It is normalized then copied to
the strength/sway fields to prevent the system from becoming unstable.
<Flex>.stiffness Float default: 0.1 -- animatable
This parameter slaves to the torque strength/sway fields. It is normalized then copied to
the strength/sway fields to prevent the system from becoming unstable.
<Flex>.paintStrength Float default: 0.1
Sets the amount of weight that the brush leaves on the mesh. Higher values leave more
weight. Range=-1 to 1.
<Flex>.paintRadius Float default: 36.0
Set the size of the brush in world units. Range=.001 to 99999.
<Flex>.paintFeather Float default: 0.7
Set the hardness of the brush. A value of 1 is soft. Range=-1 to 1.
 Flex : Modifier 1129

<Flex>.absolute Boolean default: false

Turn on to change the value of the Vertex Weight parameter to assign absolute weights to
the selected vertices. Turn off to add or remove weight based on the vertices current
weight.
<Flex>.forceNode ArrayParameter default: #() --array containing Force
Nodes; alias: Force_Nodes
Assigns force effect to particle space warps identified in an array.
<Flex>.colliderNode ArrayParameter default: #() -- node array
Array contains a list of collider objects that flex will use.
<Flex>.referenceFrame Integer default: 0 -- alias: Reference_Frame
Flex will start computing at this frame.
<Flex>.endFrame Integer default: 100
Flex will stop computing after this time.
<Flex>.enableEndFrame Boolean default: false
Turns the end frame on/off.
<Flex>.affectAll Boolean default: false
Forces flex to ignore any selection in the stack, causing it to flex the entire object.
<Flex>.enableAdvanceSprings Boolean default: false
Enables the advance spring fields. When this is off, the Stretch and Torque parameters are
slaved to the Stretch and Stiffness parameters.
<Flex>.stretchStrength Float default: 0.2 -- animatable
Controls the strength of stretch springs.
<Flex>.stretchSway Float default: 0.2 -- animatable
Controls the sway of stretch springs.
<Flex>.torqueStrength Float default: 0.2 -- animatable
Controls the strength of torque springs.
<Flex>.torqueSway Float default: 0.2 -- animatable
Controls the sway of torque springs.
<Flex>.holdLength Boolean default: false
Turns on/off the hold length parameter.
<Flex>.holdLengthPercent Float default: 25.0
The maximum percentage the spring can stretch/squash.
<Flex>.addMode Integer default: 0
Flag to determine how springs will be added:
Single spring across selected vertices
Edge Springs
Edge Springs across only selected vertices
Hold Springs
Hold Springs across only selected vertices
<Flex>.displaySprings Booleandefault: false
Turns on/off the display of spring when in sub-object mode.
1130 Chapter 11 | 3ds max Objects

<Flex>.holdRadius Float default: 50.0

The maximum distance that will be looked around when the hold springs are added.
<Flex>.extraStrength ArrayParameter default: #(0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
0.2, 0.2, 0.2, 0.2) -- float array
Control the strength of extra springs (those that belong to a group other than 0 [stretch] or
1 [torque]).
<Flex>.extraSway ArrayParameter default: #(0.2, 0.2, 0.2, 0.2, 0.2, 0.2,
0.2, 0.2, 0.2, 0.2) -- float array
Control the sway of extra springs (those that belong to a group other than 0 [stretch] or 1
[torque]).
<Flex>.lazyEval Boolean default: false
Turns on/off lazy evaluation, which causes the system to be reevaluated less at the expense
of a less accurate display.
<Flex>.springColors ArrayParameter default: #([0,0,1], [0.909091,0,0],
[0.818182,0,0], [0.727273,0,0], [0.636364,0,0], [0.545455,0,0], [0.454545,0,0],
[0.363636,0,0], [0.272727,0,0], [0.181818,0,0], [0.0909091,0,0], [0,0,0]) --
point3 array
The colors for the springs for each group.
<Flex>.customSpringDisplay ArrayParameter default: #(true, true, true, true, true,
true, true, true, true, true, true, true) -- bool array
This boolean array lets you turn on/off the display of the spring group.
<Flex>.createSpringDepth Integer default: 2
The number of times the system is recursed when using create soft body.
<Flex>.createSpringMult Float default: 2.0
The amount the flex effect is multiplied after each recursion when using create soft body.
The following property is defined by Flex, but is not used:
<Flex>.paintBackface Boolean default: true
Flex Methods:
Paint <flex>
Presses the paint button in the flex interface.
SetReference <flex>
Presses the Set Reference button in the flex interface.
Reset <flex>
Presses the Reset button in the flex interface.
AddForce <flex> <force>
Adds a force to the force list.
force (node) - The force to be added to the force list.
RemoveForce <flex> <force>
Removes a force to the force list.
force (integer) - The index of the force to be removed. If this index = -1 then the selected
force will be removed.
 Flex : Modifier 1131

NumberVertices <flex>
Returns and integer containing the number of points in the system.
SelectVertices <flex> <sel> <update>
Selects the vertices passed in sel.
Sel (bitarray) - The bitarray that holds the selection.
Update (boolean) - Determines whether the viewports get updated.
GetSelectedVertices <flex>
Returns bitarray containing the current selected vertices.
GetVertexWeight <flex> <index>
Returns the weight of a specific vertex.
index (integer) - The index of the vertex you want to get the weight of.
SetVertexWeight <flex> <Index_tab> <values_tab>
Sets the weight of vertices. These tables should be the same size.
index_tab (integer table) - A table of indices of the vertex you want to set the weight of.
values_tab (float table) - A table of values containing the weights.
SetEdgeList <flex> <sel> <update>
Sets the edges to sel.
Sel (bitarray) - The bitarray that holds the edge selection.
Update (boolean) - Determines whether the viewports get updated.
GetEdgeList <flex>
Returns bitarray containing the current edge selection list.
AddSpringFromSelection <flex> <flag> <addDupes>
This creates one spring between 2 selected vertices that belong to a group.
flag (integer) - The group that this spring will belong to.
addDupes (boolean) - Will add duplicates if true.
addSpring <flex> <a> <b> <flag> <addDupes>
This creates a spring between the 2 specified vertices.
a (integer) - Index of vertex of the start of the spring.
b (integer) - Index of the vertex of the end of the spring.
flag (integer) - Group springs belongs to (0 to12).
addDupes (boolean) – When true, if there is a duplicate spring it will be added.
removeAllSprings <flex>
Removes all the springs the in the system.
addSpringButton <flex>
Equivalent of hitting the Add Spring button in the interface.
RemoveSpringButton <flex>
Equivalent of hitting the Remove Spring button in the interface.
optionsButton <flex>
Equivalent of hitting the Options button in the interface.
1132 Chapter 11 | 3ds max Objects

createSimpleSoftButton <flex>
Equivalent of hitting the Create Simple Soft Bodies button in the interface.
RemoveSpringByEnd <flex> <a>
This removes all springs that are connected to a vertex.
a (integer) – The vertex index to be checked.
removeSpringByEnds <flex> <a> <b>
This removes all springs that are connected to both vertex a and b.
a (integer) – First vertex index.
b (integer) – Second vertex index.
removeSpringByIndex <flex> <index>
Remove a spring from the list which is at index in the spring list.
index (integer) – Index of the spring.
numberSprings <flex>
Returns the number of springs in the system
getSpringGroup <flex> <index>
Returns the group that the spring belongs to.
index (integer) – Index of the spring you want to examine.
setSpringGroup <flex> <index> <group>
Sets the spring’s groups.
index (integer) – Index of the spring.
group (integer) – The group number (0-12).
getSpringLength <flex> <index>
Gets the rest length of a particular spring.
index (integer) – Index of the spring that you want to examine.
setSpringLength <flex> <index> <length>
Sets the rest length of a particular spring.
index (integer) – Index of the spring that you want to examine.
length (float) – The rest length of the spring.
getIndex <flex> <a> <b>
Returns the index of a spring that uses vertex a and b.
a (integer) – Index of the start vertex of the spring.
b (integer) – Index of the start end of the spring.
FlexOps Methods:
flexOps.GetNumberVertices <Flex>
Returns the number of vertices in the object the Flex modifier is applied to.
flexOps.GetVertexWeight <Flex> <vertex_index_integer>
Returns the weight of the specified vertex.
flexOps.SelectVertices <Flex> \
( <vertex_index_integer> | <index_integer_array> | <bitarray> )
 Lathe : Modifier 1133

Selects the specified vertices. Clears any previously selected vertices.

flexOps.isEdgeVertex <Flex> <vertex_index_integer>
Returns 0 if the specified vertex is not an edge vertex, 1 if it is an edge vertex.
flexOps.ClearEdgeVertices <Flex> \
( <vertex_index_integer> | <index_integer_array> )
Sets the specified vertices to not be edge vertices.
flexOps.SetEdgeVertices <Flex> \
( <vertex_index_integer> | <index_integer_array> )
Sets the specified vertices to be edge vertices.
flexOps.SetVertexWeights <Flex> \
( <vertex_index_integer> | <index_integer_array> ) \
( <weight_integer> | <weight_integer_array> )
Assigns the specified weights to the specified vertices. If the vertices and weights are
specified as arrays, the arrays must be of equal size.
Note:
If deferred plug-in loading is enabled, an instance of the Flex modifier must be created before these
methods will be visible. This is because these methods are defined in the Flex modifier plug-in.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Lathe : Modifier
Constructor:
lathe ...

Properties:
<Lathe>.degrees Float default: 360.0 -- animatable, angle
Determines the number of degrees that the object is spun around the axis of revolution (0
to 360, default=360). You can set keyframes for Degrees to animate the circular growth of a
lathed object. The Lathe axis auto-sizes itself to the height of the shape being lathed.
<Lathe>.weldCore Boolean default: false
When on, simplifies the mesh by welding together vertices that lie on the axis of
revolution.
<Lathe>.flipNormals Boolean default: false
Depending on the direction of the vertices on your shape, and the direction of rotation,
the lathed object might be inside out. Toggle this value to fix this.
<Lathe>.segs Integer default: 16 -- animatable, alias: segments
Determines how many interpolated segments are created in the surface between the start
and endpoint.
1134 Chapter 11 | 3ds max Objects

<Lathe>.capStart Boolean default: false

Caps the start of the lathed object with Degrees set to less than 360 and a closed shape.
<Lathe>.capEnd Boolean default: false
Caps the end of the lathed object with Degrees set to less than 360 and a closed shape.
<Lathe>.capType Integer default: 0
Cap type:
Morph (Arranges cap faces in a predictable, repeatable pattern necessary for creating
morph targets. Morph capping can generate long, thin faces that don’t render or deform as
well as grid capping. Use morph capping primarily if you are lathing multiple morph
targets.)
Grid (Arranges cap faces in a square grid trimmed at the shape boundaries. This method
produces a surface of evenly sized faces that can easily be deformed by other modifiers.)
<Lathe>.output Integer default: 1
Output:
Patch (Produces an object that you can collapse to a patch object.)
Mesh (Produces an object that you can collapse to a mesh object.)
NURBS (Produces an object that can be collapsed to a NURBS surface.)
<Lathe>.mapCoords Boolean default: false
When on, applies mapping coordinates to the lathed object. When Degrees is less than
360, and Generate Mapping Coordinates is turned on, additional mapping coordinates are
applied to the end caps, placing a 1 x 1 tile on each cap.
<Lathe>.matIDs Boolean default: true
When on, the software assigns different material IDs to the sides and the caps of the lathed
object. Specifically, the sides receive ID 3, and the caps (when Degrees is less than 360 and
the lathed shape is closed) receive IDs 1 and 2.
<Lathe>.useShapeIDs Boolean default: false
When on, the software uses the material ID values assigned to segments in the object.
<Lathe>.smooth Boolean default: true
When on, applies smoothing to the extruded shape.
<Lathe>.axis SubAnim
At this sub-object level, you can transform and animate the axis of revolution.
<Lathe.axis>.position Point3 default: [0,0,0] --
animatable
Position of the axis of revolution.
<Lathe.axis>.rotation Quat default: (quat -0.707107 0 0 0.707107) -- animatable
Rotation of the axis of revolution.
<Lathe.axis>.scale Point3 default: [1,1,1] --
animatable
Scale of the axis of revolution.
 Lattice : Modifier 1135

Note:
The Flip Normals, Generate Material IDs, and Use Shape IDs properties are not accessible by
MAXScript in 3ds max 4.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Lattice : Modifier
Constructor:
lattice ...

Properties:
<Lattice>.Strut_Radius Float default: 2.0 -- animatable
The radius of the struts.
<Lattice>.Strut_Segments Integer default: 1 -- animatable
The number of segments along the struts. Increase this value when you need to deform or
distort the struts with subsequent modifiers.
<Lattice>.Strut_Sides Integer default: 4 -- animatable
The number of sides around the perimeter of the struts.
<Lattice>.Joint_Radius Float default: 5.0 -- animatable
The radius of the joints.
<Lattice>.Joint_Segs Integer default: 1 -- animatable
The number of segments in the joints. The more segments, the more spherical the joints’
shape.
Note:
The Geometry, Struts Material ID, Struts Ignore Hidden Edges, Struts End Caps, Struts Smooth, Joints
Base Type, Joints Material ID, Joints Smooth, and Mapping Coordinates parameters are not
accessible by MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1136 Chapter 11 | 3ds max Objects

Linked_XForm : Modifier
Constructor:
linked_xform ...

Properties:
<Linked_xform>.Control Node default: undefined
Object that the vertices are linked to. When transformed, the vertices follow.
Note:
While you can assign a node to the Control property in MAXScript, an internal transform in
Linked_XForm is not properly set. This will cause an immediate, undesired offset of the geometry of
the node the modifier is applied to.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

MaterialByElement : Modifier
Constructor:
materialByElement ...

Properties:
<MaterialByElement>.method Integer default: 1
Set method:
Random Distribution (Assigns the materials at random to different elements in the object.)
List Frequency (Determines an approximate relative weight (percentage) for each of up to
eight material ID’s)
<MaterialByElement>.Material_ID_Count Integer default: 2 -- animatable
The minimum number of material IDs to assign. Because material ID assignment is
random, setting it to the number of materials in the multi/sub-object material or higher
doesn’t guarantee that all materials get used.
<MaterialByElement>.Material_ID__1 Float default: 0.5 -- animatable
Approximate relative weight (percentage) for first material ID.
<MaterialByElement>.Material_ID__2 Float default: 0.5 -- animatable
Approximate relative weight (percentage) for second material ID.
<MaterialByElement>.Material_ID__3 Float default: 0.0 -- animatable
Approximate relative weight (percentage) for third material ID.
<MaterialByElement>.Material_ID__4 Float default: 0.0 -- animatable
Approximate relative weight (percentage) for fourth material ID.
 MaterialModifier : Modifier 1137

<MaterialByElement>.Material_ID__5 Float default: 0.0 -- animatable

Approximate relative weight (percentage) for fifth material ID.
<MaterialByElement>.Material_ID__6 Float default: 0.0 -- animatable
Approximate relative weight (percentage) for sixth material ID.
<MaterialByElement>.Material_ID__7 Float default: 0.0 -- animatable
Approximate relative weight (percentage) for seventh material ID.
<MaterialByElement>.Material_ID__8 Float default: 0.0 -- animatable
Approximate relative weight (percentage) for eighth material ID.
<MaterialByElement>.Random_Seed Integer default: 12345
The seed value for the (pseudo-)randomization of material ID assignments.
Note:
Material_ID values are shown as percentages in the 3ds max user interface, but stored as fractions.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

MaterialModifier : Modifier
Constructor:
materialModifier ...

Properties:
<Materialmodifier>.materialid Integer default: 1 -- animatable, alias:
Material_ID
The material ID to be assigned. If the input object is in face sub-selection, then the ID is
only applied to selected faces, otherwise it is applied to the entire object. The ID number
refers to one of the materials in a multi/sub-object material.
Note:
The default modifier name used when creating a MaterialModifier modifier is “material”. If you then
try to access the modifier as a property of the node it is applied to, a name conflict occurs with the
material property of nodes. To prevent this conflict, you should specify a name during
MaterialModifier creation. For example:
addModifier myObj (materialModifier materialID:5 name:”MaterialMod”)

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1138 Chapter 11 | 3ds max Objects

Melt : Modifier
Constructor:
melt ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Melt>.Melt_Amount Float default: 0.0 -- animatable
The extent of the “decay,” or melting effect applied to the gizmo, thus affecting the object.
<Melt>.Spread Float default: 19.0 -- animatable
Specifies how much the object and melt will spread as the Amount value increases. It’s
basically a “bulge” along a flat plane.
<Melt>.Solidity_Preset Integer default: 0
The relative height of the center of the melted object. Less-solid substances like jelly tend
to settle more in the center as they melt. This group provides several presets for different
types of substances, as well as a Custom spinner for setting your own solidity:
Ice (The default Solidity setting.)
Glass (Uses a high Solidity setting to simulate glass.)
Jelly (Causes a significant drooping effect in the center.)
Custom (Sets any solidity between 0.2 and 30.0.)
<Melt>.Solidity_Custom_Value Float default: 1.0 -- animatable
Custom solidity value.
<Melt>.axis Integer default: 0
The axis (local to the object) on which the melt will occur. Note that this axis is local to
the Melt gizmo and not related to the selected entity.
Z
Y
X
<Melt>.Negative_Axis Integer default: 0
Normally, the melt occurs from the positive direction toward the negative along a given
axis. Turn on Flip Axis to reverse this direction.
Don’t Flip Axis
Flip Axis
<Melt>.center Point3 default: [0,0,0]
The center of the melt gizmo.
<Melt>.gizmo SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object,
altering the effect of the Melt modifier.
<Melt.gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the gizmo. Translating the gizmo translates its center an equal distance.
 MeshSmooth : Modifier 1139

<Melt.gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the gizmo. Rotating the gizmo takes place with respect to its center.
<Melt.gizmo>.scale Point3 default: [1,1,1] -- animatable
The scaling of the gizmo. Scaling the gizmo takes place with respect to its center.
The following properties are defined by Melt, but are not used:
<Melt>.cut_Off__obsolete Float default: 0.0 -- animatable
<Melt>.Confine_To_Gizmo Integer default: 0

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

MeshSmooth : Modifier
Constructor:
meshSmooth ...

Properties:
<MeshSmooth>.subdivMethod Integer default: 2
Selects the Subdivision method to use:
Classic (Produces three- and four-sided facets.)
Quad Output (Produces only four-sided facets.)
NURMS (Produces Non-Uniform Rational MeshSmooth object.)
<MeshSmooth>.Apply_To_Whole_Mesh Boolean default: true
When turned on, any sub-object selection passed up the stack is ignored and MeshSmooth
is applied to the entire object. Note that the sub-object selection is still passed up the stack
to any subsequent modifiers.
<MeshSmooth>.ignoreSel Boolean default: true
When turned on, any sub-object selection passed up the stack is ignored and MeshSmooth
is applied to the entire object.
<MeshSmooth>.oldMapping Boolean default: false
Uses the algorithm from the previous release of the program to apply MeshSmooth to the
mapping coordinates. This technique tends to distort the underlying mapping coordinates
as it creates new faces and as texture coordinates shift.
<MeshSmooth>.iterations Integer default: 0 -- animatable
The number of iterations used to smooth the mesh. Each iteration generates new faces
using the vertices created from the previous iteration.
1140 Chapter 11 | 3ds max Objects

<MeshSmooth>.smoothness Float default: 1.0 -- animatable; alias:

smoothness_filter
Determines how sharp a corner must be before faces are added to smooth it. Smoothness is
calculated as the average angle of all edges connected to a vertex. A value of 0.0 prevents
the creation of any faces. A value of 1.0 adds faces to all vertices even if they lie on a plane.
<MeshSmooth>.useRenderIterations Boolean default: false; alias:
use_render_iterations
Turn on/off use of render iterations, for using a different number of iterations at render
time. When off, the software will use the iterations value.
<MeshSmooth>.renderIterations Integer default: 0 -- animatable; alias:
render_iterations
Number of smoothing iterations to be applied to the object at render time.
<MeshSmooth>.useRenderSmoothness Boolean default: false; alias:
use_render_smoothness
Turn on/off use of render smoothness, for using a different smoothness value at render
time. When off, the software will use the smoothness value.
<MeshSmooth>.renderSmoothness Float default: 1.0 -- animatable;
alias: render_smoothness
Lets you choose a different Smoothness value to be applied to the object at render time.
<MeshSmooth>.ignoreBackfacing Boolean default: false
When on, selection of sub-objects selects only those sub-objects whose normals are visible
in the viewport. When off (the default), selection includes all sub-objects, regardless of the
direction of their normals.
<MeshSmooth>.controlLevel Integer default: 0
Allows you to see the control mesh after one or more iterations and to edit sub-object
points and edges at that level.
<MeshSmooth>.displayCage Boolean default: false; alias:
display_control_mesh
Displays an orange wireframe gizmo that shows what the control mesh looks like after it’s
been converted to polygons (if applicable) and before the smoothing occurs.
<MeshSmooth>.useSoftSel Boolean default: false
Affects the action of Move, Rotate, and Scale functions within editable object or edit
modifier, and the action of deformation modifiers applied to the object if they are
operating on a sub-object selection. When on, 3ds max applies a spline curve deformation
to the unselected sub-objects surrounding the selection that you transform.
<MeshSmooth>.useEdgeDist Boolean default: false
Turn on/off use Edge Distance.
<MeshSmooth>.edgeDist Integer default: 1
Limits the region affected by the number of edges between the selection and the affected
vertices.
 MeshSmooth : Modifier 1141

<MeshSmooth>.affectBackfacing Boolean default: false

When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the
normals of faces to which they’re attached) are facing in the opposite direction to the
average normal of the selected sub-objects, are affected by the soft selection influence.
<MeshSmooth>.falloff Float default: 20.0
Distance in current units from the center to the edge of a sphere defining the affected
region. Use higher falloff settings to achieve more gradual slopes, depending on the scale
of your geometry.
<MeshSmooth>.pinch Float default: 0.0
Raises and lowers the top point of the curve along the vertical axis. Sets the relative
“pointedness” of the region. When negative, a crater is produced instead of a point. At a
setting of 0, Pinch produces a smooth transition across this axis.
<MeshSmooth>.bubble Float default: 0.0
Expands and contracts the curve along the vertical axis. Sets the relative “fullness” of the
region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for
Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble
move the bottom of the curve below the surface, creating a “valley” around the base of the
region.
<MeshSmooth>.strength Float default: 0.5 -- animatable
Sets the size of the added faces using a range from 0.0 to 1.0.
Values near 0.0 create small faces that are very thin and close to the original vertices and
edges, values near 0.5 size faces evenly between edges, and values near 1.0 create large new
faces and make the original faces very small.
<MeshSmooth>.Relax Float default: 0.0 -- animatable
Applies a positive relax effect to smooth all vertices.
<MeshSmooth>.limitSurface Boolean default: false; alias:
project_to_limit_surface
Places all points on the “limit surface” of the MeshSmooth result, which is the surface
you’d get after an infinite number of iterations.
<MeshSmooth>.smoothResult Boolean default: false; alias: smooth_output
Applies the same smoothing group to all faces.
<MeshSmooth>.sepByMats Boolean default: false; alias:
separate_by_materials
Prevents the creation of new faces for edges between faces that do not share Material IDs.
<MeshSmooth>.sepBySmGroups Boolean default: false; alias:
separate_by_smoothing_group
Prevents the creation of new faces at edges between faces that don’t share at least one
smoothing group.
1142 Chapter 11 | 3ds max Objects

<MeshSmooth>.faceType Integer default: 1

Select the type to operate on during input conversion:
Faces
Polygons
Operate On Faces treats every triangle as a face and smooths across all edges, even invisible
edges. Operate On Polygons ignores invisible edges, treating polygons (like the quads
making up a box or the cap on a cylinder) as a single face.
<MeshSmooth>.keepConvex Boolean default: false; alias:
keep_input_faces_convex
Keeps all input polygons convex. Selecting this option causes non-convex polygons to be
handled as a minimum number of separate faces, each of which is convex.
<MeshSmooth>.update Integer default: 0; alias: update_options
Set update options:
Always update
Update when rendering
Update Manually
<MeshSmooth>.reset Integer default: 0
Select reset settings:
Reset all levels
Reset this level
Note:
The edge and vertex weight properties are not accessible to MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Mesh_Select : Modifier
Constructor:
mesh_select ...

Properties:
<Mesh_Select>.Use_Soft_Selection Integer default: 0 -- animatable
Use_Soft_Selection = 0 - off; 1 - on
<Mesh_Select>.falloff Float default: 20.0 -- animatable
<Mesh_Select>.Pinch Float default: 0.0 -- animatable
<Mesh_Select>.Bubble Float default: 0.0 -- animatable
 Mirror : Modifier 1143

See the getVertSelection(), getFaceSelection(), and getEdgeSelection() functions in

the Editable_Mesh (p. 1041) topic for information about accessing the current selections in the
Mesh_Select modifier.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Mirror : Modifier
Constructor:
mirror ...

Properties:
<Mirror>.mirror_axis Integer default: 0
The axis or axes about which the mirroring takes place:
X
Y
Z
XY
YZ
ZX
<Mirror>.Mirror_Offset Float default: 0.0 -- animatable
The offset, in units, from the mirror axis.
<Mirror>.copy Boolean default: false
When on, copies the geometry rather than simply mirroring it.
<Mirror>.mirror_center SubAnim
Represents the axis of the mirror effect. You can move, rotate or scale the gizmo to affect
the mirroring.
<Mirror.Mirror_Center>.position Point3 default: [0,0,0] -- animatable
The position of the mirror center.
<Mirror.Mirror_Center>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the mirror center.
<Mirror.Mirror_Center>.scale Point3 default: [1,1,1] -- animatable
The scaling of the mirror center.
1144 Chapter 11 | 3ds max Objects

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Morpher : Modifier
Constructor:
Morpher ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Morpher>.Use_Limits Integer default: 1
When on, 3ds max uses the minimum and maximum limits for all channels.
<Morpher>.Spinner_Minimum Float default: 0.0
The minimum limit.
<Morpher>.Spinner_Maximum Float default: 100.0
The maximum limit.
<Morpher>.Use_Selection Integer default: 0
Turn on to limit morphing to vertices selected in a modifier below the Morpher modifier
in the modifier stack.
<Morpher>.Value_Increments Integer default: 1
<Morpher>.Autoload_of_targets Integer default: 0
Turn this on to allow animated targets to be updated dynamically by the Morpher
modifier.
Note:
You cannot get or set the morph channel objects and percentages using MAXScript in 3ds max 4.
The morpher modifier developer is planning on releasing a MAXScript extension that will provide
access to the morph channel objects.
You can access the morph channel percentage controllers as subAnims of the morpher modifier once
an object has been assigned to the channel. There is a one-to-one correspondence between the
channel number and the subAnim number. For example, if you assign an object to channel 1, the
channel 1’s percentage controller is stored in subAnim 1.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 NCurve_Sel : Modifier 1145

NCurve_Sel : Modifier
Constructor:
NCurve_Sel ...

Properties:
There are no additional properties for NCurve_Sel.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

NoiseModifier : Modifier
Constructor:
noiseModifier ...

Properties:
<Noisemodifier>.seed Integer default: 0 -- animatable
A random start point is generated from the number you set.
<Noisemodifier>.scale Float default: 100.0 -- animatable
The size of the noise effect (not strength). Larger values produce smoother noise, lower
values more jagged noise.
<Noisemodifier>.fractal Boolean default: false -- animatable
When on, produces a fractal effect based on current settings.
<Noisemodifier>.roughness Float default: 0.0 -- animatable, alias: rough
The extent of fractal variation. Lower values are less rough than higher values.
<Noisemodifier>.iterations Float default: 6.0 -- animatable
The number of iterations (or octaves) used by the fractal function. Fewer iterations use less
fractal energy and generate a smoother effect. An iteration of 1.0 is the same as turning
.fractal off.
<Noisemodifier>.strength Point3 default: [0,0,0] -- animatable
The strength of the noise effect along each of three axes. Enter a value for at least one of
these axes to produce a noise effect.
<Noisemodifier>.animate Boolean default: false
Enables/disables animation playback.
<Noisemodifier>.frequency Float default: 0.25
The speed of the noise effect. Higher frequencies make the noise quiver faster. Lower
frequencies produce a smoother and more gentle noise.
<Noisemodifier>.phase Time default: 0f -- animatable
1146 Chapter 11 | 3ds max Objects

Shifts the start and end points of the underlying wave.

<Noisemodifier>.center Point3 default: [0,0,0] -- animatable
You can move, rotate, or scale the center sub-object to affect the noise. You can also
animate the sub-object transforms.
<Noisemodifier>.gizmo SubAnim
You can move, rotate, or scale the gizmo sub-object to affect the noise. You can also
animate the sub-object transforms.
<Noisemodifier.gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the gizmo.
<Noisemodifier.gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the gizmo.
<Noisemodifier.gizmo>.scale Point3 default: [1,1,1] -- animatable
The scaling of the gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Normalize_Spline : Modifier
Constructor:
normalize_spline ...

Properties:
<normalize_spline>.Length Float default: 20.0
Determines how many control points are added. Smaller values produce more control
points; larger values produce fewer.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 NormalModifier : Modifier 1147

NormalModifier : Modifier
Constructor:
normalModifier ...

Properties:
<Normalmodifier>.unify Boolean default: false
When on, unifies the normals of an object by flipping the normals so that they all point in
the same direction, usually outward.
<Normalmodifier>.flip Boolean default: false
When on, reverses the direction of all the surface normals of the faces of the selected
object or objects.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

NSurf_Sel : Modifier
Constructor:
NSurf_Sel ...

Properties:
There are no additional properties for NSurf_Sel.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1148 Chapter 11 | 3ds max Objects

Optimize : Modifier
Constructor:
optimize ...

Properties:
<optimize>.renderLOD Integer default: 0
You can store two different optimization settings for the renderer, in two separate levels;
L1 & L2. Set the level of display for the default scanline renderer:
L1
L2
<optimize>.viewLOD Integer default: 0
You can store two different optimization settings for the viewport, in two separate levels;
L1 & L2. Set the level of display for the viewport:
L1
L2
<optimize>.facethreshold1 Float default: 4.0 -- animatable, angle, alias:
Face_Threshold_L1
The threshold angle used to determine which faces are collapsed. Low values produce less
optimization but better approximations of the original shape. Higher values improve
optimization, but are more likely to result in faces that render poorly .
<optimize>.edgethreshold1 Float default: 1.0 -- animatable, angle, alias:
Edge_Threshold_L1
Sets a different threshold angle for open edges (those that bound only one face). A low
value preserves open edges. At the same time you can apply a high face threshold to get
good optimization.
<optimize>.bias1 Float default: 0.1 -- animatable, alias: Bias_L1
Helps eliminate the skinny or degenerate triangles that occur during optimization, which
can cause rendering artifacts. Higher values keeps triangles from becoming degenerate.
The default of 0.1 is enough to eliminate the skinniest triangles.
<optimize>.Max_Edge_Length_1 Float default: 0.0 -- animatable
The maximum length, beyond which an edge cannot be stretched when optimized. When
Max_Edge_Length_1 is 0, it has no effect. Any value greater than 0 specifies the
maximum length of the edges.
<optimize>.preservemat1 Boolean default: false
When on, prevents face collapse across material boundaries.
<optimize>.preservesmooth1 Boolean default: false
When turned on, allows only faces that share at least one smoothing group to collapse.
 Optimize : Modifier 1149

<optimize>.facethreshold2 Float default: 4.0 -- animatable, angle, alias:

Face_Threshold_L2
The threshold angle used to determine which faces are collapsed. Low values produce less
optimization but better approximations of the original shape. Higher values improve
optimization, but are more likely to result in faces that render poorly .
<optimize>.edgethreshold2 Float default: 1.0 -- animatable, angle, alias:
Edge_Threshold_L2
Sets a different threshold angle for open edges (those that bound only one face). A low
value preserves open edges. At the same time you can apply a high face threshold to get
good optimization.
<optimize>.bias2 Float default: 0.1 -- animatable, alias: Bias_L2
Helps eliminate the skinny or degenerate triangles that occur during optimization, which
can cause rendering artifacts. Higher values keeps triangles from becoming degenerate.
The default of 0.1 is enough to eliminate the skinniest triangles.
<optimize>.Max_Edge_Length_2 Float default: 0.0 -- animatable
The maximum length, beyond which an edge cannot be stretched when optimized. When
Max_Edge_Length_2 is 0, it has no effect. Any value greater than 0 specifies the
maximum length of the edges.
<optimize>.preservemat2 Boolean default: false
When on, prevents face collapse across material boundaries.
<optimize>.preservesmooth2 Boolean default: false
When turned on, allows only faces that share at least one smoothing group to collapse.
<optimize>.manualUpdate Boolean default: false
When on, enables the Update button. When turned off, Optimize works as it does by
default, updating the viewport display dynamically.
<optimize>.autoedge Boolean default: false
When on, turns edges on and off following optimization. Turns on any open edges. Turns
off any edges between faces whose normals are within the face threshold; such edges
beyond the threshold are not turned on.
Note:
The Manual Update property is not accessible to MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1150 Chapter 11 | 3ds max Objects

PatchDeform : Modifier
Constructor:
patchDeform ...

Properties:
<PatchDeform>.U_Percent Float default: 50.0 -- animatable,
percentage
Moves the object along the U (horizontal) axis of the gizmo patch, based on a percentage
of the U distance. This defaults to a setting of 50 percent, which places the object at the
center of the gizmo patch. A setting of 0 percent places the object at the left edge of the
gizmo patch, as seen from the viewport where the patch was created.
<PatchDeform>.U_Stretch Float default: 1.0 -- animatable
Scales the object along the U (horizontal) axis of the gizmo patch.
<PatchDeform>.V_Percent Float default: 50.0 -- animatable,
percentage
Moves the object along the V (vertical) axis of the gizmo patch, based on a percentage of
the V distance. A setting of 0 percent places the object at the bottom of the gizmo patch.
<PatchDeform>.V_Stretch Float default: 1.0 -- animatable
Scales the object along the V (vertical) axis of the gizmo patch.
<PatchDeform>.rotation Float default: 0.0 -- animatable, angle
Rotates the modified object with respect to the gizmo patch.
<PatchDeform>.Plane_to_Patch_Deform Integer default: 0
Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo
patch:
XY
YZ
ZX
<PatchDeform>.Flip_deformation_axis Integer default: 0
When on, reverses the gizmo direction.
Don’t flip
Flip
<PatchDeform>.gizmo SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object,
altering the effect of the modifier. The PatchDeform gizmo is a representation of the
deforming patch object, so transforming it determines which part of the patch affects the
modified object.
 PathDeform : Modifier 1151

<PatchDeform.gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the patchdeform gizmo.
<PatchDeform.gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the patchdeform gizmo.
<PatchDeform.gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the patchdeform gizmo.
Note:
There is no way to specify the patch to deform to using MAXScript in 3ds max 4.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

PathDeform : Modifier
Constructor:
pathDeform ...

Properties:
<PathDeform>.path Node default: undefined
The selected path object.
<PathDeform>.Percent_along_path Float default: 0.0 -- animatable,
percentage
Moves the object along the gizmo path based on a percentage of the path length.
<PathDeform>.Stretch Float default: 1.0 -- animatable
Scales the object along the gizmo path, using the object’s pivot point as the base of the
scale.
<PathDeform>.rotation Float default: 0.0 -- animatable, angle
Rotates the object about the gizmo path.
<PathDeform>.Twist Float default: 0.0 -- animatable, angle
Twists the object about the path. The twist angle is based on the rotation of one end of the
overall length of the path. Typically, the deformed object takes up only a portion of the
path, so the effect can be subtle.
1152 Chapter 11 | 3ds max Objects

<PathDeform>.axis Integer default: 2

The axus if the gizmo object which is aligned with the corresponding local axis of the path
object:
X
Y
Z
<PathDeform>.Flip_deformation_axis Integer default: 0
When on, reverses the gizmo path 180 degrees about the specified axis.
Don’t flip
Flip
<PathDeform>.gizmo SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object,
altering the effect of the modifier. The PathDeform gizmo is a representation of the
deforming path object, so transforming it determines which part of the path affects the
modified object.
<PathDeform.Gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the pathdeform gizmo.
<PathDeform.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the pathdeform gizmo.
<PathDeform.Gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the pathdeform gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Preserve : Modifier
Constructor:
preserve ...

Properties:
<Preserve>.iterations Integer default: 25 -- animatable
The number of calculations toward the solution. The higher this number, the closer the
object comes to matching the original object and the slower the process. When this is set
to zero, the original object has no effect, as if the Preserve modifier were never applied.
<Preserve>.Edge_Length_Weight Float default: 1.0 -- animatable
The relative importance of the edge length.
 Push : Modifier 1153

<Preserve>.Face_Angle_Weight Float default: 0.3 -- animatable

The relative importance of the face angle.
<Preserve>.Volume_Weight Float default: 0.3 -- animatable
The relative importance of the volume.
<Preserve>.Apply_To_Whole_Mesh Integer default: 0
When on, applies Preserve to the entire object, regardless of the selection passed from
previous levels of the stack:
OFF
ON
<Preserve>.Selected_Verts_Only Integer default: 0
When on, uses previous sub-object vertex selections. Note that it doesn’t matter if the
Vertex sub-object level is active in a previous stack item. As long as vertices have been
selected, Preserve will use that selection.
OFF
ON
<Preserve>.Invert_Selection Integer default: 0
When on, inverts the selection passed up the stack.
OFF
ON
Note:
There is no way to specify the “Original” object using MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Push : Modifier
Constructor:
push ...

Properties:
<Push>.Push_Value Float default: 0.0 -- animatable
The distance in world units by which vertices are moved with respect to the object center.
Use a positive value to move vertices outward, or a negative value to move vertices inward.
1154 Chapter 11 | 3ds max Objects

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Relax : Modifier
Constructor:
relax ...

Properties:
<Relax>.iterations Integer default: 1 -- animatable
The number of times Relax is repeated. Each iteration recalculates average vertex locations
based on the result of the previous iteration.
<Relax>.Relax_Value Float default: 0.5 -- animatable
The distance a vertex moves as a percentage of the distance between a vertex and the
average location of its neighbors.
<Relax>.Keep_Boundary_Pts_Fixed Integer default: 1
When on, vertices at the edge of open meshes do not relax.
OFF
ON

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Ripple : Modifier
Constructor:
ripple ...

Properties:
<Ripple>.amplitude1 Float default: 5.0 -- animatable, alias: Amplitude_1
The amplitude of the first ripple.
<Ripple>.amplitude2 Float default: 5.0 -- animatable, alias: Amplitude_2
The amplitude of the second ripple, which is perpendicular to the first ripple.
<Ripple>.wavelength Float default: 25.0 -- animatable, alias: Wave_Length
The distance between the peaks of the wave. The greater the length, the smoother and
more shallow the ripple for a given amplitude.
 Skew : Modifier 1155

<Ripple>.phase Float default: 0.0 -- animatable

Shifts the ripple pattern over the object. Positive numbers move the pattern inward, while
negative numbers move it outward.
<Ripple>.decay Float default: 0.0 -- animatable
Limits the effect of the wave generated from its center. A default decay of zero means that
the wave will generate infinitely from its center. Increasing the decay value reduces the
distance over which the wave is generated.
<Ripple>.center Point3 default: [0,0,0] -- animatable
At this sub-object level, you can translate and animate the center of the ripple effect, and
thus the shape and positions of the ripples.
<Ripple>.gizmo SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object,
altering the effect of the Ripple modifier. Translating the gizmo translates its center an
equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Ripple.gizmo>.position Point3 default: [0,0,0] -- animatable
The poosition of the ripple gizmo.
<Ripple.gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the ripple gizmo.
<Ripple.gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the ripple gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Skew : Modifier
Constructor:
skew ...

Properties:
<Skew>.amount Float default: 25.0 -- animatable
The angle to skew from the vertical plane.
<Skew>.direction Float default: 0.0 -- animatable
The direction of the skew relative to the horizontal plane.
1156 Chapter 11 | 3ds max Objects

<Skew>.axis Integer default: 2

The axis that will be skewed:
X
Y
Z
<Skew>.limit Boolean default: false
When on, applies limit constraints to the Skew modifier.
<Skew>.upperlimit Float default: 0.0 -- animatable, alias: Upper_Limit
The upper limit boundaries in world units from the skew center point, beyond which the
skew no longer affects the geometry.
<Skew>.lowerlimit Float default: 0.0 -- animatable, alias: Lower_Limit
The lower limit boundaries in world units from the skew center point, beyond which the
skew no longer affects the geometry.
<Skew>.center Point3 default: [0,0,0] -- animatable
At this sub-object level, you can translate and animate the center of the Skew effect.
<Skew>.gizmo SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object,
altering the effect of the Skew modifier. Translating the gizmo translates its center an equal
distance. Rotating and scaling the gizmo takes place with respect to its center.
<Skew.Gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the skew gizmo.
<Skew.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the skew gizmo.
<Skew.Gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the skew gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Skin : Modifier 1157

Skin : Modifier
Constructor:
skin ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Skin>.Effect Float default: 0.0
Absolute weight of selected vertices.
<Skin>.filter_vertices Boolean default: false
Turn vertex selection on/off.
<Skin>.filter_cross_sections Boolean default: true
Turn cross-section selection on/off.
<Skin>.filter_envelopes Boolean default: true
Turn envelope selection on/off.
<Skin>.draw_all_envelopes Boolean default: false
When turned on, displays all envelopes. When off, only the selected envelopes are
displayed.
<Skin>.draw_vertices Boolean default: true
Turn on/off the display of weighted vertices.
<Skin>.ref_frame Integer default: 0
Sets the frame where the bones and the mesh are in a reference position.
<Skin>.paint_radius Float default: 24.0
Sets the brush radius.
<Skin>.paint_feather Float default: 0.7
Sets the brush falloff.
<Skin>.cross_radius Float default: 10.0
Scales the selected envelope cross-section.
<Skin>.always_deform Boolean default: true
Always deforms the skin when the bones are moved. The Animate button does not have to
be turned on to move bones and deform the skin.
<Skin>.paint_str Float default: 0.1
Sets the brush strength.
<Skin>.localSquash Array default: #() -- float array
Amount of squash applied to each bone.
<Skin>.initialSquash Array default: #() -- float array
Array containing initial squash values for a bone.
<Skin>.initialStaticEnvelope Boolean default: false
When turned on, an initial static envelope size is used when a bone is added. When off,
the initial envelope size is determined by the object bounding box.
1158 Chapter 11 | 3ds max Objects

<Skin>.initialInnerEnvelopePercent Float default: 0.75

The multiplier used to find the inner cross-section size when initialStaticEnvelope
is false.
<Skin>.initialOuterEnvelopePercent Float default: 3.5
The multiplier used to find the outer cross-section size when initialStaticEnvelope
is false.
<Skin>.initialEnvelopeInner Float default: 10.0
The inner cross-section size when initialStaticEnvelope is true.
<Skin>.initialEnvelopeOuter Float default: 50.0
The outer cross-section size when initialStaticEnvelope is true.
<Skin>.draw_all_gizmos Boolean default: true
Turn on/off the display off all gizmos.
<Skin>.draw_all_vertices Boolean default: false
Turns on/off the display of all vertices as small dots.
<Skin>.shadeweights Boolean default: true
Turn on/off display of weighted vertices using vertex colors.
<Skin>.envelopesAlwaysOnTop Boolean default: true
Turn on/off display of envelopes on top of the mesh.
<Skin>.crossSectionsAlwaysOnTop Boolean default: true
Turn on/off display of cross-sections on top of the mesh.
<Skin>.rigid_vertices Boolean default: false
When turned on, a single vertex can only be affected by one bone.
<Skin>.rigid_handles Boolean default: false
When turned on, all handles have the same weights as the knot that owns them.
<Skin>.fast_update Boolean default: false
When turned on, the system uses only rigid vertices for the viewport display.
<Skin>.gizmos Array default: #() -- max object array
Array containing all gizmos assigned to skin.
Methods:
The following methods require that the Skin modifier be the displayed modifier in the Modify panel,
and that the Modify panel is active.
skinops.addbone <Skin> <Bone_node> <Update_integer>
Adds a bone to the current system.
For Update_integer, - 1 forces a complete update and redraw, 0 does not update the
system. This allows you to add a bunch of bones to a system and then update once at the
end.
skinops.addBoneFromViewEnd <Skin>
Ends the addBoneFromViewStart command mode.
skinops.addBoneFromViewStart <Skin>
Puts you in a command mode where you can select bones from the viewport by clicking
on them. You can exit this mode by right clicking or calling addBoneFromViewEnd.
 Skin : Modifier 1159

skinops.addCrossSection <Skin> <BoneID_integer> <U_float> <InnerRadius_float>

<OuterRadius_float>
Adds a cross section to the bone whose index matches BoneID_integer. U_float, which
ranges from 0.0-1.0, defines where along the bone to add the cross-section.
skinops.addCrossSection <Skin> <U_float>
Adds a cross section to the current selected bone. The inner and outer radii are computed
based on the neighboring cross sections. U_float, which ranges from 0.0-1.0, defines
where along the bone to add the cross-section.
skinops.addCrossSection <Skin> <U_float> <InnerRadius_float> <OuterRadius_float>
Adds a cross section to the current selected bone. U_float, which ranges from 0.0-1.0,
defines where along the bone to add the cross-section.
skinops.buttonAdd <Skin>
Presses the add bone button.
skinops.buttonAddCrossSection <Skin>
Presses the add cross section button.
skinops.buttonAddGizmo <Skin>
Presses the add gizmo button in the gizmo rollout.
skinops.buttonCopyGizmo <Skin>
Presses the copy gizmo button in the gizmo rollout.
skinops.buttonExclude <Skin>
Presses the exclude vertices button.
skinops.buttonInclude <Skin>
Presses the include vertices button.
skinops.buttonPaint <Skin>
Presses the paint button.
skinops.buttonPasteGizmo <Skin>
Presses the paste gizmo button in the gizmo rollout.
skinops.buttonRemove <Skin>
Presses the remove bone button.
skinops.buttonRemoveCrossSection <Skin>
Presses the remove cross section button.
skinops.buttonRemoveGizmo <Skin>
Presses the remove gizmo button in the gizmo rollout.
skinops.buttonSelectExcluded <Skin>
Presses the select excluded vertices button.
skinops.copySelectedBone <Skin>
Copies current selected bone properties to the copy buffer.
skinops.enableGizmo <Skin> <GizmoID_integer> <Enable_bool>
Enables/disables the gizmo type whose index equals GizmoID_integer.
1160 Chapter 11 | 3ds max Objects

skinOps.GetBoneName <Skin> <bone_integer> <nameflag_index>

Returns the name of the indexed bone as a string. where nameflag_index can be 0 or 1.
If nameflag_index = 0 the node that holds the transform for this bone is returned; = 1
the name that exists in the list box is returned. If a Bones system is used for the Skin bones,
the transform for a bone is held by its parent.
skinops.getBonePropEnvelopeVisible <Skin> <BoneID_integer>
Returns the bone visibility parameter of the bone. 0 is invisible, 1 is visible.
skinops.getBonePropFalloff <Skin> <BoneID_integer>
Returns the falloff parameter of the bone.
1 – linear
2 – sinual
3 – fast out
4 – slow out
skinops.getBonePropRelative <Skin> <BoneID_integer>
Gets the relative property of the bone. It returns 1 if relative or 0 is absolute.
skinops.GetCrossSectionU <Skin> <BoneID_integer> <CrossSectionID_integer>
Gets the U value from the specified bone and cross section
skinops.getCurrentSelectGizmoType <Skin>
Returns the current selected gizmo type.
skinops.GetEndPoint <Skin> <BoneID_integer>
Returns a point3 which is the end point of the bone.
skinOps.GetInnerRadius <Skin> \
<bone_integer> <CrossSectionID_integer>
Returns the inner cross section radius for the specified bone and cross section.
skinOps.GetNumberBones <Skin>
Returns the number of bones in the system.
skinOps.getNumberCrossSections <Skin> <bone_integer>
Returns the number of cross sections for the specified bone.
skinops.getNumberOfGizmos <Skin>
Returns the number of gizmos.
skinops.getNumberOfGizmoTypes <Skin>
Returns the number of gizmo types.
skinOps.GetNumberVertices <Skin>
Returns the number of vertices for the object the Skin modifier is applied to.
skinOps.GetOuterRadius <Skin> \
<bone_integer> <CrossSectionID_integer>
Returns the outer cross section radius for the specified bone and cross section.
skinOps.GetSelectedBone <Skin>
Returns the index of the current selected bone in the Bone list.
 Skin : Modifier 1161

skinops.getSelectedBonePropEnvelopeVisible <Skin>
Returns the bone visibility parameter of the current selected bone. 0 is invisible, 1
is visible.
skinops.getSelectedBonePropFalloff <Skin>
Returns the falloff parameter of the current selected bone:
1 – linear
2 – sinual
3 – fast out
4 – slow out
skinops.getSelectedBonePropRelative <Skin>
Gets the relative property of the current selected bone. It returns 1 if relative or 0
is absolute.
skinops.getSelectedGizmo <Skin>
Returns the current selected gizmo.
skinops.GetStartPoint <Skin> <BoneID_integer>
Returns a point3 which is the start point of the bone.
skinOps.GetVertexWeight <Skin> \
<vertex_integer> <vertex_bone_integer>
Returns the influence of the Nth bone affecting the specified vertex.
skinOps.GetVertexWeightBoneID <Skin> \
<vertex_integer> <vertex_bone_integer>
Returns the system bone index of the Nth bone affecting the specified vertex.
skinOps.GetVertexWeightCount <Skin> <vertex_integer>
Returns the number of bones influencing the specified vertex.
skinops.isBoneSelected <Skin> <BoneID_integer>
Returns 1 if the bone is selected otherwise 0.
skinOps.IsVertexModified <Skin> <vertex_integer>
Returns 1 if the vertex has been modified, 0 if it has not been modified. A modified vertex
is vertex that has been weighted by hand or painting, an unmodified vertex weight
depends solely on the envelopes.
skinOps.IsVertexSelected <Skin> <vertex_integer>
Returns 1 if the vertex is selected, 0 if it is not selected.
skinops.loadEnvelope <Skin>
Opens the load envelopes dialog
skinops.loadEnvelope <Skin> <filename_string>
Loads the envelopes to the file supplied
skinops.multiRemove <Skin>
Brings up a list box where the user can delete multiple bones instead of one at a time.
skinops.pasteToAllBones <Skin>
Pastes the copy buffer to all the bones.
1162 Chapter 11 | 3ds max Objects

skinops.pasteToBone <Skin> <BoneID_int>

Pastes the copy buffer to bone id supplied.
skinops.pasteToSelectedBone <Skin>
Pastes the copy buffer to the current selected bone.
skinops.removebone <Skin>
Removes the current selected bone from the bones system.
skinops.removebone <Skin> <BoneID_integer>
Removes the BoneID from the bones system.
skinops.RemoveCrossSection $<Skin>
Removes the current selected cross section from the current selected bone.
skinops.RemoveCrossSection <Skin> <BoneID_integer> <CrossSectionID_integer>
Removes a particular cross-section from a particular bone.
skinOps.ReplaceVertexWeights <Skin> <vertex_integer> \
( <vertex_bone_integer> | <vertex_bone_array> ) \
( <weight_float> | <weight_array> )
Sets the influence of the specified bone(s) to the specified vertex. Any influence weights
for the bone(s) that are not specified are erased. If the bones and weights are specified as
arrays, the arrays must be of the same size.
skinops.resetAllBones <Skin>
Resets all bones.
skinops.resetSelectedBone <Skin>
Resets the current selected bone.
skinops.resetSelectedVerts <Skin>
Resets the current selected vertices.
skinops.saveEnvelope <Skin>
Opens the save envelopes dialog
skinops.saveEnvelope <Skin> <filename_string>
Saves the envelopes to the file supplied
skinOps.SelectBone <Skin> <bone_integer>
Selects the specified bone in the Bone list.
skinops.selectCrossSection <Skin> <CrossSectionID_integer> <Inner_Outer_integer>
Selects a cross section on the current selected bone.
For Inner_Outer_integer, 0 is the inner envelope 1 is the outer envelope.
skinops.selectEndPoint <Skin>
Selects the start point of the envelope the current selected bone.
skinops.selectGizmo <Skin> <gizmoID_int>
Desc – this function selects the gizmo who index equals gizmoID.
skinops.selectGizmoType <Skin> <gizmoTypeID_int>
Selects the gizmo type whose index equals gizmoTypeID.
skinops.selectNextBone <Skin>
Selects the next bone in the bone list.
 Skin : Modifier 1163

skinops.selectPreviousBone <Skin>
Selects the next bone in the bone list.
skinops.selectStartPoint <Skin>
Selects the end point of the envelope of the current selected bone.
skinOps.SelectVertices <Skin> \
( <vertex_integer> | <vertex_array > | <<vertex_bitarray> )
Selects the specified vertices.
skinops.setBonePropEnvelopeVisible <Skin> <BoneID_integer> <Visible_integer>
Sets the bone visibility parameter of the bone whose index matches BoneID_integer.
For Visible_integer, 0 is visible, 1 is invisible when not selected.
skinops.setBonePropFalloff <Skin> <BoneID_integer> <Falloff_integer>
Sets the falloff parameter of the bone.
For Faloff_integer, the fall off of the bone is:
1 – linear
2 – sinual
3 – fast out
4 – slow out
skinops.setBonePropRelative <Skin> <BoneID_integer> <Relative_integer>
Sets the relative property of the bone whose index matches BoneID_integer.
For Relative_integer, 0 is absolute and 1 is relative.
skinops.SetCrossSectionU <Skin> <BoneID_integer> <CrossSectionID_integer>
<U_float>
Sets the U value from the specified bone and cross section.
skinops.SetEndPoint <Skin> <BoneID_integer> <EndPointPos_point3>
Sets the end point of the specified bone.
skinOps.SetInnerRadius <Skin> \
<bone_integer> <CrossSectionID_integer> <Radius_float>
Sets the inner cross section radius for the specified bone and cross section.
skinOps.SetOuterRadius <Skin> \
<bone_integer> <CrossSectionID_integer> <Radius_float>
Sets the outer cross section radius for the specified bone and cross section.
skinops.setSelectedBonePropEnvelopeVisible <Skin> <Visible_integer>
Sets the bone visibility parameter of the current selected bone.
For Visible_integer, 0 = visible, 1 = invisible when not selected
1164 Chapter 11 | 3ds max Objects

skinops.setSelectedBonePropFalloff <Skin> <Falloff_integer>

Sets the falloff parameter of the current selected bone.
The falloff_integer sets the fall off of the bone:
1 – linear
2 – sinual
3 – fast out
4 – slow out
skinops.setSelectedBonePropRelative <Skin> <Relative_integer>
Sets the relative property of the current selected bone.
For relative_integer, 0 is relative mode, 1 is absolute mode.
skinops.SetStartPoint <Skin> <BoneID_integer> <EndPointPos_point3>
Sets the start point of the specified bone
skinOps.SetVertexWeights <Skin> <vertex_integer> \
( <vertex_bone_integer> | <vertex_bone_array> ) \
( <weight_float> | <weight_array> )
Sets the influence of the specified bone(s) to the specified vertex. Any influence weights
for the bone(s) that are not specified are retained. If the bones and weights are specified as
arrays, the arrays must be of the same size.
skinops.ZoomToBone <Skin> <All_boolean>
Zooms the active or all views to the selected bone. If All_boolean is true, then all views
are zoomed.
skinops.ZoomToGizmo <Skin> <All_boolean>
Zooms the active or all views to the selected gizmo. If All_boolean is true, then all views
are zoomed.
Note:
If deferred plug-in loading is enabled, an instance of the Skin modifier must be created before these
methods will be visible. This is because these methods are defined in the Skin modifier plug-in.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 SliceModifier : Modifier 1165

SliceModifier : Modifier
Constructor:
sliceModifier ...

Properties:
<sliceModifier>.Slice_Type Integer default: 0
Defines how the slice plane will affect the geometry to which it has been applied:
Refine Mesh (Adds new vertices and edges along the intersection of the geometry with the
slicing plane. Faces cut by the plane are subdivided into new faces.)
Split Mesh (Adds a double set of vertices and edges along the plane boundary producing
two separate meshes (one on either side of the slice plane), which you can modify
differently if desired. Use this to break a mesh in two.)
Remove Top (Deletes all the faces and vertices above the Slice Plane.)
Remove Bottom (Deletes all the faces and vertices below the Slice Plane.)
<sliceModifier>.Faces___Polygons_Toggle Integer default: 1
Specifies how the slice handles quads and other polygons:
Operate on Face (Treats the selection set as a set of triangular faces, slicing each one in
turn.)
Operate on Polygon (Treats the selection set as polygonal facets based on visible edges.
Hidden edges within a polygon are recomputed to give the best result for the whole
polygons.)
<sliceModifier>.slice_plane SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object to
determine where the slice occurs. Scaling the gizmo has no effect, because its extents are
effectively infinite. If you need to limit the extent of the slice, use it on a sub-object
selection set of faces, rather than on the entire object.
<sliceModifier.Slice_Plane>.position Point3 default: [0,0,0] --
animatable
The position of the slice plane object.
<sliceModifier.Slice_Plane>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the slice plane object.
<sliceModifier.Slice_Plane>.scale Point3 default: [1,1,1] --
animatable
The scale of the slice plane object.
1166 Chapter 11 | 3ds max Objects

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Smooth : Modifier
Constructor:
smooth ...

Properties:
<smooth>.autosmooth Boolean default: false
When on, the object is auto-smoothed using the threshold value. Auto Smooth sets the
smoothing groups based on the angle between faces. Any two adjacent faces are put in the
same smoothing group if the angle between their normals is less than the threshold angle.
<smooth>.preventIndirect Boolean default: false
Turn on to prevent smoothing “leaks” when using Auto Smooth. If you apply Auto
Smooth to an object, and portions of that object that should not be smoothed become
smoothed, then turn on Prevent Indirect Smoothing to see if it corrects the problem.
<smooth>.threshold Float default: 30.0 -- animatable, angle
The threshold angle in degrees. Any two adjacent faces are put in the same smoothing
group if the angle between their normals is less than the threshold angle.
<SmoothModifier>.smoothingBits Integer default: 0
The smoothing group assigned to the selected face.
Note:
See the Editable_Mesh (p. 1041) topic, Face Methods for a description of the smoothing group
integer value.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Spherify : Modifier 1167

Spherify : Modifier
Constructor:
spherify ...

Properties:
<Spherify>.percent Float default: 100.0 -- animatable
The percentage of spherical distortion to apply to an object.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SplineSelect : Modifier
Constructor:
splineSelect ...

Properties:
There are no additional properties for SplineSelect.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Squeeze : Modifier
Constructor:
squeeze ...

Properties:
<Squeeze>.Bulge_Amount Float default: 0.0 -- animatable
The magnitude of the bulging effect. Higher values effectively elongate the object and
cause the ends to curve outward.
<Squeeze>.Bulge_Curviture Float default: 2.0 -- animatable
The degree of curvature on the bulging ends. You can use this to control whether the bulge
is smooth or pointy.
1168 Chapter 11 | 3ds max Objects

<Squeeze>.Squeeze_Amount Float default: 0.0 -- animatable

The magnitude of the squeezing action. Values larger than zero tend to constrict the
“waist” of the object, and values less than zero tend to bulge the waistline out, as if the
object had been stepped on.
<Squeeze>.Squeeze_Curvature Float default: 2.0 -- animatable
The degree of curvature into the squeeze. Low values cause a sharp squeezing effect, while
high values create a gradual, less pronounced squeeze.
<Squeeze>.Limit_Squeeze_Effects Integer default: 0
When on, limits the extent of the squeeze effect as defined by the Lower and Upper Limit
settings.
OFF
ON
<Squeeze>.Squeeze_Lower_Limit Float default: -50.0 -- animatable
The limit of the squeeze effect in the positive direction along the Z axis.
<Squeeze>.Squeeze_Upper_Limit Float default: 50.0 -- animatable
The limit of the squeeze effect in the negative direction along the Z axis.
<Squeeze>.Bias Float default: 0.0 -- animatable,
percentage
The relative amounts of bulge and squeeze while retaining a constant object volume.
<Squeeze>.Volume Float default: 100.0 -- animatable,
percentage
Increases or decreases the effects of both Squeeze and Bulge in parallel.
<Squeeze>.center Point3 default: [0,0,0] -- animatable
At this sub-object level, you can translate and animate the center, altering the Squeeze
gizmo’s shape, and thus the shape of the squeezed object.
<Squeeze>.gizmo SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object,
altering the effect of the Squeeze modifier. Translating the gizmo translates its center an
equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Squeeze.Gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the squeeze gizmo.
<Squeeze.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the squeeze gizmo.
<Squeeze.Gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the squeeze gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 STL_Check : Modifier 1169

STL_Check : Modifier
Constructor:
stl_check ...

Properties:
<STL_Check>.Selection_Type Integer default: 4
Selects incorrect geometry specific to the following settings:
Open Edge (Checks for open edges.)
Double Face (Checks for faces that share the same 3D space.)
Spike (Checks for spikes, which are isolated faces that share only one edge with the object.)
Multiple Edge (Checks for faces that share more than one edge.)
Everything (Checks for all of the above.)
<STL_Check>.Select_Faces Integer default: 1
These options specify the level of incorrect geometry that’s selected, based on the settings
for the selection_type value:
Don’t Select (When on, STL Check doesn’t select any part of objects in error.)
Select Edges (When on, STL Check marks the edges of faces in error by selecting them. The
selection of erroneous edges is visible in viewports.)
Select Faces (When on, STL Check marks the faces of any object in error by selecting them.
The selection of erroneous faces is visible in viewports.)
<STL_Check>.Check_Now Integer default: 0
Turn on to perform the STL check. For complex objects, expect a pause between the time
you turn this on, and the time you see the reported errors in the Status group.
OFF
ON
<STL_Check>.Change_MatID Integer default: 1
When on, STL Check also marks faces in error by assigning them a unique material ID.
OFF
ON
<STL_Check>.Material_ID Integer default: 2
The material ID that STL Check assigns to faces in error.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1170 Chapter 11 | 3ds max Objects

Stretch : Modifier
Constructor:
stretch ...

Properties:
<Stretch>.Stretch Float default: 0.0 -- animatable
The base scale factor for all three axes. The scale factor derived from the Stretch value
varies according to the sign of the value.
<Stretch>.Amplify Float default: 0.0 -- animatable
The scale factor applied to the minor axes. Amplify generates a multiplier using the same
technique as stretch. The multiplier is then applied to the stretch value before the
scale factor for the minor axes is calculated.
<Stretch>.axis Integer default: 2
Determines which of the object’s local axes is the Stretch Axis:
X
Y
Z
<Stretch>.limit Boolean default: false
When on, the stretch effect is limited by the from and to values.
<Stretch>.from Float default: 0.0 -- animatable
The boundary of the stretch effect along the negative Stretch Axis.
<Stretch>.to Float default: 0.0 -- animatable
The boundary of the stretch effect along the positive Stretch Axis.
<Stretch>.center Point3 default: [0,0,0] -- animatable
At this sub-object level, you can translate and animate the center, altering the Stretch
gizmo’s shape, and thus the shape of the stretched object.
<Stretch>.gizmo SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object,
altering the effect of the Stretch modifier. Translating the gizmo translates its center an
equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Stretch.Gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the stretch gizmo.
<Stretch.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the stretch gizmo.
<Stretch.Gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the stretch gizmo.
Note:
The Limit Effect property is not accessible by MAXScript in 3ds max 4.
 Surface : Modifier 1171

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Surface : Modifier
Constructor:
surface ...

Properties:
<surface>.threshold Float default: 1.0 -- animatable
The overall distance that is used to weld the vertices of the spline object. All vertices/
vectors within the threshold of each other are treated as one.
<surface>.steps Integer default: 5 -- animatable
The number of steps used between each vertex. The higher the step count, the smoother
the curve you will get between vertices.
Note:
The Flip Normals, Remove Interior Patches, and Use Only Selected Segs. properties are not accessible
by MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SurfDeform : Modifier
Constructor:
surfDeform ...

Properties:
<SurfDeform>.surface Node default: undefined
The surface used to apply deformation.
<SurfDeform>.U_Percent Float default: 50.0 -- animatable,
percentage
Moves the object along the U (horizontal) axis of the gizmo patch, based on a percentage
of the U distance. This defaults to a setting of 50 percent, which places the object at the
center of the gizmo patch. A setting of 0 percent places the object at the left edge of the
gizmo patch, as seen from the viewport where the patch was created.
1172 Chapter 11 | 3ds max Objects

<SurfDeform>.U_Stretch Float default: 1.0 -- animatable

Scales the object along the U (horizontal) axis of the gizmo patch.
<SurfDeform>.V_Percent Float default: 50.0 -- animatable,
percentage
Moves the object along the V (vertical) axis of the gizmo patch, based on a percentage of
the V distance. A setting of 0 percent places the object at the bottom of the gizmo patch.
<SurfDeform>.V_Stretch Float default: 1.0 -- animatable
Scales the object along the V (vertical) axis of the gizmo patch.
<SurfDeform>.rotation Float default: 0.0 -- animatable, angle
Rotates the modified object with respect to the gizmo patch.
<SurfDeform>.Plane_to_Patch_Deform Integer default: 0
Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo
patch:
XY
YZ
ZX
<SurfDeform>.Flip_deformation_axis Integer default: 0
When on, reverses the gizmo direction.
Don’t flip
Flip
<SurfDeform>.gizmo SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object,
altering the effect of the modifier. The PatchDeform gizmo is a representation of the
deforming patch object, so transforming it determines which part of the patch affects the
modified object.
<SurfDeform.Gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the surfdeform gizmo.
<SurfDeform.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the surfdeform gizmo.
<SurfDeform.Gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the surfdeform gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Taper : Modifier 1173

Taper : Modifier
Constructor:
taper ...

Properties:
<Taper>.amount Float default: 1.0 -- animatable
The extent to which the ends are scaled. Amount is a relative value with a maximum of 10.
<Taper>.curve Float default: 0.0 -- animatable, alias: curvature
Applies a curvature to the sides of the Taper gizmo, thus affecting the shape of the tapered
object. Positive values produce an outward curve along the tapered sides, negative values
an inward curve. At 0, the sides are unchanged.
<Taper>.primaryaxis Integer default: 2
The central axis or spine of the taper:
X
Y
Z
<Taper>.effectaxis Integer default: 2
The axis, or pair of axes, indicating the direction of the taper from the primary axis. The
available choices are determined by the choice of primary axis. The effect axis can be
either of the two remaining axes, or their combination. If the primary axis is X, the effect
axis can be Y, Z, or YZ.
Z
Y
ZY
<Taper>.symmetry Boolean default: false -- animatable
When on, produces a symmetrical taper around the primary axis. A taper is always
symmetrical around the effect axis.
<Taper>.limit Boolean default: false
Enables/disables upper and lower limits for the taper effect.
<Taper>.upperlimit Float default: 0.0 -- animatable, alias: Upper_Limit
The upper limit boundaries in world units from the taper center point, beyond which the
taper no longer affects the geometry.
<Taper>.lowerlimit Float default: 0.0 -- animatable, alias: Lower_Limit
The lower limit boundaries in world units from the taper center point, beyond which the
taper no longer affects the geometry.
<Taper>.center Point3 default: [0,0,0] -- animatable
At this sub-object level, you can translate and animate the center, altering the Taper
gizmo’s shape, and thus the shape of the melted object
1174 Chapter 11 | 3ds max Objects

<Taper>.gizmo SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object,
altering the effect of the Taper modifier. Translating the gizmo translates its center an
equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Taper.Gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the taper gizmo.
<Taper.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the taper gizmo.
<Taper.Gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the taper gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Tessellate : Modifier
Constructor:
tessellate ...

Properties:
<Tessellate>.tension Float default: 2500.0 -- animatable, percentage
Determines if the new faces are flat, concave, or convex after Edge tessellation. A positive
value rounds faces by pushing vertices outward. A negative value creates concave faces by
pulling vertices inward. A setting of 0 keeps the faces flat.
Note:
The tension value is 100* the value shown in the 3ds max user interface.
Most properties in the Tessellate modifier are not accessible by MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Trim_Extend : Modifier 1175

Trim_Extend : Modifier
Constructor:
trim_extend ...

Properties:
There are no additional properties for Trim_Extend.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Twist : Modifier
Constructor:
twist ...

Properties:
<Twist>.angle Float default: 0.0 -- animatable
The amount of twist around the vertical axis.
<Twist>.bias Integer default: 0 -- animatable
Causes the twist rotation to bunch up at either end of the object. When the parameter is
negative, the object twists closer to the gizmo center. When the value is positive, the
object twists more away from the gizmo center. When the parameter is 0, the twisting is
uniform.
<Twist>.axis Integer default: 2
The axis along which the twist will occur. This is the local axis of the Twist gizmo.
X
Y
Z
<Twist>.limit Boolean default: false
When on, applies limit constraints to the Twist modifier.
<Twist>.upperlimit Float default: 0.0 -- animatable, alias: Upper_Limit
The upper limit for the twist effect.
<Twist>.lowerlimit Float default: 0.0 -- animatable, alias: Lower_Limit
The lower limit for the twist effect.
<Twist>.center Point3 default: [0,0,0] -- animatable
You can translate and animate the center at this sub-object level, altering the Twist gizmo’s
shape, and thus the shape of the twisted object.
1176 Chapter 11 | 3ds max Objects

<Twist>.gizmo SubAnim
You can transform and animate the gizmo like any other object at this sub-object level,
altering the effect of the Twist modifier. Translating the gizmo translates its center an equal
distance. Rotating and scaling the gizmo takes place with respect to its center.
<Twist.Gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the twist gizmo.
<Twist.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the twist gizmo.
<Twist.Gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the twist gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Unwrap_UVW : Modifier
Constructor:
unwrap_UVW ...

Note: This class is not available in 3D Studio VIZ.

Properties:
There are no additional properties for Unwrap_UVW.
Methods:
The following methods require that the Unwrap UVW modifier be the displayed modifier in the
Modify panel, and that the Modify panel is active.
PlanarMap()
Presses the Planar Map button in the rollup interface
Save()
Presses the Save button in the rollup interface
Load()
Presses the Load button in the rollup interface
Reset()
Presses the Reset button in the rollup interface
Edit()
Presses the Edit button in the rollup interface
 Unwrap_UVW : Modifier 1177

SetMapChannel <channel>
Sets the Map Channel field in the rollup
Channel (integer) – The channel that you want to set to.
GetMapChannel()
Returns the Map Channel field value in the rollup
SetVC <VertexColor>
Sets the Vertex Color Channel radio button in the rollup on or off.
VertexColor (integer) – Turn the vertex color on/off.
GetVC()
Returns the state of the Vertex Color Channel radio button in the rollup.
SetProjectionType <Proj>
Proj (integer) – The type of mapping you want:
1 – X aligned
2 – Y aligned
3 – Z aligned
4 – normal aligned
GetProjectionType()
Returns the state of the mapping align radio buttons:
1 – X aligned
2 – Y aligned
3 – Z aligned
4 – normal aligned
Move()
Presses the Move button in the edit floater.
MoveH()
Presses the Move Horizontal button in the edit floater.
MoveV()
Presses the Move Vertical button in the edit floater.
Rotate()
Presses the Rotate button in the edit floater.
Scale()
Presses the Scale button in the edit floater.
ScaleH()
Presses the Scale Horizontal button in the edit floater.
ScaleV()
Presses the Scale Vertical button in the edit floater.
MirrorH()
Presses the Mirror Horizontal button in the edit floater.
1178 Chapter 11 | 3ds max Objects

MirrorV()
Presses the Mirror Vertical button in the edit floater.
ExpandSelection()
Presses the Expand Selection button in the edit floater.
ContractSelection()
Presses the Contract Selection button in the edit floater
SetFalloffType <falloff>
Sets the falloff type in the edit floater.
falloff (integer) – The falloff type:
1 – Linear falloff
2 – Sinual falloff
3 – Fast falloff
4 – Slow falloff
GetFalloffType()
Returns the falloff type in the edit floater:
1 – Linear falloff
2 – Sinual falloff
3 – Fast falloff
4 – Slow falloff
SetFalloffSpace <space>
Sets the falloff space in the edit floater.
space (integer) – The space you want the falloff to be computed in:
1 – XY (The local space of the object.)
2 – UV (The UVW space of the object.)
GetFalloffSpace()
Returns the falloff space in the edit floater.
SetFalloffDist <dist>
Sets the falloff distance in the edit floater.
dist (float) – The falloff distance.
GetFalloffDist()
Returns the falloff distance from the edit floater.
BreakSelected()
Presses the Break Selected button in the edit floater.
Weld()
Presses the Target Weld button in the edit floater.
WeldSelected()
Presses the Weld Selected button in the edit floater.
Updatemap()
Presses the Update Map button in the edit floater.
 Unwrap_UVW : Modifier 1179

Displaymap <DisplayMap>
Toggles the Display Map button in the edit floater.
DisplayMap (boolean) – The state that you want to set the Display Map to.
IsMapDisplayed()
Returns the state of the Display Map button.
SetUVSpace <UVspace>
Sets the UV Space fly out in the edit floater.
UVSpace (integer) – The space that you want to view the texture vertices in:
1 – UV
2 – VW
3 – UW
GetUVSpace()
Returns the state of the UV Space fly out in the edit floater:
1 – UV
2 – VW
3 – UW
Options()
Presses the Options button in the edit floater.
Lock()
Toggles the Lock Selected Vertices button in the edit floater.
Hide()
Presses the Hide button in the edit floater.
Unhide()
Presses the Unhide button in the edit floater.
Freeze()
Presses the Freeze button in the edit floater.
Thaw()
Presses the Unfreeze button in the edit floater
FilterSelected()
Toggles the Filter Selected Faces button in the edit floater.
Pan()
Presses the Pan button in the edit floater.
Zoom()
Presses the Zoom button in the edit floater.
ZoomRegion()
Presses the Zoom Region button in the edit floater.
Fit()
Presses the Fit button in the edit floater.
FitSelected()
Presses the Fit Selected button in the edit floater.
1180 Chapter 11 | 3ds max Objects

Snap()
Presses the Snap button in the edit floater.
GetCurrentMap()
Returns the index into the map drop down list of the current map in the view of the edit
floater.
SetCurrentMap <map>
Changes the currently displayed map to the index provided.
map (integer) – The index of the map in the drop down list that you want to display.
NumberMaps()
Returns the number of maps in the map drop down list.
GetLineColor()
Returns the color of the lines used to connect the texture vertices edges as a Point3 value.
SetLineColor <color>
Sets the line color of the texture vertices.
color (point3) – The color that you want to set the lines to.
GetSelColor()
Returns the texture vertices selection color as a Point3 value.
SetSelColor <color>
Sets the color of selected texture vertices.
color (point3) – The color that you want the selected vertice to be.
GetRenderWidth <dist>
Returns the width of the bitmap used to render 2d/3d textures to.
SetRenderWidth <width>
Sets the width of the bitmap used to render to for display.
width (integer) – The width in pixels for the bitmap.
GetRenderHeight()
Returns the height of the bitmap used to render 2d/3d textures to.
SetRenderHeight <height>
Sets the width of the bitmap used to render to the display.
height (integer) - The height in pixels for the bitmap.
GetUseBitmapRes()
Returns the state of the Use Bitmap Resolution as a boolean value. If false, the bitmaps are
rendered using the RenderWidth/Height values.
SetUseBitmapRes <useBitmapRes>
Sets the state of the Use Bitmap Resolution value. If it is false the bitmaps are rendered
using the RenderWidth/Height values.
UseBitmapRes (boolean) - Toggle Use Bitmap Resolution.
GetWeldThresold()
Returns the weld threshold
 Unwrap_UVW : Modifier 1181

SetWeldThreshold <threshold>
Sets the threshold values for welds.
threshold (float) – Threshold for welds.
GetConstantUpdate()
Returns the state of Constant Update as a boolean value. When true, viewport is updated
on every move, otherwise it is just updated on mouse up.
SetConstantUpdate <constantUpdates>
Sets the state of the Constant Update value. When true, the viewport is updated on every
move, otherwise it is just updated on mouse up.
GetShowSelectedVertices()
Returns a boolean value which indicates whether the selected texture vertices are also
displayed in the view port.
SetShowSelectedVertices <show>
Sets whether the selected texture vertices are also displayed in the viewport.
show (boolean) – The state of Show Selected Vertices.
GetMidPixelSnape()
Returns a boolean value which indicated whether the mid pixels snap is used, if it is false
the snap is set to the bottom right corner of the pixel, else it snaps to the center of the
pixel.
SetMidPixelSnape <snap>
Sets whether mid pixels snap is used. When false, the snap is set to the bottom right corner
of the pixel. When true, it snaps to the center of the pixel.
snap (boolean) – The mid pixel snap state to be set.
GetMatID()
Returns the current material id index filter.
SetMatID <matid>
Sets the material drop list to the index supplied.
matid (integer) – The material id index to be set.
NumberMatIDs()
Returns the number of material ids in the material id filter drop down.
GetSelectedVerts()
Returns the current selected texture vertices in the edit floater as a bitarray.
SelectVerts <sel>
Selects texture vertices in the edit floater dialog.
sel (bitarray) – The selection set.
IsVertexSelected <index>
Returns a boolean value which indicates whether a texture vertex is selected.
index (integer) – The index of the vertex to check.
1182 Chapter 11 | 3ds max Objects

MoveSelectedVertices <offset>
Moves the selected texture vertices by the offset.
offset (point3) - The offset by which you want to move the vertices.
RotateSelectedVertices <angle>
Rotates the selected vertices around their center point.
angle (float) – The angle in radians that you want to rotate the selection by.
RotateSelectedVertices <angle> <axis>
Rotates the selected vertices around a specific axis.
angle (float) – The angle in radians that you want to rotate the selection by.
axis (point3) – The axis that you want to rotate the selected vertices by. This is in the
space of the window.
ScaleSelectedVertices <scale> <dir>
Scales the selected points around their center.
scale (float) – The amount that you want to scale by.
dir (integer) – The direction you want to scale by:
0 – Scales uniform
1 – Scales in the x
2 – Scales in the y
ScaleSelectedVertices <scale> <dir> <axis>
Scales the selected points around their center around the axis.
scale (float) – The amount that you want to scale by.
dir (integer) – The direction:
0 – Scales uniform
1 – Scales in the x
2 – Scales in the y
axis (point3) – The axis that you want to rotate the selected vertices by. This is in the
space of the window.
GetVertexPosition <time> <index>
Returns the position of the vertex as a Point3 value.
time (timevalue) – The time at which you wan to check.
index (integer) – The index of the vertex.
NumberVertices()
Returns the number of texture vertices.
MoveX <p>
This sets the selected vertices x values in absolute coordinates.
p (float) – The absolute position along the x axis.
 Unwrap_UVW : Modifier 1183

MoveY <p>
This sets the selected vertices y values in absolute coordinates.
p (float) – The absolute position along the y axis.
MoveZ <p>
This sets the selected vertices xzvalues in absolute coordinates.
p (float) – The absolute position along the z axis.
GetSelectedPolygons()
Returns the selected polygons in the view port as a bitarray.
SelectPolygons <sel>
Selects the polygons in the view ports.
sel (bitarray) – The polygons to select.
IsPolygonSelected <index>
Returns whether a polygon is selected or not.
index (integer) – Index of the polygon to check.
NumberPolygons()
Returns the number of polygons in the object.
DetachEdgeVerts()
Detaches any vertex that is not completely surrounded by selected vertices. This is similar
to a polygon selection detach except it uses the vertex selection to determine what is
detached.
FlipH()
This presses the Flip Horizontal button in the edit floater dialog.
FlipV()
This presses the Flip Vertical button in the edit floater dialog.
GetLockAspect()
Returns whether the edit window aspect ratio is locked or not. If the aspect ratio is not
locked the image will try stretch to fit the aspect ratio of the window.
SetLockAspect <aspect>
This sets the Lock Aspect Ratio value.
aspect (boolean) – Aspect lock toggle.
GetMapScale()
Returns the scaling factor when the user applies a planar map. The smaller the value the
more planar map is scaled down
SetMapScale <scale>
Sets the scaling factor when the user applies a planar map. The smaller the value the more
planar map is scaled down.
scale (float) - The scaling factor for planar map.
GetSelectionFromFace()
This takes the current polygon selection and uses it to select the texture vertices that are
associated with it.
1184 Chapter 11 | 3ds max Objects

ForceUpdate <update>
This sets a flag to determines how Unwrap will behave when a topology change occurs. If
update is TRUE the mapping gets reset, otherwise unwrap skips mapping the object if it
has a different topology. It is sometimes useful to turn this off if you have MeshSmooth or
other topology changing modifiers below Unwrap that have different topologies when
rendering.
update (boolean) – Determines whether the mapping is reset on topology change.
ZoomToGizmo <all>
This zooms the selected or all the viewports to zoom to the current planar map gizmo.
all (boolean) – Determines whether the active or all the viewports get zoomed.
UpdateView()
This forces the viewport and dialog to update.
SetVertexPosition <t> <index> <pos>
This sets the position of a UVW vertex at a specific time.
t (timeValue) – The time at what you want to set the pos.
index (integer) – The index of the vertex.
pos (point3) – The position of the vertex in UVW space.
The functions below work on the UVW topology allowing you to rearrange the topology or add new
topology. Use these with care since you can create invalid topology which can cause unpredictable
results. Unwrap has topology similar to meshes but it has been changed to support everything
except patches and polygons at the same time. Unwrap has a list of Point3 values which are the
texture vertices positions. Then there are texture faces which contain an array of integers which are
indices into the texture vertex list. There can be 3 to N number of ints in this array depending on
the topology being fed into Unwrap. In addition to this, there are also 2 arrays of integers for the
handles and interior handles if the topology is a patch which also points into the texture vertex list.
The functions below allow you to manipulate these arrays to do things like break, weld, and other
topological functions.
MarkAsDead <index>
This marks a vertex that it is dead, and no longer in use. Vertices are not actually deleted
they are just marked and recycled when needed. That means that when a vertex is added
vertices marked as dead will be the first ones checked. If there are no dead vertices, the
vertex is appended to the end of the list. Use this function carefully, since marking a vertex
in use as dead will cause strange results.
index (integer) – The index of the vertex to mark as dead.
NumberPointsInFace <index>
This retrieves the numbers of vertices that a face contains. A face can contain 3 to N
number of points depending on what type of topology Unwrap is working on. For Tri
Meshes this is always 3; for patches this can be 3 or 4; and for polygons this can be 3 or
greater. Unwrap abstracts all three object types into one generic format.
index (integer) – The index of the face that you are inspecting.
 Unwrap_UVW : Modifier 1185

GetVertexIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a vertex, from a face. A face contains 0 to N number of vertices,
so to retrieve a particular vertex index, you give it the face index and the ith vertex that
you want to inspect. For example, if you wanted to look at the 3 vertex on face 1 you
would call GetVertexIndexFromFace (1,3).
FaceIndex (integer) – The index of the face that you want to inspect.
IthVertexIndex (integer) – The ith vertex of that you want to retrieve. This value should
range from 1 to the number of vertices that the face contains.
GetHandleIndexFromFace <faceindex> <ithVertexIndex>
This retrieves the index of a handle, from a face, which contains 0 to N number of
handles. To retrieve a particular handle index, you give it the face index and the ith handle
that you want to inspect. For example, if you wanted to look at the 3 handle on face 1 you
would call GetHandleIndexFromFace (1,3). This only applies to patch meshes.
FaceIndex (integer) – The index of the face that you want to inspect.
IthVertexIndex (integer) – The ith handle of that you want to retrieve. This value
should range from 1 to the twice the number of vertices that the face contains.
GetInteriorIndexFromFace <faceindex> <ithVertexIndex>
This retrieves the index of a interior handle from a face. A face contains 0 to N number of
interior handles, so to retrieve a particular interior handle index, you give it the face index
and the ith interior handle that you want to inspect. For example, if you wanted to look at
the 3 interior handle on face 1 you would call GetInteriorIndexFromFace (1,3). This only
applies for patch meshes.
FaceIndex (integer) – The index of the face that you want to inspect.
IthVertexIndex (integer) – The ith interior handle of that you want to retrieve. This
value should range from 1 to the number of vertices that the face contains.
GetVertexGIndexFromFace <faceindex> <ithVertexIndex>
This retrieves the index of a geometric vertex from a face. This the vertex that is attached
to the mesh and not the texture faces. A face contains 0 to N number of vertices, so to
retrieve a particular vertex index, you give it the face index and the ith vertex that you
want to inspect. For example, if you wanted to look at the 3 vertex on face 1 you would
call GetVertexGeomIndexFromFace (1,3).
FaceIndex (integer) – The index of the face that you want to inspect.
IthVertexIndex (integer) – The ith vertex of that you want to retrieve. This value should
range from 1 to the number of vertices that the face contains.
GetHandleGIndexFromFace <faceindex> <ithVertexIndex>
This retrieves the index of a geometric handle from a patch. This the handle that is
attached to the patch and not the texture faces. A face contains 0 to N number of handles,
so to retrieve a particular handle index, you give it the face index and the ith handle that
you want to inspect. For example, if you wanted to look at the 3 handle on face 1 you
would call GetHandleGeomIndexFromFace(1,3).
1186 Chapter 11 | 3ds max Objects

FaceIndex (integer) – The index of the face that you want to inspect.
IthVertexIndex (integer) – The ith handle of that you want to retrieve. This value
should range from 1 to twice the number of vertices that the face contains.
GetInteriorGIndexFromFace <faceindex> <ithVertexIndex>
This retrieves the index of a geometric interior handle from a patch. This the interior
handle that is attached to the patch and not the texture faces. A face contains 0 to N
number of interior handles, so to retrieve a particular interior handle index, you give it the
face index and the ith interior handle that you want to inspect. For example, if you
wanted to look at the 3 interior handle on face 1 you would call
GetInteriorGeomIndexFromFace (1,3).
FaceIndex (integer) – The index of the face that you want to inspect.
IthVertexIndex (integer) – The ith interior handle of that you want to retrieve. This
value should range from 1 to the number of vertices that the face contains.
SetFaceVertex <pos> <fIndex> <vIndex> <sel>
This allows you to manipulate the position of vertex attached to a face. Basically, it
detaches the vertex if multiple faces share that vertex and then moves it to the position
specified. So if you want to move the 3rd vertex of face 1 to (.5,.5,.0) you would do
setFaceVertex [.5 .5 .0] 1 3. If you don’t want the vertex broken use SetVertexSPosition.
pos (point3) - The position that you want to move a vertex to.
fIndex (integer) – The index of the face that you wish to work on.
vIndex (integer) – The ith vertex of the face that you want to change.
sel (boolean) – Whether or not to select the vertex after it is recreated.
SetFaceHandle <pos> <fIndex> <vIndex> <sel>
Identical to SetFaceVertex except works on patch handles.
pos (point3) - The position that you want to move a vertex to.
fIndex (integer) – The index of the face that you wish to work on.
vIndex (integer) – The ith vertex of the face that you want to change.
sel (boolean) – Whether or not to select the vertex after it is recreated.
SetFaceInterior <pos> <fIndex> <vIndex> <sel>
Identical to SetFaceVertex except works on patch interior handles.
pos (point3) - The position that you want to move a vertex to.
fIndex (integer) – The index of the face that you wish to work on.
vIndex (integer) – The ith vertex of the face that you want to change.
sel (boolean) – Whether or not to select the vertex after it is recreated.
 UVW_Xform : Modifier 1187

SetFaceVertexIndex <fIndex> <ithV> <vIndex>

This allows you to set the index of the ith vertex of a face. For example, if you wanted to
change the index of the 3rd vertex of face 1 to 100 you would call setFaceVertexIndex
1 3 100.
fIndex (integer) – Index of the face you want work on.
ithV (integer) – The ith vertex that you want to manipulate.
vIndex (integer) – The index into the vertex list that you want to set to.
SetFaceHandleIndex <fIndex> <ithV> <vIndex>
Identical to setFaceVertexIndex but works on handles for patches.
fIndex (integer) – Index of the face you want work on.
ithV (integer) – The ith vertex that you want to manipulate.
vIndex (integer) – The index into the vertex list that you want to set to.
SetFaceInteriorIndex <fIndex> <ithV> <vIndex>
Identical to setFaceVertexIndex but works on interior handles for patches.
fIndex (integer) – Index of the face you want work on.
ithV (integer) – The ith vertex that you want to manipulate.
vIndex (integer) – The index into the vertex list that you want to set to.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

UVW_Xform : Modifier
Constructor:
uvw_xform ...

Properties:
<UVW_Xform>.U_Tile Float default: 1.0 -- animatable
The tiling along the U-axis.
<UVW_Xform>.U_Flip Integer default: 0
When on, reverses the direction of the map along the U-axis.
OFF
ON
<UVW_Xform>.V_Tile Float default: 1.0 -- animatable
The tiling along the V-axis.
1188 Chapter 11 | 3ds max Objects

<UVW_Xform>.V_Flip Integer default: 0

When on, reverses the direction of the map along the V-axis.
OFF
ON
<UVW_Xform>.W_Tile Float default: 1.0 -- animatable
The tiling along the W-axis.
<UVW_Xform>.W_Flip Integer default: 0
When on, reverses the direction of the map along the W-axis.
OfFF
ON
<UVW_Xform>.U_Offset Float default: 0.0 -- animatable
Offsets the map along the U-axis.
<UVW_Xform>.V_Offset Float default: 0.0 -- animatable
Offsets the map along the V-axis.
<UVW_Xform>.W_Offset Float default: 0.0 -- animatable
Offsets the map along the W-axis.
<UVW_Xform>.Map_or_Vertex_Color Integer default: 0
Specifies whether to apply the transform to a mapping channel or a vertex color channel:
Map Channel
Vertex Color Channel
Note:
The Map Channel property is not accessible by MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

UVWmap : Modifier
Constructor:
uvwmap ...

Properties:
<Uvwmap>.maptype Integer default: 0
Determines the type of mapping coordinates used. Different kinds of mapping are
distinguished by how the map is geometrically projected onto the object and how the
projection interacts with the object’s surfaces.
 UVWmap : Modifier 1189

Planar (Projects the map from a single plane flat against the object, somewhat like
projecting a slide. Planar projection is useful when only one side of an object needs to be
mapped. It is also useful for obliquely mapping multiple sides, and for mapping two sides
of a symmetrical object.)
Cylindrical (Projects the map from a cylinder, wrapping it around an object. Seams where
the edges of the bitmap meet are visible unless a seamless map is used. Cylindrical
projection is useful for objects that are roughly cylindrical in shape.)
Spherical (Surrounds the object by projecting the map from a sphere. You see a seam and
mapping singularities at the top and bottom of the sphere where the bitmap edges meet at
the sphere’s poles. Spherical mapping is useful for objects that are roughly spherical in
shape.)
Shrink Wrap (Uses spherical mapping, but truncates the corners of the map and joins
them all at a single pole, creating only one singularity. Shrink-wrap mapping is useful
when you want to hide the mapping singularity.)
Box (Projects the map from the six sides of a box. Each side projects as a planar map, and
the effect on the surface depends on the surface normal. Each face is mapped from the
closest box surface whose normal most closely parallels its own normal.)
Face (Applies a copy of the map to every face of an object. Pairs of faces sharing a hidden
edge are mapped with the full rectangular map. Single faces with no hidden edge are
mapped with a triangular portion of the map.)
XYZ to UVW (Maps 3D procedural coordinates to UVW coordinates. This “sticks” the
procedural texture to the surface. If the surface stretches, so does the 3D procedural map.)
<Uvwmap>.cap Boolean default: false
When on, applies planar mapping coordinates to the caps of the cylinder.
<Uvwmap>.length Float default: 1.0 -- animatable
The length of the UVW mapping gizmo.
<Uvwmap>.width Float default: 1.0 -- animatable
The width of the UVW mapping gizmo.
<Uvwmap>.height Float default: 1.0 -- animatable
The height of the UVW mapping gizmo.
<Uvwmap>.utile Float default: 1.0 -- animatable, alias: U_Tile
The tiling of the UVW map along the U-axis.
<Uvwmap>.uflip Boolean default: false
When on, reverses the image about the U-axis.
<Uvwmap>.vtile Float default: 1.0 -- animatable, alias: V_Tile
The tiling of the UVW map along the V-axis.
<Uvwmap>.vflip Boolean default: false
When on, reverses the image about the V-axis.
<Uvwmap>.wtile Float default: 1.0 -- animatable, alias: W_Tile
The tiling of the UVW map along the W-axis.
1190 Chapter 11 | 3ds max Objects

<Uvwmap>.wflip Boolean default: false

When on, reverses the image about the W-axis.
<Uvwmap>.channel Integer default: 0
Specifies whether to apply the transform to a mapping channel or a vertex color channel:
Map Channel
Vertex Color Channel
<Uvwmap>.mapChannel Integer default: 1
The map channel used to apply mapping transforms.
<Uvwmap>.axis Integer default: 2
Specifies which axis of the gizmo is aligned with the local Z-axis of the object:
X
Y
Z
<Uvwmap>.gizmo SubAnim
Enables gizmo transformations. Turn on and then move, scale, and rotate the gizmo in the
viewports to position the map. In the Material Editor, you turn on the Show Map in
Viewport option to make the map visible in a shaded viewport, the map moves on the
surface of the object as you transform the gizmo.
<Uvwmap.Gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the UVWmap gizmo.
<Uvwmap.Gizmo>.rotation Quat default: (quat 0 0 -1 0) -- animatable
The rotation of the UVWmap gizmo.
<Uvwmap.Gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the UVWmap gizmo.
Note:
The Map Channel property is not accessible by MAXScript in 3ds max 4.
The Gizmo property is not present until the Uvwmap modifier has been applied to a node.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Vertex_Colors : Modifier 1191

Vertex_Colors : Modifier
Constructor:
The Vertex_Colors modifier is not creatable by MAXScript. It can only be created
using the Assign Vertex Colors utility.

Properties:
There are no additional properties for Vertex_Colors.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

VertexPaint : Modifier
Constructor:
vertexPaint ...

Note: This class is not available in 3D Studio VIZ.

Properties:
There are no additional properties for VertexPaint.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1192 Chapter 11 | 3ds max Objects

VolumeSelect : Modifier
Constructor:
volumeselect ...

Properties:
<Volumeselect>.level Integer default: 0
Volume Select provides three selection levels. Vertex and Face levels put the modifier stack
in sub-object selection. You can make one sub-object selection for each Volume Select
modifier. You can then toggle the one selection between Face and Vertex level to send
either up the stack. Object (top) level lets you modify the whole object while retaining any
sub-object selection.
Object
Vertex
Face
<Volumeselect>.type Integer default: 0
Sets the volume select type:
Replace (Clears any selection passed up the stack to the Volume Select modifier, and then
selects geometry within the volume.)
Add (Selects all geometry within the volume, adding to any previous selection.)
Subtract (Deselects all geometry within the volume.)
<Volumeselect>.invert Boolean default: false
When on, the entire selection set is reversed. Geometry that was unselected becomes
selected, and vice versa.
<Volumeselect>.method Integer default: 0
Lets you determine whether selected faces are wholly or partially within the defined
volume:
Window (Selects only faces with all three vertices within the selection volume.)
Crossing (Selects faces with only one vertex within the selection volume.)
<Volumeselect>.volume Integer default: 0
These controls let you define the selection with a primitive, a mesh object, or by surface
characteristics:
Box
Sphere
Cylinder
Mesh Object
Texture Map
Material Id
Smoothing Group
 VolumeSelect : Modifier 1193

<Volumeselect>.Node Node default: undefined

The node which defines the selection space when .volume is set to 3 (mesh object).
<Volumeselect>.matID Integer default: 1 -- alias:
Material_ID
When .volume is set to 5 (material ID), all faces or vertices using the material ID specified
by this value are selected.
<Volumeselect>.smGroup Integer default: 1 -- alias:
Smoothing_Group
When .volume is set to 6 (smoothing group), all faces or vertices using the smoothing
group specified by this value are selected.
<Volumeselect>.texture TextureMap default: undefined -- alias:
TextureMap
When .volume is set to 4 (texture map), this texture map will define the selection space.
<Volumeselect>.map Integer default: 0 -- alias:
Map_Channel_Type
Specifies whether to apply the selection by mapping channel or vertex color channel:
Map Channel
Vertex Color Channel
<Volumeselect>.mapChannel Integer default: 1 -- alias:
Map_Channel
Specifies which map channel to use when .map is set to 0.
<Volumeselect>.autofit Boolean default: true -- alias: Auto_fit
When on, automatically adjusts the gizmo size and shape to fit the object as you change
the underlying topology.
<Volumeselect>.UseAffectRegion Boolean default: false -- alias:
Use_affect_region
When on, a soft selection region is applied.
<Volumeselect>.falloff Float default: 20.0 -- animatable
Distance in current units from the center to the edge of a sphere defining the affected
region. Use higher falloff settings to achieve more gradual slopes, depending on the scale
of your geometry.
<Volumeselect>.pinch Float default: 0.0 -- animatable
Raises and lowers the top point of the curve along the vertical axis. Sets the relative
“pointedness” of the region. When negative, a crater is produced instead of a point. At a
setting of 0, Pinch produces a smooth transition across this axis.
<Volumeselect>.bubble Float default: 0.0 -- animatable
Expands and contracts the curve along the vertical axis. Sets the relative “fullness” of the
region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for
Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble
move the bottom of the curve below the surface, creating a “valley” around the base of the
region.
1194 Chapter 11 | 3ds max Objects

<Volumeselect>.center Point3 default: [0,0,0] -- animatable

You can translate and animate the center, which affects rotation or scaling of the Volume
Select modifier’s gizmo.
<Volumeselect>.gizmo SubAnim
You can transform and animate the gizmo to change the selection. Translating the gizmo
translates its center an equal distance. Rotating and scaling the gizmo takes place with
respect to its center.
<Volumeselect.Gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the volumeselect gizmo.
<Volumeselect.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the volumeselect gizmo.
<Volumeselect.Gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the volumeselect gizmo.
Note:
The Map Channel property is not accessible by MAXScript in 3ds max 4.
The center and gizmo properties are not present until the Volumeselect modifier has been applied
to a node.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Wave : Modifier
Constructor:
wave ...

Properties:
<Wave>.amplitude1 Float default: 5.0 -- animatable, alias: Amplitude_1
This produces a sine wave along the gizmo’s Y-axis. Switching a value from positive to
negative reverses the positions of peaks and troughs.
<Wave>.amplitude2 Float default: 5.0 -- animatable, alias: Amplitude_2
This produces a sine wave the gizmo’s X-axis. Switching a value from positive to negative
reverses the positions of peaks and troughs.
<Wave>.wavelength Float default: 25.0 -- animatable, alias: Wave_Length
The distance in current units between the crests of both waves.
<Wave>.phase Float default: 0.0 -- animatable
Shifts the wave pattern over the object. Positive numbers move the pattern in one
direction, while negative numbers move it in the other.
 XForm : Modifier 1195

<Wave>.decay Float default: 0.0 -- animatable

Limits the effect of the wave generated from its origin. A decay value decreases the
amplitude at increasing distance from the center. As this value increases, the wave is
concentrated at the center and flattened until it disappears (completely decays).
<Wave>.center Point3 default: [0,0,0] -- animatable
At this sub-object level, you can translate and animate the center, altering the Wave
gizmo’s shape, and thus the shape of the wavy object.
<Wave>.gizmo SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object,
altering the effect of the Wave modifier. Translating the gizmo translates its center an
equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Wave.Gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the wave gizmo.
<Wave.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable
The rotation of the wave gizmo.
<Wave.Gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the wave gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

XForm : Modifier
Constructor:
xform ...

Properties:
<XForm>.center Point3 default: [0,0,0] -- animatable
At this sub-object level, you can translate and animate the center, altering the Xform
gizmo’s shape, and thus the shape of the object.
<XForm>.gizmo SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object,
altering the effect of the Xform modifier. Translating the gizmo translates its center an
equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<XForm.Gizmo>.position Point3 default: [0,0,0] -- animatable
The position of the wave gizmo.
1196 Chapter 11 | 3ds max Objects

<XForm.Gizmo>.rotation Quat default: (quat 0 0 0 1) -- animatable

The rotation of the wave gizmo.
<XForm.Gizmo>.scale Point3 default: [1,1,1] -- animatable
The scale of the wave gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099)
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Spacewarp Binding SpacewarpModifiers

The SpaceWarp Binding SpacewarpModifiers are not directly created in MAXScript, but are rather
created and applied to a node using the bindSpaceWarp() method. Most of the
SpacewarpModifiers do not have any additional properties.
Constructors and Properties:
SimpleOSMToWSMMod:
bindSpaceWarp <node> <spaceBend_node>
bindSpaceWarp <node> <spaceNoise_node>
bindSpaceWarp <node> <spaceSkew_node>
bindSpaceWarp <node> <spaceStretch_node>
bindSpaceWarp <node> <spaceTaper_node>
bindSpaceWarp <node> <spaceTwist_node>

BombBinding:
bindSpaceWarp <node> <bomb_node>

DeflectorBinding:
bindSpaceWarp <particlesys_node> <deflector_node>

DisplaceBinding:
bindSpaceWarp <node> <spaceDisplace_node>

FFD_Binding:
bindSpaceWarp <node> <spaceFFDBox_node>
bindSpaceWarp <node> <spaceFFDCyl_node>

GravityBinding:
bindSpaceWarp <node> <gravity_node>

MotorMod:
bindSpaceWarp <node> <motor_node>

PathFollowMod:
bindSpaceWarp <particlesys_node> <path_Follow_node>
 XForm : Modifier 1197

PBombMod:
bindSpaceWarp <node> <pbomb_node>

PDynaFlectMod:
bindSpaceWarp <node> <PDynaFlect_node>

POmniFlectMod:
bindSpaceWarp <particlesys_node> <POmniFlect_node>

PushMod:
bindSpaceWarp <node> <pushSpaceWarp_node>

RippleBinding:
bindSpaceWarp <node> <spaceRipple_node>
<RippleBinding>.Flexibility Float default: 1.0 -- animatable

SDeflectMod:
bindSpaceWarp <particlesys_node> <sdeflector_node>

SDynaFlectMod:
bindSpaceWarp <node> <SDynaFlect_node>

SOmniFlectMod:
bindSpaceWarp <particlesys_node> <SOmniFlect_node>

SpaceConform:
bindSpaceWarp <node> <conformSpaceWarp_node>

UDeflectorMod:
bindSpaceWarp <particlesys_node> <uDeflector_node>

UDynaFlectMod:
bindSpaceWarp <node> <UDynaFlect_node>

UOmniFlectMod:
bindSpaceWarp <particlesys_node> <UOmniFlect_node>

WaveBinding:
bindSpaceWarp <node> <spaceWave_node>
<WaveBinding>.Flexibility Float default: 1.0 -- animatable

WindBinding:
bindSpaceWarp <node> <wind_node>

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1198 Chapter 11 | 3ds max Objects

Other SpacewarpModifiers

Displace_Mesh : SpacewarpModifier
Constructor:
displace_Mesh ...

Properties:
There are no additional properties for Displace_Mesh.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Displace_NURBS : SpacewarpModifier
Constructor:
displace_NURBS ...

Properties:
There are no additional properties for Displace_NURBS.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

MapScaler : SpacewarpModifier
Constructor:
MapScaler ...

Properties:
<MapScaler>.scale Float default: 100.0 -- animatable
The size of one repeat of the texture pattern. Size is measured in current scene units.
Repeats occur across the object in the U direction.
<MapScaler>.channel Integer default: 1
The map channel used.
 SpaceCameraMap : SpacewarpModifier 1199

<MapScaler>.Wrap_Texture Integer default: 1

When on, Map Scaler attempts to wrap the texture evenly around the object. This option
requires more computing, but usually produces the most satisfactory results.
OFF
ON
<MapScaler>.Up_Direction Integer default: 1
Sets the map alignment:
World Z Axis (Aligns the map with the Z axis of the world.)
Local Z Axis (Aligns the map with the local Z axis of the object.)

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SpaceCameraMap : SpacewarpModifier
Constructor:
SpaceCameraMap ...

Properties:
<SpaceCameraMap>.camera Node default: undefined

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SpacePatchDeform : SpacewarpModifier
Constructor:
SpacePatchDeform ...

Properties:
<SpacePatchDeform>.U_Percent Float default: 50.0 -- animatable,
percentage
Moves the object along the U (horizontal) axis of the gizmo patch, based on a percentage
of the U distance. This defaults to a setting of 50 percent, which places the object at the
center of the gizmo patch. A setting of 0 percent places the object at the left edge of the
gizmo patch, as seen from the viewport where the patch was created.
1200 Chapter 11 | 3ds max Objects

<SpacePatchDeform>.U_Stretch Float default: 1.0 -- animatable

Scales the object along the U (horizontal) axis of the gizmo patch.
<SpacePatchDeform>.V_Percent Float default: 50.0 -- animatable,
percentage
Moves the object along the V (vertical) axis of the gizmo patch, based on a percentage of
the V distance. A setting of 0 percent places the object at the bottom of the gizmo patch.
<SpacePatchDeform>.V_Stretch Float default: 1.0 -- animatable
Scales the object along the V (vertical) axis of the gizmo patch.
<SpacePatchDeform>.rotation Float default: 0.0 -- animatable,
angle
Rotates the modified object with respect to the gizmo patch.
<SpacePatchDeform>.Plane_to_Patch_Deform Integer default: 0
Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo
patch:
XY
YZ
ZX
<SpacePatchDeform>.Flip_deformation_axis Integer default: 0
When on, reverses the gizmo direction:
OFF
ON
Note:
There is no way to specify the patch to deform to using MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SpacePathDeform : SpacewarpModifier
Constructor:
SpacePathDeform ...

Properties:
<SpacePathDeform>.path Node default: undefined
The node designated as the path.
<SpacePathDeform>.Percent_along_path Float default: 0.0 -- animatable,
percentage
Moves the object along the gizmo path based on a percentage of the path length.
 SpaceSurfDeform : SpacewarpModifier 1201

<SpacePathDeform>.Stretch Float default: 1.0 -- animatable

Scales the object along the gizmo path, using the object’s pivot point as the base of
the scale.
<SpacePathDeform>.rotation Float default: 0.0 -- animatable,
angle
Rotates the object about the gizmo path.
<SpacePathDeform>.Twist Float default: 0.0 -- animatable,
angle
Twists the object about the path. The twist angle is based on the rotation of one end of the
overall length of the path. Typically, the deformed object takes up only a portion of the
path, so the effect can be subtle.
<SpacePathDeform>.axis Integer default: 2
Choose one to rotate the gizmo path to align with a specified local axis of the object:
X
Y
Z
<SpacePathDeform>.Flip_deformation_axis Integer default: 0
When on, reverses the gizmo path 180 degrees about the specified axis.
OFF
ON

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

SpaceSurfDeform : SpacewarpModifier
Constructor:
SpaceSurfDeform ...

Properties:
<SpaceSurfDeform>.surface Node default: undefined
The surface used for deformation.
<SpaceSurfDeform>.U_Percent Float default: 50.0 -- animatable,
percentage
Moves the object along the U (horizontal) axis of the gizmo patch, based on a percentage
of the U distance. This defaults to a setting of 50 percent, which places the object at the
center of the gizmo patch. A setting of 0 percent places the object at the left edge of the
gizmo patch, as seen from the viewport where the patch was created.
1202 Chapter 11 | 3ds max Objects

<SpaceSurfDeform>.U_Stretch Float default: 1.0 -- animatable

Scales the object along the U (horizontal) axis of the gizmo patch.
<SpaceSurfDeform>.V_Percent Float default: 50.0 -- animatable,
percentage
Moves the object along the V (vertical) axis of the gizmo patch, based on a percentage of
the V distance. A setting of 0 percent places the object at the bottom of the gizmo patch.
<SpaceSurfDeform>.V_Stretch Float default: 1.0 -- animatable
Scales the object along the V (vertical) axis of the gizmo patch.
<SpaceSurfDeform>.rotation Float default: 0.0 -- animatable,
angle
Rotates the modified object with respect to the gizmo patch.
<SpaceSurfDeform>.Plane_to_Patch_Deform Integer default: 0
Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo
patch:
XY
YZ
ZX
<SpaceSurfDeform>.Flip_deformation_axis Integer default: 0
Flip_deformation_axis = 0 - off; 1 - on

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Surface_Mapper : SpacewarpModifier
Constructor:
surface_mapper ...

Properties:
There are no additional properties for Surface_Mapper.
Methods:
updateSurfaceMapper <surface_mapper>
This method has the effect of performing a manual update to the mapping provided by
the associated NURBS surface.
Note:
There is no way to specify the Source Texture Surface using MAXScript in 3ds max 4.
 Material Common Properties, Operators, and Methods 1203

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Material : MAXWrapper
The Material class represents the materials which you can assign to objects in 3ds max. You can
create materials like standard, blend, and raytrace, access various properties on them, and assign
these materials to 3ds max objects.
The classes derived directly from the Material class are described in the Material Types (p. 1204) topic.
Other classes are derived from these classes, and inherit the properties and methods defined for the
Material class.
The properties, operators, and methods that are common to all classes derived directly from the
Material class are described in the Material Common Properties, Operators, and Methods (p. 1203) topic.
The Material class is derived from the MAXWrapper class, and inherits the properties and methods
defined for that class. These properties and methods are described in the MAXWrapper (p. 808) topic.

Material Common Properties, Operators, and Methods

Properties:
<material>.name
All the material subclasses can access the name property and specify it as a constructor
parameter.
<material>.effectsChannel
All the material subclasses can access the effectsChannel property and specify it as a
constructor parameter.
Methods:
assignNewName <material>
Modifies the name of the specified material to make it unique. The name is of the form
“Material #1” where the number is incremented as required to make ensure it’s unique.
okMtlForScene <material>
Tests the material name against other material names in the scene, and returns true if
there are no other materials with the same name, false otherwise. Before assigning
material to scene, call this to avoid duplicate names.
1204 Chapter 11 | 3ds max Objects

getMTLMEditFlags ( <material> | <texture> )

setMTLMEditFlags ( <material> | <texture> ) <bitarray>
Get and set the MEdit options for the specified material or texture as a <bitarray>. If a bit is
on, the corresponding option is turned on. The order of the bits is:
#{MTL_BEING_EDITED,BACKGROUND,BACKLIGHT,VIDEO_COLOR_CHECK}
The first bit is set if the rollout for the specified material or texture is currently displayed in
the active MEdit slot. The state of this bit is ignored in setMTLMEditFlags().
getMTLMeditObjType ( <material> | <texture> )
setMTLMeditObjType ( <material> | <texture> ) <integer>
Get and set the MEdit sample object type for the specified material or texture. The valid
values are: 1 - sphere; 2 - cylinder; 3 - cube; 4 - custom
getMTLMeditTiling ( <material> | <texture> )
setMTLMeditTiling ( <material> | <texture> ) <integer>
Get and set the MEdit tiling type for the specified material or texture. The valid values are:
1 - 1x1; 2 - 2x2; 3 - 3x3; 4 - 4x4
updateMTLInMedit ( <material> | <texture> )
Performs a set of 3ds max notifications that forces an update of the material or texture
throughout 3ds max, including the MEdit and material browser.
You can get and set Material Editor materials using the getMeditMaterial() and
setMeditMaterial() functions. You can also get a material from the Material Editor using the
meditMaterials virtual array. See the Material Editor (p. 1606) and MaterialLibrary Values (p. 795)
topics for more information.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Material Types
The following list displays the 3ds max material subclasses:
Blend (p. 1205)
Composite (p. 1206)
DoubleSided (p. 1207)
MatteShadow (p. 1208)
MorpherMaterial (p. 1209)
MultiMaterial (p. 1210)
 Blend : Material 1205

NoMaterial (p. 1212)

RaytraceMaterial (p. 1212)
Shellac (p. 1233)
Standard (p. 1224)
TopBottom (p. 1233)

Blend : Material
Constructor:
blend ...

Properties:
<blend>.map1 Material default: Standard -- alias: Map_1
The first material to be blended.
<blend>.map1Enabled Boolean default: true -- alias: Map_1_Enable
Turn on/off the use of the first material in the blend.
<blend>.map2 Material default: Standard -- alias: Map_1
the second material to be blended.
<blend>.map2Enabled Boolean default: true -- alias: Map_2_Enable
Turn on/off
<Blend>.mask TextureMap default: undefined
Selects a map to use as a mask. The two materials will blend in greater or lesser degree
according to the intensity of the map. Lighter (whiter) areas of the mask show Material 1.
Darker (blacker) areas of the mask show Material 2.
<blend>.maskEnabled Boolean default: true -- alias: MaskEnable
Enable/disable the use of the map mask.
<blend>.interactive Integer default: 0
Selects which of the two materials is displayed on object surfaces in viewports by the
interactive renderer:
Material 1
Material 2
<blend>.mixAmount Float default: 0.0 -- animatable; percentage
The proportion of the blend (percentage). 0 means only Material 1 is visible on the surface;
100 means only Material 2 is visible.
1206 Chapter 11 | 3ds max Objects

<blend>.useCurve Boolean default: false

Determines whether the Mixing Curve affects the mix.
<blend>.upper Float default: 0.75 -- animatable
<blend>.lower Float default: 0.25 -- animatable
These values adjust the level of the Upper and Lower limits. If the two values are the same,
the two materials meet at a definite edge. Wider ranges give more gradual blending from
one sub-material to the other. The mixing curve displays the effect of changing these
values.

See also
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

CompositeMaterial : Material
Constructor:
compositeMaterial()

Properties:
<compositematerial>.materialList Array default: #(Standard, undefined, ... ,
undefined, undefined) -- alias: Material
This array contains all of the materials included in the composite material.
<compositematerial>.mapEnables Array default: #(true, true, ... , true,
true) -- alias: Map_Enable
This array turns on/off the use of materials (corresponding to the .materialList array)
in the composite material.
<compositematerial>.mixType Array default: #(0, 0, ... , 0,
0) -- alias: Composite_Type
This array sets the mix type for each material in the .materialList of the composite
material:
Additive
Subtractive
Mix
<compositematerial>.amount Array default: #(100.0, 100.0, ... , 100.0,
100.0) -- animatable
This array sets the amount of mixing for each corresponding material in the
.materialList.
<compositematerial>.baseMaterial Standard Material default: (null) – alias for
materialList[0]
S ets a base material for the composite material.
 DoubleSided : Material 1207

Note:
The materialList array stores the material for the base material and the sub-materials, the
mapEnables array stores whether a sub-material is enabled, the mixTypes array stores the type of
mixing to be performed for a sub-material, and the mixTypes array stores the amount of mixing to
be performed for a sub-material. The materialList array contains N elements, corresponding to
the base material and the (N-1) sub-materials. The remaining arrays store (N-1) elements,
corresponding to the (N-1) sub-materials.
A property alias exists for each element of the amount array. The property aliases have the name
amount_X, where X is the array element index. So the alias for the first amount element is amount_1,
for the second amount_2, etc.
baseMaterial is an alias for materialList[1].

See also
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

DoubleSided : Material
Constructor:
doubleSided ...
doubleSidedMat ...

Properties:
<DoubleSided>.translucency Float default: 0.0 -- animatable
The amount that one material shows through the other. This is a percentage that can
range from 0.0 to 100.0. At 100 percent, the outer material is visible on inner faces and the
inner material is visible on outer faces. At intermediate values, the specified percentage of
the inner material “bleeds through” and is visible on outer faces.
<DoubleSided>.material1 Material default: Standard -- alias: Material_1
The facing material.
<DoubleSided>.map1Enabled Boolean default: true -- alias: Map_1_Enable
Turn on/off display of the facing material.
<DoubleSided>.material2 Material default: Standard -- alias: Material_2
The back material.
<DoubleSided>.map2Enabled Boolean default: true -- alias: Map_2_Enable
Turn on/off display of the back material.
1208 Chapter 11 | 3ds max Objects

See also
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

MatteShadow : Material
Constructor:
matteShadow ...
matte ...

Properties:
<MatteShadow>.opaqueAlpha Boolean default: true -- alias: Opaque_Alpha
Determines whether or not the matte material appears in the alpha channel. If you turn
off Opaque Alpha, the matte object will not make an alpha channel, and the image can be
used for compositing, just as if there are no matte objects in the scene.
<MatteShadow>.applyAtmosphere Boolean default: false
Turns the fogging of matte objects on and off.
<MatteShadow>.atmosphereDepth Integer default: 0
When applying fog, you can choose between two different methods. You can either apply
fog as if the matte surface is at an infinite distance from the camera or you can apply it as
if the matte surface is actually at that point on the object being shaded. In other words,
you can apply the fog to the matte surface in either 2D or 3D. The following controls
determine how this is applied:
At Background Depth (This is the 2D method. The scanline renderer fogs the scene, and
then renders its shadows. In this case, the shadows won’t be lightened by the fog. If you
want to lighten the shadows, you need to turn up the shadow brightness.)
At Object Depth (This is the 3D method. The renderer first renders the shadows, and then
fogs the scene. Since this varies the amount of fog over the 3D matte surface, the generated
matte/alpha channels don’t blend perfectly into the background. Use At Object Depth
when the matte object is meant to be a 3D object in the scene that the 2D background
represents.)
<MatteShadow>.receiveShadows Boolean default: false
When on, renders shadows on the matte surfaces.
<MatteShadow>.affectAlpha Boolean default: false
When on, shadows cast on a matte material are applied to the alpha channel. This lets you
render bitmaps with alpha channels that you can composite later.
 MorpherMaterial : Material 1209

<MatteShadow>.shadowBrightness Float default: 0.0 -- animatable, alias:

Shadow_Brightness
Sets shadow brightness. At 0.5, the shadows will not be attenuated on the matte surface; at
1.0, the shadows are brightened to the color of the matte surface; and at 0.0 they are
darkened to completely obliterate the matte surface.
<MatteShadow>.color Color default: (color 0 0 0) -- animatable,
alias: Shadow_Color
The color of the shadow.
<MatteShadow>.amount Float default: 50 -- animatable,
percentage, alias: Reflection_Amount
The amount of reflection to use. This is a percentage that can range from 0 to 100.
<MatteShadow>.map TextureMap default: undefined
The map used for reflections.
<MatteShadow>.useReflMap Boolean default: true
Turns on/off the use of a reflection map.

See also
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

MorpherMaterial : Material
Constructor:
morphermaterial ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<MorpherMaterial>.Channel_0 Float default: 0.0 -- animatable, percentage
<MorpherMaterial>.Channel_1 Float default: 0.0 -- animatable, percentage
<MorpherMaterial>.Channel_2 Float default: 0.0 -- animatable, percentage
...
<MorpherMaterial>.Channel_98 Float default: 0.0 -- animatable, percentage
<MorpherMaterial>.Channel_99 Float default: 0.0 -- animatable, percentage
<MorpherMaterial>.Channel_100 Float default: 0.0 -- percentage
Note:
The Morph modifier associated with a MorpherMaterial can not be set using MAXScript in
3ds max 4.
The Channel_N properties are instances of the Morph modifier channel percentage properties,
where MorpherMaterial Channel_N corresponds to the Morph modifier channel N+1. The
MorpherMaterial Channel_100 value corresponds to Morph modifier base object percentage.
1210 Chapter 11 | 3ds max Objects

The Channel_N property values are 100* the value shown for the corresponding Morph
modifier channel percentage value.
The submaterial for each channel is stored as a subAnim, and can not be set using MAXScript.
Once a material has been assigned to a channel (channel N), the properties of that material can
be accessed as subAnim N+1 of the MorpherMaterial, and the base object submaterial is
subAnim 101.
As an example, suppose you had an object called MyMorph which has two morph channels
defined, and a MorpherMaterial applied to it. You would need to assign the channel
submaterials in the 3ds max user interface. To access this material and its submaterials you
could use:
mtl=$MyMorph.material -- get the MorpherMaterial
MM_C1_percent=mtl.Channel_0/100. -- get morph target 1 percentage and scale it
correctly
MM_C1_mtl=mtl[1] -- get morph target 1 submaterial
MM_base_percent=mtl.Channel_100/100. -- get morph base object percentage and
scale it correctly
MM_base_mtl=mtl[101] -- get morph base object submaterial

See also
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

MultiMaterial : Material
Constructor:
multimaterial [ numsubs:<integer> ]
multiSubMaterial [ numsubs:<integer> ]

Properties:
<multimaterial>.numsubs
<multisubmaterial>.numsubs
the number of sub-materials in the multimaterial.
<multimaterial>.materialList ArrayParameter default: #(Standard, Standard, ...
Standard, Standard)
<multisubmaterial>.materialList ArrayParameter default: #(Standard, Standard,
... Standard, Standard)
Stores the Material for each sub-material.
<multimaterial>.mapEnabled ArrayParameter default: #(true, true, ... true,
true)
<multisubmaterial>.mapEnabled ArrayParameter default: #(true, true, ... true,
true)
Stores whether the sub-material is enabled.
<multimaterial>.names ArrayParameter default: #(”“, ““, ... ““, ““)
 MultiMaterial : Material 1211

<multisubmaterial>.names ArrayParameter default: #(”“, ““, ... ““, ““)

Stores the sub-material slot name (not the sub-material name).
<Multimaterial>.materialIDList ArrayParameter default: #(0, 1, 2, 3, 4, 5,
6, 7, 8, 9) -- int array; Index
<Multisubmaterial>.materialIDList ArrayParameter default: #(0, 1, 2, 3, 4,
5, 6, 7, 8, 9) -- int array; Index
Stores the sub-material ID’s.
<Multimaterial>.material1 Standardmaterial default: Standard -- alias
for materialList[0]; SubAnim
<Multisubmaterial>.material1 Standardmaterial default: Standard -- alias
for materialList[0]; SubAnim
Stores the material.
Note:
MultiSubMaterial is obsolete and is visible only for backward compatibility.
Each of the arrays contains numsubs elements. The materialList array stores the Material for
each sub-material, the mapEnabled array stores whether that sub-material is enabled, and the
names array stores the sub-material slot name (not the sub-material name).
MultiMaterials have sub-materials arranged in a table, so MAXScript also allows you to access
these sub-materials using the array indexing accessor:
mm = multimaterial numsubs:3
mm[1] = $foo.material
$baz.material = mm[2]

If the numsubs named parameter is not specified, the default numsubs value is 10.
The number of sub-materials can be changed after material creation by changing the numsubs
property value.
The number of sub-materials can also be changed by setting the count property for the
materialList, mapEnabled, or names property to the desired number.
material1 is an alias for materialList[1].

See also
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1212 Chapter 11 | 3ds max Objects

NoMaterial : Material
Assigning this material is equivalent to setting the material to “None” in the Material Editor. Setting
a material to the value undefined is also equivalent to setting the material to “None” in the
Material Editor. For example, if a box had a Top_Bottom material assigned, the following would set
the Top sub-material to “None”:
$box01.material.TopMaterial=noMaterial()

or
$box01.material.TopMaterial=undefined

Constructor:
noMaterial ...

Properties:
There are no additional properties for NoMaterial.

See also
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

RayTraceMaterial : Material
Constructor:
rayTraceMaterial ...

Properties:
<RaytraceMaterial>.Ambient_Color_On Float default: 0.0
If Ambient_Color_On = 0, Ambient_Amount is used, otherwise Ambient is used
<RaytraceMaterial>.Ambient Color default: (color 0 0 0) --
animatable
Sets the degree to which the material absorbs ambient light.
<RaytraceMaterial>.Ambient_Amount Float default: 0.0 -- animatable;
percentage
The amount that the ambient map affects the material expressed as a percentage of full
intensity.
<RaytraceMaterial>.Luminosity_Color_On Float default: 0.0
If Luminosity_Color_On = 0, Self_Illum__Amount is used, otherwise Luminosity is
used
 RayTraceMaterial : Material 1213

<RaytraceMaterial>.Luminosity Color default: (color 0 0 0) --

animatable
The self-illumination color of the material.
<RaytraceMaterial>.Self_Illum_Amount Float default: 0.0 -- animatable;
percentage
The amount that the self-illumination map affects the material expressed as a percentage
of full intensity.
<RaytraceMaterial>.Diffuse Color default: (color 127.5 127.5
127.5) -- animatable
Sets the diffuse color.
<RaytraceMaterial>.Transparency_Color_On Float default: 0.0
If Transparency_Color_On = 0, Transparency_Amount is used, otherwise Transparecy
is used
<RaytraceMaterial>.Transparecy Color default: (color 0 0 0) --
animatable
The filter color of the material.
<RaytraceMaterial>.Transparency_Amount Float default: 0.0 -- animatable;
percentage
The amount that the transparency map affects the material expressed as a percentage of
full intensity.
<RaytraceMaterial>.Reflect_Color_On Float default: 0.0
If Reflect_Color_On = 0, Reflect_Amount is used, otherwise Reflect is used
<RaytraceMaterial>.Reflect Color default: (color 0 0 0) --
animatable
The specular reflection color.
<RaytraceMaterial>.Reflect_amount Float default: 0.0 -- animatable;
percentage
The amount that the reflection map affects the material expressed as a percentage of full
intensity.
<RaytraceMaterial>.Index_of_Refraction Float default: 100.0 -- animatable;
percentage
The index of refraction (IOR) controls how severely the material refracts transmitted light.
At 1.0, the IOR of air, the object behind the transparent object does not distort. At 1.5, the
object behind distorts greatly, like a glass marble. At an IOR slightly less than 1.0, the
object reflects along its edges, like a bubble seen from under water.
<RaytraceMaterial>.Spec__Color Color default: (color 255 255 255) -
- animatable
Sets the color of specular highlights.
<RaytraceMaterial>.Specular_Level Float default: 50.0 -- animatable;
percentage
Sets the intensity of specular highlights. Set the Specular Level to a very high value for very
strong, tight highlights.
1214 Chapter 11 | 3ds max Objects

<RaytraceMaterial>.Glossiness Float default: 40.0 -- animatable;

percentage
Affects the size of the specular highlight. As you increase the value, the highlight gets
smaller and the material appears shinier.
<RaytraceMaterial>.Soften Float default: 0.1 -- animatable
Softens the effect of highlights formed by glancing light.
<RaytraceMaterial>.Extra_Lighting Color default: (color 0 0 0) --
animatable
Adds light to the surface of objects with the Raytrace material.
<RaytraceMaterial>.translucency Color default: (color 0 0 0) --
animatable
Creates a translucent effect. The Translucency color is a non-directional diffuse reflection.
<RaytraceMaterial>.Fluorescence Color default: (color 0 0 0) --
animatable
Creates an effect similar to black light on a black light poster. The light from a black light is
largely ultraviolet, outside the visible spectrum. Under black light, fluorescent paints flare
or glow. The fluorescence in Raytrace material takes whatever light it sees in the scene,
applies the Bias to it, and then, regardless of the color of the lights in the scene,
illuminates the fluorescent material as if it were lit by white light.
<RaytraceMaterial>.Fluorescence_Bias Float default: 70.0 -- animatable;
percentage
At 0.5, The Bias makes Fluorescence behave just like diffuse coloring. Bias values higher
than 0.5 increase the fluorescent effect, making the object brighter than other objects in
the scene. Bias values lower than 0.5 make the object dimmer than other objects in the
scene.
<RaytraceMaterial>.Wire_Size Float default: 100.0 -- animatable;
percentage
Sets the size of the wire in wireframe mode.
<RaytraceMaterial>.Color_Density_Enable Boolean default: false -- animatable
Turns on/off the color density controls.
<RaytraceMaterial>.Color_Density_Start Float default: 0.0 -- animatable
The position in the object where the density color begins to appear.
<RaytraceMaterial>.Color_Density_End Float default: 25.0 -- animatable
The position in the object where the density color reaches its full Amount value.
<RaytraceMaterial>.Color_Density_Amount Float default: 1.0 -- animatable
The amount of density color. It can range from 0 to 1.0. Reducing this value reduces the
density color effect.
<RaytraceMaterial>.Color_Density_Color Color default: (color 255 255 255) -
- animatable
Sets a transmission color based on thickness. While filter (Transparency) color tints objects
behind the transparent object, the density color gives the appearance of color within the
object itself, like tinted glass.
 RayTraceMaterial : Material 1215

<RaytraceMaterial>.Fog_Enable Boolean default: false -- animatable

Turn on/off the use of density fog in the raytrace material.
<RaytraceMaterial>.Fog_Start Float default: 0.0 -- animatable
The position in the object where the density fog begins to appear.
<RaytraceMaterial>.Fog_End Float default: 25.0 -- animatable
The position in the object where the density fog reaches its full Amount value.
<RaytraceMaterial>.Fog_Amount Float default: 1.0 -- animatable
Controls the amount of density fog. It can range from 0 to 1.0. Reducing this value reduces
the density fog effect and makes the fog translucent.
<RaytraceMaterial>.Fog_Color Color default: (color 255 255 255) -
- animatable
The color of the density fog.
<RaytraceMaterial>.Reflection_Type Integer default: 0 -- animatable
Set the type of reflection:
Default (Reflections are layered with the diffuse color)
Additive (Refelections are added to the diffuse color)
<RaytraceMaterial>.Reflection_Gain Float default: 0.5 -- animatable
Controls reflection brightness. The lower the gain value, the brighter the reflection. At a
gain of 1.0, no reflection is visible.
<RaytraceMaterial>.Enable_Raytraced_Reflections Boolean default: false
Turns raytracing of reflective objects on or off.
<RaytraceMaterial>.Enable_Raytraced_Refractions Boolean default: true
Turns raytracing of transparent objects on or off.
<RaytraceMaterial>.Reflection_Falloff_Mode Integer default: 0 --
animatable
When on, dims reflections to black at distance specified by
Reflection_Falloff_End_Distance:
Off (Turns off attenuation)
Linear
Inverse Square (Inverse square is the actual attenuation rate for light in the real world.)
Exponential
<RaytraceMaterial>.Reflection_Falloff_End_Distance Float default: 100.0 --
animatable
The distance in world units where the reflected ray is fully attenuated.
1216 Chapter 11 | 3ds max Objects

<RaytraceMaterial>.Refraction_Falloff_Mode Integer default: 0 --

animatable
Sets the falloff mode for refraction in the raytrace material:
Off (Turns off attenuation)
Linear
Inverse Square (Inverse square is the actual attenuation rate for light in the real world.)
Exponential
<RaytraceMaterial>.Refraction_Falloff_End_Distance Float default: 100.0 --
animatable
The distance in world units where the refracted ray is fully attenuated.
<RaytraceMaterial>.Bump_Map_Effect Float default: 1.0 -- animatable
Adjusts the effect of bump maps on raytraced reflections and refractions.
<RaytraceMaterial>.Override_Global_Antialiasing_Settings Boolean default:
false -- animatable
If Override_Global_Antialiasing_Settings = false, Global Antialiasing Settings are used. If
true, the antialiaser is determined by Adaptive_Antialiasing_On.
<RaytraceMaterial>.Adaptive_Antialiasing_On Boolean default: false -
- animatable
If Adaptive_Antialiasing_On = true, the Multiresolution Adaptive Antialiaser is used;
otherwise the Fast Adaptive Antialiaser is used. This property only has an effect if
Override_Global_Antialiasing_Settings = true.
The following properties are associated with the Options dialog
<RaytraceMaterial>.Options___Raytracer_Enable Boolean default: true -
- animatable
Turns the raytracer on or off.
<RaytraceMaterial>.Options___Antialiasing_Enable Boolean default: true -
- animatable
Turns antialiasing on or off.
<RaytraceMaterial>.Options___Self_Reflect_Refract Boolean default: true -
- animatable
Turns self reflection/refraction on or off.
<RaytraceMaterial>.Options___Raytrace_Atmospherics Boolean default: true -
- animatable
Turns the raytracing of atmospheric effects on or off. Atmospheric effects include
combustion, fog, volume light, and so on.
<RaytraceMaterial>.Options___Reflect_Refract_Material_ID_s Boolean default:
true -- animatable
When on, the material reflects effects assigned to material IDs in the renderer’s G-Buffer.
<RaytraceMaterial>.Options___Raytrace_Objects_in_Glass Boolean default:
true -- animatable
Turns the raytracing of objects inside raytraced objects on or off.
 RayTraceMaterial : Material 1217

<RaytraceMaterial>.Options___Raytrace_Atmospherics_in_Glass Boolean default:

true -- animatable
Turns the raytracing of atmospherics inside raytraced objects on or off.
<RaytraceMaterial>.Options___Color_Density___Fog_Enable Boolean default:
true -- animatable
Turns the color density and fog features on or off.
The following properties are associated with the Antialiaser configuration dialogs.
<RaytraceMaterial>.Local_Threshold Float default:
0.1 -- animatable
The sensitivity of the adaption algorithm. This value can range from 0 to 1, where 0 always
casts the maximum number of rays and 1 always casts only the minimum number of rays.
<RaytraceMaterial>.Local_Min__Rays Integer default:
4 -- animatable
The minimum number of rays that the algorithm casts.
<RaytraceMaterial>.Local_Max__Rays Integer default:
32 -- animatable
The maximum number of rays the algorithm casts.
<RaytraceMaterial>.Local_Blur_Offset Float default:
0.0 -- animatable
The sharpness or blurriness of reflections or refractions without regard to distance. This
value is specified in pixels.
<RaytraceMaterial>.Local_Blur_Aspect Float default:
1.0 -- animatable
Changes the shape of the blur by changing the aspect ratio.
<RaytraceMaterial>.Local_Defocus Float default:
0.0 -- animatable
Blurs based on distance. Objects near the surface are not blurred, but objects farther away
are blurred. The rays cast are spread as they leave the surface of the raytrace map object.
<RaytraceMaterial>.Local_Defocus_Aspect Float default:
1.0 -- animatable
Changes the shape of the defocusing by changing the aspect ratio.
The following properties are associated with the Maps rollout.
<RaytraceMaterial>.ambientMap TextureMap default:
undefined
The map assigned to the ambient map channel.
<RaytraceMaterial>.ambientMapAmount Float default:
100.0
The relative strength of the ambient map channel.
<RaytraceMaterial>.ambientMapEnable Boolean default:
false
Turn on/off use of the ambient map channel.
<RaytraceMaterial>.bumpMap TextureMap default:
undefined
The map assigned to the bump map channel.
1218 Chapter 11 | 3ds max Objects

<RaytraceMaterial>.bumpMapAmount Float default:

100.0
The relative strength of the bump map channel.
<RaytraceMaterial>.bumpMapEnable Boolean default:
false
Turn on/off use of the bump map channel.
<RaytraceMaterial>.diffuseMap TextureMap default:
undefined
The map assigned to the diffuse map channel.
<RaytraceMaterial>.diffuseMapAmount Float default:
100.0
The relative strength of the diffuse map channel.
<RaytraceMaterial>.diffuseMapEnable Boolean default:
false
Turn on/off use of the diffuse map channel.
<RaytraceMaterial>.displacementMap TextureMap default:
undefined
The map assigned to the displacement map channel.
<RaytraceMaterial>.displacementMapAmount Float default:
100.0
The relative strength of the displacement map channel.
<RaytraceMaterial>.displacementMapEnable Boolean default:
false
Turn on/off use of the displacement map channel.
<RaytraceMaterial>.reflectionMap TextureMap default:
undefined
The map assigned to the reflection map channel.
<RaytraceMaterial>.reflectionMapAmount Float default:
100.0
The relative strength of the reflection map channel.
<RaytraceMaterial>.reflectionMapEnable Boolean default:
false
Turn on/off use of the reflection map channel.
<RaytraceMaterial>.refractionMap TextureMap default:
undefined
The map assigned to the refraction map channel.
<RaytraceMaterial>.refractionMapAmount Float default:
100.0
The relative strength of the refraction map channel.
<RaytraceMaterial>.refractionMapEnable Boolean default:
false
Turn on/off use of the refraction map channel.
 RayTraceMaterial : Material 1219

<RaytraceMaterial>.glossinessMap TextureMap default:

undefined
The map assigned to the glossiness map channel.
<RaytraceMaterial>.
glossinessMapAmount Float default: 100.0
The relative strength of the glossiness map channel.
<RaytraceMaterial>.
glossinessMapEnable Boolean default: false
Turn on/off use of the glossiness map channel.
<RaytraceMaterial>.specularLevelMap TextureMap defau
lt: undefined
The map assigned to the specularLevel map channel.
<RaytraceMaterial>.specularLevelMapAmount Float defau
lt: 100.0
The relative strength of the specularLevel map channel.
<RaytraceMaterial>.specularLevelMapEnable Boolean defau
lt: false
Turn on/off use of the specularLevel map channel.
<RaytraceMaterial>.luminosityMap TextureMap default:
undefined
The map assigned to the luminosity map channel.
<RaytraceMaterial>.luminosityMapAmount Float default:
100.0
The relative strength of the luminosity map channel.
<RaytraceMaterial>.luminosityMapEnable Boolean default:
false
Turn on/off use of the luminosity map channel.
<RaytraceMaterial>.transparencyMap TextureMap defaul
t: undefined
The map assigned to the transparency map channel.
<RaytraceMaterial>.transparencyMapAmount Float defaul
t: 100.0
The relative strength of the transparency map channel.
<RaytraceMaterial>.transparencyMapEnable Boolean defaul
t: false
Turn on/off use of the transparency map channel.
<RaytraceMaterial>.environmentMap TextureMap default
: undefined
The map assigned to the environment map channel.
<RaytraceMaterial>.environmentMapAmount Float default
: 100.0
The relative strength of the environment map channel.
1220 Chapter 11 | 3ds max Objects

<RaytraceMaterial>.environmentMapEnable Boolean default

: false
Turn on/off use of the environment map channel.
<RaytraceMaterial>.transEnvMap TextureMap default:
undefined
The map assigned to the transEnv map channel.
<RaytraceMaterial>.transEnvMapAmount Float default:
100.0
The relative strength of the transEnv map channel.
<RaytraceMaterial>.transEnvMapEnable Boolean default:
false
Turn on/off use of the transEnv map channel.
<RaytraceMaterial>.iorMap TextureMap default:
undefined
The map assigned to the ior map channel.
<RaytraceMaterial>.iorMapAmount Float default: 100.0
The relative strength of the ior map channel.
<RaytraceMaterial>.iorMapEnable Boolean default: false
Turn on/off use of the ior map channel.
<RaytraceMaterial>.translucencyMap TextureMap defaul
t: undefined
The map assigned to the translucency map channel.
<RaytraceMaterial>.translucencyMapAmount Float defaul
t: 100.0
The relative strength of the translucency map channel.
<RaytraceMaterial>.translucencyMapEnable Boolean defaul
t: false
Turn on/off use of the translucency map channel.
<RaytraceMaterial>.extraLightingMap TextureMap defau
lt: undefined
The map assigned to the extraLighting map channel.
<RaytraceMaterial>.extraLightingMapAmount Float defau
lt: 100.0
The relative strength of the extraLighting map channel.
<RaytraceMaterial>.extraLightingMapEnable Boolean defau
lt: false
Turn on/off use of the extraLighting map channel.
<RaytraceMaterial>.flourescenceMap TextureMap defaul
t: undefined
The map assigned to the flourescence map channel.
<RaytraceMaterial>.flourescenceMapAmount Float defaul
t: 100.0
The relative strength of the flourescence map channel.
 RayTraceMaterial : Material 1221

<RaytraceMaterial>.flourescenceMapEnable Boolean defaul

t: false
Turn on/off use of the flourescence map channel.
<RaytraceMaterial>.colorDensityMap TextureMap defaul
t: undefined
The map assigned to the colorDensity map channel.
<RaytraceMaterial>.colorDensityMapAmount Float defaul
t: 100.0
The relative strength of the colorDensity map channel.
<RaytraceMaterial>.colorDensityMapEnable Boolean defaul
t: false
Turn on/off use of the colorDensity map channel.
<RaytraceMaterial>.fogColorMap TextureMap default:
undefined
The map assigned to the fogColor map channel.
<RaytraceMaterial>.fogColorMapAmount Float default:
100.0
The relative strength of the fogColor map channel.
<RaytraceMaterial>.fogColorMapEnable Boolean default:
false
Turn on/off use of the fogColor map channel.
<RaytraceMaterial>.diffusionMap TextureMap default:
undefined
The map assigned to the diffusion map channel.
<RaytraceMaterial>.diffusionMapAmount Float default:
100.0
The relative strength of the diffusion map channel.
<RaytraceMaterial>.diffusionMapEnable Boolean default:
false
Turn on/off use of the diffusion map channel.
<RaytraceMaterial>.specularMap TextureMap default:
undefined
The map assigned to the specular color map channel.
<RaytraceMaterial>.specularMapAmount Float default:
100.0
The relative strength of the specular color map channel.
<RaytraceMaterial>.specularMapEnable Boolean default:
false
Turn on/off use of the specular color map channel.
1222 Chapter 11 | 3ds max Objects

The following properties are associated with the Dynamics Properties rollout. These properties are
not present in 3D Studio VIZ.
<RaytraceMaterial>.Bounce_Coefficient Float default:
1.0 -- animatable
Sets how far an object bounces after hitting a surface. The higher the value, the greater the
bounce. A value of 1 represents a “perfectly elastic collision,” or a bounce in which no
kinetic energy is lost.
<RaytraceMaterial>.Static_Friction Float default:
0.0 -- animatable
Sets how difficult it is for the object to start moving along a surface. The higher this value,
the more difficult.
<RaytraceMaterial>.Sliding_Friction Float default:
0.0 -- animatable
Sets how difficult it is for the object to keep moving over a surface. The higher this value,
the more difficult for the object to keep moving.
The following properties do not correspond to any user-interface items, but appear to be used by the
raytracer. These properties appear to be similar to the corresponding properties for the Raytrace
TextureMap (p. 1271).
<RaytraceMaterial>.Attenuation_Start Float default: 0.0
The distance in world units where attenuation begins.
<RaytraceMaterial>.Attenuation_Exponent Float default: 2.0
The distance in world units where the ray is fully attenuated.
<RaytraceMaterial>.Attenuation_Color_Mode Integer default: 0
This affects the behavior of light rays as they attenuate out:
Background (As the ray attenuates out, returns the background (either the scene’s
background or the background specified locally in the Raytracer Parameters rollout) rather
than the actual color of what the reflected/refracted ray sees.)
Use Attenuation_Color
<RaytraceMaterial>.Attenuation_Color Color default:
(color 0 0 0)
The color used for attenuation.
<RaytraceMaterial>.Attenuation_Near Float default: 1.0
The strength of the reflected/refracted ray at the start range distance. This is a normalized
percentage that can range from 0.0 to 1.0.
<RaytraceMaterial>.Attenuation_Control_1 Float default: 0.6666
Controls the shape of the curve near the curve start.
<RaytraceMaterial>.Attenuation_Control_2 Float default: 0.3333
Controls the shape of the curve near the curve end.
<RaytraceMaterial>.Attenuation_Far Float default: 0.0
Sets the strength of the reflected/refracted ray at the end range distance. This is a
normalized percentage that can range from 0.0 to 1.0.
 RayTraceMaterial : Material 1223

<RaytraceMaterial>.Blur_Map Boolean default:

false
When on, the software uses a map to apply the Blur Offset value. That is, where the map is
white, blur offset is fully applied, and where it is black, it is ignored. For example, if the
map is a Checker map, blur offset is applied only in every other square. Values between
black and white cause less blur.
<RaytraceMaterial>.Defocus_Map Boolean default:
false
When on, uses a map to apply the Defocus value. That is, where the map is white, Defocus
is fully applied, and where it is black, it is ignored. For example, if the map is a Checker
map, Defocus is applied only in every other square. Values between black and white cause
less defocusing.
<RaytraceMaterial>.Enable_Reflection_Falloff Boolean default:
false
Turns on/off falloff of reflection.
<RaytraceMaterial>.Reflection_Falloff_Distance Float default: 0.0
The distance until the reflections are fully attenuated.
<RaytraceMaterial>.Enable_Refraction_Falloff Boolean default: false
Turns on/off falloff of refraction.
<RaytraceMaterial>.Refraction_Falloff_Distance Float default: 0.0
The distance until the refractions are fully attenuated.
Note:
The following user-interface properties not exposed to MAXScript in 3ds max 4: Shading, 2-Sided,
Wire, Face Map, and SuperSample

See also
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1224 Chapter 11 | 3ds max Objects

StandardMaterial : Material
Constructor:
standardMaterial ...
standard ...

Properties:
The properties of a standard material vary based on the shader type. The following properties are
applicable to all shader types:
<Standard>.shaderType Integer default: 1 -- alias:
Shader_Type
Sets the shader type:
Anisotropic
Blinn
Metal
Multi-Layer
Oren-Nayar-Blinn
Phong
Strauss
<Standard>.shaderByName String default: “Blinn” -- alias:
Shader_Name
Sets the type of shader with a string, rather than a number. Enter “anisotropic”,
“blinn”, “metal”, “multi-layer”, “oren-nayar-blinn”, “phong”, or “strauss”.
Note: The .shaderType and .shaderByName are linked and will automatically change
each others values.
<Standard>.wire Boolean default: false
When on, the material will be rendered in wireframe mode.
<Standard>.twoSided Boolean default: false -- alias:
Two_sided
When on, the material will be applied to both sides of the selected faces.
<Standard>.faceMap Boolean default: false -- alias:
Face_Map
Applies the material to the faces of the geometry. If the material is a mapped material, it
requires no mapping coordinates. The map is automatically applied to each facet of the
object.
<Standard>.faceted Boolean default: false
Renders each face of a surface as if it were flat.
<Standard>.adTextureLock Boolean default: false -- alias:
Ambient_Diffuse_Texture_Lock
When on, ambient and diffuse texture maps will be locked.
 StandardMaterial : Material 1225

<Standard>.adLock Boolean default: false -- alias:

Ambient_Diffuse_Lock
When on, ambient and diffuse colors will be locked.
<Standard>.opacityType Integer default: 0 -- alias:
Opacity_Type
Sets the type of opacity:
Filter
Subtractive
Additive
<Standard>.opacity Float default: 100.0 -- animatable,
percentage
Sets the opacity/transparency of the material as a percentage.
<Standard>.filterColor Color default: (color 127.5 127.5
127.5) -- animatable, alias: Filter_Color
The color transmitted through transparent or semi-transparent materials such as glass.
<Standard>.opacityFallOffType Integer default: 0, -- alias:
Falloff_Type
Sets the fallof type:
In (Increases transparency towards the inside of the object, as in a glass bottle. )
Out (Increases transparency towards the outside of the object, as in a cloud of smoke.)
<Standard>.opacityFallOff Float default: 0.0 -- animatable,
percentage, alias: Falloff
Specifies the amount of transparency at the outside or inside extreme.
<Standard>.ior Float default: 1.5 -- animatable,
alias: Index_of_Refraction
Sets the index of refraction (IOR) used by refraction maps and raytracing. The IOR controls
how severely the material refracts transmitted light. Left at 1.0, the IOR of air, the object
behind the transparent object does not distort. At 1.5 the object behind distorts greatly,
like a glass marble. At an IOR slightly less than 1.0, the object reflects along its edges, like a
bubble seen from under water.
<Standard>.wireSize Float default: 1.0 -- animatable,
alias: Wire_Size
Sets the size of the wire in wireframe mode.
<Standard>.wireUnits Integer default: 0 -- alias:
Wire_Units
Sets the unites to use with the .wiresize value:
Pixels
Units
<Standard>.applyReflectionDimming Boolean default: false -- alias:
Apply_Reflection_Dimming
Turn on to use reflection dimming. When off, the reflection-mapped material is not
affected by the presence or absence of direct light.
1226 Chapter 11 | 3ds max Objects

<Standard>.dimLevel Float default: 0.0 -- animatable,

alias: Dim_Level
The amount of dimming that takes place in shadow. At 0.0, the reflection map is
completely dark in shadow. At 0.5, the reflection map is half dimmed. At 1.0, the
reflection map is not dimmed and the material appears as if Apply were turned off.
<Standard>.reflectionLevel Float default: 3.0 -- animatable,
alias: Reflection_Level
Affects the intensity of the reflection that is not in shadow. The Reflection Level value
multiplies the illumination level of the lit area of the reflection, to compensate for
dimming.
<Standard>.sampler Integer default: 3 -- alias:
Pixel_Sampler
Sets the sampler type:
Adaptive Halton (Spaces samples along both X and Y axes according to a scattered, “quasi
random” pattern. Depending on Quality, the number of samples can range from 4 to 40. )
Adaptive Uniform (Spaces samples regularly, from a minimum quality of 4 samples to a
maximum of 36. The pattern is not square, but skewed slightly to improve accuracy in the
vertical and horizontal axes. )
Hammersley (Spaces samples regularly along the X axis, but along the Y axis it spaces them
according to a scattered, “quasi random” pattern. Depending on Quality, the number of
samples can range from 4 to 40.)
Max 2.5 Star (The sample at the center of the pixel is averaged with 4 samples
surrounding it. The pattern is like the fives on dice.)
<Standard>.samplerByName String default: “Max 2.5 Star” --
alias: Sampler_Name
Sets the sampler type by name. Enter “Adaptive Halton”, “Adaptive Uniform”,
“Hammersley”, or “Max 2.5 Star”.
<Standard>.samplerEnable Boolean default: false -- animatable,
alias: Sampler_Enable
When on, applies supersampling to the material.
<standard>.subSampleTextureOn Boolean default: true -- alias:
SubSample_Textures
When on, the maps applied to the material are supersampled as well. When off, the
supersampler uses pixel averages for maps.
<Standard>.samplerQuality Float default: 0.5 -- animatable,
alias: Sampler_Enable
Adjusts the quality of supersampling by controlling the number of samples used for each
pixel.
<Standard>.samplerAdaptOn Boolean default: true -- alias:
Adaptive_On
When on, these methods take fewer samples than the Quality specifies unless samples
show a change in color greater than the Threshold value. In that case, they take all the
 StandardMaterial : Material 1227

samples specified by the Quality. Turning on Adaptive On can reduce the amount of time
required to supersample.
<Standard>.samplerAdaptThreshold Float default: 0.1 -- alias:
Adaptive_Threshold
Controls the Adaptive methods. A change in color greater than the Threshold value causes
the adaptive methods to take the full number of samples specified by the Quality. If the
color does not change as much, the adaptive method takes fewer samples and does not
require as much processing time.
<Standard>.samplerAdvancedOptions Boolean default: true -- alias:
Advanced_Options
The samplerAdvancedOptions property is defined as a property, but is not used by the
Standard material.
<standard>.UserParam0 Float default: 0.0 -- alias:
Optional_Param0
<standard>.UserParam1 Float default: 0.0 -- alias:
Optional_Param1
The UserParam0 and UserParam1 properties are defined as properties, but are not used by
the Standard material.
<Standard>.maps ArrayParameter default: #(undefined,
undefined, ... , undefined, undefined)
<Standard>.mapEnables ArrayParameter default: #(false, false, ... ,
false, false) -- alias: Map_Enables
<Standard>.mapAmounts ArrayParameter default: #(100.0, 100.0, ... ,
100.0, 100.0) -- animatable, alias: Map_Amounts
The three map arrays each have 24 elements and store data related to the material’s maps.
The maps array stores the textureMap for each channel, the mapEnables array stores
whether the that map channel is enabled, and the mapAmounts array stores the amount
value for each channel. The meaning of each map channel depends on the shaderType
value. Table Map Channels for Standard Material Shaders (p. 1232) shows the meaning of
each map channel for each shader. For example, for the Blinn shader type element 5 of the
map arrays correspond to the Glossiness map channel. The names in this table also reflect
property aliases that have been defined for easier access to the map channels. Again for the
Blinn shader type, array element 4, the property aliases for the 3 map arrays are:
GlossinessMap (maps[5]), GlossinessMapEnable (mapEnables[5]), and
GlossinessMapAmount (mapAmounts[5]). A textureMap needs to be assigned to a maps
array element (or alias) before the corresponding mapAmounts property (or alias) can be
animated.
The following properties are associated with the Dynamics Properties rollout. These properties are
not present in 3D Studio VIZ.
<Standard>.bounce Float default: 1.0 -- animatable,
alias: Bounce_Coefficient
Sets how far an object bounces after hitting a surface. The higher the value, the greater the
bounce. A value of 1 represents a “perfectly elastic collision,” or a bounce in which no
kinetic energy is lost.
1228 Chapter 11 | 3ds max Objects

<Standard>.staticFriction Float default: 0.0 -- animatable,

alias: Static_Friction
Sets how difficult it is for the object to start moving along a surface. The higher this value,
the more difficult.
<Standard>.slidingFriction Float default: 0.0 -- animatable,
alias: Sliding_Friction
Sets how difficult it is for the object to keep moving over a surface. The higher this value,
the more difficult for the object to keep moving.
Shader Types: Phong; Metal; Blinn; Oren-Nayar-Blinn; Anisotropic
Unless otherwise noted, the following additional properties are applicable to the above shader types:
<Standard>.ambient Color default: (color 25.5 25.5 25.5) --
animatable, alias: Ambient_Color
Controls the ambient color. The ambient color is the color in direct light.
<Standard>.diffuse Color default: (color 127.5 127.5 127.5) --
animatable, alias: Diffuse_Color
Controls the diffuse color. The diffuse color is the color in direct light.
<Standard>.specular Color default: (color 229.5 229.5 229.5) --
animatable, alias: Specular_Color
Controls the specular color. The specular color is the color of the highlight on a shiny
object.
<Standard>.dsLock Boolean default: false -- alias:
Diffuse_Specular_Lock
When on, the diffuse and specular colors are linked together.
<Standard>.useSelfIllumColor Boolean default: false -- alias:
Use_Self_Illumination
When on, the material uses a special self-illumination color (.selfIllumColor). When
off, the material uses the diffuse color for self-illumination.
<Standard>.selfIllumAmount Float default: 0.0 -- animatable, percentage,
alias: Self_Illumination
Sets the amount of self-illumination.
<Standard>.selfIllumColor Color default: (color 0 0 0) -- animatable,
alias: Self_Illum_Color
Sets a separate color to use for self-illumination.
<Standard>.specularLevel Float default: 5.0 -- animatable, percentage,
alias: Specular_Level
Affects the intensity of the specular highlight. As you increase the value, the highlight
grows brighter.
<Standard>.glossiness Float default: 25.0 -- animatable, percentage
Affects the size of the specular highlight. As you increase the value, the highlight gets
smaller and the material appears shinier.
 StandardMaterial : Material 1229

<Standard>.soften Float default: 0.1 -- animatable, alias:

Soften_Level
Softens the effect of specular highlights, especially those formed by glancing light. When
Specular Level is high and Glossiness is low, you can get harsh backlights on surfaces.
Increase the value of Soften to mitigate this effect. At 0 there is no softening. At 1.0, the
maximum amount of softening is applied.
Note: Soften is not applicable to the Anisotropic shader
The following additional properties are applicable to the Oren-Nayar-Blinn shader:
<Standard>.diffuseLevel Float default: 100.0 -- animatable, percentage,
alias: Diffuse_Level
Controls the brightness of the material’s diffuse component. Increasing this value
increases diffuse brightness, and decreasing it reduces diffuse brightness without affecting
the specular highlight.
<Standard>.diffuseRoughness Float default: 50.0 -- animatable, percentage,
alias: Diff_Roughness
Controls how quickly the diffuse component blends into the ambient component. As you
increase roughness, the matte appearance of the material increases. It also grows darker
and appears more flat.
The following additional properties are applicable to the Anisotropic shader:
<Standard>.diffuseLevel Float default: 100.0 -- animatable, percentage,
alias: Diffuse_Level
Controls the brightness of the material’s diffuse component. Increasing this value
increases diffuse brightness, and decreasing it reduces diffuse brightness without affecting
the specular highlight.
<Standard>.anisotropy Float default: 50.0 -- animatable, percentage
Controls the anisotropy, or shape, of the highlight. At 0, the highlight is round. At 100,
the highlight is extremely narrow.
<Standard>.orientation Float default: 0.0 -- animatable, percentage
Changes the orientation of the highlight.
<Standard>.unused Integer default: 1
the unused property is defined but not used by the shader
Shader Type: Multi-Layer
<Standard>.ambient Color default: (color 25.5 25.5 25.5) --
animatable, alias: Ambient_Color
Controls the ambient color. The ambient color is the color not in direct light.
<Standard>.diffuse Color default: (color 127.5 127.5 127.5) --
animatable, alias: Diffuse_Color
Controls the diffuse color. The diffuse color is the color in direct light.
<Standard>.useSelfIllumColor Boolean default: false -- alias:
Use_Self_Illumination
When on, the material uses a special self-illumination color (.selfIllumColor). When
off, the material uses the diffuse color for self-illumination.
1230 Chapter 11 | 3ds max Objects

<Standard>.selfIllumAmount Float default: 0.0 -- animatable, percentage,

alias: Self_Illumination
Sets the amount of self-illumination. As you increase self-illumination, the self-
illumination color takes over from the ambient color. At a setting of 100, the material
shows no shaded areas, although it can show specular highlights.
<Standard>.selfIllumColor Color default: (color 0 0 0) -- animatable,
alias: Self_Illum_Color
Sets an alternate color to use for self-illumination.
<Standard>.diffuseLevel Float default: 100.0 -- animatable, percentage,
alias: Diffuse_Level
Controls the brightness of the material’s diffuse component. Increasing this value
increases diffuse brightness, and decreasing it reduces diffuse brightness without affecting
the specular highlight.
<Standard>.diffuseRoughness Float default: 0.0 -- animatable, percentage,
alias: Diff_Roughness
Controls how quickly the diffuse component blends into the ambient component. As you
increase roughness, the matte appearance of the material increases. It also grows darker
and appears more flat.
<Standard>.specular Color default: (color 229.5 229.5 229.5) --
animatable, alias: Color_1
Controls the specular color of the first color’s highlight. The specular color is the color of
the highlight on a shiny surface.
<Standard>.specularLevel Float default: 5.0 -- animatable, percentage,
alias: Level_1
Affects the intensity of the first color’s specular highlight. As you increase the value, the
highlight grows brighter.
<Standard>.glossiness Float default: 25.0 -- animatable, percentage,
alias: Glossiness_1
Affects the size of the first color’s specular highlight. As you increase the value, the
highlight gets smaller and the material appears shinier.
<Standard>.anisotropy Float default: 0.0 -- animatable, alias:
Anisotropy_1
Controls the anisotropy, or shape, of the first color’s highlight. At 0, the highlight is
round. At 100, the highlight is extremely narrow.
<Standard>.orientation Float default: 0.0 -- animatable, percentage
Changes the orientation of the first color’s highlight.
<Standard>.specular2 Color default: (color 229.5 229.5 229.5) --
animatable, alias: Color_2
Affects the intensity of the second color’s specular highlight. As you increase the value, the
highlight grows brighter.
<Standard>.specularLevel2 Float default: 0.0 -- animatable, percentage,
alias: Level_2
Affects the intensity of the second color’s specular highlight. As you increase the value, the
highlight grows brighter.
 StandardMaterial : Material 1231

<Standard>.glossiness2 Float default: 25.0 -- animatable, percentage,

alias: Glossiness_2
Affects the size of the second color’s specular highlight. As you increase the value, the
highlight gets smaller and the material appears shinier.
<Standard>.anisotropy2 Float default: 0.0 -- animatable, alias:
Anisotropy_2
Controls the anisotropy, or shape, of the second color’s highlight. At 0, the highlight is
round. At 100, the highlight is extremely narrow.
<Standard>.orientation2 Float default: 0.0 -- animatable, percentage
Changes the orientation of the second color’s highlight.
Shader Type: Strauss
<Standard>.diffuse Color default: (color 127.5 127.5 127.5) --
animatable, alias: Diffuse_Color
Controls the color of the material. This corresponds to the diffuse color you specify for
other kinds of shaders. With the Strauss shader, you control only this color. The shader
calculates the ambient and specular color components.
<Standard>.glossiness Float default: 25.0 -- animatable, percentage
Affects the size and intensity of the specular highlight. As you increase the value, the
highlight gets smaller and the material appears shinier.
<Standard>.metalness Float default: 0.0 -- animatable, percentage
Changes the metallic appearance of a material. Increasing the Metalness value increases
the metallic appearance, with glancing as well as primary highlights. Because a metallic
appearance principally depends on highlights, the Metalness value has little effect unless
you also increase the Glossiness value.

See also
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1232 Chapter 11 | 3ds max Objects

Map Channels for Standard Material Shaders

Aniso- Oren-Nayar-
tropic Blinn Metal Multi-Layer Blinn Phong Strauss
1 AmbientMap AmbientMap AmbientMap AmbientMap AmbientMap AmbientMap DiffuseMap
2 DiffuseMap DiffuseMap DiffuseMap DiffuseMap DiffuseMap DiffuseMap GlossinessMap
3 SpecularMap SpecularMap SpecularMap DiffuseLevelMap SpecularMap SpecularMap MetalnessMap

4 DiffuseLevel SpecularLevel SpecularLevel Diffuse GlossinessMap SpecularLevel OpacityMap

Map Map Map RoughnessMap Map
5 SpecularLevel GlossinessMap GlossinessMap SpecularMap SpecularLevel GlossinessMap FilterMap
Map Map
6 Glossiness Map SelfIllumMap SelfIllumMap SpecularLevel SelfIllumMap SelfIllumMap BumpMap
Map
7 Anisotropy OpacityMap OpacityMap GlossinessMap OpacityMap OpacityMap ReflectionMap
Map
8 OrientationMap FilterMap FilterMap AnisotropyMap FilterMap FilterMap RefractionMap

9 SelfIllumMap BumpMap BumpMap OrientationMap DiffuseLevelMap BumpMap Displacement

Map
10 OpacityMap ReflectionMap ReflectionMap specularMap2 Diffuse ReflectionMap
RoughnessMap
11 FilterMap RefractionMap RefractionMap SpecularLevel BumpMap RefractionMap
Map2
12 BumpMap Displacement Displacement GlossinessMap2 ReflectionMap Displacement
Map Map Map
13 ReflectionMap AnisotropyMap2 RefractionMap

14 RefractionMap Orientation Displacement

Map2 Map
15 Displacement SelfIllumMap
Map
16 OpacityMap
17 FilterMap
18 BumpMap
19 ReflectionMap
20 RefractionMap
21 Displacement
Map
 Shellac : Material 1233

Shellac : Material
Constructor:
Shellac ...

Properties:
<Shellac>.shellacMtl1 Material default: Standard -- alias: Base_Material
The base sub-material.
<Shellac>.shellacMtl2 Material default: Standard -- alias:
Shellac_Material
The shellac material.
<Shellac>.shellacColorBlend Float default: 0.0 -- animatable,
percentage, alias: Shellac_Color_Blend
Controls the amount of color mixing. At 0.0, the shellac material has no effect. Increasing
the Shellac Color Blend value increases the amount of shellac material color blended into
the base material color. There is no upper limit on this parameter. Large values “overload”
the shellac material colors.

See also
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TopBottom : Material
Constructor:
topBottom ...
topBottomMat ...

Properties:
<TopBottom>.topMaterial Material default: Standard -- alias:
Top______Standard
The top material.
<TopBottom>.bottomMaterial Material default: Standard -- alias:
Bottom______Standard
The bottom material.
<TopBottom>.map1Enabled Boolean default: true -- alias: Map_1_Enable
Turns on/off the use of the top material in the topbottom material.
<TopBottom>.map2Enabled Boolean default: true -- alias: Map_2_Enable
Turns on/off the use of the bottom material in the topbottom material.
1234 Chapter 11 | 3ds max Objects

<TopBottom>.blend Float default: 0.0 -- animatable

Blends the edge between the top and bottom sub-materials. This is a percentage that can
range from 0 to 100. At 0, there is a sharp line between the top and bottom sub-materials.
At 100, the top and bottom sub-materials tint each other.
<TopBottom>.position Float default: 50.0 -- animatable
Determines where the division between the two materials lies on an object. This is a
percentage that can range from 0 to 100. 0 is at the bottom of the object, and displays only
the top material. 100 is at the top of the object, and displays only the bottom material.
<TopBottom>.coordinates Integer default: 0
Choose how the software determines the boundary between top and bottom:
World (Faces point up or down according to the scene’s world coordinates. When you
rotate the object, the boundary between top and bottom faces remains in place.)
Local (Faces point up or down according to the object’s local coordinates. When you rotate
the object, the material rotates with it.)

See also
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TextureMap : Material
The TextureMap class represents the 2D and 3D texture maps which you can assign to materials or
certain object properties in 3ds max. You can create texture maps like bitmap, dent, and swirl, access
various properties on them, and assign these texture maps to materials and to certain 3ds max object
properties.
The classes derived directly from the TextureMap class are described in the TextureMap Types
(p. 1240) topic.
The properties, operators, and methods that are common to all classes derived directly from the
TextureMap class are described in the TextureMap Common Properties, Operators, and Methods (p. 1235)
topic.
TextureMaps also share a set of classes for properties that are used in several different TextureMap
classes. These shared classes are described in the TextureMap Shared Classes (p. 1236) topic.
The TextureMap class is derived from the Material class, and inherits the properties and methods
defined for that class. These properties and methods are described in the Material Common Properties,
Operators, and Methods (p. 1203) topic.
 TextureMap Common Properties, Operators, and Methods 1235

TextureMap Common Properties, Operators, and Methods

Properties:
<TextureMap>.name
All the TextureMap subclasses can access the name property and specify it as a constructor
parameter.
Methods:
assignNewName <TextureMap>
Modifies the name of the specified texture to make it unique. The name is of the form
“Map #1” where the number is incremented as required to make ensure it’s unique.
renderMap <TextureMap> [ into:<bitmap> ] \
[ size:<point2> ] \
[ filename:<string> ] \
[ scale:<float> ] \
[ filter:<boolean> ] \
[ display:<boolean> ]
Provides access the Render Map function available in the Material Editor. The function
returns a Bitmap value containing a rendering of the given texture map. If you specify the
optional into: argument, the function renders the map into the supplied bitmap, taking
size and other attributes from the existing bitmap. If you don’t, a new bitmap value is
created using the size: and fileName: arguments in its creation. Default size value is
[200,200].
The scale: argument is a scale factor applied to 3D TextureMaps. This is the scale of the
surface in 3d space that is mapped to UV and controls how much of the texture appears in
the bitmap representation. Default scale value is 1.
If the filter: argument is true, the bitmap is filtered. It is quite a bit slower to rescale
bitmaps with filtering on. Defaults filter value is false/off.
If the display: argument is true, the resulting bitmap is displayed using the virtual
frame buffer; otherwise it is not. Default display value is false/off.
Example:
rm = renderMap $foo.material.diffuseMap size:[640,480] \
fileName:”foodif.bmp”
save rm
close rm

The above will render a map to a bitmap and save it as a .bmp file.
1236 Chapter 11 | 3ds max Objects

Associated Methods:
showTextureMap <material> <TextureMap> <boolean>
This method provides control over the visibility of textures in the shaded viewport. You
specify the material containing the texture map, the texture map in that material to be
controlled, and a boolean to turn the display on or off. For example:
showTextureMap $foo.material $foo.material.diffuseMap on

tm = checker()
mat = standardMaterial diffuseMap:tm
mm = multimaterial()
mm[1] = mat
$box01.material = mm
showTextureMap mm[1] tm on

Note that for multimaterials, you need to specify the appropriate sub-material (using []
indexing, for example).

See also
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TextureMap Shared Classes

The following set of material classes are shared by multiple texture maps. These shared classes
correspond to the Coordinates, Noise, and Output rollouts for texture maps in Material Editor. These
classes are not constructable in MAXScript, rather they are automatically constructed by the texture
map.
These shared material classes are the 2D and 3D texture map coordinate properties, and the Output
properties:
UVGenClass (p. 1237)
StandardXYZGen (p. 1238)
TexOutputClass (p. 1239)
 UVGenClass : Material 1237

UVGenClass : Material
Properties:
<textureMap.coordinates>.mappingType Integer default: 0
mappingType = 0 - Texture; 1 - Environment
If the Coordinates rollout for the textureMap is displayed in Material Editor and this
property’s value is changed, the Texture/Environ radiobutton and Mapping dropdown
displays are not updated to reflect the change.
<textureMap.coordinates>.mapping Integer default: varies
If mapping type is Texture mapping (mappingType = 0), the default value for this property
is 0. mapping = 0 – Explicit Map Channel; 1 – Vertex Color Channel; 2 – Planar from
Object XYZ; 3 – Planar from World XYZ
If mapping type is Environment mapping (mappingType = 1), the default value for this
property is 4. mapping = 0 - Spherical; 1 - Cylindrical; 2 - Shrink-Wrap; 3 – Screen
The mapping source for Texture and Environment mapping types are internally stored in
separate variables, and the mapping source set for a mapping type is retained if you change
the mapping source for the other mapping type.
<textureMap.coordinates>.mapChannel Integer default: 1
The UV coordinate map channel.
<textureMap.coordinates>.U_Offset Float default: 0.0 -- animatable
<textureMap.coordinates>.V_Offset Float default: 0.0 -- animatable
Offset mapping coordinates along the surface’s local U axis or V axis. That is, at 0.0 (the
default), the map begins at the U or V origin. Increasing an Offset value moves the map
forward along that axis, and decreasing it moves it backward.
<textureMap.coordinates>.U_Tiling Float default: 1.0 -- animatable
<textureMap.coordinates>.V_Tiling Float default: 1.0 -- animatable
The tiling of UV mapping coordinates; that is, the number of times a mapped material’s
map is repeated in the surface’s local U axis or V axis.
<textureMap.coordinates>.U_Angle Float default: 0.0 -- animatable, angle
Rotates the map about the U-axis (in degrees).
<textureMap.coordinates>.V_Angle Float default: 0.0 -- animatable, angle
Rotates the map about the V-axis (in degrees).
<textureMap.coordinates>.W_Angle Float default: 0.0 -- animatable, angle
Rotates the map about the W-axis (in degrees).
<textureMap.coordinates>.Blur Float default: 1.0 -- animatable
Affects the sharpness or blurriness of the map based on its distance from the view. The
farther away the map is, the greater the blurring. The Blur value blurs maps in world space.
<textureMap.coordinates>.Blur_Offset Float default: 0.0 -- animatable
Affects the sharpness or blurriness of the map without regard to its distance from the view.
Blur Offset blurs the image itself in object space. Use this option when you want to soften
or defocus the details in a map to achieve the effect of a blurred image.
1238 Chapter 11 | 3ds max Objects

<textureMap.coordinates>.Phase Float default: 0.0 -- animatable

The speed of the animation of the noise function.
<textureMap.coordinates>.Noise_Amount Float default: 1.0 -- animatable
The strength of the fractal function, expressed as a percentage. If the amount is 0 there is
no noise. If the amount is 100 the map becomes pure noise.
<textureMap.coordinates>.Noise_Levels Integer default: 1 -- animatable
The number of times the function is applied. The effect of the level is dependent on the
Amount value. The stronger the amount, the greater the effect of increasing the Levels
value.
<textureMap.coordinates>.Noise_Size Float default: 1.0 -- animatable
The scale of the noise function relative to geometry. At very small values, the noise effect
becomes white noise. At large values, the scale can exceed the scale of the geometry, in
which case it has little or no effect.
Note:
The following properties are not accessible by MAXScript in 3ds max 4: Show Map on Back, Mirror,
and Tile checkboxes and UV/VW/WU radiobuttons in the Coordinates rollout, and Animate and On
checkboxes in the Noise rollout.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

StandardXYZGen : Material
Properties:
<textureMap.coords>.coordType Integer default: 0
The type of coordinates used for mapping:
Object XYZ (Uses planar mapping based on the object’s local coordinates (disregarding the
pivot point location).)
World XYZ (Uses planar mapping based on the scene’s world coordinates (disregarding the
object’s bounding box).)
Explicit Map Channel (Uses the map channel specified by the .mapChannel value.)
Vertex Color Channel (Uses assigned vertex colors as a channel.)
<textureMap.coords>.mapChannel Integer default: 1
The map channel used for mapping coordinates.
<textureMap.coords>.offset Point3 default: [0,0,0] -- animatable
Changes the position of the map in UV coordinates. The map moves in relation to its size.
<textureMap.coords>.Tiling Point3 default: [1,1,1] -- animatable
The number of times the map is tiled across each axis.
 TexOutputClass : Material 1239

<textureMap.coords>.angle Point3 default: [0,0,0] -- animatable, point3

angle
Rotates the map about the U, V, and W-axis (in degrees).
<textureMap.coords>.blur Float default: 1.0 -- animatable
Affects the sharpness or blurriness of the map based on its distance from the view. The
farther away the map is, the greater the blurring. The Blur value blurs maps in world space.
<textureMap.coords>.Blur_Offset Float default: 0.0 -- animatable
Affects the sharpness or blurriness of the map without regard to its distance from the view.
Blur Offset blurs the image itself in object space.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TexOutputClass : Material
Properties:
<texturemap.output>.Output_Amount Float default: 1.0 -- animatable
The amount of the map being mixed into a composite material. Affects the saturation and
alpha value of the map.
<texturemap.output>.RGB_Offset Float default: 0.0 -- animatable
This value is added to the RGB values of the map colors, which affects the tonal value of
the colors. Eventually the map becomes white and self-illuminated. Lowering the value
decreases the tonal value towards black.
<texturemap.output>.RGB_Level Float default: 1.0 -- animatable
The RGB values of the map colors are multiplied by this value, which affects the saturation
of the color. Eventually the map becomes fully saturated and self-illuminated. Lowering
the value decreases the saturation and makes the map colors grayer.
<texturemap.output>.Bump_Amount Float default: 1.0 -- animatable
Adjusts the amount of bumpiness. This value has an effect only when the map is used as a
bump map.
<texturemap.output>.Mono_Color_Map subAnim
The Mono_Color_Map SubAnim contains the monochrome color mapping curve. You
cannot create this curve in MAXScript, or access this curve unless you first turn on the
Enable Color Map checkbox in the user interface.
<texturemap.output>.RGB_Color_Map subAnim
The RGB_Color_Map SubAnim contains the RGB color mapping curves. You cannot create
these curves in MAXScript, or access the curves unless you first turn on the Enable Color
Map checkbox and select the RGB radiobutton in the user interface.
1240 Chapter 11 | 3ds max Objects

<texturemap.output.Mono_Color_Map>.curve_1 SubAnim
The curve_1 SubAnim contains the monochrome color mapping curve points. You
cannot create or access these points unless the point is animated. If a point is animated,
you can access the point position using the .Point_X property of curve_1, where X in
the point number.
<texturemap.output.RGB_Color_Map>.curve_1 SubAnim
<texturemap.output.RGB_Color_Map>.curve_2 SubAnim
<texturemap.output.RGB_Color_Map>.curve_3 SubAnim
The curve_1, curve_2, and curve_3 SubAnims contains the R, G, and B color mapping
curve, respectively. You cannot create or access points in these curves unless the point is
animated. If a point is animated, you can access the point position using the .Point_X
property of the curve, where X in the point number.
Note:
The following properties are not accessible by MAXScript in 3ds max 4: Invert, Clamp, Alpha from
RGB Intensity, and Enable Color Map checkboxes, and the RGB/Mono radio-button.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TextureMap Types
The following list displays the 3ds max TextureMap subclasses:
Adobe_Photoshop_Plug_In_Filter (p. 1241)
Adobe_Premiere_Video_Filter (p. 1242)
Bitmap (p. 1243)
Bricks (p. 1245)
Cellular (p. 1247)
Checker (p. 1249)
Composite (p. 1250)
Dent (p. 1251)
Falloff (p. 1252)
FalloffTextureMap (p. 1255)
FlatMirror (p. 1255)
Gradient (p. 1257)
Gradient_Ramp (p. 1259)
Marble (p. 1261)
Mask (p. 1262)
Mix (p. 1262)
 Adobe_Photoshop_Plug_In_Filter : TextureMap 1241

Noise (p. 1263)

NoTexture (p. 1265)
Output (p. 1265)
Paint (p. 1266)
Particle_Age (p. 1266)
Particle_Mblur (p. 1267)
Perlin_Marble (p. 1268)
Planet (p. 1269)
Raytrace (p. 1271)
Reflect_Refract (p. 1276)
RGB_Multiply (p. 1278)
RGB_Tint (p. 1278)
Smoke (p. 1279)
Speckle (p. 1280)
Splat (p. 1281)
Stucco (p. 1282)
Swirl (p. 1283)
Thin_Wall_Refraction (p. 1284)
Vertex_Color (p. 1285)
Water (p. 1286)
Wood (p. 1010)

Adobe_Photoshop_Plug_In_Filter : TextureMap
Constructor:
adobe_photoshop_plug_in_filter ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Adobe_Photoshop_Plug_In_Filter>.blur Float default: 0.0 --
animatable, percentage
<Adobe_Photoshop_Plug_In_Filter>.Foreground_Color Color default: (color 0 0
0) -- animatable
Specifies the foreground color for the image, used by some Photoshop filters.
<Adobe_Photoshop_Plug_In_Filter>.Background_Color Color default: (color 0 0
0) -- animatable
Specifies the background color for the image, used by some Photoshop filters.
1242 Chapter 11 | 3ds max Objects

<Adobe_Photoshop_Plug_In_Filter>.coordinates SubAnim
See the UVGenClass (p. 1237) topic for the StandardUVGen properties.
<Adobe_Photoshop_Plug_In_Filter>.output StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.
Note:
The following properties are not accessible by MAXScript in 3ds max 4: the Use Alpha Plane
checkbox in the Parameters rollout, and all properties in the Bitmap Parameters and Time
Parameters rollouts.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Adobe_Premiere_Video_Filter : TextureMap
Constructor:
adobe_premiere_video_filter ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Adobe_Premiere_Video_Filter>.coordinates SubAnim
See the UVGenClass (p. 1237) topic for the StandardUVGen properties.
<Adobe_Premiere_Video_Filter>.output StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.
Note:
The following properties are not accessible by MAXScript in 3ds max 4: all properties in the Time
Parameters rollout.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 BitmapTexture : TextureMap 1243

BitmapTexture : TextureMap
Constructor:
bitmaptexture ...
bitmaptex ...

Properties:
<Bitmaptexture>.bitmap Bitmap default: Bitmap:
Returns the bitmap of the texture map. The script can perform any bitmap operations on
this bitmap and the changes will be reflected in the texture map. In order to see the results
of changing the bitmap in Material Editor and in the viewports, you need to modify any
one bitmapTexture property in the Material Editor user interface. This is a read only
property.
<Bitmaptexture>.filename String default: ““ -- alias: file_name
The name of the bitmap file.
<Bitmaptexture>.filtering Integer default: 0
The method of pixel averaging used in antialiasing the bitmap:
Pyramidal (Requires less memory and is adequate for most purposes.)
Summed Area (Requires much more memory, but yields generally superior results.)
None (Turns off filtering.)
<Bitmaptexture>.monoOutput Integer default: 0
Some parameters, such as opacity or specular level are a single value as opposed to a
material’s three-value color components. Controls in this group determine the source of
the Output mono channel in terms of the input bitmap:
RGB Intensity (Uses the intensity of the red, green, and blue channels for mapping. The
color of the pixels is ignored and only the value or luminance of the pixels is used. The
colors are computed as gray values in the range between 0 (black) and 255 (white).)
Alpha (Uses the intensity of the alpha channel for mapping.)
<Bitmaptexture>.RGBOutput Integer default: 0
The RGB Channel Output determines where the output RGB part comes from. The
controls in this group affect only maps for material components that display color:
Ambient, Diffuse, Specular, Filter Color, Reflection, and Refraction.
RGB (Displays the full color values of the pixels.)
Alpha as Gray (Displays tones of gray based on the levels of the alpha channel.)
<Bitmaptexture>.apply Boolean default: false
Turn on to use the cropping or placements settings.
<Bitmaptexture>.cropPlace Integer default: 0
Set whether cropping or placement is active:
Crop
Place
1244 Chapter 11 | 3ds max Objects

<Bitmaptexture>.clipu Float default: 0.0 -- animatable, alias:

clip_u_offset
Adjusts the bitmap location along the U-axis.
<Bitmaptexture>.clipv Float default: 0.0 -- animatable, alias:
clip_v_offset
Adjusts the bitmap location along the V-axis.
<Bitmaptexture>.clipw Float default: 1.0 -- animatable, alias:
clip_u_width
Adjusts the width of the bitmap.
<Bitmaptexture>.cliph Float default: 1.0 -- animatable, alias:
clip_v_width
Adjusts the height of the bitmap.
<Bitmaptexture>.jitter Float default: 1.0 -- animatable, alias:
jitter_placement
The amount of random offset. At 0, there is no random offset.
<Bitmaptexture>.alphasource Integer default: 0
Controls in this group determine the source of the Output alpha channel in terms of the
input bitmap:
Image Alpha (Uses the image’s alpha channel.)
RGB Intensity (Converts the colors in the bitmap to grayscale tonal values and uses them
for transparency. Black is transparent and white is opaque.)
None (Opaque; does not use transparency.)
<Bitmaptexture>.preMultAlpha Boolean default: true
Determines how alpha is treated in the bitmap. When turned on, the default,
premultiplied alpha is expected in the file. When turned off, the alpha is treated as non-
premultiplied, and any RGB values are ignored.
<Bitmaptexture>.starttime Timedefault: 0f
The frame where the playback of the animated map will begin.
<Bitmaptexture>.playbackrate Float default: 1.0
Lets you speed up and slow down the rate that the animation is applied to the map (for
example, 1.0 is normal speed, 2.0 is twice as fast, .333 is 1/3 as fast).
<Bitmaptexture>.endcondition Integer default: 0
These controls determine what happens after the last frame of the animation:
Loop (Causes the animation to loop over and over again.)
Ping Pong (Causes the animation to be played backwards, making every animated
sequence “loop smoothly.”)
Hold (Causes the last frame of the animation to be frozen on the surface until the end of
the scene.)
<Bitmaptexture>.coords StandardUVGen -- alias: coordinates
See the UVGenClass (p. 1237) topic for the StandardUVGen properties.
 Bricks : TextureMap 1245

<Bitmaptexture>.output StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.
Associated Methods:
enumerateFiles [ <MAXWrapper_obj> ] <function> [ <arg> ] \
[ #inactive ] [ #videoPost ] [ #render ] [ #missing ] \
[ #localOnly ]
Lets you run through all the bitmap files currently used in the scene or in an individual
object. You can filter this so it just gives you the bitmap files that are inactive or missing.
See the Bitmap Files (p. 1641) topic for a description of this method’s parameters.
freeSceneBitmaps()
Frees up all the memory used by the image file bitmap caches. This is useful if memory is
fragmented with a lot of different bitmaps and you want to have just the ones currently
active reloaded.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Bricks : TextureMap
Constructor:
bricks ...

Properties:
<Bricks>.Brick_Type Integer default: 1
Brick_Type = 0 - Custom Bricks; 1 - Running Bond; 2 - Common Flemish Bond; 3 - English
Bond; 4 - 1/2 Running Bond; 5 - Stack Bond; 6 - Fine Running Bond; 7 - Fine Stack Bond
The brick_type values define a set of predefined values for the Stacking and Row and
Column Editing properties. Changing brick_type only updates these properties if
Material Editor is displayed and the material is in the active slot.
<Bricks>.Show_Texture_Swatches Integer default: 1
When on, updates to show the texture assigned by a map for Bricks or Mortar.
OFF
ON
<Bricks>.Brick_Color Color default: (color 165.75 76.5 51) --
animatable
The color of the bricks.
<Bricks>.Horizontal_Count Float default: 3.0 -- animatable
The number of bricks in a row.
1246 Chapter 11 | 3ds max Objects

<Bricks>.Vertical_Count Float default: 8.0 -- animatable

The number of bricks in a column.
<Bricks>.Color_Variance Float default: 0.4 -- animatable
The color variation among the bricks.
<Bricks>.Fade_Variance Float default: 0.2 -- animatable
The fading variation among the bricks.
<Bricks>.Mortar_Color Color default: (color 211.65 196.35 183.6) --
animatable
The color of the mortar.
<Bricks>.Horizontal_Gap Float default: 1.0 -- animatable
The horizontal size of the mortar between the bricks.
<Bricks>.Vertical_Gap Float default: 1.0 -- animatable
The vertical size of the mortar between the bricks.
<Bricks>.Lock_Gap_Symmetry Integer default: 1
When on, the vertical_gap and horizontal_gap values are locked to one another.
Off
On
<Bricks>.Holes Integer default: 0 -- animatable
The percentage of holes in the bricked surface caused by missing bricks. The mortar shows
through the holes.
<Bricks>.Edge_Roughness Float default: 0.0 -- animatable
Controls the roughness of the edges of the mortar.
<Bricks>.Random_Seed Integer default: 43304 -- animatable
Randomly applies patterns of color variation to the bricks. Does not require any other
setting to generate completely different patterns.
<Bricks>.Line_Shift Float default: 0.0 -- animatable
Shifts every second row of bricks a distance of one unit.
<Bricks>.Random_Shift Float default: 0.0 -- animatable
Randomly shifts all rows of bricks a distance of one unit.
<Bricks>.Use_Row_Edit Integer default: 0
Turn on/off row edit:
Off
On
<Bricks>.Per_Row Integer default: 2
The amount of bricks per row.
<Bricks>.Change_Row Float default: 1.0
For every row you specify in the Per_Row value, the software stores the amount of bricks
that you specify in the Change_row value.
 Cellular : TextureMap 1247

<Bricks>.Use_Column_Edit Integer default: 0

Turn on/off column edit:
OFF
ON
<Bricks>.Per_Column Float default: 1.0
The amount of bricks per column.
<Bricks>.Change_Column Float default: 1.0
For every row you specify in the Per_Column value, the software stores the amount of
bricks that you specify in the Change_column value.
<Bricks>.coordinates SubAnim
See the UVGenClass (p. 1237) topic for the StandardUVGen properties.
Note:
The Bricks and Mortar sub-maps are not accessible to MAXScript in 3ds max 4 unless they have
already been assigned to the Bricks map. Once these maps have been assigned, they are available as
properties of the Bricks TextureMap value. The property names, however, are dependent on the type
of maps assigned. For example, if a Checker and a Cellular map were assigned as the Bricks and
Mortar maps, the property names would be similar to Bricks__Map__7____Checker and
Mortar__Map__6____Cellular. These maps are also stored as subAnims 15 and 16 of the Bricks
TextureMap value. If the subAnim name for the subAnim is Bricks__None and Mortar__None,
respectively, no map has been assigned.
There is an error in the parameter naming for Bricks. The Per_Column property is exposed with the
name Change_Row, which conflicts with the existing Change_Row property name. As a result, you
can not access the b property.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Cellular : TextureMap
Constructor:
cellular ...

Properties:
<Cellular>.celcolor Color default: (color 255 255 255) -- animatable,
alias: Cell_Color
The color of the cell.
<Cellular>.cellmap textureMap default: undefined
Assigns a map to the cells, rather than a solid color.
1248 Chapter 11 | 3ds max Objects

<Cellular>.map1Enabled Boolean default: true -- alias: Map1_On

When on, enables the map. When off, disables the map (cell color reverts to celcolor).
<Cellular>.variation Float default: 0.0 -- animatable
Varies the color of the cells by randomly altering RGB values. The higher the variation, the
greater the random effect. This percentage value can range from 0 to 100. At 0, the color
swatch or the map completely determines the cell color.
<Cellular>.divcolor1 Color default: (color 127.5 127.5 127.5) --
animatable, alias: Division_Color1
The color of the first cell division.
<Cellular>.divmap1 textureMap default: undefined -- alias: DivisionMap1
Assigns a map to the first cell division.
<Cellular>.map2Enabled Boolean default: true -- alias: Map2_On
When on, enables the first cell division map. When off, disables the associated map (the
division color reverts to divcolor1).
<Cellular>.divcolor2 Color default: (color 0 0 0) -- animatable, alias:
Division_Color2
The color of the second cell division.
<Cellular>.divmap2 textureMap default: undefined -- alias: DivisionMap2
Assigns a map to the second cell division.
<Cellular>.map3Enabled Boolean default: true -- alias: Map3_On
When on, enables the second cell division map. When off, disables the associated map
(the division color reverts to divcolor2).
<Cellular>.type Integer default: 0
Sets the shape and size of the cells:
Circular (This gives a more organic, or bubbly look.)
Chips (With Chips, the cells have linear edges. This gives a more chipped or mosaic
appearance.)
<Cellular>.size Float default: 5.0 -- animatable
Alters the overall scale of the map. Adjust this value to fit the map to your geometry.
<Cellular>.spread Float default: 0.5 -- animatable
Alters the size of individual cells.
<Cellular>.smooth Float default: 0.1 -- animatable, alias:
Bump_smoothing
When you use a cellular map as a bump map, you might encounter aliasing or jagginess at
the boundaries of the cells. If this occurs, increase this value.
<Cellular>.fractal Boolean default: false
When on, makes the cellular pattern a fractal pattern.
<Cellular>.iteration Float default: 3.0 -- animatable, alias:
Iterations
Sets the number of times the fractal function is applied. Caution: Increasing this value
increases rendering time.
 Checker : TextureMap 1249

<Cellular>.adaptive Boolean default: true

When on, the number of fractal iterations is set adaptively. That is, the number of
iterations increases the closer the geometry is to the scene’s point of view, and decreases in
the distance. This reduces aliasing and also saves time while rendering.
<Cellular>.roughness Float default: 0.0 -- animatable
When you use the Cellular map as a bump map, this parameter controls how rough the
bumps are. When Roughness is zero, each iteration is half the strength of the previous
iteration, and half the size. As Roughness increases, each iteration is closer in strength and
size to the previous iteration. When Roughness is at its maximum value of 1.0, each
iteration is the same size and strength as the previous. In effect, this turns off the
fractalization. Roughness has no effect unless Iterations is greater than 1.0.
<Cellular>.lowthresh Float default: 0.0 -- animatable, alias: Low
<Cellular>.midthresh Float default: 0.5 -- animatable, alias: Mid
<Cellular>.highthresh Float default: 1.0 -- animatable, alias: High
These controls affect the relative size of cells and divisions. They are expressed as
normalized percentages (0 to 1) of the sizes specified by the default algorithm.
lowthresh: Adjusts the size of the cells. Default=0.0.
midthresh: Adjusts the size of the first division color, relative to the second. Default=0.5.
highthresh: Adjusts the overall size of divisions. Default=1.0.
<Cellular>.coords StandardXYZGen -- alias: coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.
<Cellular>.output StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Checker : TextureMap
Constructor:
checker ...

Properties:
<Checker>.soften Float default: 0.0 -- animatable
Blurs the edges between the checkers. A little blurs a lot.
<Checker>.color1 Color default: (color 0 0 0) -- animatable, alias:
Color_1
Sets the color of one of the checkers.
1250 Chapter 11 | 3ds max Objects

<Checker>.map1 textureMap default: undefined -- alias: Map_1

Selects a map to use within the area of the checker color. For example, you could put an
additional checkerboard within one of the checker colors.
<Checker>.map1Enabled Boolean default: true -- alias: Map_1_Enable
This enables the associated map.
<Checker>.color2 Color default: (color 255 255 255) -- animatable,
alias: Color_2
Sets the color of the second checker.
<Checker>.map2 textureMap default: undefined -- alias: Map_2
Selects a map to use within the area of the checker color. For example, you could put an
additional checkerboard within one of the checker colors.
<Checker>.map2Enabled Boolean default: true -- alias: Map_2_Enable
This enables the associated map.
<Checker>.coords StandardUVGen -- alias: coordinates
See the UVGenClass (p. 1237) topic for the StandardUVGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

CompositeTextureMap : TextureMap
Constructor:
compositeTextureMap ...
compositeTexture ...

Properties:
<CompositeTexturemap>.mapList ArrayParameter default: #(undefined,
undefined) -- alias: Maps
<CompositeTexturemap>.mapEnabled ArrayParameter default: #(true, true) --
alias: Map_1_Enable
 Dent : TextureMap 1251

Note:
Each of the map arrays initially contains 2 elements, corresponding to 2 sub-texturemaps for the
CompositeTextureMap. The mapList array stores the TextureMap for each sub-TextureMap, the
mapEnabled array stores whether that sub-TextureMap is enabled.
To change the number of sub-texturemaps, set the count property for either the mapList or
mapEnabled property to the desired number. For example, to create a compositeTextureMap with 5
sub-texturemaps, you would say:
c=compositeTextureMap()
c.mapList.count=5

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Dent : TextureMap
Constructor:
dent ...

Properties:
<Dent>.size Float default: 200.0 -- animatable
Sets the relative size of dents. As the size increases, the number of dents decreases when
other settings are the same.
<Dent>.strength Float default: 20.0 -- animatable
Higher values increase the number of dents, lower values decrease the number of dents.
Decreasing Strength reduces the number of dents over a surface. At 0, the surface is
smooth (no dents). Increasing Strength increases the number of dents over a surface. 100 is
maximum.
<Dent>.iterations Integer default: 2 -- animatable
Sets the number of calculations used to create the dents.
<Dent>.color1 Color default: (color 0 0 0) -- animatable, alias:
Color_1
Sets the color of the dent.
<Dent>.map1 TextureMap default: undefined
Colors can be replaced by maps in the dent pattern.
<Dent>.map1Enabled Boolean default: true -- alias: MapOn1
Enables the associated map.
1252 Chapter 11 | 3ds max Objects

<Dent>.color2 Color default: (color 255 255 255) -- animatable,

alias: Color_2
Sets the second color of the dent.
<Dent>.map2 TextureMap default: undefined
Assigns second map to the dent pattern.
<Dent>.map2Enabled Boolean default: true -- alias: MapOn2
Enables the associated map.
<Dent>.coords StandardXYZGen -- alias: coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Falloff : TextureMap
Constructor:
falloff ...

Properties:
<Falloff>.color1 Color default: (color 0 0 0) -- animatable, alias:
Color_1
Sets the first color for falloff.
<Falloff>.map1Amount Float default: 100.0 -- animatable, alias:
Map_Amount_1
Relative strength of the first color in the falloff map.
<Falloff>.map1 TextureMap default: undefined -- alias: Map_1
Assigns a map to the first slot in the falloff.
<Falloff>.map1On Boolean default: true -- alias: Map_1_Enable
When on, the selected maps are used in the falloff. When off, colors are used.
<Falloff>.color2 Color default: (color 255 255 255) -- animatable,
alias: Color_2
Sets the second color for falloff.
<Falloff>.map2Amount Float default: 100.0 -- animatable, alias:
Map_Amount_2
Relative strength of the second color in the falloff map.
<Falloff>.map2 TextureMap default: undefined -- alias: Map_1
Assigns a map to the second slot in the falloff.
<Falloff>.map2On Boolean default: true -- alias: Map_2_Enable
When on, the selected maps are used in the falloff. When off, colors are used.
 Falloff : TextureMap 1253

<Falloff>.type Integer default: 1 -- animatable, alias:

Falloff_Type
Sets the type of falloff:
Towards/Away (Sets the angular falloff ranges between face normals that face toward
(parallel to) the falloff direction and normals that face away from the falloff direction. The
falloff range is based on a 180-degree change in face normal direction.)
Perpendicular/Parallel (Sets the angular falloff ranges between face normals that are
perpendicular to the falloff direction and normals that are parallel to the falloff direction.
The falloff range is based on a 90-degree change in face normal direction.)
Fresnel (Based on adjustments to the Index of Refraction (IOR). Results in dim reflections
on surfaces facing the view, with much brighter reflections on angled faces, creating
highlights like those on the sides of a glass.)
Lit/Shadowed (Adjusts between two subtextures based on how much light is falling on the
object.)
Distance Blend (Adjusts between two subtextures based on Near Distance and Far Distance
values. Uses include reducing aliasing on large terrain objects and controlling the shading
in non-photorealistic environments.)
<Falloff>.mtlIOROverride Boolean default: true -- alias:
Mtl_IOR_Override_Enable
When on, allows change to the Index of Refraction set by the material.
<Falloff>.ior Float default: 1.6 -- animatable, alias:
Index_of_Refraction
Sets a new Index of Refraction.
<Falloff>.nearDistance Float default: 0.0 -- animatable, alias:
Near_Distance
The distance at which the blend effect begins.
Note: This is only available for the Distance Blend falloff type.
<Falloff>.farDistance Float default: 100.0 -- animatable, alias:
Far_Distance
The distance at which the blend effect ends.
Note: This is only available for the Distance Blend falloff type.
<Falloff>.extrapolateOn Boolean default: false -- alias:
Distance_Blend_Extrapolate
When on, allows the effect to continue beyond the Near and Far settings.
Note: This is only available for the Distance Blend falloff type.
<Falloff>.direction Integer default: 0 -- animatable, alias:
Falloff_Direction
Sets the direction of the falloff:
Viewing Direction (Sets the falloff direction relative to the camera (or screen). Changing
object orientation doesn’t affect the falloff map.)
1254 Chapter 11 | 3ds max Objects

Object ( Picks an object whose orientation determines the falloff direction, .node. The
falloff direction is the direction from the point being shaded toward the object’s center.
Points on the side toward the object center get the Towards value, and those away from
the object get the Away value.)
Local X Axis (Sets the falloff direction to the object’s local X-axis. Changing the
orientation of the object changes the falloff direction. When no object is chosen, the
falloff direction uses the local X-axis of the object being shaded.)
Local Y Axis (Sets the falloff direction to the object’s local Y-axis. Changing the orientation
of the object changes the falloff direction. When no object is chosen, the falloff direction
uses the local Y-axis of the object being shaded.)
Local Z Axis (Sets the falloff direction to the object’s local Z-axis. Changing the orientation
of the object changes the falloff direction. When no object is chosen, the falloff direction
uses the local Z-axis of the object being shaded.)
World X Axis (Sets the falloff direction to the world coordinate system X-axis. Changing
object orientation doesn’t affect the falloff map.)
World Y Axis (Sets the falloff direction to the world coordinate system Y-axis. Changing
object orientation doesn’t affect the falloff map.)
World Z Axis (Sets the falloff direction to the world coordinate system Z-axis. Changing
object orientation doesn’t affect the falloff map.)
<Falloff>.node Node default: undefined -- alias:
Falloff_Direction_Object
When Falloff_Direction = 1, this object will determine the falloff direction.
<Falloff>.texture_output StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.
<Falloff>.mixcurve SubAnim default: SubAnim:MixCurve
This mix curve determines the falloff.
<Falloff.mixcurve>.curve_1 SubAnim default: SubAnim:Curve_1
The curve_1 SubAnim contains the mix curve points. You cannot create or access these
points unless the point is animated. If a point is animated, you can access the point
position using the .Point_X property of curve_1, where X in the point number.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 FalloffTextureMap : TextureMap 1255

FalloffTextureMap : TextureMap
Constructor:
The falloffTextureMap class is used to convert 3ds max R2.5 falloff texture maps to the new
3ds max 4 falloff texture map. FalloffTextureMap objects are not creatable in MAXScript.
Properties:
There are no properties associated with falloffTextureMap.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

FlatMirror : TextureMap
Constructor:
flatMirror ...

Properties:
<FlatMirror>.applyBlur Boolean default: true
Turns on filtering to blur the maps. Antialiasing is also applied to the Distortion effect, if
any, when Apply Blur is turned on.
<FlatMirror>.blurAmount Float default: 1.0 -- animatable
Affects the sharpness or blurriness of the generated map based on its distance from the
object. The farther away the map is, the greater the blurring.
<FlatMirror>.frame Integer default: 1
When this is set to 0, the renderer creates the automatic flat mirror only on the first frame.
When this is set to 1, the renderer creates the automatic flat mirror based on nthframe.
<FlatMirror>.nthFrame Integer default: 1
<FlatMirror>.useEnviroment Boolean default: true
When off, environment maps are ignored by the mirror during rendering. It’s useful to
turn this off when you have mirrors in the scene and you’re rotoscoping against a flat
screen environment map. A screen environment map does not exist in 3D space the way
the other environment-map types do, and will not render properly.
<FlatMirror>.applyToFaceID Boolean default: false
When on, a specified material is applied to the mirror face.
<FlatMirror>.faceID Integer default: 1
Specifies the material ID number where you want the mirror assigned.
1256 Chapter 11 | 3ds max Objects

<FlatMirror>.distortionType Integer default: 0

To simulate irregular surfaces, you can distort the flat-mirror reflections. Distortion can be
based on a bump map or on noise controls built into Flat Mirror material.
None (No distortion)
Use Bump Map (Distorts the reflection using the material’s bump map. A flat mirror
surface that has a Bump map will appear bumpy, but its reflection won’t be distorted by
the bumps unless you use this option.)
Use Built-in Noise (Distorts the reflection using the settings in the Noise group.)
<FlatMirror>.noiseType Integer default: 0
Sets the type of noise when distortionType is set to 2.
Regular (Generates plain noise. Basically the same as Fractal noise with the Levels setting
at 1. When the noise type is set to Regular, the Levels spinner is inactive, because Regular is
not a fractal function.)
Fractal (Generates noise using a fractal algorithm. The Levels setting determines the
number of iterations for the fractal noise.)
Turbulence (Generates fractal noise with an absolute value function applied to it to make
fault lines.)
<FlatMirror>.distortionAmount Float default: 0.5 -- animatable
Adjusts the amount of distortion to the reflected image. This is the only value that affects
the amount of distortion.
<FlatMirror>.phase Float default: 0.0 -- animatable
Controls the speed of the animation of the noise function. A 3D noise function is used for
the noise, so that the first two parameters are U and V and the third is phase.
<FlatMirror>.size Float default: 10.0 -- animatable
Sets the scale of the noise function. Smaller values give smaller chunks of noise.
<FlatMirror>.level Float default: 2.0 -- animatable
Sets the number of fractal iterations or turbulence (as a continuous function).

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Gradient : TextureMap 1257

Gradient : TextureMap
Constructor:
gradient ...

Properties:
<Gradient>.color1 Color default: (color 0 0 0) -- animatable,
alias: Color_1
The gradient interpolates between 3 colors. This is the first color.
<Gradient>.map1 TextureMap default: undefined -- alias: Map_1
You can interpolate between 3 maps instead of colors. This is the first map.
<Gradient>.map1Enabled Boolean default: true -- alias:
Map_1_Enable
When on, the associated map is enabled.
<Gradient>.color2 Color default: (color 127.5 127.5 127.5) --
animatable, alias: Color_2
The gradient interpolates between 3 colors. This is the second color.
<Gradient>.map2 TextureMap default: undefined -- alias: Map_2
You can interpolate between 3 maps instead of colors. This is the second map.
<Gradient>.map2Enabled Boolean default: true -- alias:
Map_2_Enable
When on, the associated map is enabled.
<Gradient>.color3 Color default: (color 255 255 255) -
- animatable, alias: Color_3
The gradient interpolates between 3 colors. This is the third color.
<Gradient>.map3 TextureMap default: undefined -- alias: Map_3
You can interpolate between 3 maps instead of colors. This is the third map.
<Gradient>.map3Enabled Boolean default: true -- alias:
Map_3_Enable
When on, the associated map is enabled.
<Gradient>.color2Pos Float default: 0.5 -- animatable,
alias: Color_2_Position
Controls the centerpoint of the middle color. The position ranges from 0 to 1. When it is
0, color2 replaces color3. When it is 1, color2 replaces color1.
<Gradient>.gradientType Integer default: 0 -- alias:
Gradient_Type
Sets the type of gradient:
Linear (Interpolates the color based on the vertical position.)
Radial (Interpolates based on the distance from the center of the map.)
<Gradient>.noiseAmount Float default: 0.0 -- animatable,
alias: Noise_Amount
When nonzero (ranges from 0 to 1), applies a noise effect. This perturbs the color
interpolation parameter using a 3D noise function based on U, V, and Phase.
1258 Chapter 11 | 3ds max Objects

<Gradient>.noiseType Integer default: 0 -- alias:

Noise_Type
Set the type of noise
Regular (Generates plain noise. This is the same as Fractal noise with the Levels setting
at 1.)
Fractal (Generates noise using a fractal algorithm. noiselevels sets the number of
iterations for the fractal noise.)
Turbulence (Generates fractal noise with an absolute value function applied to it to make
fault lines. The noise amount must be greater than 0 to see any effects of turbulence.)
<Gradient>.noiseSize Float default: 1.0 -- animatable,
alias: Noise_Size
Scales the noise function. Smaller values give smaller chunks of noise.
<Gradient>.noisePhase Float default: 0.0 -- animatable,
alias: Noise_Phase
Controls the speed of the animation of the noise function. A 3D noise function is used for
the noise. The first two parameters are U and V and the third is phase.
<Gradient>.noiseLevels Float default: 4.0 -- animatable,
alias: Noise_Levels
Sets the number of fractal iterations or turbulence (as a continuous function).
<Gradient>.noiseThresholdLow Float default: 0.0 -- animatable,
alias: Low_Threshold
<Gradient>.noiseThresholdHigh Float default: 1.0 -- animatable,
alias: High_Threshold
<Gradient>.noiseThresholdSMooth Float default: 0.0 -- animatable,
alias: Threshold_Smoothing
When the noise value is above the Low threshold and below the High threshold, the
dynamic range is stretched to fill 0-1. This produces a smaller discontinuity at the
threshold transition and thus causes less potential aliasing.
noiseThresholdLow: Sets the low threshold.
noiseThresholdHigh: Sets the high threshold.
NoiseThresholdSmooth: Helps make a smoother transition from the threshold value to
the noise value. When 0, no smoothing is applied. When it is 1, the maximum amount of
smoothing is applied.
<Gradient>.coords StandardUVGen -- alias:
coordinates
See the UVGenClass (p. 1237) topic for the StandardUVGen properties.
<Gradient>.output StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.
 Gradient_Ramp : TextureMap 1259

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Gradient_Ramp : TextureMap
Constructor:
gradient_ramp ...

Properties:
<Gradient_Ramp>.Gradient_Type Integer default: 4
The type of gradient:
4 Corner (An asymmetrical linear transition of colors.)
Box (A box.)
Diagonal (A linear diagonal transition of colors.)
Lighting (Based on the light intensity value.)
Linear (A smooth, linear transition of colors.)
Mapped (Based on the luminance. Remaps the colors of the source map used in the
gradient.)
Normal (Based on the angle between the vector from the camera to the object and the
surface normal vector at the sample point.)
Pong (A diagonal sweep that repeats in the middle.)
Radial (A radial transition of colors.)
Spiral (A smooth, circular transition of colors.)
Sweep (A linear sweep transition of colors.)
Tartan (A plaid.)
<Gradient_Ramp>.Source_Map_On Integer default: 1
When on, assigns a map to a mapped gradient.
OFF
ON
1260 Chapter 11 | 3ds max Objects

<Gradient_Ramp>.Noise_Type Integer default: 0

Sets the noise type:
Regular (Generates plain noise. Basically the same as fractal noise with levels disabled,
because Regular is not a fractal function.)
Fractal (Generates noise using a fractal algorithm. levels sets the number of iterations
for the fractal noise.)
Turbulence (Generates fractal noise with an absolute value function applied to it to make
fault lines. Note that amount must be greater than 0 to see any effects of turbulence.)
<Gradient_Ramp>.amount Float default: 0.0 -- animatable
When nonzero, a random noise effect is applied to the gradient, based on the interaction
of the gradient ramp colors (and maps, if present). The higher this value, the greater the
effect.
<Gradient_Ramp>.size Float default: 1.0 -- animatable
Sets the scale of the noise function. Smaller values give smaller chunks of noise.
<Gradient_Ramp>.phase Float default: 0.0 -- animatable
Controls the speed of the animation of the noise function. A 3D noise function is used for
the noise; the first two parameters are U and V and the third is phase.
<Gradient_Ramp>.Levels Float default: 4.0 -- animatable
Sets the number of fractal iterations or turbulence (as a continuous function).
<Gradient_Ramp>.Low_Threshold Float default: 0.0 -- animatable
<Gradient_Ramp>.High_Threshold Float default: 1.0 -- animatable
When the noise value is above the Low threshold and below the High threshold, the
dynamic range is stretched to fill 0 to 1. This causes a smaller discontinuity at the
threshold transition and produces less potential aliasing.
<Gradient_Ramp>.Threshold_Smoothing Float default: 0.0 -- animatable
Helps make a smoother transition from the threshold value to the noise value. When 0, no
smoothing is applied. When 1, the maximum amount of smoothing is applied.
<Gradient_Ramp>.coordinates SubAnim
See the UVGenClass (p. 1237) topic for the StandardUVGen properties.
<Gradient_Ramp>.output StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.
<Gradient_Ramp>.gradient_ramp SubAnim
<Gradient_Ramp.gradient_ramp>.flag__1 SubAnim
<Gradient_Ramp.gradient_ramp>.flag__2 SubAnim
<Gradient_Ramp.gradient_ramp>.flag__3 SubAnim
<Gradient_Ramp.gradient_ramp.flag__1>.color Point3 default: [255,0,0] --
animatable
<Gradient_Ramp.gradient_ramp.flag__2>.color Point3 default: [0,0,255] --
animatable
<Gradient_Ramp.gradient_ramp.flag__3>.color Point3 default: [0,255,0] --
animatable
<Gradient_Ramp.gradient_ramp.flag__3>.position Float default: [0,255,0] --
animatable
 Marble : TextureMap 1261

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Marble : TextureMap
Constructor:
marble ...

Properties:
<Marble>.size Float default: 70.0 -- animatable
Sets the spacing between the veins.
<Marble>.width Float default: 0.025 -- animatable, alias:
Vein_width
Sets the width of the veins.
<Marble>.color1 Color default: (color 51 51 25.5) -- animatable, alias:
Color_1
The color for the veins.
<Marble>.map1 TextureMap default: undefined -- alias: Map_1
The map used for the veins.
<Marble>.map1Enabled Boolean default: true -- alias: Map_1_Enable
When on, the veins use map1 as their color.
<Marble>.color2 Color default: (color 209.1 209.1 153) -- animatable,
alias: Color_2
The color of the background.
<Marble>.map2 TextureMap default: undefined -- alias: Map_2
The map used for the background.
<Marble>.map2Enabled Boolean default: true -- alias: Map_2_Enable
When on, map2 is used for the background.
<Marble>.coords StandardXYZGen -- alias: coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1262 Chapter 11 | 3ds max Objects

Mask : TextureMap
Constructor:
mask ...
maskTex ...

Properties:
<Mask>.map TextureMap default: undefined
The map viewed through the mask.
<Mask>.mapEnabled Boolean default: true -- alias: Map_1_Enable
Enables the map.
<Mask>.mask TextureMap default: undefined
The map to be used as a mask.
<Mask>.maskEnabled Boolean default: true -- alias: Map_2_Enable
Enables the mask map.
<Mask>.maskInverted Boolean default: false -- alias: Invert
When on, inverts the effect of the mask.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Mix : TextureMap
Constructor:
mix ...

Properties:
<Mix>.color1 Color default: (color 0 0 0) -- animatable, alias: Color_1
The first color to be mixed.
<Mix>.map1 TextureMap default: undefined -- alias: Map_1
Sets a map to be used instead of color1.
<Mix>.map1Enabled Boolean default: true -- alias: Map_1_Enable
When on, map1 is enabled.
<Mix>.color2 Color default: (color 255 255 255) -- animatable, alias:
Color_2
The second color to be mixed.
<Mix>.map2 TextureMap default: undefined -- alias: Map_2
Sets a map to be used instead of color2.
 Noise : TextureMap 1263

<Mix>.map2Enabled Boolean default: true -- alias: Map_2_Enable

When on, map2is enabled.
<Mix>.mixAmount Float default: 0.0 -- animatable, percentage
Determines the proportion of the mix. 0 means only color1 is visible on the surface, 1
means only color2 is visible.
<Mix>.mask TextureMap default: undefined
You can also use a map instead of the mix amount. The two colors will mix in greater or
lesser degree according to the intensity of the map.
<Mix>.maskEnabled Boolean default: true -- alias: MaskEnable
When on, mask is used instead of mixAmount.
<Mix>.useCurve Boolean default: false
Determines whether the Mixing Curve effects the mix.
<Mix>.lower Float default: 0.3 -- animatable
<Mix>.upper Float default: 0.7 -- animatable
Adjusts the level of the upper and lower limits. If the two values are the same, the two
materials will meet at a definite edge. Wider ranges give more gradual mixing.
<Mix>.output StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Noise : TextureMap
Constructor:
noise ...

Properties:
<Noise>.type Integer default: 0
Sets the type of noise:
Regular (Generates plain noise. Basically the same as fractal noise with levels at 1.)
Fractal (Generates noise using a fractal algorithm. levels sets the number of iterations for
the fractal noise.)
Turbulence (Generates fractal noise with an absolute value function applied to it to make
fault lines.)
<Noise>.size Float default: 25.0 -- animatable, alias:
Noise_Size
Sets the scale of the noise function.
1264 Chapter 11 | 3ds max Objects

<Noise>.thresholdLow Float default: 0.0 -- animatable, alias:

Low_Threshold
<Noise>.thresholdHigh Float default: 1.0 -- animatable, alias:
High_Threshold
When the noise value is above the Low threshold and below the High threshold, the
dynamic range is stretched to fill 0-1. This creates a smaller discontinuity (technically, 1st
order instead of 0 order) at the threshold transition and produces less potential aliasing.
<Noise>.levels Float default: 3.0 -- animatable, alias:
Noise_Levels
Determines how much fractal energy is used for the Fractal and Turbulence noise
functions. You can set the exact amount of turbulence you want, and also animate the
number of fractal levels.
<Noise>.phase Float default: 0.0 -- animatable
Controls the speed of the animation of the noise function. Use this option to animate the
noise function.
<Noise>.color1 Color default: (color 0 0 0) -- animatable, alias:
Color_1
Sets the first principal noise color.
<Noise>.map1 TextureMap default: undefined -- alias: Map_1
Map used in place of color1.
<Noise>.map1Enabled Boolean default: true -- alias: Map_1_Enable
When on, map1 is enabled.
<Noise>.color2 Color default: (color 255 255 255) -- animatable,
alias: Color_2
Sets the second principal noise color.
<Noise>.map2 TextureMap default: undefined -- alias: Map_2
Map used in place of color2.
<Noise>.map2Enabled Boolean default: true -- alias: Map_2_Enable
When on, map2 is enabled.
<Noise>.coords StandardXYZGen -- alias: coordinates
see the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties
<Noise>.output StandardTextureOutput
see the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 NoTexture : TextureMap 1265

NoTexture : TextureMap
Assigning this texture is equivalent to setting a texture to “None” in the Material Editor. Setting a
texture to the value undefined is also equivalent to setting the texture to “None” in the Material
Editor. For example:
$box01.material.bumpmap=noTexture()

or
$box01.material.bumpmap=undefined

Constructor:
noTexture ...

Properties:
There are no additional properties associated with NoTexture.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Output : TextureMap
Constructor:
output ...

Properties:
<output>.map1 TextureMap default: undefined -- alias: Map_1
Map used to apply output settings.
<output>.map1Enabled Boolean default: true -- alias: Map_1_Enable
When on, enables the associated map.
<output>.output StandardTextureOutput
see the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1266 Chapter 11 | 3ds max Objects

Paint : TextureMap
Note: Paint maps are no longer supported in 3ds max 4.
Constructor:
paint ...

Properties:
<Paint>.height Integer default: 0 -- animatable
<Paint>.width Integer default: 0 -- animatable
<Paint>.coordinates SubAnim
See the UVGenClass (p. 1237) topic for the StandardUVGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Particle_Age : TextureMap
Constructor:
particle_age ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Particle_Age>.color1 Color default: (color 0 0 0) -- animatable,
alias: Color_1
Sets the color of a particle at its birth.
<Particle_Age>.map1 TextureMap default: undefined -- alias: Map_1
Sets the map used for a particle at its birth.
<Particle_Age>.map1Enabled Boolean default: true -- alias: Map_1_Enable
When on, the associated map is enabled.
<Particle_Age>.age1 Float default: 0.0 -- animatable, alias:
Age_1
Sets the age where a particle starts changing from color1 to color2, expressed as a
percentage of the particle’s entire life.
<Particle_Age>.color2 Color default: (color 127.5 127.5 127.5) --
animatable, alias: Color_2
Sets the color of a particle in mid-life.
<Particle_Age>.map2 TextureMap default: undefined -- alias: Map_2
Sets the map used for a particle in mid-life.
 Particle_MBlur : TextureMap 1267

<Particle_Age>.map2Enabled Boolean default: true -- alias: Map_2_Enable

When on, the associated map is enabled.
<Particle_Age>.age2 Float default: 50.0 -- animatable, alias:
Age_2
Sets the age where a particle’s color equals color2, expressed as a percentage of the
particle’s entire life.
<Particle_Age>.color3 Color default: (color 255 255 255) -- animatable,
alias: Color_3
Sets the color of a particle at its death.
<Particle_Age>.map3 TextureMap default: undefined -- alias: Map_3
Sets the map used for a particle at its death.
<Particle_Age>.map3Enabled Boolean default: true -- alias: Map_3_Enable
When on, the associated map is enabled.
<Particle_Age>.age3 Float default: 100.0 -- animatable, alias:
Age_3
Sets the age where a particle changes to color3, expressed as a percentage of the particle’s
entire life.
<Particle_Age>.output StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Particle_MBlur : TextureMap
Constructor:
particle_mblur ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Particle_MBlur>.color1 Color default: (color 255 255 255) -- animatable, alias:
Color_1
A particle approaches this color as it reaches its slowest speed. By default, this color is
white to provide the opaque end of the range for an opacity map.
<Particle_MBlur>.color2 Color default: (color 0 0 0) -- animatable, alias:
Color_2
A particle approaches this color as it speeds up. As a default, this color is black to provide
transparency in an opacity map.
1268 Chapter 11 | 3ds max Objects

<Particle_MBlur>.sharp Float default: 2.0 -- animatable, alias: Sharpness

Controls the transparency, relative to the speed. If Sharpness is set to 0, the entire particle
is blurry and transparent, no matter how slow it is traveling. The default works well in
many cases.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Perlin_Marble : TextureMap
Constructor:
perlin_marble ...

Properties:
<Perlin_Marble>.size Float default: 50.0 -- animatable
Sets the size of the marble pattern. Change this to change the scale of marble, relative to
the object’s geometry.
<Perlin_Marble>.level Float default: 8.0 -- animatable, alias:
Levels
Sets the number of times the turbulence algorithm is applied. Can range from 1.0 to 10.0.
The higher the value, the more complicated the marble pattern.
<Perlin_Marble>.color1 Color default: (color 189.975 189.975 160.65) --
animatable, alias: Color_1
The first color used in the marble.
<Perlin_Marble>.saturation1 Float default: 85.0 -- animatable, alias:
Color_1_Saturation
Controls the saturation of the color in the map, without altering the color displayed in the
color swatch. Lower values darken the color, and higher values lighten it.
<Perlin_Marble>.map1 TextureMap default: undefined
Map used in place of color1.
<Perlin_Marble>.map1Enabled Boolean default: true -- alias: EnableMap1
When on, the associated map is enabled.
<Perlin_Marble>.color2 Color default: (color 59.925 89.25 59.925) --
animatable, alias: Color_2
The second color used in the marble.
<Perlin_Marble>.saturation2 Float default: 70.0 -- animatable, alias:
Color_2_Saturation
Controls the saturation of the color in the map, without altering the color displayed in the
color swatch. Lower values darken the color, and higher values lighten it.
 Planet : TextureMap 1269

<Perlin_Marble>.map2 TextureMap default: undefined

Map used in place of color2.
<Perlin_Marble>.map2Enabled Boolean default: true -- alias: EnableMap2
When on, the associated map is enabled.
<Perlin_Marble>.coords StandardXYZGen -
- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Planet : TextureMap
Constructor:
planet ...

Properties:
<Planet>.color1 Color default: (color 10.2 20.4 79.05) -- animatable,
alias: Color_1
The color at the center of the water mass.
<Planet>.color2 Color default: (color 10.2 30.6 79.05) -- animatable,
alias: Color_2
The color surrounding the center of the water mass.
<Planet>.color3 Color default: (color 10.2 40.8 79.05) -- animatable,
alias: Color_3
The color surrounding color2, meeting the land.
<Planet>.color4 Color default: (color 10.2 99.45 12.75) -- animatable,
alias: Color_4
<Planet>.color5 Color default: (color 99.45 79.05 12.75) -- animatable,
alias: Color_5
<Planet>.color6 Color default: (color 79.05 20.4 7.65) -- animatable,
alias: Color_6
<Planet>.color7 Color default: (color 99.45 79.05 51) -- animatable,
alias: Color_7
<Planet>.color8 Color default: (color 99.45 99.45 99.45) -- animatable,
alias: Color_8
The colors in these five swatches are applied to the land areas of the planet surface. Their
arrangement continues that of the water colors. color4 is the shoreline of the land,
meeting the water; color5 comes next, working toward the center of the land mass.
color8 is at the center of the land mass.
1270 Chapter 11 | 3ds max Objects

<Planet>.continentSize Float default: 40.0 -- animatable, alias:

Continent_Size
Sets the size of the fractal noise pattern used to generate the continents. Can range from 0
to 100. The higher the value, the larger the continents.
<Planet>.islandFactor Float default: 0.5 -- animatable, alias:
Island_Factor
Sets the size of the fractal noise pattern used to generate islands and mountains. Can range
from 0 to 100. At 0, the geography is very low. Higher settings create a more rugged
landscape.
<Planet>.oceanPercent Float default: 60.0 -- animatable, alias:
Ocean_Percent
Sets the percentage of the planet’s surface that is covered by water.
<Planet>.randomSeed Integer default: 12345
Sets the seed for pseudo-random generation of the pattern. Changing this number can
completely change the pattern, even if other settings remain the same. On the other hand,
a different Planet map with the same settings including the same Random Seed will appear
the same.
<Planet>.blendWaterLand Boolean default: true
When on, the boundary between water and land is blended, giving a hazy appearance.
When off, the boundary between water and land is sharp.
<Planet>.coords StandardXYZGen -- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Raytrace : TextureMap 1271

Raytrace : TextureMap
Constructor:
raytrace ...

Properties:
<Raytrace.parameters>.Trace_Mode Integer default: 0
Sets whether to cast reflected or refracted rays:
Auto Detect (If assigned to the material’s Reflection component, the raytracer will reflect.
If assigned to Refraction, it will refract. If you assign Raytrace to any other component, you
have to manually specify whether you want reflected rays or refracted rays.)
Reflection (Casts reflected rays off the object’s surface.)
Refraction (Casts refracted rays into or through the object’s surface.)
<Raytrace.parameters>.Options__Raytracer_Enable Boolean default:
true -- animatable
Turns the raytracer on or off. Even with raytracing off, Raytrace material and Raytrace map
still reflect and refract the environment, including both the environment map for the
3ds max scene, and the environment map assigned to the Raytrace material.
<Raytrace.parameters>.Options__Antialiasing_Enable Boolean default:
true -- animatable
Turns antialiasing on or off. Antialiasing is possibly the slowest portion of raytrace
rendering.
<Raytrace.parameters>.Options__Self_Reflect_Refract Boolean default:
true -- animatable
Turns self reflection/refraction on or off.
<Raytrace.parameters>.Options__Raytrace_Atmospherics Boolean default:
true -- animatable
Turns the raytracing of atmospheric effects on or off. Atmospheric effects include fire, fog,
volume light, and so on.
<Raytrace.parameters>.Options__Reflect_Refract_Material_ID_s Boolean default:
true -- animatable
When on, the material reflects effects assigned to material IDs in the renderer’s G-buffer on
or off.
<Raytrace.parameters>.Options__Raytrace_Objects_in_Glass Boolean default:
true -- animatable
Turns the raytracing of objects inside raytraced objects on or off.
<Raytrace.parameters>.Options__Raytrace_Atmospherics_in_Glass Boolean default:
true -- animatable
Same as the previous control, but for atmospheric effects instead of objects.
<Raytrace.parameters>.Options__Color_Density___Fog_Enable Boolean default:
true -- animatable
Turns the color density and fog features on or off.
1272 Chapter 11 | 3ds max Objects

<Raytrace.parameters>.Background_Mode Integer default: 0

Sets Background Mode:
Use Environment Settings (Respects the environment settings of the current scene.)
Use Background_Color (Overrides environment settings)
Use background map (Overrides the environment settings with the specified map.)
<Raytrace.parameters>.Background_Color Color default:
(color 0 0 0) -- animatable
Color used as background.
<Raytrace.parameters>.Local_Antialias_Override Boolean default:
false
When on, allows you to modify local anitialiasing settings.
<Raytrace.parameters>.Adaptive_Antialiasing Boolean default:
false
When on, enables the adaptive antialiaser for this Raytrace map.
<Raytrace.parameters>.Local_Threshold Float default:
0.1 -- animatable
Determines the sensitivity of the adaption algorithm. This value can range from 0 to 1,
where 0 always casts the maximum number of rays and 1 always casts only the minimum
number of rays.
<Raytrace.parameters>.Local_Min__Rays Integer default:
4 -- animatable
Sets the initial number of rays cast per pixel.
<Raytrace.parameters>.Local_Max_Rays Integer default:
32 -- animatable
Sets the maximum number of rays the algorithm casts.
<Raytrace.parameters>.Local_Blur_Offset Float default:
0.0 -- animatable
Affects the sharpness or blurriness of reflections or refractions without regard to distance.
You can use this to soften the details of a reflection or refraction. This value is specified in
pixels.
<Raytrace.parameters>.Local_Blur_Aspect Float default:
1.0 -- animatable
Changes the shape of the blur by changing the aspect ratio. Usually you will not need to
change this setting.
<Raytrace.parameters>.Local_Defocus_Amount Float default:
0.0 -- animatable
Blurs based on distance. Objects near the surface are not blurred, but objects farther away
are blurred. The rays cast are spread as they leave the surface of the Raytrace map object.
<Raytrace.parameters>.Local_Defocus_Aspect Float default:
1.0 -- animatable
Changes the shape of the defocusing by changing the aspect ratio. Usually you will not
need to change this setting.
 Raytrace : TextureMap 1273

<Raytrace.parameters>.Use_Blur_Map Boolean default:

false
When on, uses a map to apply the Blur Offset value. That is, where the map is white, blur
offset is fully applied, and where it is black, it is ignored. For example, if the map is a
Checker map, blur offset is applied only in every other square. Values between black and
white cause less blur.
<Raytrace.parameters>.Use_Defocus_Map Boolean default:
false
When on, uses a map to apply the Defocus value. That is, where the map is white, Defocus
is fully applied, and where it is black, it is ignored. For example, if the map is a Checker
map, Defocus is applied only in every other square. Values between black and white cause
less defocusing.
<Raytrace.parameters>.Attenuation_Mode Integer default: 0
Sets Attenuation Mode:
Off
Linear (Linear attenuation is calculated between the attenuation_start and
attenuation_end values.)
Inverse Scale (Sets inverse square attenuation. Inverse square attenuation is calculated
beginning at the attenuation_start range, and doesn’t use the attenuation_end
range. Inverse scale is the actual attenuation rate for light in the real world. However, it
doesn’t always give the effect you want in a rendered scene.)
Exponential (Sets exponential attenuation. Exponential attenuation is calculated between
the attenuation_start and attenuation_end values. You also specify the exponent to
use.)
Custom Falloff (Specifies a custom curve to use for attenuation.)
<Raytrace.parameters>.Attenuation_Start Float default:
0.0 -- animatable
The distance in world units where attenuation begins.
<Raytrace.parameters>.Attenuation_End Float default:
100.0 -- animatable
<Raytrace.parameters>.Attenuation_Exponent Float default:
2.0 -- animatable
<Raytrace.parameters>.Attenuation_Color_Mode Integer default: 0
Attenuation_Color_Mode = 0 - Background; 1 - use Attenuation_Color
<Raytrace.parameters>.Attenuation_Color Color default:
(color 0 0 0) -- animatable
Sets the distance in world units where the ray is fully attenuated.
<Raytrace.parameters>.Attenuation_Near Float default:
1.0 -- animatable
Sets the strength of the reflected/refracted ray at the start range distance. This is a
normalized percentage that can range from 0.0 to 1.0.
1274 Chapter 11 | 3ds max Objects

<Raytrace.parameters>.Attenuation_Control_1 Float default:

0.6666 -- animatable
Controls the shape of the curve near the curve start.
<Raytrace.parameters>.Attenuation_Control_2 Float default:
0.3333 -- animatable
Controls the shape of the curve near the curve end.
<Raytrace.parameters>.Attenuation_Far Float default:
0.0 -- animatable
Sets the strength of the reflected/refracted ray at the end range distance. This is a
normalized percentage that can range from 0.0 to 1.0.
<Raytrace.parameters>.Use_Reflectivity_Map Boolean default:
false -- animatable
Enables a reflectivity map.
<Raytrace.parameters>.Reflectivity_Map_Amount Float default:
1.0 -- animatable
Controls the amount of raytracing used by the material it is assigned to.
<Raytrace.parameters>.Basic_Tint_Enable Boolean default:
false
Turns basic tinting on or off.
<Raytrace.parameters>.Tint_Amount Float default:
1.0 -- animatable
Sets the amount of tinting used.
<Raytrace.parameters>.Tint_Color Color default:
(color 255 255 255) -- animatable
Assigns a tint color for reflections.
<Raytrace.parameters>.Use_Tint_Map Boolean default:
false
Enables the use of a map for tinting.
<Raytrace.parameters>.Color_Density_Enable Boolean default:
false
Turns color density on or off.
<Raytrace.parameters>.Color_Density_Color Color default:
(color 255 255 255) -- animatable
Sets the transmission color.
<Raytrace.parameters>.Color_Density_Amount Float default:
1.0 -- animatable
Controls the amount of density color. It can range from 0 to 1.0. Reducing this value
reduces the density color effect.
 Raytrace : TextureMap 1275

<Raytrace.parameters>.Color_Density_Start Float default:

0.0 -- animatable
<Raytrace.parameters>.Color_Density_End Float default:
25.0 -- animatable
A thin piece of tinted glass is mainly clear, while a thick piece of the same glass has more
color. Start and End Distance, expressed in world units, controls help you simulate this
effect. Start is the position in the object where the density color begins to appear. End is
the position in the object where the density color reaches its full Amount value. To have a
lighter effect, increase the End value. To have a heavier effect, reduce the End value.
<Raytrace.parameters>.Use_Color_Density_Map Boolean default:
false
Enables the use of a map for the color density filter.
<Raytrace.parameters>.Fog_Enable Boolean default:
false
Turns fog on or off.
<Raytrace.parameters>.Fog_Color Color default:
(color 255 255 255) -- animatable
Sets the fog color.
<Raytrace.parameters>.Fog_Amount Float default:
1.0 -- animatable
Controls the amount of density fog. It can range from 0 to 1.0. Reducing this value reduces
the density fog effect and makes the fog translucent.
<Raytrace.parameters>.Fog_Start Float default:
0.0 -- animatable
<Raytrace.parameters>.Fog_End Float default:
25.0 -- animatable
Start and End Distance controls, expressed in world units, adjust the fog effect based on
the object’s dimensions. Start is the position in the object where the density fog begins to
appear. End is the position in the object where the density fog reaches its full Amount
value. To have a lighter effect, increase the End value. To have a heavier effect, reduce the
End value.
<Raytrace.parameters>.Use_Fog_Map Boolean default:
false
Enables a map for the fog color.
The following properties do not correspond to any user-interface items, and may or may not be used
by the raytracer.
<Raytrace.parameters>.Interobject_Interphase_Fusing Boolean default:
false
<Raytrace.parameters>.IIF_Tolerance Float default:
1.0
1276 Chapter 11 | 3ds max Objects

Note:
The sub-maps that can be assigned to a Raytrace texturemap are not accessible to MAXScript in
3ds max 4 unless they have already been assigned to the Bricks map. Once these maps have been
assigned, they are available as properties of the Bricks TextureMap value. The property names,
however, are dependent on the type of maps assigned. For example, if dent maps were assigned to
all the sub-maps, the property names would be similar to Background__Map__17____Dent,
Blur_Map__Map__18____Dent, Defocus_Map__Map__19____Dent,
Reflectivity_Map__Map__20____Dent, Tint_Map__Map__21____Dent,
Color_Density_Map__Map__22____Dent, and Fog_Color_Map__Map__23____Dent. These
maps are also stored as subAnims 2 through 8 of the Raytrace TextureMap value, respectively. If the
subAnim name for a subAnim is similar to Background__None, no map has been assigned to that
sub-map.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Reflect_Refract : TextureMap
Constructor:
reflect_refract ...

Properties:
<Reflect_Refract>.source Integer default: 0
Chooses the source of the six cubic maps:
Automatic (Automatically generates by looking out in six directions from the pivot of the
object with the material, then mapped onto the surface during rendering. When on, the
options in the Automatic group are active, letting you choose whether the maps will be
generated only once, or regenerated at specified frames in the animation.)
From File (When on, you can specify the bitmaps to use.)
<Reflect_Refract>.size Integer default: 100 -- animatable
Sets the size of the Reflect/Refract maps. The default value of 100 produces distinct images.
Lower values lose progressively more detail.
<Reflect_Refract>.useAtmosphericMap Boolean default: true -- alias:
Use_Atmospheric
When off, environment maps are ignored by Reflect/Refract map during rendering. It’s
useful to turn this off when you have mirrors in the scene and you’re rotoscoping against a
flat screen environment map. A screen environment map does not exist in 3D space the
way the other environment-map types do, and will not render properly.
 Reflect_Refract : TextureMap 1277

<Reflect_Refract>.apply Boolean default: true

Turns on filtering to blur the maps.
<Reflect_Refract>.blurOffset Float default: 0.0 -- animatable,
alias: Blur_Offset
Affects the sharpness or blurriness of the map without regard to its distance from the
object. Use this when you want to soften or defocus the details in a map to achieve the
effect of a blurred image.
<Reflect_Refract>.blur Float default: 1.0 -- animatable
Affects the sharpness or blurriness of the generated map based on its distance from the
object. The farther away the map is, the greater the blurring. Blur is primarily used to avoid
aliasing. It’s a good idea to use a small amount of blurring for all maps in order to avoid
the scintillation or aliasing that can occur when pixel details are reduced off in the
distance.
<Reflect_Refract>.near Float default: 0.0 -- animatable,
alias: Near_Value
Sets the near range for fog.
<Reflect_Refract>.far Float default: 500.0 -- animatable,
alias: Far_Value
Sets the far range for fog.
<Reflect_Refract>.frametype Integer default: 0
Sets the frame type:
First Frame Only (Tells the renderer to create automatic maps only on the first frame.)
Every Nth Frame (Tells the renderer to create animated auto maps based on nthframe.)
<Reflect_Refract>.nthframe Integer default: 1
Sets the frame rate for automatic maps.
<Reflect_Refract>.bitmapName ArrayParameter default: #(undefined, ... ,
undefined)
Array with 6 elements. Each element stores a string reflecting the name of a source bitmap
file.
<Reflect_Refract>.outputname String default: undefined -- alias:
Output_Name

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1278 Chapter 11 | 3ds max Objects

RGB_Multiply : TextureMap
Constructor:
rgb_multiply ...

Properties:
<RGB_Multiply>.color1 Color default: (color 255 255 255) -- animatable,
alias: Color_1
<RGB_Multiply>.map1 TextureMap default: undefined -- alias: Map_1
<RGB_Multiply>.map1Enabled Boolean default: true -- alias: Map_1_Enable
Enables associated map.
<RGB_Multiply>.color2 Color default: (color 255 255 255) -- animatable,
alias: Color_2
<RGB_Multiply>.map2 TextureMap default: undefined -- alias: Map_2
<RGB_Multiply>.map2Enabled Boolean default: true -- alias: Map_2_Enable
Enables associated map.
<RGB_Multiply>.alphaFrom Integer default: 2
Determines how to generate alpha for the map:
Map #1 (Uses the first map’s alpha channel.)
Map #2 (Uses the second map’s alpha channel.)
Multiply Alphas (Generates a new alpha channel by multiplying the alpha channels of the
two maps.)

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

RGB_Tint : TextureMap
Constructor:
rgb_tint ...

Properties:
<RGB_Tint>.red Color default: (color 255 0 0) -- animatable
The tint of the red color channel.
<RGB_Tint>.green Color default: (color 0 255 0) -- animatable
The tint of the green color channel.
<RGB_Tint>.blue Color default: (color 0 0 255) -- animatable
The tint of the blue color channel.
 Smoke : TextureMap 1279

<RGB_Tint>.map1 TextureMap default: undefined -- alias: Map_1

Sets the map to be tinted.
<RGB_Tint>.map1Enabled Boolean default: true -- alias: Map_1_Enable
Enable the effect of map1.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Smoke : TextureMap
Constructor:
smoke ...

Properties:
<Smoke>.size Float default: 40.0 -- animatable
Changes the scale of the smoke “clumps.”
<Smoke>.iterations Integer default: 5 -- animatable
Sets the number of times the fractal function is applied. The higher the value, the more
detail within the smoke, but the longer the calculation time.
<Smoke>.phase Float default: 0.0 -- animatable
Shifts the turbulence within the smoke pattern. Animate this parameter to animate the
movement of the smoke.
<Smoke>.exponent Float default: 1.5 -- animatable
Makes color2, representing the smoke, sharper and more wispy. As this value increases,
the smoke “tendrils” become smaller within the pattern.
<Smoke>.color1 Color default: (color 0 0 0) -- animatable, alias:
Color_1
The smokeless portion of the effect.
<Smoke>.map1 TextureMap default: undefined
The map used for the smokeless portion of the effect.
<Smoke>.map1On Boolean default: true -- alias: Map1_On
Enables the associated map.
<Smoke>.color2 Color default: (color 229.5 229.5 229.5) -- animatable,
alias: Color_2
The color of the smoke.
<Smoke>.map2 TextureMap default: undefined
The map used for the smoke.
1280 Chapter 11 | 3ds max Objects

<Smoke>.map2On Boolean default: true -- alias: Map2_On

Enables the associated map.
<Smoke>.coords StandardXYZGen -- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Speckle : TextureMap
Constructor:
speckle ...

Properties:
<Speckle>.size Float default: 60.0 -- animatable
Adjusts the size of the speckles. Use this to make the speckles match your geometry.
<Speckle>.color1 Color default: (color 51 127.5 255) -- animatable, alias:
Color_1
The color of the speckles.
<Speckle>.map1 TextureMap default: undefined
The map used as the color of the speckles.
<Speckle>.map1On Boolean default: true -- alias: Map1_On
Enables associated map.
<Speckle>.color2 Color default: (color 178.5 204 204) -- animatable, alias:
Color_2
The color of the background.
<Speckle>.map2 TextureMap default: undefined
The map used as the color of the background.
<Speckle>.map2On Boolean default: true -- alias: Map2_On
Enables associated map.
<Speckle>.coords StandardXYZGen -- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Splat : TextureMap 1281

Splat : TextureMap
Constructor:
splat ...

Properties:
<Splat>.size Float default: 40.0 -- animatable
Adjusts the size of the splats. Use this to make the splats match your geometry.
<Splat>.iterations Integer default: 4 -- animatable
Sets the number of times the fractal function is evaluated. The higher the number, the
more detailed the splats, but the longer the calculation time.
<Splat>.threshold Float default: 0.2 -- animatable
Determines how much of color1 is mixed with color2. At 0, only color1 is displayed;
at 1, only color2 is displayed.
<Splat>.color1 Color default: (color 178.5 204 204) -- animatable,
Color_1
The color of the background.
<Splat>.map1 TextureMap default: undefined
The map used as the color of the background.
<Splat>.map1On Boolean default: true -- alias: Map1_On
Enables associated map.
<Splat>.color2 Color default: (color 51 127.5 255) -- animatable,
Color_2
The color of the splats.
<Splat>.map2 TextureMap default: undefined
The map used as the color of the splats.
<Splat>.map2On Boolean default: true -- alias: Map2_On
Enables associated map.
<Splat>.coords StandardXYZGen -- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1282 Chapter 11 | 3ds max Objects

Stucco : TextureMap
Constructor:
stucco ...

Properties:
<Stucco>.size Float default: 20.0 -- animatable
Adjusts the size of the indentations. Use this to make the scale of the stucco match your
geometry.
<Stucco>.thickness Float default: 0.15 -- animatable
Blurs the border between the two colors. At 0, the borders are sharp. The higher the
Thickness, the more the borders are blurred and the less distinct the indentations are.
When you use Stucco as a bump map, the indentations are very faint at 0.5 and disappear
at values not much greater.
<Stucco>.threshold Float default: 0.57 -- animatable
Determines how much of color1 is mixed with color2. At 0, only color1 is displayed;
at 1, only color2 is displayed.
<Stucco>.color1 Color default: (color 0 0 0) -- animatable, alias:
Color_1
The color of the indentations.
<Stucco>.map1 TextureMap default: undefined
The map used as the color of the indentations.
<Stucco>.map1On Boolean default: true -- alias: Map1_On
Enables associated map.
<Stucco>.color2 Color default: (color 229.5 229.5 229.5) -- animatable,
alias: Color_2
The background stucco color.
<Stucco>.map2 TextureMap default: undefined
The map used as the background stucco color.
<Stucco>.map2On Boolean default: true -- alias: Map2_On
Enables associated map.
<Stucco>.coords StandardXYZGen -- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Swirl : TextureMap 1283

Swirl : TextureMap
Constructor:
swirl ...

Properties:
<Swirl>.Base Color default: (color 229.5 147.9 76.5) -- animatable
The underlying layer for the swirl effect.
<Swirl>.Swirl Color default: (color 0 25.5 51) -- animatable
Mixed with the Base color or map, produces the swirl effect.
<Swirl>.Color_Contrast Float default: 0.4 -- animatable
Controls the contrast between Base and Swirl. At 0, the swirl is blurred. Higher values
increase the contrast until all colors become black and white, even if Swirl Intensity and
Swirl Amount are very high.
<Swirl>.Swirl_Intensity Float default: 2.0 -- animatable
Controls the intensity of the swirl color. Higher values create a more vibrant mix of colors.
At 0, the swirl effect disappears.
<Swirl>.Swirl_Amount Float default: 1.0 -- animatable
Controls the quantity of the swirl color that gets mixed into the base color. If set to 0,
only the base color is used.
<Swirl>.Twist Float default: 1.0 -- animatable
Changes the number of spirals in the swirl effect. Higher values increase the number of
spirals. Negative values change the direction of the twist. At 0, the colors are randomly
distributed, not swirled.
<Swirl>.Constant_Detail Integer default: 4 -- animatable
Changes the level of detail within a swirl. Lower values minimize the level of detail within
the swirl. At 0, all detail is lost. Higher values increase detail until the swirl effect
disappears.
<Swirl>.Center_Position_Y Float default: -0.5 -- animatable
<Swirl>.Center_Position_X Float default: -0.5 -- animatable
Adjusts the location of the swirl’s center on the object.
<Swirl>.Lock_Background Integer default: 1
X and Y values remain identical as you adjust them. By turning off Lock and adjusting
either the X or Y position, you can “slide” the swirl effect across the object.
OFF
ON
<Swirl>.Random_Seed Float default: 23638.4 -- animatable
Sets a new starting point for the swirl effect. Changes the swirl pattern while maintaining
other parameters.
<Swirl>.coordinates SubAnim
See the UVGenClass (p. 1237) topic for the StandardUVGen properties.
1284 Chapter 11 | 3ds max Objects

Note:
The Base and Swirl sub-maps are not accessible to MAXScript in 3ds max 4 unless they have already
been assigned to the Swirl map. Once these maps have been assigned, they are available as properties
of the Swirl TextureMap value. The property names, however, are dependent on the type of maps
assigned. For example, if a Checker and a Cellular map were assigned as the Base and Swirl sub-maps,
the property names would be similar to Swirl__Map__7____Checker and
Swirl__Map__6____Cellular. These maps are also stored as subAnims 12 and 13 of the Swirl
TextureMap value. If the subAnim name for the subAnim is Swirl__None and Swirl__None,
respectively, no map has been assigned.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Thin_Wall_Refraction : TextureMap
Constructor:
thin_wall_refraction ...

Properties:
<Thin_Wall_Refraction>.applyBlur Boolean default: true
Turns on filtering to blur the maps.
<Thin_Wall_Refraction>.blur Float default: 1.0 -- animatable
Affects the sharpness or blurriness of the generated map based on its distance from the
object. The farther away the map is, the greater the blurring. Blur is primarily used to avoid
aliasing. It’s a good idea to use a small amount of blurring for all maps in order to avoid
the scintillation or aliasing that can occur when pixel details are reduced off in the
distance.
<Thin_Wall_Refraction>.frame Integer default: 0
Affects how the refraction should behave in animations:
First Frame Only (Tells the renderer to create the refracted image only on the first frame.)
Every Nth Frame (Tells the renderer to regenerate the refracted image based on nthframe.)
<Thin_Wall_Refraction>.nthFrame Integer default: 1
Sets the regeneration rate in animations.
<Thin_Wall_Refraction>.useEnviroment Boolean default: true
When off, environment maps are ignored by the refraction during rendering. It’s useful to
turn it this off when you have refractions in the scene and you’re rotoscoping against a flat
screen environment map. A screen environment map does not exist in 3D space the way
the other environment map types do, and will not render properly.
 Vertex_Color : TextureMap 1285

<Thin_Wall_Refraction>.thicknessOffset Float default: 0.5 -- animatable,

alias: Thickness_Offset
Affects the size of the refractive offset, or jog effect. At 0, there’s no offset, and the object
can appear invisible in the rendered scene. At 10.0, the offset is at its greatest.
<Thin_Wall_Refraction>.bumpMapEffect Float default: 1.0 -- animatable,
alias: Bump_Map_Effect
Affects the magnitude of refraction due to the presence of a bump map. This parameter
multiplies the current bump map Amount in the parent material. Reduce this value to
reduce the effect of the secondary refraction; increase this value to increase the effect. If
there is no bump map assigned, this value has no effect.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Vertex_Color : TextureMap
Constructor:
vertex_color ...

Properties:
There are no additional properties for vertex_color.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1286 Chapter 11 | 3ds max Objects

Water : TextureMap
Constructor:
water ...

Properties:
<Water>.numWaveSets Integer default: 10 -- animatable, alias:
Num_Wave_Sets
Specifies how many wave sets are used in the pattern. Wave sets are groups of radially
symmetrical waves that originate from randomly computed points along the surface of an
imaginary sphere inside the object (a circle, in the case of 2D wave distribution). For calm
water, set this to a low number. Use a high number for choppy water.
<Water>.waveRadius Float default: 800.0 -- animatable, alias:
Wave_Radius
Specifies the radius, in 3ds max units, of the imaginary sphere (3D distribution) or circle
(2D distribution) whose surface is the origin of each wave set. A large radius produces large
circular wave patterns, while a small radius produces dense, smaller waves.
<Water>.waveLenMax Float default: 50.0 -- animatable
<Water>.waveLenMin Float default: 5.0 -- animatable
Define the interval used to randomly chose each wave center. If these two values are close
together, the water appears more regular. If they’re farther apart, the water is less regular.
<Water>.amplitude Float default: 1.0 -- animatable
Adjusts the strength and the depth of the waves by increasing the contrast between the
two colors.
<Water>.phase Float default: 0.0 -- animatable
Shifts the wave pattern. Animate this parameter to animate the motion of the pattern.
<Water>.distribution Integer default: 0
3D distributes the wave centers on the surface of an imaginary sphere, affecting all sides of
a 3D object. 2D distributes the wave in circles centered on the XY plane, which is more
appropriate for flat water surfaces such as oceans and lakes.
3D
2D
<Water>.randomSeed Integer default: 30159
Provides a seed number to generate the water pattern. The pattern changes with each seed,
but all other settings are maintained.
<Water>.color1 Color default: (color 198.9 198.9 239.7) -- animatable,
alias: Color_1
Sets the wave trough color.
<Water>.map1 TextureMap default: undefined
Sets a map as the wave trough color.
<Water>.map1On Boolean default: true -- alias: Map1_On
Enables associated map.
 Wood : TextureMap 1287

<Water>.color2 Color default: (color 25.5 25.5 198.9) -- animatable,

alias: Color_2
The color of wave peaks.
<Water>.map2 TextureMap default: undefined
Sets a map as the color of wave peaks.
<Water>.map2On Boolean default: true -- alias: Map2_On
Enables associated map.
<Water>.coords StandardXYZGen -- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Wood : TextureMap
Constructor:
wood ...

Properties:
<Wood>.thickness Float default: 7.0 -- animatable, alias:
Grain_Thickness
Sets the relative thickness of the color bands that make up the grain.
<Wood>.radialNoise Float default: 1.0 -- animatable, alias:
Radial_Noise
Sets the relative randomness of the pattern on a plane perpendicular to the grain, the
circular ring structure.
<Wood>.axialNoise Float default: 1.0 -- animatable, alias:
Axial_Noise
Sets the relative randomness of the pattern on a plane parallel with the grain, along the
length of the grain.
<Wood>.color1 Color default: (color 201.45 175.95 68.85) -- animatable,
alias: Color_1
<Wood>.map1 TextureMap default: undefined
<Wood>.map1Enabled Boolean default: true -- alias: MapOn1
Enables associated map.
1288 Chapter 11 | 3ds max Objects

<Wood>.color2 Color default: (color 130.05 81.6 12.75) -- animatable,

alias: Color_2
<Wood>.map2 TextureMap default: undefined
<Wood>.map2Enabled Boolean default: true -- alias: MapOn2
Enables associated map.
<Wood>.coords StandardXYZGen -- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235)
Material Common Properties, Operators, and Methods (p. 1203)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Animation Controllers
All animation in 3ds max is implemented using one of the many controller classes accessible in the
Track View and Motion Panel, or assigned automatically by 3ds max when you use the Animate
button to do keyframing. Certain controllers (keyframeable controllers) store their animation values
as keys.
This section includes topics that discuss all aspects of scripting 3ds max controllers and the Key
classes used in keyframing.
Controller Common Properties, Operators, and Methods (p. 1289)
Time and Key Functions on Object Hierarchies (p. 1299)
Controllers - Superclass Level (p. 1300)
The controllers are arranged in a hierarchy of superclasses and classes. All classes in a superclass
output a specific data type (for example, Float or Point3). Each animatable property in 3ds max has
a data type, and any of the classes in the superclass that outputs that data type can be assigned that
property. So, for example, the linear_float and noise_float controllers are classes in the Float
superclass, and either can be assigned to the height property of a box, which is has a Float data type.
The list of controller superclasses can be determined using the apropos() function:
apropos “controller:super”

The list of available controllers can be determined using the showClass() function:
showClass “*:*controller*”
which lists all the known classes that have “controller” in their superclass name. The
controllers include, at least, 3ds max’s core controllers and any 3rd-party plug-in
controllers. In some cases, embedded controllers for some complex plug-ins may be visible
in the showClass() listing (such as for character studio and HyperMatter). You should
not attempt to create and use these controllers individually, this may result in system
exceptions.
 Wood : TextureMap 1289

Controller Common Properties, Operators, and Methods

Properties:
All controllers have the following properties:
<controller>.keys MAXKeyArray -- read-only, the controller’s key array
<controller>.value varies -- get or set the current controller value

The keys and value properties give you access to the value and keys in a free-standing
controller, which is useful when working with the global tracks controllers that are
accessible in MAXScript. Those controllers that are not keyframeable return an empty
KeyArray for their keys property.
The value property is sensitive to the current time and animate contexts, so you can use it
to evaluate a controller at various times or to plant keyframes in those controllers that
support keys.
You can only assign a value to a controller’s value property if the controller is a key-based
controller. The only exception to this is that you can assign a Matrix3 value to a PRS
controller’s value property. MAXScript will automatically set the individual position,
rotation, and scale values to the values represented in the Matrix3 value.
If an Ease Curve has been assigned to a controller, the following controller-related sub-property is
available:
<controller>.Ease_Curve Float -- the controller’s ease curve value

If an Ease Curve has been assigned to a controller, the following controller-related sub-property is
available:
<controller>.Multiplier_Curve Float -- the controller’s multiplier curve value

See the Ease and Multiplier Curve Functions (p. 1297) topic for methods and notes related to ease and
multiplier curves.
Example:
globaltracks.float.mycontroller.value
globaltracks.float.mycontroller.keys[2]

Associated Properties:
All animatable properties in 3ds max objects let you reference several controller-related sub-
properties. These are:
<property>.controller -- the property’s controller
<property>.track -- a synonym for .controller
<property>.isAnimated -- a boolean indicating whether the property is animated
<property>.keys -- read-only, gets the property’s controller’s key array

The track property is a simple synonym for controller. If an animatable property does not yet
have a controller assigned, the isAnimated property returns false and the controller, track,
and keys properties return undefined.
1290 Chapter 11 | 3ds max Objects

Example:
$foo.pos.controller
bend_mod1.angle.isAnimated
$bar.taper.gizmo.scale.keys[2]

You create controllers as you do other 3ds max objects by calling the class as a function:
c = bezier_position()
and assign them to animatable properties by assigning to the controller property in those
animatables.
Example:
$foo.pos.controller = c
$baz.bend.gizmo.rotation.controller = tcb_rotation()
$box01.length = linear_float()

Methods:
getPointControllers {<editable_mesh_node> | <editable_spline_node>}
Returns an array of controllers assigned to the vertices in the mesh or spline. If no
controller has been assigned to a vertex, the array element value will be undefined. For
editable splines, each knot consists of 3 vertices: the in vector, the knot, and the out
vector. The array of controllers returned is a “snapshot” of the current controllers. If
controllers are assigned or changed for a vertex, this change is not reflected in the array. If
a vertex is added/deleted, the array is not resized to reflect the change in number of
vertices.
getPointController <editable_mesh_node> <vertex_index_integer>
Returns the controller currently assigned to the vertex, undefined if no controller
assigned.
getPointController <editable_spline_node> <spline_index_integer>
<vertex_index_integer>
Returns the controller for specified vertex in the specified spline, undefined if no
controller assigned. Each spline knot consists of 3 vertices: the in vector, the knot, and the
out vector.
Note:
Applying a controller to a property causes the controller to take on the properties value at frame 0.
If keys are present for the controller before the assignment to the property, all keys will be adjusted
by the difference between the controller’s value at frame 0 and the property’s value. This is shown
in the following example.
 Wood : TextureMap 1291

Script:
a=bezier_float()
addnewkey a 0
addnewkey a 10
a.keys[1].value=10
a.keys[2].value=100
b=box()
b.height
b.height.controller=a
b.height
at time 10 b.height

Output:
Controller:Bezier_Float -- result line 1
#Bezier Float key(1 @ 0f) -- result line 2
#Bezier Float key(2 @ 10f) -- result line 3
10 -- result line 4, key value at time 0
100 -- result line 5, key value at time 10
$Box:Box01 @ [0.0,0.0,0.0] -- result line 6
25.0 -- result line 7, default property value
Controller:Bezier_Float -- result line 8
25.0 -- result line 9, key value changed from 10 to 25 (delta= +15)
115.0 -- result line 10, key value changed by delta = +15

A somewhat strange situation can arise when a single controller is assigned to multiple object
properties. The value actually stored in a controller may not necessarily be the same value seen
in Track View or in the command panels, nor the same value returned by accessing the property
value in MAXScript. Part of a MAXWrapper property definition is scaling value that is applied
when reading or setting the true value stored in a controller. For example, the slice_to and
slice_from properties associated with many of the geometry primitives is displayed in
degrees. The actual value stored in the controller associated with these properties are in radians.
This scaling factor is an internal property of the MAXWrapper property, and not an internal
property of the controller. Both 3ds max and MAXScript automatically apply the specified
scaling factor when accessing properties, so this scaling is normally invisible to the user. If the
same controller is assigned to two properties which have different scaling factors, the question
arises as to which scaling factor to apply to the output of the controller. If you are accessing the
controller’s value through a MAXWrapper property, the scaling factor associated with that
property is applied to the controller’s value. MAXScript also internally stores the last scaling
factor applied to the controller’s value. If you are directly accessing the value property of the
controller, or the value property of a key in the controller, the stored scaling factor is used. This
can result in a controller’s value property returning different values at different times in a
script, based on how the controller was last accessed. Because of this, it is highly recommended
that you do not instance a controller onto multiple MAXWrapper properties which have
different scaling factors. The scaling factor, if any, is listed for each MAXWrapper property in
the documentation of the MAXWrapper classes.
1292 Chapter 11 | 3ds max Objects

Methods:
displayControlDialog <controller> <string>
Displays the modal controller dialog, if any. The string will be in the dialog title bar. If the
controller is a keyframe controller, the key info dialog will be displayed for the selected
keys. If no keys are selected, no dialog will be displayed.
Controllers that can be keyframed support several time and key-related functions, as described in
the following topics:
Controller Time Functions (p. 1292)
Controller Key Functions (p. 1294)
Controller Out-Of-Range Functions (p. 1296)
Controller Ease and Multiplier Curve Functions (p. 1297)
Controller Key Reducer (p. 1299)

See also
Key Common Properties, Operators, and Methods (p. 768)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Controller Time Functions

supportsTimeOperations <ctrl>
returns true or false depending on whether the controller supports the following time
operations
deleteTime <controller> <interval> [ #incLeft ] [ #incRight ] [ #noSlide ]
Deletes an interval of time from the controller, removing all the keys with that interval
and, by default, sliding the keys to the right of the interval to the left by the width of the
interval. The optional symbolic arguments choose one of several options:
#incLeft: includes any key exactly at the start time of the interval
#incRight: includes any key exactly at the end time of the interval
#noSlide: doesn’t slide the later keys to fill in the gap removed- this effectively just
deletes any keys in the interval.
The <interval> argument can be specified as an Interval value or as two numbers or time
values defining the start and end times. Number values are taken as frame numbers.
reverseTime <controller> <interval> [ #incLeft ] [ #incRight ]
Reverses time in the given interval, essentially swapping keys around so that their time
placements are reversed within the interval. The notes on inclusion and interval
arguments from deleteTime() apply.
 Controller Time Functions 1293

scaleTime <controller> <interval> <float_scale>

Scales the times of the keys within the given interval. Again, the <interval> argument
can be specified as an Interval value or as two numbers or time values defining the start
and end times. Number values are taken as frame counts.
insertTime <controller> <at_time> <amount_time>
Inserts a block of time at the specified time, effectively moving all later keys out in time by
the amount inserted. The times can be numbers or Time values. Numbers are taken as
frame counts.
getTimeRange <controller> [ #selOnly ] [ #allKeys ] [ #children ]
Returns a time Interval value specifying the range of time covered by keys in the
controller. The optional symbolic arguments specify options:
#selOnly: return the time range covered by the currently selected keys (in the track view)
#allKeys (default): the time range for all keys in the controller
#children: descends into sub-controllers and returns the total time interval covering all
keys in all sub-controllers
setTimeRange <controller> [ <interval> ] [ #linkToKeys ]
Sets the time range to be an interval other than that covered by existing keys, typically to
influence when the out-of-range methods take over. If the optional #linkToKeys
argument is given any keys exactly at the start or end of the given interval become anchors
for the time range and moving them move the time range for the controller.
If you call setTimeRange() with just the single argument, #linkToKeys, it will set the
time range to the current start and end keys in all the controllers affected:
setTimeRange $box* #linkToKeys

This is equivalent to the Recouple Ranges function in the Position Ranges mode in
Track View.
Example:
The following script shows example usages of some of the above methods.
Script:
-- controller test bed 1
b=box height:10
at time 5 animate on b.height=50
at time 10 animate on b.height=100
bhc=b.height.controller
bhk=bhc.keys
supportstimeoperations bhc
deletetime bhc 4 5
bhk
deletetime bhc 4 5 #incLeft
bhk
deletetime bhc 1 4 #noslide
bhk
at time 5 animate on b.height=50
deletetime bhc (interval 5 8) #incLeft
1294 Chapter 11 | 3ds max Objects

bhk
at time 10 animate on b.height=150
for k in bhk do format “%:%\n” k.time k.value
reversetime bhc 5 15 #incLeft #incRight
for k in bhk do format “%:%\n” k.time k.value
insertTime bhc 12 5
bhk
getTimeRange bhc

Controller Key Functions

addNewKey <controller> <time> [ #select ]
Adds a new key to the controller track at the time specified. The value for the new key is
the interpolated controller value at the specified time. The new key is also selected if the
#select optional argument is specified. The value for the new key is the interpolated
controller value at that time. addNewKey() will not add a key if a key already exists at the
specified time. The return value in this case is the key located at the specified time.
This function returns a MAXKey value representing the key so you can set its various
properties. See the Controller Key Functions (p. 1294) topic for details.
deleteKeys <controller> [ #allKeys ] [ #selection ]
Deletes keys from the controller according to the optional symbolic argument supplied.
#allKeys (default): deletes all keys in the controller.
#selection: deletes the currently selected keys
deleteKey <controller> <index>
Deletes the indexed key. Key indexes are 1-based.
selectKeys <controller> [ <interval> | <time> ]
Selects the specified keys in the track view. If an interval is given, all the keys within the
interval are selected. If a single time is given, the key at that time is selected. If no time or
interval is given, select all keys.
deselectKeys <controller> [ <interval> | <time> ]
Deselects specified keys. Arguments are as described in selectKeys().
selectKey <controller> <index_integer>
Selects the indexed key. Key indexes are 1-based.
isKeySelected <controller> <index_integer>
Returns true if indexed key is selected, false otherwise. Key indexes are 1-based.
deselectKey <controller> <index_integer>
Deselects the indexed key. Key indexes are 1-based.
moveKeys <controller> <time> [ #selection ]
Moves the specified keys by the time given. If #selection is specified, move the current
selection otherwise move all keys.
moveKey <controller> <index_integer> <time>
Move the indexed key by the specified time.
 Controller Key Functions 1295

numKeys <controller>
Returns the number of keys in the controller. Returns -1 if you call it on a controller that
does not support keyframing.
getKey <controller> <index_integer>
Returns the indexed key as a MAXKey instance. See the Controller Key Functions (p. 1294)
topic for MAXKey class information.
getKeyTime <controller> <index_integer>
Returns the time of indexed key.
getKeyIndex <controller> <time>
Returns the index of the key at the specified time.
numSelKeys <controller>
Returns the number of keys currently selected in the track view.
sortKeys <controller>
Re-sorts keys according to their times. Some MAXKey operations can result in out of order
keys and this function must be called to correctly order keys. See the Controller Keys and
Key Properties topic for MAXKey properties information.
createLockKey <controller> <time> <rot_or_pos_integer>
This method is called to create a locking key at the specified time. This is a key that looks
back to the previous key and creates a new key at the specified time which matches the
previous key in value. It also adjusts the parameters for the key such that the value stays
constant from the previous key to this key. For instance, for a TCB controller the
continuity of the previous key and new key will set to 0. For a Bezier controller the out
tangent type of the previous key is set to linear and the in tangent type of the new key is
set to linear.
If the controller passed to this method is a transform level controller,
<rot_or_pos_integer> specifies whether to create the key in the transform controller’s
position or rotation (or roll angle) sub-controller. If rot_or_pos_integer = 0, the key is
created in the position controller. For all other values, the key is created in the rotation (or
roll angle) controller.
If the controller passed to this method is not a transform level controller, the
<rot_or_pos_integer> value is not used.
Returns true if the key creation was successful, false otherwise.
1296 Chapter 11 | 3ds max Objects

Example:
The following script shows example usages of some of the above methods.
Script:
-- controller test bed 2
b=box height:10
at time 5 animate on b.height=50
at time 10 animate on b.height=100
bhc=b.height.controller
bhk=bhc.keys
addnewkey bhc 7
addnewkey bhc 9
for k in bhk do format “%:%\n” k.time k.value
selectKeys bhc (interval 7 9)
deleteKeys bhc #selection
bhk
addnewkey bhc 7
addnewkey bhc 9
selectKeys bhc (interval 7 9)
deleteKeys bhc #selection #slide
bhk
addnewkey bhc 7
addnewkey bhc 9
selectKeys bhc (interval 7 9)
deleteKeys bhc #selection #slide #rightToLeft
bhk
addnewkey bhc 8
i=getKeyIndex bhc 8
selectKey bhc i
moveKey bhc i 10
bhk
getKeyTime bhc 4
b.width.controller=noise_float()
numkeys b.width.controller

Controller Out-Of-Range Functions

getBeforeORT <controller>
Gets the Out-of-Range type (ORT) for the controller for the time before the first key.
Returns one of the following name values:
#constant
#cycle
#loop
#pingPong
#linear
#relativeRepeat

getAfterORT <controller>
Gets the Out-of-Range (ORT) type for the controller for the time after the last key. Returns
one of the name values as for getBeforeORT() shown above.
 Controller Ease and Multiplier Curve Functions 1297

setBeforeORT <controller> <ORT_type_name>

Sets the Out-of-Range (ORT) type for the controller for the time before the first key. The
<ORT_type_name> must be one of the following name values:
#constant
#cycle
#loop
#pingPong
#linear
#relativeRepeat

setAfterORT <controller> <ORT_type_name>

Sets the Out-of-Range (ORT) type for the controller for the time after the last key. The
<ORT_type_name> must be one of the symbolic values shown in setBeforeORT() above.
No testing done on the validity of <ORT_type_name> is performed.
enableORTs <controller> <boolean>
Enables or disables the Out-of-Range processing for the controller. If set to disabled with
false, the controller effectively employs a constant ORT.

Controller Ease and Multiplier Curve Functions

addEaseCurve <controller> [ <float_controller> ]
Adds an ease curve to the specified controller. You may provide an optional float controller
for the curve or have the function generate a default float controller for you. When you
add a ease curve in Track View, keys are automatically created at the beginning and end of
the current animation range. The addEaseCurve() method does not generate these keys,
so you will need to add them to the ease curve controller.
deleteEaseCurve <controller> <index_integer>
Deletes the indexed ease curve from the controller. The indexes are 1-based and
correspond to the order in which the curves were originally added to the controller.
numEaseCurves <controller>
Returns the number of ease curves currently operating on the controller.
applyEaseCurve <controller> <time>
Applies the combined ease curves in the specified controller to the given time value,
returning the transformed time.
addMultiplierCurve <controller> [ <float_controller> ]
Adds a multiplier curve to the specified controller. You may provide an optional float
controller for the curve or have the function generate a default float controller for you.
When you add a ease curve in Track View, keys are automatically created at the beginning
and end of the current animation range. The addMultiplierCurve() method does not
generate these keys, so you will need to add them to the ease curve controller.
deleteMultiplierCurve <controller> <index_integer>
Deletes the indexed multiplier curve from the controller. The indexes are 1-based and
correspond to the order in which the curves were originally added to the controller.
1298 Chapter 11 | 3ds max Objects

numMultiplierCurves <controller>
Returns the number of multiplier curves currently operating on the controller.
getMultiplierValue <controller> <time>
Returns the combined (float) value of the multiplier curves in the specified controller at
the given time value.
Associated Properties:
If an Ease Curve has been assigned to a controller, the following controller-related sub-property is
available:
<controller>.Ease_Curve -- the controller’s ease curve value

If an Ease Curve has been assigned to a controller, the following controller-related sub-property is
available:
<controller>.Multiplier_Curve -- the controller’s multiplier curve value

Note:
The values stored in an Ease Curve controller are stored as integer time ticks.
Example:
The following script shows example usages of some of the above methods.
Script:
-- controller test bed 3
b=box height:10
at time 5 animate on b.height=50
at time 10 animate on b.height=100
bhc=b.height.controller
ec=bezier_float()
at time 0 animate on ec.value = 0
at time 100 animate on ec.value=100*ticksPerFrame
setBeforeORT ec #linear
setAfterORT ec #linear
addEaseCurve bhc ec
applyEaseCurve bhc 50
addEaseCurve bhc ec
numEaseCurves bhc
deleteEaseCurve bhc 2
numEaseCurves bhc
at time 50 bhc.ease_curve.value
mc=bezier_float()
at time 0 animate on mc.value = 1
at time 100 animate on mc.value = 2
addMultiplierCurve bhc mc
at time 50 bhc.multiplier_curve
 Controller Key Reducer 1299

Controller Key Reducer

reduceKeys <controller> <threshold> <step> [ <range> ]
where <threshold> is the closeness that the key-reduced controller will match the
original keys, <step> is the time step at which the controller will be sampled and
<range> is an optional time range within which the keys are reduced given as either 2
time values or an Interval value, defaulting to the active animation range.
Examples:
reduceKeys $foo.pos.controller 0.5 1f
reduce keys on foo’s position, retain 0.5 units accuracy, sample every frame.
reduceKeys $baz.bend.angle.controller 0.1 0.5f (interval 20 75)
Reduce keys on baz’s bend angle, retain 0.1 units accuracy, sample every half frame, reduce
within the interval 20f to 75f.
As with the reducer in the track view, a progress bar and cancel button is displayed.

Time and Key Functions on Object Hierarchies

Certain of the controller time and key functions can be called on any 3ds max object or collection
of 3ds max objects, not just individual controllers. If called in this way, they apply recursively to all
the nested controllers within those objects and on any on sub-objects and sub-controllers within
those objects. In this way, they work in a manner similar to the object-level tracks in the 3ds max
Track View that allow you to manipulate keys and time for all the sub-objects and sub-controllers
within them.
The time and controller functions that work this way are:
deleteTime
reverseTime
scaleTime
insertTime
setTimeRange

addNewKey
deleteKeys
selectKeys
deselectKeys
moveKeys
sortKeys
reduceKeys

addEaseCurve
deleteEaseCurve
setBeforeORT
setAfterORT
enableORTs
1300 Chapter 11 | 3ds max Objects

The above functions can be called on any 3ds max object collection (such as a wild-card pathname
or object set or array of objects ) and will recursively apply to all animation within those objects. If
they are called on components within an object that themselves have nested controllers, they are
applied to all those nested controllers - see the examples below.
Examples:
insertTime $box01.xform 0f 10f
all keys after 0f in all controllers in the xform modifier are moved by 10f
insertTime $box01 0f 10f
all keys after 0f in box01 are moved (transform, creation, modifiers)
selectKeys $box02.xform.gizmo.rotation.controller 0f 100f
selects keys in 0-100f, if controller is Euler, e.g., will select x, y and z keys
deleteTime $box* 10f 10f
delete 10f at frame 10 in all keys in all objects named $box* (works with any pathname or
array of objects)
insertTime $box03.children 0f 10f
inserts time in all controllers of all children of $box03
reduceKeys $box01.modifiers 0.5 1f
applies key reductions to all controllers in all modifiers in $box01 (leaves transform and
creation parameters alone)

Controller Types

Controllers - Superclass Level

The following is a list of the controller superclasses:
FloatController (p. 1301)
Matrix3Controller (p. 1302)
MorphController (p. 1302)
Point3Controller (p. 1302)
PositionController (p. 1303)
RotationController (p. 1303)
ScaleController (p. 1304)
QuatController (p. 1304)
MasterBlockController (p. 1301)
 FloatController : MAXWrapper 1301

FloatController : MAXWrapper
FloatController is the superclass for all controllers that can be assigned to parameters that are
simple numbers (Float or Integer). The following is a list of the core FloatController classes
accessible in MAXScript:
AudioFloat (p. 1306)
Bezier_Float (p. 1309)
Block (p. 1311)
Float_Expression (p. 1313)
Float_List (p. 1317)
Float_Motion_Capture (p. 1321)
Float_Reactor (p. 1326)
Float_Script (p. 1329)
Linear_Float (p. 1315)
LOD_Controller (p. 1319)
Noise_Float (p. 1322)
On_Off (p. 1323)
SlaveFloat (p. 1333)
TCB_Float (p. 1334)
Waveform_Float (p. 1335)

MasterBlockController : MAXWrapper
MasterBlockController is the superclass for the controllers associated with the Block Control
Track View node. These classes are:
Block_Control (p. 1311)
MasterBlock (p. 1320)
1302 Chapter 11 | 3ds max Objects

Matrix3Controller : MAXWrapper
Matrix3Controller is the superclass for all controllers that can be assigned to transform or
Position-Rotation-Scale parameters. The following is a list of the core Matrix3Controller classes
accessible in MAXScript:
Link_Control (p. 1316)
LookAt (p. 1319)
PRS (p. 1325)
IK_ControllerMatrix3Controller (p. 1313)
Slave_Controller (p. 1333)

MorphController : MAXWrapper
MorphController is the superclass for all controllers that can be assigned to morph objects. The
following is a list of the core MorphController classes accessible in MAXScript:
Barycentric_Morph_Controller (p. 1306)
Cubic_Morph_Controller (p. 1312)

Point3Controller : MAXWrapper
Point3Controller is the superclass for all controllers that can be assigned to Point3 parameters.
The following is a list of the core Point3Controller classes accessible in MAXScript:
AudioPoint3 (p. 1306)
Bezier_Color (p. 1309)
Bezier_Point3 (p. 1309)
Color_RGB (p. 1335)
Noise_Point3 (p. 1322)
Point3_Expression (p. 1313)
Point3_List (p. 1317)
Point3_Motion_Capture (p. 1321)
Point3_Reactor (p. 1326)
Point3_Script (p. 1329)
Point3_XYZ (p. 1335)
Slave_Point3 (p. 1333)
TCB_Point3 (p. 1334)
 PositionController : MAXWrapper 1303

PositionController : MAXWrapper
PositionController is the superclass for all controllers that can be assigned to position
parameters. The following is a list of the core Point3Controller classes accessible in MAXScript:
Attachment (p. 1304)
Audioposition (p. 1306)
Bezier_Position (p. 1309)
Dynamic_Position_Controller (p. 1312)
Linear_Position (p. 1315)
Noise_Position (p. 1322)
Path (p. 1324)
Position_Expression (p. 1313)
Position_List (p. 1317)
Position_Motion_Capture (p. 1321)
Position_Reactor (p. 1326)
Position_Script (p. 1329)
Position_XYZ (p. 1335)
Surfaceposition (p. 1334)
TCB_Position (p. 1334)

RotationController : MAXWrapper
RotationController is the superclass for all controllers that can be assigned to rotation
parameters. The following is a list of the core RotationController classes accessible in
MAXScript:
AudioRotation (p. 1306)
Bezier_Rotation (p. 1309)
Dynamics_Rotation_Controller (p. 1312)
Euler_XYZ (p. 1335)
Linear_Rotation (p. 1315)
Local_Euler_XYZ (p. 1335)
Noise_Rotation (p. 1322)
Rotation_List (p. 1317)
1304 Chapter 11 | 3ds max Objects

Rotation_Motion_Capture (p. 1321)

Rotation_Reactor (p. 1326)
Rotation_Script (p. 1329)
SlaveRotation (p. 1333)
TCB_Rotation (p. 1334)

ScaleController : MAXWrapper
ScaleController is the superclass for all controllers that can be assigned to scale parameters. The
following is a list of the core ScaleController classes accessible in MAXScript:
AudioScale (p. 1306)
Bezier_Scale (p. 1309)
Linear_Scale (p. 1315)
Noise_Scale (p. 1322)
Scale_Expression (p. 1313)
Scale_List (p. 1317)
Scale_Motion_Capture (p. 1321)
Scale_Reactor (p. 1326)
Scale_Script (p. 1329)
ScaleXYZ (p. 1335)
SlaveScale (p. 1333)
TCB_Scale (p. 1334)

QuatController : MAXWrapper
There are presently no classes associated with the QuatController superclass.

Attachment : PositionController
Constructor:
attachment ...

Properties:
<attachment>.keys : MAXKeyArray
<attachment>.node : Node
<attachment>.align : Booleandefault: true
Fixes the orientation of the attached object to the face where it’s assigned. When this is
turned off, the orientation of the attached object is not affected by the orientation of the
face on the target object.
 Attachment Controller Keys 1305

<attachment>.manupdate : Booleandefault: false

Enables the update button.
Methods:
AttachCtrl.getKey <attachment> <index_integer>
Returns the indexed key as a MAXAKey value
AttachCtrl.addNewKey <attachment> <time>
Returns the indexed key as a MAXAKey value
AttachCtrl.update <attachment>
Causes the controller to update if the manual update property is turned on for the
attachment controller.
Note:
Accessing a key for these controllers by indexing into the .keys property will return a MAXKey
value. The only properties available for a key accessed in this manner are the .time and .selected
properties. The AttachCtrl.getKey() method returns a key of class MAXAKey, which provides
access to the attachment controller key specific properties. All the common key functions like
deleteKey, selectKeys, movekeys, etc. can be used with Attachment controllers.

See also
MAXKeyArray Values (p. 793)
Attachment Controller Keys (p. 1305)
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Attachment Controller Keys

Properties:
For Attachment controller keys, the following properties are accessible:
<key>.time : Time (time value or number [interpreted as frames]) Read-only.
<key>.selected : Boolean
Specifies whether the key is selected. Read/write access.
The AttachCtrl.getKey() method returns keys of class MAXAKey. These keys have the following
properties:
<MAXAKey>.face : Integer (0-based)
<MAXAKey>.coord : Point2 (barycentric coordinates)
<MAXAKey>.time : Time
<MAXAKey>.selected : Boolean
<MAXAKey>.tension : Float
<MAXAKey>.continuity : Float
<MAXAKey>.bias : Float
<MAXAKey>.easeTo : Float
<MAXAKey>.easeFrom : Float
1306 Chapter 11 | 3ds max Objects

See also
Key Common Properties, Operators, and Methods (p. 768)
Value Common Properties, Operators, and Methods (p. 714)

Audio Controllers
audiofloat : floatController
audiopoint3 : point3Controller
audioposition : positionController
audiorotation : rotationController
audioscale : scaleController
Constructor:
audiofloat ...
audiopoint3 ...
audioposition ...
audiorotation ...
audioscale ...

Properties:
There are no additional properties accessible for Audio controllers.

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Barycentric_Morph_Controller : MorphController
You access the morph controller on a morph compound object via the <node>.morph property, for
example:
c = $foo.morph -- get the morph controller
mk1 = c.keys[1] -- get the first morph key

Constructor:
createMorphObject <source_node>
Turns the given scene node into a Morph compound object - does nothing if it already is a
Morph object. The returned morph object has a morph controller created accessible via
the morph property.
 Barycentric_Morph_Controller : MorphController 1307

Methods:
addMorphTarget <morph_controller> <target_node> <add_method>
Adds a new morph target object to the given morph controller. The <add_method>
argument defines the method of attaching the target and should be a number between 1
and 4 with the following interpretation:
1 -- by reference
2 -- by copy
3 -- by move
4 -- by instance

The return value is an Integer giving the target index of the added target object.
setMorphTarget <morph_controller> <target_index_integer> <target_node>
<add_method>
Replaces an existing target with a different scene node. The arguments are the same as for
addMorphTarget().
getMKTargetNames <morph_controller>
Returns an array of names of the targets in the given morph controller.
deleteMorphTarget <morph_controller> <target_index_integer>
Deletes the numbered morph target in the given controller.
setMorphTargetName <morph_controller> <target_index_integer> <name_string>
Changes the target name of the numbered target in the given morph controller.
getMKTargetWeights <morph_controller> <time> <dest_array>
A quick way of retrieving all the target weights for a given key at the time specified. The
targets are placed into <dest_array> which must be an array of the right size. You can
find out how many targets there by getting the size of the array returned by the
getMKTargetNames() function which returns an array of target names.
getMKKey <morph_controller> <time>
Returns the morph key on the given controller at the specified time, yields undefined if
there is no key at that time.
getMKKeyIndex <morph_controller> <time>
Returns the index of the key at the specified time, yields undefined if there is no key at
that time.
Note:
When using the addnewkey() method to create a key for the Barycentric_Morph_Controller
controller, the time component of the key value returned is usually not correct. Use the getMKKey()
method to access the created key.
1308 Chapter 11 | 3ds max Objects

See also
Barycentric_Morph_Controller Keys (p. 1308)
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Barycentric_Morph_Controller Keys
Note: This class is not available in 3D Studio VIZ.
The morph key functions operate on MAXScript key values that are accessed on Barycentric morph
controllers in the same way as keys on other keyable controllers. For Barycentric_Morph_Controller
keys, the following properties and methods are accessible:
Properties:
<key>.time Time -- time value or number (interpreted as frames). Read-
only.
<key>.selected Boolean -- specifies whether the key is selected. Read/write
access.

Methods:
getMKTime <morph_key>
Returns the given morph key’s time.
setMKTime <morph_key> <time>
Sets the time of the given morph key.
getMKWeight <morph_key> <target_index_integer>
Gets the weight as a percentage for the numbered target on the given morph key. Targets
are numbered in order as seen in the target list in the morph key Track View dialog. This is
the order in which the targets were added.
setMKWeight <morph_key> <target_index_integer> <pcnt_float> <keep100%_boolean>
Sets the percentage weight of the numbered target on the given morph key. The last
argument is a boolean, if true adjusts other target weights so the maximum is 100%.
Note:
When using the addnewkey() method to create a key for the Barycentric_Morph_Controller
controller, the time component of the key value returned is usually not correct. Use the getMKKey()
method to access the created key.

See also
Key Common Properties, Operators, and Methods (p. 768)
Value Common Properties, Operators, and Methods (p. 714)
 Bezier Controllers 1309

Example:
Script:
sel1 = sphere radius:30 -- target 1
sel2 = sphere radius:50 -- target 2
createMorphObject sel1 -- create the morph object from sel1
mobj1= sel1.morph -- grab morph controller
addmorphtarget mobj1 sel2 3 -- add sel2 as target - creates key with
-- target weights of 0 and 100%
k=mobj1.keys[1] -- grab the key
setMKWeight k 1 100 true -- set target 1 to 100%, keep total 100%
addnewkey mobj1 50 -- create morph key at frame 50
k=getMKKey mobj1 50 -- grab the key
setMKWeight k 2 100 true -- set target 2 to 100%, keep total 100%

Output:
$Sphere:Sphere01 @ [0.0,0.0,0.0] -- result line 1
$Sphere:Sphere02 @ [0.0,0.0,0.0] -- result line 2
$Editable_Mesh:Sphere01 @ [0.0,0.0,0.0] -- result line 3
Controller:Barycentric_Morph_Controller -- result line 4
2 -- result line 5
#Barycentric Morph Controller key(1 @ 0f) -- result line 7
1 -- result line 8
#Barycentric Morph Controller key(0 @ 50f) -- result line 9
#Barycentric Morph Controller key(2 @ 50f) -- result line 10
2

Bezier Controllers
bezier_color : point3Controller
bezier_float : floatController
bezier_point3 : point3Controller
bezier_position : positionController
bezier_rotation : rotationController
bezier_scale : scaleController
Constructor:
bezier_color ...
bezier_float ...
bezier_point3 ...
bezier_position ...
bezier_rotation ...
bezier_scale ...

Properties:
<bezier_controller>.keys MAXKeyArray
1310 Chapter 11 | 3ds max Objects

See also
MAXKeyArray Values (p. 793)
Bezier Controller Keys (p. 1310)
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Bezier Controller Keys

For Bezier controller keys, the following properties are accessible:
Properties:
<key>.time Time -- time value or number (interpreted as frames)
<key>.selected Boolean -- specifies whether the key is selected
<key>.value varies -- class determined by its containing controller
<key>.inTangent varies -- float or point3 (see below)
<key>.outTangent varies -- float or point3 (see below)
<key>.inTangentType Name -- see list of permitted names below
<key>.outTangentType Name -- see list of permitted names below
<key>.x_locked Boolean default: true
<key>.y_locked Boolean default: true
<key>.z_locked Boolean default: true
<key>.constantVelocity Boolean default: false

The inTangent and outTangent values are Floats in keys of float controllers and Point3s for the
other appropriate controllers. Default value is 0 for float controllers, [0,0,0] otherwise.
The inTangentType and outTangentType properties have symbolic name values representing
the 6 possible tangent types available in the drop-down menu in the Bezier key property dialog:
#smooth (default)
#linear
#step
#fast
#slow
#custom

See also
Key Common Properties, Operators, and Methods (p. 768)
Value Common Properties, Operators, and Methods (p. 714)
 Block : FloatController 1311

Examples:
c = bezier_position () -- create and assign new controller
$bar.pos.controller = c

k = addNewKey c 0f -- add a key at frame 0

k.value = [10,0,0] -- set value there
k.outTangentType = #slow -- and outgoing tangent type

k = addNewKey c 100f -- add another key at 100

k.value = [200,10,0] -- set value
k.inTangentType = #custom -- make inTangent custom
k.inTangent = [0.2, 0.02, 0.112] -- set its tangents
k.x_locked = false -- and unlock handles

Block : FloatController
Constructor:
The Block controller is not creatable by MAXScript. It can only be created by creating a Masterblock
in the Block Control node in the Global Tracks node of Track View. See the MasterBlock :
MasterBlockController (p. 1320) topic for more information.

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Block_Control : MasterBlockController
Constructor:
The Block_Control controller is not creatable by MAXScript. Only one instance of the class
exists in 3ds max - the Block Control node in the Global Tracks node of Track View. See the
MasterBlock : MasterBlockController (p. 1320) topic for more information.

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1312 Chapter 11 | 3ds max Objects

Cubic_Morph_Controller : MorphController
The Barycentric_Morph_Controller (p. 1306) should be used instead of a Cubic_Morph_Controller
controller.
Constructor:
Cubic_Morph_Controller ...

Note: This class is not available in 3D Studio VIZ.

Properties:
<Cubic_Morph_Controller>.keys MAXKeyArray

See also
MAXKeyArray Values (p. 793)
Cubic_Morph_Controller Keys (p. 1312)
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Cubic_Morph_Controller Keys
Properties:
For Cubic_Morph_Controller keys, the following properties are accessible:
<key>.time Time -- time value or number (interpreted as frames). Read-
only.
<key>.selected Boolean -- specifies whether the key is selected. Read/write
access.

See also
Key Common Properties, Operators, and Methods (p. 768)
Value Common Properties, Operators, and Methods (p. 714)

Dynamics Controllers
Dynamics_Position_Controller : positionController
Dynamics_Rotation_Controller : rotationController
Constructor:
The Dynamics controllers are created by the Dynamics utility, and are not creatable in
MAXScript.
Note: These classes are not available in 3D Studio VIZ.
 Expression Controllers 1313

Properties:
When you solve a dynamics solution in the Dynamics utility, the Dynamics controllers are assigned
as the position and rotation controllers of all objects not flagged as unyielding. These controllers are
similar to List controllers in that they contain multiple sub-controllers. The first sub-controller is a
Bezier controller of the appropriate type that contains the keys generated while solving the
dynamics solution. This controller can be accessed as the Dynamic_position_controller or
Dynamic_rotation_controller property of the dynamics controller. The second sub-controller
is the original position or rotation controller assigned to the object, and can be accessed as the
old_position or old_position property.

Expression Controllers
float_expression : floatController
point3_expression : point3Controller
position_expression : positionController
scale_expression : scaleController
Constructor:
float_expression ...
point3_expression ...
position_expression ...
scale_expression ...

Note: These classes are not available in 3D Studio VIZ.

Properties:
There are no additional properties accessible for Expression controllers.

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

IK_ControllerMatrix3Controller : Matrix3Controller
The functions described in this topic provide access to some of the Inverse Kinematics (IK)
parameters of the IK controller. The IK controller is typically used by the Bones system in 3ds max.
You cannot create a Bones system using MAXScript in 3ds max 3, but these methods provide access
to the IK controller for existing Bones systems. An IK system actually consists of two types of
controllers – the master IK controller and slave IK controllers. The slave IK controllers are used as the
transform controller for all nodes in the IK system, and the master IK controller controls the
individual slave IK controllers.
1314 Chapter 11 | 3ds max Objects

All the IK-related methods are in the ik structure and are associated with a parameter in the Motion
panel, IK Controller Parameters rollout. These functions return undefined if executed on an object
whose controller is not an IK controller. The controller actually being accessed in these methods is
the master IK controller. Accessing the IK controller for any object in the IK system accesses the same
master IK controller.
Note:
The following ik structure methods are still present, but not applicable in 3ds max 4.
Getting/setting via these methods return a value of ‘undefined’:
GetRotThreshold
SetRotThreshold
GetPosThreshold
SetPosThreshold
GetIterations
SetIterations

ik.GetPosThreshold <node>
ik.SetPosThreshold <node> <float>
Get and set the Position threshold value for the specified object.
ik.GetRotThreshold <node>
ik.SetPosThreshold <node> <float>
Get and set the Rotation threshold value for the specified object.
ik.GetIterations <node>
ik.SetIterations <node> <integer>
Get and set the Iterations value for the specified object.
ik.GetStartTime <node>
ik.SetStartTime <node> <time>
Get and set the Start time for the specified object
ik.GetEndTime <node>
ik.SetEndTime <node> <time>
Get and set the End time for the specified object
ik.getPinNode <node>
Gets the node the specified node is bound to in the IK panel as a <node> value, undefined
if none.
ik.setPinNode <node> (<node> | undefined)
Sets the node the specified node is bound to in the IK panel. If undefined is specified, the
node is unbound. Returns true if the bind was successful, false otherwise.
ik.getPrecedence <node>
Gets the precedence of the node as specified in the IK panel as an <integer> value
ik.setPrecedence <node> <number>
Sets the precedence of the node as specified in the IK panel. Returns true if the assignment
was successful, false otherwise.
ik.getIsTerminator <node>
ik.setIsTerminator <node> <boolean>
Get/set whether the node is a terminator.
 Linear Controllers 1315

ik.getBindPos <node>
ik.setBindPos <node> <boolean>
Get/set whether Bind Position is turned on for the node.
ik.getBindOrient <node>
ik.setBindOrient <node> <boolean>
Get/set whether Bind Orientation is turned on for the node.

Linear Controllers
linear_float : floatController
linear_position : positionController
linear_rotation : rotationController
linear_scale : scaleController
Constructor:
linear_float ...
linear_position ...
linear_rotation ...
linear_scale ...

Properties:
<controller>.keys MAXKeyArray

See also
MAXKeyArray Values (p. 793)
Linear Controller Keys (p. 1315)
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Linear Controller Keys

For Linear controller keys, the following properties are accessible:
Properties:
<key>.time Time -- time value or number (interpreted as frames)
<key>.selected Boolean -- specifies whether the key is selected
<key>.value varies -- class determined by its containing controller

See also
Key Common Properties, Operators, and Methods (p. 768)
Value Common Properties, Operators, and Methods (p. 714)
1316 Chapter 11 | 3ds max Objects

Link_Control : Matrix3Controller
Constructor:
link_control ...

Properties:
<link_control>.transform Matrix3Controller
Contains the transform controller below the link controller
Methods:
linkCtrl.getLinkCount <link_control>
Returns the number of nodes linked to as an integer.
linkCtrl.getLinkNode <link_control> <index_integer>
Returns the node for the indexed link as a node value.
linkCtrl.setLinkNode <link_control> <index_integer> <node>
Sets the node for the indexed link. The indexed link must already exist.
linkCtrl.getLinkTime <link_control> <index_integer>
Returns the time for the indexed link as a time value.
linkCtrl.setLinkTime <link_control> <index_integer> <time>
Sets the time for the indexed link. The indexed link must already exist.
linkCtrl.addLink <link_control> <node> <time>
Adds the specified node as a link with the specified time.
linkCtrl.deleteLink <link_control> <index_integer>
Deletes the indexed link.

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 List Controllers 1317

List Controllers
float_list : floatController
point3_list : point3Controller
position_list : positionController
rotation_list : rotationController
scale_list : scaleController
Constructor:
float_list ...
point3_list ...
position_list ...
rotation_list ...
scale_list ...

Properties:
The property list for a list controller contains the sub-controllers in the list controller (if any), plus
an available property. The available property has a controller property, which contains a
“phantom” controller. To add a controller to a list controller, assign the controller to the
available.controller property. The following script shows an example of creating and adding
controllers to a list controller.
Script:
p=float_list() -- create a list controller
showproperties p -- show its properties
p.available.controller -- the “phantom” controller
p1=bezier_float() -- create a new bezier float controller
p.available.controller=p1 -- add it to the list controller
p2=bezier_float() -- create a new bezier float controller
p.available.controller=p2 -- add it to the list controller
getpropnames p -- show the list controller properties
showproperties p -- show the list controller properties
p.numSubs -- the number of list controller subAnims
getsubanimnames p -- show the list controller subAnim names
p[2].object -- retrieve the second bezier float controller

Output:
Controller:Float_List -- result line 1
.available : float -- output line 2
OK -- result line 2
Controller: -- result line 3 (the “phantom” controller)
Controller:Bezier_Float -- result line 4
Controller:Bezier_Float -- result line 5
Controller:Bezier_Float -- result line 6
Controller:Bezier_Float -- result line 7
#(#bezier_float, #available) -- result line 8
.bezier_float : float -- output line 9
.bezier_float : float -- output line 9
.available : float -- output line 9
1318 Chapter 11 | 3ds max Objects

OK -- result line 9
3 -- result line 10
#(#bezier_float, #bezier_float, #available) -- result line 11
Controller:Bezier_Float -- result line 12

In line 9 of the output, only one occurrence of #bezier_float is shown. The reason for this is this
is that multiple properties with the same name are not shown by MAXScript. This is because all
property names are normally supposed to be unique. In the case of list controllers, this is not true.
Instead of accessing the controllers added to a list controller as properties of the list controller, the
controllers should be accessed through the subAnims of the list controller as shown in the last line
of the example.
There currently is not a method for removing a controller from a list controller. To easiest way to
accomplish this is to create a new list controller, instance all other sub-controllers from the original
list controller, and then replace the original list controller with the new list controller. The following
script shows a example which performs these actions.
Script:
-- creates new list controller from old, deleting indexed controller
-- returns the new controller
fn deleteFromListController list_cont index =
(
-- create new list controller based on class of input list controller
new_cont=execute ((classof list_cont as string) + “()”)
-- for each subAnim (except the last, which is the phantom “available”
-- controller)..
for i=1 to (list_cont.numSubs-1) do
-- if not the sub-controller to delete
if i != index do
-- instance the sub-controller (contained in the .object property of
-- the subAnim) to the new list controller
new_cont.available.controller=list_cont[i].object
-- and return the new list controller
return new_cont
)
--
-- example usage (obj.pos already has list controller)
obj.pos.controller = deleteFromListController obj.pos.controller 2

Methods:
listCtrl.getName <list_controller> <index_integer>
Returns the name of the indexed subcontroller in the list controller
listCtrl.setName <list_controller> <index_integer> <string>
Sets the name of the indexed subcontroller in the list controller. If the string is a null string
(”“), the default controller name is used.
 LOD_Controller : FloatController 1319

listCtrl.getActive <list_controller>
Returns the index of the active subcontroller in the list controller
listCtrl.setActive <list_controller> <index_integer>
Sets the indexed subcontroller in the list controller as the active controller

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

LOD_Controller : FloatController
Constructor:
The LOD_Controller controller is not creatable by MAXScript. It can only be created using the
Level of Detail utility.
Properties:
There are no additional properties for LOD_Controller.

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

LookAt : Matrix3Controller
Constructor:
lookat ...

Properties:
<lookAt>.position Bezier_Position -- the position controller
<lookAt>.roll_angle Bezier_Float -- the roll controller
<lookAt>.scale Bezier_Scale -- the scale controller
1320 Chapter 11 | 3ds max Objects

There presently are no methods for directly accessing or setting the target node in the LookAt
controller. To set the target node, the LookAt controller needs to be assigned to a node, and then the
lookat property of the node is set to the target node. If the transform controller for a node is not a
LookAt controller, and a target node is assigned to the lookat property of the node, a LookAt
controller is automatically assigned to the node. For example,
$box01.lookat=$box02

is equivalent to
$box01.transform.controller=lookat()
$box01.lookat=$box02

Note:
The following properties are not accessible by MAXScript in 3ds max 4 the Axis radio-button and
the Flip checkbox.

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

MasterBlock : MasterBlockController
Constructor:
The MasterBlock controller is not creatable by MAXScript. It can only be created in the Block
Control node in the Global Tracks node of Track View. If multiple MasterBlocks are present, you
will need to access the MasterBlocks as a subAnim of trackviewnodes.global_tracks.
block_control. This is because all MasterBlocks have the same name (MasterBlock).
Properties:
Once a MasterBlock has been created in Track View, the following MasterBlock property is
available:
<MasterBlock>.blend Float

Once a track has been added to the MasterBlock, a Block controller is added to the MasterBlock,
and the track’s controller is added as an input controller to the Block controller. The name
assigned to the Block controller is the name specified for the block. The Block controller is then
available as a property of the MasterBlock, and the track’s controller is available as a property of
the Block controller. In addition, the track’s controller is replaced with a list controller and the
track’s original controller is placed in the list controller along with a Slave controller. This Slave
controller is controlled by the Block controller. For example, if a block with name “BoxHeight”
is present, and contains the height controller for a box object, the block and its track can be
accessed as follows:
 Motion Capture Controllers 1321

mb=trackviewnodes.global_tracks.block_control[1] -- SubAnim:MasterBlock
getpropnames mb -- #(#Blend, #height)
h=mb.height -- SubAnim:height
h.object -- Controller:Block
getpropnames h -- #(#Box01_Height)
h.box01_height -- 157.083 - the box’s height
h.box01_height.controller -- Controller:Bezier_Float - the box’s height controller

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Motion Capture Controllers

float_motion_capture : floatController
point3_motion_capture : point3Controller
position_motion_capture : positionController
rotation_motion_capture : rotationController
scale_motion_capture : scaleController
Constructor:
float_motion_capture ...
point3_motion_capture ...
position_motion_capture ...
rotation_motion_capture ...
scale_motion_capture ...

Note: These classes are not available in 3D Studio VIZ.

Properties:
<motion_capture>.data Controller
The data controller type depends on the motion controller data type. The controller is
typically a Bezier controller.
There are presently no properties or methods associated with the motion capture controllers
themselves.

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1322 Chapter 11 | 3ds max Objects

Noise Controllers
noise_float : floatController
noise_point3 : point3Controller
noise_position : positionController
noise_rotation : rotationController
noise_scale : scaleController
Constructor:
noise_float ...
noise_point3 ...
noise_position ...
noise_rotation ...
noise_scale ...
Properties:
Access to the following properties is available on all noise controllers:
<noise_controller>.seed Integer default: 0
<noise_controller>.frequency Float default: 0.5
<noise_controller>.fractal Boolean default: true
<noise_controller>.roughness Float default: 0.0
<noise_controller>.rampin Time default: 0f
<noise_controller>.rampout Time default: 0f

In addition, for noise float controllers you can get these properties:
<noise_controller>.noise_strength Float default: 50 -- animatable
<noise_controller>.positive Boolean default: false
limits values to > 0
and for noise position, point3, rotation and scale controllers:
<noise_controller>.noise_strength Point3 default: varies -- animatable
position and point3 default: [50,50,50]
rotation default: [0.785398,0.785398,0.785398]
scale default: [0.5,0.5,0.5]

<noise_controller>.x_positive Boolean default: false

<noise_controller>.y_positive Boolean default: false
<noise_controller>.z_positive Boolean default: false
limits values to > 0
 On_Off : FloatController 1323

Note:
You need to access these properties explicitly on a controller, for example:
$box01.position.controller.x_strength = 100

or,
c = $box01.rotation.controller
c.seed = random 0 100
c.fractal = off
c.frequency = random 0.1 0.2

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

On_Off : FloatController
Constructor:
on_off ...

Properties:
<on_off>.keys MAXKeyArray

See also
MAXKeyArray Values (p. 793)
On_Off Controller Keys (p. 1323)
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

On_Off Controller Keys

Properties:
For On_Off keys, the following properties are accessible:
<key>.time Time -- time value or number (interpreted as frames). Read-
only.
<key>.selected Boolean -- specifies whether the key is selected. Read/write
access.
1324 Chapter 11 | 3ds max Objects

See also
Key Common Properties, Operators, and Methods (p. 768)
Value Common Properties, Operators, and Methods (p. 714)

Path : PositionController
Constructor:
path ...

Properties:
<path>.allowUpsideDown Boolean default: false -- alias: Allow_Upside_Down
Turn on to avoid the situation in which an object flips when going around a vertically
oriented path.
<path>.axis Integer default: 0
axis = 0 - X; 1 - Y; 2 - Z
<path>.axisFlip Boolean default: false -- alias: Axis_Flip
Flips the direction of the object on the path 180 degrees.
<path>.bank Boolean default: false
Allows the object to bank (roll) as it negotiates the curves of the spline.
<path>.bankAmount Float default: 0.5 -- animatable, alias:
Bank_Amount
The amount of the banking to one side or the other, depending on whether the value is
positive or negative.
<path>.constantVel Boolean default: false -- alias: Constant_Velocity
Provides a constant velocity along the path. When off, the velocity of the object along the
path varies depending on the distance between the vertices on the path.
<path>.follow Booleandefault: false
Aligns the object to the trajectory as it follows the contour.
<path>.loop Boolean default: false -- boolean
When turned on, the path controlled object will loop back to the start point of the path,
after the end point is reached.
<path>.path Node default: undefined -– node; Path_Constraint
The spline in the scene that you want the selected object to follow.
<path>.pathlist Array default: #() -- node array; SubAnim
The object will follow the resultant path which is the weighted average of the paths in this
array. The weight for each path is found in the corresponding entry in
<path>.weightlist.
<path>.percent Floatdefault: 0.0 -- animatable, percentage
The percent that the object is positioned along the path.
<path>.relative Boolean default: false -- booleanExample
When turned on, the path controlled object will maintain the position offset between its
initial position and the start point of the path.
 PRS : Matrix3Controller 1325

<path>.smoothness Float default: 0.5 -- animatable

Controls how rapidly the roll angle changes as the object moves through bends in the
trajectory. Smaller values will make the object more responsive to subtle changes in the
curve, while larger values smooth out jerking. The default value is a good value for general
damping along the curve. Values below 2 tend to make the action jerky, but values around
3 can be very useful for simulating a certain degree of realistic instability.
<path>.weightlist Array default: #() -- float array; Weight; SubAnim
Array containing weights corresponding to entries in the <path>.pathlist array. The
object will follow the resultant path which is the weighted average of the selected paths.
The following script shows an example of assigning and animating a path controller.
Script:
thePath=circle radius:50 -- create shape node for path
theObj=cone radius1:6 radius2:0 height:15 -- create object to travel on path
theObj.pos.controller=path follow:true -- assign path controller to object
PosCont=theObj.pos.controller -- grab the path controller
PosCont.path=thePath -- set path to shape node
PosCont.axis=2 -- point local Z axis along path
animate on -- create keys at…
( at time 30 PosCont.percent=25 -- frame 30 - 25% along path
at time 100 PosCont.percent=95 -- frame 100 - 95% along path
)

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

PRS : Matrix3Controller
Constructor:
prs ...

Properties:
<prs>.position Bezier_Position -- the position controller
<prs>.rotation TCB_Rotation -- the rotation controller
<prs>.scale Bezier_Scale -- the scale controller

Note:
You can assign a Matrix3 value to a PRS controller’s value property. MAXScript will automatically
set the individual position, rotation, and scale values to the values represented in the Matrix3 value.
1326 Chapter 11 | 3ds max Objects

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Reactor Controllers
float_Reactor : floatController
point3_Reactor : point3Controller
position_Reactor : positionController
rotation_Reactor : rotationController
scale_Reactor : scaleController
Constructor:
float_Reactor ...
point3_Reactor ...
position_Reactor ...
rotation_Reactor ...
scale_Reactor ...

Methods:
createReaction <reactor_controller>
Creates a new reaction for the specified reactor controller.
deleteReaction <reactor_controller> <index_integer>
Deletes the specified reaction. <index_integer> is the reaction you want to delete. The
order of reactions is the order in which they are created, and the order in which the
reactions are listed in the Reactor Parameters dialog.
reactTo <reactor_controller> ( <controller> | <node> )
Sets the controller that the reactor controller reacts to. You can either specify either a
controller you want to react to or a node whose world position to react to.
getReactionCount <reactor_controller>
Returns the number of reactions for the specified reactor controller.
selectReaction <reactor_controller> <index_integer>
Selects the specified reaction. <index_integer> is the reaction you want to select. The
order of reactions is the order in which they are created, and the order in which the
reactions are listed in the Reactor Parameters dialog.
getSelectedReactionNum <reactor_controller>
Returns the number of the selected reaction.
getReactionFalloff <reactor_controller> <index_integer>
Returns the specified reaction’s falloff. <index_integer> is the reaction you want to get
the falloff from. The order of reactions is the order in which they are created, and the order
in which the reactions are listed in the Reactor Parameters dialog.
 Reactor Controllers 1327

setReactionFalloff <reactor_controller> <index_integer> <float>

Sets the specified reaction’s falloff to the specified value. <index_integer> is the reaction
you want to set the falloff for. The order of reactions is the order in which they are created,
and the order in which the reactions are listed in the Reactor Parameters dialog.
getReactionInfluence <reactor_controller> <index_integer>
Returns the specified reaction’s influence. <index_integer> is the reaction you want to
get the influence from. The order of reactions is the order in which they are created, and
the order in which the reactions are listed in the Reactor Parameters dialog.
setReactionInfluence <reactor_controller> <index_integer> <float>
Sets the specified reaction’s influence to the specified value. <index_integer> is the
reaction you want to set the influence for. The order of reactions is the order in which they
are created, and the order in which the reactions are listed in the Reactor Parameters
dialog.
getReactionStrength <reactor_controller> <index_integer>
Returns the specified reaction’s strength. <index_integer> is the reaction you want to
get the strength from. The order of reactions is the order in which they are created, and
the order in which the reactions are listed in the Reactor Parameters dialog.
setReactionStrength <reactor_controller> <index_integer> <float>
Sets the specified reaction’s strength to the specified value. <index_integer> is the
reaction you want to set the strength for. The order of reactions is the order in which they
are created, and the order in which the reactions are listed in the Reactor Parameters
dialog.
getReactionState <reactor_controller> <index_integer>
Returns the specified reaction’s state. The value type returned matches the reactor
controller type. <index_integer> is the reaction you want to get the state from. The
order of reactions is the order in which they are created, and the order in which the
reactions are listed in the Reactor Parameters dialog.
setReactionState <reactor_controller> <index_integer> <value>
Sets the specified reaction’s state to the specified value. <index_integer> is the reaction
you want to set the state for. The order of reactions is the order in which they are created,
and the order in which the reactions are listed in. The <value> type must match the
reactor controller type.
getReactionValue <reactor_controller> <index_integer>
Returns the specified reaction’s value. The return value type is the same as the controller
type being reacted to. <index_integer> is the reaction you want to get the value from.
The order of reactions is the order in which they are created, and the order in which the
reactions are listed in the Reactor Parameters dialog.
setReactionValue <reactor_controller> <index_integer> <value>
Sets the specified reaction’s value to the specified value. <index_integer> is the reaction
you want to set the value for. The order of reactions is the order in which they are created,
and the order in which the reactions are listed in. The <value> type must match the
controller type being reacted to.
1328 Chapter 11 | 3ds max Objects

setReactionName <reactor_controller> <index_integer> <string>

Sets the name of the specified reaction. <index_integer> is the reaction you want to set
the name for. The order of reactions is the order in which they are created, and the order
in which the reactions are listed in.
getReactionName <reactor_controller> <which>
Returns the specified reaction’s name. <index_integer> is the reaction you want to get
the name of. The order of reactions is the order in which they are created, and the order in
which the reactions are listed in the Reactor Parameters dialog.
Script:
-- Setup a scene
b1 = box name:”box01” pos:[-32.5492,-21.2796,0] -- create two boxes
b2 = box name:”box02” pos:[51.3844,-17.2801,0]
animate on at time 100 b1.pos = [-48.2522,167.132,0] -- animate position of one box
--
-- Assign a reactor, pick the react to object, and create reactions
cont = b2.pos.controller = position_Reactor()
--
-- you can either react to a controller
reactTo cont b1.pos.controller
-- or a node (the World Space position of the box)
-- reactTo cont b1
--
slidertime = 100
createReaction cont
slidertime = 50
createReaction cont
deleteReaction cont 3
--
-- Set the reaction parameters
setReactionState cont 2 [65.8385,174.579,0]
selectReaction cont 1
setReactionInfluence cont 1 100
setReactionStrength cont 1 1.2
setReactionFalloff cont 1 1.0
setReactionValue cont 1 [-40.5492,-20.0,0]
setReactionName cont 1 “My Reaction”
--
-- get the reaction parameters
getReactionInfluence cont 1
getReactionStrength cont 1
getReactionFalloff cont 1
getReactionState cont 1
getReactionValue cont 1
getSelectedReactionNum cont
getReactionCount cont
getReactionName cont 1
 Script Controllers 1329

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Script Controllers
float_script : floatController
point3_script : point3Controller
position_script : positionController
rotation_script : rotationController
scale_script : scaleController
Constructor:
float_script ...
point3_script ...
position_script ...
rotation_script ...
scale_script ...

Properties:
<script_controller>.script String default: varies
lets you programmatically get and set the text for scripts. For example,
$foo.position.controller=position_script()
$foo.position.controller.script = “$baz.pos - [20,20,35]”

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Script controllers function in similar way to expression controllers, providing a properties dialog in
which a script can be entered that is used to compute the controller value. The primary advantages
of script controllers are:
• They can use all the features of the MAXScript language including loops, scripted functions,
pathnames, etc.
• Almost any property of any object in the scene can be used to help compute controller values,
including things like mesh vertices, values of properties at arbitrary frame times, and other non-
animatable properties that are not accessible in Expression controllers.
• They can use MAXScript global variables to communicate and coordinate with other controllers
and scripts in 3ds max.
1330 Chapter 11 | 3ds max Objects

When you assign a Script controller to some parameter, a properties dialog becomes available in
Track View through the right-mouse-button menu or the Properties button on the Track View
toolbar. This dialog contains two text boxes and several buttons:
Script text box: You type the script to compute the controller value here. See the section below on
writing controller scripts for details.
Result text box: This box shows the results of an evaluation or any error messages caused by errors
in your script.
Evaluate button: Cause an evaluation of the controller script to be made and prints the result in the
Result box. The evaluation is computed for the current position of the 3ds max time slider.
Load/Save buttons: Load and save scripts to text files.
Close button: Compiles and checks the controller script and if all is OK, close the properties dialog.
Any problems result in a dialog asking whether you really want to close the box with an incorrect
script. If you do, the controller yields a null value (0, [0,0,0], etc.) when evaluated by 3ds max.
 Script Controllers 1331

Writing Controller Scripts

3ds max interprets the text you type into the Script text box as the body of a MAXScript block
expression, so you can type as many expressions as you want on as many lines as you want and they
are evaluated in turn and the value of the last expression is taken as the controller value. This value
must yield the right type for the controller, Float for float, Point3 for position, Quat for rotation,
etc.
The value returned from a script controller may not necessarily be the same value seen in Track View
or in the command panels, nor the same value returned by accessing the property value in
MAXScript. Part of a MAXWrapper property definition is a scaling value that is applied when reading
or setting the true value stored in a controller. For example, the slice_to and slice_from
properties associated with many of the geometry primitives is displayed in degrees. The actual value
stored in the controller associated with these properties are in radians. This scaling factor is an
internal property of the MAXWrapper property, and not an internal property of the controller. Both
3ds max and MAXScript automatically apply the specified scaling factor when accessing properties,
so this scaling is normally invisible to the user. The exception is when script or expression controllers
are used. For these controllers, the data value returned must be the unscaled value, as 3ds max will
then apply the scaling factor to the output value. In the documentation of the MAXWrapper classes,
any scaling applied to a property is shown. If there is no scaling listed, no scaling occurs for that
property. For example, a portion of the Capsule documentation is:
<Capsule>.radius Float default: 0.0 -- animatable
<Capsule>.height Float default: 0.0 -- animatable
<Capsule>.slice_from Float default: 0.0 -- animatable, angle
<Capsule>.slice_to Float default: 0.0 -- animatable, angle

From this, a scripted controller would return unscaled values for the radius and height properties,
and radians for slice_from and slice_to. The scaling types, stored value meaning, and scaling
value applied to the true controller value are as follows:
Angle -- value stored in radians, output scaled by 57.29578
Percentage -- value stored as fraction (0 to 1), output scaled by 100
For properties that have a Color value type, the controller output is automatically scaled by 255. If
a point3_script is assigned to one of these properties, each component value should stored as
fraction (0 to 1). Remember that converting a MAXScript Color value to a Point3 value does not
apply a scaling factor – red as point3 returns a value of [255,0,0]. Therefore you must explicitly
scale a Color value by dividing by 255 if it is output by the script controller.
The body of a script controller’s script is any valid MAXScript expression that evaluates to the proper
data type, and can contain global and local variables, functions, and structure definitions. The script
is compiled in its own local scope, and the locals are only visible inside the scope of the script
controller. Script controller local variables are heap-based locals, which are slightly different from
normal (stack-based) locals. Normal locals are visible in the current scope and have a lifetime of one
execution of that scope. Heap-based locals are also visible only in the current scope, but have a
lifetime equal to the lifetime of the top-level expression where they are defined. A script controller’s
locals are created the first time the script is executed and are kept permanently in the heap (unless
1332 Chapter 11 | 3ds max Objects

and until you redefine the script). This means you can store values in local variables during one
execution of the script controller and these values will still be present at the next evaluation. You
cannot access the script controller’s locals from another utility or from Listener, because they are not
executing within the scope of the script controller. See the Scope of Variables (p. 646) topic for more
information.
As a special case, you can exit a script controller’s script using a return <expr>.
A controller is always evaluated by 3ds max with respect to a specific animation time. This might be
the current time slider or incrementing frame time if an animation is playing or a render is under
way.
In the case of Script controllers, the time being evaluated is used to establish an automatic ‘at time’
context around the controller script, so any properties you access (outside of other explicit ‘at time’
expressions) yield the correct values for the current controller evaluation time. This means you don’t
have to do anything special in your scripts to work at the correct time. You can access the evaluation
time if you need to with the standard MAXScript variable, currentTime. You can also reference
scene property values at other times by using explicit ‘at time’ expressions in your scripts, as in
normal MAXScript programming.
Remember that MAXScript lets you write multiline string literals, if you need.
Examples:
A position script keeping the object at the center of all other objects in the scene as they move about:
local pos = [0,0,0]
for o in objects where o != $foo do
pos += o.pos
pos / (objects.count - 1)

The above script computes the average position of all objects except the current one (written as
$foo here) by setting up a local variable that iterates through all objects except $foo,
accumulates a total position vector, and computes the average in the last line, which is the final
result of the script.
A position script keeping the object attached to the highest vertex in a given object:
local high_index = 1, high_z = (getVert $foo 1).z
for i in 2 to $foo.numVerts do
if (getVert $foo i).z > high_z then
(
high_index = i
high_z = (getVert $foo i).z
)
getVert $foo high_index

The above script runs over the vertices in $foo remembering the index of the vertex with the
largest z and returns that vertex’s coordinates as the new position.
 Slave_Control : Matrix3Controller 1333

Limitations
Script controllers are not automatically updated when you interactively modify objects that they
depend on.
If you move the time slider or if you animate the changes and then play the animation, the changes
are reflected automatically. Because the scripts can refer to other objects in very indirect ways or
conditional ways, it is not possible for MAXScript to automatically determine the objects a script
depends on.

Slave_Control : Matrix3Controller
Note: This class is not available in 3D Studio VIZ.
The Slave_Control is used as the transform controller for the boxes in a RingArray system object. You
cannot create a RingArray system using MAXScript in 3ds max 4, but properties for this controller
are accessible by MAXScript for existing RingArray systems. A RingArray system actually consists of
two types of controllers – the master controller and Slave_Control controllers. The Slave_Control
controllers are used as the transform controller for all the boxes in the RingArray system, and the
master controller controls the individual Slave_Control controllers. Changing a property value for
one Slave_Control in a RingArray system changes the property value for all Slave_Controls in the
system.
Properties:
<Slave_Control>.radius Float default: 100.0 -- animatable
<Slave_Control>.cycles Float default: 3.0 -- animatable
<Slave_Control>.amplitude Float default: 20.0 -- animatable
<Slave_Control>.phase Float default: 1.0 -- animatable

Slave Controllers
slavefloat : floatController
slave_point3 : point3Controller
slavepos : positionController
slaverotation : rotationController
slavescale : scaleController
Constructor:
The Slave controllers are not creatable by MAXScript. They can only be created by creating a
Masterblock in the Block Control node in the Global Tracks node of Track View. See the
MasterBlock : MasterBlockController (p. 1320) topic for more information.

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1334 Chapter 11 | 3ds max Objects

Surface_position : PositionController
Constructor:
Surface_position ...

Properties:
<Surface_position>.surface Node default: undefined
<Surface_position>.u Float default: 0.0 -- animatable
<Surface_position>.v Float default: 0.0 -- animatable
<Surface_position>.align Integer default: 1
align = 1 - No Alignment; 2 - Align to U; 3 - Align to V
<Surface_position>.flip Boolean default: false

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

TCB Controllers
TCB_float : floatController
TCB_point3 : point3Controller
TCB_position : positionController
TCB_rotation : rotationController
TCB_scale : scaleController
Constructor:
TCB_float ...
TCB_point3 ...
TCB_position ...
TCB_rotation ...
TCB_scale ...

Properties:
<controller>.keys MAXKeyArray

See also
MAXKeyArray Values (p. 793)
TCB Controller Keys (p. 1335)
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 TCB Controller Keys 1335

TCB Controller Keys

For TCB controller keys, the following additional properties are accessible:
<key>.time Time -- time value or number (interpreted as frames)
<key>.selected Boolean -- specifies whether the key is selected
<key>.value varies -- class determined by its containing controller
<key>.tension Float default: 25.0
<key>.continuity Float default: 25.0
<key>.bias Float default: 25.0
<key>.easeTo Float default: 0.0
<key>.easeFrom Float default: 0.0

See also
Key Common Properties, Operators, and Methods (p. 768)
Value Common Properties, Operators, and Methods (p. 714)

Waveform_Float : FloatController
Constructor:
waveform_float ...

Properties:
There are no additional properties accessible for Waveform_Float controllers.

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

XYZ Controllers
Color_RGB : Point3Controller
Euler_XYZ : RotationController
Local_Euler_XYZ : RotationController
Point3_XYZ : Point3Controller
Position_XYZ : PositionController
ScaleXYZ : ScaleController
1336 Chapter 11 | 3ds max Objects

Constructor:
Color_RGB ...
Euler_XYZ ...
Local_Euler_XYZ ...
Point3_XYZ ...
Position_XYZ ...
ScaleXYZ ...

Properties:
The property names for the XYZ controllers vary between the specific controllers.
Color_RGB:
<Color_RGB>.r Float default: 0.0 -- animatable
<Color_RGB>.g Float default: 0.0 -- animatable
<Color_RGB>.b Float default: 0.0 -- animatable

Euler_XYZ:
<Euler_XYZ>.x_rotation Float default: 0.0 -- animatable
<Euler_XYZ>.y_rotation Float default: 0.0 -- animatable
<Euler_XYZ>.z_rotation Float default: 0.0 -- animatable
<Euler_XYZ>.axisOrder Integer default: 1
Get/set the order of application of the axis angles. Its value can be any of the following:
1 - XYZ
2 - XZY
3 - YZX
4 - YXZ
5 - ZXY
6 - ZYX
7 - XYX
8 - YZY
9 - ZXZ
Local_Euler_XYZ:
<Local_Euler_XYZ>.local_x_rotation Float default: 0.0 -- animatable
<Local_Euler_XYZ>.local_y_rotation Float default: 0.0 -- animatable
<Local_Euler_XYZ>.local_z_rotation Float default: 0.0 -- animatable
<Local_Euler_XYZ>.axisOrder Integer default: 1
Get/set the order of application of the axis angles. Its value can be any of the following:
1 - XYZ
2 - XZY
3 - YZX
4 - YXZ
5 - ZXY
6 - ZYX
 XYZ Controllers 1337

7 - XYX
8 - YZY
9 - ZXZ

Point3_XYZ:
<Point3_XYZ>.x Float default: 0.0 -- animatable
<Point3_XYZ>.y Float default: 0.0 -- animatable
<Point3_XYZ>.z Float default: 0.0 -- animatable

Position_XYZ:
<Position_XYZ>.x_position Float default: 0.0 -- animatable
<Position_XYZ>.y_position Float default: 0.0 -- animatable
<Position_XYZ>.z_position Float default: 0.0 -- animatable

ScaleXYZ:
<ScaleXYZ>.x_scale Float default: 0.0 -- animatable
<ScaleXYZ>.y_scale Float default: 0.0 -- animatable
<ScaleXYZ>.z_scale Float default: 0.0 -- animatable

Methods:
getXYZControllers <controller>
Returns an array of the X, Y, and Z sub-controllers of the specified controller

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Atmospheric : MAXWrapper
The Atmospheric class lets you set up volumetric rendering effects with MAXScript. You can create
atmospherics like combustion and fog, access various properties on them and maintain their list of
gizmo nodes such as lights and atmospheric helpers.
The classes derived directly from the Atmospheric class are described in the Atmospheric Effect Types
(p. 1339) topic.
The properties, operators, and methods that are common to all classes derived directly from the
Atmospheric class are described in the Atmospheric Effects Common Properties, Operators, and Methods
(p. 1338) topic.
The Atmospheric class is derived from the MAXWrapper class, and inherits the properties and
methods defined for that class. These properties and methods are described in the MAXWrapper
Common Properties, Operators, and Methods (p. 809) topic.
1338 Chapter 11 | 3ds max Objects

Atmospheric Effects Common Properties, Operators, and Methods

Atmospherics have the following common properties and methods:
Properties:
<atmos>.name String default: varies
The name as it appears in the Environment dialog list. The class name is used as the
default name when no name: creation parameter is supplied.
<atmos>.numGizmos Integer -- read-only
The number of gizmos ever assigned to the atmospheric. A gizmo obtained via
.numGizmos may be undefined, meaning a gizmo was added and then deleted. The
atmospheric maintains an array of gizmos, and not every slot is necessarily in use.
numGizmos is the size of the array, not the number of used slots.
Methods:
isActive <atmos>
Returns true if the atmospheric is set to active; false otherwise.
getGizmo <atmos> <index_integer>
Retrieves the indexed gizmo node from the atmospheric. The gizmo node will be a light or
atmospheric helper. The Index is 1-based.
deleteGizmo <atmos> <index_integer>
Deletes the indexed gizmo from the atmospheric.
appendGizmo <atmos> <node>
Appends the node to the gizmo list on the atmospheric. It must be of the right kind for the
atmospheric, lights for volumeLights, helper gizmos for combust, etc.
setActive <atmos> <boolean>
Sets the atmospheric active or inactive. If <boolean> is true the atmospheric is set to
active; if false, inactive.
Associated Methods:
You can use the following functions for maintaining the list of atmospherics in the global rendering
environment:
addAtmospheric <atmos>
Appends the atmospheric to the Atmospheric Effects list
getAtmospheric <index_integer>
Retrieves the atmospheric at the indexed position in the Atmospheric Effects list. Index is
1-based.
setAtmospheric <index_integer> <atmos>
Sets the atmospheric at the indexed position in the Atmospheric Effects list to the
specified atmospheric. If the Atmospheric Effects dialog is displayed when this method is
called, the displayed Atmospheric Effects list is not updated.
deleteAtmospheric <index_integer>
Deletes the atmospheric at the indexed position in the Atmospheric Effects list. Index is 1-
based.
 Fire_Effect : Atmospheric 1339

editAtmosphere <atmos> <node>

Opens the Environment dialog, and opens the rollout for the specified atmospheric if it
has been added to the Atmospheric Effects list. If the specified node is a gizmo for the
atmospheric, that gizmo is selected in the atmospheric’s gizmo list.
editAtmospheric <atmos> [ gizmo: <node> ]
Opens the Environment dialog, and opens the rollout for the specified atmospheric if it
has been added to the Atmospheric Effects list. If the optional gizmo: argument is
specified, and the specified node is a gizmo for the atmospheric, that gizmo is selected in
the atmospheric’s gizmo list.
The 3ds max global variable numAtmospherics gives you the number of current atmospherics in
the rendering environment.
Note:
Unlike most MAXWrapper objects, you can not copy an Atmospheric.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Example:
atmos = combust density:20 outer_color:red
appendGizmo atmos $SphereGizmo01

Atmospheric Effect Types

The following list shows the 3ds max Atmospheric Effect types:
Fire_Effect (p. 1339)
Fog (p. 1342)
Volume_Fog (p. 1343)
Volume_Light (p. 1344)

Fire_Effect : Atmospheric
Constructor:
Fire_Effect ...

Properties:
<Fire_Effect>.Inner_Color Color default: (color 252 202 0) -- animatable
Sets the color of the densest part of the effect. For a typical fire, this color represents the
hottest part of the flame.
1340 Chapter 11 | 3ds max Objects

<Fire_Effect>.Outer_Color Color default: (color 225 30 30) -- animatable

Sets the color of the sparsest part of the effect. For a typical fire, this color represents the
cooler, dissipating edge of the flame. The fire effect is colored using a gradient between the
inner and outer colors. The dense areas of the effect use the inner color and gradually
blend to the outer color near the edges of the effect.
<Fire_Effect>.Smoke_Color Color default: (color 25.5 25.5 25.5) -- animatable
Sets the color of smoke for use with the Explosion option.
<Fire_Effect>.Flame_Type Integer default: 0
Sets the flame type:
Fire Ball (Creates round puffy flames. Fireballs are well suited for explosions.)
Tendril (Creates directional pointed flames with veins along their center. The flames orient
along the local Z axis of the fire apparatus. Tendril creates campfire-like flames.)
<Fire_Effect>.Stretch Float default: 1.0 -- animatable
Scales flames along the Z axis of the apparatus. Stretch works best with Tendril flames, but
you can use it to give Fireballs an oval shape. Values less than 1.0 compress flames, making
them shorter and thicker. Values greater than 1.0 stretch flames, making them long and
skinny.
<Fire_Effect>.Regularity Float default: 0.2 -- animatable
Modifies how the flames fill the apparatus. A value of 1.0 completely fills the apparatus.
The effect fades near the edges of the apparatus, but the overall shape is still very
noticeable. A value of 0.0 produces a very irregular effect that might occasionally reach the
boundary of the apparatus, but usually gets trimmed back and is smaller.
<Fire_Effect>.Flame_Size Float default: 35.0 -- animatable
Sets the size of individual flames inside the apparatus. The size of the apparatus affects the
flame size. A larger apparatus requires a larger flame size. Use a range from 15.0 to 30.0 for
the best results. Large values work best for Fireballs. Small values work best for Tendrils.
<Fire_Effect>.Flame_Detail Float default: 3.0 -- animatable
Controls the amount of color change and edge sharpness seen within each flame. Low
values produce smooth, fuzzy flames and render faster. High values produce patterned,
sharp flames and render slower.
<Fire_Effect>.Density Float default: 15.0 -- animatable
Sets the opacity and brightness of the fire effect. The size of the apparatus affects the
density. A large apparatus with the same density as a small apparatus appears more opaque
and brighter because of its larger size. Low values make the effect less opaque and use more
of the outer color. High values make the effect more opaque and brighten the effect by
gradually replacing the inner color with white. The higher the value, the more white the
center of the effect is.
<Fire_Effect>.Samples Integer default: 15 -- animatable
Sets the rate at which the effect is sampled. Higher values produce more accurate results
but take longer to render.
<Fire_Effect>.phase Float default: 0.0 -- animatable
Controls the rate of change for the fire effect.
 Setting explosion start and end times for Fire-Effect 1341

<Fire_Effect>.Drift Float default: 0.0 -- animatable

Sets how flames are rendered along the Z-axis of the fire apparatus. The value is the
amount of rise in units.
<Fire_Effect>.Explosion Integer default: 0
When on, animates size, density, and color automatically based on the animation of the
phase value.
OFF
ON
<Fire_Effect>.Smoke Integer default: 1
Controls whether or not the explosion creates smoke.
OFF
ON
<Fire_Effect>.Fury Float default: 1.0
Varies the churning effect of the Phase parameter. Values greater than 1.0 cause faster
churning. Values less than 1.0 cause slower churning.
Note:
The Explosion, Smoke, and Fury properties are not available in 3D Studio VIZ.

See also
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Setting explosion start and end times for Fire-Effect

The start and end spinners in the Explosion Setup dialog for Fire-Effect effectively install keyframes
and set times and values for them in the controller for phase. You can achieve the same effect by
manually constructing a phase controller and its keyframes. In the following example, the start and
end times are set at 20 and 75:
c = getAtmospheric 1

-- to set up a new phase controller like the setup dialog does:

-- make and set the controller
pc = bezier_float()
c.phase.controller = pc

-- add key 1 at 20 & set properties

k = addNewKey pc 20
k.value = 0
k.inTangentType = #slow
k.outTangentType = #fast
1342 Chapter 11 | 3ds max Objects

-- add key 2 at 75 & set

k = addNewKey pc 75
k.value = 300
k.inTangentType = #slow
k.outTangentType = #fast

-- or, to change times if the keys are already there:

c.phase.keys[1].time = 20
c.phase.keys[2].time = 75

Fog : Atmospheric
Constructor:
fog ...

Properties:
<Fog>.Fog_Color Color default: (color 255 255 255) -- animatable
<Fog>.Use_Color_Map Integer default: 0
Use_Color_Map = 0 - off; 1 - on
<Fog>.Use_Opacity_Map Integer default: 0
Use_Opacity_Map = 0 - off; 1 - on
<Fog>.Fog_Background Integer default: 1
Fog_Background = 0 - off; 1 - on
<Fog>.Fog_Type Integer default: 0
Fog_Type = 0 - Standard; 1 - Layered
<Fog>.Exponential Integer default: 0
Exponential = 0 - off; 1 - on
<Fog>.Near Float default: 0.0 -- animatable, percentage
<Fog>.Far Float default: 100.0 -- animatable, percentage
<Fog>.Top Float default: 100.0 -- animatable
<Fog>.Bottom Float default: 0.0 -- animatable
<Fog>.Density Float default: 50.0 -- animatable
<Fog>.falloff Integer default: 2
falloff = 0 - Top; 1 - Bottom; 2 - None
<Fog>.Horizon_Noise Integer default: 0
Horizon_Noise = 0 - off; 1 - on
<Fog>.size Float default: 20.0 -- animatable
<Fog>.angle Float default: 5.0 -- animatable, angle
<Fog>.phase Float default: 0.0 -- animatable

Note:
You currently cannot assign texture maps as the color and opacity maps using MAXScript. Once
these texture maps have been assigned, they are accessible as subAnims of Fog.
 Volume_Fog : Atmospheric 1343

See also
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Volume_Fog : Atmospheric
Constructor:
volume_fog ...

Properties:
<Volume_Fog>.Soften_Gizmo_Edges Float default: 0.2 -- animatable
<Volume_Fog>.Fog_Color Color default: (color 255 255 255) --
animatable
<Volume_Fog>.Exponential Integer default: 0
Exponential = 0 - off; 1 - on
<Volume_Fog>.Density Float default: 20.0 -- animatable
<Volume_Fog>.Step_Size Float default: 4.0
<Volume_Fog>.Max_Steps Integer default: 100
<Volume_Fog>.Fog_Background Integer default: 1
Fog_Background = 0 - off; 1 - on
<Volume_Fog>.Noise_Type Integer default: 0
Noise_Type = 0 - Regular; 1 - Fractal; 2 - Turbulence
<Volume_Fog>.invert Integer default: 0
invert = 0 - off; 1 - on
<Volume_Fog>.High_Threshold Float default: 1.0 -- animatable
<Volume_Fog>.Low_Threshold Float default: 0.0 -- animatable
<Volume_Fog>.Uniformity Float default: 0.0 -- animatable
<Volume_Fog>.Levels Float default: 3.0 -- animatable
<Volume_Fog>.size Float default: 20.0 -- animatable
<Volume_Fog>.phase Float default: 0.0 -- animatable
<Volume_Fog>.Wind_Strength Float default: 0.0
<Volume_Fog>.Wind_Direction Integer default: 0
Wind_Direction = 0 - Front; 1 - Back; 2 - Left; 3 - Right; 4 - Top; 5 - Bottom

See also
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1344 Chapter 11 | 3ds max Objects

Volume_Light : Atmospheric
Constructor:
volume_light ...

Properties:
<Volume_Light>.Fog_Color Color default: (color 255 255
255) -- animatable
<Volume_Light>.attenuation_color Color default: (color 0 0
255) -- animatable
<Volume_Light>.Exponential Integer default: 0
Exponential = 0 - off; 1 - on
<Volume_Light>.Density Float default: 5.0 --
animatable
<Volume_Light>.Max_Light Float default: 90.0 --
animatable
<Volume_Light>.Min_Light Float default: 0.0 --
animatable
<Volume_Light>.Use_Attenuation_Color Integer default: 0
Use_Attenuation_Color = 0 - off; 1 - on
<Volume_Light>.Attenuation_Color_Multiplier Float default: 2.0 --
animatable
<Volume_Light>.Filter_Shadows Integer default: 3
Filter_Shadows = 0 - Low; 1 - Medium; 2 - High; 3 - Use Light Smp Range
<Volume_Light>.Samples Integer default: 20
<Volume_Light>.Auto_Sample Integer default: 1
Auto_Sample = 0 - off; 1 - on
<Volume_Light>.Atten_Start Float default: 100.0 --
animatable
<Volume_Light>.Atten_End Float default: 100.0 --
animatable
<Volume_Light>.Noise_On Integer default: 0
Noise_On = 0 - off; 1 - on
<Volume_Light>.Noise_Amount Float default: 0.0 --
animatable
<Volume_Light>.Link_To_Light Integer default: 0
Link_To_Light = 0 - off; 1 - on
<Volume_Light>.Noise_Type Integer default: 0
Noise_Type = 0 - Regular; 1 - Fractal; 2 - Turbulence
<Volume_Light>.invert Integer default: 0
invert = 0 - off; 1 - on
<Volume_Light>.High_Threshold Float default: 1.0 --
animatable
<Volume_Light>.Low_Threshold Float default: 0.0 --
animatable
 Volume_Light : Atmospheric 1345

<Volume_Light>.Uniformity Float default: 0.0 --

animatable
<Volume_Light>.Levels Float default: 3.0 --
animatable
<Volume_Light>.size Float default: 20.0 --
animatable
<Volume_Light>.phase Float default: 0.0 --
animatable
<Volume_Light>.Wind_Strength Float default: 0.0
<Volume_Light>.Wind_Direction Integer default: 0
Wind_Direction = 0 - Front; 1 - Back; 2 - Left; 3 - Right; 4 - Top; 5 - Bottom

See also
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Working with Atmospherics

The following 3ds max system global variables give you access to the global rendering environment:
backgroundColor
Lets you get and set a Color value that defines the global rendering environment
(Rendering\Environment) background color.
backgroundColorController
Lets you get and set a Controller value that defines the global rendering environment
(Rendering\Environment) background color controller.
ambientColor
Lets you get and set a Color value that defines the global rendering environment
(Rendering\Environment) ambient lighting color.
ambientColorController
Lets you get and set a Controller value that defines the global rendering environment
(Rendering\Environment) ambient lighting color controller.
environmentMap
Lets you get and set a TextureMap value that defines the global rendering environment
(Rendering\Environment) environment map.
useEnvironmentMap
Lets you get and set the global rendering environment (Rendering\Environment) Use Map
value. A Boolean value - true if Use Map is on, false if off.
lightTintColor
Lets you get and set a Color value that defines the global rendering environment
(Rendering\Environment) Global Lighting Tint color.
lightTintColorController
Lets you get and set a Controller value that defines the global rendering environment
(Rendering\Environment) Global Lighting Tint color controller.
1346 Chapter 11 | 3ds max Objects

lightLevel
Lets you get and set a Float value that defines the global rendering environment
(Rendering\Environment) Global Lighting Tint Level.
lightLevelController
Lets you get and set a Controller value that defines the global rendering environment
(Rendering\Environment) Global Lighting Tint Level controller.
numAtmospherics
Contains an Integer value that defines the number of atmospheric events, as shown in
Rendering\Environment. This variable is read-only.
The following methods set options in the global rendering environment:
getUseEnvironmentMap()
setUseEnvironmentMap <boolean>
Lets you get and set the global rendering environment (Rendering\Environment) Use Map
value. If <boolean> is true Use Map is turned on, false it is turned off.
getBackGroundController()
Returns the global rendering environment (Rendering\Environment) background color
controller.
setBackGround <time> <point3>
Lets you set a Point3 value that defines the global rendering environment
(Rendering\Environment) background color at the specified time. Each component of the
Point3 value is in the range of 0 to 255.
setBackGroundController ( <color_controller> | <point3_controller> )
Assigns the specified controller as the global rendering environment
(Rendering\Environment) background color controller.
Examples:
ambientColor = color 10 10 25
environmentMap = bitmapTexture filename:”foo.bmp”

The following script shows an example of creating Volume Fog and Volume Light atmospherics.
Script:
-- Atmospheric Effects Test Bed
-- create a geosphere, sphere gizmo, onnilight, and targetted camera
geos=geosphere radius:24
sgizmo=spheregizmo radius:40
omni=omnilight farAttenStart:20 farAttenEnd:100 useFarAtten:true v=255
cam=targetcamera pos:[150,-50,100] target:(targetobject())
--
-- put a material on the geosphere
geos.material=standard()
geos.material.selfIllumColor = color 238 241 2
--
-- create a Volume Fog atmospheric. Set name so it has one in Environment dialog.
vf=volume_fog name:”VolFog” soften_gizmo_edges:0.7 exponential:1 density:75
vf.fog_color=color 255 157 0
vf.noise_type=2
 Render Effects Common Properties, Operators, and Methods 1347

vf.size=4
appendGizmo vf sgizmo
addAtmospheric vf
--
-- create a Volume Light atmospheric. Set name so it has one in Environment dialog.
vl=volume_light name: “VolLight” exponential:1 density:20
vl.fog_color=color 255 30 0
vl.attenuation_color= color 255 162 0
vl.Use_Attenuation_Color=1
vl.noise_on=1
vl.Noise_Amount=1
vl.size=5
vl.noise_type=2
appendGizmo vl omni
addAtmospheric vl
--
-- and render away…
renderWidth=320
renderHeight=200
render camera:cam

RenderEffect : MAXWrapper
The RenderEffect class lets you set up rendering effects with MAXScript. You can create render effects
such as blur, color balance, and film grain effect.
The classes derived directly from the RenderEffect class are described in the Render Effect Types
(p. 1348) topic.
The properties, operators, and methods that are common to all classes derived directly from the
RenderEffect class are described in the Render Effects Common Properties, Operators, and Methods
(p. 1347) topic.
The RenderEffect class is derived from the MAXWrapper class, and inherits the properties and
methods defined for that class. These properties and methods are described in the MAXWrapper
Common Properties, Operators, and Methods (p. 809) topic.

Render Effects Common Properties, Operators, and Methods

Render Effects have the following common properties and methods:
Properties:
<renderEffect>.name String default: varies
The name as it appears in the Rendering/Effects dialog list. The class name is used as the
default name when no name: creation parameter is supplied.
Methods:
addEffect <renderEffect>
Adds the render effect to the Rendering/Effects dialog list.
1348 Chapter 11 | 3ds max Objects

setActive <renderEffect> <boolean>

Sets the render effect active or inactive. If <boolean> is true the render effect is set to
active; if false, inactive.
Associated Methods and Global Variables:
You can use the following global variables and functions for maintaining the list of render effects in
the Rendering/Effects dialog list:
IsActive <renderEffect>
Returns true if the render effect is set to active; false otherwise.
numEffects
Global variable containing an Integer value that defines the number of current render
effects defined in the Rendering/Effects dialog list. This variable is read-only.
getEffect <index_integer>
Retrieves the render effect at the indexed position in the Rendering/Effects dialog list. The
index is 1-based.
editEffect <renderEffect> [ gizmo: <node> ]
Opens the Rendering/Effects dialog, and opens the rollout for the specified render effect if
it has been added to the Render Effects list. If the optional gizmo: argument is specified,
and the specified node is a gizmo for the render effect, that gizmo is selected in the render
effect’s gizmo list.
setEffect <index_integer> <renderEffect>
Sets the render effect at the indexed position in the Rendering/Effects dialog list to the
specified render effect. If the Render Effects dialog is displayed when this method is called,
the displayed Render Effects list is not updated.
deleteEffect <index_integer>
Deletes the indexed render effect from the Rendering/Effects dialog list. The index is 1-
based.
Note:
Unlike most MAXWrapper objects, you can not copy an RenderEffect.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Render Effect Types

The following list shows the 3ds max Render Effect types:
Blur Effect (p. 1349)
Brightness and Contrast (p. 1353)
Color Balance Effect (p. 1354)
Depth of Field (p. 1354)
 Blur : RenderEffect 1349

File Output Effect (p. 1356)

Film Grain (p. 1356)
Lens Effects (p. 1357)

Blur : RenderEffect
Constructor:
blur ...

Properties:
<blur>.blur_type Integer default: 0 -- animatable
Select a blur type:
Uniform
Directional
Radial
<blur>.bUnifPixRad Float default: 10.0
Determines the intensity of the Blur effect. Increasing the value increases the number of
surrounding pixels that each pixel will use to compute its blur. The more pixels used
means a greater blur for the image.
<blur>.bUnifAlpha Boolean default: true -- animatable
Applies the Uniform Blur effect to the alpha channel when turned on.
<blur>.bDirUPixRad Float default: 10.0
Determines the horizontal intensity of the Blur effect. Increasing the value increases the
number of surrounding pixels that each pixel will use to compute its blur. The more pixels
used means a greater horizontal blur for the image.
<blur>.bDirVPixRad Float default: 10.0
Determines the vertical intensity of the Blur effect. Increasing the value increases the
number of surrounding pixels that each pixel will use to compute its blur. The more pixels
used means a greater vertical blur for the image.
<blur>.bDirUTrail Float default: 0.0
Adds “direction” to your blur by weighting more blur to either side of the U axis. This adds
a streaking effect and creates the illusion that your objects or your camera are rapidly
moving in a particular direction.
<blur>.bDirVTrail Float default: 0.0
Adds “direction” to your blur by weighting more blur to either side of the V axis. This adds
a streaking effect and creates the illusion that your objects or your camera are rapidly
moving in a particular direction.
1350 Chapter 11 | 3ds max Objects

<blur>.bDirRotation Integer default: 0

Rotates the axis of the U and V pixels that will be blurred by the U and V Pixel Radius
spinners. By using Rotation with the U and V Pixel Radius spinners you can have the Blur
effect applied to any direction in your rendered image. When rotation is 0, U corresponds
to the image’s X-axis and V corresponds to the image’s Y-axis.
<blur>.bDirAlpha Boolean default: true -- animatable
Applies the Directional Blur effect to the Alpha channel when turned on.
<blur>.bRadialPixRad Float default: 20.0
Determines the intensity of the Radius Blur effect. Increasing the value increases the
number of surrounding pixels that each pixel will use to compute its blur. The more pixels
used means a greater blur for the image.
<blur>.bRadialXOrig Integer default: 320
Sets the origin for the radial blur effect along the X axis.
<blur>.bRadialYOrig Integer default: 240
Sets the origin for the radial blur effect along the Y axis.
axis.<blur>.bRadialTrail Float default: 0.0
Adds “direction” to your blur by weighting more or less blur towards the center of the Blur
effect. This adds a streaking effect and creates the illusion that your objects or your camera
are rapidly moving in a particular direction.
<blur>.bRadialAlpha Boolean default: true -- animatable
Applies the Radial Blur effect to the Alpha channel when turned on.
<blur>.bRadialNode Node default: undefined
Node to which radial blur is assigned.
<blur>.bRadialUseNode Boolean default: false
Turn on/off use object center for selected node, bradialnode.
<blur>.selImageActive Boolean default: true -- animatable
When on, the blur affects the entire rendered image. This is useful when the blur effect
dims your rendered image.
<blur>.selImageBrighten Float default: 0.0
Brightens the entire image.
<blur>.selImageBlend Float default: 100.0
Blends the Blur effect and the Whole Image parameters with the original rendered image.
This can be used to create a soft-focus effect.
<blur>.selIBackActive Boolean default: false
Affects everything but the background image or animation when turned on. This is useful
when the Blur effect has dimmed you scene objects but not the background.
<blur>.selIBackBrighten Float default: 0.0
Brightens the rendered image except for the background image or animation.
<blur>.selIBackBlend Float default: 100.0
Blends the Blur effect and the Non-Background parameters with the original rendered
image.
 Blur : RenderEffect 1351

<blur>.selIBackFRadius Float default: 10.0

Feathers the Blur effect applied to the Non-Background elements of your scene. When
using Non-Background as a Pixel Selection you will notice that the scene objects have a
hard edge to their blur since the objects are being blurred but the background is not.
<blur>.selLumActive Boolean default: false
Affects any pixels that have luminance values that fall between it’s Min and Max values,
selLumMin & selLumMax.
<blur>.selLumBrighten Float default: 0.0
Brightens pixels that fall between the Minimum and Maximum luminance values.
<blur>.selLumBlend Float default: 100.0
Blends the Blur effect and the Luminance parameters with the original rendered image.
<blur>.selLumMin Float default: 90.0
The minimum luminance value necessary for each pixel in order for the Blur effect to be
applied to the pixel.
<blur>.selLumMax Float default: 100.0
The maximum luminance value a pixel can have in order for the Blur effect to be applied
to the pixel.
<blur>.selLumFRadius Float default: 10.0
Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum
luminance values. When using Luminance as a Pixel Selection the Blur effect can create a
hard edge on the effect.
<blur>.selMaskActive Boolean default: false
When turned on, applies the Blur effect according to the channel selected and mask
applied through the Material/Map Browser.
<blur>.selMaskMap TextureMap default: undefined
Map assigned to the blur effect.
<blur>.selMaskChannel Integer default: 4 -- alias:
select_mask_channel
Selects a channel that the Blur effect will be applied to:
Red
Blue
Green
Alpha
Luminance
<blur>.selMaskBrighten Float default: 0.0
Brightens the portions of the image that the Blur effect is applied to.
<blur>.selMaskBlend Float default: 100.0
Blends the Map Mask Blur effect with the original rendered image.
<blur>.selMaskMin Float default: 90.0
The minimum value (RGB, Alpha, or Luminance) a pixel must have in order to have the
Blur effect applied to it.
1352 Chapter 11 | 3ds max Objects

<blur>.selMaskMax Float default: 100.0

The maximum value (RGB, Alpha, or Luminance) a pixel can have for the Blur effect to be
applied to it.
<blur>.selMaskFRadius Float default: 10.0
Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum
channel values. When using map mask as a Pixel Selection the Blur effect can create a hard
edge on the effect.
<blur>.selObjIdsActive Boolean default: false -- animatable
When turned on, applies the Blur effect to an object or part of an object with a specific
Object ID, if the object matches the Filter settings.
<blur>.selObjIdsIds Array default: #() -- int array
This array contains all of the Object ID’s to which the blur effects will be applied.
<blur>.selObjIdsBrighten Float default: 0.0 -- animatable
Brightens the portion of the image that the Object ID-specific Blur effect is applied to.
<blur>.selObjIdsBlend Float default: 100.0 -- animatable
Blends the Object ID Blur effect with the original rendered image.
<blur>.selObjIdsFRadius Float default: 10.0 -- animatable
Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum
luminance values.
<blur>.selObjIdsLumMin Float default: 0.0 -- animatable
The minimum luminance value a pixel must have in order to have the Blur effect applied
to it.
<blur>.selObjIdsLumMax Float default: 100.0 -- animatable
The maximum luminance value a pixel can have for the Blur effect to be applied to it.
<blur>.selMatIdsActive Boolean default: false -- animatable
Applies the Blur effect to a material or part of a material with a specific material effects
channel, if the material matches the Filter settings.
<blur>.selMatIdsIds Array default: #() -- int array
This array contains all of the Material ID’s to which the blur effects will be applied.
<blur>.selMatIdsBrighten Float default: 0.0 -- animatable
Brightens the portion of the image that the Blur effect is applied to.
<blur>.selMatIdsBlend Float default: 100.0 -- animatable
Blends the Material ID Blur effect with the original rendered image.
<blur>.selMatIdsFRadius Float default: 10.0 -- animatable
Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum
luminance values.
<blur>.selMatIdsLumMin Float default: 0.0 -- animatable
The minimum luminance value a pixel must have in order to have the Blur effect applied
to it.
<blur>.selMatIdsLumMax Float default: 100.0 -- animatable
The maximum luminance value a pixel can have for the Blur effect to be applied to it.
 Brightness_and_Contrast : RenderEffect 1353

<blur>.selGenBrightType Integer default: 1 -- animatable

Selects the type of brightening applied to the feather falloff curve:
Additive
Multiplicative
<blur>.select_falloff_curve SubAnim default: SubAnim:Select_Falloff_Curve
<blur.select_falloff_curve>.curve_1 SubAnim default: SubAnim:Curve_1
The brightening curve for the feather falloff.
<blur.select_falloff_curve>.curve_2 SubAnim default: SubAnim:Curve_2
The blend curve for the feather falloff.

See also
Render Effects Common Properties, Operators, and Methods (p. 1347)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Brightness_and_Contrast : RenderEffect
Constructor:
brightness_and_contrast ...

Properties:
<Brightness_and_Contrast>.Brightness Float default: 0.5 -- animatable
<Brightness_and_Contrast>.contrast Float default: 0.5 -- animatable
<Brightness_and_Contrast>.ignoreBack Boolean default: false -- animatable,
alias: ignore_background

See also
Render Effects Common Properties, Operators, and Methods (p. 1347)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1354 Chapter 11 | 3ds max Objects

Color_Balance : RenderEffect
Constructor:
color_balance ...

Properties:
<Color_Balance>.red Integer default: 0 -- animatable
<Color_Balance>.green Integer default: 0 -- animatable
<Color_Balance>.blue Integer default: 0 -- animatable
<Color_Balance>.preserveLum Boolean default: false -- animatable, alias:
Preserve_Luminosity
<Color_Balance>.ignoreBack Boolean default: false -- animatable, alias:
Ignore_Background

See also
Render Effects Common Properties, Operators, and Methods (p. 1347)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Depth_of_Field : RenderEffect
Constructor:
depth_of_field ...

Properties:
<Depth_of_Field>.AffectAlpha Boolean default: true -- alias: Affect_Alpha
<Depth_of_Field>.camNodeIndex Integer default: -1 -- alias: Camera_Index
camNodeIndex specifies which camera in the Depth of Field camera dropdown is the
selected camera. A value of -1 specifies that no camera is selected. The index is otherwise 0-
based.
<Depth_of_Field>.focalNodeIndex Integer default: -1 -- alias: Focal_Index
focalNodeIndex specifies which camera in the Depth of Field focal point node dropdown
is the selected focal point node. A value of -1 specifies that no focal point node is selected.
The index is otherwise 0-based.
<Depth_of_Field>.FocalPoint Integer default: 0 -- alias: Focal_Point
FocalPoint = 0 - Focal Node; 1 - Use Camera
<Depth_of_Field>.FocalType Integer default: 0 -- alias: Focal_Type
FocalType = 0 - Custom; 1 - Use Camera
 Depth_of_Field : RenderEffect 1355

<Depth_of_Field>.HorizFocalLoss Float default: 10.0 -- animatable, alias:

Horiz_Focal_Loss
<Depth_of_Field>.VertFocalLoss Float default: 10.0 -- animatable, alias:
Vert_Focal_Loss
<Depth_of_Field>.FocalRange Float default: 100.0 -- animatable, alias:
Focal_Range
<Depth_of_Field>.FocalLimit Float default: 200.0 -- animatable, alias:
Focal_Limit

Methods:
DOF.addCam <Depth_of_Field> <camera_node_name_string>
Adds the specified camera to the Depth of Field camera dropdown.
camera_node_name_string is the name of the camera as a string, and must match the
case of the camera’s name. Returns true if the addition was successful, false if it failed.
The normal reason for a failure is that the named camera is not present in the scene.
DOF.addFocalNode <Depth_of_Field> <node_name_string>
Adds the specified node to the Depth of Field focal point node dropdown.
node_name_string is the name of the node as a string, and must match the case of the
node’s name. Returns true if the addition was successful, false if it failed. The normal
reason for a failure is that the named node is not present in the scene.
DOF.deleteCam <Depth_of_Field> <index_integer>
Deletes the indexed camera from the Depth of Field camera dropdown, where
<index_integer> is the index of the camera in the dropdown. The index is 0-based to
maintain consistency with the camNodeIndex property. Returns true if the deletion was
successful, false if it failed. The normal reason for a failure is that the indexed camera is
not present in the dropdown.
DOF.deleteCamByName <Depth_of_Field> <camera_node_name_string>
Deletes the specified camera from the Depth of Field camera dropdown.
camera_node_name_string is the name of the camera as a string, and must match the
case of the camera’s name. Returns true if the deletion was successful, false if it failed.
The normal reason for a failure is that the named camera is not present in the dropdown.
DOF.deleteFocalNode <Depth_of_Field> <index_integer>
Deletes the indexed node from the Depth of Field focal point node dropdown, where
<index_integer> is the index of the node in the dropdown. The index is 0-based to
maintain consistency with the focalNodeIndex property. Returns true if the deletion
was successful, false if it failed. The normal reason for a failure is that the indexed node
is not present in the dropdown.
DOF.deleteFocalNodeByName <Depth_of_Field> <node_name_string>
Deletes the specified node from the Depth of Field focal point node dropdown.
node_name_string is the name of the node as a string, and must match the case of the
node’s name. Returns true if the deletion was successful, false if it failed. The normal
reason for a failure is that the named node is not present in the dropdown.
1356 Chapter 11 | 3ds max Objects

See also
Render Effects Common Properties, Operators, and Methods (p. 1347)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

File_Output : RenderEffect
Constructor:
file_output ...

Properties:
<File_Output>.bitmap BitMap default: BitMap: -- output bitmap
<File_Output>.channelType Integer default: 0 -- alias: channel_type
channelType = 0 - Whole Image; 1 - Luminance; 2 - Depth; 3 - Alpha
<File_Output>.active Boolean default: true -- animatable
<File_Output>.affectSource Boolean default: false -- animatable, alias:
affect_source
<File_Output>.cameraNode Node default: undefined -- alias: camera_node
<File_Output>.nearZ Float default: 0.0 -- animatable, alias:
near_z_depth
<File_Output>.farZ Float default: -500.0 -- animatable, alias:
far_z_depth
<File_Output>.fitScene Boolean default: true -- animatable, alias:
fit_entire_scene

See also
Render Effects Common Properties, Operators, and Methods (p. 1347)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Film_Grain : RenderEffect
Constructor:
film_grain ...

Properties:
<Film_Grain>.Grain Float default: 0.2 -- animatable
<Film_Grain>.’Mask Background’ Boolean default: false -- animatable; alias:
Ignore_Background
 Lens_Effects : RenderEffect 1357

See also
Render Effects Common Properties, Operators, and Methods (p. 1347)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Lens Effects

Lens_Effects : RenderEffect
Constructor:
lens_effects ...

Properties:
<Lens_Effects>.size Float default: 100.0 -- animatable
<Lens_Effects>.intensity Float default: 100.0 -- animatable
<Lens_Effects>.seed Integer default: 1357
<Lens_Effects>.angle Float default: 0.0 -- animatable
<Lens_Effects>.squeeze Float default: 0.0 -- animatable
<Lens_Effects>.affectAlpha Boolean default: true -- alias:
Affect_Alpha
<Lens_Effects>.affectZBuffer Boolean default: false -- alias:
Affect_Z_Buffer
<Lens_Effects>.distAffectsSize Boolean default: false -- alias:
Distance_Affects_Size
<Lens_Effects>.distAffectsIntensity Boolean default: false -- alias:
Distance_Affects_Intensity
<Lens_Effects>.centerAffectsSize Boolean default: false -- alias:
Off_Center_Affects_Size
<Lens_Effects>.centerAffectsIntensity Boolean default: false -- alias:
Off_Center_Affects_Intensity
<Lens_Effects>.innerOcclusionRadius Float default: 3.0 -- animatable,
alias: Inner_Occlusion_Radius
<Lens_Effects>.outerOcclusionRadius Float default: 33.0 -- animatable,
alias: Outer_Occlusion_Radius
<Lens_Effects>.occlusionAffectsSize Boolean default: true -- alias:
Occlusion_Affects_Size
<Lens_Effects>.occlusionAffectsIntensity Boolean default: true -- alias:
Occlusion_Affects_Intensity
<Lens_Effects>.affectByAtmosphere Boolean default: false -- alias:
Affect_By_Atmosphere
1358 Chapter 11 | 3ds max Objects

Methods:
The following methods add elements to a Lens Effects, load and save a Lens Effects configuration
file, add and delete lights, and delete Lens Effects elements.
le.addASec <Lens_Effects>
Adds a Auto Secondary element to the Lens Effect. The element is appended to any
elements present. Returns true if the addition was successful, false if it failed.
le.addGlow <Lens_Effects>
Adds a Glow element to the Lens Effect. The element is appended to any elements present.
Returns true if the addition was successful, false if it failed.
le.addMSec <Lens_Effects>
Adds a Manual Secondary element to the Lens Effect. The element is appended to any
elements present. Returns true if the addition was successful, false if it failed.
le.addRay <Lens_Effects>
Adds a Ray element to the Lens Effect. The element is appended to any elements present.
Returns true if the addition was successful, false if it failed.
le.addRing <Lens_Effects>
Adds a Ring element to the Lens Effect. The element is appended to any elements present.
Returns true if the addition was successful, false if it failed.
le.addStar <Lens_Effects>
Adds a Star element to the Lens Effect. The element is appended to any elements present.
Returns true if the addition was successful, false if it failed.
le.addStreak <Lens_Effects>
Adds a Streak element to the Lens Effect. The element is appended to any elements
present. Returns true if the addition was successful, false if it failed.
le.load <Lens_Effects> <filename_string>
le.save <Lens_Effects> <filename_string>
Saves the Lens Effects configuration to the file specified by <filename_string>.
Animated parameter values are not saved.
le.numLights <Lens_Effects>
Returns the number of lights in the light list.
le.addLightNode <Lens_Effects> <light_node>
Adds light node to the light list.
le.addLight <Lens_Effects> <light_node_name_string>
Adds the specified light to the Lens Effects Lights dropdown. light_node_name_string
is the name of the light as a string, and must match the case of the light’s name. Returns
true if the addition was successful, false if it failed. The normal reason for a failure is
that the named light is not present in the scene.
le.deleteLight <Lens_Effects> <index_integer>
Deletes the indexed light from the Lens Effects Lights dropdown, where
<index_integer> is the index of the light in the Lens Effects Lights dropdown. Returns
true if the deletion was successful, false if it failed. The normal reason for a failure is
that the indexed light is not present in the dropdown.
 Lens_Effects : RenderEffect 1359

le.deleteLightByName <light_node_name_string>
Deletes the named light from the Lens Effects Lights dropdown.
light_node_name_string is the name of the light as a string, and must match the case
of the light’s name. Returns true if the deletion was successful, false if it failed. The
normal reason for a failure is that the named light is not present in the dropdown.
le.lightIndex <Lens_Effects> <light_node_name_string>
Returns the light list index of the named light. Returns –1 if the light’s name is not in the
light list.
le.lightName <Lens_Effects> <index>
Returns the node name of the light for the specified light list index. If the index is out of
range, a null string will be returned.
le.deleteElement <Lens_Effects> <index_integer>
Deletes the indexed element, where <index_integer> is the index of the element in the
Lens Effects composition window. Returns true if the deletion was successful, false if it
failed. The normal reason for a failure is that the indexed element does not exist.
le.deleteElementByName <element_name_string>
Deletes the named element. element_name_string is the name of the element as a
string, and must match the case of the element’s name. Returns true if the deletion was
successful, false if it failed. The normal reason for a failure is that the named element
does not exist.

See also
Lens_Effects - Auto_Secondary (p. 1360)
Lens_Effects - Glow (p. 1363)
Lens_Effects - Manual_Secondary (p. 1366)
Lens_Effects - Ray (p. 1370)
Lens_Effects - Ring (p. 1373)
Lens_Effects - Star (p. 1376)
Lens_Effects - Streak (p. 1379)
Render Effects Common Properties, Operators, and Methods (p. 1347)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1360 Chapter 11 | 3ds max Objects

Lens_Effects - Auto_Secondary
Constructor:
le.addASec <Lens_Effects>

Properties:
<auto_secondary>.elementName String default: “Auto Secondary” --
alias: Name
<auto_secondary>.on Boolean default: true
<auto_secondary>.minSize Float default: 25.0 --
animatable; alias: Min_Size
<auto_secondary>.maxSize Float default: 100.0 --
animatable; alias: Max_Size
<auto_secondary>.axis Float default: 3.0 --
animatable
<auto_secondary>.intensity Float default: 30.0 --
animatable
<auto_secondary>.quantity Integer default: 12 --
animatable
<auto_secondary>.colorSource Float default: 20.0 --
animatable; alias: Source_Color
<auto_secondary>.sides Integer default: 0
sides = 0 - Circular; 1 - Three; 2 - Four; 3 - Five; 4 - Six; 5 - Seven; 6 - Eight
<auto_secondary>.occlusion Float default: 100.0 --
animatable
<auto_secondary>.presets Integer default: 0
presets selects a preset from the indexed list. presets = 0 - no preset.
<auto_secondary>.squeeze Boolean default: false
<auto_secondary>.radialColor1 Color default: (color 0 0 0) --
animatable; alias: Radial_Color_1
<auto_secondary>.radialColor2 Color default: (color 57 34 89) --
animatable; alias: Radial_Color_2
<auto_secondary>.radialColor3 Color default: (color 85 139 85) --
animatable; alias: Radial_Color_3
<auto_secondary>.radialColor4 Color default: (color 190 99 10) --
animatable; alias: Radial_Color_4
<auto_secondary>.colorRadius1 Float default: 90.0 --
animatable; alias: Radius_Color_1
<auto_secondary>.colorRadius2 Float default: 92.0 --
animatable; alias: Radius_Color_2
<auto_secondary>.colorRadius3 Float default: 95.0 --
animatable; alias: Radius_Color_3
<auto_secondary>.colorRadius4 Float default: 98.0 --
animatable; alias: Radius_Color_4
<auto_secondary>.radialMtl TextureMap default: undefined -- alias:
Radial_Material
<auto_secondary>.useRadialMtl Boolean default: false -- alias:
Apply_Radial_Color_Map
<auto_secondary>.radial_falloff SubAnim
 Lens_Effects - Auto_Secondary 1361

<auto_secondary>.radialMap TextureMap default: undefined -- alias:

Radial_Falloff_Map
<auto_secondary>.useRadialMap Boolean default: false -- alias:
Apply_Radial_Falloff_Map
<auto_secondary>.circularColorMix Float default: 0.0 --
animatable; alias: Circular_Color_Mix
<auto_secondary>.quadrant1Color Color default: (color 255 0 0) --
animatable; alias: Quadrant_1_Color
<auto_secondary>.quadrant2Color Color default: (color 255 0 0) --
animatable; alias: Quadrant_2_Color
<auto_secondary>.quadrant3Color Color default: (color 255 0 0) --
animatable; alias: Quadrant_3_Color
<auto_secondary>.quadrant4Color Color default: (color 255 0 0) --
animatable; alias: Quadrant_4_Color
<auto_secondary>.circularMtl TextureMap default: undefined -- alias:
Circular_Material
<auto_secondary>.useCircularMtl Boolean default: false -- alias:
Apply_Circular_Color_Map
<auto_secondary>.circular_falloff SubAnim
<auto_secondary>.circularMap TextureMap default: undefined -- alias:
Circular_Falloff_Map
<auto_secondary>.useCircularMap Boolean default: false -- alias:
Apply_Circular_Falloff_Map
<auto_secondary>.radial_size SubAnim
<auto_secondary>.radialSizeMap TextureMap default: undefined -- alias:
Radial_Size_Map
<auto_secondary>.useRadialSizeMap Boolean default: false -- alias:
Apply_Radial_Size_Map
<auto_secondary>.applyLights Boolean default: true -- alias:
Apply_to_Lights
<auto_secondary>.applyImage Boolean default: false -- alias:
Apply_to_Image
<auto_secondary>.applyImageCenters Boolean default: false -- alias:
Apply_to_Image_Centers
<auto_secondary>.sourceObjectID Boolean default: false -- alias:
Source_Object_ID
<auto_secondary>.objectID Integer default: 1 --
animatable; alias: Object_ID
<auto_secondary>.sourceEffectsID Boolean default: false -- alias:
Source_Effects_ID
<auto_secondary>.effectsID Integer default: 0 --
animatable; alias: Effects_ID
<auto_secondary>.sourceUnclampedColor Boolean default: false -- alias:
Source_Unclamped_Color
<auto_secondary>.unclampedColor Float default: 1.0 --
animatable; alias: Unclamped_Color
<auto_secondary>.unclampedColorInvert Boolean default: false -- alias:
Source_Unclamped_Color_Invert
<auto_secondary>.sourceSurfaceNormal Boolean default: false -- alias:
Source_Surface_Normal
1362 Chapter 11 | 3ds max Objects

<auto_secondary>.surfaceNormal Float default: 0.0 --

animatable; alias: Surface_Normal
<auto_secondary>.surfaceNormalInvert Boolean default: false -- alias:
Source_Surface_Normal_Invert
<auto_secondary>.sourceWhole Boolean default: false -- alias:
Source_Whole
<auto_secondary>.sourceAlpha Boolean default: false -- alias:
Source_Alpha
<auto_secondary>.alpha Integer default: 0
<auto_secondary>.sourceZBuffer Boolean default: false -- alias:
Source_Z_Buffer
<auto_secondary>.zHi Float default: 1000.0 --
animatable; alias: Z_Hi
<auto_secondary>.zLo Float default: 0.0 --
animatable; alias: Z_Lo
<auto_secondary>.filterAll Boolean default: true -- alias:
Filter_All
<auto_secondary>.filterEdge Boolean default: false -- alias:
Filter_Edge
<auto_secondary>.filterPerimeterAlpha Boolean default: false -- alias:
Filter_Perimeter_Alpha
<auto_secondary>.filterPerimeter Boolean default: false -- alias:
Filter_Perimeter
<auto_secondary>.filterBrightness Boolean default: false -- alias:
Filter_Brightness
<auto_secondary>.brightness Integer default: 0 --
animatable; alias: Bright
<auto_secondary>.brightnessInvert Boolean default: false -- alias:
Filter_Brightness_Invert
<auto_secondary>.filterHue Boolean default: false -- alias:
Filter_Hue
<auto_secondary>.hueRange Integer default: 0 --
animatable; alias: Hue_Range
<auto_secondary>.hue Color default: (color 255 0 0) --
animatable
<auto_secondary>.applyNoise Boolean default: false -- alias:
Apply_Additional_Effects
<auto_secondary>.noiseMap TextureMap default: undefined -- alias:
Noise_Map
<auto_secondary>.radial_density SubAnim
<auto_secondary>.radialDensity TextureMap default: undefined -- alias:
Radial_Density_Map
<auto_secondary>.useRadialDensity Boolean default: false -- alias:
Apply_Radial_Density_Map

<auto_secondary.radial_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
 Lens_Effects - Glow 1363

<auto_secondary.circular_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the circular_falloff curve. You cannot create or
access points in this curve unless the point is animated. In this case, you can access the
animated point position as a SubAnim of the curve_1 property.
<auto_secondary.radial_size>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_size curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
<auto_secondary.radial_density>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_density curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
Note:
The le.addASec <Lens_Effects> method returns true if the addition was successful, false if
it failed. Once the element has been added, it can be accessed as a property of the lens_effects
value. The name of this property for auto_secondary elements is auto_secondary. If more than
one element of the same type is added, only the first is accessible using the property name. You will
need to access the remaining elements as subAnims of the lens_effects value. The subAnim
names are the same as the property names. The elements start at subAnim 7.

See also
Lens_Effects : RenderEffect (p. 1357)
Value Common Properties, Operators, and Methods (p. 714)

Lens_Effects - Glow
Constructor:
le.addGlow <Lens_Effects>

Properties:
<glow>.elementName String default: “Glow” -- alias: Name
<glow>.on Boolean default: true
<glow>.size Float default: 30.0 -- animatable
<glow>.intensity Float default: 110.0 -- animatable
<glow>.objectsHide Boolean default: true -- alias: Object_Hide
<glow>.occlusion Float default: 100.0 -- animatable
<glow>.squeeze Boolean default: false
<glow>.useSourceColor Float default: 0.0 -- animatable; alias:
Source_Color
<glow>.centerColor Color default: (color 255 255 255) --
animatable; alias: Center_Color
<glow>.edgeColor Color default: (color 255 0 0) -- animatable;
alias: Edge_Color
1364 Chapter 11 | 3ds max Objects

<glow>.radialMtl TextureMap default: undefined -- alias:

Radial_Material
<glow>.useRadialMtl Boolean default: false -- alias:
Apply_Radial_Color_Map
<glow>.radial_falloff SubAnim
<glow>.radialMap TextureMap default: undefined -- alias:
Radial_Falloff_Map
<glow>.useRadialMap Boolean default: false -- alias:
Apply_Radial_Falloff_Map
<glow>.circularColorMix Float default: 0.0 -- animatable; alias:
Circular_Color_Mix
<glow>.quadrant1Color Color default: (color 255 0 0) -- animatable;
alias: Quadrant_1_Color
<glow>.quadrant2Color Color default: (color 255 0 0) -- animatable;
alias: Quadrant_2_Color
<glow>.quadrant3Color Color default: (color 255 0 0) -- animatable;
alias: Quadrant_3_Color
<glow>.quadrant4Color Color default: (color 255 0 0) -- animatable;
alias: Quadrant_4_Color
<glow>.circularMtl TextureMap default: undefined -- alias:
Circular_Material
<glow>.useCircularMtl Boolean default: false -- alias:
Apply_Circular_Color_Map
<glow>.circular_falloff SubAnim
<glow>.circularMap TextureMap default: undefined -- alias:
Circular_Falloff_Map
<glow>.useCircularMap Boolean default: false -- alias:
Apply_Circular_Falloff_Map
<glow>.radial_size SubAnim
<glow>.radialSizeMap TextureMap default: undefined -- alias:
Radial_Size_Map
<glow>.useRadialSizeMap Boolean default: false -- alias:
Apply_Radial_Size_Map
<glow>.applyLights Boolean default: true -- alias:
Apply_to_Lights
<glow>.applyImage Boolean default: true -- alias:
Apply_to_Image
<glow>.applyImageCenters Boolean default: false -- alias:
Apply_to_Image_Centers
<glow>.sourceObjectID Boolean default: false -- alias:
Source_Object_ID
<glow>.objectID Integer default: 1 -- animatable; alias:
Object_ID
<glow>.sourceEffectsID Boolean default: false -- alias:
Source_Effects_ID
<glow>.effectsID Integer default: 1 -- animatable; alias:
Effects_ID
<glow>.sourceUnclampedColor Boolean default: false -- alias:
Source_Unclamped_Color
<glow>.unclampedColor Float default: 1.0 -- animatable; alias:
Unclamped_Color
 Lens_Effects - Glow 1365

<glow>.unclampedColorInvert Boolean default: false -- alias:

Source_Unclamped_Color_Invert
<glow>.sourceSurfaceNormal Boolean default: false -- alias:
Source_Surface_Normal
<glow>.surfaceNormal Float default: 0.0 -- animatable; alias:
Surface_Normal
<glow>.surfaceNormalInvert Boolean default: false -- alias:
Source_Surface_Normal_Invert
<glow>.sourceWhole Boolean default: false -- alias:
Source_Whole
<glow>.sourceAlpha Boolean default: false -- alias:
Source_Alpha
<glow>.alpha Integer default: 0 -- animatable
<glow>.sourceZBuffer Boolean default: false -- alias:
Source_Z_Buffer
<glow>.zHi Float default: 1000.0 -- animatable; alias:
Z_Hi
<glow>.zLo Float default: 0.0 -- animatable; alias:
Z_Lo
<glow>.filterAll Boolean default: true -- alias: Filter_All
<glow>.filterEdge Boolean default: false -- alias: Filter_Edge
<glow>.filterPerimeterAlpha Boolean default: false -- alias:
Filter_Perimeter_Alpha
<glow>.filterPerimeter Boolean default: false -- alias:
Filter_Perimeter
<glow>.filterBrightness Boolean default: false -- alias:
Filter_Brightness
<glow>.brightness Integer default: 0 -- animatable; alias:
Bright
<glow>.brightnessInvert Boolean default: false -- alias:
Filter_Brightness_Invert
<glow>.filterHue Boolean default: false -- alias: Filter_Hue
<glow>.hueRange Integer default: 0 -- animatable; alias:
Hue_Range
<glow>.hue Color default: (color 255 0 0) -- animatable
<glow>.applyNoise Boolean default: false -- alias:
Apply_Additional_Effects
<glow>.noiseMap TextureMap default: undefined -- alias: Noise_Map
<glow>.radial_density SubAnim
<glow>.radialDensity TextureMap default: undefined -- alias:
Radial_Density_Map
<glow>.useRadialDensity Boolean default: false -- alias:
Apply_Radial_Density_Map

<glow.radial_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
1366 Chapter 11 | 3ds max Objects

<glow.circular_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the circular_falloff curve. You cannot create or
access points in this curve unless the point is animated. In this case, you can access the
animated point position as a SubAnim of the curve_1 property.
<glow.radial_size>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_size curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
<glow.radial_density>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_density curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
Note:
The le.addGlow <Lens_Effects> method returns true if the addition was successful, false if
it failed. Once the element has been added, it can be accessed as a property of the lens_effects
value. The name of this property for glow elements is glow. If more than one element of the same
type is added, only the first is accessible using the property name. You will need to access the
remaining elements as subAnims of the lens_effects value. The subAnim names are the same as
the property names. The elements start at subAnim 7.

See also
Lens_Effects : RenderEffect (p. 1357)
Value Common Properties, Operators, and Methods (p. 714)

Lens_Effects - Manual_Secondary
Constructor:
le.addMSec <Lens_Effects>

Properties:
<manual_secondary>.elementName String default: “Manual
Secondary” -- alias: Name
<manual_secondary>.on Boolean default: true
<manual_secondary>.size Float default: 50.0 --
animatable
<manual_secondary>.intensity Float default: 30.0 --
animatable
<manual_secondary>.plane Float default: 150.0 --
animatable
<manual_secondary>.colorSource Float default: 20.0 --
animatable; alias: Source_Color
<manual_secondary>.sides Integer default: 0
sides = 0 - Circular; 1 - Three; 2 - Four; 3 - Five; 4 - Six; 5 - Seven; 6 - Eight
 Lens_Effects - Manual_Secondary 1367

<manual_secondary>.occlusion Float default: 100.0 --

animatable
<manual_secondary>.squeeze Boolean default: false
<manual_secondary>.presets Integer default: 0
presets selects a preset from the indexed list. presets = 0 - no preset.
<manual_secondary>.radialColor1 Color default: (color 0 0 0) --
animatable; alias: Radial_Color_1
<manual_secondary>.radialColor2 Color default: (color 57 34 89) --
animatable; alias: Radial_Color_2
<manual_secondary>.radialColor3 Color default: (color 85 139 85) --
animatable; alias: Radial_Color_3
<manual_secondary>.radialColor4 Color default: (color 190 99 10) --
animatable; alias: Radial_Color_4
<manual_secondary>.colorRadius1 Float default: 90.0 --
animatable; alias: Radius_Color_1
<manual_secondary>.colorRadius2 Float default: 92.0 --
animatable; alias: Radius_Color_2
<manual_secondary>.colorRadius3 Float default: 95.0 --
animatable; alias: Radius_Color_3
<manual_secondary>.colorRadius4 Float default: 98.0 --
animatable; alias: Radius_Color_4
<manual_secondary>.radialMtl TextureMap default: undefined -- alias:
Radial_Material
<manual_secondary>.useRadialMtl Boolean default: false -- alias:
Apply_Radial_Color_Map
<manual_secondary>.radial_falloff SubAnim
<manual_secondary>.radialMap TextureMap default: undefined -- alias:
Radial_Falloff_Map
<manual_secondary>.useRadialMap Boolean default: false -- alias:
Apply_Radial_Falloff_Map
<manual_secondary>.circularColorMix Float default: 0.0 --
animatable; alias: Circular_Color_Mix
<manual_secondary>.quadrant1Color Color default: (color 255 0 0) --
animatable; alias: Quadrant_1_Color
<manual_secondary>.quadrant2Color Color default: (color 255 0 0) --
animatable; alias: Quadrant_2_Color
<manual_secondary>.quadrant3Color Color default: (color 255 0 0) --
animatable; alias: Quadrant_3_Color
<manual_secondary>.quadrant4Color Color default: (color 255 0 0) --
animatable; alias: Quadrant_4_Color
<manual_secondary>.circularMtl TextureMap default: undefined -- alias:
Circular_Material
<manual_secondary>.useCircularMtl Boolean default: false -- alias:
Apply_Circular_Color_Map
<manual_secondary>.circular_falloff SubAnim
<manual_secondary>.circularMap TextureMap default: undefined -- alias:
Circular_Falloff_Map
<manual_secondary>.useCircularMap Boolean default: false -- alias:
Apply_Circular_Falloff_Map
<manual_secondary>.radial_size SubAnim
1368 Chapter 11 | 3ds max Objects

<manual_secondary>.radialSizeMap TextureMap default: undefined -- alias:

Radial_Size_Map
<manual_secondary>.useRadialSizeMap Boolean default: false -- alias:
Apply_Radial_Size_Map
<manual_secondary>.applyLights Boolean default: true -- alias:
Apply_to_Lights
<manual_secondary>.applyImage Boolean default: false -- alias:
Apply_to_Image
<manual_secondary>.applyImageCenters Boolean default: false -- alias:
Apply_to_Image_Centers
<manual_secondary>.sourceObjectID Boolean default: false -- alias:
Source_Object_ID
<manual_secondary>.objectID Integer default: 1 --
animatable; alias: Object_ID
<manual_secondary>.sourceEffectsID Boolean default: false -- alias:
Source_Effects_ID
<manual_secondary>.effectsID Integer default: 0 --
animatable; alias: Effects_ID
<manual_secondary>.sourceUnclampedColor Boolean default: false -- alias:
Source_Unclamped_Color
<manual_secondary>.unclampedColor Float default: 1.0 --
animatable; alias: Unclamped_Color
<manual_secondary>.unclampedColorInvert Boolean default: false -- alias:
Source_Unclamped_Color_Invert
<manual_secondary>.sourceSurfaceNormal Boolean default: false -- alias:
Source_Surface_Normal
<manual_secondary>.surfaceNormal Float default: 0.0 --
animatable; alias: Surface_Normal
<manual_secondary>.surfaceNormalInvert Boolean default: false -- alias:
Source_Surface_Normal_Invert
<manual_secondary>.sourceWhole Boolean default: false -- alias:
Source_Whole
<manual_secondary>.sourceAlpha Boolean default: false -- alias:
Source_Alpha
<manual_secondary>.alpha Integer default: 0
<manual_secondary>.sourceZBuffer Boolean default: false -- alias:
Source_Z_Buffer
<manual_secondary>.zHi Float default: 1000.0 --
animatable; alias: Z_Hi
<manual_secondary>.zLo Float default: 0.0 --
animatable; alias: Z_Lo
<manual_secondary>.filterAll Boolean default: true -- alias:
Filter_All
<manual_secondary>.filterEdge Boolean default: false -- alias:
Filter_Edge
<manual_secondary>.filterPerimeterAlpha Boolean default: false -- alias:
Filter_Perimeter_Alpha
<manual_secondary>.filterPerimeter Boolean default: false -- alias:
Filter_Perimeter
<manual_secondary>.filterBrightness Boolean default: false -- alias:
Filter_Brightness
 Lens_Effects - Manual_Secondary 1369

<manual_secondary>.brightness Integer default: 0 --

animatable; alias: Bright
<manual_secondary>.brightnessInvert Boolean default: false -- alias:
Filter_Brightness_Invert
<manual_secondary>.filterHue Boolean default: false -- alias:
Filter_Hue
<manual_secondary>.hueRange Integer default: 0 --
animatable; alias: Hue_Range
<manual_secondary>.hue Color default: (color 255 0 0) --
animatable
<manual_secondary>.applyNoise Boolean default: false -- alias:
Apply_Additional_Effects
<manual_secondary>.noiseMap TextureMap default: undefined -- alias:
Noise_Map
<manual_secondary>.radial_density SubAnim
<manual_secondary>.radialDensity TextureMap default: undefined -- alias:
Radial_Density_Map
<manual_secondary>.useRadialDensity Boolean default: false -- alias:
Apply_Radial_Density_Map

<manual_secondary.radial_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
<manual_secondary.circular_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the circular_falloff curve. You cannot create or
access points in this curve unless the point is animated. In this case, you can access the
animated point position as a SubAnim of the curve_1 property.
<manual_secondary.radial_size>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_size curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
<manual_secondary.radial_density>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_density curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
Note:
The le.addMSec <Lens_Effects> method returns true if the addition was successful, false if
it failed. Once the element has been added, it can be accessed as a property of the lens_effects
value. The name of this property for manual_secondary elements is manual_secondary. If more
than one element of the same type is added, only the first is accessible using the property name. You
will need to access the remaining elements as subAnims of the lens_effects value. The subAnim
names are the same as the property names. The elements start at subAnim 7.
1370 Chapter 11 | 3ds max Objects

See also
Lens_Effects : RenderEffect (p. 1357)
Value Common Properties, Operators, and Methods (p. 714)

Lens_Effects - Ray
Constructor:
le.addRay <Lens_Effects>

Properties:
<ray>.elementName String default: “Ray” -- alias: Name
<ray>.on Boolean default: true
<ray>.size Float default: 300.0 -- animatable
<ray>.intensity Float default: 10.0 -- animatable
<ray>.number Integer default: 100 -- animatable; alias:
Quantity
<ray>.angle Float default: 0.0 -- animatable
<ray>.sharpness Float default: 8.0 -- animatable
<ray>.objectsHide Boolean default: false
<ray>.occlusion Float default: 100.0 -- animatable
<ray>.squeeze Boolean default: false
<ray>.colorSource Float default: 100.0 -- animatable; alias:
Source_Color
<ray>.centerColor Color default: (color 255 255 255) -- animatable;
alias: Center_Color
<ray>.edgeColor Color default: (color 255 0 0) -- animatable;
alias: Edge_Color
<ray>.radialMtl TextureMap default: undefined -- alias:
Radial_Material
<ray>.useRadialMtl Boolean default: false -- alias:
Apply_Radial_Color_Map
<ray>.radial_falloff SubAnim
<ray>.radialMap TextureMap default: undefined -- alias:
Radial_Falloff_Map
<ray>.useRadialMap Boolean default: false -- alias:
Apply_Radial_Falloff_Map
<ray>.circularColorMix Float default: 0.0 -- animatable; alias:
Circular_Color_Mix
<ray>.quadrant1Color Color default: (color 255 0 0) -- animatable;
alias: Quadrant_1_Color
<ray>.quadrant2Color Color default: (color 255 0 0) -- animatable;
alias: Quadrant_2_Color
<ray>.quadrant3Color Color default: (color 255 0 0) -- animatable;
alias: Quadrant_3_Color
<ray>.quadrant4Color Color default: (color 255 0 0) -- animatable;
alias: Quadrant_4_Color
<ray>.circularMtl TextureMap default: undefined
Circular_Material
 Lens_Effects - Ray 1371

<ray>.useCircularMtl Boolean default: false -- alias:

Apply_Circular_Color_Map
<ray>.circular_falloff SubAnim
<ray>.circularMap TextureMap default: undefined -- alias:
Circular_Falloff_Map
<ray>.useCircularMap Boolean default: false -- alias:
Apply_Circular_Falloff_Map
<ray>.radial_size SubAnim
<ray>.radialSizeMap TextureMap default: undefined -- alias:
Radial_Size_Map
<ray>.useRadialSizeMap Boolean default: false -- alias:
Apply_Radial_Size_Map
<ray>.applyLights Boolean default: true -- alias:
Apply_to_Lights
<ray>.applyImage Boolean default: true -- alias:
Apply_to_Image
<ray>.applyImageCenters Boolean default: false -- alias:
Apply_to_Image_Centers
<ray>.sourceObjectID Boolean default: false -- alias:
Source_Object_ID
<ray>.objectID Integer default: 1 -- animatable; alias:
Object_ID
<ray>.sourceEffectsID Boolean default: false -- alias:
Source_Effects_ID
<ray>.effectsID Integer default: 1 -- animatable; alias:
Effects_ID
<ray>.sourceUnclampedColor Boolean default: false -- alias:
Source_Unclamped_Color
<ray>.unclampedColor Float default: 1.0 -- animatable; alias:
Unclamped_Color
<ray>.unclampedColorInvert Boolean default: false -- alias:
Source_Unclamped_Color_Invert
<ray>.sourceSurfaceNormal Boolean default: false -- alias:
Source_Surface_Normal
<ray>.surfaceNormal Float default: 0.0 -- animatable; alias:
Surface_Normal
<ray>.surfaceNormalInvert Boolean default: false -- alias:
Source_Surface_Normal_Invert
<ray>.sourceWhole Boolean default: false -- alias: Source_Whole
<ray>.sourceAlpha Boolean default: false -- alias: Source_Alpha
<ray>.alpha Integer default: 0 -- animatable
<ray>.sourceZBuffer Boolean default: false -- alias:
Source_Z_Buffer
<ray>.zHi Float default: 1000.0 -- animatable; alias:
Z_Hi
<ray>.zLo Float default: 0.0 -- animatable; alias:
Z_Lo
<ray>.filterAll Boolean default: true -- alias: Filter_All
<ray>.filterEdge Boolean default: false -- alias: Filter_Edge
<ray>.filterPerimeterAlpha Boolean default: false -- alias:
Filter_Perimeter_Alpha
1372 Chapter 11 | 3ds max Objects

<ray>.filterPerimeter Boolean default: false -- alias:

Filter_Perimeter
<ray>.filterBrightness Boolean default: false -- alias:
Filter_Brightness
<ray>.brightness Integer default: 0 -- animatable; alias:
Bright
<ray>.brightnessInvert Boolean default: false -- alias:
Filter_Brightness_Invert
<ray>.filterHue Boolean default: false -- alias: Filter_Hue
<ray>.hueRange Integer default: 0 -- animatable; alias:
Hue_Range
<ray>.hue Color default: (color 255 0 0) -- animatable
<ray>.applyNoise Boolean default: false -- alias:
Apply_Additional_Effects
<ray>.noiseMap TextureMap default: undefined -- alias: Noise_Map
<ray>.radial_density SubAnim
<ray>.radialDensity TextureMap default: undefined -- alias:
Radial_Density_Map
<ray>.useRadialDensity Boolean default: false -- alias:
Apply_Radial_Density_Map

<ray.radial_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
<ray.circular_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the circular_falloff curve. You cannot create or
access points in this curve unless the point is animated. In this case, you can access the
animated point position as a SubAnim of the curve_1 property.
<ray.radial_size>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_size curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
<ray.radial_density>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_density curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
Note:
The le.addRay <Lens_Effects> method returns true if the addition was successful, false if it
failed. Once the element has been added, it can be accessed as a property of the lens_effects
value. The name of this property for ray elements is ray. If more than one element of the same type
is added, only the first is accessible using the property name. You will need to access the remaining
elements as subAnims of the lens_effects value. The subAnim names are the same as the property
names. The elements start at subAnim 7.
 Lens_Effects - Ring 1373

See also
Lens_Effects : RenderEffect (p. 1357)
Value Common Properties, Operators, and Methods (p. 714)

Lens_Effects - Ring
Constructor:
le.addRing <Lens_Effects>

Properties:
<ring>.elementName String default: “Ring” -- alias: Name
<ring>.on Boolean default: true
<ring>.size Float default: 75.0 -- animatable
<ring>.intensity Float default: 75.0 -- animatable
<ring>.plane Float default: 0.0 -- animatable
<ring>.thickness Float default: 10.0 -- animatable
<ring>.objectsHide Boolean default: false -- alias: Object_Hide
<ring>.occlusion Float default: 100.0 -- animatable
<ring>.squeeze Boolean default: false
<ring>.colorSource Float default: 0.0 -- animatable; alias:
Source_Color
<ring>.centerColor Color default: (color 255 255 255) --
animatable; alias: Center_Color
<ring>.edgeColor Color default: (color 255 0 0) -- animatable;
alias: Edge_Color
<ring>.radialMtl TextureMap default: undefined -- alias:
Radial_Material
<ring>.useRadialMtl Boolean default: false -- alias:
Apply_Radial_Color_Map
<ring>.radial_falloff SubAnim
<ring>.radialMap TextureMap default: undefined -- alias:
Radial_Falloff_Map
<ring>.useRadialMap Boolean default: false -- alias:
Apply_Radial_Falloff_Map
<ring>.circularColorMix Float default: 0.0 -- animatable; alias:
Circular_Color_Mix
<ring>.quadrant1Color Color default: (color 255 0 0) -- animatable;
alias: Quadrant_1_Color
<ring>.quadrant2Color Color default: (color 255 0 0) -- animatable;
alias: Quadrant_2_Color
<ring>.quadrant3Color Color default: (color 255 0 0) -- animatable;
alias: Quadrant_3_Color
<ring>.quadrant4Color Color default: (color 255 0 0) -- animatable;
alias: Quadrant_4_Color
<ring>.circularMtl TextureMap default: undefined -- alias:
Circular_Material
<ring>.useCircularMtl Boolean default: false -- alias:
Apply_Circular_Color_Map
<ring>.circular_falloff SubAnim
1374 Chapter 11 | 3ds max Objects

<ring>.circularMap TextureMap default: undefined -- alias:

Circular_Falloff_Map
<ring>.useCircularMap Boolean default: false -- alias:
Apply_Circular_Falloff_Map
<ring>.radial_size SubAnim
<ring>.radialSizeMap TextureMap default: undefined -- alias:
Radial_Size_Map
<ring>.useRadialSizeMap Boolean default: false -- alias:
Apply_Radial_Size_Map
<ring>.applyLights Boolean default: true -- alias:
Apply_to_Lights
<ring>.applyImage Boolean default: true -- alias:
Apply_to_Image
<ring>.applyImageCenters Boolean default: false -- alias:
Apply_to_Image_Centers
<ring>.sourceObjectID Boolean default: false -- alias:
Source_Object_ID
<ring>.objectID Integer default: 1 -- animatable; alias:
Object_ID
<ring>.sourceEffectsID Boolean default: false -- alias:
Source_Effects_ID
<ring>.effectsID Integer default: 1 -- animatable; alias:
Effects_ID
<ring>.sourceUnclampedColor Boolean default: false -- alias:
Source_Unclamped_Color
<ring>.unclampedColor Float default: 1.0 -- animatable; alias:
Unclamped_Color
<ring>.unclampedColorInvert Boolean default: false -- alias:
Source_Unclamped_Color_Invert
<ring>.sourceSurfaceNormal Boolean default: false -- alias:
Source_Surface_Normal
<ring>.surfaceNormal Float default: 0.0 -- animatable; alias:
Surface_Normal
<ring>.surfaceNormalInvert Boolean default: false -- alias:
Source_Surface_Normal_Invert
<ring>.sourceWhole Boolean default: false -- alias:
Source_Whole
<ring>.sourceAlpha Boolean default: false -- alias:
Source_Alpha
<ring>.alpha Integer default: 0 -- animatable
<ring>.sourceZBuffer Boolean default: false -- alias:
Source_Z_Buffer
<ring>.zHi Float default: 1000.0 -- animatable; alias:
Z_Hi
<ring>.zLo Float default: 0.0 -- animatable; alias:
Z_Lo
<ring>.filterAll Boolean default: true -- alias: Filter_All
<ring>.filterEdge Boolean default: false -- alias: Filter_Edge
<ring>.filterPerimeterAlpha Boolean default: false -- alias:
Filter_Perimeter_Alpha
 Lens_Effects - Ring 1375

<ring>.filterPerimeter Boolean default: false -- alias:

Filter_Perimeter
<ring>.filterBrightness Boolean default: false -- alias:
Filter_Brightness
<ring>.brightness Integer default: 0 -- animatable; alias:
Bright
<ring>.brightnessInvert Boolean default: false -- alias:
Filter_Brightness_Invert
<ring>.filterHue Boolean default: false -- alias: Filter_Hue
<ring>.hueRange Integer default: 0 -- animatable; alias:
Hue_Range
<ring>.hue Color default: (color 255 0 0) -- animatable
<ring>.applyNoise Boolean default: false -- alias:
Apply_Additional_Effects
<ring>.noiseMap TextureMap default: undefined -- alias: Noise_Map
<ring>.radial_density SubAnim
<ring>.radialDensity TextureMap default: undefined -- alias:
Radial_Density_Map
<ring>.useRadialDensity Boolean default: false -- alias:
Apply_Radial_Density_Map

<ring.radial_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
<ring.circular_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the circular_falloff curve. You cannot create or
access points in this curve unless the point is animated. In this case, you can access the
animated point position as a SubAnim of the curve_1 property.
<ring.radial_size>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_size curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
<ring.radial_density>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_density curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
Note:
The le.addRing <Lens_Effects> method returns true if the addition was successful, false if
it failed. Once the element has been added, it can be accessed as a property of the lens_effects
value. The name of this property for ring elements is ring. If more than one element of the same
type is added, only the first is accessible using the property name. You will need to access the
remaining elements as subAnims of the lens_effects value. The subAnim names are the same as
the property names. The elements start at subAnim 7.
1376 Chapter 11 | 3ds max Objects

See also
Lens_Effects : RenderEffect (p. 1357)
Value Common Properties, Operators, and Methods (p. 714)

Lens_Effects - Star
Constructor:
le.addStar <Lens_Effects>

Properties:
<star>.elementName String default: “Star” -- alias: Name
<star>.on Boolean default: true
<star>.size Float default: 200.0 -- animatable
<star>.intensity Float default: 20.0 -- animatable
<star>.width Float default: 8.0 -- animatable
<star>.angle Float default: 0.0 -- animatable
<star>.taper Float default: 0.5 -- animatable
<star>.sharp Float default: 9.5 -- animatable; alias:
Sharpness
<star>.quantity Integer default: 6 -- animatable
<star>.objectsHide Boolean default: false -- alias: Object_Hide
<star>.occlusion Float default: 50.0 -- animatable
<star>.squeeze Boolean default: false
<star>.colorSource Float default: 100.0 -- animatable; alias:
Source_Color
<star>.centerColor Color default: (color 0 0 255) -- animatable;
alias: Center_Color
<star>.edgeColor Color default: (color 255 255 255) --
animatable; alias: Edge_Color
<star>.radialMtl TextureMap default: undefined -- alias:
Radial_Material
<star>.useRadialMtl Boolean default: false -- alias:
Apply_Radial_Color_Map
<star>.radial_falloff SubAnim
<star>.radialMap TextureMap default: undefined -- alias:
Radial_Falloff_Map
<star>.useRadialMap Boolean default: false -- alias:
Apply_Radial_Falloff_Map
<star>.circularColorMix Float default: 0.0 -- animatable; alias:
Circular_Color_Mix
<star>.leftSectionColor Color default: (color 0 0 255) -- animatable;
alias: Left_Section_Color
<star>.centerSectionColor Color default: (color 255 255 255) --
animatable; alias: Center_Section_Color
<star>.rightSectionColor Color default: (color 0 0 255) -- animatable;
alias: Right_Section_Color
<star>.circularMtl TextureMap default: undefined -- alias:
Circular_Material
 Lens_Effects - Star 1377

<star>.useCircularMtl Boolean default: false -- alias:

Apply_Circular_Color_Map
<star>.circular_falloff SubAnim
<star>.circularMap TextureMap default: undefined -- alias:
Circular_Falloff_Map
<star>.useCircularMap Boolean default: false -- alias:
Apply_Circular_Falloff_Map
<star>.radial_size SubAnim
<star>.radialSizeMap TextureMap default: undefined -- alias:
Radial_Size_Map
<star>.useRadialSizeMap Boolean default: false -- alias:
Apply_Radial_Size_Map
<star>.applyLights Boolean default: true -- alias:
Apply_to_Lights
<star>.applyImage Boolean default: true -- alias:
Apply_to_Image
<star>.applyImageCenters Boolean default: false -- alias:
Apply_to_Image_Centers
<star>.sourceObjectID Boolean default: false -- alias:
Source_Object_ID
<star>.objectID Integer default: 1 -- animatable; alias:
Object_ID
<star>.sourceEffectsID Boolean default: false -- alias:
Source_Effects_ID
<star>.effectsID Integer default: 1 -- animatable; alias:
Effects_ID
<star>.sourceUnclampedColor Boolean default: false -- alias:
Source_Unclamped_Color
<star>.unclampedColor Float default: 1.0 -- animatable; alias:
Unclamped_Color
<star>.unclampedColorInvert Boolean default: false -- alias:
Source_Unclamped_Color_Invert
<star>.sourceSurfaceNormal Boolean default: false -- alias:
Source_Surface_Normal
<star>.surfaceNormal Float default: 0.0 -- animatable; alias:
Surface_Normal
<star>.surfaceNormalInvert Boolean default: false -- alias:
Source_Surface_Normal_Invert
<star>.sourceWhole Boolean default: false -- alias:
Source_Whole
<star>.sourceAlpha Boolean default: false -- alias:
Source_Alpha
<star>.alpha Integer default: 0 -- animatable
<star>.sourceZBuffer Boolean default: false -- alias:
Source_Z_Buffer
<star>.zHi Float default: 1000.0 -- animatable; alias:
Z_Hi
<star>.zLo Float default: 0.0 -- animatable; alias:
Z_Lo
<star>.filterAll Boolean default: true -- alias: Filter_All
<star>.filterEdge Boolean default: false -- alias: Filter_Edge
1378 Chapter 11 | 3ds max Objects

<star>.filterPerimeterAlpha Boolean default: false -- alias:

Filter_Perimeter_Alpha
<star>.filterPerimeter Boolean default: false -- alias:
Filter_Perimeter
<star>.filterBrightness Boolean default: false -- alias:
Filter_Brightness
<star>.brightness Integer default: 0 -- animatable; alias:
Bright
<star>.brightnessInvert Boolean default: false -- alias:
Filter_Brightness_Invert
<star>.filterHue Boolean default: false -- alias: Filter_Hue
<star>.hueRange Integer default: 0 -- animatable; alias:
Hue_Range
<star>.hue Color default: (color 255 0 0) -- animatable
<star>.applyNoise Boolean default: false -- alias:
Apply_Additional_Effects
<star>.noiseMap TextureMap default: undefined -- alias: Noise_Map
<star>.radial_density SubAnim
<star>.radialDensity TextureMap default: undefined -- alias:
Radial_Density_Map
<star>.useRadialDensity Boolean default: false -- alias:
Apply_Radial_Density_Map

<star.radial_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
<star.circular_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the circular_falloff curve. You cannot create or
access points in this curve unless the point is animated. In this case, you can access the
animated point position as a SubAnim of the curve_1 property.
<star.radial_size>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_size curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
<star.radial_density>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_density curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
Note:
The le.addStar <Lens_Effects> method returns true if the addition was successful, false if
it failed. Once the element has been added, it can be accessed as a property of the lens_effects
value. The name of this property for star elements is star. If more than one element of the same
type is added, only the first is accessible using the property name. You will need to access the
remaining elements as subAnims of the lens_effects value. The subAnim names are the same as
the property names. The elements start at subAnim 7.
 Lens_Effects - Streak 1379

See also
Lens_Effects : RenderEffect (p. 1357)
Value Common Properties, Operators, and Methods (p. 714)

Lens_Effects - Streak
Constructor:
le.addStreak <Lens_Effects>

Properties:
<streak>.elementName String default: “Streak” -- alias: Name
<streak>.on Boolean default: true
<streak>.size Float default: 50.0 -- animatable
<streak>.intensity Float default: 30.0 -- animatable
<streak>.width Float default: 2.0 -- animatable
<streak>.angle Float default: 0.0 -- animatable
<streak>.taper Float default: 0.5 -- animatable
<streak>.sharp Float default: 9.8 -- animatable;
alias: Sharpness
<streak>.objectsHide Boolean default: false -- alias:
Object_Hide
<streak>.occlusion Float default: 100.0 -- animatable
<streak>.squeeze Boolean default: false
<streak>.colorSource Float default: 100.0 -- animatable;
alias: Source_Color
<streak>.centerColor Color default: (color 0 0 255) -- animatable;
alias: Center_Color
<streak>.edgeColor Color default: (color 255 255 255) --
animatable; alias: Edge_Color
<streak>.radialMtl TextureMap default: undefined -- alias:
Radial_Material
<streak>.useRadialMtl Boolean default: false -- alias:
Apply_Radial_Color_Map
<streak>.radial_falloff SubAnim
<streak>.radialMap TextureMap default: undefined -- alias:
Radial_Falloff_Map
<streak>.useRadialMap Boolean default: false -- alias:
Apply_Radial_Falloff_Map
<streak>.circularColorMix Float default: 50.0 -- animatable;
alias: Circular_Color_Mix
<streak>.quadrant1Color Color default: (color 0 0 0) -- animatable;
alias: Left_Section_Color
<streak>.quadrant2Color Color default: (color 255 255 255) --
animatable; alias: Center_Section_Color
<streak>.quadrant3Color Color default: (color 0 0 0) -- animatable;
alias: Right_Section_Color
<streak>.circularMtl TextureMap default: undefined -- alias:
Circular_Material
1380 Chapter 11 | 3ds max Objects

<streak>.useCircularMtl Boolean default: false -- alias:

Apply_Circular_Color_Map
<streak>.circular_falloff SubAnim
<streak>.circularMap TextureMap default: undefined -- alias:
Circular_Falloff_Map
<streak>.useCircularMap Boolean default: false -- alias:
Apply_Circular_Falloff_Map
<streak>.radial_size SubAnim
<streak>.radialSizeMap TextureMap default: undefined -- alias:
Radial_Size_Map
<streak>.useRadialSizeMap Boolean default: false -- alias:
Apply_Radial_Size_Map
<streak>.applyLights Boolean default: true -- alias:
Apply_to_Lights
<streak>.applyImage Boolean default: true -- alias:
Apply_to_Image
<streak>.applyImageCenters Boolean default: false -- alias:
Apply_to_Image_Centers
<streak>.sourceObjectID Boolean default: false -- alias:
Source_Object_ID
<streak>.objectID Integer default: 1 -- animatable;
alias: Object_ID
<streak>.sourceEffectsID Boolean default: false -- alias:
Source_Effects_ID
<streak>.effectsID Integer default: 1 -- animatable;
alias: Effects_ID
<streak>.sourceUnclampedColor Boolean default: false -- alias:
Source_Unclamped_Color
<streak>.unclampedColor Float default: 1.0 -- animatable;
alias: Unclamped_Color
<streak>.unclampedColorInvert Boolean default: false -- alias:
Source_Unclamped_Color_Invert
<streak>.sourceSurfaceNormal Boolean default: false -- alias:
Source_Surface_Normal
<streak>.surfaceNormal Float default: 0.0 -- animatable;
alias: Surface_Normal
<streak>.surfaceNormalInvert Boolean default: false -- alias:
Source_Surface_Normal_Invert
<streak>.sourceWhole Boolean default: false -- alias:
Source_Whole
<streak>.sourceAlpha Boolean default: false -- alias:
Source_Alpha
<streak>.alpha Integer default: 0 -- animatable
<streak>.sourceZBuffer Boolean default: false -- alias:
Source_Z_Buffer
<streak>.zHi Float default: 1000.0 -- animatable;
alias: Z_Hi
<streak>.zLo Float default: 0.0 -- animatable;
alias: Z_Lo
<streak>.filterAll Boolean default: true -- alias:
Filter_All
 Lens_Effects - Streak 1381

<streak>.filterEdge Boolean default: false -- alias:

Filter_Edge
<streak>.filterPerimeterAlpha Boolean default: false -- alias:
Filter_Perimeter_Alpha
<streak>.filterPerimeter Boolean default: false -- alias:
Filter_Perimeter
<streak>.filterBrightness Boolean default: false -- alias:
Filter_Brightness
<streak>.brightness Integer default: 0 -- animatable;
alias: Bright
<streak>.brightnessInvert Boolean default: false -- alias:
Filter_Brightness_Invert
<streak>.filterHue Boolean default: false -- alias:
Filter_Hue
<streak>.hueRange Integer default: 0 -- animatable;
alias: Hue_Range
<streak>.hue Color default: (color 255 0 0) -- animatable
<streak>.applyNoise Boolean default: false -- alias:
Apply_Additional_Effects
<streak>.noiseMap TextureMap default: undefined -- alias: Noise_Map
<streak>.radial_density SubAnim
<streak>.radialDensity TextureMap default: undefined -- alias:
Radial_Density_Map
<streak>.useRadialDensity Boolean default: false -- alias:
Apply_Radial_Density_Map

<streak.radial_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
<streak.circular_falloff>.curve_1 SubAnim
The curve_1 SubAnim contains the circular_falloff curve. You cannot create or
access points in this curve unless the point is animated. In this case, you can access the
animated point position as a SubAnim of the curve_1 property.
<streak.radial_size>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_size curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
<streak.radial_density>.curve_1 SubAnim
The curve_1 SubAnim contains the radial_density curve. You cannot create or access
points in this curve unless the point is animated. In this case, you can access the animated
point position as a SubAnim of the curve_1 property.
1382 Chapter 11 | 3ds max Objects

Note:
The le.addStreak <Lens_Effects> method returns true if the addition was successful, false
if it failed. Once the element has been added, it can be accessed as a property of the lens_effects
value. The name of this property for streak elements is streak. If more than one element of the
same type is added, only the first is accessible using the property name. You will need to access the
remaining elements as subAnims of the lens_effects value. The subAnim names are the same as
the property names. The elements start at subAnim 7.

See also
Lens_Effects : RenderEffect (p. 1357)
Value Common Properties, Operators, and Methods (p. 714)

Track View Nodes

You can access and modify controllers in the Global Tracks and Video Post sections in Track View,
and create new named global tracks. Among other things, these can be used to provide keyframeable
parameters in your scripted utilities.
There are also methods associated with the Track View window. These methods are described in the
Track View (p. 1609) topic.
MAXTVNode : Value is the class whose instances represent track view global track nodes. Each
MAXTVNode can contain any number of MAXTVNodes or animation controllers. The
MAXTVNodes and controllers within a MAXTVNode are shown as properties of the MAXTVNode
so you navigate through the nesting using property access. A MAXTVNode itself does not store
animation data, but rather acts as a container that can store one or more MAXTVNode or animation
controller.
There are three track view nodes you can access through global variables: the root node to which
you can add new custom tracks; the existing Global Tracks node which provides access to the global
track controllers; and the Video Post tracks node which provides access to any video post controllers.
These nodes are also accessible as properties on the root node.
Constructor:
trackViewNodes
Global variable containing the top-level World, or root, node in Track View. This variable
is read-only.
globalTracks
Global variable containing the top-level Global Tracks node in Track View. This variable is
read-only.
videoPostTracks
Global variable containing the top-level Video Post Track View node. This variable is read-
only. This variable contains the value undefined in 3D Studio VIZ.
 Lens_Effects - Streak 1383

newTrackViewNode [ <maxtvnode> ] <name_string> [ #hidden ]

if the <maxtvnode> argument is supplied, adds a sub-track node to it. If not, creates a new
‘top-level’ track in the Track View. If the optional #hidden flag is supplied, the node is not
visible in the Track View.
Properties:
<maxtvnode>.name String
the track view node name as it appears in Track View
The sub-tracks and sub-controllers for a track view node are also shown as properties of the
track view node. For example, the additional default properties for global
trackViewNodes are:
TrackViewNodes.Global_Tracks MAXTVNode
TrackViewNodes.Video_Post MAXTVNode

And the additional default properties for global globalTracks are:

GlobalTracks.float float_list controller
GlobalTracks.point3 point3_list controller
GlobalTracks.position position_list controller
GlobalTracks.rotation rotation_list controller
GlobalTracks.scale scale_list controller
GlobalTracks.Block_Control block_control controller

Methods:
deleteTrackViewNode [ <parent_maxtvnode> ] <maxtvnode>
deletes the given node from the supplied parent, or the top-level if the parent is not
specified
addTrackViewController <maxtvnode> <controller> <name>
adds the sub-controller to the given Track View node. The
deleteTrackViewController <maxtvnode> <controller>
deletes the controller from the given Track View node

See also
Value Common Properties, Operators, and Methods (p. 714)
1384 Chapter 11 | 3ds max Objects

Examples:
-- access a video post track
videoPost.glow.size = 5

-- set up some visible tracks for some keyframeable parameters in a rollout panel
my_tracks = newTrackViewNode “Grinner”
happy_ctrl = bezier_position()
addTrackViewController my_tracks happy_ctrl “Happy”
...
-- plant keyframes in rollout spinner handler if the animate button is on
rollout grinner ...
(
...
on happy changed val do
(
...
happy_ctrl.value = [x, y, z]
...
)
...
)

-- add a new float controller to the global tracks float controller list:
globalTracks.float.controller.available.controller = bezier_float()

Working with NURBS

This topic mirrors almost one-for-one on the NURBS API in the 3ds max SDK, so an understanding
of one will help with the other. The following topics provide you with information about the NURBS
classes and how to work with them:
Working with the NURBS Classes (p. 1385)
Overview of the Principal NURBS Classes (p. 1386)
Using the NURBS Classes and Functions to Create and Modify 3ds max NURBS Models (p. 1389)
The NURBS Classes (p. 1401)
 Working with the NURBS Classes 1385

Working with the NURBS Classes

Unlike other parts of MAXScript that let you script 3ds max scene objects directly, the NURBS family
of classes provides an indirect means of working with 3ds max NURBS objects. They allow you to
build an idealized structure representing 3ds max NURBS objects and then use this structure to
either create new or add to scene NURBS objects or to access certain parts of existing scene objects.
The structure is made up of instances of the MAXScript NURBS classes, listed in the NURBS Classes
(p. 1401) topic. The main class for this is NURBSSet. It is the structure that corresponds to a scene
NURBS object and contains a collection of NURBS items such as curves, surfaces, dependent surfaces,
points, and so on, which are themselves instances of the other MAXScript NURBS classes. You
construct a NURBSSet object describing a NURBS object and then have it be instantiated as a real
scene object. Conversely, you can ask for a NURBSSet to be created that corresponds to a given scene
NURBS object and use it to examine the component NURBS items and to modify certain properties
directly on the scene object it describes.
Parameter Validity
The 3ds max NURBS SDK methods and the corresponding MAXScript methods and properties
perform very little parameter validation. As a result, passing invalid parameters to the functions or
accessing invalid ranges will generate Assertion Failures easily. In most cases 3ds max will not crash
if Retry or Ignore is selected. An example of this is:
1. Create a CV surface and select it.
2. Enter in MAXScript:
s = getnurbsset $ #relational
obj = getobject s 1
tess = getviewtess obj #displacement

This is invalid because the viewport does not support displacement approximation, only the
production renderer does. Therefore, this will generate an Assertion Failure.
1386 Chapter 11 | 3ds max Objects

NURBSId’s and Indexes

An important concept to understand when working with NURBSSets and the other NURBS classes,
is the way you identify component items in the set. Before a NURBSet is instantiated as a scene
NURBS object, the individual curves and points and surfaces are identified by an index number. As
you append objects to the set they are assigned successive indexes, starting at 1. When you want to
refer to a particular item, for example to specify the parent surfaces in a blend surface, you use this
index. Once an object has been added to a NURBSSet, its index can determined through the .index
property. This is a read-only property.
However, once a NURBSet is associated with a scene object, either by being instantiated or because
it was directly created from an existing scene object, this index is no longer valid. Instead, a different
number, called a NURBSId, is assigned to each item and you must use that Id when referring to items
from then on. The NURBSId of any item in an instantiated NURBSSet can be obtained through the
.NURBSId property on that object.
These identifiers, indexes or NURBSId’s, are used in many places to specify the parent objects for
other dependent objects. Often, these are specified using the .parent or .parentID properties on
a dependent object. You must be sure to use the correct property depending on whether the
containing NURBSSet has been associated with a scene object or not: .parent for non-associated
NURBSSets, .parentID for associated NURBSSets. Remember that indexes used in .parent settings
are 1-based.

Overview of the Principal NURBS Classes

The diagram below shows the inheritance tree of the principal classes in the NURBS family. The base
classes are shown at the top, and the inheritance hierarchy proceeds toward the bottom and to the
right. NURBSObject (p. 1402) is the main base class, with NURBSPoint (p. 1403), NURBSControlVertex
(p. 1409), NURBSCurve (p. 1409), NURBSSurface (p. 1425), NURBSCVCurve (p. 1412), and
NURBSPointCurve (p. 1418) also functioning as base classes. Several additional classes are used with
NURBS objects, but are not part of the NURBS hierarchy. These classes are the NURBSDisplay
(p. 1447), NURBSSelection (p. 1448), NURBSSet (p. 1450), NURBSSurfaceApproximation (p. 1453), and
NURBSTextureSurface (p. 1455) classes.
 Overview of the Principal NURBS Classes 1387

NURBS Class Hierarchy

The NURBSObject class is the base NURBS class. It provides a set of properties that are common to
the other classes such as getting and setting the name of the item. It also has a NURBSId property
which is an ID used to specify a particular object in communication between the NURBS classes.
1388 Chapter 11 | 3ds max Objects

The NURBSSet class is the class used when developers want to create 3ds max NURBS objects, or
retrieve data from existing 3ds max NURBS objects. The NURBSSet acts as a container for the other
objects. This class contains a table of the various NURBSObject derived entities (points, curves,
surfaces) used to make up the set. Additionally it has two ‘fuse’ tables: one for fuse curves and one
for fuse surfaces. These are used to allow the CVs in the curves or surfaces to be ‘stitched’ or ‘fused’
together so that if one curve or surface moves the other moves with it. This class also has the surface-
approximation properties that control the object’s tessellation into triangle meshes for use in the
viewports and the production renderer.
The NURBSPoint classes describe a point in 3D space. Depending on the specific class, points can be
either independent or dependent. Independent points are those that don’t rely on other objects to
define their location. Dependent points are related to the objects they depend on such that the
relationship established initially remains if the point, curve or surface moves. For example, a point
can be created such that it always remains a certain distance from another point. The options are
XYZ-relative, along a normal, or along a tangent (or set of tangents for a surface-dependent
constrained point).
The NURBSControlVertex class defines a Control Vertex of a NURBS Curve or NURBS Surface. This
class shares may of the same properties as a NURBSPoint and has the added property of a rational
weight. The weight value of a CV is rational. That is, it is relative to other CVs in the curve or surface.
Changing the weight of all CVs at once has no effect, because this doesn’t change the ratio between
weights.
The NURBSCurve classes describe the properties of NURBS curves. As with the NURBSPoint classes,
depending on the specific class, curves can be either independent or dependent. Independent curves
are those that don’t rely on other objects to define their location. A dependent curve is an object
that depends on one or more other objects to define what it is. For example, a Blend Curve depends
on the two parent curves that it blends between when it was created (as well as on its two tension
parameters).
The NURBSSurface classes describe the properties of NURBS surfaces. As with the NURBSPoint and
NURBSCurve classes, depending on the specific class, surfaces can be either independent or
dependent. Independent surfaces are those that don’t rely on other objects to define their location.
Dependent surfaces are surface sub-objects whose geometry depends on other surfaces or curves in
the NURBS model. When you change the geometry of the original parent surface or curve, the
dependent surface changes as well.
 Creating New NURBS Objects 1389

Using the NURBS Classes and Functions to Create and

Modify 3ds max NURBS Models
For NURBS objects in the scene, 3ds max uses a different internal representation of NURBS objects
than the MAXScript and SDK classes do. These MAXScript and SDK classes are simply a means to
access these internal 3ds max NURBS objects and allow them to be manipulated.
The object used in communication between the internal 3ds max NURBS objects and the classes in
MAXScript available to work with these objects is the NURBSSet (p. 1450). There are also two
functions used in this communication. The first is the constructor NURBSNode() and the second is
a node method, getNURBSSet(). How these are used is described in the following topics:
Creating New NURBS Objects (p. 1389)
Modifying Existing NURBS Objects (p. 1390)
Parameter Ranges for Curves and Surfaces (p. 1391)
Materials Assignment and Texture Coordinates (p. 1391)
Creating NURBS Scene Objects (p. 1392)
Creating NURBSCVSurface Values (p. 1394)
NURBS Node Properties and Methods (p. 1397)

Creating New NURBS Objects

The NURBS classes can be used to create new NURBS scene objects. This is done by adding the
objects (points, curves and surfaces) to an item called a NURBSSet and passing it to the function
NURBSNode(). The NURBSSet is a container for the objects that define each element in the scene
NURBS object. The function NURBSNode() makes an internal 3ds max NURBS object from the
specifications in the set. The function NURBSNode() is documented in the Creating NURBS Scene
Objects (p. 1392) topic.
As an example, consider the following code fragment that creates a NURBSCVCurve object (with
NURBSControlVertex sub-objects) and puts it in the scene:
Script:
-- create an empty NURBSSet object
nset = NURBSSet ()
-- create a new NURBSCVCurve and set the knots and CVs
c = NURBSCVCurve name:”CV Curve” order:4 numCVs:4 numKnots:8
for k in 1 to 4 do ( setKnot c k 0; setKnot c (k+4) 1 )
cv = NURBSControlVertex [0, 0, 50]
setCV c 1 cv
cv.pos = [-100, 0, 50]
setCV c 2 cv
cv.pos = [-100, 100, 50]
setCV c 3 cv
cv.pos = [0, 100, 50]
setCV c 4 cv
1390 Chapter 11 | 3ds max Objects

-- add the NURBSCVCurve object to the set

appendObject nset c
-- create the NURBS object from the NURBSSet
n = NURBSNode nset name:”nurbs01” pos:[10,0,0]

Note that the NURBSSet supplied to the NURBSNode() function will be modified by that function
to be a relational representative for the newly created scene node which you can then use to modify
the scene object -- you don’t have to re-extract a fresh relational NURBSSet.

Modifying Existing NURBS Objects

The classes can also be used to modify the properties of existing NURBS objects in the scene. To gain
access to an internal 3ds max NURBS object you must have the data copied into a NURBSSet. This
is done using the node method getNURBSSet(). You can then use the methods of the NURBSSet to
access the objects.
For example, the following sample code attempts to grab the first NURBS sub-object from the first
node in the current selection set. It then checks if it’s a blend surface and if so adjust one of the
tension parameters.
-- get the first node in selection
node = selection[1];
-- make sure creation has been completed on the node
stopCreating node
-- get the nurbs set for it
getSet = getNURBSSet node #relational
-- extract the first obj, check class & set tension
obj = getObject getSet 1
if classOf obj == NURBSBlendSurface then obj.tension1 = 2.0

The kinds of modification you can perform in this way are limited to changing those parameters and
properties that do not alter the structure of the NURBS scene object -- you can modify point and CV
positions, CV weights, dependent object parameters such as offsets and extrude amounts, etc. You
cannot add or delete objects, change the number of CVs or knots or parent curves, etc. To do this
kind of structural modification, use the appendObject(), setObject(), and removeObject()
functions defined in the NURBSSet : Value (p. 1450) topic and the addNURBSSet(),
breakSurface(), and similar functions defined in the NURBS Node Properties and Methods (p. 1397)
topic.
The stopCreating() method is used to ensure that the specified node is fully created. This method
is primarily used to ensure that a NURBS scene objects is fully created, which it will not be until the
creation is stopped. The NURBSSet returned for a NURBS scene object will not be complete if the
object is still in creation mode. This method will also deactivated any activated object create buttons
in the Create panel.
There are other global functions that may be used to modify NURBS scene objects. These functions
are documented in the NURBS Node Properties and Methods (p. 1397) topic. For instance, developers
 Parameter Ranges for Curves and Surfaces 1391

can use the function breakSurface() to take an existing NURBS surface and break it into two
separate surfaces.
Non-relational NURBSSets
You can also use the getNURBSSet() function in a non-relational mode, but not supplying the
#relational argument, to retrieve a “flattened” version of the NURBSSet in which all dependent
surfaces, such as blends and offsets and lofts are represented as independent curves and surfaces and
there is no ‘live’ connection back to the scene object from which the NURBSSet was derived. You
might use this to get a simplified version of the NURBS scene object for an export script, for example
if the destination system does not support relational objects. You can also use a non-relational
NURBSSet derived in this way as the basis for creating other scene objects, perhaps modifying or
adding to the set and then re-instantiating it with the NURBSNode() function.

Parameter Ranges for Curves and Surfaces

Methods that deal with points in the parameter space of a curve work with arguments in U. Methods
that deal with points in the parameter space of surfaces deal with arguments in U and V. For
example, setting the property <NURBSSurfConstPoint>.uParam sets the position of a dependent
point in the parent surface’s U parameter space. The valid U and V values that may be passed to this
method must be obtained by referencing the <NURBSSurface> properties .uParameterRangeMin,
.uParameterRangeMax, .vParameterRangeMin, and .vParameterRangeMax on the parent
surface. This retrieves the minimum and maximum values for U and V that may be used. For curves
there are similar properties for getting the valid range for U.
Developers should be aware that a curve or surface needs to be instantiated in the 3ds max data base
before it is okay to call these methods (for example by calling NURBSNode()). Prior to the object
existing in the data base these calls will fail.
Generally, when CV curves and surfaces are created, the valid parameter range is known because
they were specified in the beginning and ending knot values. In cases where they are not known,
one can instantiate a NURBSSet that has just the base curves or surfaces. Once instantiated, the
parameter range properties can be interrogated. Then one can build the rest of the parametric model
by making additions and/or modifications to the already instantiated object. The node method
addNURBSSet() makes this easy to do.

Materials Assignment and Texture Coordinates

Materials and NURBS
Each NURBS surface has its own material ID. If you assign a Multi-SubObject material you can apply
a different material to each surface in a NURBS object by setting the <NURBSSurface> property
.MatID.
Texture Coordinates and NURBS
Texture coordinates are assigned to each of the four corners of a NURBS surface. On the standard
3ds max primitives for example most are assigned to use (0,0) to (1,1) across the surface. Some
1392 Chapter 11 | 3ds max Objects

primitives, such as the Prism, don’t use (0,0) to (1,1) because of the way they wrap. Developers may
of course assign any values using the API. The <NURBSSurface> method to do this is
setTextureUVs().

Creating NURBS Scene Objects

The following functions create new nodes in the 3ds max scene. The main function is NURBSNode()
which takes an arbitrary NURBSSet and instantiates a NURBS object in the scene based on the
definition in the NURBSSet. The other two functions are shorthand ways of creating lathe and
extrude NURBS surfaces based on existing shapes in the scene.
NURBSNode <nurbsset> {node_creation_parameters}
Takes a NURBSSet object and creates a 3ds max NURBS object in the scene corresponding
to the definitions in that NURBSSet. After the function call, the supplied NURBSSet
becomes an active representative for the new scene node, all the NURBSId properties are
filled-in and you can modify the scene object by modifying the properties of the
NURBSSet component objects.
Any of the standard <node> constructor keyword arguments can be added, such as .name,
.prefix, .pos, .rotation, .wireColor, etc. See the Node (p. 820) class topic for details.
NURBSLatheNode <curve> <axis> <sweep> [capStart:<boolean>] \
[capEnd:<boolean>] [capType:<integer>] \
[weldCore:<boolean>] [flipNormals:<boolean>] \
[mapCoords:<boolean>] [segs:<integer>] \
[matIDs:<boolean>] [shapeIDs:<boolean>] \
{node_creation_parameters}
This function generates a NURBS object based on the specified lathe (surface of revolution)
definition and returns a pointer to it. This is used by the lathe modifier.
curve <node>
The shape object to revolve. Note that if the curve pointed to is a bezier spline then
capping won’t work properly.
axis <Matrix3>
This specifies the axis of revolution.
sweep <float>
The angle for the surface of revolution in degrees.
capStart: <boolean>
Specifies if the surface should be capped at the beginning: true to cap; false to leave
open.
capEnd: <boolean>
Specifies if the surface should be capped at the ending: true to cap; false to leave
open.
capType: <integer>
This parameter is not currently used and the value specified is ignored.
weldCore: <boolean>
true to collapse any coincident vertices at the center of the surface; otherwise false.
 Creating NURBS Scene Objects 1393

flipNormals: <boolean>
true to invert the orientation of surface normals; otherwise false.
mapCoords: <boolean>
true to generate mapping coordinates; otherwise false.
segs: <integer>
The number of segments in the surface of revolution.
matIDs: <boolean>
If true special material IDs are assigned to the surfaces and caps.
shapeIDs: <boolean>
If true shape IDs are used. When on, this function uses the material ID values
assigned to segments in the spline to be lathed, or curve sub-objects in the NURBS
curve to be lathed. This is available only when matIds is true.
NURBSExtrudeNode <shape> <amount> [capStart:<boolean>] \
[capEnd:<boolean>] [capType:<integer>] \
[mapCoords:<boolean>] [matIDs:<boolean>] \
[shapeIDs:<boolean>] {node_creation_parameters}
This function generates a NURBS object based on the specified extrusion definition and
returns a pointer to it. This is used by the extrude modifier.
shape <node>
The shape node to extrude. Note that if the shape pointed to is a bezier spline then
capping won’t work properly.
amount <float>
Specifies the height of the extrusion.
capStart: <boolean>
Specifies if the surface should be capped at the beginning: true to cap; false to leave
open.
capEnd: <boolean>
Specifies if the surface should be capped at the ending: true to cap; false to leave
open.
capType: <integer>
This parameter is not currently used and the value specified is ignored.
matIDs: <boolean>
If true, special material IDs are assigned to the surfaces and caps.
shapeIDs: <boolean>
If true shape IDs are used. When on, this function uses the material ID values
assigned to segments in the spline to be extruded, or curve sub-objects in the NURBS
curve to be extruded. This is available only when matIds is true.
1394 Chapter 11 | 3ds max Objects

Creating NURBSCVSurface Values

The following functions provide shorthand ways to construct NURBSCVSurface values that you can
then add to a NURBSSet for creation in the scene.
MakeNURBSLatheSurface <curve> <origin> <north> <start> <end>
This function generates a NURBS surface of revolution given an input curve, origin, up
axis, and start and end angles. The output of this function is a NURBS Surface. Note that
this is a CV surface that matches the definition, not a relational surface.
curve <NURBSCurve>
This is the NURBS curve that is revolved.
origin <point3>
Specifies the origin of the revolution.
north <point3>
This is the axis that specified the up direction.
start <float>
This is the start angle of the revolution in radians.
end <float>
This is the end angle of the revolution in radians.
MakeNURBSSphereSurface <radius> <center> <north_axis> <ref_axis> \
<startU> <endU> <startV> <endV> [open:<boolean>]
This function generates a NURBS sphere. The output of this function is a NURBS Surface.
Note that this is a CV surface that matches the definition, not a relational surface.
radius <float>
The radius of the sphere.
center <Point3>
The center point of origin of the sphere.
north_axis <Point3>
This specifies the up axis. Use (Point3 0 0 1) for the Z axis for example.
ref_Axis <Point3>
This is the direction of the seam. The sphere primitive uses (Point3 0 -1 0) as this
value. The northAxis and refAxis must be perpendicular to one another.
startU <float>
The start angle for the sphere in the U direction, specified in radians.
endU <float>
The end angle for the sphere in the U direction, specified in radians.
startV <float>
The start angle for the sphere in the V direction, specified in radians.
endV <float>
The end angle for the sphere in the V direction, specified in radians.
open: <boolean>
If true, the surface is closed; otherwise the surface is not closed. Defaults to false.
 Creating NURBSCVSurface Values 1395

MakeNURBSCylinderSurface <radius> <height> <origin> <sym_axis> \

<ref_axis> <start> <end> [open:<boolean>]
This function generates a NURBS cylinder. The output of this function is a NURBS Surface.
Note that this is a CV surface that matches the definition, not a relational surface.
radius <float>
The radius of the cylinder.
height <float>
The height of the cylinder.
origin <Point3>
The origin of the cylinder.
sym_Axis <Point3>
The axis of symmetry. The standard cylinder primitive specifies (Point3 0 0 1).
ref_Axis <Point3>
This is the direction of the seam. The standard cylinder primitive specifies (Point3 0 1
0). The symAxis and refAxis must be perpendicular to one another.
start <float>
The start angle in radians.
end <float>
The end angle in radians.
open: <boolean>
If true, the surface is closed; otherwise the surface is not closed. Defaults to false.
MakeNURBSConeSurface <radius1> <radius2> <height> <origin> <sym_axis> \
<ref_axis> <start> <end> [open:<boolean>]
This function generates a NURBS cone surface. The output of this function is a NURBS
Surface. Note that this is a CV surface that matches the definition, not a relational surface.
radius1 <float>
One of the radii of the cone.
radius2 <float>
The other radius of the cone.
height <float>
The height of the cone.
origin <Point3>
The origin of the cone.
sym_Axis <Point3>
The axis of symmetry.
ref_Axis <Point3>
This is the direction of the seam. The symAxis and refAxis must be perpendicular to
one another.
1396 Chapter 11 | 3ds max Objects

start <float>
The start angle in radians.
end <float>
The end angle in radians.
open: <boolean>
If true, the surface is closed; otherwise the surface is not closed. Defaults to false.
MakeNURBSTorusSurface <majorRad> <minorRad> <origin> <sym_axis> \
<ref_axis> <startU> <endU> <startV> <endV> \
[open:<boolean>]
This function generates a NURBS torus surface. The output of this function is a NURBS
Surface. Note that this is a CV surface that matches the definition, not a relational surface.
Note: This surface is not closed surface.
majorRad <float>
This is the radius of the entire ‘donut’ shape.
minorRad <float>
The is the radius of the ‘tube’.
origin <Point3>
The origin of the cone.
sym_Axis <Point3>
The axis of symmetry.
ref_Axis <Point3>
This is the direction of the seam. The symAxis and refAxis must be perpendicular to
one another.
startU <float>
The start angle of the torus in the U direction.
endU <float>
The end angle of the torus in the U direction.
startV <float>
The start angle of the torus in the V direction.
endV <float>
The end angle of the torus in the V direction.
open: <boolean>
If true, the surface is closed; otherwise the surface is not closed. Defaults to false.
 NURBS Node Properties and Methods 1397

NURBS Node Properties and Methods

Properties:
There are several properties on <node> objects that give access to sub-object selections in
NURBS objects:
<node>.selectedCurveCVs
<node>.selectedCurves
<node>.selectedImports
<node>.selectedPoints
<node>.selectedSurfaces
<node>.selectedSurfCVs
<node>.curveCVs
<node>.curves
<node>.imports
<node>.surfaces
<node>.surfCVs
<node>.points

These all return a NURBSSelection Value (p. 1448), and enable sub-object manipulation in a manner
similar to that provided for Editable Meshes.
Methods:
The following NURBS-related methods operate on scene nodes:
getNURBSSet <node> [#relational]
This function is used to retrieve a NURBSSet that corresponds to the specified NURBS scene
node. This allows access the internal objects inside a 3ds max editable NURBS object.
If the optional #relational parameter is not supplied, the returned NURBSSet will
contain only independent curves and surfaces, all dependent objects will be decomposed
into corresponding independent objects. So for example, if you pass an object that has a
relational model (perhaps two CV surfaces and a dependent blend surface) it will
decompose them into three CV surfaces. This will be the CV surfaces that represent the
two surfaces and the blend, but you won’t have the blend relational data. If the
#relational argument is supplied, you get back two CV surfaces and a NURBS blend
surface and the NURBSSet is an active representative for the scene object -- any changes
you make to the properties of it’s constituent NURBSObjects will be reflected directly in
the source scene object.
addNURBSSet <node> <nurbsSet>
This function adds the supplied NURBSSet to the specified NURBS scene object, creating
subobjects within the scene node corresponding to the definitions in the NURBSSet. After
the function call, the supplied NURBSSet becomes an active representative for the new
scene node subobjects, all the NURBSId properties are filled-in and you can modify the
associated scene sub-object by modifying the properties of the NURBSSet component
objects.
1398 Chapter 11 | 3ds max Objects

transform <node> <nurbsId_or_Id_array> <matrix3>

Transforms the specified sub-objects by the matrix supplied in the node’s local space. The
sub-objects to be transformed are identified by their NURBSId property which is set up
when you instantiate a NURBSSet with the NURBSNode() function or if you extract a
relational NURBSSet from an existing NURBS scene node using the getNURBSSet()
function.
breakCurve <node> <nurbsId> <u_param>
Breaks the specified sub-object curve at the parametric point along the curve defined by
the <u_param> float argument. The sub-object to be broken is identified by its NURBSId
property which is set up when you instantiate a NURBSSet with the NURBSNode()
function or if you extract a relational NURBSSet from an existing NURBS scene node using
the getNURBSSet() function.
breakSurface <node> <nurbsId> (#U | #V) <u_or_v_param>
Breaks the specified sub-object surface at the parametric point defined by the
<u_or_v_param> argument in the u or v direction depending on whether #U or #V is
supplied for the third argument. The sub-object to be broken is identified by its NURBSId
property which is set up when you instantiate a NURBSSet with the NURBSNode()
function or if you extract a relational NURBSSet from an existing NURBS scene node using
the getNURBSSet() function.
joinCurves <node> <nurbsId1> <nurbsId2> <tolerance_float> \
[flip1:<boolean>] [flip2:<boolean>]
Joins two curve sub-objects in the specified scene node and makes a single curve out of
them. That is, the endpoints of the two curve objects are connected by new segments, and
the two original curves are replaced by a single curve.
The supplied tolerance is a distance in 3ds max units. If the gap between the curves you
are joining is greater than this value, this function creates the join by first creating a blend
curve and then joining the three parts. If the gap is less than this value, or if the curves are
overlapping or coincident, no blend is created.
Creating a blend and then joining the three curves into a single curve is the better
technique. The result matches the parent curves well. Without the blend step, the
resulting curve can deviate from the parent curves, in order to maintain smoothness. (The
amount of deviation depends on how far from tangent the two input curves were at the
join.)
A problem arises when there is a gap but it is too small. In this case, this function generates
the blend but because there isn’t enough room for it, the resulting curve has a loop in it.
To avoid this loop, set this parameter higher than the gap distance.
If you the tolerance to 0.0, the function chooses a value to use for the tolerance.
The sub-objects to be joined are identified by their NURBSId property which is set up
when you instantiate a NURBSSet with the NURBSNode() function or if you extract a
relational NURBSSet from an existing NURBS scene node using the getNURBSSet()
function.
 NURBS Node Properties and Methods 1399

joinSurfaces <node> <nurbsId1> <nurbsId2> <edge1_integer> \

<edge2_integer> <tolerance_float>
Joins two surface sub-objects in the specified scene node and makes a single surface from
them. The specified edges of the two surface objects are connected by a new surface, and
the two original surfaces are replaced by a single surface.
The edges are identified by edge index numbers.
The tolerance is a distance in 3ds max units. If the gap between the surfaces you are
joining is greater than this value, this function creates the join by first creating a blend
surface. If the gap is less than this value, or if the surfaces are overlapping or coincident,
3ds max doesn’t create the blend.
Creating a blend and then joining the three surfaces into a single surface is the better
technique. The result matches the parent surfaces well. Without the blend step, the
resulting surface can deviate from the parent surfaces, in order to maintain smoothness.
(The amount of deviation depends on how far from tangent the two input surfaces were at
the join.)
A problem arises when there is a gap but it is too small. In this case, this function generates
the blend but because there isn’t enough room for it, the resulting surface has a loop in it.
To avoid this loop, set the tolerance parameter higher than the gap distance.
If you set the tolerance to 0.0, the function chooses a value to use for the tolerance.
The sub-objects to be joined are identified by their NURBSId property which is set up
when you instantiate a NURBSSet with the NURBSNode() function or if you extract a
relational NURBSSet from an existing NURBS scene node using the getNURBSSet()
function.
makeIndependent <node> <nurbsId>
This function takes a dependent sub-object (fillet, offset, blend, etc.) and turns it into a CV
variant of itself such that it is independent (no longer dependent on a parent).
The sub-object to be made independent is identified by its NURBSId property which is set
up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a
relational NURBSSet from an existing NURBS scene node using the getNURBSSet()
function.
setViewApproximation <node> <surfaceApproximation>
setRenderApproximation <node> <surfaceApproximation>
setSurfaceDisplay <node> <nurbsdisplay>
These methods work NURBS curve and surface scene nodes. They take instances of the
NURBSSurfaceApproximation (p. 1453) and NURBSDisplay (p. 1447) classes and set the
display or curve/surface approximation settings of the given NURBS scene node to those
specified in the approximation or display control instance.
1400 Chapter 11 | 3ds max Objects

Associated Methods:
canConvertTo <node> <class>
Allows you to test whether a given node is convertible into a given class. Returns true or
false. For example:
if canConvertTo $foo NURBSSurface then ...

The kinds of classes you can convert objects to are the generic editable forms including
Mesh, SplineShape, NURBSCurve, NURBSSurface, etc.
convertTo <node> <class> -- mapped
This function is a general form of the existing specific conversion functions such as
convertToMesh(), convertToSplineShape(), etc. For example,
convertToSplineShape() can be written:
convertTo $circle01 SplineShape

If the conversion is not supported, the function returns the value undefined.
convertToNURBSSurface <node> -- mapped
convertToNURBSCurve <node> -- mapped
These functions work on those primitive geometry and shape classes that support
conversion to NURBS (such as boxes, spheres, circles, lines, etc.). If an object does not
support conversion, the function returns undefined.
isPointSelected <node> <point_index>
Returns true is the specified point is selected, false if not. The definition of a ‘point’ varies
depending on the object type. For meshes, it is the mesh vertex. For a spline, it is the knot.
For NURBS objects, it is the vertex or control point.
pointSelection <node> <point_index>
Returns a floating point weighted point selection if the object supports it. Most object
types just return 1.0 if the point is selected and 0.0 if not. Only NURBS objects currently
support weighted point selection.
stopCreating <node>
This method stops the creation of the current object, if any. This method is primarily used
to ensure that a NURBS scene objects is fully created, which it will not be until the creation
is stopped. The NURBSSet returned for a NURBS scene object will not be complete if the
object is still in creation mode. This method will also deactivated any activated object
create buttons in the Create panel.
 NURBS Node Properties and Methods 1401

The NURBS Classes

The following topics describe all of the NURBS classes:
NURBSObject (p. 1402)
NURBSPoint : NURBSObject (p. 1403)
NURBSCurveConstPoint : NURBSPoint (p. 1403)
NURBSCurveIntersectPoint : NURBSPoint (p. 1404)
NURBSCurveSurfaceIntersectPoint : NURBSPoint (p. 1405)
NURBSIndependentPoint : NURBSPoint (p. 1406)
NURBSPointConstPoint : NURBSPoint (p. 1407)
NURBSSurfConstPoint : NURBSPoint (p. 1407)
NURBSControlVertex : NURBSObject (p. 1409)
NURBSCurve : NURBSObject (p. 1409)
NURBSBlendCurve : NURBSCurve (p. 1410)
NURBSChamferCurve : NURBSCurve (p. 1411)
NURBSCVCurve : NURBSCurve (p. 1412)
NURBSCurveOnSurface : NURBSCVCurve (p. 1414)
NURBSFilletCurve : NURBSCurve (p. 1415)
NURBSIsoCurve : NURBSCurve (p. 1416)
NURBSMirrorCurve : NURBSCurve (p. 1417)
NURBSOffsetCurve : NURBSCurve (p. 1417)
NURBSPointCurve : NURBSCurve (p. 1418)
NURBSPointCurveOnSurface : NURBSPointCurve (p. 1419)
NURBSProjectNormalCurve : NURBSCurve (p. 1420)
NURBSProjectVectorCurve : NURBSCurve (p. 1421)
NURBSSurfaceEdgeCurve : NURBSCurve (p. 1422)
NURBSSurfaceNormalCurve : NURBSCurve (p. 1422)
NURBSSurfSurfIntersectionCurve : NURBSCurve (p. 1423)
NURBSXFormCurve : NURBSCurve (p. 1424)
NURBSSurface : NURBSObject (p. 1425)
NURBS1RailSweepSurface : NURBSSurface (p. 1427)
NURBS2RailSweepSurface : NURBSSurface (p. 1429)
NURBSBlendSurface : NURBSSurface (p. 1430)
NURBSCapSurface : NURBSSurface (p. 1432)
NURBSCVSurface : NURBSSurface (p. 1433)
1402 Chapter 11 | 3ds max Objects

NURBSExtrudeSurface : NURBSSurface (p. 1435)

NURBSFilletSurface : NURBSSurface (p. 1436)
NURBSLatheSurface : NURBSSurface (p. 1437)
NURBSMirrorSurface : NURBSSurface (p. 1437)
NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438)
NURBSNBlendSurface : NURBSSurface (p. 1439)
NURBSOffsetSurface : NURBSSurface (p. 1440)
NURBSPointSurface : NURBSSurface (p. 1441)
NURBSRuledSurface : NURBSSurface (p. 1442)
NURBSULoftSurface : NURBSSurface (p. 1443)
NURBSUVLoftSurface : NURBSSurface (p. 1444)
NURBSXFormSurface : NURBSSurface (p. 1445)
NURBSTexturePoint : NURBSObject (p. 1446)
NURBSDisplay : Value (p. 1447)
NURBSSelection : Value (p. 1448)
NURBSSet : Value (p. 1450)
NURBSSurfaceApproximation : Value (p. 1453)
NURBSTextureSurface : Value (p. 1455)

NURBSObject Values
This is the parent class for all the NURBS classes and so is not directly constructable.
Properties:
Because this is a parent class, all the NURBS classes except NURBSSet have the following
properties:
<nurbsobject>.name : string
The name of the NURBS object
<nurbsobject>.index : integer, read-only
Only valid after a NURBSSet is instantiated via NURBSNode() or if the NURBS object is
part of a non-relational NURBSSet.
<nurbsobject>.nurbsID : integer, read-only
Only valid after a NURBSSet is instantiated via NURBSNode() or if the NURBS object is
part of a relational NURBSSet extracted using getNURBSSet().
<nurbsobject>.selected : boolean
Indicates whether the sub-object in a relational NURBSSet is selected in the NURBS
modifier panel in the 3ds max user interface. You can force the selection and deselection
of objects by setting this property to true or false.
 NURBSPoint : NURBSObject 1403

See also
Value Common Properties, Operators, and Methods (p. 714)

NURBSPoint Classes

NURBSPoint : NURBSObject
This is the parent class for all the NURBS point classes and so is not directly constructable. The class
describes a point in 3D space.
Properties:
All NURBS point classes have the following properties. These properties are both gettable and
settable for independent points, and read-only for dependent points. They are always given in the
parent NURBS node local coordinate system.
<nurbspoint>.pos : point3
<nurbspoint>.x : float
<nurbspoint>.y : float
<nurbspoint>.z : float

See also
NURBSPoint (p. 1403)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSCurveConstPoint : NURBSPoint
This class defines a dependent point that lies on a curve or relative to it. The point can either be on
the curve or off the curve. If it is on the curve, the U Position is the only control of its location. The
U Position specifies a location along the curve (based on the curve’s local U axis). There are four ways
to specify the displacement of the point’s location relative to the U position:
• OnObject - the point is actually on the surface of the object.
• Offset - the point is moved according to a relative (object space) X,Y,Z location.
• Normal - the point is moved along the direction of the curve’s normal. (Negative values move
it opposite to the normal.)
• Tangent - the point is moved along the tangent of the U Position. If the value is positive it’s the
tangent that heads in the direction of increasing U value; if negative it’s the tangent that heads
in the direction of decreasing U value.
1404 Chapter 11 | 3ds max Objects

Constructors:
NURBSCurveConstPoint [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbscurveconstpoint>.parent : integer
The parent curve by NURBSet index.
<nurbscurveconstpoint>.parentID : integer
The parent curve by NURBSId.
<nurbscurveconstpoint>.uParam : float
Parametric point along the parent curve.
<nurbscurveconstpoint>.type : #onObject, #offset, #normal, #tangent
Specifies the transform relationship between the point and the curve.
<nurbscurveconstpoint>.offset : point3
Offset vector if an offset type.
<nurbscurveconstpoint>.normal : float
Distance along the normal if a normal type.
<nurbscurveconstpoint>.uTangent : float
Distance along the curve tangent if a tangent type.
<nurbscurveconstpoint>.trimCurve : boolean
If true, trims parent curve at the point.
<nurbscurveconstpoint>.flipTrim : boolean
If true the curve is trimmed from the point towards low parameter space. If false the
curve is trimmed from the point towards high parameter space.

See also
NURBSPoint (p. 1403)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSCurveIntersectPoint : NURBSPoint
This class defines a dependent point at the intersection of two curves.
Constructors:
NURBSCurveIntersectPoint [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>
 NURBSCurveSurfaceIntersectPoint : NURBSPoint 1405

Properties:
<nurbscurveintersectpoint>.parent1 : integer
The 1st parent curve by NURBSet index.
<nurbscurveintersectpoint>.parent1ID : integer
The 1st parent curve by NURBSId.
<nurbscurveintersectpoint>.parent2 : integer
The 2nd parent curve by NURBSet index.
<nurbscurveintersectpoint>.parent2ID : integer
The 2nd parent curve by NURBSId.
<nurbscurveintersectpoint>.trimCurve1 : boolean
If true, trim the 1st parent curve at the intersection.
<nurbscurveintersectpoint>.trimCurve2 : boolean
If true, trim the 2nd parent curve at the intersection.
<nurbscurveintersectpoint>.flipTrim1 : boolean
If true the 1st parent curve is trimmed from the point towards low parameter space. If
false the curve is trimmed from the point towards high parameter space.
<nurbscurveintersectpoint>.flipTrim2 : boolean
If true the 2nd parent curve is trimmed from the point towards low parameter space. If
false the curve is trimmed from the point towards high parameter space.

See also
NURBSPoint (p. 1403)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSCurveSurfaceIntersectPoint : NURBSPoint
This class defines a dependent point at the intersection of a curve and a surface.
Constructors:
NURBSCurveSurfaceIntersectPoint [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbscurvesurfaceintersectpoint>.parent1 : integer
The parent surface by NURBSet index.
<nurbscurvesurfaceintersectpoint>.parent1ID : integer
The parent surface by NURBSId.
<nurbscurvesurfaceintersectpoint>.parent2 : integer
The parent curve by NURBSet index.
1406 Chapter 11 | 3ds max Objects

<nurbscurvesurfaceintersectpoint>.parent2ID : integer
The parent curve by NURBSId.
<nurbscurvesurfaceintersectpoint>.trimCurve : boolean
If true, trims parent curve at the point.
<nurbscurvesurfaceintersectpoint>.flipTrim : boolean
If true the curve is trimmed from the point towards low parameter space. If false the
curve is trimmed from the point towards high parameter space.
<nurbscurvesurfaceintersectpoint>.seed : float
The seed location is a U position along the length of the parent curve.

See also
NURBSPoint (p. 1403)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSIndependentPoint : NURBSPoint
This class defines an independent, free-standing point.
Constructors:
NURBSIndependentPoint <point3>
getObject <nurbsset> <index>
getPoint <nurbspointsurface> <index>
getPoint <nurbspointcurve> <index>
getPoint <nurbspointcurveonsurface> <index>
Operators:
<nurbsindependentpoint> == <nurbsindependentpoint>
<nurbsindependentpoint> != <nurbsindependentpoint>

Properties:
There are no additional properties for NURBSIndependentPoint.

See also
NURBSPoint (p. 1403)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
 NURBSPointConstPoint : NURBSPoint 1407

NURBSPointConstPoint : NURBSPoint
This class defines a dependent point that lies at a point or relative to it. It is a point constrained
relative to another point. This can be a point used to define a point surface or point curve, it can be
a trim point, or just a point in space. There are two ways to specify the displacement of the point’s
location relative to the U position:
• OnObject - the point is actually at the parent.
• Offset - the point is moved according to a relative (object space) X,Y,Z location.
Constructors:
NURBSPointConstPoint [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbspointconstpoint>.parent : integer
The parent point by NURBSet index.
<nurbspointconstpoint>.parentID : integer
The parent point by NURBSId.
<nurbspointconstpoint>.type : #onObject, #offset
<nurbspointconstpoint>.offset : point3
Offset vector if an offset type.

See also
NURBSPoint (p. 1403)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSSurfConstPoint : NURBSPoint
This class defines a dependent point on a surface or related to it. There are four ways to specify the
displacement of the point’s location relative to the UV position:
• OnObject - the point is actually on the surface of the object.
• Offset - the point is offset some distance (specified in object space) from the surface of the
object.
• Normal - the point is offset along the direction of the surface’s normal. (Negative values move
it opposite to the normal.)
• Tangent - the point is offset some U and/or V distance along the tangent from the surface. If the
value is positive it’s the tangent that heads in the direction of increasing parameter value; if
negative it’s the tangent that heads in the direction of decreasing parameter value.
1408 Chapter 11 | 3ds max Objects

Constructors:
NURBSSurfConstPoint [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbssurfconstpoint>.parent : integer
The parent surface by NURBSet index.
<nurbssurfconstpoint>.parentID : integer
The parent surface by NURBSId.
<nurbssurfconstpoint>.type : #onObject, #offset, #normal, #tangent
<nurbssurfconstpoint>.uParam : float
Parametric position along u direction.
<nurbssurfconstpoint>.vParam : float
Parametric position along v direction.
<nurbssurfconstpoint>.offset : point3
Offset vector if an offset type.
<nurbssurfconstpoint>.normal : float
Distance along the normal if a normal type.
<nurbssurfconstpoint>.uTangent : float
Distance along the u tangent if a tangent type.
<nurbssurfconstpoint>.vTangent : float
Distance along the v tangent if a tangent type.

See also
NURBSPoint (p. 1403)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
 NURBSControlVertex : NURBSObject 1409

NURBSControlVertex Class

NURBSControlVertex : NURBSObject
This class defines an independent Control Vertex of a NURBS Curve or NURBS Surface. This class
shares may of the same properties as a NURBSPoint and has the added property of a rational weight.
The weight value of a CV is rational. That is, it is relative to other CVs in the curve or surface.
Changing the weight of all CVs at once has no effect, because this doesn’t change the ratio between
weights.
Constructors:
NURBSControlVertex <point3> [<weight_float>]
getCV <nurbscvcurve> <index>
getCV <nurbscvsurface> <u_index> <v_index>

Operators:
<nurbscontrolvertex> == <nurbscontrolvertex>
<nurbscontrolvertex> != <nurbscontrolvertex>

Properties:
<nurbscontrolvertex>.weight : float
The weight of the control vertex. This is a value greater than zero. Larger values cause the
CV to have a greater effect, thus the curve or surface will try to pass closer to the CV.

See also
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSCurve Classes

NURBSCurve : NURBSObject
This is the parent class for all the NURBS curve classes and so is not directly constructable. The class
describes the common properties of all NURBS curves. This includes its open/closed state, and
number of trim points. The evalPos() and evalTangent() methods are used to compute points
and tangents on the curve.
Properties:
All NURBS curve classes have the following properties:
<nurbscurve>.isClosed : boolean, read-only
true if the curve is closed, false if open.
<nurbscurve>.numTrimPoints : integer, read-only
The number of trim points in the curve.
1410 Chapter 11 | 3ds max Objects

<nurbscurve>.parameterRangeMin : float, read-only

<nurbscurve>.parameterRangeMax : float, read-only
Contains the minimum and maximum valid values for <u_parm> in the methods
associated with NURBS Curves.
<nurbscurve>.matID : integer
The material ID assigned to the curve.
Methods:
All NURBS curve classes have the following methods:
evalPos <nurbscurve> <u_param>
Returns the position in space of the given parametric point along the curve.
evalTangent <nurbscurve> <u_param>
Returns the tangent vector at the given parametric point along the curve.

See also
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSBlendCurve : NURBSCurve
This class defines a dependent Blend curve. A Blend curve connects the end of one curve to the end
of another, blending the curvature of the parents to create a smooth curve between them.
Constructors:
NURBSBlendCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsblendcurve>.parent1 : integer
The 1st parent curve by NURBSet index.
<nurbsblendcurve>.parent1ID : integer
The 1st parent curve by NURBSId.
<nurbsblendcurve>.parent2 : integer
The 2nd parent curve by NURBSet index.
<nurbsblendcurve>.parent2ID : integer
The 2nd parent curve by NURBSId.
<nurbsblendcurve>.flip1 : boolean
true to use the end of 1st parent curve; false to use the beginning, defaults to false.
<nurbsblendcurve>.flip2 : boolean
true to use the end of 2nd parent curve; false to use the beginning, defaults to false.
 NURBSChamferCurve : NURBSCurve 1411

<nurbsblendcurve>.tension1 : float
The tension value for the 1st parent curve.
<nurbsblendcurve>.tension2 : float
The tension value for the 2nd parent curve.

See also
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSChamferCurve : NURBSCurve
This class defines a dependent Chamfer curve. A Chamfer is a curve that creates a straight line corner
between two parent curves.
Constructors:
NURBSChamferCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbschamfercurve>.parent1 : integer
The 1st parent curve by NURBSet index.
<nurbschamfercurve>.parent1ID : integer
The 1st parent curve by NURBSId.
<nurbschamfercurve>.parent2 : integer
The 2nd parent curve by NURBSet index.
<nurbschamfercurve>.parent2ID : integer
The 2nd parent curve by NURBSId.
<nurbschamfercurve>.length1 : float
The length for 1st parent curve back from the end that defines the beginning of the
chamfer.
<nurbschamfercurve>.length2 : float
The length for 2nd parent curve back from the end that defines the beginning of the
chamfer.
<nurbschamfercurve>.flip1 : boolean
true to use the end of 1st parent curve; false to use the beginning, defaults to false.
<nurbschamfercurve>.flip2 : boolean
true to use the end of 2nd parent curve; false to use the beginning, defaults to false.
<nurbschamfercurve>.trim1 : boolean
Sets whether 1st parent curve is trimmed. true if the curve is trimmed; otherwise false.
1412 Chapter 11 | 3ds max Objects

<nurbschamfercurve>.trim2 : boolean
Sets whether 2nd parent curve is trimmed. true if the curve is trimmed; otherwise false.
<nurbschamfercurve>.flipTrim1 : boolean
If true the 1st parent curve is trimmed from the point towards low parameter space. If
false the curve is trimmed from the point towards high parameter space.
<nurbschamfercurve>.flipTrim2 : boolean
If true the 2nd parent curve is trimmed from the point towards low parameter space. If
false the curve is trimmed from the point towards high parameter space.

See also
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSCVCurve : NURBSCurve
This class defines an independent NURBS CV Curve. The position and weight of the control vertices
(CVs) controls the shape of the curve. Unlike spline vertices, CVs don’t necessarily lie on the curve
they define. The CVs define a control lattice which surrounds the curve.
Constructors:
NURBSCVCurve [<property>:<val>] [closed:<boolean>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor. If closed:true is specified, the curve is created as a closed curve, otherwise it
is an open curve.
getObject <nurbsset> <index>

Properties:
<nurbscvcurve>.order : integer
The order of the curve. This is one more than the degree of polynomial of any segment of
the curve. All curves have a degree. The degree of a curve is the highest exponent in the
equation used to represent it. A linear equation is degree 1, a quadratic equation degree 2.
NURBS curves typically are represented by cubic equations and have a degree of 3.
<nurbscvcurve>.numKnots : integer
The number of knots in the curve. If this value is changed, the previous knot data is NOT
maintained. Because they are generated mathematically, NURBS curves have a parameter
space in addition to the 3D geometric space in which they are displayed. Specifically, an
array of values called knots specifies the extent of influence of each control vertex (CV) on
the curve or surface.
<nurbscvcurve>.numCVs : integer
The number of control vertices in the curve. If this value is changed, the previous control
vertex data is NOT maintained.
 NURBSCVCurve : NURBSCurve 1413

<nurbscvcurve>.transform : matrix3
The transformation matrix for the NURBSCVCurve. This controls the relative position of
the item within a NURBSSet.
<nurbscvcurve>.endsOverlap : boolean, read-only
true if the ends of the curve overlap even though the curve may not be closed (that is, the
tangents match at the ends), false otherwise.
<nurbscvcurve>.autoParam : #notAutomatic, #autoCentripetal, #autoUniform
#notAutomatic, #autoCentripetal, and #autoUniform correspond to the Automatic
Reparam options in the CV Curve rollouts: none, chord length and uniform, respectively.
Defaults to #notAutomatic.
Methods:
close <nurbscvcurve>
Forces the curve to be closed.
getKnot <nurbscvcurve> <index>
setKnot <nurbscvcurve> <index> <float>
Get and set the indexed knot’s value, indexes are 1-based. Knots are a mathematical
construct that helps define the span of control of CVs and blending functions that define
NURBS Curves and Surfaces. The knots are an array of values that determines the
parameterization of a curve. Values in the knot vector are nondecreasing. The knots
specify the region of influence of the CVs on the curve. It is a way of partitioning the
parameter space up into different segments. A B-spline curve or a NURBS curve is a curve
that is defined by a series of segments. On each one of the segments the curve is like a
polynomial, or in the case of a rational one, it’s like the ratio of polynomials. The knot
vector describes how to partition the parameter space of the curve up for each of the
different pieces of the polynomial.
getCV <nurbscvcurve> <cv_index>
Get the indexed CV as a NURBSControlVertex, indexes are 1-based.
setCV <nurbscvcurve> <cv_index> <NURBSControlVertex>
Sets the indexed CV to the given NURBSControlVertex, indexes are 1-based.
refine <nurbscvcurve> <u_param>
Add a new, interpolated CV at the given parametric point along the curve.
reparameterize <nurbscvcurve> (#centripetal | #uniform)
Reparameterizes the curve by chord length (#centripetal) or uniform (#uniform)
uniform parameterization.
Note:
CV curves and surfaces must obey the relationship that “order + number of CVs = number of knots”.
If this is not the case in most cases no object will be created and in some cases an assertion fault
might be generated.
1414 Chapter 11 | 3ds max Objects

See also
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSCurveOnSurface : NURBSCVCurve
This class defines a dependent Curve-on-Surface CV curve. These curves can be used for trimming
the surface they lie on.
Constructors:
NURBSCurveOnSurface [<property>:<val>] [closed:<boolean>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor. If closed:true is specified, the curve is created as a closed curve, otherwise it
is an open curve.
getObject <nurbsset> <index>

Properties:
<nurbscurveonsurface>.parent : integer
The parent surface by NURBSet index.
<nurbscurveonsurface>.parentID : integer
The parent surface by NURBSId.
<nurbscurveonsurface>.trim : boolean
If true, trims parent surface at the curve.
<nurbscurveonsurface>.flipTrim : boolean
The state of the trim flip toggle. This controls which portion of the surface is trimmed.
Note:
The values for CVs for a NURBSCurveOnSurface are values in the parameter space of the surface, not
in 3D space. CV surfaces are normally parameterized from 0 to 1, so all the CV values should have
values from 0 to 1.
Point surfaces are chord-length parameterized, which means that the CV parameter range is about
the same as the size of the surface. In most cases, NURBSCurveOnSurfaces work better when point
surfaces are used.
You may have problems generating NURBSCurveOnSurfaces on CV surfaces.
NURBSPointCurveOnSurfaces on CV surfaces are typically easier to work with.
 NURBSFilletCurve : NURBSCurve 1415

See Also
NURBSCVCurve (p. 1412)
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSFilletCurve : NURBSCurve
This class defines a dependent Fillet curve. A Fillet is a curve that creates a circular arc corner between
two parent curves.
Constructors:
NURBSFilletCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsfilletcurve>.parent1 : integer
The 1st parent curve by NURBSet index.
<nurbsfilletcurve>.parent1ID : integer
The 1st parent curve by NURBSId.
<nurbsfilletcurve>.parent2 : integer
The 2nd parent curve by NURBSet index.
<nurbsfilletcurve>.parent2ID : integer
The 2nd parent curve by NURBSId.
<nurbsfilletcurve>.radius : float
The radius of the fillet.
<nurbsfilletcurve>.flip1 : boolean
true to use the end of 1st parent curve; false to use the beginning, defaults to false.
<nurbsfilletcurve>.flip2 : boolean
true to use the end of 2nd parent curve; false to use the beginning, defaults to false.
<nurbsfilletcurve>.trim1 : boolean
Sets whether 1st parent curve is trimmed. true if the curve is trimmed; otherwise false.
<nurbsfilletcurve>.trim2 : boolean
Sets whether 2nd parent curve is trimmed. true if the curve is trimmed; otherwise false.
<nurbsfilletcurve>.flipTrim1 : boolean
If true the 1st parent curve is trimmed from the point towards low parameter space. If
false the curve is trimmed from the point towards high parameter space.
<nurbsfilletcurve>.flipTrim2 : boolean
If true the 2nd parent curve is trimmed from the point towards low parameter space. If
false the curve is trimmed from the point towards high parameter space.
1416 Chapter 11 | 3ds max Objects

See also
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSIsoCurve : NURBSCurve
This class defines a dependent Iso (isoparametric) curve. U and V Iso curves are dependent curves
created along lines of constant parameter value of a NURBS surface.
Constructors:
NURBSIsoCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsisocurve>.parent : integer
The parent surface by NURBSet index.
<nurbsisocurve>.parentID : integer
The parent surface by NURBSId.
<nurbsisocurve>.dir : #U, #V
The direction of the iso curve, either #U or #V.
<nurbsisocurve>.parameter : float
The parametric position in the range of 0.0 to 1.0 in the given direction on the surface at
which the iso line will sit.
<nurbsisocurve>.trim : boolean
If true, trims parent surface at the curve.
<nurbsisocurve>.flipTrim : boolean
The state of the trim flip toggle. This controls which portion of the surface is trimmed.
<nurbsisocurve>.seed : point2
The seed location is a UV position on the parent surface.

See also
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
 NURBSMirrorCurve : NURBSCurve 1417

NURBSMirrorCurve : NURBSCurve
This class defines a dependent Mirror curve. A Mirror curve is similar to a mirror object that you
create using the Mirror tool (on the 3ds max toolbar) or the Mirror modifier. It is the original curve
reflected about one or two axes.
Constructors:
NURBSMirrorCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsmirrorcurve>.parent : integer
The parent curve by NURBSet index.
<nurbsmirrorcurve>.parentID : integer
The parent curve by NURBSId.
<nurbsmirrorcurve>.axis : #X, #Y, #Z, #XY, #XZ, #YZ
The axis or axes of reflection for the curve.
<nurbsmirrorcurve>.distance : float
The mirror offset distance.
<nurbsmirrorcurve>.transform : matrix3
This is an additional transformation applied to the axis specification. This corresponds to
the gizmo the user may use interactively to alter the location of the mirror axis. This is
exactly equivalent to setting the transform on the gizmo of a mirror modifier.

See also
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSOffsetCurve : NURBSCurve
This class defines a dependent Offset curve. An Offset curve is offset from the original, parent curve.
It lies in the same plane as its parent, and is normal to the original.
Constructors:
NURBSOffsetCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>
1418 Chapter 11 | 3ds max Objects

Properties:
<nurbsoffsetcurve>.parent : integer
The parent curve by NURBSet index.
<nurbsoffsetcurve>.parentID : integer
The parent curve by NURBSId.
<nurbsoffsetcurve>.distance : float
The distance of the offset curve from the parent.

See also
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSPointCurve : NURBSCurve
This class defines an independent curve that uses points to describe its shape. All the points lie on
the curve itself.
Constructors:
NURBSPointCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbspointcurve>.numPoints : integer
The number of points in the point curve. If this value is changed, the previous point data
is not maintained.
<nurbspointcurve>.closed : boolean
true if the curve is closed, false if open.
<nurbspointcurve>.transform : matrix3
The transformation matrix for the NURBSPointCurve. This controls the relative position of
the item within a NURBSSet.
Methods:
close <nurbspointcurve>
Closes the curve.
getPoint <nurbspointcurve> <index>
Get the indexed curve point as a NURBSIndependentPoint
setPoint <nurbspointcurve> <index> <nurbs_independent_pt>
Set the indexed point to the given NURBSIndependentPoint
refine <nurbspointcurve> <u_param>
Adds a new, interpolated point at the given parametric position along the curve.
 NURBSPointCurveOnSurface : NURBSPointCurve 1419

See also
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSPointCurveOnSurface : NURBSPointCurve
This class defines a dependent Curve-on-Surface Point curve. These curves can be used for trimming
the surface they lie on.
Constructors:
NURBSPointCurveOnSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbspointcurveonsurface>.parent : integer
The parent surface by NURBSet index.
<nurbspointcurveonsurface>.parentID : integer
The parent surface by NURBSId.
<nurbspointcurveonsurface>.trim : boolean
If true, trims parent surface at the curve.
<nurbspointcurveonsurface>.flipTrim : boolean
The state of the trim flip toggle. This controls which portion of the surface is trimmed.

See also
NURBSPointCurve (p. 1418)
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
1420 Chapter 11 | 3ds max Objects

NURBSProjectNormalCurve : NURBSCurve
This class defines a dependent Normal Projected curve. A Normal Projected curve lies on a surface.
It is based on an existing curve, which is projected onto the surface in the direction of the surface’s
normals.
Constructors:
NURBSProjectNormalCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsprojectnormalcurve>.parent1 : integer
The parent surface by NURBSet index.
<nurbsprojectnormalcurve>.parent1ID : integer
The parent surface by NURBSId.
<nurbsprojectnormalcurve>.parent2 : integer
The parent curve by NURBSet index.
<nurbsprojectnormalcurve>.parent2ID : integer
The parent curve by NURBSId.
<nurbsprojectnormalcurve>.trim : boolean
If true, trims parent surface at the curve.
<nurbsprojectnormalcurve>.flipTrim : boolean
The state of the trim flip toggle. This controls which portion of the surface is trimmed.
<nurbsprojectnormalcurve>.seed : point2
The seed location is a UV position on the parent surface.

See also
NURBSPointCurve (p. 1418)
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
 NURBSProjectVectorCurve : NURBSCurve 1421

NURBSProjectVectorCurve : NURBSCurve
This class defines a dependent Vector Projected curve. A Vector Projected curve lies on a surface. This
is almost the same as a Normal Projected curve, except that the projection from the existing curve
to the surface is in the direction of a vector that you can control.
Constructors:
NURBSProjectVectorCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsprojectvectorcurve>.parent1 : integer
The parent surface by NURBSet index.
<nurbsprojectvectorcurve>.parent1ID : integer
The parent surface by NURBSId.
<nurbsprojectvectorcurve>.parent2 : integer
The parent curve by NURBSet index.
<nurbsprojectvectorcurve>.parent2ID : integer
The parent curve by NURBSId.
<nurbsprojectvectorcurve>.trim : boolean
If true, trims parent surface at the curve.
<nurbsprojectvectorcurve>.flipTrim : boolean
The state of the trim flip toggle. This controls which portion of the surface is trimmed.
<nurbsprojectvectorcurve>.seed : point2
The seed location is a UV position on the parent surface.
<nurbsprojectvectorcurve>.pVec : point3
The projection vector.

See also
NURBSPointCurve (p. 1418)
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
1422 Chapter 11 | 3ds max Objects

NURBSSurfaceEdgeCurve : NURBSCurve
This class defines a dependent Surface Edge curve.
Constructors:
NURBSSurfaceEdgeCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbssurfaceedgecurve>.parent : integer
The parent surface by NURBSet index.
<nurbssurfaceedgecurve>.parentID : integer
The parent surface by NURBSId.
<nurbssurfaceedgecurve>.seed : Point2
The seed location is a UV position on the parent surface.

See also
NURBSPointCurve (p. 1418)
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSSurfaceNormalCurve : NURBSCurve
This class defines a dependent Surface Normal curve. This is a curve created at a specified distance
from a surface and normal to it.
Constructors:
NURBSSurfaceNormalCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbssurfacenormalcurve>.parent : integer
The parent curve by NURBSet index.
<nurbssurfacenormalcurve>.parentID : integer
The parent curve by NURBSId.
<nurbssurfacenormalcurve>.distance : float
The distance along the normal from the surface to the curve.
 NURBSSurfSurfIntersectionCurve : NURBSCurve 1423

Note:
The parent curve must have one of the following types: surface-surface intersection, U iso, V iso,
normal projected, vector projected, CV curve on surface, or point curve on surface.

See also
NURBSPointCurve (p. 1418)
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSSurfSurfIntersectionCurve : NURBSCurve
This class defines a dependent Surface-Surface Intersection curve.
Constructors:
NURBSSurfSurfIntersectionCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbssurfsurfintersectioncurve>.parent1 : integer
The 1st parent surface by NURBSet index.
<nurbssurfsurfintersectioncurve>.parent1ID : integer
The 1st parent surface by NURBSId.
<nurbssurfsurfintersectioncurve>.parent2 : integer
The 2nd parent surface by NURBSet index.
<nurbssurfsurfintersectioncurve>.parent2ID : integer
The 2nd parent surface by NURBSId.
<nurbssurfsurfintersectioncurve>.trimCurve1 : boolean
If true, trim the 1st parent surface at the intersection.
<nurbssurfsurfintersectioncurve>.trimCurve2 : boolean
If true, trim the 2nd parent surface at the intersection.
<nurbssurfsurfintersectioncurve>.flipTrim1 : boolean
If true the 1st parent surface is trimmed from the point towards low parameter space. If
false the surface is trimmed from the point towards high parameter space.
<nurbssurfsurfintersectioncurve>.flipTrim2 : boolean
If true the 2nd parent surface is trimmed from the point towards low parameter space. If
false the surface is trimmed from the point towards high parameter space.
<nurbssurfsurfintersectioncurve>.seed : point2
The seed location is a UV position on the parent surface.
1424 Chapter 11 | 3ds max Objects

See also
NURBSPointCurve (p. 1418)
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSXFormCurve : NURBSCurve
This class defines a dependent Transform (XForm) curve. A Transform curve is a copy of the original
curve with a different position, rotation, or scale.
Constructors:
NURBSXFormCurve [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsxformcurve>.parent : integer
The parent curve by NURBSet index.
<nurbsxformcurve>.parentID : integer
The parent curve by NURBSId.
<nurbsxformcurve>.transform : matrix3
The offset transformation matrix for the NURBSCVCurve. This controls the relative
position of the item to the parent curve.

See also
NURBSPointCurve (p. 1418)
NURBSCurve (p. 1409)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
 NURBSSurface : NURBSObject 1425

NURBSSurface Classes

NURBSSurface : NURBSObject
This is the parent class for all the NURBS surface classes and so is not directly constructable. The class
describes the common properties of all NURBS surfaces. This includes its material ID, texture/tiling
options, renderable state, and open/closed state, and normal inverted state. The evalPos(),
evalUTangent(), and evalVTangent() methods are used to compute points and tangents on the
surface.
Properties:
All NURBS surface classes have the following properties.
<nurbssurface>.renderable : boolean
Specifies whether the surface is renderable. true if the surface is renderable, false if not.
<nurbssurface>.flipNormals : boolean
Specifies whether all the surface’s surface normals are flipped. true if the surface normals
are to be flipped, false if not.
<nurbssurface>.generateUVs1 : boolean
If true, enables the generation of UV mapping coordinates for UVW channel 1. See the
getGenerateUVs() and setGenerateUVs() methods for generalized mapping channel
access.
<nurbssurface>.generateUVs2 : boolean
If true, enables the generation of UV mapping coordinates for UVW channel 2. See the
getGenerateUVs() and setGenerateUVs() methods for generalized mapping channel
access.
<nurbssurface>.matID : integer
The material ID of the surface.
<nurbssurface>.closedInU : boolean, read-only
true if the surface is closed in the U direction, false if open.
<nurbssurface>.closedInV : boolean, read-only
true if the surface is closed in the V direction, false if open.*
<nurbssurface>.uParameterRangeMin : float, read-only
<nurbssurface>.uParameterRangeMax : float, read-only
Contains the minimum and maximum valid values for <u_parm> in the methods
associated with NURBS Surfaces.
<nurbssurface>.vParameterRangeMin : float, read-only
<nurbssurface>.vParameterRangeMax : float, read-only
Contains the minimum and maximum valid values for <v_param> in the methods
associated with NURBS Surfaces.
1426 Chapter 11 | 3ds max Objects

<nurbssurface>.textureSurface1 : NURBSTextureSurface
<nurbssurface>.textureSurface2 : NURBSTextureSurface
Used to get and set the texture surfaces for the two mapping channels. These properties
take and return instances of the NURBSTextureSurface class. .textureSurface1 accesses
mapping channel 1 and .textureSurface2 accesses mapping channel 2. See
NURBSTextureSurface : Value (p. 1455). See the getTextureSurface() and
setTextureSurface() methods for generalized mapping channel access.
It is not possible to assign texture surfaces to NURBS objects present in the scene. You can
create new NURBSSets and the texture surface is used when you call
createNURBSObject(). However, if you do a getNURBSSet() and assign a
NURBSTextureSurface to these properties, nothing happens.
Methods:
All NURBS surface classes have the following methods:
evalPos <nurbssurface> <u_param> <v_param>
Returns the coordinates in space of the point at the given U and V parametric position on
the surface.
evalUTangent <nurbssurface> <u_param> <v_param>
Returns the U tangent vector of the surface at the given U and V parametric position on
the surface.
evalVTangent <nurbssurface> <u_param> <v_param>
Returns the V tangent vector of the surface at the given U and V parametric position on
the surface.
getTiling <nurbssurface> [channel:<index>]
setTiling <nurbssurface> <ut> <vt> [channel:<index>]
These methods get and set the tiling factor on the surface in the u and v directions. These
methods return or take a point2 value, with u tiling in the x component and v tiling in the
y component of the point2. The optional channel keyword argument can be used to
select the mapping channel which defaults to 1.
getTilingOffset <nurbssurface> [channel:<index>]
setTilingOffset <nurbssurface> <uo> <vo> [channel:<index>]
These methods get and set the tiling offset on the surface for the selected channel. These
methods return or take a point2 value, with u offset in the x component and v offset in
the y component of the point2. The optional channel keyword argument can be used to
select the mapping channel which defaults to 1.
getGenerateUVs <nurbssurface> <channel_index>
setGenerateUVs <nurbssurface> <channel_index> <boolean>
These methods get and set whether the generation of UV mapping coordinates for the
selected channel is enabled.
 NURBS1RailSweepSurface : NURBSSurface 1427

getTextureUVs <nurbssurface> <index> [channel:<index>]

setTextureUVs <nurbssurface> <index> <point2> [channel:<index>]
These methods get and set the texture UV as a point2 value for the indexed coordinate and
selected channel. The 1-based index of the texture coordinate must be >= 1 and <= 4. The
optional channel keyword argument can be used to select the mapping channel which
defaults to 1.
getTextureSurface <nurbssurface> <channel_index>
setTextureSurface <nurbssurface> <channel_index> <NURBSTextureSurface>
These methods get and set texture surfaces for the selected channel. These methods return
or take an instance of the NURBSTextureSurface class. See NURBSTextureSurface : Value
(p. 1455).
getProdTess <nurbssurface> <tessType_name>
setProdTess <nurbssurface> <tessType_name> <NURBSSurfaceApproximation>
getViewTess <nurbssurface> <tessType_name>
setViewTess <nurbssurface> <tessType_name> <NURBSSurfaceApproximation>
These methods get and set renderer and viewport NURBSSurfaceApproximation values for
individual surfaces, where <tessType_name> is one of #surface, #displacement, or
#curve corresponding to the 3 kinds of tessellation that can be controlled on a surface.
clearProdTess <nurbssurface> <tessType_name>
clearViewTess <nurbssurface> <tessType_name>
Resets the surface approximation settings for the surface for the given tessellation type,
where <tessType_name> is one of #surface, #displacement, or #curve corresponding
to the 3 kinds of tessellation that can be controlled on a surface.

See also
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBS1RailSweepSurface : NURBSSurface
This class defines a dependent 1-Rail Sweep surface. A 1-Rail Sweep surface uses at least two curves.
One curve, the “rail,” defines one edge of the surface. The other curves define the surface’s cross
sections. The cross-section curves should intersect the rail curve. If the cross sections don’t intersect
the rail, the resulting surface is unpredictable.
Constructors:
NURBS1RailSweepSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbs1railsweepsurface>.rail : integer
The parent rail curve by NURBSet index.
1428 Chapter 11 | 3ds max Objects

<nurbs1railsweepsurface>.railID : integer
The parent rail curve by NURBSId.
<nurbs1railsweepsurface>.numCurves : integer
The number of cross-section curves.
<nurbs1railsweepsurface>.parallel : boolean
If true, ensures that the sweep surface’s normal is parallel to the rail.
<nurbs1railsweepsurface>.axisTM : matrix3
The axis of the sweep.
Methods:
appendCurve <nurbs1railsweepsurface> <curve> [flip:<boolean>] [startPoint:<float>]
Adds a curve to the end of the list of cross-section curves by specifying the index in the
NURBSSet. If flip:true is specified, the cross-section curve is reversed. startPoint
specifies the start point on the parent curve. startPoint is applicable only if the parent is
a closed curve.
appendCurveByID <nurbs1railsweepsurface> <curveID> [flip:<boolean>]
[startPoint:<float>]
Adds a curve to the end of the list of cross-section curves by specifying the NURBSId. If
flip:true is specified, the cross-section curve is reversed. startPoint specifies the start
point on the parent curve. startPoint is applicable only if the parent is a closed curve.
getCurve <nurbs1railsweepsurface> <index>
setCurve <nurbs1railsweepsurface> <index> <curve>
Get or set the indexed cross-section curve by NURBSSet index.
getCurveID <nurbs1railsweepsurface> <index>
setCurveByID <nurbs1railsweepsurface> <index> <curveID>
Get or set the indexed cross-section curve by NURBSId.
getFlip <nurbs1railsweepsurface> <index>
setFlip <nurbs1railsweepsurface> <index> <boolean>
Get or set whether the indexed cross-section curve is reversed.
getCurveStartPoint <nurbs1railsweepsurface> <index>
setCurveStartPoint <nurbs1railsweepsurface> <index> <float>
Get or set the start point of the indexed cross-section curve on the parent curve. The start
point is applicable only if the parent is a closed curve.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
 NURBS2RailSweepSurface : NURBSSurface 1429

NURBS2RailSweepSurface : NURBSSurface
This class defines a dependent 2-Rail Sweep surface. A 2-Rail Sweep surface uses at least three curves.
Two curves, the “rails,” define the two edges of the surface. The other curves define the surface’s
cross sections. A 2-Rail Sweep surface is similar to a 1-Rail sweep. The additional rail gives you more
control over the shape of the surface.
Constructors:
NURBS2RailSweepSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbs2railsweepsurface>.rail1 : integer
The 1st parent rail curve by NURBSet index.
<nurbs2railsweepsurface>.rail1ID : integer
The 1st parent rail curve by NURBSId.
<nurbs2railsweepsurface>.rail2 : integer
The 2nd parent rail curve by NURBSet index.
<nurbs2railsweepsurface>.rail2ID : integer
The 2nd parent rail curve by NURBSId.
<nurbs2railsweepsurface>.numCurves : integer
The number of cross-section curves.
<nurbs2railsweepsurface>.parallel : boolean
If false, the rail curves define a ruled surface, and the cross sections describe lofting from
this base ruled surface. If true, each cross section is associated with its best fitting plane.
This plane moves along the rails and parallel to them. If the rails are curved, the plane can
rotate. If the spacing between the rails changes, the section scales or stretches. In either
case, the surface is blended from section to section along its entire length.
Methods:
appendCurve <nurbs2railsweepsurface> <curve> [flip:<boolean>] [startPoint:<float>]
Adds a curve to the end of the list of cross-section curves by specifying the index in the
NURBSSet. If flip:true is specified, the cross-section curve is reversed. startPoint
specifies the start point on the parent curve. startPoint is applicable only if the parent is
a closed curve.
appendCurveByID <nurbs2railsweepsurface> <curveID> [flip:<boolean>]
[startPoint:<float>]
Adds a curve to the end of the list of cross-section curves by specifying the NURBSId. If
flip:true is specified, the cross-section curve is reversed. startPoint specifies the start
point on the parent curve. startPoint is applicable only if the parent is a closed curve.
1430 Chapter 11 | 3ds max Objects

getCurve <nurbs2railsweepsurface> <index>

setCurve <nurbs2railsweepsurface> <index> <curve>
Get or set the indexed cross-section curve by NURBSSet index.
getCurveID <nurbs2railsweepsurface> <index>
setCurveByID <nurbs2railsweepsurface> <index> <curveID>
Get or set the indexed cross-section curve by NURBSId.
getFlip <nurbs2railsweepsurface> <index>
setFlip <nurbs2railsweepsurface> <index> <boolean>
Get or set whether the indexed cross-section curve is reversed.
getCurveStartPoint <nurbs2railsweepsurface> <index>
setCurveStartPoint <nurbs2railsweepsurface> <index> <float>
Get or set the start point of the indexed cross-section curve on the parent curve. The start
point is applicable only if the parent is a closed curve.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSBlendSurface : NURBSSurface
This class defines a dependent Blend surface. A Blend surface connects the edge of one surface to the
edge of another, blending the curvature of the parents to create a smooth surface between them. You
can also blend from a surface to a curve, or from a curve to a curve.
Constructors:
NURBSBlendSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsblendsurface>.parent1 : integer
The 1st parent by NURBSet index.
<nurbsblendsurface>.parent1ID : integer
The 1st parent by NURBSId.
<nurbsblendsurface>.parent2 : integer
The 2nd parent by NURBSet index.
<nurbsblendsurface>.parent2ID : integer
The 2nd parent by NURBSId.
 NURBSBlendSurface : NURBSSurface 1431

<nurbsblendsurface>.edge1 : integer
Which edge of the 1st parent surface is used for the blend. The property’s value is one of
the following:
1: The low U edge
2: The high U edge
3: The low V edge
4: The high V edge

<nurbsblendsurface>.edge2 : integer
Which edge of the 2nd parent surface is used for the blend.
<nurbsblendsurface>.flip1 : boolean
Controls the matching of parent surface normals when creating the Blend surface. For
example, normally when you create a Blend surface between two parent surfaces you don’t
want a ‘bow tie’ surface (one with the ends rotated 180 degrees so it crosses on itself in the
middle). If you simply match the parent normals you’ll occasionally get a ‘bow tie’ surface.
To prevent this you use this property to set a state indicating that one or the other should
be flipped before it’s used. In this way, when the blend is created, a ‘bow tie’ won’t occur. If
true, the 1st parent’s surface normal will be matched; if false the 1st parent’s surface
normal will not be matched.
<nurbsblendsurface>.flip2 : boolean
If true, the 2nd parent’s surface normal will be matched; if false the 2nd parent’s surface
normal will not be matched.
<nurbsblendsurface>.tension1 : float
The tension value for the 1st parent.
<nurbsblendsurface>.tension2 : float
The tension value for the 2nd parent.
<nurbsblendsurface>.curveStartPoint1 : float
<nurbsblendsurface>.curveStartPoint2 : float
Adjusts the position of the start point at the two edges of the blend. Adjusting the start
points can help eliminate unwanted twists or “buckles” in the surface. These values are not
applicable if the edges or curves are not closed.
Methods:
getParent <nurbsblendsurface> <index>
setParent <nurbsblendsurface> <index> <curve>
Get or set a parent by NURBSSet index. <index> = 1 - parent 1; 2 - parent 2.
getParentID <nurbsblendsurface> <index>
setParentID <nurbsblendsurface> <index> <curveID>
Get or set a parent by NURBSId. <index> = 1 - parent 1; 2 - parent 2.
getEdge <nurbsblendsurface> <index>
setEdge <nurbsblendsurface> <index> <edge>
Get or set which edge of the parent surface is used for the blend. <index> = 1 - parent 1; 2
- parent 2. See the edge1 property description for the <edge> value description.
1432 Chapter 11 | 3ds max Objects

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSCapSurface : NURBSSurface
This class defines a dependent Cap surface. A Cap surface is a surface that caps a closed curve or the
edge of a closed surface. Caps are especially useful with extruded surfaces.
Constructors:
NURBSCapSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbscapsurface>.parent : integer
The parent curve or surface by NURBSet index.
<nurbscapsurface>.parentID : integer
The parent curve or surface by NURBSId.
<nurbscapsurface>.edge : integer
Which edge of the parent surface is capped. This value is not applicable if the parent is a
curve. The property’s value is one of the following:
1: The low U edge
2: The high U edge
3: The low V edge
4: The high V edge

<nurbscapsurface>.curveStartPoint : integer
The start point on the parent curve. This value is only applicable if the parent is a curve.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
 NURBSCVSurface : NURBSSurface 1433

NURBSCVSurface : NURBSSurface
This class defines an independent surface that uses control vertices (CVs) to describe its shape. The
CVs define a control lattice which surrounds the surface.
Constructors:
NURBSCVSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbscvsurface>.uOrder : integer
<nurbscvsurface>.vOrder : integer
The order of the surface in the U and V directions.
<nurbscvsurface>.numUKnots : integer
<nurbscvsurface>.numVKnots : integer
The number of knots in the surface in the U and V directions. If this value is changed, the
previous knot data is NOT maintained. Because they are generated mathematically, NURBS
surfaces have a parameter space in addition to the 3D geometric space in which they are
displayed. Specifically, an array of values called knots specifies the extent of influence of
each control vertex (CV) on the surface.
<nurbscvsurface>.numCVs : point2
The number of control vertices for the surface in the U and V directions. If this value is
changed, the previous control vertex data is NOT maintained.
<nurbscvsurface>.transform : matrix3
The transformation matrix for the NURBSCVSurface. This controls the relative position of
the item within a NURBSSet.
<nurbscvsurface>.uEdgesOverlap : boolean, read-only
<nurbscvsurface>.vEdgesOverlap : boolean, read-only
true if the edges of the surface overlap in U and/or V even though the surface may not be
closed (that is, the tangents match at the edges), false otherwise.
<nurbscvsurface>.autoParam : #notAutomatic, #autoCentripetal, #autoUniform
#notAutomatic, #autoCentripetal, and #autoUniform correspond to the Automatic
Reparam options in the CV Surface rollouts: none, chord length and uniform, respectively.
Defaults to #notAutomatic.
1434 Chapter 11 | 3ds max Objects

<nurbscvsurface>.rigid : boolean
true if the surface is ‘rigid’; otherwise false. The only editing allowed on a rigid surface
is to transform it at the Surface sub-object level. You can’t move a rigid surface’s points or
CVs, or change the number of points or CVs. Rigid surfaces reduce the amount of memory
used by the NURBS model. Making surfaces rigid improves performance, especially for
large and complex models. When a surface is rigid, you can’t see its points or CVs when
you are at the Point or Surface CV sub-object levels. If the model has no nonrigid surfaces
and no point curves, the Point and Surface CV sub-object levels aren’t available at all.
Methods:
closeU <nurbscvsurface>
Closes the surface in the U direction.
closeV <nurbscvsurface>
Closes the surface in the V direction.
getUKnot <nurbscvsurface> <u_index>
Get the indexed U-direction knot; knot indexes are 1-based.
setUKnot <nurbscvsurface> <u_index> <float>
Sets the indexed U-direction knot to the given value; knot indexes are 1-based.
getVKnot <nurbscvsurface> <v_index>
Get the indexed V-direction knot; knot indexes are 1-based.
setVKnot <nurbscvsurface> <v_index> <float>
Get the indexed V-direction knot to the given value; knot indexes are 1-based.
getCV <nurbscvsurface> <u_index> <v_index>
Get the CV at the given U and V index as a NURBSControlVertex; CV indexes are 1-based.
setCV <nurbscvsurface> <u_index> <v_index> <NURBSControlVertex>
Sets the CV at the given U and V index to the supplied NURBSControlVertex; CV indexes
are 1-based.
refineU <nurbscvsurface> <v_param>
Adds new row of interpolated CVs in the U direction on the surface at the given
parametric V point.
refineV <nurbscvsurface> <u_param>
Adds new column of interpolated CVs in the V direction on the surface at the given
parametric U point.
refine <nurbscvsurface> <u_param> <v_param>
Adds a new row and column of interpolated CVs on the surface at the given parametric UV
position.
reparameterize <nurbscvsurface> (#centripetal | #uniform)
Reparameterizes the surface by chord length (#centripetal) or uniform (#uniform)
uniform parameterization.
 NURBSExtrudeSurface : NURBSSurface 1435

Note:
CV curves and surfaces must obey the relationship that “order + number of CVs = number of knots”.
If this is not the case in most cases no object will be created and in some cases an assertion fault
might be generated.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSExtrudeSurface : NURBSSurface
This class defines a dependent Extrude surface. An Extrude surface is extruded from a curve sub-
object. It is similar to a surface created with the Extrude modifier. The advantage is that an extrude
sub-object is part of the NURBS model, so you can use it to construct other curve and surface sub-
objects.
Constructors:
NURBSExtrudeSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsextrudesurface>.parent : integer
The parent curve by NURBSet index.
<nurbsextrudesurface>.parentID : integer
The parent curve by NURBSId.
<nurbsextrudesurface>.distance : float
The length of extrusion.
<nurbsextrudesurface>.axisTM : matrix3
The extrusion axis.
<nurbsextrudesurface>.curveStartPoint : float
The start point on the parent curve. This value is only applicable if the curve is closed.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
1436 Chapter 11 | 3ds max Objects

NURBSFilletSurface : NURBSSurface
This class defines a dependent Fillet surface. A Fillet surface is a rounded corner surface connecting
the edges of two other surfaces.
Constructors:
NURBSFilletSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsfilletsurface>.cubic : boolean
If true, the radius is always linear. If false, the radius is treated as a cubic function,
allowing it to change based on the parent surfaces’ geometry.
Methods:
getParent <nurbsfilletsurface> <index>
setParent <nurbsfilletsurface> <index> <curve>
Get or set a parent surface by NURBSSet index. <index> = 1 - parent 1; 2 - parent 2.
setParentID <nurbsfilletsurface> <index> <curveID>
getParentID <nurbsfilletsurface> <index>
Get or set a parent surface by NURBSId. <index> = 1 - parent 1; 2 - parent 2.
getSeed <nurbsfilletsurface> <index>
setSeed <nurbsfilletsurface> <index> <point2>
The UV location of the seed value on a parent surface. <index> = 1 - parent 1; 2 - parent 2.
getRadius <nurbsfilletsurface> <index>
setRadius <nurbsfilletsurface> <index> <float>
Get or set the radius of the fillet surface. <index> = 1 - start radius; 2 - end radius.
getTrimSurface <nurbsfilletsurface> <index>
setTrimSurface <nurbsfilletsurface> <index> <bool>
Get or set whether to trim a parent’s surface. If true, trims the parent surface at the
intersection. <index> = 1 - parent 1; 2 - parent 2.
getFlipTrim <nurbsfilletsurface> <index>
setFlipTrim <nurbsfilletsurface> <index> <bool>
Get or set the direction to trim a parent’s surface. If true the parent surface is trimmed
from the point towards low parameter space. If false the surface is trimmed from the
point towards high parameter space. <index> = 1 - parent 1; 2 - parent 2.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
 NURBSLatheSurface : NURBSSurface 1437

NURBSLatheSurface : NURBSSurface
This class defines a dependent Lathe surface. A Lathe surface is generated from a curve sub-object. It
is similar to a surface created with the Lathe modifier. The advantage is that a lathe sub-object is part
of the NURBS model, so you can use it to construct other curve and surface sub-objects.
Constructors:
NURBSLatheSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbslathesurface>.parent : integer
The parent curve by NURBSet index.
<nurbslathesurface>.parentID : integer
The parent curve by NURBSId.
<nurbslathesurface>.axisTM : matrix3
The axis system for the surface of revolution.
<nurbslathesurface>.sweep : float
The angle of the revolution in degrees.
<nurbsextrudesurface>.curveStartPoint : float
The start point on the parent curve. This value is only applicable if the curve is closed.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSMirrorSurface : NURBSSurface
This class defines a dependent Mirror surface. A Mirror surface is similar to a mirror object that you
create using the Mirror tool (on the 3ds max toolbar) or the Mirror modifier. It is the original surface
reflected about one or two axes.
Constructors:
NURBSMirrorSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>
1438 Chapter 11 | 3ds max Objects

Properties:
<nurbsmirrorsurface>.parent : integer
The parent curve by NURBSet index.
<nurbsmirrorsurface>.parentID : integer
The parent curve by NURBSId.
<nurbsmirrorsurface>.axis : #X, #Y, #Z, #XY, #XZ, #YZ
The axis or axes of reflection for the surface.
<nurbsmirrorsurface>.distance : float
The offset from the center of the local coordinate system for the mirror object that moves
the mirror, in the direction specified by the mirror axis.
<nurbsmirrorsurface>.transform : matrix3
This is an additional transformation applied to the axis specification. This corresponds to
the gizmo the user may use interactively to alter the location of the mirror axis. This is
exactly equivalent to setting the transform on the gizmo of a mirror modifier.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSMultiCurveTrimSurface : NURBSSurface
This class defines a dependent Multicurve Trim surface which is a surface that is trimmed by multiple
curves forming a loop.
Constructors:
NURBSMultiCurveTrimSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsmulticurvetrimsurface>.surfaceParent : Integer
The parent surface by NURBSet index.
<nurbsmulticurvetrimsurface>.surfaceParentID : Integer
The parent surface by NURBSId.
<nurbsmulticurvetrimsurface>.numCurves : Integer
The number of curves used for the trim loop.
<nurbsmulticurvetrimsurface>.flipTrim : Boolean
The state of the trim flip toggle. This controls which portion of the surface is trimmed.
Methods:
 NURBSNBlendSurface : NURBSSurface 1439

getParent <nurbsmulticurvetrimsurface> <index>

Gets the NURBSSet index of the indexed trim loop.
setParent <nurbsmulticurvetrimsurface> <index> <curve>
Sets the indexed trim loop to the curve specified by the NURBSSet index.
getParentID <nurbsmulticurvetrimsurface> <index>
Gets the NURBSId of the indexed trim loop.
setParentID <nurbsmulticurvetrimsurface> <index> <curveID>
Sets the indexed curve in the trim loop to the curve specified by the NURBSId.
appendCurve <nurbsmulticurvetrimsurface> <curve>
Adds a curve to the end of the list of curves comprising the trim loop by specifying the
NURBSSet index.
appendCurveByID <nurbsmulticurvetrimsurface> <curveID>
Adds a curve to the end of the list of curves comprising the trim loop by specifying the
NURBSId.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSNBlendSurface : NURBSSurface
This class defines a dependent Multisided Blend surface. A Multisided Blend surface is a surface that
“fills in” the edges defined by three or four other curve or surfaces. Unlike a regular, two-sided Blend
surface, the curves or surfaces edges must form a closed loop (that is, sequence head to tail, and the
ends must match). That is, they must completely surround the opening the Multisided Blend will
cover.
Constructors:
NURBSNBlendSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
There are no additional properties for NURBSNBlendSurface.
Methods:
getParent <nurbsnblendsurface> <index>
Returns the NURBSSet index of the indexed curve or surface.
setParent <nurbsnblendsurface> <index> <curve>
Sets the specified parent curve or surface by NURBSSet index as the indexed edge for the
surface.
1440 Chapter 11 | 3ds max Objects

getParentID <nurbsnblendsurface> <index>

Returns the NURBSId of the indexed curve or surface.
setParentID <nurbsnblendsurface> <index> <curveID>
Sets the specified parent curve or surface by NURBSId as the indexed edge for the surface.
getEdge <nurbsnblendsurface> <index>
setEdge <nurbsnblendsurface> <index> <edge>
Get or set which edge of the indexed parent surface is used for the blend. The edge is only
applicable if the parent is a surface. the <edge> value is one of the following:
1: The low U edge
2: The high U edge
3: The low V edge
4: The high V edge

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSOffsetSurface : NURBSSurface
This class defines a dependent Offset surface. An Offset surface is offset a specified distance from the
original along the parent surface’s normals.
Constructors:
NURBSOffsetSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsoffsetsurface>.parent : integer
The parent surface by NURBSet index.
<nurbsoffsetsurface>.parentID : integer
The parent surface by NURBSId.
<nurbsoffsetsurface>.distance : float
The distance of the offset surface from the parent surface.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
 NURBSPointSurface : NURBSSurface 1441

NURBSPointSurface : NURBSSurface
This class defines an independent surface that uses points to describe its shape.
Constructors:
NURBSPointSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbspointsurface>.numPoints : point2
The number of points in the point surface in the U and V directions. If this value is
changed, the previous point data is not maintained.
<nurbspointsurface>.transform : matrix3
The transformation matrix for the NURBSPointSurface. This controls the relative position
of the item within a NURBSSet.
<nurbspointsurface>.closedU : boolean
true if the surface is closed in the U direction, false if open.
<nurbspointsurface>.closedV : boolean
true if the surface is closed in the V direction, false if open.
Methods:
closeU <nurbspointsurface>
Close the curve in U.
closeV <nurbspointsurface>
Close the curve in V.
getPoint <nurbspointsurface> <u_index> <v_index>
Get the indexed surface point as a NURBSIndependentPoint; point indexes are 1-based.
setPoint <nurbspointsurface> <u_index> <v_index> <NURBSIndependentPoint>
Get the indexed surface point to the given NURBSIndependentPoint; point indexes are
1-based.
refineU <nurbspointsurface> <v_param>
Add new row of interpolated points in the U direction on the surface at the given
parametric V point.
refineV <nurbspointsurface> <u_param>
Add new column of interpolated points in the V direction on the surface at the given
parametric U point.
refine <nurbspointsurface> <u_param> <v_param>
Add a new row and column of interpolated points on the surface at the given parametric
UV position.
1442 Chapter 11 | 3ds max Objects

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSRuledSurface : NURBSSurface
This class defines a dependent Ruled surface. A Ruled surface is generated from two curve sub-
objects. It lets you use curves to design the two opposite borders of a surface.
Constructors:
NURBSRuledSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsruledsurface>.parent1 : integer
The 1st parent curve by NURBSet index.
<nurbsruledsurface>.parent1ID : integer
The 1st parent curve by NURBSId.
<nurbsruledsurface>.parent2 : integer
The 2nd parent curve by NURBSet index.
<nurbsruledsurface>.parent2ID : integer
The 2nd parent curve by NURBSId.
<nurbsruledsurface>.flip1 : boolean
Controls the matching of parent curve direction when creating the Ruled surface. For
example, normally when you create a Ruled surface between two parent curves you don’t
want a ‘bow tie’ surface (one with the ends rotated 180 degrees so it crosses on itself in the
middle). If you simply match the parent direction you’ll get a ‘bow tie’ surface. To prevent
this you use this property to set a state indicating that one or the other should be flipped
before it’s used. In this way, when the ruled surface is created, a ‘bow tie’ won’t occur. If
true, the 1st parent’s curve direction will be flipped; if false the 1st parent’s curve
direction will not be flipped.
<nurbsruledsurface>.flip2 : boolean
If true, the 2nd parent’s curve direction will be flipped; if false the 2nd parent’s curve
direction will not be flipped.
<nurbsruledsurface>.curveStartPoint1 : float
The start point on the 1st parent curve. This value is only applicable if the curve is closed.
<nurbsruledsurface>.curveStartPoint2 : float
The start point on the 2nd parent curve. This value is only applicable if the curve is closed.
 NURBSULoftSurface : NURBSSurface 1443

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSULoftSurface : NURBSSurface
This class defines a dependent U Loft surface. A U Loft surface interpolates a surface across multiple
curve sub-objects. The curves become U-axis contours of the surface.
Constructors:
NURBSUloftSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsuloftsurface>.numCurves : integer
The number of curves used by the U Loft.
Methods:
getCurve <nurbsuloftsurface> <index>
Gets the NURBSSet index of the indexed U Loft curve; curve indexes are 1-based.
setCurve <nurbsuloftsurface> <index> <curve>
Sets the indexed U Loft curve to the curve specified by the NURBSSet index.
getCurveID <nurbsuloftsurface> <index>
Gets the NURBSId of the indexed U Loft curve in the loft; curve indexes are 1-based.
setCurveByID <nurbsuloftsurface> <index> <curveID>
Sets the indexed U Loft curve to the curve specified by the NURBSId.
appendCurve <nurbsuloftsurface> <curve> [flip:<boolean>] [startPoint:<float>] \
[tension:<float>] [useTangent:<boolean>] [flipTangent:<boolean>]
Adds a curve to the end of the list of U Loft curves by specifying the NURBSSet index. If
flip:true is specified, the interpretation of the start and end of the curve to be reversed.
startPoint: specifies the start point on the curve. This value is only applicable if the
curve is closed. tension: specifies the tension of the curve. If useTangent:true is
specified and the curve is a curve on surface, causes the U Loft to use the tangency of the
surface. This can help blend a loft smoothly onto a surface. If flipTangent:true is
specified, the tangent is flipped for the curve.
appendCurveByID <nurbsuloftsurface> <curveID> [flip:<boolean>]
[startPoint:<float>] \
[tension:<float>] [useTangent:<boolean>] [flipTangent:<boolean>]
Adds a curve to the end of the list of U Loft curves by specifying the NURBSId.
1444 Chapter 11 | 3ds max Objects

getFlip <nurbsuloftsurface> <index>

setFlip <nurbsuloftsurface> <index> <boolean>
Get or set the flip state of the indexed U Loft curve; true causes the interpretation of the
start and end of the curve to be reversed, used to control twisting in the loft.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSUVLoftSurface : NURBSSurface
This class defines a dependent UV Loft Surface. This surface is similar to the U Loft surface, but has
a set of curves in the V dimension as well as the U dimension.
Constructors:
NURBSUVLoftSurface [<property>:<val>]...
any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsuvloftsurface>.numUCurves : integer
The number of curves in the U direction used by the UV Loft.
<nurbsuvloftsurface>.numVCurves : integer
The number of curves in the V direction used by the UV Loft.
Methods:
getUCurve <nurbsuvloftsurface> <index>
Gets the NURBSSet index of the U direction indexed UV Loft curve; curve indexes are 1-
based.
setUCurve <nurbsuvloftsurface> <index> <curve>
Sets the indexed UV Loft curve in the U direction to the curve specified by the NURBSSet
index.
getUCurveID <nurbsuvloftsurface> <index>
Gets the NURBSId of the U direction indexed UV Loft curve in the loft; curve indexes are
1-based.
setUCurveByID <nurbsuvloftsurface> <index> <curveID>
Sets the indexed UV Loft curve in the U direction to the curve specified by the NURBSId.
getVCurve <nurbsuvloftsurface> <index>
Gets the NURBSSet index of the V direction indexed UV Loft curve; curve indexes are 1-
based.
 NURBSXFormSurface : NURBSSurface 1445

setVCurve <nurbsuvloftsurface> <index> <curve>

Sets the indexed UV Loft curve in the V direction to the curve specified by the NURBSSet
index.
getVCurveID <nurbsuvloftsurface> <index>
Gets the NURBSId of the V direction indexed UV Loft curve in the loft; curve indexes are
1-based.
setVCurveByID <nurbsuvloftsurface> <index> <curveID>
Sets the indexed UV Loft curve in the V direction to the curve specified by the NURBSId.
appendUCurve <nurbsuvloftsurface> <curve>
Adds a curve to the end of the list of U direction UV Loft curves by specifying the
NURBSId.
appendUCurveByID <nurbsuvloftsurface> <curveID>
Adds a curve to the end of the list of U direction UV Loft curves by specifying the
NURBSSet index.
appendVCurve <nurbsuvloftsurface> <curve>
Adds a curve to the end of the list of V direction UV Loft curves by specifying the
NURBSSet index.
appendVCurveByID <nurbsuvloftsurface> <curveID>
Adds a curve to the end of the list of V direction UV Loft curves by specifying the
NURBSId.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSXFormSurface : NURBSSurface
This class defines a dependent Transform (XForm) surface. A Transform surface is a copy of the
original surface with a different position, rotation, or scale.
Constructors:
NURBSXFormSurface [<property>:<val>]...
any of the object’s properties may be set via optional keyword arguments on the
constructor.
getObject <nurbsset> <index>

Properties:
<nurbsxformsurface>.parent : integer
The parent surface by NURBSet index.
<nurbsxformsurface>.parentID : integer
The parent surface by NURBSId.
1446 Chapter 11 | 3ds max Objects

<nurbsxformsurface>.transform : matrix3
The offset transformation matrix for the NURBSXFormSurface. This controls the relative
position of the item to the parent surface.

See also
NURBSSurface (p. 1425)
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)

NURBSTexturePoint Class

NURBSTexturePoint : NURBSObject
This class defines a single texture vertex in a NURBS texture surface.
Constructors:
NURBSTexturePoint <point2> [indices:<point2>]
Create a NURBSTexturePoint with the specified UV coordinate. If indices: is specified, it
sets the ordering the texture point in the texture surface.
getPoint <NURBSTextureSurface> <u_index> <v_index>

Properties:
<nurbstexturepoint>.pos : point2
The UV coordinate of the texture point.
Methods:
setIndices <nurbstexturepoint> <u_index> <v_index>
Sets the ordering the texture point in the texture surface.

See also
NURBSObject (p. 1402)
Value Common Properties, Operators, and Methods (p. 714)
 NURBSDisplay : Value 1447

NURBS Associated Classes

NURBSDisplay : Value
This class corresponds to the NURBS display control checkboxes in the General NURBS rollout panel.
You can exert control over the display levels in a NURBS object by either assigning NURBSDisplay
values to the .display property of a NURBSSet value or using the setSurfaceDisplay() node
function. See NURBS Node Properties and Methods (p. 1397).
Constructors:
NURBSDisplay [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
<nurbsset>.display

Properties:
<nurbsdisplay>.displayCurves : boolean
true if curves are displayed; otherwise false.
<nurbsdisplay>.displaySurfaces : boolean
true if surfaces are displayed; otherwise false.
<nurbsdisplay>.displayLattices : boolean
true if lattices are displayed; otherwise false.
<nurbsdisplay>.displaySurfCVLattices : boolean
true if surface CV lattices are displayed; otherwise false.
<nurbsdisplay>.displayCurveCVLattices : boolean
true if curve CV lattices are displayed; otherwise false.
<nurbsdisplay>.displayDependents : boolean
true if dependent sub-objects are displayed; otherwise false.
<nurbsdisplay>.displayTrimming : boolean
true if surface trimming is displayed; otherwise false.
<nurbsdisplay>.degradeOnMove : boolean
true if the surface may degrade while transforming it; otherwise false.
<nurbsdisplay>.displayShadedLattice : boolean
true if the NURBS surfaces appear as shaded lattices in shaded viewports and wireframe
viewports display the surface’s lattice without shading. false if NURBS surfaces display as
tessellated meshes in shaded viewport and wireframe viewports surfaces display as either
iso curves or wire meshes.

See also
Value Common Properties, Operators, and Methods (p. 714)
1448 Chapter 11 | 3ds max Objects

NURBSSelection : Value
An NURBSSelection represents a set of NURBS sub-objects for a scene NURBS node as a virtual array.
As such, you can access a sub-object by index, iterate over the sub-objects, and apply mapped
functions to the sub-objects. The NURBSSelection array is dynamic, i.e., its contents will change as
the sub-objects of the NURBS node change. NURBSSelection values are mappable.
Constructors:
<node>.selectedCurveCVs
<node>.selectedCurves
<node>.selectedImports
<node>.selectedPoints
<node>.selectedSurfaces
<node>.selectedSurfCVs
<node>.curveCVs -- read-only
<node>.curves -- read-only
<node>.imports -- read-only
<node>.surfaces -- read-only
<node>.surfCVs -- read-only
<node>.points -- read-only
Properties:
<nurbsselection>.count : Integer, read-only
Returns the number of sub-objects in the NURBSSelection array.
<nurbsselection>.selSetNames : Array of names, read-only
Returns an array of names of the current named selection sets corresponding to the
NURBSSelection level for the object the NURBSSelection is associated with.
The following property is present for singleton selections (of the form $foo.curveCVs[n]):
<nurbsselection>.index : Integer, read-only
Returns the index of the selected sub-object in the NURBS object, e.g.,
$foo.selectedcurveCVs[2].index

returns the curve CV index of the 2nd curve CV in the current selection.
Note that iterating over a selection yields singleton selections in the loop body:
sCVs = for i in $foo.selectedcurveCVs collect i.index
sCVs contains selected curve CVs as array
Operators:
<node>.selectedCurveCVs = (<array> | <bitarray>)
<node>.selectedCurves = (<array> | <bitarray>)
<node>.selectedImports = (<array> | <bitarray>)
<node>.selectedPoints = (<array> | <bitarray>)
<node>.selectedSurfaces = (<array> | <bitarray>)
<node>.selectedSurfCVs = (<array> | <bitarray>)
Selects the specified sub-objects.
<nurbsselection>[<integer>]
Retrieves the indexed sub-object as a singleton NURBSSelection. Index starts at 1
 NURBSSelection : Value 1449

<nurbsselection>[(<integer_array> | <bitarray>)]
Retrieves the indexed sub-objects as a NURBSSelection. Index starts at 1.
<nurbsselection>[(<#name> | <string>)]
Retrieves the sub-object level named selection set, where the name of the named selection
set can be specified as a name or string value.
<nurbsselection>[(<#name> | <string>)] = (<nurbsselection> | <integer_array> |
<bitarray>)
Sets the sub-object level named selection set to the specified edges. The name of the
named selection set can be specified as a name or string value, and the edges can be
specified as an array, bitArray, or a NURBSSelection from the same object and of the same
sub-object level.
Methods:
move <nurbsselection> <point3>
Moves the sub-objects in the NURBSSelection.
rotate <nurbsselection> <quat_or_other_rotation_form>
Rotates the sub-objects in the NURBSSelection.
scale <nurbsselection> <point3>
Scales the sub-objects in the NURBSSelection.
select <nurbsselection>
Selects the sub-objects in the NURBSSelection.
deselect <nurbsselection>
Deselects the sub-objects in the NURBSSelection.
delete <nurbsselection>
Deletes the sub-objects in the NURBSSelection.
append <nurbsselection> (<nurbsselection> | <integer>)
Appends the sub-objects(s) to the NURBSSelection.
findItem <nurbsselection> (<nurbsselection[<integer>] | <integer>)
Returns the selection index of the matching item or 0 if not found. The item is selection
index or singleton NURBSSelection.
Examples:
$foo.surfCVs[#baz] -- retrieves the surf CV selection named baz
move $foo.curves[#bar] [0,0,10] -- moves the “bar” curve selection 10 in Z
move $foo.selectedSurfCVs [0,0,10] -- moves the current surface CV selection 10 in
Z
coordsys local scale $foo.surfaces[#baz] [2,2,2]
select $foo.curveCVs[#(1,2,3,4,5)] -- select the specified curve CVs
deselect $foo.curves -- deselect all curves
delete $foo.points[#{1..31, 40..50}] -- delete the specified points
$foo.curveCVs[#fred] = $foo.selectedCurveCVs - “snapshot” the selected curve CVs

See also
Value Common Properties, Operators, and Methods (p. 714)
1450 Chapter 11 | 3ds max Objects

NURBSSet : Value
This is the class used to create NURBS objects, or retrieve data from existing NURBS objects. The
NURBSSet acts as a container for the other objects.
This class contains a table of the various NURBSObject derived entities (points, curves, surfaces) used
to make up the set. Additionally it has two ‘fuse’ tables: one for fuse curves and one for fuse surfaces.
These are used to allow the CVs in the curves or surfaces to be ‘stitched’ or ‘fused’ together so that
if one curve or surface moves the other moves with it. This class also has the surface-approximation
properties that control the object’s tessellation into triangle meshes for use in the viewports and the
production renderer.
NURBSSet values are mappable.
Constructors:
NURBSSet [<property>:<val>]...
any of the object’s properties may be set via optional keyword arguments on the
constructor
getNURBSSet <node> [#relational]
This function is used to retrieve a NURBSSet that corresponds to the specified NURBS scene
node. This allows access the internal objects inside a 3ds max editable NURBS object.
If the optional #relational parameter is not supplied, the returned NURBSSet will
contain only independent curves and surfaces, all dependent objects will be decomposed
into corresponding independent objects. So for example, if you pass an object that has a
relational model (perhaps two CV surfaces and a dependent blend surface) it will
decompose them into three CV surfaces. This will be the CV surfaces that represent the
two surfaces and the blend, but you won’t have the blend relational data. If the
#relational argument is supplied, you get back two CV surfaces and a NURBS blend
surface and the NURBSSet is an active representative for the scene object -- any changes
you make to the properties of it’s constituent NURBSObjects will be reflected directly in
the source scene object.
Properties:
<nurbsset>.numObjects : integer, read-only
<nurbsset>.count : integer, read-only
The number of internal objects in the NURBSSet.
The following properties control the surface approximation tessellation. There are dual sets of
properties, one for controlling viewport tessellation, the other for controlling renderer tessellation.
The properties correspond directly to the surface approximation controls in the NURBS surface
modifier panel. See NURBSSurfaceApproximation (p. 1453) for a description of these properties.
<nurbsset>.viewConfig : #isoOnly, #isoAndMesh, #meshOnly
<nurbsset>.viewIsoULines : integer
<nurbsset>.viewIsoVLines : integer
<nurbsset>.viewMeshUSteps : integer
<nurbsset>.viewMeshVSteps : integer
<nurbsset>.viewMeshApproxType : #parametric, #spatial, #curvature,
 NURBSSet : Value 1451

: #regular, #spatialAndCurvature
<nurbsset>.viewSpacialEdge : float
<nurbsset>.viewCurvatureAngle : float
<nurbsset>.viewCurvatureDistance : float
<nurbsset>.viewViewDependent : boolean
<nurbsset>.renderConfig : #isoOnly, #isoAndMesh, #meshOnly,
: #regular, #spatialAndCurvature

<nurbsset>.renderIsoULines : integer
<nurbsset>.renderIsoVLines : integer
<nurbsset>.renderMeshUSteps : integer
<nurbsset>.renderMeshVSteps : integer
<nurbsset>.renderMeshApproxType : #parametric, #spatial, #curvature,
: #regular, #spatialAndCurvature

<nurbsset>.renderSpacialEdge : float
<nurbsset>.renderCurvatureAngle : float
<nurbsset>.renderCurvatureDistance : float
<nurbsset>.renderViewDependent : boolean

<nurbsset>.display : NURBSDisplay
Takes and returns instances of the NURBSDisplay (p. 1447) class that controls visibility of
various components of a NURBS object’s display in the viewports.
<nurbsset>.viewApproximation : NURBSSurfaceApproximation
<nurbsset>.renderApproximation : NURBSSurfaceApproximation
These properties are used to access and control surface approximation using the
NURBSSurfaceApproximation (p. 1453) class, instances of which encapsulate all the
approximation settings for either viewports or rendering. You can construct a surface
approximation setup in one of these instances and use it to set the surface approximation
for many objects.
<nurbsset>.merge : float
Controls the tessellation of surface sub-objects whose edges are joined or very nearly
joined. When input to a modifier as Mesh Select which requires a mesh, and when NURBS
surfaces are tessellated for production rendering, by default 3ds max adjusts the
tessellation of adjoining surfaces to match each other in terms of the number of faces
along the edges. The merge value controls how this is done. If merge is zero, adjoining
faces are unchanged. Increasing the value of merge increases the distance 3ds max uses to
calculate how edges should match, guaranteeing no gaps between the surfaces when they
are rendered.
Operators:
<nurbsset>[<index>]
<nurbsset>[<index>] = <nurbsobj>
The sub-objects in a NURBSSet can be accessed using the standard MAXScript array
indexing operator, []. This is equivalent to using the getObject() and setObject()
methods described below.
1452 Chapter 11 | 3ds max Objects

Methods:
appendObject <nurbsset> <nurbsobj>
Appends the given NURBSObject (instances of any of the subclasses of NURBSObject and
their subclasses, all the points, curves, surfaces) as a new sub-object to the NURBSSet. The
new sub-object receives the next available index.
setObject <nurbsset> <index> <nurbsobj>
Set the indexed sub-object to the given NURBSObject; indexes are 1-based. You use this
function to replace a previously appended object.
getObject <nurbsset> (<index> | <NURBSSelection>)
Retrieves the indexed sub-object or the set of sub-objects specified by the NURBSSelection
from the NURBSSet; sub-object indexes are 1-based. If the NURBSSelection specifies no
sub-objects, undefined is returned. If one sub-object is specified, a value of that sub-
object’s class is returned. If multiple sub-objects are specified, a NURBSSet value is
returned.
removeObject <nurbsset> <index>
Removes the given sub-object from the NURBSSet. The indexes of all the remaining
higher-indexed sub-objects are renumbered down.
disconnect <nurbsset>
Disconnect a relational NURBS set from its scene object, turning it into a non-relational
set.
deleteObjects <nurbsset>
This method deletes all the NURBSObjects in a NURBSSet, and frees its memory.
getProdTess <nurbsset> <tessType_name>
setProdTess <nurbsset> <tessType_name> <NURBSSurfaceApproximation>
getViewTess <nurbsset> <tessType_name>
setViewTess <nurbsset> <tessType_name> <NURBSSurfaceApproximation>
These methods get and set renderer and viewport NURBSSurfaceApproximation values for
individual surfaces, where <tessType_name> is one of #surface, #displacement, or
#curve corresponding to the 3 kinds of tessellation that can be controlled on a surface.
clearProdTess <nurbsset> <tessType_name>
clearViewTess <nurbsset> <tessType_name>
Resets the surface approximation settings for the surfaces in the NURBSet for the given
tessellation type, where <tessType_name> is one of #surface, #displacement, or
#curve corresponding to the 3 kinds of tessellation that can be controlled on a surface.

See also
Value Common Properties, Operators, and Methods (p. 714)
 NURBSSurfaceApproximation : Value 1453

NURBSSurfaceApproximation : Value
Instances of this class contain a complete surface approximation setting that can be used to set the
approximation for NURBS objects described by NURBSSet values or directly in existing NURBS scene
node. You use the setViewApproximation() and setRenderApproximation() functions on
existing scene nodes and the .viewApproximation and .renderApproximation properties on
NURBSSet values.
Constructors:
NURBSSurfaceApproximation [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
<nurbsset>.viewApproximation

<nurbsset>.renderApproximation

Properties:
<nurbssurfaceapproximation>.config : #isoOnly, #isoAndMesh, #meshOnly
This property determines what is displayed in the interactive or scanline renderer.
If #isoOnly is specified, only Iso lines are displayed. Iso (parametric) lines are similar to
contour lines. The lines show where the NURBS surface has a constant U or V value or
both. Iso line representations can be less crowded and easier to visualize than wire mesh
representations.
If #isoAndMesh is specified, Iso lines and the mesh are displayed. When chosen,
wireframe viewports display iso line representations of the surface, and shaded viewports
display the shaded surface.
If #meshOnly is specified, just the mesh is displayed. When chosen, wireframe viewports
display the surface as a wire mesh, and shaded viewports display the shaded surface. In
wireframe viewports, this option lets you see the curve approximation used for viewports.
<nurbssurfaceapproximation>.isoULines : integer
This is used with the ISO line display. This is the number of additional interior iso lines in
U (there are always lines along the outer edges).
<nurbssurfaceapproximation>.isoVLines : integer
This is used with the ISO line display. This is the number of additional interior iso lines in
V (there are always lines along the outer edges).
<nurbssurfaceapproximation>.meshUSteps : integer
This is used for parametric tessellation. This is the number of tessellations in U. This is the
number of sub-divisions for a knot span for the surface.
<nurbssurfaceapproximation>.meshVSteps : integer
This is used for parametric tessellation. This is the number of tessellations in V. This is the
number of sub-divisions for a knot span for the surface.
1454 Chapter 11 | 3ds max Objects

<nurbssurfaceapproximation>.meshApproxType : #parametric, #spatial, #curvature,

: #regular, #spatialAndCurvature
This property controls the type of surface tessellation.
If #parametric is specified, parametric tessellation is performed. This provides for a fixed
number of meshUSteps by meshVSteps tessellations. There are meshUSteps times
meshVSteps quadrilaterals and each one is split up into two triangles.
If #spatial is specified, spatial tessellation is performed. This uses spacialEdge as its
parameter. This specifies that the size of the tessellation will be the spacialEdge length.
In view dependent tessellation spacialEdge is specified in pixels.
If #curvature is specified, view dependent tessellation is performed. This uses the
curvatureAngle and curvatureDistance property values.
If #regular is specified, a fixed, regular tessellation across the surface is performed.
If #spatialAndCurvature is specified, a tessellation method which combines the spatial
and curvature methods is used. This uses the spacialEdge, curvatureAngle, and
curvatureDistance property values.
<nurbssurfaceapproximation>.spacialEdge : float
This is the length of an edge to use in spatial (#spatial) tessellation. In view dependent
tessellation this is specified in pixels. If not in view dependent tessellation this is a
percentage of the bounding box diagonal length.
<nurbssurfaceapproximation>.curvatureAngle : float
This is used in curvature dependent tessellation (#curvature). If 0.0 is specified this is
ignored. If specified this ensures that no two adjacent face normals exceed this angle
between them. This value is specified in radians.
<nurbssurfaceapproximation>.curvatureDistance : float
This is used in curvature dependent tessellation (#curvature). If 0.0 is specified this is
ignored. This specifies a distance that cannot be exceeded between a vertex on the mesh
and the mathematical surface. This is defined as a percentage of the diagonal of the
bounding box of the individual surface in object space. For instance if this was set to 1.0,
the allowable error in generating a tessellation would be 1% of the bounding box diagonal
distance of the surface. This would be 1/100 (1%) of the diagonal distance of the bounding
box. In this way if an object is scaled the tessellation remains the same. Additionally, if you
have an object with a big surface and a little surface, the smaller surface will get tessellated
more finely because its own bounding box is used. This prevents the smaller surface from
just becoming a single triangle for example.
<nurbssurfaceapproximation>.viewDependent : boolean
Specifies if this is view dependent tessellation. If true this will tessellate less finely the
farther away from the camera the object is. If false the tessellation does not change based
on distance from the camera.

See also
Value Common Properties, Operators, and Methods (p. 714)
 NURBSTextureSurface : Value 1455

NURBSTextureSurface : Value
This class contains an editable texture coordinate surface corresponding to the editable texture
surface in NURBS surfaces. You can create and apply them to any NURBSSurface value or retrieve
existing texture surfaces using the getTextureSurface() and setTextureSurface() methods
to access any of the 99 texture channels for a NURBS surface.
3ds max uses the texture surface to control how materials are mapped. In effect, changing the
texture surface stretches or otherwise changes the UV coordinates for the surface, altering the
mapping. This is a 2D (not 3D) surface that lives in the parameter space of the corresponding
NURBSSurface which controls the texture mapping used by the NURBSSurface.
It is not possible to assign texture surfaces to NURBS objects that are present in the scene. You can
create new NURBSSets and the texture surface is used when you call createNURBSObject().
However, if you do a getNURBSSet() and assign a NURBSTextureSurface to a texture channel for a
NURBS surface, nothing happens.
Constructors:
NURBSTextureSurface [<property>:<val>]...
Any of the object’s properties may be set via optional keyword arguments on the
constructor.
getTextureSurface <nurbssurface> <channel_index>

<nurbssurface>.textureSurface1
<nurbssurface>.textureSurface2
Provides backward compatibility for scripts written for 3ds max R2.5. Get and set the
texture surfaces for the first two texture channels.
Properties:
<nurbstexturesurface>.type : #default, #userDefined, #projected
The type of texture surface.
<nurbstexturesurface>.parent : integer
The parent surface by NURBSet index.
<nurbstexturesurface>.parentID : integer
The parent surface by NURBSId.
<nurbstexturesurface>.numUPoints : integer -- read-only
<nurbstexturesurface>.numVPoints : integer -- read-only
<nurbstexturesurface>.numPoints : point2
The number of U and V points.
Methods:
getPoint <nurbstexturesurface> <u_index> <v_index>
setPoint <nurbstexturesurface> <u_index> <v_index> <texturepoint>
Get or set a NURBSTexturePoint value for the texture point at the U and V index of the
texture surface.
1456 Chapter 11 | 3ds max Objects

Associated Methods:
setTextureSurface <nurbssurface> <channel_index> <NURBSTextureSurface>
This method sets the texture surface for the selected channel.
Note:
The NURBSTextureSurface class has been updated to correspond to the new texture surface
mechanism in 3ds max 4, and has different properties and methods that were defined in
3ds max R3.

See also
NURBSSurface (p. 1425)
Value Common Properties, Operators, and Methods (p. 714)

Biped and Physique

The following topics describe the MAXScript access to Biped systems and the Physique modifier:
Biped : System (p. 1456)
Physique : Modifier (p. 1458)
Biped-Related Classes (p. 1457)
PhyContextExport Values (p. 1458)
PhyRigidVertex Values (p. 1459)
PhyBlendingRigidVertex Values (p. 1459)
BipedExportInterface Values (p. 1458)
The following is an example of accessing Physique data:
Script:
phy = GetPhyContextExport $ $.physique
format “Physique Export Interface\n”
for v=1 to phy.numVerts do
( vx = GetVertexInterface phy v
p = GetOffsetVector vx
--
format “\tVertex # % assigned to %\t “ (v-1) (GetNode vx).name
format “%\n” (if (classOf vx) == PhyRigidVertex then “RIGID_TYPE”)
format “\tOffset X: % Offset Y :% Offset Z: %\n” p.x p.y p.z
)

Biped : System
Constructor:
Biped systems are nor creatable by MAXScript.
Properties:
There are no properties associated with Physique.
 Biped-Related Classes 1457

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Biped-Related Classes
The following classes associated with Biped systems. Instances of these classes are not creatable by
MAXScript.
Geometry:
Biped_Object : GeometryClass
This class represents the each object within the biped system.

See also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Controllers:
Vertical_Horizontal_Turn : Matrix3Controller
This class represents the transform controller for the root object within the biped system.
BipSlave_Control : Matrix3Controller
This class represents the transform controller for each object within the biped system. If
the object does not have a transform controller (that is, it is a slave of another object in the
biped), a value of undefined is returned.
Footsteps : Matrix3Controller
This class represents both the transform controller for the footsteps and the footstep
object.

See also
Controller Common Properties, Operators, and Methods (p. 1289)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1458 Chapter 11 | 3ds max Objects

BipedExportInterface Values
The BipedExportInterface class is an interface into a Biped.
Constructor:
getBipedExportInterface <biped_node>
Returns an instance of BipedExportInterface class. The biped_node can be any node
associated with the Biped system, including the footprints.
Methods:
setNonUniformScale <BipedExportInterface> <boolean>
Biped-based bone systems created prior to character studio version R2.1 have non-uniform
scaling on the nodes that make up the biped object. This scaling can cause difficulties
when exporting the biped. This function removes or restores the non-uniform scaling on a
biped object. If <boolean> is true the non-uniform scaling will be set, and false will
remove it. All non-uniform scaling information has been removed from new bipeds
created with version R2.1 or greater of character studio, and this method is not required
for exporting these bipeds.

Physique : Modifier
Constructor:
physique ...

Properties:
There are no properties associated with Physique.

See also
Modifier Common Properties, Operators, and Methods (p. 1096)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

PhyContextExport Values
The PhyContextExport class is an interface into the physique vertex data. It can be used to retrieve
vertex data of the modifier. Currently it only supports rigid vertices (blended and non-blended). You
can use convertToRigid() to convert all vertices into rigid.
Constructor:
getPhyContextExport <node> <physique_modifier>
Returns an instance of PhyContextExport class.
Properties:
<GetPhyContextExport>.numVerts
Returns the number vertices in the object. This property is read-only.
 PhyRigidVertex Values 1459

Methods:
convertToRigid <PhyContextExport> <boolean>
Converts all vertices into rigid vertices. If a true value is passed then
getVertexInterface() converts a deformable vertex into a rigid vertex and returns the
vertex. If a false value is passed then getVertexInterface() returns undefined for a
deformable vertex.
allowBlending <PhyContextExport> <boolean>
If a true value is passed then getVertexInterface() returns a PhyBlendingRigidVertex,
if a vertex is blended, otherwise undefined.
getVertexInterface <PhyContextExport> <index_integer>
Returns the vertex given the vertex index. The vertex can be either PhyRigidVertex or
PhyBlendingRigidVertex.

See also
PhyRigidVertex Values (p. 1459)
PhyBlendingRigidVertex Values (p. 1459)

PhyRigidVertex Values
The PhyRigidVertex class representing a rigid vertex in a Physique modifier. A rigid vertex can be
linked to only one node.
Constructor:
getVertexInterface <PhyContextExport> <index_integer>
Returns the vertex given the vertex index. The vertex can be either PhyRigidVertex or
PhyBlendingRigidVertex.
Methods:
getNode <PhyRigidVertex>
Returns the node the vertex is linked to.
getOffsetVector <PhyRigidVertex>
Returns the coordinates of the vertex in the local coordinates of associated node.

PhyBlendingRigidVertex Values
The PhyBlendingRigidVertex class representing a blended vertex in a Physique modifier. A blended
vertex can be linked to multiple nodes.
Constructor:
getVertexInterface <PhyContextExport> <index_integer>
Returns the vertex given the vertex index. The vertex can be either PhyRigidVertex or
PhyBlendingRigidVertex.
1460 Chapter 11 | 3ds max Objects

Properties:
<PhyBlendingRigidVertex>.numNodes
Returns the number of nodes the vertex is linked to. This property is read-only.
Methods:
getNode <PhyBlendingRigidVertex> <index_integer>
Returns the indexed node the vertex is linked to.
getOffsetVector <PhyBlendingRigidVertex> <index_integer>
Returns the coordinates of the vertex in the local coordinates of indexed node.
getWeight <PhyBlendingRigidVertex> <index_integer>
Returns the weight of the indexed node on the vertex.

Missing Object Classes

The following classes are used to represent objects in the scene for which the plug-in defining the
object class is missing. An example of this is if you load a scene containing a Biped, but you do not
have the character studio plugins, the biped objects will be retained in the scene, and the object’s
class will be shown as the appropriate missing object class. These classes are not creatable by
MAXScript and do not have any properties or methods.
Missing_Atmospheric
Standin for missing Atmospheric class objects.
Missing_Camera
Standin for missing Camera class objects.
Missing_Float_Control
Standin for missing Float controller class objects.
Missing_GeomObject
Standin for missing Geometry object class objects.
Missing_Helper
Standin for missing Helper object class objects.
Missing_Light
Standin for missing Light object class objects.
Missing_Matrix3_Control
Standin for missing Matrix3 controller class objects.
Missing_Morph_Control
Standin for missing Morph controller class objects.
Missing_Mtl
Standin for missing Material class objects.
Missing_OSM
Standin for missing Object Space Modifier class objects.
Missing_Point3_Control
Standin for missing Point3 controller class objects.
Missing_Position_Control
Standin for missing Position controller class objects.
 PhyBlendingRigidVertex Values 1461

Missing_RefTarget
Standin for missing Reference Target class objects.
Missing_Render_Effect
Standin for missing Render Effect class objects.
Missing_Rotation_Control
Standin for missing Rotation controller class objects.
Missing_Scale_Control
Standin for missing Scale controller class objects.
Missing_Shape
Standin for missing Shape class objects.
Missing_System
Standin for missing System class objects.
Missing_TextureMap
Standin for missing TextureMap class objects.
Missing_UVGen
Standin for missing UVGen class objects.
Missing_WSM
Standin for missing World Space Modifier class objects.
Missing_WSM_Object
Standin for missing World Space Modifier Object class objects.
Missing_XYZGen
Standin for missing XYZGen class objects.

Scripting Vertex and Control Point Animation

You can add animation to vertices in editable meshes, spline shapes and FFD modifiers using the
animateVertex() method. Its syntax is:
animateVertex <node_or_ffd_modifier> <vertex_spec>
Animates one or more vertex, knot, or control point, where <vertex_spec> is one of
<index>
<index_array>
#all
#selected -- not applicable for FFD modifiers

For FFD modifiers, the animateAll() method will animate all the control points, and is equivalent
to animateVertex <ffd_modifier> #all. Its syntax is:
animateAll <ffd_modifier>
Animates all control points.
The animateVertex() and animateAll() methods effectively assign controllers to editable
meshes, spline shapes and FFD modifiers which make them appear as animatables in the Track View,
allowing further scripting of these vertex animation controllers.
1462 Chapter 11 | 3ds max Objects

Examples:
animateVertex $line01 2
animateVertex $box01 #(2,3,4,5)
animateAll $box01.ffd_3x3x3

These animateVertex() method only work on editable meshes, spline shapes and FFD modifiers
and will report an error if applied to other types of objects. You can use the functions
convertToMesh() and convertToSplineShape() to convert existing geometry into the needed
forms. Note that Line objects are SplineShapes already and don’t need conversion.
The vertices to be animated are specified by index number, with the keyword #all to animate all
vertices or control points, or #selected to animate the currently selected vertices. The #selected
keyword is not applicable to FFD modifiers. In the case of SplineShapes, the vertex index numbers
are interpreted in a special way to accommodate tangent handles and multiple curves, as follows:
• Each SplineShape vertex has three indexes, one for each in-tangent handle, vertex, and out-
tangent handle, in that order.
• The indexes run consecutively through each curve in a multi-curve shape, with the index
number for the first in-tangent handle of a curve starting after the index of the last out-tangent
handle in the prior curve.
See also Class and Object Inspector Functions (p. 799) for details on accessing the vertices, tangents, or
control points.
For information about scripting FFD control placement within FFD lattice space, see also the
getModContextBBoxMin() and getModContextBBoxMin() functions, as described in the Modifier
Common Properties, Operators, and Methods (p. 1096) topic.
For editable meshes and spline shapes, the controller values assigned to the vertices, knots, and
tangent handles is in object space. See the Using Node Transform Properties (p. 843) topic for
information on converting between world space to object space.
Chapter 12: Creating MAXScript Tools

Scripted Utilities
MAXScript provides a set of classes and functions and some special syntax to allow you to construct
custom rollouts that can be incorporated into the existing 3ds max user interface. You typically use
custom rollouts to provide a point-and-click interface to a tool that you have written or want to
write in MAXScript, so users of your tool don’t have to work with it at the script level.
There are two places in the 3ds max user interface where you can install scripted rollouts:
• In the Utilities panel. You use the utility definition construct in MAXScript to define and install
scripted utilities. Once installed, they appear in the Utilities list at the bottom of the MAXScript
rollout. If the user selects a utility in this list, its rollout(s) appear below the MAXScript rollout
and functions just like a plug-in utility.
• In special modeless rollout floater windows that you can create with the newRolloutFloater()
function. These windows appear on the desktop and function in a way similar to the Material
Editor and the Selection floater in 3ds max. You can click to alternate between them and the
main 3ds max user interface. You create individual rollout(s) for these windows using the rollout
definition construct in MAXScript and install them in a rollout floater window using the
addRollout()function.
Choosing which place is best for your scripted rollouts depends on a number of factors. It is best to
keep them in the Utilities panel if possible, as that maximizes the use of the screen and is consistent
with the 3ds max user interface conventions. However sometimes it is useful to have them in a
modeless window if the user of your tool needs to move between the various command panels while
using the tool. In some cases, you might want to provide a “float me” button on a scripted Utility
rollout, similar to the Color Clipboard utility, so the user can choose to display the rollouts in a
rollout floater window or in the Utilities panel.
The following topics provide information about scripting utility panels and rollout floater windows:
Scripted Utility Panels (p. 1464)
Utility Clauses (p. 1466)
Managing Multiple Rollouts in a Scripted Utility (p. 1468)
1464 Chapter 12 | Creating MAXScript Tools

Rollout Clauses (p. 1470)

Utility and Rollout Properties, Methods, and Event Handlers (p. 1474)
Rollout User-Interface Controls (p. 1481)
Visibility of Locals, Functions, Structures and User-Interface Items in Rollout Code (p. 1478)
Accessing Locals and Other Items in a Rollout from External Code (p. 1480)
Rollout Floater Windows (p. 1477)

Scripted Utility Panels

A scripted utility panel is created using the utility definition construct in MAXScript. The top-level
syntax is as follows:
utility <var_name> <description_string>
[ rolledUp:<boolean> ] [ silentErrors:<boolean> ]
( <utility_body> )

The <var_name> is the name of an automatically created global variable to hold the value that
represents the scripted utility panel.
The <description_string> is a string which is used as the description for the utility in the
Utilities list in the MAXScript rollout.
The optional rolledUp: parameter specifies whether the utility rollout is initially rolled up. If set
to true, the utility rollout is initially rolled up. The default value is false.
The optional silentErrors: parameter controls whether MAXScript runtime error messages are
displayed while executing the scripted utility. If this parameter is set to false, error messages are
displayed to Listener and possibly to a pop-up error dialog, and continued execution of the utility
is terminated. If this parameter is set to true, error messages will not be displayed, and continued
execution of the utility is permitted. Setting this parameter to true is useful for distributed scripted
plug-ins that may confuse the user with MAXScript error messages. The default value is false.
The <utility_body> is inside the required parentheses and is a sequence of clauses that defines
the user-interface items that will appear in the utility, along with functions and event handlers that
process user interactions, as defined in detail in the Utility Clauses (p. 1466) topic.
Here is a short example that implements a utility for spreading the positions of the objects in the
current selection. It installs a Spread objects entry in the Utilities list. When opened, the Spread
objects rollout has three check boxes and one spread amount spinner. The spread spinner event
handler is called whenever the user adjusts the spinner, and the event handler expression computes
a new position for the objects in the selection, testing the state of each check box to control the
spread.
 Scripted Utility Panels 1465

Script:
utility spread “Spread objects” -- define the utility name and description string
( local last_amt = 0 -- define and initialize local variable
--
checkbox x “Spread in x” -- create 3 checkboxes
checkbox y “Spread in y”
checkbox z “Spread in z”
spinner spread “Spread amount:” range:[-1000,1000,0] -- create a spinner
--
on spread changed amt do -- when spinner value changes...
( delta = amt - last_amt -- calculate difference in current and previous
for obj in selection do -- values for each selected object
(
-- calculate new position based on current position and selection center
p = obj.pos + normalize (obj.pos - selection.center) * delta
if x.checked then obj.pos.x = p.x -- if checkbox x checked, apply X position
if y.checked then obj.pos.y = p.y -- if checkbox y checked, apply Y position
if z.checked then obj.pos.z = p.z -- if checkbox z checked, apply Z position
)
last_amt = amt -- store spinner value as previous value
) -- end of “on spread changed”
) -- end of utility definition

The Utilities panel rollout created by the previous script looks like the following figure. The Close
button is automatically created by MAXScript in the utility rollout, and closes the rollout.

Spread objects rollout

Evaluating a utility definition does several things. It creates a new value which is an instance of the
Rollout class and contains the utility definition. It assigns this value to the named global variable
and installs the utility description in the Utilities list in the MAXScript rollout. At this point, the user
can select the utility from the Utilities list and the utility’s rollout(s) will open.
Note: If a scripted utility already exists with the same description, the old rollout(s) is replaced with
the new one(s), even if it is currently open in the Utilities panel. This allows you to incrementally
develop a utility. Each time you modify and evaluate its definition, the old version is replaced with
the new one.
1466 Chapter 12 | Creating MAXScript Tools

Utility Clauses
The <utility_body> of a scripted utility definition is composed of a sequence of utility clauses as
follows:
<utility_body> ::= { <utility_clause> }+

where
<utility_clause> ::= <rollout_clause> |
<nested_rollout>

A <utility_clause> can contain one or more instances of <rollout_clause> or

<nested_rollout>. A nested rollout is basically another self-contained rollout definition which
can be used to construct scripted utilities with multiple rollouts or populate rollout floater windows
that may be associated with the utility. A <nested_rollout> is defined as follows:
rollout <var_name> <description_string>
[ rolledUp:<boolean> ] [ silentErrors:<boolean> ]
( <rollout_body> )

where
<rollout_body> ::= { <utility_clause> }+

In other words, a rollout definition is identical to a utility definition except its description string is
not displayed in the Utilities list in the MAXScript rollout. In fact, a utility can just be considered a
special case of a rollout, and both are instances of the Rollout class.
As an example, consider the following script. In this script, line 1 defines the start of the utility, and
the utility body is lines 2 through 42. The following line ranges are utility clauses: 3 (a rollout
clause), 5 to 9 (a nested rollout), 11 to 30 (a nested rollout), 32 to 35 (a rollout clause), and 37 to 40
(a rollout clause).
Script:
utility MyUtil “My Utility”
(
local pot
--
rollout bout “About My Utility”
( button aboutMU “About” width:45 height:20
on aboutMU pressed do
messagebox “My First Utility\nby ME\nVersion .1” \
title:”About My Utility”
)--end rollout bout
--
rollout creator “The Teapot”
( group “Object Creator”
( button tea “Teapot”
spinner rad “Radius” range:[10,50,20] type:#integer
spinner seg “Segments” range:[4,32,12] type:#integer scale:1
)
 Utility Clauses 1467

--
on tea pressed do
( pot=teapot radius:rad.value
pot.name=”TestPot”
pot.segs=seg.value
) -- end on tea pressed
--
on rad changed value do
pot.radius=value
--
on seg changed value do
pot.segs=seg.value
--
) -- end rollout creator
--
on MyUtil open do
( addRollout bout
addRollout creator
) -- end on MyUtil open
--
on MyUtil close do
( removeRollout bout
removeRollout creator
) -- end on MyUtil close
--
)--end utility MyUtil

The Utilities panel rollouts created by the previous script look like the following:

Multiple rollouts defined in a utility

You can also define rollouts outside utility definitions when you want to add them to a rollout
floater window that may not be associated with a scripted utility. This is described more fully in the
Rollout Floater Windows (p. 1477) topic.
1468 Chapter 12 | Creating MAXScript Tools

A value is created for a utility or rollout when the script defining the utility or rollout is executed.
In general, the lifetime of a utility value is the entire 3ds max session, unless a new utility with the
same name is executed. The lifetime of a rollout defined in a utility is the lifetime of the utility value.
The lifetime of a rollout defined outside a utility is the lifetime of the context the rollout was defined
in. For more information, see the Scope of Variables (p. 646) topic.

Managing Multiple Rollouts in a Scripted Utility

MAXScript includes support for managing multiple rollouts in one utility, which is useful in large
scripted utilities that would be unwieldy in one rollout. There is one main rollout defined by the
user-interface items in the utility definition itself. The other rollouts are defined as nested rollouts
within the body of the utility definition. These other rollouts can be added to and removed from
the Utilities panel under script control.
You define extra rollouts with the rollout clause inside a utility definition:
utility foo “name”
(
local ...
spinner ...
...
rollout baz “name”
(
local ...
checkbox ..
on ...
)
...
)

Such nested rollouts can contain anything a utility definition can contain with the exception of
further nested rollouts. Nested rollouts are not automatically opened or closed when the parent
utility rollout opens and closes. You need to explicitly do this in the open and close handlers or other
handlers or functions in the utility. There are two new functions for this:
addRollout <rollout> [ rolledUp:<boolean> ]
removeRollout <rollout>

The rolledUp: parameter on the addRollout() function specifies whether the rollout is added in
a rolled-up state. This defaults to false, so the rollout is added fully opened. The nested rollouts are
arranged in the order of addRollout() calls, so take care in sequencing these to ensure the order
you want.
The nested rollouts do not automatically get removed when the main utility rollout is closed. You
must make sure they are explicitly removed, typically in the close handler for the main utility.
 Managing Multiple Rollouts in a Scripted Utility 1469

To always open and close extra rollouts when the main utility is opened and closed, place
addRollout() and removeRollout() calls in the main utility open and close handlers. For
example:
on foo open do
(
...
addRollout panel_1
addRollout panel_2 rolledUp:true
...
)

on foo close do
(
...
removeRollout panel_1
removeRollout panel_2
...
)

Calling removeRollout() on an already closed rollout is OK and does nothing. If, during utility
development, you forget to close a nested rollout, closing the entire MAXScript utility will remove
any remaining open scripted rollouts.
Because these rollout definitions are nested within a utility, all the locals, functions, and other items
in the utility are visible to nested rollouts, following the standard nested scoping in MAXScript. This
means you can “reach out” and access the utility’s locals, user-interface control items, and functions.
Conversely, user-interface control items and locals in nested rollouts are exposed as properties of
that rollout, so code in the main utility or other rollouts can “reach in” and access them. In the
following example, the spinner bar change handler looks at the state of a check box in the nested
rollout baz:
utility foo “name”
(
local ...
spinner bar ...
...
rollout baz “name”
(
local ...
checkbox baz_enable ...
on ...
)
...
on bar changed val do
if baz.baz_enable.checked == true then ...
1470 Chapter 12 | Creating MAXScript Tools

Rollout Clauses
Rollout clauses define the components of a rollout (utilities are considered a special case of rollouts)
and can be one of four basic things:
• Local variables, functions, or structure definitions are variables, functions, and structures whose
scope is the rollout. These locals will exist as long as the rollout value exists. The rollout value
will exist until a new value is assigned to the rollout’s variable name. Local variables are
particularly useful for storing working data associated with the rollout such as picked objects or
arrays of generated objects. The visibility of locals, and accessing rollout locals from external
code, are described in the Visibility of Locals, Functions, Structures, and User-Interface Items in
Rollout Code (p. 1478) and Accessing Locals and Other Items in a Rollout from External Code (p. 1480)
topics.
• Mouse tools are used to perform a set of actions based on mouse clicks in the 3ds max viewports,
and are described in the Scripted Mouse Tools (p. 1531) topic.
• User-interface control items are elements displayed in the rollout, such as buttons, spinners,
and list boxes.
• Event handlers are special kinds of functions associated with particular user-interface control
items. Event handlers specify the processing you want to occur when a user interacts with a user-
interface item. For example pressing a button or adjusting a spinner. These user actions generate
named events and the optional event handler you supply for that event is called when the user
action occurs. For example, if you press a button named DoIt, the on DoIt pressed event
handler expression is executed.
Formally, the syntax of a <rollout_clause> is defined as follows:
<rollout_clause> ::= <local_variable_decl> |
<local_function_decl> |
<local_struct_decl> |
<mousetool> |
<user_interface_item> |
<item_group> |
<event_handler>
Locals:
A <local_variable_decl>, <local_function_decl>, and <local_struct_decl> are exactly
the same as local variable, function, and structure definitions in MAXScript:
<local_variable_decl> ::= local <decl> { , <decl> }
<decl> ::= <name> [ = <expr> ] -- optional initial value

<local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr>

<local_struct_decl> ::= struct <name> ( <member> { , <member> } )

<member> ::= ( <name> [ = <expr> ] | <local_function_decl> )
 Rollout Clauses 1471

Examples of the previous (in order) are:

local numSelected
local numSelected = 0
fn onlyOneSelected = (selection.count == 1)
struct parents (mother=”“, father=”“)

Global variables cannot be declared as a rollout clause, however they can be declared within event
handler scripts. If you need to ensure that a variable name references a global variable, declare the
variable name as global immediately before defining the utility in your script.
When writing scripts, it is good programming practice to explicitly declare your local and global
variables. Implicit declaration is provided as a short-hand, typically used when working in the
Listener interactively or developing short scripts. When developing extended scripts, explicitly
declaring variables can reduce errors and improve readability of the code. It is also recommend that
you declare as local all variables unless you really want them to be global variables. The reasons for
this are described in the Scope of Variables (p. 646) topic.
User-Interface Items
A <user_interface_item> defines an individual button, check box, spinner, or other user-
interface control item that will appear in the rollout. These user-interface control items are described
in the Rollout User-Interface Controls (p. 1481) topic.
An <item_group> is used to place a sequence of user-interface items in a labeled box in the rollout,
so you can organize large rollouts into meaningful groups. Its syntax is:
group <group_label_string> ( { <user_interface_item> } )

The use of group is shown in the following script:

Utility Infinity “Game Utilities”
(
group “Lighting”
( label label1d “Number of Day lights:” across:2 offset:[10,0]
label label2d “0” offset:[10,0]
label label1n “Number of Night lights:” across:2 offset:[13,0]
label label2n “0” offset:[10,0]
label label3
Radiobuttons WhichOn “Active Lights:” labels:#(”Day”,”Night”)
)

group “Scene Data Dump”

( Button scenedump “Dump Scene Data”
)

group “Exclusions/Inclusions”
( Button DispExcl “Unhide Exclusions&Inclusions”
)
1472 Chapter 12 | Creating MAXScript Tools

group “Camera Mattes”

( radiobuttons CamMatte labels:#(”None”,”1”,”2”,”3”,”4”) columns:3
)

Button resetb “Reset”

)

The Utilities panel rollout which the previous script generates looks like the following figure.

Game Utilities rollout using group user-interface item

Event Handlers:
An <event_handler> is a special function definition local to a utility or rollout that you provide
to handle the processing you want to occur when a user performs an action on a user-interface item.
For example, event handlers are called when the user presses a button or adjusts a spinner, opens or
closes the utility or rollout, or resizes or moves a rollout floater window. These user actions generate
named events and any event handler you supply for that event is called when the action occurs. The
syntax for defining an event handler is as follows:
on <item_name> <event_name> [ <argument> ] do <expr>
 Rollout Clauses 1473

The <item_name> specifies the name of the item to which this handler is connected. The
<event_name> specifies the type of event to be handled and the optional <argument> is used to
pass various values to the handler. The possible events you can specify depend on the item type.
These events include:
pressed
changed
picked
entered
selected
resized
moved
open
close

The available events and the arguments passed are defined in the description for each user-interface
item type, as listed in the Rollout User-Interface Controls (p. 1481) topic. The available events and the
arguments passed for utilities and rollouts are described in the Utility and Rollout Properties, Methods,
and Event Handlers (p. 1474) topic.
You can access and invoke the event handler functions in a scripted rollout by referring to the
handlers as properties on the user-interface items. The event handler functions are accessed as
sub-properties of the item, using the event name as the sub-property name. For example, if a scripted
rollout had a check box item named foo, and an on foo changed event handler was defined, you
could invoke the handler as follows:
foo.changed true -- call foo’s ‘changed’ handler function, passing argument of true

Or, if a scripted rollout had a button item named apply, and an on apply pressed event handler
was defined, you could invoke the handler as follows:
apply.pressed() -- call apply’s ‘pressed’ handler function, no argument.

You can access an event handler function as a sub-property of the item. For example,
ApplyPressedEH = apply.pressed

stores a copy of the on apply pressed event handler function value to variable ApplyPressedEH.
The event handler functions can only be read in this way. You cannot set the handler function to
another user-defined function.
1474 Chapter 12 | Creating MAXScript Tools

Utility and Rollout Properties, Methods, and Event Handlers

Properties:
Several properties are available for scripted utilities and rollouts which provide control over whether
a rollout is open and the rollout scroll state. These properties are:
<rollout_or_utility>.open Boolean
Indicates whether the rollout is in an open or rolled-up state. If true, the rollout is open,
false it is rolled up. You can assign true or false to this property to open or roll up the
rollout.
<rollout_or_utility>.scrollPos Integer
This property is, strictly speaking, a property of the entire collection of rollouts in a rollout
floater window or the Utilities panel, and gives the scroll position for the rollout set when
opened in a panel that is too small to show all the rollouts. It can be accessed as a property
on any rollout currently present in a rollout floater window or the Utilities panel.
You can implement a form of rollout state save and restore for your scripted rollouts by recording
the open state of all rollouts and the scrollPos of the entire panel during close handler
processing, and then reset the values in the open handler.
Methods:
Several methods are available for opening and closing utilities, and adding and removing rollouts in
the Utilities panel. These methods are:
openUtility <utility>
Opens the utility’s main rollout in the Utilities panel. This is equivalent to selecting the
utility from the Utilities list in MAXScript’s Utilities panel rollout.
closeUtility <utility>
Closes the utility’s main rollout in the Utilities panel. This is equivalent to clicking the
Close button in this rollout.
addRollout <rollout> [ rolledUp:<boolean> ]
Adds the rollout to the Utilities panel. The rolledUp: parameter on the addRollout()
function specifies whether the rollout is added in a rolled-up state. This defaults to false,
so the rollout is added fully opened. The extra rollouts are arranged in the order of
addRollout() calls, so take care in sequencing these to ensure the order you want.
removeRollout <rollout>
Removes the rollout from the Utilities panel.
See the Managing Multiple Rollouts in a Scripted Utility (p. 1468) topic for more information on the
addRollout() and removeRollout() methods.
 Utility and Rollout Properties, Methods, and Event Handlers 1475

Event Handlers:
In addition to the event handlers you specify for particular user-interface items in a rollout, you can
define handler functions that are called when an entire rollout is first opened (open) or explicitly
closed (close) by the user. These event handlers are useful for initialization code or for cleaning up
when a rollout closes, and are necessary when managing multiple rollouts in one scripted utility. If
a rollout floater window is resized or moved, an event handler (resized or moved, respectively)
is called on the first rollout in the rollout floater window. An additional event handler (oktoclose)
is called to verify that it is OK to close a rollout. The syntax is as follows:
on <rollout_or_utility> open do <expr>
Called when the rollout or utility is opened.
on <rollout_or_utility> close do <expr>
Called when the rollout or utility is closed.
on <rollout_or_utility> oktoclose do <expr>
Called when the user clicks the rollout’s Close button so the script writer can decide
whether to allow the close to proceed. If the expression evaluates to the value true, the
rollout is allowed to close. If the expression evaluates to the value false, the action
attempting the close is ignored and the rollout or utility is left open.
on <rollout> resized <arg> do <expr>
Called on first rollout in a rollout floater window when it is resized either by the user or by
a script changing the size property of the rollout floater window. Changing the rollout
floater window size in the resized event handler expression will not cause the resized
event handler to be called again. The value of <arg> is the current width and height of the
rollout floater window. For example:
global my_rof_size
...
on my_rollout resized size do
( my_rof_size = size -- save the new window size
)

on <rollout> moved <arg> do <expr>

Called on first rollout in a rollout floater window when it is moved either by the user or by
a script changing the pos property of the rollout floater window. The value of <arg> is the
current position of the rollout floater window on the screen in pixels.
1476 Chapter 12 | Creating MAXScript Tools

The following example keeps a log file of its actions, and uses the rollout open and close handlers
to open and close the log file:
utility frab “Optimal Frabulator”
(
local log
spinner frab_x ...
button do_it “Enfrabulate now”
...
on do_it pressed do
(
frabulate selection
format “selection frabbed at %\n” localTime to:log
)
on frab open do log = createFile “frabulator.log”
on frab close do close log
)

In the following example the utility will not close unless the “OK To Close” check button is pressed:
Script:
utility ui_oktoclose “OKToClose Test”
(
checkbutton a2 “OK To Close”
on ui_oktoclose oktoclose do a2.state
)

In the following example the on a resized event handler is called when the rollout floater window
is resized. Because the event is generated only for the first rollout in a rollout floater window, the
on b resized event handler is never called.
Script:
rollout a “Rollout A”
( button a1 “a1”
on a resized val do (format “A: %\n” val)
)
--
rollout b “Rollout B”
( button b1 “b1”
on b resized val do (format “B: %\n” val)
)
--
rof=newrolloutfloater “test” 200 200
addrollout a rof
addrollout b rof
rof.size=[300,300]
 Rollout Floater Windows 1477

Rollout Floater Windows

MAXScript lets you create modeless dialog windows and populate them with rollouts defined using
global rollout definitions or utility rollout definitions. The user can resize a rollout floater window
vertically by dragging on the lower window edge.
There are two functions and a special class in support of this, as follows:
newRolloutFloater <title_string> <width_integer> <height_integer> \
[<top_integer> <left_integer>]
Creates and opens a new rollout floater window with the title and width and height given.
If you don’t supply top and left coordinates, the window will open centered in the screen.
The width of the 3ds max command panel is 218, in case you want to duplicate its width
for precisely accommodating Utilities panel rollouts.
This method returns a RolloutFloater value to which you add rollouts.
closeRolloutFloater <rolloutFloater>
Closes the rollout floater window. The user can also do this by clicking the close box on
the window. Once closed, the window is no longer usable. All the close handlers in the
rollout floater window’s rollouts are called and they are released for use in other rollout
floater windows or scripted utilities.
The existing functions for adding and removing rollouts to the Utilities panel are extended to work
with rollout floater windows:
addRollout <rollout> [ <rolloutFloater> ] [ rolledUp:<boolean> ]
If the optional second argument is specified, it must be a RolloutFloater value as returned
from the newRolloutFloater() function. The rollout specified by the first argument is
appended after any rollouts previously in the window.
removeRollout <rollout> [ <rolloutFloater> ]
Removes the rollout from the given rollout floater window.
In both functions above, if the optional <rolloutFloater> is not supplied the rollout is added to,
or removed from, the Utilities panel, as described in the Managing Multiple Rollouts in a Scripted Utility
(p. 1468) topic.
Rollout floater windows have the following properties:
<rolloutFloater>.size Point2
The current size of the rollout floater window in pixels. The first component of the Point2
is the width, the second the height. This property is read/write.
<rolloutFloater>.pos Point2
The current screen position of the rollout floater window in pixels. This property is read/
write.
When a rollout floater window is resized, either by the user or by a script changing the size
property, a resized event is generated for the first rollout in the rollout floater window. Likewise,
when a rollout floater window is moved, either by the user or by a script changing the pos property,
a moved event is generated for the first rollout in the rollout floater window. The event handler for
1478 Chapter 12 | Creating MAXScript Tools

the resized and moved events are described in the Utility and Rollout properties, Methods, and Event
Handlers (p. 1474) topic.
Example:
rollout grin “Grin Control”
( slider happy “Happy” orient:#vertical across:5
slider sad “Sad” orient:#vertical
slider oo “OO” orient #vertical
slider ee “EE” orient #vertical
slider oh “OH” orient:#vertical

on happy changed val do object.xform1.center = ...

on sad changed val do object.xform2.gizmo.rotation = ...
...
)

gw = newRolloutFloater “Grinning” 300 220

addRollout grin gw

Visibility of Locals, Functions, Structures, and User-Interface Items in

Rollout Code
The ordering of user-interface items and functions and sub-rollouts in a utility is important when
referencing other items and rollouts in handler or local function code. Specifically, you can only
reference a user-interface item or rollout or function in a handler or other function if that item or
rollout or function has been defined earlier in the utility. A recommended ordering can help
ensure this:
local variables
structs
user-interface items
nested rollouts
functions
event handlers

In some situations, cross-referencing means there’s no way to order definitions and still pre-define
everything. To remedy this, MAXScript lets you pre-declare local rollouts and functions, so code that
comes before the function or rollout definition will see the correct object. You do this by declaring
such rollouts and functions as uninitialized locals. In the following example, there are two rollouts,
ro1 and ro2, that each want to reference items within the other. By pre-declaring them as locals in
the main utility, this cross-referencing is possible:
 Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code 1479

utility foo “name”

(
local ro1, ro2, ... -- declare local rollouts
...
rollout ro1 “name”
( local ...
checkbox enable ...
on ... do
ro2.enable.checked = false
)
...
rollout ro2 “name1”
( local ...
checkbox enable ...
on ... do
ro1.enable.checked = true
)
...
)

As a general rule, it is recommended that all local variable names be explicitly declared as locals at
their outermost scope. This will prevent any conflicts from occurring if another script has declared
the same variable name as a global variable. While functions, structures definitions, and rollouts will
always be local to the utility they are defined in (even if they have the same name as a global
variable), declaring these as local will ensure the variables are defined, even if the order in which
they are defined is changed. Here’s an example showing these declarations:
utility foo “Object Frabulator”
(
-- local variables
local target_obj
-- local functions
local prop_name
-- local rollouts
local setup

fn prop_name obj name =

for c in obj.children do c.name = name + “_” + c.name

checkbutton setup_btn “Setup”

edittext name_box “New name:”

-- use a checkbutton to dynamically control presence of panels

on setup_btn changed state do
if state then addRollout setup else removeRollout setup

on foo close do
removeRollout setup -- always close rollouts

rollout setup “Setup fraber” -- local panel

(
1480 Chapter 12 | Creating MAXScript Tools

label hello
pickbutton pick_tgt “Pick object”
on pick_tgt picked obj do
( target_obj = obj -- access utility local
name_box.text = obj.name -- access utility item
prop_name obj obj.name -- call utility local fn
)
)
)

Accessing Locals and Other Items in a Rollout from External Code

The local components defined in a scripted utility or rollout are accessible to external code as
properties of the utility or rollout object. Recall that the rollout object is assigned to a new global
variable (or local variable if a nested rollout) named on the utility or rollout definition.
Example:
utility foo “Object Frabulator”
( local var1, var2, ...
...
checkbox enable “Enable frabber”
...
rollout setup “Setup frabber” -- local panel
( local var3
button doit “Execute”
...
on doit pressed do ...
)

function frab a b = ...

...
on enable changed state do ...
...
)

The example defines the utility and places the utility object in a global variable named foo. You can
access components in the utility from the Listener or other code as properties of that object, using
the name of the variable or item as the property name. Any event-handler functions supplied for
user-interface items can also be accessed as sub-properties of the item, using the event name as the
property name. For example:
print foo.var1 -- get foo’s local variable, var1
if foo.enable then ... -- test foo’s enabled checkbox
foo.enable = false -- set it
foo.enable.changed false -- call its ‘changed’ handler function
foo.frab $box01 $box02 -- call its ‘frab’ function
foo.setup.var3=10 -- set foo’s setup rollout local variable, var3
foo.setup.doit.pressed() -- call ‘changed’ handler function for doit button in
setup rollout
 Rollout User-Interface Controls Common Properties 1481

The local variables, functions, and structures in scripted utilities and rollouts are initialized as soon
as the utility or rollout is first defined, rather than when the utility or rollout is first displayed. This
allows other code to use local functions and set local values at any time after definition.

Rollout User-Interface Controls

There are 16 types of user-interface control items that you can choose from to construct your rollout.
They all share the same overall syntax:
<item_type> <name> [ <label_string> ] [ <parameters> ]

The item types correspond to the types of user-interface control items you see in typical 3ds max
rollouts. The types of user-interface control items are described in the Rollout User-Interface Control
Types (p. 1484) topic.
The <name> is used to name an automatically constructed rollout local variable that will hold the
value representing the control item, and is used to associate event handler functions with the
control item. The optional <label_string> is used as a caption, item label, or text content
depending on the control item type, as described in the topics for each type. The optional
<parameters> is a sequence of keyword arguments used to set options or influence layout for the
control item. The exact parameters that each control item type supports is also defined in the topics
for each type.
There are properties associated with each of the user-interface control item types. The properties that
are common to all user-interface control item types are described in the Rollout User-Interface Controls
Common Properties (p. 1481) topic. Properties that are unique to a user-interface control item type are
defined in the topics for each type.
As you define a sequence of control items, MAXScript will by default automatically lay them out in
the rollout, one below the other in the order they are defined. You can override this layout or make
adjustments to it using special layout parameters defined in the Rollout User-Interface Controls
Common Layout Parameters (p. 1483) topic.

Rollout User-Interface Controls Common Properties

All defined user-interface controls have a local variable constructed for them in the rollout and a
value representing the control is placed in that variable. These values typically contain state
information relevant to the item, such as if a check box is checked, the current spinner value, the
items in a list box, and so on. This information is made available to you as various named properties
on the item values. You use standard MAXScript property access to read and set these values, for
example:
frab_x.enabled = true
enable the frab_x spinner
foo.text = “Don’t do it”
set foo button text
first_item = baz.items[1]
get item list from listbox baz
1482 Chapter 12 | Creating MAXScript Tools

$bar.pos.x = x_spinner.value
get current value from spinner x_spinner
All of the user-interface common properties except for caption (the label string value is used as the
caption) can be specified as parameters when the user-interface item is constructed. For example:
button foo “Press Me!” enabled:false

The following properties are common to all user-interface items:

<ui_item>.caption String
The meaning of this property varies depending on the specific user-interface item type. If
the user-interface item has a caption, this property contains the caption string. For the
various types of buttons, it is the text inside the button. The default value of the caption is
the label string specified in the item definition.
<ui_item>.text String
For all the user-interface items except edittext and combobox, the text property is an
alias of the caption property. For edittext and combobox user-interface items, it is the
text in the edit box. The default text property value for edittext user-interface items is
a null string (”“). The default text property value for combobox user-interface items is the
selected item’s text.
<ui_item>.enabled Boolean default: true
Sets whether the item is enabled for interaction when the rollout is initially opened.
Disabled items appear unavailable in the rollout. All items are enabled by default, so you
typically use this parameter to disable those items that should not initially be available to
the user. For example, you might have some spinners that change the properties on a
scene object that should not be changed until the user has picked the object, typically
with a pickbutton in the rollout. You would disable the spinner in its definition, as in
the following example, and enable it once the user picked an object.
spinner frab_x “Frabulate x-axis:” range:[0,100,0] enabled:false
...
frab_x.enabled=true

<ui_item>.pos Point2 default: varies

This forces the user-interface item to a fixed [x,y] pixel position in the rollout, with [0,0] at
the top-left corner.
Notes:
Due to limitations in 3ds max, you cannot specify a node using a Pickbutton in the Create panel,
for example in a scripted Geometry plugin. The work-around is to only enable the Pickbutton when
the object is open in the Modify Panel.

See also
Rollout User-Interface Controls (p. 1481)
Rollout User-Interface Controls Common Layout Parameters (p. 1483)
 Rollout User-Interface Controls Common Layout Parameters 1483

Rollout User-Interface Controls Common Layout Parameters

The layout of user-interface items defined in a utility or rollout is, by default, handled by MAXScript.
It places each successive interface item down the rollout, one below the other, horizontally and
vertically aligning them to match the layout conventions in the built-in 3ds max command panels.
For the most part, this works well, particularly for rollouts displayed in the Utilities panel, because
there is usually just enough room for one item across. In some cases, you may want to adjust or
override the automatic layout and for this there are a number of definition-line layout parameters
you can use.
The user-interface element <parameters> that can be supplied in the item definition varies with
the item type and is defined in each type’s topic, for example spinner ranges, check box initial states,
list box contents, and so on. There is, however, a set of common layout parameters that you can
specify on any user-interface item. Except for the pos parameter, these parameters are not properties
of the user-interface item and cannot be accessed or changed by a script. The common layout
parameters for all user-interface items are:
align:#left
align:#center
align:#right
Aligns the user-interface item to the left, center, or right in the rollout. Default varies
by type.
offset: <point2> default: [0,0]
Specifies an [x,y] offset in pixels relative to automatic placement. This is applied after all
other layout parameters are applied, and can be used to adjust them.
width: <number> default: varies
Forces the user-interface item to a specified width in pixels. Useful with buttons, for
example, which otherwise self-size to their text label. Specifying an explicit width always
overrides any widths computed from the text or caption properties. For example, if a
spinner is given a fixed width that is too small for both label and spinner, it always aligns
things to show the spinner and so might push the text out of view.
height: <number> default: varies by type
Forces the user-interface item to a specified height, typically in pixels. This lets you
override the default setting height for user-interface items. For example
button foo “Stop” width:75 height:25

makes a nice big stop button.

For comboBox, dropdownList and listBox user-interface items, the height is in text
rows. To have a comboBox exactly display N items, set height to N+2. To have a
dropdownList exactly display N items in the list, set height to N+2. To have a listBox
exactly display N items, set height to N. Height has no affect on spinner and slider
user-interface items.
1484 Chapter 12 | Creating MAXScript Tools

across: <number> default: 1

Causes this and following <number>-1 items to be laid out horizontally rather than
vertically. The <number> given defines how many items to arrange horizontally. Layout
then reverts to normal vertical placement. This parameter effectively divides the utility
into the given number of equal-width columns and places items within them using the
normal alignment for each item. The other layout parameters can be used with the
across: parameter to control layout within the item’s column.
pos: <point2> default: varies
This forces the user-interface item to a fixed [x,y] pixel position in the rollout, with [0,0] at
the top-left corner.
Examples:
button foo “foo” align:#right
normal alignment is center
button baz “baz” align:#right offset:[0,6]
align right and bump this button down a bit
radiobuttons btn1 “Size:” labels:#(”Big”, “Bigger”, ...) columns:3
three columns of buttons
checkbutton b1 “yes” across:3
checkbutton b2 “no”
checkbutton b3 “maybe”
put b1, b2, b3 across
spinner s1 “Length:” align:#left
normal alignment is right

See also
Rollout User-Interface Controls (p. 1481)
Rollout User-Interface Controls Common Properties (p. 1481)

Rollout User-Interface Control Types

There are 17 types of user-interface controls you can choose from to construct your rollout. The
user-interface control types are:
bitmap (p. 1487)
button (p. 1488)
checkbox (p. 1489)
checkbutton (p. 1490)
colorpicker (p. 1492)
combobox (p. 1493)
dropdownlist (p. 1494)
edittext (p. 1496)
label (p. 1497)
 Rollout User-Interface Controls Common Layout Parameters 1485

listbox (p. 1497)

mapbutton (p. 1499)
materialbutton (p. 1500)
multilistbox (p. 1502)
pickbutton (p. 1504)
progressbar (p. 1505)
radiobuttons (p. 1506)
slider (p. 1507)
spinner (p. 1509)
timer (p. 1512)
The following script will display all of the user-interface types in the Utilities panel:
Script:
utility ui_items “ui items”
(
bitmap a1 bitmap:(bitmap 50 50)
button a2 “button”
checkbox a3 “checkbox”
checkbutton a4 “checkbutton”
colorpicker a5 “colorpicker: “
combobox a6 “combobox:” items:#(”1 / 2”, “1 / 4”, “1/8”) height:5
dropdownlist a7 “dropdownlist:” items:#(”1 / 2”, “1 / 4”, “1/8”)
edittext a8 “edittext: “
label a9 “label”
listbox a10 “listbox: “ items:#(”1 / 2”, “1 / 4”, “1/8”) height:3
mapbutton a11 “mapButton”
materialbutton a12 “materialbutton”
pickbutton a13 “pickbutton”
progressbar a14
radiobuttons a15 “radiobuttons: “ labels:#(”lbl 1”, “lbl 2”, “lbl 3”)
spinner a16 “spinner: “
slider a17 “slider: “
timer a18
)
1486 Chapter 12 | Creating MAXScript Tools

The resulting Utilities panel rollout will appear as:

Utilities rollout showing all user-interface items

 Bitmap 1487

Bitmap
A bitmap item is used to place a bitmap image on the rollout. The syntax is:
bitmap <name> [ <caption> ] \
[ fileName:<filename_string> | bitmap:<bitmap> ]

The default alignment of bitmap items is #center. There is no caption or text displayed with
bitmap items.
Example:
bitmap the_bmp fileName:”my_pic.bmp”
Parameters:
fileName:
The name of the bitmap file to load and display. The size of the bitmap image in the
rollout is the bitmap file image size. The specified file name is searched for in the following
directories (in order of search): current MAXScript directory, MAXScript startup directory,
MAXScript directory, 3ds max bitmap directories, and then the 3ds max image directory.
bitMap:
You can specify a bitMap: creation parameter in place of the fileName: parameter that is
used to specify a bitmap file. This allows you to use an existing bitmap value, such as those
generated by a call to the render function. You can set bitmap to an “empty” image of a
specified size by specifying a bitmap value constructor. For example:
bitmap BitmapImage bitmap:(bitmap 50 50)

Properties:
<bitmap>.fileName String
The bitmap item file name as a string. You can change the image at any time by setting
this property to a new name, but it will not resize the display area in the rollout; it will
always be the size set from the initial image.
<bitmap>.bitmap TextureMap
A write-only property that is used to set the image displayed from a MAXScript bitmap
value, as might be derived from functions like render() or selectBitmap(). You can
change the image at any time by setting this property to a bitmap value, but it will not
resize the display area in the rollout; it will always be the size set from the initial image.
Events:
-- none --

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)
1488 Chapter 12 | Creating MAXScript Tools

Button
A button item is used to place a press button on the rollout which the user can click, typically to
have some task performed. The syntax is:
button <name> [ <caption> ] [ images:<image_spec_array> ] \
[ toolTip:<string> ]

The default alignment of button items is #center.

Example:
button clone “Create Clones”

on clone pressed do ...

Parameters:
images:
An image-specification array for providing bitmap images for the button. If this is
specified, the <label> is ignored and the contents of the button are replaced with the
bitmaps. The form is:
images:#(<image>, <maskImage>, <count_integer>, \
<enabled_out_image_index>, <enabled_in_image_index>, \
<disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a

MAXScript bitmap value. <count_integer> specifies the number of sub-images in
the bitmaps, and the image_index values specify which sub-image in the bitmaps is
to be used for each of the four button states. For example:
bm1 = render camera:$cam01 outputSize:[80,60].
...
button foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use the rendered image as the button image, and

button decay images:#(”dcybtns.bmp”, “dcymask.bmp”, 6, 1, 4, 1, 4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out
and in states of the button, respectively.
See also the Image Buttons (p. 1513) topic.
toolTip:
Provides text for a tooltip for the button; no tooltip if unsupplied.
 Checkbox 1489

Properties:
<button>.images Array
Sets the image-specification array for the button. For example:
-- re-render, update button
bm1 = render()
foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

This property is write-only.

Events:
on <button> pressed do <expr>
Called when the user clicks the button.

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)

Checkbox
A checkbox item is used to place a check box on the rollout. The user can click to successively switch
between states. The syntax is:
checkbox <name> [ <caption> ] [ checked:<boolean> ]

The default alignment of checkbox items is #left.

Example:
checkbox frab_enable “Enable frabing”

on frab_enable changed state do ...

...
if frab_enable.checked then frabulate master_obj
...

Parameters:
checked:
Initial state of the check box, defaults to false (unchecked).
Properties:
<checkbox>.checked Boolean
The state of the check box, on (true) or off (false).
<checkbox>.state Boolean
Synonym for .checked
1490 Chapter 12 | Creating MAXScript Tools

Events:
on <checkbox> changed <arg> do <expr>
Called when the user clicks the check box to check or uncheck it. The <arg> argument
contains the new state of the check box, on (true) or off (false).

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)

Checkbutton
A checkbutton item is used to place a press button on the rollout that has two states, on and off, just
like a check box. The user can click to successively switch between states. The syntax is:
checkbutton <name> [ <caption> ] [ highlightColor:<color> ] \
[ toolTip:<string> ] \
[ checked:<boolean> ] \
[ images:<image_spec_array> ]

The default alignment of checkbutton items is #center.

Example:
checkbutton setup “Setup” checked:true tooltip:”Opens setup panels”
on setup changed state do
if state == on
then openRollout setup_pan
else closeRollout setup_pan

Parameters:
checked:
Initial state of the check button, defaults to off.
highlightColor:
The background color of the check button in its pressed (or on) state, defaults to a light-
gray wash in keeping with 3ds max user-interface conventions.
toolTip:
Provides text for a tooltip for the check button; no tooltip if unsupplied.
 Checkbutton 1491

images:
An image-specification array for providing bitmap images for the check button. If this is
specified, the <label> is ignored and the contents of the check button are replaced with
the bitmaps. The form is:
images:#(<image>, <maskImage>, <count_integer>, \
<enabled_out_image_index>, <enabled_in_image_index>, \
<disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a

MAXScript bitmap value. <count_integer> specifies the number of sub-images in
the bitmaps, and the image_index values specify which sub-image in the bitmaps is
to be used for each of the four check button states. For example:
bm1 = render camera:$cam01 outputSize:[80,60]
...
checkbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the check button image, and

checkbutton decay images:#(”dcybtns.bmp”, “dcymask.bmp”, 6, 1, 4, 1, 4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out
and in states of the check button, respectively.
See also the Image Buttons (p. 1513) topic.
Properties:
<checkbutton>.checked Boolean
The state of the check button, on (true) or off (false).
<checkbutton>.state Boolean
Synonym for .checked
<checkbutton>.images Array
Sets the image-specification array for the check button. For example:
-- re-render, update button
bm1 = render()
foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

This property is write-only.

Events:
on <checkbutton> changed <arg> do <expr>
Called when the user clicks the check button to change its state; the <arg> argument
contains the new state of the check button, on (true) or off (false).
1492 Chapter 12 | Creating MAXScript Tools

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)

Colorpicker
A colorpicker item is used to place a 3ds max color selection swatch on the rollout. The user can click
the swatch to display a Color Selector dialog or drag colors to or from it. The syntax is:
colorpicker <name> [ <caption> ] [ color:<color> ] \
[ fieldWidth:<number> ] [ height:<number> ] \
[ title:<string> ]

The default alignment of colorpicker items is #left.

Exampl:e
colorpicker foo “Wire color:” color:[0,0,255]

on foo changed new_col do selection.wirecolor = new_col

Parameters:
color:
Initial color of the swatch. Defaults to blue.
title:
The title displayed on the Color Selector dialog. Defaults to “Choose a color”.
fieldWidth:
The width in pixels of the swatch. Defaults to 40.
height:
The height in pixels of the swatch. Defaults to 16.
Properties:
<colorpicker>.color Color
The current swatch color.
Events:
on <colorpicker> changed <arg> do <expr>
Called when the user selects a new color in the open Color Selector dialog for this swatch
or drops a new color on it. The <arg> argument contains the new color.

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)
 Combobox 1493

Combobox
A combobox item is used to place a combo box list in the rollout. This is a variant of the drop-down
list in which the list is always fully displayed in the rollout with an additional edit-text box at the
top of the list where the current selection is placed and may be edited. The user can scroll the list or
click to select an item in the list. The syntax is:
combobox <name> [ <caption> ] [ items:<array_of_strings> ] \
[ selection:<number> ] [ height:<number> ]

The default alignment of combobox items is #left.

Example:
combobox scale_cb “Scale” items:#(”1 / 2”, “1 / 4”, “1/8”, “1/16”)

on scale_cb selected i do
format “You selected %\n!” scale_cb.items[i]

scale_cb.selected = “new item text”

Parameters:
text:
The text string in the edit box.
items:
The array of text strings that are the items in the list
selection:
The 1-based number of the currently selected item in the list. Defaults to 1.
height:
The overall height of the combobox in number of item lines. Defaults to 10 lines. To have
a combobox display exactly N items in the list, set height to N+2.
Properties:
<combobox>.caption String
The text of the optional caption above the combo box.
<combobox>.text String
The text in the edit box.
<combobox>.items Array
The item string array.
<combobox>.selection Integer
The currently selected item number, 1-based. If the items list is an empty array, this value
is 0.
<combobox>.selected String
The text of the currently selected item. Can be used to replace individual items without
resetting the entire items array. If the items list is an empty array, this value is
undefined.
1494 Chapter 12 | Creating MAXScript Tools

Events:
on <combobox> selected <arg> do <expr>
Called when the user selects an item in the combo box list. The <arg> argument contains
the new current selection item number.
on <combobox> doubleClicked <arg> do <expr>
Called when the user double-clicks an item in the list. Note that the on selected handler
is always called on single clicks and on the first click of a double-click. The <arg>
argument contains the number of the item double-clicked. For example
combobox foo items:#(...)
on foo doubleClicked sel do ...

on <combobox> entered <arg> do <expr>

Called when the user changes the text in the edit box then changes the focus away from
the edit box. This handler is not called if the user presses ENTER. The <arg> argument
contains the new text in the edit box.
on <combobox> changed <arg> do <expr>
Called for each individual character change the user performs in the edit box. This handler
is not called when the user presses ENTER or changes the focus away from the edit box.
The <arg> argument contains the new text in the edit box.

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)

Dropdownlist
A dropdownlist item is used to place a drop-down list in the rollout. The user can click open the
list and scroll or click again to select an item in the list. The syntax is:
dropdownlist <name> [ <caption> ] [ items:<array_of_strings> ] \
[ selection:<number> ] [ height:<number> ]

The default alignment of dropdownList items is #left.

Example:
dropdownlist scale_dd “Scale” items:#(”1 / 2”, “1 / 4”, “1/8”, “1/16”)

on scale_dd selected i do
format “You selected %\n!” scale_dd.items[i]
 Dropdownlist 1495

Parameters:
items:
The array of text strings that are the items in the list.
selection:
The 1-based number of the currently selected item in the list. Defaults to 1.
height:
The overall height of the dropdownlist in number of item lines. Defaults to 10 lines. To
have a dropdownlist exactly display N items in the list, set height to N+2.
Properties:
<dropdownlist>.items Array
The item string array.
<dropdownlist>.selection Integer
The currently selected item number, 1-based. If the items list is an empty array, this value
is 0.
<dropdownlist>.selected String
The text of the currently selected item. Can be set to replace individual items without
resetting the entire items array. If the items list is an empty array, this value is
undefined.
Events:
on <dropdownlist> selected <arg> do <expr>
Called when the user selects an item in the drop-down list. The <arg> argument contains
the new current selection item number.
Example:
rollout test “t”
( dropdownlist dd “dd” items:#(”1”,”2”,”3”,”4”,”5”,”6”,”7”,”8”,”9”,”10”) height:6
label l “L”
)
rof=newrolloutfloater “A” 200 200
addrollout test rof
you will get 5 items in the dropdown list. Change height to 5, and you get 3.

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)
1496 Chapter 12 | Creating MAXScript Tools

Edittext
An edittext item is used to place an editable text field where the user can type and edit text. The
syntax is:
edittext <name> [ <caption> ] [ text:<string> ] \
[ fieldWidth:<integer> ] [bold:<boolean> ]

The default alignment of edittext items is #left.

Example:
edittext prefix_txt “Name prefix:” fieldWidth:70

on prefix_txt entered text do ...

...
new_obj = copy master pos:[x,y,z] prefix:prefix_txt.text
...

Parameters:
text:
The text string in the edit box.
fieldWidth:
The width in pixels of the edit box. By default, the width is set to be from just after the
caption text to the right margin of the rollout.
bold:
If set to true, the text string in the edit box is displayed in bold format, if set to false, in
normal, non-bold format. The default value is false.
Properties:
<edittext>.text String
The text in the edit box.
<edittext>.caption String
The text of the optional caption next to the edit box.
<edittext>.bold Boolean
If true, the text is displayed in bold format, if false, in normal, non-bold format.
Events:
on <edittext> changed <arg> do <expr>
Called each time the user changes the text in the edit box; the <arg> argument contains
the new text in the edit box.
on <edittext> entered <arg> do <expr>
Called when the user enters text in the edit box and then presses ENTER or TAB to move
the cursor out of the field. The <arg> argument contains the new text in the edit box.
If you enter a string in the edit box and then press ENTER, the on changed handler is called once
per character and once for the ENTER. The on entered handler is just called once, for the ENTER.
 Label 1497

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)

Label
A label item is used to place static text on the rollout, perhaps a label for another item or a text
message. The syntax is:
label <name> [ <string> ]

The default alignment of label items is #center.

Example:
label lab1 “Please choose an object:”

Properties:
No additional properties for label.
Events:
-- none --

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)

Listbox
A listbox item is used to place a list box in the rollout. This is another variant of the drop-down list
in which the list is always fully displayed in the rollout. Unlike combobox, it has no edit-text field
at the top and it is just a simple scrollable list. The user can scroll the list or click to select an item.
The syntax is:
listbox <name> [ <caption> ] [ items:<array_of_strings> ] \
[ selection:<number> ] [ height:<number> ]

The default alignment of listbox items is #left.

Example:
listbox selns items:obj_name_array

on selns selected i do
copy obj_array[i] pos:[rand_x, rand_y, rand_z]

selns.selection = 2
1498 Chapter 12 | Creating MAXScript Tools

Parameters:
items:
The array of text strings that are the items in the list.
selection:
The 1-based number of the currently selected item in the list. The default selection value
is 1.
height:
The overall height of the listbox in number of item lines. Defaults to 10 lines. To have a
listBox display exactly N items, set height to N.
Properties:
<listbox>.items String
The item string array.
<listbox>.selection Integer
The currently selected item number, 1-based. If the items list is an empty array, this value
is 0.
<listbox>.selected String
The text of the currently selected item. Can be used to replace individual items with
resetting the entire items array. If the items list is an empty array, this value is
undefined.
Events:
on <listbox> selected <arg> do <expr>
Called when the user selects an item in the list. The <arg> argument contains the new
current selection item number.
on <listbox> doubleClicked <arg> do <expr>
Called when the user double-clicks on an item in the list. Note that the on selected
handler is always called on single clicks and on the first click of a double-click. The <arg>
argument contains the number of the item double-clicked. For example,
listbox foo items:#(...)
on foo doubleClicked sel do ...

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)
 Mapbutton 1499

Mapbutton
A mapbutton item is used to place a button in the rollout that will display the 3ds max Material/
Map Browser dialog when clicked. Only texture maps will be displayed in the Material/Map Browser
dialog. The syntax is:
mapbutton <name> [ <caption> ] [ map:<texturemap> ] \
[ images:<image_spec_array> ] [ toolTip:<string> ]

The default alignment of mapbutton items is #center.

Example:
label sbm_lbl “Background Map:”
mapbutton choosemap “<<none>>“ tooltip:”Select Background Map”

on choosemap picked texmap do

( environmentmap = texmap
choosemap.text=classof texmap as string
)

Parameters:
map:
The initial textureMap value returned by the map property before the user has selected a
texture map using the mapbutton. Defaults to undefined.
images:
An image-specification array for providing bitmap images for the mapbutton. If this is
specified, the <label> is ignored and the contents of the mapbutton are replaced with
the bitmaps. The form is:
images:#(<image>, <maskImage>, <count_integer>, \
<enabled_out_image_index>, <enabled_in_image_index>, \
<disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a

MAXScript bitmap value. <count_integer> specifies the number of sub-images in
the bitmaps, and the image_index values specify which sub-image in the bitmaps is
to be used for each of the four mapbutton states. For example:
bm1 = render camera:$cam01 outputSize:[80,60]
...
mapbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the mapbutton image, and

mapbutton decay images:#(”dcybtns.bmp”, “dcymask.bmp”, 6, 1, 4, 1, 4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out
and in states of the mapbutton, respectively.
See also the Image Buttons (p. 1513) topic.
1500 Chapter 12 | Creating MAXScript Tools

toolTip:
Provides text for a tooltip for the mapbutton. No tooltip if unsupplied.
Properties:
<mapbutton>.map TextureMap
The current textureMap value for the mapbutton, or the textureMap value specified by the
map parameter if the user has not yet selected a texture map.
<mapbutton>.images Array
Sets the image-specification array for the mapbutton. For example:
-- re-render, update button
bm1 = render()
foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

This property is write-only.

Events:
on <mapbutton> picked <arg> do <expr>
Called when the user selects a texture map from the Material/Map Browser dialog while in
the mapbutton pick command mode. The <arg> argument contains the selected
textureMap value. The handler is not called if the user cancels out of the Material/Map
Browser dialog.
Notes:
When a mapButton or materialButton is used in a rollout in a scripted material or textureMap
plug-in, and so turn up the Material Editor, it behaves with the same functionality as sub-map and
sub-material buttons do in other materials and maps. This includes supporting drag-and-drop with
instance/copy, and opening sub-maps/materials if they have been assigned.

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)

Materialbutton
A materialbutton item is used to place a button in the rollout that will display the 3ds max Material/
Map Browser dialog when clicked. Only materials will be displayed in the Material/Map Browser
dialog. The syntax is:
materialbutton <name> [ <caption> ] [ material:<material> ] \
[ images:<image_spec_array> ] \
[ toolTip:<string> ]

The default alignment of materialbutton items is #center.

 Materialbutton 1501

Example:
label smtl_lbl “Set selected object’s material to:”
materialbutton choosemtl “Pick Material”

on choosemtl picked mtl do

( print mtl
if $ != undefined do $.material=mtl
)

Parameters:
material:
The initial material value returned by the material property before the user has selected a
material using the materialbutton. Defaults to undefined.
images:
An image-specification array for providing bitmap images for the materialbutton. If this
is specified, the <label> is ignored and the contents of the materialbutton are replaced
with the bitmaps. The form is:
images:#(<image>, <maskImage>, <count_integer>, \
<enabled_out_image_index>, <enabled_in_image_index>, \
<disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file name string or a
MAXScript bitmap value. <count_integer> specifies the number of sub-images in
the bitmaps, and the image_index values specify which sub-image in the bitmaps is
to be used for each of the four materialbutton states. For example:
bm1 = render camera:$cam01 outputSize:[80,60]
...
materialbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the materialbutton image, and

materialbutton decay images:#(”dcybtns.bmp”, “dcymask.bmp”, 6, 1, 4,
1,4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out
and in states of the materialbutton, respectively.
See also the Image Buttons (p. 1513) topic.
toolTip:
Provides text for a tooltip for the materialbutton. No tooltip if unsupplied.
1502 Chapter 12 | Creating MAXScript Tools

Properties:
<materialbutton>.material Material
The current material value for the materialbutton, or the material value specified by the
material parameter if the user has not yet selected a material.
<materialbutton>.images Array
Sets the image-specification array for the materialbutton. For example:
-- re-render, update button
bm1 = render()
foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

This property is write-only.

Events:
on <materialbutton> picked <arg> do <expr>
Called when the user selects a material from the Material/Map Browser dialog while in the
materialbutton pick command mode. The <arg> argument contains the selected
material value. The handler is not called if the user cancels out of the Material/Map
Browser dialog.
Notes:
When a mapButton or materialButton is used in a rollout in a scripted material or textureMap
plug-in, and so turn up the Material Editor, it behaves with the same functionality as sub-map and
sub-material buttons do in other materials and maps. This includes supporting drag-and-drop with
instance/copy, and opening sub-maps/materials if they have been assigned.

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)

MultiListBox
A MultiListBox item is used to place a list box in the rollout. This is a variant of the ListBox in which
multiple items in the list can be selected. The syntax is:
MultiListBox <name> [ <caption> ] [ items:<array_of_strings> ] \
[ selection:{<bitarray> | <number_array> | <number>} ] \
[ height:<number> ]

The default alignment of MultiListBox items is #left.

 MultiListBox 1503

Example:
rollout test “test”
(MultiListBox mlb “MultiListBox” items:#(”A”,”B”,”C”) selection:#(1,3)
on mlb selected val do format “selected: % - %\n” val mlb.selection[val]
on mlb doubleclicked val do format “doubleclicked: % - %\n” val
mlb.selection[val]
on mlb selectionEnd do format “selectionEnd: %\n” mlb.selection
)
rof=newrolloutfloater “tester” 200 300
addrollout test rof
test.mlb.items
test.mlb.selection=1
test.mlb.selection=#(1,3)
test.mlb.selection=#{}

Parameters:
items:
The array of text strings that are the items in the list.
selection:
A BitArray signifying the currently selected items in the list. The default selection value
is #{}.
height:
The overall height of the MultiListBox in number of item lines. Defaults to 10 lines. To
have a MultiListBox display exactly N items, set height to N.
Properties:
<listbox>.items Array of Strings
The item string array.
<listbox>.selection BitArray
The currently selected items. When setting the selection via a script, the selection can be
specified as a BitArray, Array of numbers, or a number. If the items list is an empty array,
this value is 0.
Events:
on <listbox> selected <arg> do <expr>
Called when the user selects or deselects an item in the list. The <arg> argument contains
the index of the item that was selected or deselected. Since multiple items can be selected
or deselected at once, this handler is called for each item in the list, starting from the top
of the list, whose selection has changed.
on <listbox> doubleClicked <arg> do <expr>
Called when the user double-clicks on an item in the list. Note that the on selected
handler is always called on single clicks and on the first click of a double-click. The <arg>
argument contains the number of the item double-clicked.
on <listbox> selectionEnd do <expr>
Called when the user selects or deselects an item in the list, but after all the calls to the on
selected handler have been made.
1504 Chapter 12 | Creating MAXScript Tools

Notes:
There isn’t a way to deselect all the items in the list by clicking in the list somewhere. To clear the
list selection you will need a “Clear Selection” button that sets selection=#{}.

Pickbutton
A pickbutton item is used to place a scene object-picker button on the rollout. It operates like a
normal pick button in the 3ds max user interface, turning light-green when pressed and causing an
object-pick mode to be entered. The user can then choose a scene object by clicking on it. The pick
mode exits and the button returns to its unpressed state. The user can right-click to cancel the pick
mode. The syntax is:
pickbutton <name> [ <caption> ] [ message:<string> ] \
[ filter:<function> ] [ toolTip:<string> ]

The default alignment of pickbutton items is #center.

Example:
fn foo_filt obj = findString obj.name “foo” == 1

pickbutton chooseit “Select master object” filter:foo_filt

on chooseit picked obj do

( master = obj
chooseit.text = obj.name
)

Parameters:
message:
The optional text to be displayed in the 3ds max status line while in the pick mode.
Default is no message.
filter:
The optional filter function that will be called to test the eligibility of the scene object
under the cursor for picking. It must be a function of one argument, which will be the
object under test, and return true if the object is eligible or false if not. For example, the
following filter function allows only objects whose names begin with “foo” to be pickable:
fn foo_filt obj = findString obj.name “foo” == 1

Default is no filtering.
toolTip:
Provides text for a tooltip for the button. No tooltip if unsupplied.
Properties:
<pickbutton>.object Node
The last object picked using the pickbutton, undefined if no object has been picked.
This property is read-only.
 ProgressBar 1505

Events:
on <pickbutton> picked <arg> do <expr>
Called when the user selects an object in the scene while in the pickbutton pick mode.
The <arg> argument contains the selected object. The handler is not called if the user
cancels out of the pick mode.

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)

ProgressBar
A progressBar item is used to place a progress bar on the rollout. The syntax is:
progressBar <name> [ value:<number> ] [ color:<color> ] \
[ orient:<name> ]

The default alignment of progressBar items is #left.

Example:
button doit “Process Scene”
progressbar doit_prog color:red

on doit pressed do
( for i = 1 to objArray.count do
( doit_prog.value = 100.*i/objArray.count
...
)
doit_prog.value = 0
)

Parameters:
value:
The initial progress percentage value (0 – 100). The default value is 0. This is an Integer
value.
color:
The color of the progress bar. The default color value is [30,10,190].
orient:
Specifies whether the progress bar should fill from left to right (orient:#horizontal) or
bottom to top (orient:#vertical). Default value is #horizontal.
1506 Chapter 12 | Creating MAXScript Tools

Properties:
<progressbar>.value Integer
The progress bar complete percentage (0 – 100).
<progressbar>.color Color
The color of the progress bar.
<progressbar>.orient Name
The orientation of the progress bar fill: #horizontal - left to right; #vertical - bottom
to top.
Events:
on <progressbar> clicked <arg> do <expr>
Called when user clicks on the progress bar. The <arg> argument contains the percentage
value at the clicked point.

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)

Radiobuttons
A radiobuttons item is used to place a set of radio buttons on the rollout, only one of which can be
checked at a time. The user can click different buttons in the set to change states. The syntax is:
radiobuttons <name> [ <caption> ] labels:<array_of_strings> \
[ default:<number> ] [ columns:<number> ]

The default alignment of radiobuttons items is #center.

Example:
radiobuttons copy_type labels:#(”copy”, “instance”, “reference”)

radiobuttons which_obj labels:obj_name_array -- computed label array

on copy_type changed state do ...

...
copyfn = case copy_type.state of
( 1: copy
2: instance
3: reference
)
...
 Slider 1507

Parameters:
labels:
An array of strings that specifies the number of radio buttons and the text label for
each one.
default:
The number of the radio button initially selected. Default is 1.
columns:
Number of columns across in which to arrange the buttons. By default, MAXScript will
attempt to lay out all the radio buttons side-by-side on one line, and if they won’t fit,
vertically in a single column. You can force the layout system to array the buttons in
multiple columns using this parameter. Each column is given the same width, which is the
width of the widest label in all columns and it left-adjusts the radio buttons in these
columns.
Properties:
<radiobuttons>.state Integer
The 1-based number of the currently selected radio button in the order specified in the
labels: array.
Events:
on <radiobuttons> changed <arg> do <expr>
Called when the user clicks one of the radio buttons in the set. The <arg> argument
contains the new state of the radio buttons array, which is the 1-based number of the
newly selected button.

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)

Slider
A slider item is used to place a slider on the rollout, as an alternative to a spinner. The user can drag
the slider’s pointer around to set its value. The syntax is:
slider <name> [ <caption> ] [ range:[min,max,val] ] \
[ type:#float ] [ ticks:10 ] \
[ orient:#horizontal ]

The default alignment of slider items is #center.

1508 Chapter 12 | Creating MAXScript Tools

Example:
slider tilt “Head tilt” orient:#vertical ticks:0 range:[-30,30,0]

on tilt changed val do $head.bend.angle = val

Parameters:
range:
A Point3 value containing the minimum, maximum and initial values for the slider in the
x, y, and z components, respectively. Defaults to [0,100,0].
type:
The type of the slider, #float or #integer. Defaults to #float.
orient:
The layout orientation of the slider in the rollout, either #vertical or #horizontal.
Defaults to #horizontal.
ticks:
Specifies how many ticks to place along the slider bar. No ticks are drawn if you specify
ticks:0. Defaults to 10.
Properties:
<slider>.range Point3
The current range and value for the slider, as a Point3 like the range: parameter.
<slider>.value Float
The current value of the slider.
<slider>.ticks Integer
The number of ticks along the slider.
Events:
on <slider> changed <arg> do <expr>
Called when the user moves the slider pointer. The <arg> argument contains the new
value of the slider.
on <slider> buttondown do <expr>
Called when the user first clicks the slider.
on <slider> buttonup do <expr>
Called when the user releases the slider.
The buttonDown and buttonUp events effectively notify you of the start and end of a slider
“twiddle”, allowing you to perform some setup for the adjustment. A typical use for this is to bring
scene nodes that are being modified in the on <slider> changed handler into the foreground
plane to speed up screen redraw. For example:
spinner foo “height: “

on foo buttonDown do flagForeground $baz...* true

on foo buttonUp do flagForeground $baz...* false
 Spinner 1509

Notes:
If you are using a slider to interactive adjust a property of an on-screen object, you can improve the
interactive speed by moving the object to the foreground plane. Objects placed in the foreground
plane are redrawn individually and so interactive changes to them are much faster. An object is
moved to the foreground or background plane using the flagForeground() method:
flagForeground <node> <boolean> -- mapped
The boolean argument puts the scene node(s) into the foreground plane if true, or into
the background plane if false.
You should be judicious in putting objects in the foreground plane, because putting too many
objects in the foreground plane reduces the foreground plane’s effectiveness. Remember to return
objects to the background plane when you don’t need to interactively control them any more.

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)

Spinner
A spinner item is used to place a 3ds max value spinner on the rollout. The user can drag the spinner
arrows or type values into the spinner edit field. The syntax is:
spinner <name> [ <caption> ] [ range:[min,max,val] ] \
[ type:<name> ] [ scale:<float> ] \
[ fieldWidth:<integer> ] [ controller:<controller> ]

The default alignment of spinner items is #right.

Example:
spinner frab_amt “Frab %:” range:[0,100,10] type:#integer
spinner ball_radius “Ball radius” controller:$ball.radius.controller

on frab_amt changed val do frabulate selection val

Parameters:
range:
A Point3 value containing the minimum, maximum, and initial values for the spinner in
the x, y, and z components, respectively. Defaults to [0,100,0].
type:
The type of the spinner: #float, #integer, or #worldunits. Defaults to #float. If
type is #worldunits, the value is displayed in the current 3ds max display units, but the
value is always in internal system units.
1510 Chapter 12 | Creating MAXScript Tools

scale:
The scale of the spinner specifies the smallest value increment. Defaults to 0.1 for floats, 1
for integers.
fieldwidth:
The width in pixels of the spinner text-edit field. By default, the spinner is placed so the
left edge of the edit field is exactly in the center of the rollout and right edge is placed at
the right margin. You can control how wide the field is using this parameter.
controller:
Links the spinner to the specified controller. This lets you establish a direct link between
the spinner and the controller. Changes to the spinner will automatically update the
controller (and its controlled objects). Changes to the controller automatically update the
spinner. For example, say you have a sphere called $ball with a float controller already
assigned to its radius, then the following code:
utility foo “foo”
(
spinner ball_radius “Ball radius” range:[0,1000,1] \
controller:$ball.radius.controller
)

sets up a spinner that automatically affects and tracks the radius of the scene node $ball.
Any changes to the spinner update $ball’s radius. Any other changes to $ball’s radius, say
in the Modify panel or because of animation, will update the spinner. Note that this links
to controllers, so the specified controller must already exist before creating the spinner
user-interface item. You can either specify a controller already assigned to the parameter
you want to link to, or you can create the controller in your script and then assign that
controller to the parameter of interest. For example:
utility foo “foo”
(
local myController=bezier_float()
spinner ball_radius “Ball radius” range:[0,1000,1] \
controller:myController
button apply “Apply Radius Controller”
on apply pressed do
( animate off at time 0 $ball.radius=myController.value
$ball.radius.controller=myController
)
)

Properties:
<spinner>.range Point3
The current range and value for the spinner, as a Point3 like the range: parameter.
<spinner>.value Float
The current value of the spinner.
 Spinner 1511

Events:
on <spinner> changed <arg> do <expr>
Called when the user spins the spinner, or when the user enters a value in the spinner field
then presses ENTER or presses TAB to move the cursor out of the field. The <arg>
argument contains the new value of the spinner.
on <spinner> entered do <expr>
Called when the user types a number into a spinners edit field and then presses ENTER or
presses TAB to move the cursor out of the field. The on <spinner> changed handler, if
supplied, has already been called at this point and the spinner’s value property is up to
date.
on <spinner> buttondown do <expr>
Called when the user first clicks the spinner.
on <spinner> buttonup do <expr>
Called when the user releases the spinner.
The buttonDown and buttonUp events effectively notify you of the start and end of a spinner
“twiddle”, allowing you to perform some setup for the adjustment. A typical use for this is to bring
scene nodes that are being modified in the on <spinner> changed handler into the foreground
plane to speed up screen redraw. For example:
spinner foo “height: “

on foo buttonDown do flagForeground $baz...* true

on foo buttonUp do flagForeground $baz...* false

Notes:
If you are using a spinner to interactive adjust a property of an on-screen object, you can improve
the interactive speed by moving the object to the foreground plane. Objects placed in the
foreground plane are redrawn individually and so interactive changes to them are much faster. An
object is moved to the foreground or background plane using the flagForeground() method:
flagForeground <node> <boolean> -- mapped
The boolean argument puts the scene node(s) into the foreground plane if true, or into
the background plane if false.
You should be judicious in putting objects in the foreground plane, because putting too many
objects in the foreground plane reduces the foreground plane’s effectiveness. Remember to return
objects to the background plane when you don’t need to interactively control them any more.

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)
1512 Chapter 12 | Creating MAXScript Tools

Timer
A timer item generates tick events at set intervals. Timer is unlike the remainder of the user-interface
items as it is not a visible control. Timer lets the user interface react, animate, or change without user
interaction, such as having animations playing on the rollout, checking for certain conditions or
events before continuing, displaying nag/splash screens, and so on. The syntax is:
timer <name> [ interval:<number> ] [ active:<boolean> ]

Example:
utility test “test1”
(
timer clock “testClock” interval:400
label test “1”

on clock tick do
( valUp = (test.text as integer)+1
test.text = valUp as string
)
)

Parameters:
interval:
An integer value specifying the time in milliseconds between tick events. Default value
1000 (1 second).
active:
Specifies whether the timer emits tick events. Default value true.
Properties:
<timer>.interval Integer
Integer value specifying the time in milliseconds between tick events.
<timer>.active Boolean
Specifies whether the timer emits tick events (true) or not (false). When first set to
true, the first tick event is generated in interval milliseconds.
Events:
on <timer> tick do <expr>
Called when timer ticks.

See also
Rollout User-Interface Items Common Properties (p. 1481)
Rollout User-Interface Items Common Layout Parameters (p. 1483)
Rollout User-Interface Control Types (p. 1484)
 Timer 1513

Image Buttons
Four rollout user-interface item types, button, checkbutton, mapbutton, and materialbutton,
can be either simple text buttons containing text labels or image buttons inside of which bitmaps
can be displayed instead of text. The images to be displayed in these buttons are specified using the
definition-line parameter images:. The parameter form is:
images:#(<image>, <maskImage>, <count_integer>, \
<enabled_out_image_index>, <enabled_in_image_index>, \
<disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a MAXScript
bitmap value. <count_integer> specifies the number of sub-images in the bitmaps, and the
image_index values specify which sub-image in the bitmaps is to be used for each of the four
button states. For example:
bm1 = render camera:$cam01 outputSize:[80,60]
...
checkbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the button image.

If the image or maskImage is specified as a file name, the bitmap file is searched for in the following
directories (in order of search): current MAXScript directory, MAXScript startup directory,
MAXScript directory, 3ds max bitmap directories, and then the 3ds max image directory.
There are four images that can be specified, one for each of the possible button states, enabled-out,
enabled-in, disabled-out, and disabled-in. These images are taken from a single bitmap file or
MAXScript bitmap value in which a number of images are stored side-by-side. This bitmap,
containing one or more images to use for the button, is called the imagelist. All the sub-images in
such an imagelist are taken to be the same width and you specify which image is used for which state
by providing an image-index into the bitmap. This means you can store the images for all the states
of many buttons in one file, specifying different indexes for the different buttons.
You can also specify a black-and-white mask image used to mask the image display into the buttons.
It is given in the same imagelist form and the mask image indexes must be the same as the images
they correspond to. Black pixels in the mask let the corresponding image pixel show; white pixels
hide corresponding image pixels and show the default background color for the button. If there is
no mask file, supply the value undefined for the mask file name.
Bitmap files without full path names are searched for in the Startup scripts directory, then the scripts
directory, then the 3ds max images directory, then the 3ds max executables directory, and then the
directories in the PATHS environment variable.
You can change the images in a button by setting the .images property of these user-interface items.
For example:
-- re-render, update button
bm1 = render camera:$cam01 outputSize:[80,60]
foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)
1514 Chapter 12 | Creating MAXScript Tools

Example:
checkbutton decay images:#(”dcybtns.bmp”, “dcymask.bmp”, 6, 1, 4, 1, 4)

In this example, the images are in a file dcybtns.bmp and the masks in dcymask.bmp. These bitmap
files each have six images across and the out-state is image 1 and the in-state is image 4. Both enabled
and disabled here are given as the same image, presumably because this particular button will never
be disabled.

Scripted Right-Click Menus

MAXScript provides a set of classes and functions and some special syntax to allow you to construct
custom right-click menus that can be incorporated into the existing 3ds max user interface. You
typically use right-click menus to provide quick access to a selection of tools you have written in
MAXScript. These tools would typically have no user interface, however you can create dialogs or
rollout floater windows in a right-click menu to display a user interface.
A scripted right-click menu is created using the RCMenu definition construct in MAXScript, and then
you register the right-click menu with 3ds max. The top-level definition syntax is as follows:
rcmenu <var_name> ( <rcmenu_body> )

where:
<var_name> is the name of an automatically created global variable to hold the rcmenu value
that represents the right-click menu.
<rcmenu_body> is enclosed in the required parentheses and is a sequence of clauses that define
the menu items that will appear in the utility, along with functions and event handlers that
process user interactions. These clauses are defined in detail in the RCMenu Clauses (p. 1515)
topic.
The following methods let you register and unregister scripted right-click menus:
registerRightClickMenu <rcmenu>
registers the specified right-click menu
unRegisterRightClickMenu <rcmenu>
unregisters the specified right-click menu
unRegisterAllRightClickMenus()
unregisters all right-click menus
Example:
The following script adds two items to the right-click menu: Cast Shadows and Receive Shadows.
These items will be enabled only if one object is selected. If enabled, the items will be checked or
unchecked based on the current state of the selected object. Choosing a menu item will flip the state
of the corresponding object property.
 RCMenu Clauses 1515

Script:
rcmenu MyRCmenu
(
menuItem mi_cs “Cast Shadows” checked:false
menuItem mi_rs “Receive Shadows” checked:false
--
on MyRCmenu open do
( local sel = (selection.count == 1)
--
-- Enable if only one object is selected
mi_cs.enabled = mi_rs.enabled = sel
--
-- Set check state of items
if sel do
( mi_cs.checked = $.castShadows
mi_rs.checked = $.receiveShadows
)
)
--
-- set up event handlers for items
on mi_cs picked do $.castShadows = (not $.castShadows)
on mi_rs picked do $.receiveShadows = (not $.receiveShadows)
)
-- register the rcmenu
registerRightClickMenu MyRCmenu

You can register as many scripted right-click menus as you like. Each scripted right-click menu
registered is appended to the right-click menu window. If a scripted right-click menu with the same
name is registered twice, the old one is over written by the new one.
If a runtime error occurs while executing a scripted right-click menu, an error message is displayed
in Listener. The right-click menu will not be disabled.

RCMenu Clauses
The <rcmenu_body> of a right-click menu definition is made up of a sequence of scripted right-click
menu clauses as follows:
<rcmenu_body> ::= { <rcmenu_clause> }+

Scripted right-click menu clauses define the components of a scripted right-click menu and can be
one of three basic things:
• Local variables, functions or structure definitions are variables, functions, and structures whose
scope is the scripted right-click menu. These locals will exist as long as the scripted right-click
menu value exists. The scripted right-click menu value will exist until the scripted right-click
menu value is redefined or deleted. Local variables are particularly useful for storing working
data associated with the right-click menu such as picked objects.
• User-interface items are displayed in the right-click menu, such as menu items, separators, and
submenus.
1516 Chapter 12 | Creating MAXScript Tools

• Event handlers are special kinds of functions that are associated with particular user-interface
items. Event handlers specify the processing you want to occur when a user interacts with an
user-interface item, for example pressing a menu item or opening a submenu. These user actions
generate named events and the optional event handler you supply for that event is called when
the user action occurs.
The visibility of locals, and accessing scripted right-click menu locals from external code, are the
same as described for utility rollouts, and described in the Visibility of Locals, Functions, Structures,
and User-Interface Items in Rollout Code (p. 1478) and Accessing Locals and Other Items in a Rollout from
External Code (p. 1480) topics. In both utility rollouts and scripted right-click menus, the name given
to a user-interface item is used to name an automatically constructed local variable that will hold
the value representing the item. It is also used to associate event handler functions with the item.
One difference between the scoping of these variables is that they are local to the rollout in utility
rollouts, and local to the scripted right-click menu in scripted right-click menus. This means that all
user-interface items in a scripted right-click menu must have a unique name within the scripted
right-click menu, even for those items present in a subMenu.
Formally, the syntax of a <rcmenu_clause> is defined as follows:
<rcmenu_clause> ::= <local_variable_decl> |
<local_function_decl> |
<local_struct_decl> |
<user_interface_item> |
<event_handler>

Locals:
A <local_variable_decl>, <local_function_decl>, and <local_struct_decl> are exactly
the same as local variable, function, and structure definitions in MAXScript:
<local_variable_decl> ::= local <decl> { , <decl> }
<decl> ::= <name> [ = <expr> ] -- optional initial value

<local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr>

<local_struct_decl> ::= struct <name> ( <member> { , <member> } )

<member> ::= ( <name> [ = <expr> ] | <local_function_decl> )

Examples of the above (in order) are:

local numSelected
local numSelected = 0
fn onlyOneSelected = selection.count == 1
struct parents (mother=”“, father=”“)

Global variables cannot be declared as a scripted right-click menu clause, however they can be
declared within event-handler scripts. If you need to ensure that a variable name references a global
variable, declare the variable name as global immediately before defining the right-click menu in
your script.
 RCMenu Clauses 1517

When writing scripts, it is good programming practice to explicitly declare your local and global
variables. Implicit declaration is provided as a short-hand, typically used when working in the
Listener interactively or developing short scripts. When developing extended scripts, explicitly
declaring variables can reduce errors and improve readability of the code. It is also recommend that
you declare as local all variables unless you really want them to be global variables. The reasons for
this are described in the Scope of Variables (p. 646) topic.
User-Interface Items:
A <user_interface_item> defines an individual menu item, separator, or submenu user-interface
item that will appear in the right-click menu. These user-interface items are described in the RCMenu
User-Interface Items (p. 1518) topic.
Event Handlers:
An <event_handler> is a special function definition local to a scripted right-click menu that you
provide to handle the processing you want to occur when a user clicks on a menu item. This user
action generates a named event and any event handler you supply for that event is called when the
action occurs. The syntax for defining a handler is as follows:
on <item_name> <event_name> do <expr>

The <item_name> specifies the name of the item for which this handler is connected. The
<event_name> specifies the type of event to be handled. There is only one type of user-interface
item event:
picked

The picked handler expression is executed when a menu item is picked from the right-click menu.
Any MAXScript action like creating a object, adding a modifier, and so on can be performed in this
expression.
In addition to the event handlers you specify for particular menu items in a right-click menu, you
can define a handler function that is called when the entire right-click menu is first opened by the
user. This event handler is useful for initialization code. The syntax for this event handler is as
follows:
on <rcmenu> open do <expr>

See also
Scripted Right-Click Menus (p. 1514)
1518 Chapter 12 | Creating MAXScript Tools

RCMenu User-Interface Items

There are three types of user-interface items you can use to construct your scripted right-click menu.
The user-interface control types are:
menuItem (p. 1518)
separator (p. 1519)
subMenu (p. 1520)

menuItem
A menuItem is used to place a pickable item in the right-click menu. The syntax for a menuItem is:
menuItem <name> <label> [ checked:<boolean> ] [ enabled:<boolean> ] [
filter:<function> ]

Parameters:
name:
Used to refer to when writing an event handler.
label:
The string that appears in the right-click menu.
checked:
Specifies if a check mark appears before the label in the right-click menu. If true the item
is checked, otherwise the item is unchecked.
enabled:
Specifies if the item is enabled for interaction when the right-click menu is opened. If
true the item is enabled, otherwise the item is disabled and appears unavailable.
filter:
A function that returns a Boolean value. The filter function is evaluated when the
right-click menu is first opened. If the filter function returns true the menuItem appears
in the menu, otherwise it is not displayed.
Properties:
<menuitem>.text String
The string that appears in the right-click menu.
<menuitem>.checked Boolean
Specifies if a check-mark appears before the label in the right-click menu. If true the item
is checked, otherwise the item is unchecked.
<menuitem>.enabled Boolean
Specifies if the item is enabled for interaction when the right-click menu is opened. If
true the item is enabled, otherwise the item is disabled and appears as unavailable.
Events:
on <menuitem> picked do <expr>
Called when the user clicks the menu item.
 separator 1519

Example:
Script:
rcmenu RCmenuRenderable
( fn onlyOneSelected = selection.count == 1 -- define filter function
menuItem mi_r “Renderable” filter: onlyOneSelected -- display if only 1 object
selected
on RCmenuRenderable open do -- perform following on rcmenu open
( if selection.count == 1 then -- if only one object selected...
( mi_r.text = $.name + “ | “ + “Renderable” -- change text of menu item
if isKindOf $ Shape then -- if shape set renderable property to
$.renderable=$.renderable -- itself to get shape and node renderable
-- properties the same
mi_r.checked=$.renderable -- turn on menu item check if renderable
)
)
on mi_r picked do $.renderable = not $.renderable -- when menu item picked,
flip renderable value
)
--
registerRightClickMenu RcmenuRenderable -- register the rcmenu

See also
RCMenu Clauses (p. 1515)
Scripted Right-Click Menus (p. 1514)

separator
A separator is used to place a separator line in the right-click menu, and is normally used to group
menu items. The syntax for a separator is:
separator <name> [ filter:<function> ]

Parameters:
name:
Used to name an automatically constructed local variable that will hold the value
representing the separator.
filter:
A function that returns a Boolean value. The filter function is evaluated when the right-
click menu is first opened. If the filter function returns true the separator appears in the
menu, otherwise it is not displayed.
Example:
Script:
rcmenu MyRCmenu
(
fn flt_objects = ($ != undefined) -- objects filter
--
menuItem mi_cs “Cast Shadows” checked:false
1520 Chapter 12 | Creating MAXScript Tools

menuItem mi_rs “Receive Shadows” checked:false

--
-- add only if one or more objects are selected
separator sep1 filter:flt_objects
menuItem mi_st “Scale Twice” filter:flt_objects
menuItem mi_sh “Scale Half” filter:flt_objects
--
-- event handlers would go here...
)
registerRightClickMenu MyRcmenu -- register the rcmenu

See also
RCMenu Clauses (p. 1515)
Scripted Right-Click Menus (p. 1514)

subMenu
A subMenu is used to place an item in the right-click menu that, if the cursor is placed on, opens a
submenu containing additional user-interface items. The syntax for a subMenu is:
subMenu <label> [ filter:<function> ] ( <submenu_body> )

The <submenu_body> of a subMenu definition is made up of a sequence of RCMenu clauses

as follows:
<submenu_body> ::= { <rcmenu_clause> }+

Parameters:
label:
The string that appears in the right-click menu.
filter:
A function that returns a Boolean value. The filter function is evaluated when the
right-click menu is first opened. If the filter function returns true the subMenu appears in
the menu, otherwise it is not displayed.
Example:
Script:
rcmenu MyRCmenu
(
fn flt_objects = ($ != undefined) -- objects filter
fn flt_shapes = (isKindOf $ Shape) -- shapes filter
--
menuItem mi_cs “Cast Shadows” checked:false
menuItem mi_rs “Receive Shadows” checked:false
--
separator sep2 filter:flt_objects
--
subMenu “Modifiers” filter:flt_objects -- begin subMenu
( -- Add common objects
 subMenu 1521

menuItem mi_bend “Bend”

menuItem mi_twist “Twist”
--
-- Add shape only modifiers
separator sep3 filter:flt_shapes
subMenu “Shape” filter:flt_shapes -- begin nested subMenu
( menuItem mi_extrude “Extrude”
menuItem mi_EditSpline “Edit Spline”
)
)
-- event handlers would go here...
)
registerRightClickMenu MyRcmenu -- register the rcmenu

See also
RCMenu Clauses (p. 1515)
Scripted Right-Click Menus (p. 1514)

Defining Macro Scripts

Macro Scripts are scripts that are associated with toolbar buttons and are executed when the
corresponding toolbar button is clicked. Macro Scripts have to be defined with the macroScript
definition construct and can then be associated with a toolbar button by right-clicking a Shortcut
toolbar or Tab and choosing Customize. The Customize User-Interface dialog is displayed, which has
a radio button above the list box that lets you choose from either Command shortcuts or Macro
Scripts. Macro Scripts are essentially pieces of MAXScript code that have a name and category, and
optionally a tooltip and icon.
Macro Scripts do not automatically create user-interface items. If you want a Macro Script to display
a dialog, you will need to create a rollout floater window and rollout(s) as described in the Rollout
Floater Windows (p. 1477) topic, and create and install the user-interface items in the rollout(s) as
described in the Rollout User-Interface Controls (p. 1481) topic.
Define a Macro Script using the following syntax:
macroScript <name> [ category:<string> ]
[ buttonText:<string> ]
[ toolTip:<string> ]
[ icon:#(<string>, <index>) | icon:<string> ]
[ silentErrors:<boolean> ]
( <macro_script_body> )
1522 Chapter 12 | Creating MAXScript Tools

For example:
macroScript Free_Camera category:”Cameras” tooltip:”Free Camera”
Icon:#(”Cameras”,2)
(
StartObjectCreation FreeCamera
)
macroScript Target_Camera category:”Cameras”
tooltip:”Targeted Camera” Icon:#(”Cameras”,1)
(
StartObjectCreation TargetCamera
)

After MAXScript evaluates a macroScript construct, the Macro Script definition will show up in
the Macro Scripts list in the Customize User-Interface dialog. The following figure shows a
Customize User Interface dialog containing the previous two Macro Scripts.
 subMenu 1523

<name> is the name shown in the Customize User-Interface dialog. Unlike other similar constructs
(Scripted Utilities, Functions, and right-click menus), macroScript does not create a variable with
this name. Rather, Macro Scripts are stored as pointers into files, as described below.
The category: argument specifies in which category in the Customize User-Interface dialog the
Macro Script name will be listed. The use of categories is intended to help you organize your Macro
Scripts into groupings so that the Macro Script names are less likely to clash. If you do not specify a
category, a default category of “unknown” is used.
The toolTip: argument specifies the tooltip for the button. If no tooltip is specified, no tooltip is
displayed for the button.
The buttonText: argument specifies the text that will appear in the button, and the icon:
argument specifies the icon that will appear in the button. You can choose in the Customize User
Interface dialog whether the buttonText or icon appears in the button. If no buttonText:
argument is specified, the Macro Script name is used as the buttonText.
The icon: argument specifies the icon bitmap file and the icon image within the icon bitmap file.
The icon bitmap file must be located in the current 3ds max user-interface directory. Icon bitmap
files have a base name, such as “MyToolbar”, followed by a suffix, such as “_24i.bmp”, that specifies
the individual icon size and icon bitmap file type. The icon: argument string is just the base name,
with no extensions present. This base name is the name shown in the Image Group list in the
Customize User-Interface dialog. Each icon bitmap file can have any number of individual icons,
lined up side-by-side in the file. If the icon bitmap file contains multiple icons, <index> specifies
which icon in the icon bitmap file to use. The left-most icon has an <index> of 1. The 3ds max
internal icons (Image Group Internal in the Customize User-Interface dialog) are not stored in an
icon file, and are referenced by using an empty string as the icon: argument.
So, the icon: argument can be either a two-element array containing the icon bitmap file’s base
name as a string and the icon’s index in that file, or just a base name string, with the index 1
assumed. For example:
macroScript Box category:”Objects” tooltip:”Box”
icon:#(”standard”, 1) -- use first icon in standard
(
StartObjectCreation Box
)
macroScript Sphere category:”Objects” tooltip:”Sphere”
icon:#(”“, 2) -- use second icon in internal icons
(
StartObjectCreation Sphere
)
macroScript Cone category:”Objects” tooltip:”Cone”
icon:”myicon” -- use first icon in myicon
(
StartObjectCreation Cone
)

See the Creating Icon Bitmap Files (p. 1530) topic for more information.
1524 Chapter 12 | Creating MAXScript Tools

The silentErrors: parameter gives control over whether MAXScript runtime error messages are
displayed while executing the Macro Script. If this parameter is set to true, error messages will not
be displayed. This may be useful for distributed Macro Scripts that may confuse the user with
MAXScript error messages. The default value is false.
The <macro_script_body> is any valid MAXScript expression, and can contain global and local
variables, functions, and structure definitions. The <macro_script_body> is compiled in its own
local scope, and the locals are only visible inside the scope of the Macro Script. Macro Script locals
are heap-based locals, which are slightly different from normal (stack-based) locals.
Normal locals are visible in the current scope and have a lifetime of one execution of that scope.
Heap-based locals are also visible only in the current scope, but have a lifetime equal to the lifetime
of the top-level expression where they are defined. A Macro Script’s locals are created the first time
you execute the Macro Script, initialized to a value of undefined, or to their specified initialization
value. These values are stored in a separate memory stack. On entry to each function (or top level
script) in the Macro Script, a ‘frame’ in the memory stack is marked and when the function (or top
level script) exits, all of the values in the frame are freed from the memory.
Because a Macro Script’s name is not created as a variable, you cannot access a Macro Script’s locals
outside the scope of the Macro Script. So, for example, you can create a rollout in a Macro Script,
and the rollout’s event handlers can access the locals defined in the Macro Script because the rollout
is executing within the scope of the Macro Script. However, you cannot access the Macro Script’s
locals from another utility or from the Listener, because they are not executing within the scope of
the Macro Script. See the Scope of Variables (p. 646) topic for more information.
When you execute a macroScript definition, the return value is an integer Macro Script ID value.
MAXScript internally stores information about each Macro Script in an array, and the returned
Macro Script ID value is the array index for that Macro Script. The information stored for each Macro
Script consists of the file in which that Macro Script is defined and a pointer into that file specifying
where the Macro Script definition begins. The Macro Script definition is only compiled when you
first press a toolbar button that contains the script, or execute the Macro Script using the
macros.run() method.
There are five ways a Macro Script can be defined:
• The default user-interface directory and its subdirectories will be automatically scanned at
startup for files of type .mcr, which will be parsed for Macro Script definitions.
• A Macro Script definition is executed in an Editor window, in a script file that you execute, or
in a startup script file.
• If you evaluate a Macro Script definition in the Listener window, a file will automatically be
created to contain the Macro Script definition. This file is stored in the MacroScripts directory
under the current user-interface directory.
• MAXScript supports text drag onto toolbars to create Macro Script buttons. You can select and
drag text from any text window, such as Listener window panes or Editor windows, onto any
visible toolbar. The cursor changes to an arrow with + sign when it is OK to drop the text. If you
drop it, a Macro Script button is added to the toolbar with the dropped text as the body of the
Macro Script. The classic case here would be to drag some text from the Macro Recorder pane in
 subMenu 1525

the Listener window onto a toolbar to make a button that does the sequence of events just
recorded. Remember that tabbed elements on the Shelf are toolbars and can accept dropped
text. MAXScript will automatically enclose the text in a Macro Script definition with a Macro
Script name of DragAndDrop-MacroN, where N is a number that will make the Macro Script
name unique. The category will be DragAndDrop and no tooltip is specified. As with Macro
Scripts defined in the Listener window, a file will automatically be created to contain the Macro
Script definition. This file is stored in the MacroScripts directory under the current user-interface
directory.
• A Macro Script can be defined using the macros.new() method described next. As with Macro
Scripts defined in the Listener window, a file will automatically be created to contain the Macro
Script definition. This file is stored in the MacroScripts directory under the current user-interface
directory.
If you move or delete a file that contains a Macro Script definition that has been loaded, and try to
execute the Macro Script, you will get an error message. Further, if you edit a file containing Macro
Script definitions, take care to save and re-evaluate the entire file so any other Macro Scripts defined
in that file will have their file pointer updated. If you don’t do this, you may get an error message
saying the currently loaded definition no longer matches its file.
If you reevaluate a Macro Script definition, any button using that Macro Script will see any changes
you make.
Any macroScript definition evaluated in MAXScript or created by dropping text onto a toolbar has
a separate definition .mcr file created in the MacroScripts directory under the current user-interface
directory (typically UI\MacroScripts). The name of the file is <category_name>-<macro_name>.mcr,
for example,
DragAndDrop-Macro12.mcr for macroScript Macro12 category:”DragAndDrop”
NURBS-Map_Updater.mcr for macroScript Map_Updater category:”NURBS”
If you evaluate a macroScript definition in the Listener or drop text on a toolbar, its recorded
definition file is this backing file in UI\MacroScripts. This definition file is the one that gets opened
if you hit Edit Macro Script in the CUI customize menus or dialogs. For macroScript definitions
evaluated in Listener, this means the same definition will be updated each time you evaluate it,
rather than having separate backing file for each evaluation.
If you evaluate macroScript definitions in a .ms or .mcr file that does not already reside in the
UI\MacroScripts directory, a copy for each will be placed in a separate file in UI\MacroScripts, but
the recorded definition file will be the original source file, so that hitting Edit Macro Script will go
to that file.
This means that if any buttons containing such macroScript definitions are added to toolbars in the
startup.cui file, the backing .mcr file in UI\MacroScripts will be used as its definition at the next
3ds max startup. When you start 3ds max, the macroScript definitions will taken from the backing
files in UI\MacroScripts. If these Macro Scripts are also defined in MAXScript startup script files, they
will be re-defined at MAXScript startup and so the definition file of record will be updated to point
to the script file.
1526 Chapter 12 | Creating MAXScript Tools

MAXScript provides several methods that allow you to access and run Macro Scripts from within a
script. These Macro Script functions are in a structure package named macros. The Macro Script
methods are:
macros.load [ <path_name_string> ]
Loads all of the Macro Script definition (.mcr) files in the current user-interface directory
path, or in directory path specified by <path_name_string>. This method does not
change the current user-interface directory path. You can get the current user-interface
directory path with the function:
local ui_dir = cui.getDir ()

macros.new <name_string> <category_string> <toolTip_string> \

<buttonText_string> <body_string>
Creates a new Macro Script with the specified name and category. A file will automatically
be created to contain the definition. This file is stored in the current user-interface
directory. Returns an integer Macro Script ID value that uniquely identifies the new Macro
Script.
macros.run <category_string> <name_string>
macros.run <macro_id_integer>
Executes the specified Macro Script. The Macro Script is identified by either its category
and name, or by its unique Macro Script ID value.
macros.edit <category_string> <name_string>
macros.edit <macro_id_integer>
These methods will open the Macro Script definition (.mcr) file that defines the specified
Macro Script in a script Editor window. The Macro Script is identified by either its category
and name, or by its unique Macro Script ID value.
For example:
macros.load “f:/gametools/macros”
macros.edit “objects” “box”
macros.run 132
macros.run “modifiers” “bend”

Examples:
The following Macro Script will save the active viewport’s image to a bitmap file.
Script:
MacroScript GrabViewport category:”Tools” tooltip:”Grab Viewport”
(
---------------------------------------------------------------------
--GRABVIEWPORT MACROSCRIPT
--Created:3/23/99
--Edited:4/28/99
--by Borislav Petrov
--bobo@email.archlab.tuwien.ac.at
---------------------------------------------------------------------
--Snapshot Active Viewport to Bitmap
--Filename in format:
--VPGRAB_MaxFileName_ViewportName_CurentFrame.ImageFormatExtension
 subMenu 1527

---------------------------------------------------------------------
--
--Init Variables
local grab_bmp --bitmap to put the snapshot into
local bmp_name --name of the bitmap to save
local get_viewport_name --viewport name
local gac,gct,mfn --variables to hold ActiveCamera, CurrentTime, MaxFileName
--
--Start Macro
grab_bmp = gw.getViewportDib() --get the viewport bitmap into variable
get_viewport_name = viewport.GetType() --get viewport name
gvn = get_viewport_name as string --convert viewport name to string
gvn = substring gvn 6 (gvn.count-5) --cut the string
if gvn == “camera” then --if the remaining string is “camera”
( gac = getActiveCamera() --get the camera
gvn = gac.name --get the name of the camera
)
mfn = MaxFileName --get max file name
if mfn == ““ then --if there is no name
mfn = “Untitled” --use “Untitled”
else
mfn = getFileNameFile mfn --use the file name without .MAX extension
gct = SliderTime as string --get current frame time
--
bmp_name = “VPGRAB_”+ mfn +”_” +gvn + “_” + gct --build the output file name
--
--Display file save dialog
bmp_name = getSaveFileName caption:”Save Viewport to:” filename:bmp_name \
types:”BMP(*.bmp)|*.bmp|TIFF(*.tif)|*.tif|JPG(*.jpg)|*.jpg|TGA(*.tga)|*.tga|”
--
if bmp_name != undefined then --if user has confirmed / entered a valid name
( grab_bmp.filename = bmp_name --set output name to the one entered in the save
file dialog
save grab_bmp --save the bitmap
display grab_bmp --display the bitmap in a VFB
)
)--end of script

The following Macro Script allows you to render directly to the RAMPlayer. This Macro Script shows
the use of rollouts and rollout floater windows in Macro Scripts.
Script:
-- MacroScript to Render to RamPlayer
-- Author: Alexander Bicalho
--****************************************************************
-- MODIFY THIS AT YOUR OWN RISK
-- This utility will allow you to render directly to the RamPlayer
--
MacroScript RAM_Render category:”Tools” tooltip:”Render to Ram”
(
-- declare local variables and define some functions
local get_names existFile
1528 Chapter 12 | Creating MAXScript Tools

function get_names name a = append a name

function existFile fname = (getfiles fname).count != 0
--
-- create the rollout definition
rollout r_size “Render Parameters”
( local p = 95
local p2 = p+78
group “Time Output”
( radiobuttons r_time columns:1 align:#left \
labels:#(”Single”,”Active Time Segment”,”Range:”)
spinner nth “Every Nth Frame:” pos:[215,24] fieldwidth:50 \
type:#integer range:[0,10000,1] enabled:false
spinner r_from fieldwidth:60 pos:[75,56] type:#integer \
range:[0,10000,1] enabled:false
spinner r_to “To:” fieldwidth:60 pos:[152,56] type:#integer \
range:[0,10000,100] enabled:false
)
group “Render Size”
( spinner rw “Width “ fieldwidth:60 pos:[15,p+08] \
type:#integer range:[0,10000,320]
spinner rh “Height “ fieldwidth:60 pos:[12,p+32] \
type:#integer range:[0,10000,240]
spinner aspect “Aspect “ fieldwidth:60 pos:[10,p+56] \
type:#float range:[0,20,1.0]
button s160 “160x120” pos:[125,p+06] width:75 height:19
button s256 “256x243” pos:[125,p+30] width:75 height:19
button s320 “320x240” pos:[205,p+06] width:75 height:19
button s512 “512x486” pos:[205,p+30] width:75 height:19
button s640 “640x480” pos:[285,p+06] width:75 height:19
button s720 “720x486” pos:[285,p+30] width:75 height:19
button conf_render “Configure” pos:[125,p+54] width:115 height:19
button wipe “Purge Files” pos:[245,p+54] width:115 height:19
button go “Render” pos:[125,p+78] width:235 height:19
)
label abt0 “Render to RAM” pos:[8,p2+31]
label abt1 “Version 0.2a” pos:[8,p2+46]
label abt2 “Alexander Esppeschit Bicalho” pos:[225,p2+31]
label abt3 “abicalho@brasilmail.com” pos:[249,p2+46]
--
-- define the rollout event handlers
on wipe pressed do
( local tempfilename_a = (getdir #image) + “\\ramplayertemp_a.avi”
local tempfilename_b = (getdir #image) + “\\ramplayertemp_b.avi”
if existfile tempfilename_a then deletefile tempfilename_a
if existfile tempfilename_b then deletefile tempfilename_b
)
--
on r_time changed state do
( case state of
( 1: nth.enabled = r_from.enabled = r_to.enabled = false
2: ( nth.enabled = true
 subMenu 1529

r_from.enabled = r_to.enabled = false

)
3: nth.enabled = r_from.enabled = r_to.enabled = true
)
)
--
on s160 pressed do (rw.value=160; rh.value=120; aspect.value=1.0)
on s320 pressed do (rw.value=320; rh.value=240; aspect.value=1.0)
on s256 pressed do (rw.value=256; rh.value=243; aspect.value=1.266)
on s512 pressed do (rw.value=512; rh.value=486; aspect.value=1.266)
on s640 pressed do (rw.value=640; rh.value=480; aspect.value=1.0)
on s720 pressed do (rw.value=720; rh.value=486; aspect.value=0.9)
--
on conf_render pressed do (max render scene)
--
on go pressed do
( local tempfilename_a = (getdir #image) + “\\ramplayertemp_a.avi”
local tempfilename_b = (getdir #image) + “\\ramplayertemp_b.avi”
if existfile tempfilename_b then
( deletefile tempfilename_a
copyfile tempfilename_b tempfilename_a
tempfilename = tempfilename_b
)
else
( if existfile tempfilename_a then
tempfilename = tempfilename_b
else
( tempfilename = tempfilename_a
tempfilename_b = ““
)
)
case r_time.state of
( 1: render outputheight:rh.value outputwidth:rw.value \
pixelaspect:aspect.value \
outputfile:tempfilename vfb:off
2: render outputheight:rh.value outputwidth:rw.value \
pixelaspect:aspect.value \
outputfile:tempfilename vfb:off \
nthframe:nth.value framerange:#active
3: render outputheight:rh.value outputwidth:rw.value \
pixelaspect:aspect.value \
outputfile:tempfilename vfb:off \
nthframe:nth.value fromframe:r_from.value \
toframe:r_to.value
)
ramplayer tempfilename_a tempfilename_b
closerolloutfloater r_dialogue
) -- end of on go pressed
) -- end of rollout r_size
--
-- close the old rollout floater if it exists
1530 Chapter 12 | Creating MAXScript Tools

try(closerolloutfloater r_dialogue);catch()
-- put up new rollout floater and add rollout to it.
r_dialogue = newrolloutfloater “Render to RAM” 400 300
addrollout r_size r_dialogue
-- end of Macro Script, rollout takes over...
)

Creating Icon Bitmap Files

An icon bitmap file can have any number of individual icons, which are lined up side-by-side in the
file. If you are creating icon bitmap files, these files must meet the following requirements:
• Icon bitmap files must be .bmp files.
• The icon bitmap files are actually groups of files. For each icon bitmap file group there needs to
be at least two image files: one containing 16x15 pixel images ending in _16i.bmp, and another
containing 24x24 pixel images ending in _24i.bmp. For example, these files would be
myicons_16i.bmp and myicons_24i.bmp.
• All icon images in an icon bitmap file must be the same size, as defined by the file name suffix.
• Each icon bitmap file group must contain similar icon images in the same order. This allows a
single index to locate the desired bitmap, independent of which button size option the user has
chosen.
• If monochrome, Windows-compatible masks are available, they need to be stored in files ending
in _16m.bmp and _24m.bmp. For example, these files would be myicons_16m.bmp and
myicons_24m.bmp.
• If 8-bit alpha channel data is available, it needs to be stored in _XXa.bmp files if the alpha is not
premultiplied, and in _XXp.bmp files if the alpha is premultiplied, where XX is either 16 or 24.
For example, these files would be myicons_16a.bmp and myicons_24a.bmp.
• If the mask channel bitmap files are present, they are used. If the mask channel bitmap files are
not present, then the alpha channel bitmap files are used. If neither the mask nor alpha channel
data bitmap files are present, then the color of the upper-left pixel is deemed the transparent
color, and a mask is generated automatically for the image bitmaps.
If you wish to generate icons via calls to render() in MAXScript, make sure you use the naming
conventions previously described and place the .bmp files in the current 3ds max user-interface
directory. You can get the current user-interface directory path with the function:
local ui_dir = cui.getDir ()
 Creating Icon Bitmap Files 1531

Scripted Mouse Tools

Scripted Mouse Tools are used to perform a set of actions based on mouse clicks in the 3ds max
viewports. Tools are useful for scripted object creation plug-ins, as described in the Scripted Plug-ins
(p. 1538) topic. Here’s a simple example:
Script:
tool foo
(
local b
on mousePoint clickno do
if clickno == 1 then b = box pos:worldPoint else #stop
on mouseMove clickno do b.pos = worldPoint
)

This tool allows the user to click in a viewport at which point a box is created. Dragging the mouse
positions the box and releasing the mouse button stops the tool.
You’d start this tool by executing:
startTool foo

The syntax for tools is similar to that for utility definition constructs. They have local variables,
functions, and event handlers, but tools have no user-interface items.
A tool is created using the tool definition construct in MAXScript. The top-level syntax is as follows:
tool <tool_name> [ prompt:<string> ] [ numPoints:<number> ]
( <tool_body> )

where:
<tool_name> is the name of an automatically created variable to hold the value that represents
the tool. The scope of this variable is the current MAXScript scope. This value is also returned
as a result of the tool declaration. The class of this value is MouseTool.
The optional prompt keyword argument specifies the prompt string displayed in the 3ds max
Prompt Line while the tool is executing.
The optional numPoints keyword argument specifies the maximum number of points (mouse
clicks) the tool will use. If the tool is still executing when you reach the numPoints number of
mouse clicks, the tool will stop and return a value of #stop.
<tool_body> is enclosed in the required parentheses and is a sequence of clauses that define
the functions and event handlers that process mouse clicks. These clauses are defined in detail
in the Mouse Tool Clauses (p. 1532) topic.
The following method invokes a tool:
startTool <tool_name> [ prompt:<string> ] [ snap:#3D|#2D ] \
[ numPoints:<number> ]

where:
<tool_name> is the tool name used in a tool definition.
1532 Chapter 12 | Creating MAXScript Tools

The optional prompt keyword argument specifies the prompt string displayed in the 3ds max
Prompt Line while the tool is executing. If specified, this string overrides the prompt string
specified in the tool definition.
The optional snap keyword argument specifies the upper limit on snapping. specifying a snap
parameter does not turn on snap, only the user can turn it on in the interface. When 2.5D or
3D snapping is turned on by the user, the snap parameter restricts snapping to the specified
level.
The optional numPoints keyword argument specifies the maximum number of points (mouse
clicks) the tool will use. If specified, this value overrides the number of points specified in the
tool definition.
The return value from startTool() will be either #stop if a called change handler returns the
value #stop or the numPoints value is reached, or #abort if the user aborts the tool using a
right-click or presses the ESC key.
A currently executing tool can also be aborted using the following method:
stopTool <tool_name>

where:
<tool_name> is the tool name used in a tool definition.
This method would typically be called in a callback function or change handler (see the Change
Handlers and Callbacks (p. 1649) topic), or in a timer event handler in a rollout (see the Timer
(p. 1512) topic).

Mouse Tool Clauses

The <tool_body> of a mouse tool definition is made up of a sequence of tool clauses as follows:
<tool_body> ::= { <tool_clause> }+

Tool clauses define the components of a tool and can be one of two basic things:
• Local variables, functions or structure definitions are variables, functions, and structures whose
scope is the tool. The <tool_body> is compiled in its own local scope and the locals are only
visible inside the scope of the tool. Tool locals are heap-based locals, which are slightly different
from normal (stack-based) locals. Normal locals are visible in the current scope and have a
lifetime of one execution of that scope. Heap-based locals are also visible only in the current
scope, but have a lifetime equal to the lifetime of the top-level expression where they are
defined. A tool’s locals are created the first time you execute the tool and are kept permanently
in the heap (unless and until you redefine the tool). This means things like rollouts created in
a tool that live beyond the simple execution of the tool can refer to these locals and the locals
will still exist. Each time you execute a tool, its local variables are initialized to a value of
undefined, or to their specified initialization value. For example, you can create a rollout in a
tool, and the rollout’s event handlers can access the locals defined in the tool because the rollout
is executing within the scope of the tool. You cannot access the tool’s locals from another utility
 Mouse Tool Clauses 1533

or from Listener, because they are not executing within the scope of the tool. See the Scope of
Variables (p. 646) topic for more information.
• Event handlers are special kinds of functions associated with particular events. Event handlers
specify the processing you want to occur when a user clicks or moves a mouse, right-clicks, or
starts or stops the tool. These actions generate named events and the optional event handler
you supply for that event is called when the action occurs.
Formally, the syntax of a <tool_clause> is defined as follows:
<tool_clause> ::= <local_variable_decl> |
<local_function_decl> |
<local_struct_decl> |
<event_handler>
Locals:
A <local_variable_decl>, <local_function_decl>, and <local_struct_decl> are exactly
the same as local variable, function, and structure definitions in MAXScript:
<local_variable_decl> ::= local <decl> { , <decl> }
<decl> ::= <name> [ = <expr> ] -- optional initial value

<local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr>

<local_struct_decl> ::= struct <name> ( <member> { , <member> } )

<member> ::= ( <name> [ = <expr> ] | <local_function_decl> )

Global variables cannot be declared as a tool clause, however they can be declared within event
handler scripts. If you need to ensure a variable name references a global variable, declare the
variable name as global immediately before defining the tool in your script.
When writing scripts, it is good programming practice to explicitly declare your local and global
variables. Implicit declaration is provided as a short-hand, typically used when working in the
Listener interactively or developing short scripts. When developing extended scripts, explicitly
declaring variables can reduce errors and improve readability of the code. It is also recommend that
you declare as local all variables unless you really want them to be global variables. The reasons for
this are described in the Scope of Variables (p. 646) topic.
Within the functions and event handlers of a tool, 13 pre-defined locals variables are always
accessible. Each one holds a useful value relating to the mouse action that just occurred:
viewPoint Point2
The current mouse position in viewport pixel coordinates.
worldPoint Point3
The current mouse position projected on the active grid in world coordinates.
worldDist Point3
The distance in X, Y, and Z from the previous click point to the current click point in
world coordinates.
worldAngle Point3
The angles around the world X, Y, and Z axes from the previous click point to the current
click point in world coordinates.
1534 Chapter 12 | Creating MAXScript Tools

gridPoint Point3
The current mouse position projected on the active grid in the coordinate system of the
active grid. If the active grid is the home grid, the coordinate system is the home grid
plane active in the current viewport (that is, the construction plane). See the discussion of
grid versus world values below.
gridDist Point3
The distance in X, Y, and Z from the previous click point to the current click point in the
coordinate system of the active grid. If the active grid is the home grid, the coordinate
system is the home grid plane active in the current viewport (that is, the construction
plane). See the discussion of grid versus world values below.
gridAngle Point3
The angles around the world X, Y, and Z axes from the previous click point to the current
click point in the coordinate system of the active grid. If the active grid is the home grid,
the coordinate system is the home grid plane active in the current viewport (that is, the
construction plane). See the discussion of grid versus world values below.
shiftKey Boolean
true if SHIFT key was down.
ctrlKey Boolean
true if CTRL key was down.
altKey Boolean
true if ALT key was down.
lButton Boolean
true if left mouse button was down.
mButton Boolean
true if middle mouse button was down.
rButton Boolean
true if right mouse button was down.
When a create mouse tool is used in a level 5 scripted plug-in, an additional local variable is
accessible:
nodeTM Matrix3
Provides read/write access to the transform of the node currently being created. This value
is in the current grid coordinate system.
See the Scripted Plug-ins (p. 1538) topic for more information.
When writing SimpleObject scripted plug-ins, you should always use the gridPoint, gridDist,
and gridAngle values rather than corresponding world values, as object-creation in SimpleObject
scripted plug-ins is managed in the active grid coordinate system.
For gridDist, the .X and .Y components are the delta X and Y between the previous clicked point
and the current mouse point in the plane of the current grid. The .Z component is a projection from
the current Y screen coordinates onto a Z-vector (in the grid coordinate system) based at the last
point clicked on the grid, such that the .Z value is the projected height up the Z-vector. For non-
orthogonal viewports this is as expected, but for orthogonal viewports (in which you are always
 Mouse Tool Clauses 1535

dragging in the XY plane of the grid), this is always the same as gridDist.y. If you are using the
gridDist value to build the portion of an object on the grid, or determine the distance on the current
grid from the last point, you want to use only the .X and .Y components. For example,
side1Len = gridDist.x
side2Len = gridDist.y
dist=length [gridDist.x,gridDist.y]

If you are specifying the height off of the current grid, you would typically use the .Z component.
For example,
height = gridDist.z

For worldDist, the behavior is similar to that for gridDist, however the projected component is
dependent on the construction plane of the viewport. For the Top, Bottom, and non-orthogonal
viewports, the projected height is contained in the .Z component. For Left and Right viewports, the
projected height is contained in the .X component. For Front and Back viewports, the projected
height is contained in the .Y component.
When you create a node in the 3ds max user-interface, the local Z axis of the node is perpendicular
to the construction plane. When you create a node using MAXScript, by default the local Z axis of
the node points along the direction of the world Z axis. If you create a node in a tool (other than in
a SimpleObject scripted plug-in), you must take into account the construction plane orientation if
you want to duplicate 3ds max’s behavior when creating a node. The easiest way to do this is to
create the node in a coordsys grid context and specify the position of the node during creation
in grid coordinate space. An example of this is shown in the following script.
Script:
tool PointCreator
( local p, createpoint
-- define a function to perform actual node creation. Setting coordsys to
-- ‘grid’ in order for the alignment of the node’s local Z axis to be
-- perpendicular to the construction grid
fn createpoint = in coordsys grid p=point pos:gridPoint
--
-- set up so that a node is created on a mouse button down, move node
-- drag, release node at mouse button up.
--
-- if clickno == 1, then we are at first mouse click, which is a mouse
-- button down. If clickno != 1, at following mouse button up.
on mousePoint clickno do
( if clickno == 1
then createPoint()
-- if p == undefined, then clicked twice without mouse movement
-- (double clicked). No point object present, so just ignore this click.
else if p != undefined do (p.pos=worldPoint;p=undefined)
)
--
-- if p != undefined, we are moving a previously created node
-- if p == undefined, and left mouse button is down, create a node
on mouseMove clickno do
1536 Chapter 12 | Creating MAXScript Tools

( if p != undefined
then p.pos=worldPoint
else if lbutton do createPoint()
)
)
-- start the tool. No exit condition defined, so right-click to exit.
startTool PointCreator

Event Handlers:
An <event_handler> is a special function definition local to a tool that you provide to handle the
processing you want to occur when a user clicks in a viewport, right-clicks, or starts or stops the tool.
Each user action generates a named event and any event handler you supply for that event is called
when the action occurs. The available event handlers are:
on start do <expr>
Called when the tool starts.
on end do <expr>
Called when the tool ends.
on freeMove do <expr>
Called when the mouse moves prior to the first click.
on mousePoint <arg> do <expr>
Called for each mouse click, parameter arg contains the number of the click.
on mouseMove <arg> do <expr>
Called when the mouse moves anytime after the first click.
on mouseAbort <arg> do <expr>
Called when the user right-clicks to cancel or presses the ESC key.
The <arg> parameter on each of the mouse event handlers lets you know which mouse click you
are in. Mouse clicks are actually only the mouse click release, except for the initial mouse click. If
you do a mouse click, drag, release, move, click, drag, and release, the on mousePoint event handler
is called three times: the first click, the first release, and the second release, with <arg> values of 1,
2, and 3, respectively. The mouse click counter is incremented after processing the on mousePoint
event handler, so the <arg> parameter for the mouseMove and mouseAbort event handlers specify
the click count for the next mouse click. In the previous example, when you drag between the first
click and first release, the <arg> value for a mouseMove event handler will have a value of 2. During
the following move, click, and drag it will have a value of 3.
The following script simply demonstrates when the various event handlers are called. Simply run
this script and drag in the viewports. Right-click or press the ESC key to stop the tool’s execution.
 Mouse Tool Clauses 1537

Script:
tool foo
( on freeMove do print “Free Moving”
on mousePoint clickno do format “Point: %\n” clickno
on mouseAbort clickno do format “Abort: %\n” clickno
on mouseMove clickno do format “Moving: %\n” clickno
on start do print “Starting”
on end do print “Ending”
)
startTool foo prompt:”Hello!”

All of the mouse action event handlers may return the special value #stop which causes the tool to
stop. In the following mousePoint event handler example, the first click creates the box and the
release (second click) terminates the tool.
on mousePoint clickno do
if clickno == 1
then b = box pos:worldPoint
else #stop

Example:
The following script implements the following functions: on mouse click three spot lights are
created at the mouse point. While holding the mouse button down, drag the mouse to position the
classical key, back and fill light positions. During this drag, holding down the SHIFT key will flip the
fill light side. Release the mouse button and move the mouse to change the elevation of the lights.
Click the mouse button when the lights are at the correct height. The back light is raised 1.5 times
the key light’s height, and the fill light is raised 0.75 times the key light’s height.
To start this tool, you’d say:
startTool three_lights

and then drag in one of the viewports.

Script:
tool three_lights
(
local key, fill, back, targ
--
on mousePoint click do coordsys grid
( if click == 1 then -- create key, back & fill lights at mousedown
( targ=targetobject pos:gridPoint
key = targetspot pos:gridPoint name:”key” target:targ
back = targetspot pos:gridPoint name:”back” target:targ
fill = targetspot pos:gridPoint name:”fill” target:targ
)
if click == 3 then #stop
)
--
on mouseMove click do
( if click == 2 then -- drag out & round on x-y plane
( coordsys grid key.pos = gridPoint
1538 Chapter 12 | Creating MAXScript Tools

coordsys targ back.pos = - key.pos

local p = if shiftKey then 90 else -90
coordsys targ fill.pos = key.pos * ((eulerangles 0 0 p) as quat)
)
else if click == 3 then -- drag up to elevate lights
( in coordsys targ
( local Z = gridDist.z
key.pos.z = Z
back.pos.z = Z * 1.5
fill.pos.z = Z * 0.5
)
)
)
)

See also
Scripted Mouse Tools (p. 1531)

Scripted Plug-ins
MAXScript supports several levels of scripted plug-ins, as follows:
The scripted plug-in appears in the user interface as a new class but does not allow instances of itself
in the scene. It lets you define a mouse tool that creates other objects in the scene, but once you’ve
finished creation, there is no instance of the class left in the scene to modify or save. Examples of
this currently in 3ds max are the System classes such as RingArray.
The scripted plug-in extends an existing plug-in, either adding to or replacing the command panel
parameter rollouts for the existing plug-in. For example, you might create a new “glass” material
which extends StandardMaterial and provides a custom, presumably smaller, Material Editor rollout
that just has glass parameters which set up and modify various properties in the underlying material
plug-in as appropriate. Or, you want to create a new light type that is actually a system of
coordinated lights, that also has a “controlling” dummy object created. This controlling dummy
keeps track of the lights in the system and has a Create/Modify panel rollout that allows coordinated
manipulation of the system. In this case, you’d create a new helper plug-in that extends Dummy,
has locals to store the lights, and define a rollout. You would also create a new light plug-in with a
create tool that builds the system.
The scripted plug-in is given a unique and permanent class ID value by the script writer and so can
be instanced in the scene and stored in scene files. All 3ds max plug-ins have a unique class ID and
3ds max uses this class ID to associate stored scene objects with the code that handles them each
time you open a scene file, hence it has to be unique and permanent. In the level 1 scripted plug-in
above, MAXScript allocates a temporary class ID that is not permanent across executions of 3ds max
and thus prevents instancing in the scene.
The scripted plug-in defines one or more parameter blocks, containing directly animatable parameters
that are saved to and restored from scene files. These are the permanent parameters for the plug-in
and are distinct from the local variables in the example above which only live during creation.
 Mouse Tool Clauses 1539

A parameter block can be associated with a rollout in the scripted plug-in that provides a user
interface for the parameters in the parameter block. When associated in this way, the parameters are
“wired” to their spinners and checkboxes, etc., and both update automatically as the other changes.
The general form for a scripted plug-in is:
plugin <superclass> <varname> {keyword:val}
( <plugin_body> )

where:
<superclass> is one of the currently-supported plug-in superclasses:
Geometry
SimpleObject
Shape
Light
Helper
Modifier
SimpleMod
Material
TextureMap
RenderEffect
Atmospheric

<varname> is the name that will be given to the global variable that contains this plug-in class.
This class value is just like a normal plug-in class (like box, sphere, etc.) and you can create an
instance of the plug-in in MAXScript by applying the class value.
{keyword:val} is an optional sequence of keyword/value pairs defining options for the
plug-in. These pairs are:
name:<string>
The optional name: parameter specifies the name of the plug-in as seen in the
3ds max user-interface. For example, if the superclass of the plug-in is geometry or
light, this name would be displayed on the plug-in’s button in the Create panel; if
the superclass of the plug-in is modifier, this name would be displayed on the plug-
in’s button in the Modify panel; and if the superclass of the plug-in is material or
textureMap, this name would be displayed in the Material/Map Browser. The default
name is the plug-in’s <varname>.
category:<string>
The optional category: parameter specifies in which object category (access via the
object category list) the plug-in will appear in. This parameter is applicable only to
plug-ins that appear in the Create panel. The default category in “Standard”. Note that
there is a fixed number of buttons available in the Create panel for each category. If a
button for your plug-in does not show up in the appropriate Create panel, you may
need to make a new category for it.
1540 Chapter 12 | Creating MAXScript Tools

classID:#(<integer>,<integer>)
You supply the classID:#(<integer>,<integer>) parameter if you want the
plug-in to be creatable and storable in the scene. This ID becomes the permanent ID
for the class and is used by 3ds max to identify objects as they are saved and loaded in
the scene. You don’t need to supply a class ID value if the plug-in is to be like a System
object that only creates other types of objects in the scene. The class ID is basically a
pair of numbers, chosen randomly so that (hopefully) they won’t conflict with
another plug-in. MAXScript provides a method to generate a fresh random class ID
each time you run it:
genClassID()
This method generates a random class ID similar to #(0x9b7ea231,
0xb6db86ef), and prints it to Listener. You can just cut and paste this class ID
into your script to use the generated ID.
extends:<maxClass>
The extends:<maxClass> parameter is supplied if you want to base your plug-in on
an existing plug-in. This basically lets you add a new class that works internally
exactly like the one you are extending, but with an expanded or replaced user
interface. The class you specify must have the same superclass as specified in the
scripted plug-in header. Current limitations prevent certain plug-ins from being
extended, in particular those with custom creation managers. These include target
lights and cameras and all the System plug-ins. You can tell if a plug-in is not
extendable if your new rollouts do not appear.
When you create an object of scripted plug-in that extends another, MAXScript also
creates an internal object of the extends: plug-in and passes most of 3ds max’s
interaction with your plug-in onto the internal object. This is called delegation and the
internal extends: plug-in object is the delegate. The delegate is visible in your plug-
in’s objects in Track View and you can access the delegate in your scripts to control it
as needed. See the locals section below for more information. The delegate is not
shown in TV if replaceUI:true is specified.
replaceUI:<boolean>
The replaceUI: parameter is used only when extends: is supplied to indicate
whether the rollouts in your plug-in should add-to or replace the extended plug-ins
rollouts. The default is false, which means your rollouts will be appended at the end
of the extended plug-in’s. Another current limitation when extending plug-ins whose
objects are created in the Create panel only allows user interface replacement in the
Modifier panel; the original plug-in’s rollouts are always displayed along with the
scripted rollouts in the Create panel.
version:<integer>
The optional version: parameter specifies the version number of the scripted plug-
in. The value assigned to this parameter is used when updating the scripted plug-in
definition. The default value for this parameter is 1. See the Updating Scripted Plug-ins
(p. 1553) topic for more information on this parameter.
 Mouse Tool Clauses 1541

invisible:<boolean>
The optional invisible: parameter gives control over whether the plug-in is visible
in the Create panel Object Type rollout or in the Material/Map Browser, etc. This is
useful for component or controlling objects created as part of a group, say in a System-
style plug-in that should not be creatable on their own. Set this parameter to true to
hide the plug-in.
silentErrors:<boolean>
The optional silentErrors: parameter gives control over whether MAXScript run-
time error messages are displayed when executing handlers in the scripted plug-in. If
this parameter is set to true, error messages will not be displayed. This may be useful
for distributed scripted plug-ins that may confuse the user with MAXScript error
messages.
<plugin_body> is enclosed in the required parentheses and is a sequence of clauses that define
the local variables and functions, parameters, user-interface items, and event handlers that
define the plug-in. These clauses are defined in detail in the Scripted Plug-in Clauses (p. 1542)
topic.
If you load a scene file that uses a level 3 or higher scripted plug-in, and you have not defined that
scripted plug-in, a Missing DLL dialog will be displayed after the load, indicating the definition for
the scripted plug-in is missing. The file will then load using a standin for the object with the missing
definition, just as it would for other objects missing their DLL definitions. 3ds max treats scripted
plug-ins as it does C++ plugins, requiring the definition to be in place, either in a script file in the
plugins directory when 3ds max starts, or having been defined by running some script prior to
loading the file.

See also
Scripted Plug-in Clauses
Scripted Plug-in Methods
Updating Scripted Plug-ins
Scripted Geometry Plug-ins
Scripted SimpleObject Plug-ins
Scripted Shape Plug-ins
Scripted Light Plug-ins
Scripted Helper Plug-ins
Scripted Modifier Plug-ins
Scripted SimpleMod Plug-ins
Scripted Material Plug-ins
Scripted TextureMap Plug-ins
Scripted RenderEffect Plug-ins
Scripted Atmospheric Plug-ins
1542 Chapter 12 | Creating MAXScript Tools

Scripted Plug-in Clauses

The various optional clauses inside the plug-in body are similar to those for scripted utilities and
tools. There is an additional scripted plug-in specific clause <parameters> for defining scene-
savable and Track View visible parameters for the plug-in.
The <plugin_body> of a scripted plug-in definition is made up of a sequence of plug-in clauses as
follows:
<plugin_body> ::= { <plugin_clause> }+

Plug-in clauses define the components of a scripted plug-in and can be one of five basic things:
• Local variables, functions or structure definitions are variables, functions, and structures whose
scope is the plug-in. These locals will exist as long as the instance of the plug-in exists. The
visibility of locals, and accessing scripted plug-in locals from external code, are described in the
Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code (p. 1478) and
Accessing Locals and Other Items in a Rollout from External Code (p. 1480) topics.
• Parameter blocks define a set of parameters for the plug-in, which are like plug-in local
variables, but are directly animatable and are saved to and restored from scene files. You can also
associate each parameter with appropriate user-interface elements in one of the plug-ins
rollouts. When associated in this way, the parameters are “wired” to their spinners and
checkboxes, etc., and both update automatically as the other changes, so you don’t have to
write any user-interface event handlers for them. These parameters correspond to the visible
parameters you see in other 3ds max plug-ins.
• Mouse tools are used to perform a set of actions based on mouse clicks in the 3ds max viewports,
and are described in the Scripted Mouse Tools (p. 1531) topic.
• Rollouts can be displayed for the scripted plug-in. For scripted plug-ins that extend an existing
plug-in, these rollouts can be displayed in addition to or replace the existing plug-in’s rollouts.
Rollout definitions are described in the Utility Clauses (p. 1466) topic.
• Event handlers are special kinds of functions associated with particular events. Event handlers
specify the processing you want to occur when a user creates an instance of the scripted plug-in
or when 3ds max calls the scripted plug-in. These actions generate named events and the
optional event handler you supply for that event is called when the action occurs.
Formally, the syntax of a <plugin_clause> is defined as follows:
<plugin_clause> ::= <local_variable_decl> |
<local_function_decl> |
<local_struct_decl> |
<parameters> |
<tools> |
<rollouts> |
<event_handler>
 Scripted Plug-in Clauses 1543

Locals:
A <local_variable_decl>, <local_function_decl>, and <local_struct_decl> are exactly
the same as local variable, function, and structure definitions in MAXScript:
<local_variable_decl> ::= local <decl> { , <decl> }
<decl> ::= <name> [ = <expr> ] -- optional initial value

<local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr>

<local_struct_decl> ::= struct <name> ( <member> { , <member> } )

<member> ::= ( <name> [ = <expr> ] | <local_function_decl> )

Global variables cannot be declared as a plug-in clause, however they can be declared within event
handler scripts. If you need to ensure a variable name references a global variable, declare the
variable name as global immediately before defining the plug-in in your script.
When writing scripts, it is good programming practice to explicitly declare your local and global
variables. Implicit declaration is provided as a short-hand, typically used when working in the
Listener interactively or developing short scripts. When developing extended scripts, explicitly
declaring variables can reduce errors and improve readability of the code. It is also recommend that
you declare as local all variables unless you really want them to be global variables. The reasons for
this are described in the Scope of Variables (p. 646) topic.
Plug-in locals are attached to plug-in objects, and each new instance of the scripted plug-in has its
own local storage area. When you reference a plug-in local in a plug-in function or handler, it
accesses the local storage of the currently active object, for example, the object currently open in the
command panel. Plug-in local storage is not permanent across scene saves and loads (unlike
<parameters>). You can provide initial values for locals, as elsewhere in MAXScript, and the locals
are re-initialized when a saved scripted plug-in object is loaded again as part of a scene file open. You
can also do this by hand in a create event handler if you supply one in the plug-in.
Plug-in locals are accessible to script code outside a plug-in as a normal property on the object, but
note that they may be hidden by parameters or other common object properties if they have the
same name. When accessing a property on a scripted plug-in object, MAXScript first looks in the
common properties (such as .pos, .scale, .parent, etc. on a node), then in the parameters, and
then in the locals for a property name match.
There are three predefined local variables accessible in all scripted plug-ins:
version
Yields the current version of the object as an Integer value.
this
Yields the instance of the scripted plug-in.
delegate
Yields the instance of the plug-in you are extending in an extends: plug-in.
1544 Chapter 12 | Creating MAXScript Tools

The version local variable contains the version number specified in the scripted plug-in definition.
See the Updating Scripted Plug-ins (p. 1553) topic for more information on this variable.
The this local variable always contains the MAXScript value corresponding to the current instance
of the scripted plug-in. This variable provides a guaranteed way of accessing parameters on the new
object within plug-in code (in case there are locals or globals with the same name), and it is a way
of referencing the plug-in in case you want to store it to a variable.
The delegate local variable contains the MAXScript value corresponding to the instance of the
plug-in being extended. To access common properties or subAnim properties in the instance of the
plug-in being extended, you need to do so via the delegate local variable. For example,
delegate.width = thisWidth
inside a plug-in function or handler would set the .width property in the instance of the
plug-in being extended. The delegate local variable in a scripted plug-in that creates a
scene object does not contain the node itself, but a the BaseObject of that node. As such,
you can not access the node level properties of the object being created. An exception to
this is the node’s transform, which is exposed to the scripted plug-in through a local
variable called nodeTM. This variable is described in the applicable scripted plug-in
type topics.
If the extends: parameter is not supplied for a plug-in, delegate returns undefined.
As well as local variables, you can define local functions and local structures, just as you can with
scripted utilities and rollouts.
Parameters:
You can define one or more parameter blocks in a scripted plug-in. A parameter block has the form:
parameters <name> [type:#class] [rollout:<name>]
(
{ <param_defs> }+
{ <event_handler> }
)

A parameter block defines a set of parameters for the plug-in, which are like plug-in local variables,
but are directly animatable and are saved to and restored from scene files. You can also associate each
parameter with appropriate user-interface elements in one of the plug-ins rollouts. When associated
in this way, the parameters are “wired” to their spinners and checkboxes, etc., and both update
automatically as the other changes, so you don’t have to write any user-interface event handlers for
them. These parameters correspond to the visible parameters you see in other 3ds max plug-ins.
Parameters in the parameter block do not participate in 3ds max’s undo system, therefore changes
to the parameter values are not undoable.
The <name> you give to a parameter block becomes permanently associated with the parameter
block and is used by MAXScript to connect to the right parameter block in a plug-in object that is
being loaded from a scene file. This becomes important as you modify a plug-in script and yet there
are still objects corresponding to the old definition in other files. When the old-version object is
loaded, MAXScript attempts to convert it to the new definition, using the current parameter block
definition as a guide. In order to properly do this, each parameter in a parameter block is also given
 Scripted Plug-in Clauses 1545

a permanent name. So, if you have existing objects of your plug-in in other files, don’t go randomly
changing parameter block names or they won’t be loadable.
The optional type:#class specifies that the parameters in the parameter block are “class”
parameters. This means that there is one copy of each parameter for the *all* the objects of this plug-
in class; they all share the parameter. Examples of existing class parameters are the creation type and
type-in parameters in a typical geometry primitive.
The optional rollout:<name> specifies a rollout definition elsewhere in the plug-in body to use as
the user-interface rollout for the parameter block’s parameters. A limitation of the internal
parameter block mechanism requires that each parameter block be associated with a separate rollout
and each rollout be associated with only one parameter block. This means that each rollout you
want to have in the plug-ins user interface must have its own separate parameter block.
The <param_defs> are definitions for each parameter in the parameter block. They have the form:
<name> type:<#name> [tabSize:<integer>] [tabSizeVariable:<boolean>] \
[default:<operand>] [animatable:<boolean>] \
[subAnim:<boolean>] [ui:<ui_def>]

The <name> is permanently associated with the parameter in the same sense as parameter block
names. They are used to connect to the right parameter when loading objects of the scripted plug-
in and allow you to make certain changes to a script and yet still be able to load old version objects.
So, as with parameter block names, don’t change or re-use parameter names if you have scene files
with old version objects you want to get at.
The type:<#name> parameter is required and defines the parameter type. It can be one of the
following:
#float animatable
#integer animatable
#color animatable
#point3 animatable
#boolean animatable
#angle animatable
#percent animatable
#worldUnits animatable
#string
#filename
#colorChannel animatable
#time animatable
#radiobtnIndex
#material
#texturemap
#bitmap
#node
#maxObject
1546 Chapter 12 | Creating MAXScript Tools

or one of the following types which are arrays of the above base types:
#floatTab
#intTab
#colorTab
#point3Tab
#boolTab
#angleTab
#percentTab
#worldUnitsTab
#stringTab
#filenameTab
#colorChannelTab
#timeTab
#radiobtnIndexTab
#materialTab
#texturemapTab
#bitmapTab
#nodeTab
#maxObjectTab

#worldUnits and #worldUnitsTab specify that a parameter holds a world distance value, kept
internally as a system units float. For example:
parameters main rollout:params
(
height type:#worldUnits ui:heightSpin
)

Note that this doesn’t cause any spinner display to be automatically shown in current display units,
you need to also specify type:#worldUnits on the associated rollout spinner definition.
#node and #nodeTab are used to store references to nodes. The nodes stored in these parameters
cannot create a circular dependency. If, for example, you were creating a scripted helper, and set the
helper as a target or parent of a camera, you can not store the camera node in a #node or #nodeTab
parameter. Likewise, if you created a scripted modifier or material, and store a node in a #node or
#nodeTab parameter, you cannot apply the modifier or material to that node.
 Scripted Plug-in Clauses 1547

The various xxTab parameter types allow you to store an array of values having the corresponding
type. The initial size of the array is specified using the tabSize: specifier. If
tabSizeVariable:true is specified, the size of the array will be automatically expanded when you
assign to an higher array index. For example:
parameters main rollout:params
(
mapAmounts type:#floatTab tabSize:4 tabSizeVariable:true \
ui:(map1Amount, map2Amount, map3Amount)
)
defines an array parameter containing 4 float elements (defined by the tabSize:
parameter). You can associate a separate rollout element with each array parameter
element. These parameters appear as arrays when accessed in plug-in handler code, for
example:
a = mapAmounts[i]

Since tabSizeVariable:true was specified, the following will automatically increase

the array size to 10:
mapAmounts[10] = a

You can also increase or decrease the array size by assigning a value to the .count property.
Each element in an array parameter whose base type is a number of some kind (floatTab, intTab,
percentTab, etc.) is independently and automatically animatable, unless you specify
animatable:false. You can get at and assign individual controllers via the .controller
property. For example:
c = mapAmounts[i].controller

The optional parameter default:<operand> specifies a initial default value for the parameter. The
<operand> expression has to be convertible by MAXScript to the base type of the parameter.
The optional parameter animatable:<boolean> specifies whether the parameter is animatable
and hence visible in the track view. Only those base types marked as animatable in the above type
list can be specified as animatable. Defaults to true.
The optional parameter subAnim:<boolean> can be specified for the 3ds max object types: #node,
#material, #textureMap, and #maxObject. If specified as true, the 3ds max object is made
visible as a sub-object track in track view. Defaults to false.
The optional parameter ui:<ui_def> is used to specify which user-interface element in the
parameter block’s associated rollout is to be linked to this parameter. When so linked, the handling
of user actions for these elements are automatic and they also update automatically to follow any
changes to the parameter caused by animation, scripts, etc. For example, in the following, the
parameter block named main is associated with the rollout named params. The parameters height
and spread are then linked with the spinners named height and spread in that rollout:
1548 Chapter 12 | Creating MAXScript Tools

parameters main rollout:params

( key type:#node subAnim:true
fill type:#node subAnim:true
back type:#node subAnim:true
height type:#float animatable:true default:10 ui:height
spread type:#float animatable:true default:10 ui:spread

on height set val do

( key.pos.z = val
back.pos.z = val * 1.5
fill.pos.z = val * 0.5
)
)

rollout params “Light Parameters”

( spinner height “Height”
spinner spread “Spread”
)

Once this is done, the parameter and spinner are linked, such that changes in one are reflected
immediately and automatically in the other. Further, if the parameter is animated, the spinner will
show red keyframe highlights when the time slider is positioned at a keyframe for that parameter,
as with other 3ds max plug-ins. The kinds of user-interface items that can be linked to particular
parameter types is limited to the following sensible combinations:
Parameter type Rollout user-interface item
#integer spinner, slider, radioButtons, checkbox, checkbutton
#float spinner, slider
#time spinner, slider
#color colorpicker
#angle spinner, slider
#percent spinner, slider
#colorChannel spinner, slider
#boolean checkbox, checkbutton
#node pickButton
#textureMap mapButton
#material materialButton
#worldUnits spinner, slider

Parameter Event Handlers:

Two event handlers are associated with parameters. These handlers are called when a parameter is
assigned a value, or when the parameter value is retrieved.
on <name> set <arg> do <expr>
A set handler can be supplied for any of the parameters in the block and it will be called
whenever the parameter is updated, either through an associated rollout user-interface
item or directly, especially via MAXScript property assignment. In general, the way you
would code change handlers is to supply set handlers for parameters, rather than on
<item> change handlers for spinners and checkboxes, etc. in the rollout definition. A set
 Scripted Plug-in Clauses 1549

handler in used in the previous example to update the light positions when the height
parameter value changes.
The set handlers are also called when an instance is created or loaded so that common
dependent actions can be taken, such as setting up other dependent system object or
delegate properties.
If a parameter is animated and has a set handler supplied, the handler will be called
whenever the 3ds max time changes, say by dragging the time slider around or within an
animation rendering.
on <name> get <arg> do <expr>
A get handler can be supplied for any of the parameters in the block and it will be called
whenever the parameter value is retrieved. This will occur when the user interface updates
itself, a script accesses the parameter, a viewport is redraw, a render occurs. In all these
cases, the animated value is retrieved one or more times. The get handler is called with a
single argument which is the current value stored in the paramblock (or underlying
controller if the parameter is animated). The currentTime variable is set to the time at
which the value is being retrieved and not necessarily the current slider time, since you
can ask a parameter for its value for any specified time. If you implement the get handler,
you must return a value, and that value is returned as the value of the parameter to the
value requester. If you don’t want to modify the value, but just monitor accesses, return
the argument. You can also compute and return any value of the appropriate type.
Tools:
Plug-ins can define local mouse tools. Although you can have any number of local tools and start
them as needed, you would typically supply a single tool with the reserved name create. This is
taken to be the create tool for objects created in the Create panel and is invoked automatically when
you create scripted plug-in objects. Tool definitions are described in the Scripted Mouse Tools (p. 1531)
topic.
Creatable scene scripted plug-ins (scripted plug-ins that are not invisible, temporary, or extend
another plug-in) require a create tool. A create tool, if present on a non-temporary extending
plug-in, will override the delegate’s create tool. The animate state is implicitly turned off while the
create tool is executed.
A local variable nodeTM is accessible within the create tool. This variable contains a Matrix3 values.
This value is in the active grid coordinate system. This variable allows the create tool to set the
transform of the node currently being created. Also, within the create tool you should use the
gridX values rather than worldX values in all cases, since object-creation is managed in the active
grid coordinate system.
Rollouts:
Plug-ins can define local rollouts. These have the same syntax as local rollouts in scripted utilities.
Unlike utility local rollouts, these rollouts are automatically opened as appropriate for the plug-in
type (in the command panel or Material Editor, etc.).
1550 Chapter 12 | Creating MAXScript Tools

Note that rollout local variables only live as long as the rollout is open in the user interface. It gets
opened and closed each time it is displayed and so the rollout open and close events are signalled at
this time. If you want to load any spinners or other user-interface elements from the currently
editing plug-in object, supply an on <rollout> open event handler to pick up these values.
Rollout definitions are described in the Utility Clauses (p. 1466) topic.
Event Handlers:
As with mouse tools, scripted plug-ins respond to certain actions in 3ds max by implementing
handler functions. All types of scripted plug-ins support the following event handlers. You can use
these event handlers to perform any extra initialization needed, such as loading up plug-in local
variables or initializing properties of the plug-in’s delegate.
on create do <expr>
The create event handler that is called whenever an instance of a scripted plug-in is
created in a scene file. The animate state is implicitly turned off while the create event
handler expression is executed.
on load do <expr>
The load event handler that is called whenever an instance of a scripted plug-in is loaded
from a scene file. The animate state is implicitly turned off while the load event handler
expression is executed.
on update do <expr>
The update event handler that is called whenever an instance of a scripted plug-in is
present in the scene file, and the definition of the scripted plug-in is changed (i.e., if you
define a scripted plug-in, create an instance of the plug-in object in the scene, and then
change and execute the script defining the scripted plug-in, the update event handler
defined in the new definition of the scripted plug-in script is called for each instance of the
plug-in object in the scene). See the Updating Scripted Plug-ins topic for more
information.
Specific classes of scripted plug-ins implement additional event handlers, and are described with
description of the scripted plug-in type.
Runtime errors in certain event handlers cause the plug-in to be disabled until it is re-defined. When
disabled, none of the plug-in event handlers are called. For example, errors in the map event handler
expression in SimpleMods and the buildMesh event handler expression in SimpleObject disable
the plug-in, since they are called so frequently. You will need to correct any problems and re-evaluate
the plug-in definition again to re-enable the plug-in event handlers.

See also
Scripted Plug-ins (p. 1538)
 Scripted Plug-in Methods 1551

Scripted Plug-in Methods

The addPluginRollouts() is used within scripted plug-in create tools, specifically for level 1
plug-ins that don’t create instances of themselves in the scene but might create other objects within
their create tool. This method lets you install rollouts for a specified object in the Create panel,
typically one of the objects being created in the create tool, so that its parameters can be adjusted
directly during creation. The form is:
addPluginRollouts <obj>

In the following example, a variation of the three light mouse tool example presented in the Mouse
Tool Clauses (p. 1532) topic is set into permanent, editable classes. It defines two new classes. The
helper class lightMaster is used as a master object for the light system. The light class
threeLights is what you create to layout the initial system. It also creates a lightMaster and sets
its parameters to point at the lights. The lightMaster rollout allows subsequent editing of the
system in the Modifier panel, and storing the lights in a parameter block makes the setup persistent
over scene saves and loads.
Script:
plugin helper lightMaster
name:”Light Master”
classID:#(12345,54321)
extends:Dummy
replaceUI:true
invisible:true
(
parameters main rollout:params
( key type:#node subAnim:true
fill type:#node subAnim:true
back type:#node subAnim:true
height type:#worldUnits default:0 ui:height
spread type:#worldUnits default:0 ui:spread
angle type:#angle default:90 ui:angle
--
-- check value of key since lights don’t exist at initial creation
on height set val do if key != undefined then coordsys key.target
( key.pos.z = val
back.pos.z = val * 1.5
fill.pos.z = val * 0.5
)
--
on spread set val do if key != undefined then coordsys key.target
( -- compute normal vector pointing at key in the target’s XY plane
-- (kuv) and reposition everything based on that and the current
-- spread and angle values
local kuv = normalize ([key.pos.x, key.pos.y, 0])
key.pos = [kuv.x * spread, kuv.y * spread, height]
back.pos = [kuv.x * -spread, kuv.y * -spread, height * 1.5]
-- position fill by placing it under the key and then rotating in
-- about the target
1552 Chapter 12 | Creating MAXScript Tools

fill.pos = [kuv.x * spread, kuv.y * spread, height * 0.5]

about key.target rotate fill angle z_axis
)
--
on angle set val do if key != undefined then coordsys key.target
( fill.pos = [key.pos.x, key.pos.y, height * 0.5]
about key.target rotate fill angle z_axis
)
)
--
rollout params “Light Parameters”
( spinner height “Height” type:#worldUnits range:[-1e32, 1e32, 0]
spinner spread “Spread” type:#worldUnits range:[0, 1e32, 0]
spinner angle “Angle” range:[-180, 180, 30]
--
on params open do flagForeGround #(key, back, fill) true
on params close do
if key != undefined and back != undefined and fill != undefined then
flagForeGround #(key, back, fill) false
)
)
--
plugin light threeLights
name:”Three Lights”
( local master
--
tool create
( on mousePoint click do
( if click == 1 then -- create key, back & fill lights at mousedown
( coordsys grid
( master = lightMaster pos:gridPoint
master.dummy.boxsize = [10,10,10]
in master
( local targObj=targetobject pos:gridPoint
master.key = targetspot pos:gridPoint name:”key” \
target:targObj
master.back = targetspot pos:gridPoint name:”back” \
target:targObj
master.fill = targetspot pos:gridPoint name:”fill” \
target:targObj
)
)
addPluginRollouts master
)
if click == 3 then
( select master
master = undefined
#stop
)
)
--
 Updating Scripted Plug-ins 1553

on mouseMove click do
( if click == 2 then -- drag out & round on x-y plane
( -- place the key on the grid then set the spread and the
-- ‘on set spread’ handler will
-- move the lights to the correct heights
master.key.pos = worldPoint
master.spread = distance master.key master.key.target
)
else if click == 3 then -- drag up to elevate lights
master.height = gridDist.z
)
--
on mouseAbort click do
( if master != undefined then
( if master.fill != undefined then delete master.fill
if master.back != undefined then delete master.back
if master.key != undefined then delete master.key
delete master
)
)
)
)

See also
Scripted Plug-ins (p. 1538)

Updating Scripted Plug-ins

MAXScript allows you to redefine scripted plug-ins while working in 3ds max, and have old
instances in the current scene and in scenes you load automatically updated to the new definition.
This ability to redefine scripted plug-ins is called schema-migration. MAXScript does this roughly by
matching the names of local variables, parameter blocks and parameters between the old version
instances and the new definition. It keeps any variables, parameter blocks and parameters of the
same name, drops anything missing in the new definition and creates new variables, blocks and
parameters as needed, filling them in with default values.
There are some limitations on the kinds of change that can be supported. Specifically:
• Parameter blocks that were per-instance cannot be made per-class and vice versa.
• Parameters cannot change type across redefinitions.
• Parameters cannot not move from one parameter block to another across redefinitions
This same mechanism is used to update old versions of scripted plug-in objects stored in scene files.
Remember that this only works properly if the classID: specified in the scripted plug-in definition
that was in force when the scene was saved is the same as the current classID: in the definition
since 3ds max depends upon this classID to match up objects in the scene file and their class
definitions.
1554 Chapter 12 | Creating MAXScript Tools

You can specify an update event handler in a scripted plug-in and it will be called whenever the
object is updated by this schema migration mechanism. To make this more useful, MAXScript
supports a version number on scripted plug-ins. The version for any particular instance of the plug-
in can be accessed via the version special local variable in any plug-in local function or handler.
When the update event handler is called during a schema-migration, the old version number is still
in force, but is updated to the current version number immediately after update. For example:
plugin helper lightMaster
name:”Light Master”
classID:#(12345,54321)
extends:Dummy
invisible:true
replaceUI:true
version:3 -- set current version to 3
(
parameters main rollout:params
...

on update do
(
if version == 1 then ... -- do something special for v1 instances
)
...
)

Note that you only need to use this explicit version access and update scheme if you want to do some
special manual conversion over-and-above the automatic migration described above.
Finally, if there are no existing instances of the plug-in, either in the current scene or in other scenes
that you care about keeping, you can simply delete them and make whatever changes you like the
scripted plug-in definition. The above version update considerations come into play only when you
wish to support old version objects of your scripted plug-in.

See also
Scripted Plug-ins (p. 1538)
 Scripted Geometry Plug-ins 1555

Scripted Geometry Plug-ins

A scripted Geometry plug-in is declared by specifying the <superclass> as geometry. Scripted
Geometry plug-ins require a create tool unless they are invisible, temporary, or extend another
plug-in. If the plug-in extends another plug-in, and a create tool is specified, it will override the
delegate’s create tool.
Script:
plugin geometry foo_plugin_def
name:”FooBar”
category:”Scripted Primitives”
( local boxes, clickAt
tool create
( on mousePoint click do
( clickAt = worldPoint
boxes = for i in 1 to 10 collect box pos:([i*20,0,0] + clickAt)
#stop
)
)
--
rollout frab “Parameters”
( spinner frab “Frabulate” range:[-1000,1000,20]
on frab changed val do
for i in 1 to 10 do boxes[i].pos = [i*val,0,0] + clickAt
)
)

This adds a new geometry category with one button to the Create panel. Pressing the FooBar button
starts a mouse command mode that creates a row of 10 boxes where you click and adds a rollout to
the command panel with one spinner that lets you adjust the separation of the boxes. This is very
similar to a System object like the RingArray, except it lives in the Geometry tab. This is the simplest
type of scripted of plug-in; it has no specific scene object and no storable parameters.
In the tool handlers, you can set the delegate properties as needed. For example:
Script:
plugin geometry Cuboid
name:”Cuboid”
classID:#(0x133067, 0x54374)
category:”Scripted Primitives”
extends:Box
( fn fmax val1 val2 = if val1 > val2 then val1 else val2
tool create
( on mousePoint click do
case click of
( 1: nodeTM.translation = gridPoint
2: #stop
)
--
on mouseMove click do
if click == 2 then
1556 Chapter 12 | Creating MAXScript Tools

delegate.width = delegate.length =
delegate.height = 2 * fmax (abs gridDist.x) (abs gridDist.y)
)
)

See also
Updating Scripted Plug-ins (p. 1553)
Scripted Plug-in Methods (p. 1551)
Scripted Plug-in Clauses (p. 1542)
Scripted Plug-ins (p. 1538)
Scripted Mouse Tools (p. 1531)

Scripted SimpleObject Plug-ins

A SimpleObject is a kind of geometry primitive object that is defined by a tri-mesh, such as box,
sphere, cone, and so on. In other words, all the Standard and Extended primitives in 3ds max. In
scripting a SimpleObject plug-in, you supply a handler for building this mesh and 3ds max
automatically handles scene display, hit-testing, ray intersection, rendering, modifier applicability,
etc. A scripted SimpleObject plug-in is declared by specifying the <superclass> as simpleObject.
Scripted SimpleObject plug-ins require a create tool.
A SimpleObject plug-in must not perform any scene related actions such as creating scene nodes or
building modifier stacks. It should basically only be adjusting its parameters in the mouse tool
handlers and constructing a mesh in the buildMesh handler. Attempting to create scene nodes or
applying modifiers in a SimpleObject plug-in will cause all kinds off strange interactions with the
in-progress scene node creation.
A SimpleObject plug-in has a predefined local variable mesh. This variable contains the underlying
mesh of the object being created. The mesh local variable is accessible in any of the plug-in’s
handlers, but is typically only built in the buildMesh handler. You can either modify the existing
TriMesh value in place, using the TriMesh methods, or construct a new TriMesh value and assign it
to the mesh plug-in local variable. The TriMesh methods and properties are described in the Editable
Mesh (p. 1041) topic.
Script:
plugin simpleObject tower_plugin_def
name:”Tower”
classID:#(145345,543211)
category:”Scripted Primitives”
( parameters main rollout:params
( height type:#worldUnits ui:height default:0
width type:#worldUnits ui:width default:0
depth type:#worldUnits ui:depth default:0
)
--
rollout params “Two Faces Parameters”
 Scripted SimpleObject Plug-ins 1557

( spinner height “Height” type:#worldunits range:[-1000,1000,0]

spinner width “Width” type:#worldunits range:[-1000,1000,0]
spinner depth “Depth” type:#worldunits range:[-1000,1000,0]
)
--
on buildMesh do
( setMesh mesh \
verts:#([0,0,0],[width,0,0],[width,depth,0],[0,depth,0]) \
faces:#([3,2,1], [1,4,3])
extrudeFace mesh #(1,2) (height * 0.5) 40 dir:#common
extrudeFace mesh #(1,2) (height * 0.5) 50 dir:#common
)
--
tool create
( on mousePoint click do
case click of
( 1: nodeTM.translation = gridPoint
3: #stop
)
on mouseMove click do
case click of
( 2: (width = gridDist.x; depth = gridDist.y)
3: height = gridDist.z
)
)
)

In this script a new primitive called Tower is defined. It constructs a (very) simple tower form; the
first drag sets the base and the second drag sets the height. It contains three animatable rollout
parameters, height, width and depth, that set the object’s basic bounds. The key components here
are the create tool and the on buildMesh handler and they work together in a fairly simple way.
The create tool sets the values of the parameters and the on buildMesh handler constructs a mesh
based on those parameter values.
The create tool can also access and set the position of the node that is being created to contain the
new object through the Matrix3 value in the pre-defined mouse tool local variable nodeTM. In this
case, the position portion of the node’s TM is set to the initial mouse down world position. The on
mouseMove handler sets the width and depth during click 2 and the height during click 3.
The on buildMesh handler constructs the desired mesh in the TriMesh value in the pre-defined
plug-in local variable mesh. Typically, it does this by building the mesh from scratch each time the
handler is called. In the example above, the mesh is initially set to a simple, two-face rectangular
plane (via setMesh()) and then the 2 faces are extruded up and scaled-down twice to get the
simple tower.
The mesh plug-in local variable is accessible in any of the plug-in’s handlers, but is typically only
built in the on buildMesh handler. You can either modify the existing TriMesh value in place using
the TriMesh methods, or construct a new TriMesh value and assign it to the mesh plug-in local
variable. The TriMesh created must be valid or a 3ds max crash may occur. All face, vertex, material
ID, and texture vertex arrays allocated must be filled in the handler.
1558 Chapter 12 | Creating MAXScript Tools

There are three additional event handlers that may be implemented for a scripted SimpleObject:
on OKtoDisplay do <boolean_expr>
If the OKtoDisplay event handler is implemented, <boolean_expr> should return true
or false depending on whether it is OK to display the current mesh. This is useful in
situations where a mesh might be in some degenerate state for particular parameter
settings and so should not be displayed in the viewports. The default implementation is
true. Note, empty meshes are OK to display.
on hasUVW do <boolean_expr>
If the hasUVW event handler is implemented, <boolean_expr> should return true or
false depending on whether UVW coordinates are present on the mesh. In many
primitive objects, a Generate Mapping Coords checkbox is provided for the user to control
UVW coordinate generation and the hasUVW handler expression would return the state of
this checkbox. The default implementation returns true or false depending on whether
the mesh has texture vertices present or not. At present, only a single map channel is
supported.
on setGenUVW <onOff> do <expr>
The setGenUVW event handler is called when 3ds max wants the plug-in to automatically
generate mapping coordinates, as happens when you first render an object that has a
material applied, but not mapping coordinates. It is called with a switch argument
<onOff> which is true or false to turn on or off the mapping coordinates. If your plug-
in is managing mapping coordinates, it should implement this handler and generate
mapping coordinates when called with a true argument. For example:
on setGenUVW onOff do
(
genMapCoords = onOff
if genMapCoords and gen_mapping_coords()
)

where gen_mapping_coords() is a function that applies mapping coordinates to the

mesh, returning true if the mapping was successful, false if not.
Here’s another example that creates a mesh by first building other temporary objects and using mesh
booleans to build the final mesh:
Script:
plugin simpleObject squareTube
name:”SquareTube”
classID:#(63445,55332)
category:”Scripted Primitives”
( local box1, box2
--
parameters main rollout:params
( length type:#worldUnits ui:length default:1E-3
width type:#worldUnits ui:width default:1E-3
height type:#worldUnits ui:height default:1E-3
)
--
 Scripted SimpleObject Plug-ins 1559

rollout params “SquareTube”

( spinner height “Height” type:#worldUnits range:[1E-3,1E9,1E-3]
spinner width “Width” type:#worldUnits range:[1E-3,1E9,1E-3]
spinner length “Length” type:#worldUnits range:[-1E9,1E9,1E-3]
)
--
on buildMesh do
( if box1 == undefined then
(box1 = createInstance box; box2 = createInstance box)
box1.height = height; box2.height = height
box1.width = width; box2.width = width * 2
box1.length = length; box2.length = length * 2
mesh = box2.mesh - box1.mesh
)
--
tool create
( on mousePoint click do
case click of
( 1: nodeTM.translation = gridPoint
3: #stop
)
on mouseMove click do
case click of
( 2: (width = abs gridDist.x; length = abs gridDist.y)
3: height = gridDist.z
)
)
)

In this example, the parameters and rollouts are handled in a similar manner to the first example,
but the buildMesh handler generates the mesh in an indirect way. The final object is in the form of
a rectangular pipe, a box with a box hole through the middle. Two plug-in locals (box1 and box2)
are made to contain Box base objects whose size parameters are set according to the plug-in’s
parameters, box2 is the outer box, box1 is the hole. The final mesh is made by boolean subtraction
of box1 from box2. In this case, a separate new mesh is created and assigned to the mesh plug-in
local variable, in contrast to the first example which modified the object’s original mesh directly.
Either technique is OK.
The createInstance() method is used to directly create the box base objects. This method creates
the geometry associated with the specified object, but does not create a node. This method is used
since SimpleObject plug-in must not perform any scene related actions such as creating scene nodes
or building modifier stacks.
1560 Chapter 12 | Creating MAXScript Tools

See also
Updating Scripted Plug-ins (p. 1553)
Scripted Plug-in Methods (p. 1551)
Scripted Plug-in Clauses (p. 1542)
Scripted Plug-ins (p. 1538)
Scripted Mouse Tools (p. 1531)

Scripted Shape Plug-ins

Scripted Shape plug-ins can only extend existing Shape plug-ins. A scripted Shape plug-in is declared
by specifying the <superclass> as shape. If a create tool is specified, it will override the
delegate’s create tool.
Script:
plugin shape Extended_Rect
name:”Rectangle2”
classID:#(0x133067, 0x54375)
extends:rectangle version:1
category:”Splines”
( fn fmax val1 val2 = if val1 > val2 then val1 else val2
tool create
( local startPoint
on mousePoint click do
case click of
( 1: startPoint = nodeTM.translation = gridPoint
3: #stop
)
--
on mouseMove click do
case click of
( 2: ( delegate.width= abs gridDist.x
delegate.length= abs gridDist.y
nodeTM.translation = startpoint + gridDist/2.
)
3: delegate.corner_radius = fmax 0 -gridDist.x
)
)
)

See also
Updating Scripted Plug-ins (p. 1553)
Scripted Plug-in Methods (p. 1551)
Scripted Plug-in Clauses (p. 1542)
Scripted Plug-ins (p. 1538)
Scripted Mouse Tools (p. 1531)
 Scripted Light Plug-ins 1561

Scripted Light Plug-ins

Scripted Light plug-ins can only extend existing Light plug-ins. A scripted Light plug-in is declared
by specifying the <superclass> as light. If a create tool is specified, it will override the
delegate’s create tool. Current limitations prevent certain plug-ins from being extended, in
particular those with custom creation managers. These include target light plug-ins. You can tell if
a plug-in is not extendable if your new rollouts do not appear.
An example of a scripted Light plug-in is shown in the Three Lights example in the Scripted Plug-in
Methods (p. 1551) topic.

See also
Updating Scripted Plug-ins (p. 1553)
Scripted Plug-in Methods (p. 1551)
Scripted Plug-in Clauses (p. 1542)
Scripted Plug-ins (p. 1538)
Scripted Mouse Tools (p. 1531)

Scripted Helper Plug-ins

Scripted Helper plug-ins can only extend existing Helper plug-ins. A scripted Helper plug-in is
declared by specifying the <superclass> as helper. If a create tool is specified, it will override
the delegate’s create tool.
An example of a scripted Helper plug-in is shown in the Three Lights example in the Scripted Plug-in
Methods (p. 1551) topic.

See also
Updating Scripted Plug-ins (p. 1553)
Scripted Plug-in Methods (p. 1551)
Scripted Plug-in Clauses (p. 1542)
Scripted Plug-ins (p. 1538)
Scripted Mouse Tools (p. 1531)
1562 Chapter 12 | Creating MAXScript Tools

Scripted Modifier Plug-ins

Scripted Modifier plug-ins can only extend existing Modifier plug-ins. A scripted Modifier plug-in is
declared by specifying the <superclass> as modifier.
The Modify panel actually creates a fresh instance of every modifier when it is to be shown in the
More... list or the buttons in the Modifiers rollout. This will cause the create handler to be called
for a scripted Modifier plug-in. No special handling in the create handler is required for this case.
Script:
plugin modifier myMod
name:”Supa Mod”
classID:#(685325,452281)
extends:Bend replaceUI:true version:1
( parameters main rollout:params
( bendamt type:#float animatable:true ui:bendamt default:0.0
on bendamt set val do delegate.angle = val
)
--
rollout params “SupaCheka Parameters”
( spinner bendamt “Bendiness: “
)
)

Script:
plugin modifier NSpline
name:”Normal. Spline”
classID:#(0x133067, 0x54374)
extends:normalize_spline
replaceUI:true version:1
( parameters main rollout:params
( seglen type:#float animatable:true ui:seglen default:20
on seglen set val do delegate.length = val
)
--
rollout params “Parameters”
( spinner seglen “Seg Length: “ range:[0.01,1e9,20]
)
)

See also
Updating Scripted Plug-ins (p. 1553)
Scripted Plug-in Methods (p. 1551)
Scripted Plug-in Clauses (p. 1542)
Scripted Plug-ins (p. 1538)
Scripted Mouse Tools (p. 1531)
 Scripted SimpleMod Plug-ins 1563

Scripted SimpleMod Plug-ins

A SimpleMod plug-in is a deformation-type modifier that moves vertices around but does not
change topology (adding or deleting vertices, faces, surfaces, lines, etc.) Examples of similar 3ds max
modifiers are Bend, Stretch, and Taper. These kinds of modifiers require only a single map handler to
be provided for moving vertices around and they automatically supply 3D box deformation gizmo
and center sub-objects. A scripted Modifier plug-in is declared by specifying the <superclass> as
modifier.
Script:
plugin simpleMod saddle
name:”SaddleDeform”
classID:#(685325,452281)
version:1
( parameters main rollout:params
( amount type:#integer ui:amtSpin default:20
)
--
rollout params “Saddle Parameters”
( spinner amtSpin “Amount: “ type:#integer range:[0,1000,20]
)
--
on map i p do
( p.z += amount * sin((p.x * 22.5/extent.x) * (p.y * 22.5/extent.y))
p
)
)

This script defines a new SimpleMod plug-in named SaddleDeform. It applies a saddle-type
deformation to an object, curving up 2 opposite corners and curving down the other two opposite
corners (try it on a plane object to see this best). There is a single parameter spinner, amount that
specifies how much deformation to apply. The key component of a SimpleMod plug-in is the map
handler. Its form is:
on map <index> <point> do <expr>

This event handler is called once for every point in the object (or current point selection in the
object) being modified. These points may be mesh vertices, spline vertices, NURBS CVs, and so on.
The <index> argument gives the number of the point, but this index may not correspond to a
vertex number in a mesh or a spline. The <point> argument supplied to the map handler gives the
current object-space coordinates of the point as a Point3. The function should modify the supplied
point value as appropriate and return it as the result of the map handler call. In the example above,
the map handler applies a Z-coordinate deformation, using the equation z = sin(x * y), so that
all the points retain their X and Y coordinates and the Z is moved up or down so as to follow the
saddle function. Note that all coordinates are object-local.
The <index> value is 1-based, however the scripted plug-in is called with a <index> value of 0 to
signal that this particular map call is being used by the gizmo bounding box drawing code to
compute points in the gizmo box to draw. This occurs hit testing is performed on the object the
1564 Chapter 12 | Creating MAXScript Tools

SimpleMod modifier is applied to and the gizmo bounding box is displayed. This will be the case if
the object is selected, the Modifier panel is active, and the SimpleMod modifier is selected in the
object’s modifier stack.
It is basically up to the object being modified to decide what index value to pass. For meshes, for
example, it is the actual mesh vertex index. For patches, it is the control points first all in one
sequence, followed by the in and out vectors for each control point in control point order. For
splines, it is control point, in vector, out vector in control point sequence within the curve sequence.
This ordering may change in future versions of 3ds max.
Since the map handler can be called many times, even on simple objects, it is highly recommended
that you minimize the number of values that are created in the map handler. This will reduce the
need for garbage collection to be run. If you need several local variables in the map handler, it is
recommended that you declare one or more Point2 or Point3 values in the scripted plug-in
definition, and then store values to the component values of the Point2 or Point3 values. This will
prevent new local variables from being allocated in the map handler.
You should not try to access the object being modified from within the map handler as this will
attempt to evaluate the scripted modifier again. This will result in an infinite loop and hang
3ds max.
There are also three pre-defined plug-in locals you can access in the map handler, as follows:
min -- the modifier context’s bounding box min coordinate
max -- the modifier context’s bounding box max coordinate
center -- the modifier context’s bounding box center coordinate
extent -- the modifier context’s bounding box extent or size

In the example above, the map handler use the extent pre-defined local variable to compute a
scaling for the saddle function, so that it gets a 1/8th cycle of the function (22.5 degrees) across the
whole object. These bounding box locals relate to the modifier’s context, either the whole object or
group of objects if applied to a scene node selection, or sub-object selection if there is a sub-object
selection modifier below it on the stack (such as a Mesh Select).
You can also use some other built-in capabilities of SimpleMod to implement modifier limits as in
Bend and Taper. To do this, implement handlers for the following (you must implement all if you
implement any):
on modLimitZMin do <expr>
on modLimitZMax do <expr>
on modLimitAxis do <expr>

If called, the on modLimitZMin and on modLimitZMax handler expressions must evaluate to float
values corresponding to the minimum and maximum limits and the on modLimitAxis handler
expression must return #x, #y or #z to specify the limit axis. The MAXScript global variable
currentTime contains the time at which these values should be computed, although, normally,
simple access to parameter values will yield the correct currentTime value automatically. The
simplest way to implement these handlers is to maintain limit parameters and associated spinners
and checkboxes, and simply pass these parameter values back.
 Scripted Material Plug-ins 1565

The Modify panel actually creates a fresh instance of every modifier when it is to be shown in the
More... list or the buttons in the Modifiers rollout. This will cause the create handler to be called
for a scripted SimpleMod plug-in. No special handling in the create handler is required for this
case.

See also
Updating Scripted Plug-ins (p. 1553)
Scripted Plug-in Methods (p. 1551)
Scripted Plug-in Clauses (p. 1542)
Scripted Plug-ins (p. 1538)
Scripted Mouse Tools (p. 1531)

Scripted Material Plug-ins

Scripted Material plug-ins can only extend existing Material plug-ins. A scriptable Material plug-in
is declared by specifying the <superclass> as material.
A scripted Material plug-in must have at least one rollout defined.
In a scripted Material plug-in, Material and Map buttons that are associated with a parameter in a
parameter block do not call the button’s picked event handler. Instead, you should link the button
to a parameter in a parameter block, and use the set handler for the parameter.
Script:
-- this is a level 3 plug-in, the beginnings of a custom glass material.
-- It extends Standard material and replaces its UI with a single
-- rollout with 2 spinners and a color picker
plugin material myGlass
name:”Supa Glass”
classID:#(695425,446581)
extends:Standard replaceUI:true version:1
( parameters main rollout:params
( trans type:#float default:27 ui:trans
refrac type:#float default:1.5 ui:refrac
col type:#color default:blue ui:col
--
on trans set val do delegate.opacity = val
on refrac set val do delegate.ior = val
on col set val do delegate.diffuse_color = val
)
--
rollout params “Glass Parameters”
( spinner trans “Transparency: “ fieldwidth:45 offset:[-90,0]
spinner refrac “Index of Refraction: “ fieldwidth:45 offset:[-90,0]
colorpicker col “Base color: “ align:#center
)
--
on create do
1566 Chapter 12 | Creating MAXScript Tools

( -- setup initial material

delegate.opacityFalloff = 75
)
)

See also
Updating Scripted Plug-ins (p. 1553)
Scripted Plug-in Methods (p. 1551)
Scripted Plug-in Clauses (p. 1542)
Scripted Plug-ins (p. 1538)
Scripted Mouse Tools (p. 1531)

Scripted TextureMap Plug-ins

Scripted TextureMap plug-ins can only extend existing TextureMap plug-ins. A scriptable
TextureMap plug-in is declared by specifying the <superclass> as textureMap.
A scripted TextureMap plug-in must have at least one rollout defined.
In a scripted TextureMap plug-in, Material and Map buttons that are associated with a parameter in
a parameter block do not call the button’s picked event handler. Instead, you should link the
button to a parameter in a parameter block, and use the set handler for the parameter.

See also
Updating Scripted Plug-ins (p. 1553)
Scripted Plug-in Methods (p. 1551)
Scripted Plug-in Clauses (p. 1542)
Scripted Plug-ins (p. 1538)
Scripted Mouse Tools (p. 1531)

Scripted RenderEffect Plug-ins

A scriptable RenderEffect plug-in can be declared by specifying the <superclass> as
RenderEffect and by declaring an apply event handler. When declared, the render effect can be
seen in Render Effects > Add dialog.
on apply <bitmap> do <expr>
When the scripted effect is added as one of the rendering effects and “Update Scene” or
“Update Effect” buttons are pressed, the apply event handler is called and passed a bitmap
which can be modified with any changes the render effect wants to make. The bitmap you
are given is the current rendered image that has had all of the prior effects in the render
effects list applied to it. You modify this bitmap in place, typically by using the
 Scripted RenderEffect Plug-ins 1567

getPixel() and setPixel() functions. This modified bitmap is then passed onto the
next render effect in the list or to the render output if it is the last effect.
To allow scripted Effects to take advantage of the g-buffer channel access, the following handlers are
present:
on channelsRequired do <expr>
The handler expression must evaluate to an array of the g-buffer channel names that are
required. The g-buffer channel names are:
#zDepth
#matID
#objectID
#UVCoords
#normal
#unClamped
#coverage
#node
#shaderColor
#shaderTransparency
#velocity
#weight

on preApply <bitmap> do <expr>

The preApply handler allows the scripted effect to analyze the incoming render bitmap
and its channels in order to precondition the delegate’s effect processing.
So, you might add an on channelsRequired do to add #node and #coverage channels to the
renderer’s bitmap, and an on preApply bm do to get the #node channel out as a mask and then
set it into a delegate’s mask parameter to limit an effect to a given object.
You cannot call render() in a scriptable RenderEffect plug-in, as this would cause the RenderEffect
to be recursively called.
Here’s a simple example that extends the Blur effect to add another rollout that has a node picker
button. If you pick a node it generates a channel mask and uses that to limit the blur to that object:
Script:
plugin RenderEffect myBlurFX
name:”Super Blur FX”
classID:#(6545,456581)
extends:Blur
version:1
( local tx = bitmaptexture (), cm, g_channels = #(#node, #coverage)
rollout params “SupaFX Parameters”
( label nn align:#center
pickbutton nodepick “Pick Node”
)
--
parameters main rollout:params
( thenode type:#node ui:nodepick
on thenode set nd do
params.nn.text = if nd == undefined then ““ else nd.name
1568 Chapter 12 | Creating MAXScript Tools

)
--
on channelsRequired do g_channels
--
on preApply map do if theNode != undefined then
( if cm == undefined then
( cm = getChannelAsMask map #node node:theNode \
fileName:(scriptsPath + “__fxtmp.bmp”)
save cm
tx.bitmap = cm
)
else
getChannelAsMask map #node node:theNode to:cm
)
--
on create do
( delegate.selMaskActive = true
delegate.selImageActive = false
delegate.selMaskMap = tx
)
)

Script:
plugin renderEffect myColorBalanceFx
name:”Super Color Balance FX”
classID:#(64425,45761)
extends:Color_Balance version:1
( parameters main rollout:params
( redness type:#integer animatable:true ui:redness default:0.0
on redness set val do delegate.red = val
)
--
rollout params “Super Color Balance Parameters”
( spinner redness “Redness: “ type:#integer range:[-100,100,0]
)
)

Script:
plugin renderEffect Negative
name:”Negative”
classID:#(0xb7aa794c, 0xc3bd78ab)
( parameters main rollout:params
( Color type:#color default:blue ui:Color
)
--
rollout params “Negative Parameters”
( colorpicker Color “Base color: “ align:#center
)
--
on apply bmp do
( for h=0 to (bmp.height-1) do
 Scripted Atmospheric Plug-ins 1569

( local sline = getPixels bmp [0,h] bmp.width

for i=1 to sline.count do sline[i] = Color - sline[i]
setPixels bmp [0,h] sline
)
)
)

See also
Updating Scripted Plug-ins (p. 1553)
Scripted Plug-in Methods (p. 1551)
Scripted Plug-in Clauses (p. 1542)
Scripted Plug-ins (p. 1538)
Scripted Mouse Tools (p. 1531)

Scripted Atmospheric Plug-ins

Scripted Atmospheric plug-ins can only extend existing Atmospheric plug-ins. A scriptable
Atmospheric plug-in is declared by specifying the <superclass> as atmospheric.
Script:
plugin atmospheric myFogEnv
name:”Super Fog Env”
classID:#(64433,27761)
extends:Fog version:1 replaceUI:true
( parameters main rollout:params
( fogcol type:#color animatable:true ui:col
on fogcol set val do delegate.fog_color = val
)
--
rollout params “Super Fog Parameters”
( colorpicker col “Fog Color”
)
--
on create do delegate.fog_type = 1
)

See also
Updating Scripted Plug-ins (p. 1553)
Scripted Plug-in Methods (p. 1551)
Scripted Plug-in Clauses (p. 1542)
Scripted Plug-ins (p. 1538)
Scripted Mouse Tools (p. 1531)
1570 Chapter 12 | Creating MAXScript Tools
Chapter 13: Interacting with the 3ds max User Interface

Command Panels
The following methods are used to get or set which command panel is active:
setCommandPanelTaskMode mode:<panel_name>
Sets the specified command panel as active. The valid panel_name values are:
#create -- Create Panel
#modify -- Modify Panel
#hierarchy -- Hierarchy Panel
#motion -- Motion Panel
#display -- Display Panel
#utility -- Utility Panel

getCommandPanelTaskMode()
Returns the current command panel as a name value. The name values correspond to the
panel_name values for SetCommandPanelTaskMode().
The following 3ds max system global variables are associated with the command panel:
cui.commandPanelOpen
Lets you get and set whether the command panel is displayed. A Boolean value - true if
the command panel is displayed, false if not displayed. This global variable is not
available in 3ds max.
Specific methods and 3ds max global variables are associated with the Create and Modify panels.
These methods and global variables are described in the following topics:
Create Panel (p. 1572)
Modify Panel (p. 1572)
1572 Chapter 13 | Interacting with the 3ds max User Interface

Create Panel
The startObjectCreation() method is used to simulate the user finding a Create Panel button
for a given object class and pressing that button, putting 3ds max into create mode for that object
class. The form is:
startObjectCreation <scene_object_class>

For example:
startObjectCreation box
startObjectCreation targetSpot

This method simply opens up the Create Panel at the right tab and category and depresses the
appropriate object button.
This method is primarily intended for use in macroScripts, but can be used in generalized scripts.
Script execution will continue immediately after entering the create mode, and you must ensure that
the script does not interfere with the object creation.

Modify Panel
The following methods are associated with the Modify panel:
enableShowEndRes <boolean>
If the boolean parameter is true, allows the Show End Result On/Off Toggle icon to
remain pressed in. If false, the Show End Result On/Off Toggle icon will return to the off
state after being pressed. This method must be used in true/false pairs, as its effect is
“sticky” when selecting other objects or modifiers, or when switching away from and back
to the Modify panel.
IsSubSelEnabled()
Returns true if the user is allowed to enter Sub-Object mode, false otherwise.
enableSubObjSel <boolean>
If the boolean parameter is true, allows the user to enter Sub-Object mode for those
objects/modifiers that have Sub-Object modes defined. If false, the Sub-Object button is
disabled. This method must be used in true/false pairs, as its effect is “sticky” when
selecting other objects or modifiers, or when switching away from and back to the Modify
panel.
modPanel.addModToSelection <modifier>
Applies a modifier to the current selection opened in the Modify panel. It should be used
in place of addModifier() in places where the target is a selection or group or where you
have the stack open at a particular place in the Modify panel with a sub-object selection
active and you want the modifier applied to that selection. addModifier() adds the
modifier separately to each object in the selection or group and does not honor the
current active sub-object selection in all cases. The Modify panel must be open on the
selection you want to apply the modifier to, otherwise the function does nothing.
 Modify Panel 1573

modPanel.getCurrentObject()
Returns the modifier or base object currently selected in the Modify panel stack. If the
Modify panel is not open, this function returns undefined.
modPanel.getModifierIndex <node> <modifier>
Returns the index of the given modifier in the modifier stack for the given node. This
index corresponds to the modifiers position in the <node>.modifiers array. This
function returns undefined if the given modifier is not in the node’s modifier stack.
modPanel.setCurrentObject < modifier | node | node_baseobject >
Sets the specified object in the current modifier stack to be the active object in the
modifier stack. The Modify panel must be open on the object containing the modifier or
base object to be selected, otherwise the function does nothing.
Examples:
modPanel.addModToSelection (bend()) -- apply bend modifier to current
selection
modPanel.getModifierIndex $ foo -- returns index of modifier foo
modPanel.setCurrentObject $ -- open on base object
modPanel.setCurrentObject $.baseObject -- same as above
modPanel.setCurrentObject $.taper -- open on taper modifier in object
modPanel.setCurrentObject $.modifiers[3] -- open on 3rd modifier
modPanel.setCurrentObject foo -- open on foo object or modifier

The following 3ds max system global variables are associated with the Modify panel:
numSubObjectLevels
Lets you get the number of sub-object levels supported by the object or modifier currently
selected in the modifier stack. If the Modify panel is not open or no objects are selected,
the global contains the value undefined.
subObjectLevel
Lets you get and set the sub-object level in the Modify panel if it is open. An Integer value
of zero or greater up to the number of sub-object levels supported by the currently open
modifier, typically in the order shown in the Sub-Object drop-down list. A subObjectLevel
of 0 means sub-object mode is off. If the Modify panel is not open or sub-object level
setting not permitted in the current modifier, the global contains the value undefined.
For example:
b=box() -- create a box
em=edit_mesh() -- create an Edit Mesh modifier
addModifier $box01 em -- add edit mesh mod
max modify mode -- open mod panel
select $box01 -- select object box01
print subObjectLevel -- print the current subobject level
subObjectLevel = 2 -- set sub-object level to Edge

showEndResult
Lets you get and set the state of the Show End Result Toggle icon in the Modify panel. A
Boolean Value – true if Show End Result is on, false if off.
1574 Chapter 13 | Interacting with the 3ds max User Interface

Main Toolbar
The following methods are associated with 3ds max’s main toolbar:
enableUndo <boolean>
Enables or disables the Undo icon.
hitByNameDlg()
Opens the standard 3ds max Select By Name dialog allowing users to select objects.
Returns false if the user cancels out of the Select by Name dialog, true otherwise.
toolMode.uniformScale()
Set scale mode to Uniform Scale.
toolMode.nonUniformScale()
Set scale mode to Non-uniform Scale.
toolMode.squashScale()
Set scale mode to Squash.
enableRefCoordSys <boolean>
Enables or disables the Reference Coordinate System drop-down list.
toolMode.coordsys <mode_name>
Sets the Reference Coordinate System. Valid <mode_name> values are:
#view
#screen
#world
#parent
#local
#grid

getRefCoordSys()
setRefCoordSys <mode_name>
Get and set the Reference Coordinate System. Valid <mode_name> values are:
#hybrid -- View
#screen -- Screen
#world -- World
#parent -- Parent
#local -- Local
#object -- Pick object or Grid – not valid for setRefCoordSys()

enableCoordCenter <boolean>
Enables or disables the Coordinate System Center icon.
getCoordCenter()
setCoordCenter <name>
Get and set the Coordinate System Center. Valid <name> values are:
#local -- Use Pivot Point Center
#selection -- Use Selection Center
#system -- Use Transform Coordinate Center
 Modify Panel 1575

toolMode.transformCenter()
Sets Coordinate System Center to Transform Coordinate System.
toolMode.selectionCenter()
Sets Coordinate System Center to Selection Center.
toolMode.pivotCenter()
Sets Coordinate System Center to Pivot Point Center.
getNumAxis()
This method reflects the Coordinate System Center state. If it is set to Pivot Point Center
then this method returns #individual otherwise #all.
setToolBtnState <name> <boolean>
Set the specified tool buttons on or off. This method does not put into the mode, it just
changes the state of the tool button. This method does not change the state of any button
other than the specified button. The valid <name> values are:
#move -- Move button on/off
#rotate -- Rotate button on/off
#nuscale -- Scale button on/off – doesn’t change scale type
#uscale -- Scale button on/off – doesn’t change scale type
#squash -- Scale button on/off – doesn’t change scale type
#select -- Select button on/off

getToolbtnState <name>
Returns whether the specified tool button is on or off as a <boolean> value. Valid name
values are:
#select
#move
#rotate
#uscale-- returns true if any of the scale button states is on
#nuscale-- returns true if any of the scale button states is on
#squash-- returns true if any of the scale button states is on

The following methods deal with the Named Selection Set drop-down list. These methods are not
intended for casual usage.
clearCurSelSet()
Clears the edit field of the Named Selection Set drop-down list. Does not deselect the
currently selected objects.
clearSubSelSets()
Clears the named selections from the Named Selection Set drop-down list. The named
selection sets still exist, they just don’t show in the drop-down list. This command can be
dangerous to use unless you are in Sub-Object mode in the Modify panel, as there is not a
direct method to rebuild the Named Selection Set list. When in Sub-Object mode in the
Modify panel, the namedSelSetListChanged() method will rebuild the list.
namedSelSetListChanged()
When in Sub-Object mode in the Modify panel, this method will rebuild the named
selection set list.
1576 Chapter 13 | Interacting with the 3ds max User Interface

setCurNamedSelSet <string>
Sets the edit field of the Named Selection Set drop-down list to the specified string. This
method not change the current selection set or add the specified string to the named
selection set list.
appendSubSelSet <string>
Appends the specified string to the Named Selection Set drop-down list. This method not
change the current selection set. Modifiers in 3ds max use this method to add sub-object
named selection sets to the Named Selection Set drop-down list. This is done whenever the
selection level changes.
The following 3ds max system global variables are associated with the main toolbar:
preferences.constantReferenceSystem
Lets you get and set whether to use a constant Reference System for the Move, Rotate, and
Scale tools. A Boolean value - true if Constant is on, false if off. This variable matches
the Constant check box in Customize menu > Preferences > General > Reference
Coordinate System.
toolmode.commandmode
Get/set the 3ds max command mode. The return value when getting the command mode
is a <name> value if the command mode is a recognized command mode, otherwise the
return value is an integer value. The recognized command modes are:
#SELECT
#MOVE
#ROTATE
#NUSCALE
#USCALE
#SQUASH
#VIEWPORT
#HIERARCHY
#CREATE
#MODIFY
#MOTION
#ANIMATION
#CAMERA
#NULL
#DISPLAY
#SPOTLIGHT
#PICK

When setting the 3ds max command mode, only the following command modes are valid:
#SELECT
#MOVE
#ROTATE
#NUSCALE
#USCALE
#SQUASH
 Prompt Line 1577

toolmode.axisConstraints
Get/set the 3ds max axis constraints. The axis constraints values are:
#X
#Y
#Z
#XY
#YZ
#ZX

Status Bar
The methods and 3ds max global variables associated with 3ds max’s Status Bar are described in the
following topics:
Prompt Line (p. 1577)
Coordinate Display (p. 1578)
Progress Bar Display (p. 1578)
Status Bar Buttons (p. 1579)

Prompt Line
The following methods are associated with 3ds max’s Status Bar Prompt Line:
displayTempPrompt <string> <milliseconds_integer>
Displays the specified string on the Prompt Line for the specified number of milliseconds.
After the time elapses, the string is popped from the stack. This may be used to put up a
temporary error message for example. Control is returned to MAXScript immediately after
the call, that is, MAXScript execution continues even while the temporary prompt is
displayed.
removeTempPrompt()
Removes the temporary prompt immediately.
replacePrompt()
Replaces the string on the top of the prompt stack.
pushPrompt <string>
Pushes the currently displayed prompt onto the prompt stack, and displays the specified
string as the prompt.
popPrompt()
Pops the currently displayed prompt off the prompt stack. The previous prompt will be
restored.
1578 Chapter 13 | Interacting with the 3ds max User Interface

Coordinate Display
The following methods are associated with 3ds max’s Status Bar Coordinate Display:
disableStatusXYZ()
Disables mouse tracking and display of coordinates to the X, Y, Z status boxes.
enableStatusXYZ()
Enables mouse tracking and display of coordinates to the X, Y, Z status boxes.
setStatusXYZ <format_name> <point3>
Displays the component values of the Point3 value in the X, Y, Z status boxes. The format
of the displayed values is controlled by format_name. The valid format_name types are:
#universe
display point3 as position in current units
#scale
display point3 as percentages – a point3 component value of 1 displays as 100%
#angle
display point3 as angles – point3 component values are in radians
#other
display point3 as straight floating point values.
Note: Using a <format_name> value of #other for setStatusXYZ() does not correctly
display the specified point3 value. The X and Y component values are displayed in the Y
and Z status boxes, and the X status box is blank.

Progress Bar Display

This group of functions let you display a progress bar for operations that may be time consuming,
similar to the progress bar 3ds max uses for IK, Preview Rendering and Reduce Key computations.
The functions are:
progressStart “caption”
Initially displays the progress bar with the caption given.
progressUpdate <percent>
Updates the bar display to show the given percentage complete (in the range 0-100). This
function also checks to see if the user has clicked the Cancel button in the progress bar and
returns true if the computation should continue and false if the user has requested a
cancel. You can also call getProgressCancel(), described below, to check the cancel
status, which is a low overhead function and so may be called more frequently than
progressUpdate().
progressEnd()
Signals the end of the operation and removes the progress bar display.
 Status Bar Buttons 1579

getProgressCancel()
A low-overhead function that checks whether the user has canceled the operation via the
Cancel button in the progress bar. You may want to call this function frequently within
deep loops in your code to reduce cancel latency for the user, because you should only call
progressUpdate() as needed to show significant progress bar changes to keep overhead
low. The getProgressCancel() function, as well as progressUpdate(), displays a
confirmation dialog if the use hits the cancel button and returns the cancel status from
that confirmation. Unlike progressUpdate(), this function returns true if the user has
made a confirmed cancel request and false otherwise.
setProgressCancel <boolean>
Sets or clears the Cancel flag for the progress bar. By passing a value of true, the Cancel
flag is set and will be detected by progressUpdate() and getProgressCancel(). By
passing a value of false, the Cancel flag is cleared if set.
The following 3ds max system global variable is associated with the Progress Bar display:
escapeEnable
Lets you get and set a Boolean value defining whether ESC key interrupt detection is on or
off. Setting enableEscape to false turns ESC key interrupt detection off, setting it to
true turns it on again. This variable is useful when used in conjunction with a Progress
Bar. You can set enableEscape to false when you don’t want the user to be able to
interrupt a script running a long computation and you have set up a progress bar with its
own Cancel button.

Status Bar Buttons

The following methods are associated with the buttons in 3ds max’s Status Bar:
getCrossing()
Returns whether Crossing Selection (true) or Window Selection (false) is set.
getPluginKeysEnabled()
setPluginKeysEnabled <boolean>
Get and set whether Plug-in Keyboard Shortcuts are enabled (true) or disabled (false).
getSnapState()
Returns the Snap toggle state - on (true) or off (false).
getSnapMode()
Returns the current snap type as a string – “ABSOLUTE” or “RELATIVE”.
isSelectionFrozen()
Returns true if the node selection is frozen, false if not frozen
freezeSelection()
Freezes the node selection
thawSelection()
Thaws the node selection.
1580 Chapter 13 | Interacting with the 3ds max User Interface

The following 3ds max system global variables are associated with the Status Bar buttons. These
global variables are not available in 3ds max.
snapMode.active
Lets you get and set a Boolean value defining the Snap toggle state - on (true) or off
(false). This global variable is not available in 3ds max.
snapMode.type
Lets you get and set a Name value defining whether 2D (#2D), 2.5D (#2_5D), or 3D (#3D) is
the current snap type. This global variable is not available in 3ds max.

Time Control
The following methods and 3ds max system global variables are associated with the 3ds max
Time Controls:
animButtonEnabled
A Boolean value that specifies whether the user can change the state of the Animate
button. If set to false, the user can not change the Animate button state. If set to true,
the user can change the Animate button state. A script can change the state of the Animate
button using animButtonState regardless of the animButtonEnabled value.
animButtonState
Lets you to get and set the state of the Animate button. A Boolean value - true if Animate
is on, false if Animate is off.
sliderTime
Lets you get and set a Time value that defines the time associated with the 3ds max
time slider.
Two functions are provided for starting and stopping the 3ds max animation playback, which are
essentially equivalent to pressing the Play button in the 3ds max user interface. The functions are:
playAnimation [ #selOnly ]
stopAnimation()

If you specify the optional argument, #selOnly, to playAnimation()only the currently selected
objects are animated.
There is an important restriction to understand when using these functions:
Calling playAnimation() is a thread-blocking call internally in 3ds max and does not return until
the playback is stopped by the user clicking the Stop Play button or another thread executing a
stopAnimation(). The only way to achieve the latter in MAXScript currently is to call
stopAnimation() from a scripted rollout panel handler such as a button press handler or from a
scripted controller script. If you invoke playAnimation() in code run from the Listener, you will
not be able to invoke stopAnimation() from the Listener, because the Listener is blocked inside
the playAnimation() call.
Also see the Time Configuration Dialog (p. 1616) topic for methods for setting options in the Time
Configuration dialog.
 Accessing Active Viewport Info, Type, and Transforms 1581

Trackbar
The following methods are associated with the Trackbar:
trackbar.getPreviousKeyTime()
gets the previous key time. If no previous key is present, returns undefined. For example:
at time sliderTime trackbar.getPreviousKeyTime()

trackbar.getNextKeyTime()
gets the next key time. If no next key is present, returns undefined.
The following 3ds max system global variables are associated with the Trackbar:
trackbar.filter Name
get and set the filter specifying which types of keys to show in the Trackbar. The valid
values are: #all, #TMOnly, #currentTM, #object, and #mat.
trackbar.visible Boolean
get and set whether the trackbar is visible - true if the trackbar is visible, false if invisible

Viewports

Accessing Active Viewport Info, Type, and Transforms

The following 3ds max system global variables are associated with the viewports:
viewport.activeViewport
Lets you get and set the index of the active viewport. If you change the currently active
viewport to a 2D view, this variable will contain the value 0.
viewport.numViews
Contains the number of 3D viewports in the current viewport layout. This variable is read-
only. This variable does not reflect any 2D (Track View, Schematic View, Listener, and so
on) views in the viewport layout. So, for example, if viewport.getLayout() returns
#layout_4 and this variable contains the value 2, you know that two of the viewports
contain 2D views. MAXScript currently does not allow you to access 2D view viewports.
The following methods are used to access active viewport information and transforms:
viewport.getLayout()
viewport.setLayout <view_layout_name>
Gets or sets the viewport layout, where <view_layout_name> specifies the viewport
layout configuration. When setting the layout, the view shown in each viewport is based
on the configuration set in Customize > Viewport Configuration > Layout. The list of valid
<view_layout_name> values below uses the following syntax:
# is the total number of viewports.
V = vertical split
H = horizontal split
L/R = left/right placement
T/B = top/bottom placement
1582 Chapter 13 | Interacting with the 3ds max User Interface

The valid <view_layout_name> values are:

#layout_1 -- 1 viewport
#layout_2v -- 2 viewports, vertical split, both same size
#layout_2h -- 2 viewports, horizontal split, both same size
#layout_2ht –- 2 viewports, horizontal split, top smaller
#layout_2hb -- 2 viewports, horizontal split, top larger
#layout_3vl –- 3 viewports, 2 on left, 1 on right
#layout_3vr -- 3 viewports, 1 on left, 2 on right
#layout_3ht -- 3 viewports, 2 on top, 1 on bottom
#layout_3hb -- 3 viewports, 1 on top, 2 on bottom
#layout_4 -- 4 viewports, all same size
#layout_4vl -- 4 viewports, 3 on left, 1 on right
#layout_4vr -- 4 viewports, 1 on left, 3 on right
#layout_4ht -- 4 viewports, 3 on top, 1 on bottom
#layout_4hb -- 4 viewports, 1 on top, 3 on bottom

viewport.getType()
viewport.setType <name>
Get and set the view type for the current viewport. Valid <name> values are:
#view_top -- Top
#view_bottom -- Bottom
#view_right -- Right
#view_left -- Left
#view_front -- Front
#view_back -- Back
#view_persp_user -- Perspective
#view_iso_user -- User
#view_camera -- Camera
#view_spot -- Light
#view_shape -- Shape
#view_track -- Track View
#view_grid -- Grid

Notes: If the current viewport is an extended viewport (that is, a Track View, Asset
Manager, or MAXScript Listener viewport), getType() will return undefined. If a
Camera or Light viewport is specified with setType(), and there is not exactly one
camera or light selected, a dialog will be displayed for the user to select the camera or light
to use.
viewport.setType returns a boolean - true if successful, false if not. Can also get a return
value of #view_none. If none of the viewports have focus, a value of false is returned from
viewport.getType.
 Accessing Active Viewport Info, Type, and Transforms 1583

Example:
viewport.setType #view_track -- no viewport is active after this command
viewport.getType() -– will return false

viewport.ResetAllViews()
This function will reset all viewports in Max to the default layout.
getActiveCamera()
viewport.getCamera()
Returns the camera node associated with the active view if any, undefined if none.
viewport.setCamera <camera_node>
Sets the active viewport to a Camera view, using the specified camera.
getViewTM()
viewport.getTM()
viewport.setTM <matrix3>
Get or set the active view screen-to-world transform matrix for non-orthographic
(perspective and isometric user views) viewports. This is the affine camera or viewport
matrix. setTM only operates on Perspective viewports, and returns a value of true if the
view transform matrix was successfully set, false otherwise.
The following function returns as a Ray value the “eye” location and direction for the active
viewport. The viewport needs to be a non-orthographic viewport.
Script:
fn getViewDirectionRay =
(
-- The affine TM transforms from world coords to view coords
-- so we need the inverse of this matrix
local coordSysTM = Inverse(getViewTM())
-- The Z axis of this matrix is the view direction.
local viewDir = -coordSysTM.row3
-- get the view position from this matrix
local viewPt = coordSysTM.row4
return ray viewPt viewDir
)

getViewFOV()
Returns the Field of View for the active viewport. If the viewport is an orthographic
viewport, a value of 57.2958 degrees (1 radian) is returned.
getViewSize()
Returns the active view size as point2 in pixels.
getScreenScaleFactor <point3>
Returns the active view scale factor, giving the width in world-space units at the point’s
distance from the view space origin.
mapScreenToWorldRay <pixel_coord_point2>
Returns a Ray value in world space through the given viewport pixel coordinates in the
current active view, and perpendicular to the viewport plane.
1584 Chapter 13 | Interacting with the 3ds max User Interface

mapScreenToView <pixel_coord_point2> <depth_float> \

[ <viewport_size_point2> ]
Returns a 3D point in the view coordinate space. Given a point in the active viewport
screen (in viewport pixel coordinates), and a depth in view coordinates, this method maps
the point into view coordinates. If <viewport_size_point2> is supplied, the specified
viewport size is used instead of the actual viewport size.
mapScreenToCP <pixel_coord_point2> [ <viewport_size_point2> ]
Maps viewport pixel coordinates in the current active view to the construction plane in
world coordinates. If <viewport_size_point2> is supplied, the specified viewport size is
used instead of the actual viewport size.
getCPTM()
Construction-plane-to-world transform matrix.
gw.nonScalingObjectSize()
The value returned from this method may be used as a scale factor that will counteract the
viewport zoom. For example, lights, cameras, and tape helper objects use this factor so the
size of the node in the scene remains constant when the viewport is zoomed in and out.
This value is affected by the ‘Non-Scaling Object Size’ spinner in the Viewport Preferences
dialog, so the user has some control over this as well.
gw.getPointOnCP <pixel_coord_point2>
Returns a point in world space on the current construction plane based on the specified
screen coordinate.
gw.getCPDisp <base_point3> <dir_point3> \
<start_pixel_coord_point2> <end_pixel_coord_point2>
This method returns a length in world space given a start screen point
(<start_pixel_coord_point2>), an end screen point (<end_pixel_coord_point2>),
a base point (<base_point3>) and a direction vector (<dir_point3>). For example,
when creating a cylinder, the user clicks the mouse down to define the center point of the
cylinder (base), then drags out a radius. They then drag out a height for the cylinder. This
method is used to return intermediate and final heights for the cylinder based on the
initial base point, the direction vector (the Z axis), the start mouse point, and the current
point the user is interactively adjusting.
gw.getVPWorldWidth <point3>
Returns the viewport screen width factor in world space at a point in world space.
gw.mapCPToWorld <point3>
Returns the corresponding world space point given a point on the construction plane. For
example, if you use gw.getPointOnCP() to convert a screen coordinate to a point on the
construction plane, you could then call this method to convert that point on the
construction plane to a world space point.
gw.IsPerspView()
Returns true if the active viewport is a perspective view; otherwise returns false.
gw.getFocalDist()
Returns the focal distance of an active perspective view.
 Accessing Active Viewport Info, Type, and Transforms 1585

gw.snapPoint <pixel_coord_point2> [ snapType:<snapType_name> ]

Given a 2D screen coordinate, this method returns a 3D point on the current construction
plane based on the current snap settings and the optional snapType parameter. The valid
<snapType_name> values are:
#in3d
Snap to all points.
#inPlane
Snap only to points on the construction plane.
#unSelObjs
Ignore selected nodes when considering snap points.
#selObjs
Ignore unselected nodes when considering snap points.
#unSelSubobj
Ignore selected sub-object geometry when considering snap points.
#selSubobj
Ignore unselected sub-object geometry when considering snap points.
#force3d
Override user settings to force snap in 3D.
gw.snapLength <length_float>
This method snaps the length to the nearest snap increment and returns the snapped
distance.
units.formatValue <float>
Returns a <string> value representing the <float> in the current unit scale. This method
can cause a string overflow, especially when the units are set to miles or kilometers. If an
overflow occurs a run-time error is thrown.
units.decodeValue <string>
Parses <string> using the current unit settings and returns a <float>. A run-time error is
thrown if an error occurs in the parsing of the string.
Refreshing the Viewports
The following methods force the viewports to redraw, or control when the viewports are redrawn.
redrawViews()
Causes the 3ds max viewports to be immediately redrawn in an optimal way, such that
only those parts of the view that have changed are redrawn. This is different from forcing
a redraw with the max view redraw command or one of the following methods which
redraw the entire scene in all views.
1586 Chapter 13 | Interacting with the 3ds max User Interface

completeRedraw()
forceCompleteRedraw [ doDisabled:<boolean> ]
Calling this method will cause all the viewports to be completely redrawn. This method
literally forces everything (every object, every screen rectangle, every view) to be marked
invalid and then the whole scene is regenerated. The individual object pipeline caches are
not flushed, however. This routine is guaranteed to be slow. If the optional doDisabled:
boolean argument for ForceCompleteRedraw is true, disabled viewports will also be
redrawn.
disableSceneRedraw()
Turns viewport scene redraw off (disables it). All calls to DisableSceneRedraw()/
EnableSceneRedraw() must be in pairs, since an internal counter is used in 3ds max to
actually do the redraw enable/disable action.
enableSceneRedraw()
Turns viewport scene redraw on (enables it). All calls to DisableSceneRedraw()/
EnableSceneRedraw() must be in pairs, since an internal counter is used in 3ds max to
actually do the redraw enable/disable action.
isSceneRedrawDisabled()
Returns true if scene redraw is disabled, false if it is enabled.
nodeInvalRect <node>
Invalidates the rectangle in the viewports that the node is occupying. Rectangles flagged
as invalid will be updated on the next screen redraw.

Viewport Background Images

The following methods provide access to the values in the Viewport Background dialog.
getBkgFrameNum <time>
Returns the viewport background image frame displayed at the specified time. Returns a
value of –1 if no frame is to be used for specified time.
getBkgImageAnimate()
setBkgImageAnimate <boolean>
Get and set whether Animate Background is on (true), or off (false).
getBkgImageAspect()
setBkgImageAspect <name>
Get and set the background image Aspect Ratio option. Valid <name> values are:
#view -- Match Viewport
#bitmap -- Match Bitmap
#output -- Match Rendering Output
 Viewport Grids 1587

getBkgORType <start_end_integer>
setBkgORType <start_end_integer> <name>
Get and set the background image Start Processing and End Procession options.
<start_end_integer> = 0 – Start Processing; 1 – End Processing
Valid <name> values are:
#blank -- Blank Before Start/After End
#hold -- Hold Before Start/After End
#loop -- Loop After End

getBkgRangeVal()
Get the background image Use Frame range as a Point2 value. The first component of the
Point2 value is the Start Frame, the second component is the End Frame.
setBkgFrameRange <point3>
Set the background image Use Frame range and step value. First component of <point3>
is Start Frame, second component is End Frame, and third component is Step Frame.
getBkgStartTime()
setBkgStartTime <time>
Get and set the background image Start At frame.
getBkgSyncFrame()
setBkgSyncFrame <integer>
Get and set the background image Synch Start To Frame frame.
The following 3ds max system global variable is associated with the Viewport Background dialog:
backgroundImageFileName
Lets you get and set a String value that defines the viewport background image bitmap file
name. It contains the corresponding bitmap file name set in the Viewport Background
dialog.

Viewport Grids
The following methods control the display and spacing of grid lines in the viewports.
getGridSpacing()
Returns the spacing between grid lines in units.
getGridMajorLines()
Returns the number of grid lines between major grid lines.
The following 3ds max system global variable is associated with the Viewport grids:
activeGrid
Contains the currently active grid. If the home grid is active, returns the value undefined.
You can assign a grid node object to this variable to make it the currently active grid.
1588 Chapter 13 | Interacting with the 3ds max User Interface

Mouse Cursors
The following methods control the mouse cursor.
setWaitCursor()
setArrowCursor()
These functions can be used to display the system wait cursor during some prolonged
computation and then replace it with the normal cursor. You might want to do this
instead of putting up a 3ds max progress bar, which may be too heavy-weight in some
situations. Note that in some cases, 3ds max may itself restore the arrow cursor
underneath this one (for example, with loadMAXFile()), and you may need to redisplay
it after such calls.
setSysCur <name>
Sets the current system cursor to one of the standard 3ds max cursors. Valid <name>
values are:
#move
#rotate
#uscale
#nuscale
#squash
#select
#arrow

Note: setSysCur #squash shows the non-uniform scale cursor.

The following 3ds max system global variables are associated with the mouse:
mouse.mode
A read only variable to get the mouse mode as an <integer> value. Return values are: 0 -
Idle; 1 - Point; 2 - Move
mouse.buttonStates
A read only variable to get the state of the mouse buttons as a 3 element <bitArray>. The
order of the bits is: #{Left, Middle, Right}
Note: right mouse button state not always correct. If you right click to bring up a right-
click menu and then click in the viewport to dismiss the menu, the right mouse button is
still reported as down.
mouse.pos
A read only variable to get the mouse position in the currently active viewport as a
<point2> value. The coordinates are in pixel values. If the currently active viewport is a 2D
view (Track View, Schematic View, Listener, etc.), the coordinates are in the first non-2D
viewport.
 Picking Points in the Viewports 1589

Picking Points in the Viewports

pickPoint [ prompt:<string> ] [ snap:#2D|#3D ] \
[ rubberBand:<start_point3> ] \
[ mouseMoveCallback:fn | #(fn,arg) ] \
[ terminators:#(<string>,<string>,...) ]

The pickPoint() function lets the user pick a 3D point in a 3ds max viewport or type in
a 3D point in the Listener. When called, the function puts 3ds max into a special point-
picking command mode and the cursor changes to a cross-hair. The user can either click in
one of 3ds max’s viewports or type a 3D point into the Listener and the function returns
that point as a MAXScript Point3 value in world-space coordinates.
The function takes an optional prompt: string argument which it prints in the Listener as
a prompt message. There is also an optional snap: keyword argument that controls
viewport point picking if Snap is turned on in the 3ds max interface. If #3D is specified,
the cursor snaps to points anywhere in 3D space, if #2D is specified (the default), the
cursor only snaps on the current active grid construction plane. If Snap is off in the
3ds max interface, the clicked point is always taken to be on the current active grid
construction plane.
The user can either press the ESC key or click the right mouse button at any time to abort
the point picking and the function immediately returns the special MAXScript value
#escape if the escape key is pressed or #rightClick if the right mouse button is clicked.
You can get the pickPoint() function to display a rubberbanding dashed line during
point input by supplying the optional keyword argument
rubberBand:<start_point3>. If you include this on a call to pickPoint(), it
rubberbands a dashed line from the specified start point to follow the mouse. You would
use it in a chain of point picks by specifying the last picked point as the rubberBand:
start point for each successive pick. The start point given to rubberBand: should be in
world coordinates.
You can also set up a mouse move callback function for tracking free mouse moves during
point input. The optional keyword argument for this is mouseMoveCallback: and it has
two forms:
mouseMoveCallback:fn
mouseMoveCallback:#(fn, arg)

The second form allows you to supply an argument value that is sent to the callback
function each time it is called.
The fn you supply should take one argument in the first form above and two in the
second. When the callback function is called, the first argument it gets is always the
current world coordinates of the mouse and the second if given is the arg you supplied.
You can use a callback function to implement a more sophisticated form of
rubberbanding, for example by adjusting a spline’s vertex or a box’s height to follow the
mouse. If you do this, make sure you call any needed update() mesh or spline functions.
1590 Chapter 13 | Interacting with the 3ds max User Interface

The pickPoint() function allows coordinates to be entered either by clicking in a

3ds max viewport or by typing numbers into the MAXScript Listener window. The user
can enter coordinates in one of several forms (based on the command line input syntax for
AutoCAD), as follows:
x, y, z
explicit point in current construction plane coordinates
x, y
point on the construction plane (cp)
d
point d units away in mouse direction from last point
@ x, y, z
relative, offset to last input point
@ x, y
on cp, relative to last point’s projection on cp
d < a
polar on cp, distance from cp origin at a angle from x-axis
@ d < a
relative polar on cp, centered on last point
d < a1 < a2
spherical on cp, d from cp origin at a1 from x and a2 angle from xy-plane
@ d < a1 < a2
relative spherical
There can be zero or more white space characters before and between numbers and
metacharacters.
Note that these typed-coordinates are always interpreted as relative to the current active
grid construction plane and that coordinates returned by pickPoint() are always in
world-space.
Keyboard input by the user that is not in one of the expected coordinate input forms is
returned as a String value so the author can handle the error gracefully or permit other
kinds of input to be parsed by the script.
You can test for these return conditions using the classOf() function, for example:
p = pickPoint()
case of
(
(p == undefined): ... -- user pressed escape
(p == #rightClick): ... -- user clicked RMB
(classOf p == Point3): ... -- user entered a point
(classOf p == String): ... -- user keyed a non-point
)

The terminators: keyword argument expects an array of 1 or more strings each of 1 or

more characters. When supplied, this list of strings specifies a set of keyboard input
terminating character sequences. If any one of them is typed at the end of some input, the
 Picking Points in the Viewports 1591

pickPoint() function returns immediately without waiting for an ENTER to be typed. In

all cases when the terminators: keyword argument is supplied, the pickPoint()
function returns a two-element array--the first element is the input point, the second
element is the terminating string, or undefined if the point was input with a mouse click
or terminated with ENTER.
This allows the user to type in a point terminated by a terminator string, or just type the
terminator string. In the second case, the first element in the result array is the value
undefined. You can inspect the second element in the array to see what terminator, if
any, the user actually typed. For example,
pp = pickPoint prompt:”foo: “ terminators:#(” “, “a”, “oo”)
if pp[2] == “a” then ...

Often, the pickPoint() function will be used repeatedly within a script to request
multiple points, such as successive vertices in a line. You may need to use the new
function, redrawViews(), to force a viewport update as you gradually construct new
scene objects this way. MAXScript normally delays viewport redraw until the script
finishes running.
pickOffsetDistance [ prompt:<string> ] [ pt2Prompt:<string> ] \
[ errPrompt:<string> ] [ snap:#2D|#3D ] \
[ keyword:<string> ]

This function issues the prompt message, if any, to Listener and waits for the user to either
click in a viewport (which determines a point exactly like the pickPoint() function), to
type in a number ended by ENTER (which determines a number), or to type all or the
beginning of the keyword ended by ENTER. If the user types the keyword, the function
returns true. If the user types a number, the function returns its value. If the user clicks a
point, the function issues the pt2Prompt message, if any, to Listener and waits for a
second point to be clicked, and then returns the world-space distance between the two
points. If the user types something which is not a number and does not match the
keyword, the function issues the errPrompt message, if any, otherwise the prompt
message, if any, and waits for the user to try again.
1592 Chapter 13 | Interacting with the 3ds max User Interface

Viewport Drawing Methods

The methods documented in this topic provide low-level access to 3ds max’s graphics system. These
methods are available for scripts to do any graphics work not possible using the standard high-level
graphics methods.
These methods are for use in the existing 3ds max viewports, and only work on the active viewport.
Note that these methods typically are not for casual use, as they are not intended to be a high level
graphics library. For example, many steps are required to display a single lit polygon. These methods
are optimized for speed, and not at all for script programmer ease of use.
The methods described in this topic actually operate on graphic windows. While graphic windows
are not the same as viewports, they are related to one another. Each viewport has its own graphics
window, and the contents of the viewport display can be thought of as a snapshot of the graphics
window contents. Since writing to display memory a relatively slow operation, 3ds max writes
instead to the graphics window, and then when all the writes have been finished, it redraws the
viewports with the graphics window contents.
Graphics Driver Configuration and Support Methods
gw.getDriverString()
This method returns a string identifying the graphics driver (and includes manufacturer
info if available)
gw.querySupport <feature_name>
Determines if the driver supports the specified feature. The valid <feature_name>
values are:
#txtCorrect
This is used to enable or gray-out the perspective correction right-click viewport
menu option.
#geomAccel
This is used to indicate to 3ds max (and the mesh class in particular) that the driver
wants to handle all of the 3D data natively. In this case, meshes are rendered by
passing 3D world space data and letting the driver transform, clip, and light the
vertices. If this returns false, then the mesh class handles all transforms, clipping
and lighting calculations and then calls the hPolygon or hPolyline 2 1 / 2D calls for
the driver to rasterize. (Primitives that are actually clipped are still sent to the
polygon/polyline methods.)
Currently, only the OpenGL driver returns true to this query, but other drivers have
been developed that return true, and the HEIDI and D3D drivers may change in the
future.
#triStrips
If this returns true, then 3ds max will try to stripify meshes before calling the
rendering methods. Currently, the drivers just return the user preference that is set in
the driver configuration dialog. This preference defaults to true.
 Viewport Drawing Methods 1593

#dualPlanes
If a driver has dual-planes support it returns true. The standard 3ds max OpenGL
display driver only returns true for this if the underlying display driver has
implemented a custom OpenGL extension that allows 3ds max to handle this
efficiently.
#swapModel
This returns true if 3ds max has to redraw the whole scene any time the viewports are
exposed.
#incrUpdate
This returns true if the driver can update a rectangular subset of the viewport without
trashing the image outside that rectangle. This is true for most drivers that blit the
viewport region and false for those that do page-flipping in the hardware. For
OpenGL, this is true if the display driver implements the Microsoft
glSwapRectHintWIN extension.
#passDecal
This is true if the driver can handle decalling with only one pass. Currently, this is
true for OpenGL, but false for HEIDI and D3D.
#driverConfig
This is true if the driver has a configuration dialog. This is true for all three of
3ds max‘s standard drivers.
#texturedBkg
This is true if the viewport background is implemented as a textured rectangle, and
false if it is a blitted bitmap.
#virtualVpts
This is true if the driver allows viewports to be made larger than the physical window
they are attached to. Currently, this is only true for OpenGL.
#paintDoesBlit
This is true if WM_PAINT messages result in a blit of the backbuffer (as opposed to a
page-flipping swap). This allows 3ds max to do quick damage region repair, and works
together with the #swapModel flag.
#wireframeStrips
This is true if the driver wants 3ds max to send down wireframe models using
triangle strips instead of a bundle of 2-point segments. This is only used by the
OpenGL driver, and it is there as a user-choosable performance-accuracy tradeoff
(since the strips are faster and are back-culled, but they display hidden edges as
though they are visible).
1594 Chapter 13 | Interacting with the 3ds max User Interface

Window and Viewport Transformation Methods

gw.isPerspectiveView()
Returns true if the view is in perspective projection; otherwise false (orthographic
projection).
gw.setTransform <matrix3>
Sets the active viewport’s graphics window transformation matrix to the specified matrix3
value, and updates the modeling coordinates to normalized projection coordinates matrix.
This routine also back-transforms each light and the eye point so that lighting can be done
in modeling coordinates.
This method may be used to set a matrix that transforms the point passed to the drawing
methods (like gw.text(), gw.marker(), gw.polyline() or gw.polygon()). Normally
these methods expect world coordinates. However if this matrix is set to an object’s
transformation matrix you can pass coordinates in the object’s space coordinates and they
will be transformed into world space (and then put into screen space when they are
drawn). If however this is set to the identity matrix, you would pass world space
coordinates. You can set this matrix to the object’s transform matrix using the
following code:
gw.setTransform node.transform

For world-to-screen space conversions by the methods gw.text(), gw.marker(),

gw.polyline() or gw.polygon(), etc, a developer must explicitly set this matrix to the
identity matrix. This is because the graphics window may have a non-identity transform
matrix already in place from a previous operation.
gw.getFlipped()
Returns true if the determinant of the current transform is positive, false if negative.
Position, Size, and Depth Clipping Methods
gw.setPos <x_integer> <y_integer> <w_integer> <h_integer>
Sets the size and position of the graphics window. The coordinates are all Windows
coordinates in the space of the graphics windows’ parent window. All coordinates are in
Windows format, with the origin in the upper left.
x - Specifies the left graphics window origin; y - Specifies the top graphics window origin;
w - Specifies the graphics window width; h - Specifies the graphics window height.
gw.getWinSizeX()
This method gets the current window size in X.
gw.getWinSizeY()
This method gets the current window size in Y.
gw.getWinDepth()
This method returns the z-buffer depth (in bits). Note: this method does not return the
proper Z depth value in 3ds max and VIZ R3.
gw.getHitherCoord()
This method returns the largest device Z value.
 Viewport Drawing Methods 1595

gw.getYonCoord()
This method returns the smallest device Z value. Note: this method does not return the
proper Z depth value in 3ds max and VIZ R3.
DIB (Device-Independent Bitmap) Methods
gw.getViewportDib()
This method returns the active viewport’s graphics window image as a Bitmap value. The
size of the bitmap is the same size as the viewport.
Script:
MacroScript GrabViewport category:”Tools” tooltip:”Grab Viewport”
(
---------------------------------------------------------------------
--GRABVIEWPORT MACROSCRIPT
--Created:3/23/99
--Edited:4/28/99
--by Borislav Petrov
--bobo@email.archlab.tuwien.ac.at
---------------------------------------------------------------------
--Snapshot Active Viewport to Bitmap
--Filename in format:
--VPGRAB_MaxFileName_ViewportName_CurentFrame.ImageFormatExtension
---------------------------------------------------------------------
--
--Init Variables
local grab_bmp --bitmap to put the snapshot into
local bmp_name --name of the bitmap to save
local get_viewport_name --viewport name
local gac,gct,mfn --variables to hold ActiveCamera, CurrentTime, MaxFileName
--
--Start Macro
grab_bmp = gw.getViewportDib() --get the viewport bitmap into variable
get_viewport_name = viewport.GetType() --get viewport name
gvn = get_viewport_name as string --convert viewport name to string
gvn = substring gvn 6 (gvn.count-5) --cut the string
if gvn == “camera” then --if the remaining string is “camera”
( gac = getActiveCamera() --get the camera
gvn = gac.name --get the name of the camera
)
mfn = MaxFileName --get max file name
if mfn == ““ then --if there is no name
mfn = “Untitled” --use “Untitled”
else
mfn = getFileNameFile mfn --use the file name without .MAX extension
gct = SliderTime as string --get current frame time
--
bmp_name = “VPGRAB_”+ mfn +”_” +gvn + “_” + gct --build the output file name
--
--Display file save dialog
bmp_name = getSaveFileName caption:”Save Viewport to:” filename:bmp_name \
types:”BMP(*.bmp)|*.bmp|TIFF(*.tif)|*.tif|JPG(*.jpg)|*.jpg|TGA(*.tga)|*.tga|”
1596 Chapter 13 | Interacting with the 3ds max User Interface

--
if bmp_name != undefined then --if user has confirmed / entered a valid name
( grab_bmp.filename = bmp_name --set output name to the one entered in the save
file dialog
save grab_bmp --save the bitmap
display grab_bmp --display the bitmap in a VFB
)
--
)--end of script

Drawing Setup
gw.resetUpdateRect()
This method resets the update rectangle. The update rectangle is the region of the screen
that needs to be updated to reflect items that have changed. When the system is done
rendering items, the goal is to only update the region of the viewport that has actually
been altered. This method sets the update rectangle (the region that will be blitted to the
display) to a special “empty” value. This way when gw.enlargeUpdateRect() is later
called, the Box2 region passed will be used as the region.
gw.enlargeUpdateRect ( <Box2> | #whole )
This method enlarges the update rectangle to include the Box2 value passed. If #whole is
specified, the whole viewport will later be updated
gw.getUpdateRect()
This method retrieves the current update rectangle as a Box2 value. Returns a special an
Box2 “empty” value if no region of the viewport needs to be updated.
gw.setRndLimits <render_limits_name_array>
Sets the rendering limits used by primitive calls. Setting the rendering limits is used in
communication between the various parts of 3ds max that handle the display of objects.
For example, setting this limit to #polyEdges and then drawing a polygon won’t result in a
polygon drawn with edges. It only sets a flag that indicates the edge should be drawn.
What happens is as follows. Inside the upper level 3ds max, part of the code knows that
polygon edges have been turned on. However this is not related through the object
oriented architecture to the part of 3ds max that does the actual drawing. When 3ds max
goes to draw objects it will see that the polygon edge flag is on. This tells it to do two
drawing passes -- one to draw the polygon, then it calls outlinePass() call with true,
draws a bunch of edges, then calls outlinePass() with false. Thus, the drawing
routine is responsible for looking at the flags and drawing appropriately. This method is
only responsible setting the limit which can later be checked.
<render_limits_name_array> specifies the rendering limits used by the viewport as an
array of <render_limits_name> values. The valid <render_limits_name> values are:
#allEdges
All edges of the item are shown (including hidden ones).
#boxMode
Objects are shown using their bounding box.
 Viewport Drawing Methods 1597

#backcull
Backface culling is used. Entities whose surface normal face away from the view
direction are not drawn.
#colorVerts
This turns on color-per-vertex display.
#flat
Flat (facet) shading mode.
#illum
This indicates that you have colors per vertex in your polygons and that they should
be used. If you had colors per vertex but this flag was not set, the colors would be
ignored.
#lighting
This is the same as setting #illum and #specular.
#noAtts
No attributes are specified.
#perspCorrect
In this mode textures are corrected for perspective display.
#pick
This indicates hit testing will be performed (not rendering).
#polyEdges
This mode causes polygon edges (Edged Faces) to be on.
#shadeCverts
This modifies #colorVerts. If set, lighting is enabled and the vertex colors are used
to modulate the colors that result from lighting. If off, the colors on each vertex are
used directly to shade the triangle. When 3ds max uses #shadeCverts mode, it puts a
white diffuse-only material on the object so that it appears that the colors are shaded
without distortion.
Described further, when #shadeCverts is OFF, then the vertex colors are used
directly. This is equivalent to saying that they are modulated by a pure white self-
illuminated material.
When #shadeCverts is ON, the diffuse white material is illuminated by the scene
lighting, resulting in shades ranging from black to white, with most vertices being
some shade of pure gray. When the vertex colors are modulated by the material color,
they get multiplied (in general) by a number less than 1, which makes them appear
darker.
The RGB components of the colors are modulated uniformly, so that there is no shift
from, say, red to green. That would happen if the underlying material was not evenly
weighted (that is, a pure gray lying between black and white). Said another way, only
the intensity of the vertex colors is changed when shading is on, not luminance,
chrominance, etc.
1598 Chapter 13 | Interacting with the 3ds max User Interface

#specular
This enables specular highlight display.
#texture
This enables texture display.
#twoSided
Faces are displayed regardless of their surface normal orientation.
#vertTicks
This mode is really a pseudo-mode, in that it doesn’t actually cause the graphics
drivers to do anything differently, but rather is tested by the Mesh class, which sends
down vertex markers (+) if the mode is on.
#wireframe
Wireframe rendering mode.
#zBuffer
When coordinates are specified for drawing primitives they have x, y, and z values.
Sometimes when drawing entities in the viewports it is desirable to ignore the z
values. For example in the 3ds max viewports the text that display the type of
viewport (Front, Left, and so on) are drawn without z values. So are the arc-rotate
circle control and the axis tripods. These items are drawn without this flag being set so
they always show up in front.
gw.getRndLimits()
Retrieves the rendering limits used by primitive calls as an array of names. See
gw.setRndLimits() for a list of the returned name values.
gw.getRndMode()
Returns the current rendering mode used by the viewport as an array of names. This is a
subset of the rendering limit, in that any limits imposed by the rendering limit are forced
onto the current mode. See gw.setRndLimits() for a list of the returned name values.
gw.setSkipCount <skip_count_integer>
Sets the number of triangles skipped when the viewport is set as a ‘Fast View Display’
viewport. To disable fastview, specify 1. Since triangles are handed down to graphics driver
one at a time, it is up to the code that feeds triangles to the graphics driver to skip the
specified number of triangles. The mesh rendering in 3ds max uses the skip count in
this way.
<skip_count_integer> specifies that every ‘n-th’ triangle should be drawn. If set to 2,
every other triangle should be drawn.
gw.getSkipCount()
Returns the current skip count setting.
 Viewport Drawing Methods 1599

The following is an example of using the above functions:

-- Get the current rendering limits
lim = gw.getRndLimits()

-- Add another limit

append lim #polyEdges

-- Set the new rendering limits

gw.setRndLimits lim

-- Get back the rendering limits to check

gw.getRndLimits()

-- Get back the rendering mode to check

gw.getRndMode()

Light and Camera Methods

gw.getMaxLights()
Returns the maximum number of lights that may be used by the interactive renderer.
Coordinate Transformation Methods
The following methods map points from the graphic window’s current transform to device space. If
the graphic window’s transform is set to the identity matrix then the mapping is done from points
specified in world space. Otherwise the points given are transformed by the graphic window’s
transform, and are then considered to be in world space. Thus, to get a world-space to screen-space
conversion, you need to set the graphic window’s transform to the identity with:
gw.setTransform(Matrix3 1)

gw.hTransPoint <point3>
This method converts the point3 coordinate to a “h” format device coordinate. Each
component of the return value is in integer format in the native device coordinates for the
graphics driver. For HEIDI and OpenGL, the origin is at the lower left. For Direct3D the
origin is at the upper left.
gw.wTransPoint <point3>
This method converts the point3 coordinate to a “w” format device coordinate. Each
component of the return value is in integer format with the origin at the upper left.
gw.transPoint <point3>
This method converts the point3 coordinate to a “h” floating point coordinate. Each
component of the return value is in float format with the origin at the upper left. This is
just a helper routine to avoid building up round-off error. 3ds max uses it just for IK.
1600 Chapter 13 | Interacting with the 3ds max User Interface

Drawing Methods
Methods that start with “h” take integer device coordinates with the origin at the lower-left.
Methods that start with “w” in front take Windows device coordinates with the origin at the upper
left. These “h” and “w” routines perform NO clipping unless otherwise noted. Drawing outside the
allowable region is likely to cause 3ds max to crash. These coordinate systems are left-handed.
Methods that don’t start with “h” or “w” map points from the graphic window’s current transform
to device space. This coordinate system is right-handed. If the graphic window’s transform is set to
the identity matrix then the mapping is done from points specified in world space. Otherwise the
points given are transformed by the graphic window’s transform, and are then considered to be in
world space. Thus, to get a world-space to screen-space conversion, you need to set the graphic
window’s transform to the identity with:
gw.setTransform(Matrix3 1)

After completing any drawing to the graphics window with the methods described in this section,
you need to call gw.updateScreen() to update the viewport display.
gw.updateScreen()
Updates the viewport display to display any text, markers, polylines, polygons, or tristrips
written to the graphics window via the methods described below.
gw.text <point3> <string> [ color:<color> ]
gw.hText <point3> <string> [ color:<color> ]
gw.wText <point3> <string> [ color:<color> ]
Draws 2D fixed font annotation string text to the specified location using the specified
(optional) color. If the color is not specified, a default color of red is used.
Note: This routine DOES perform clipping of the text if it is off the screen.
gw.Marker <point3> <marker_name> [ color:<color> ]
gw.hMarker <point3> <marker_name> [ color:<color> ]
gw.wMarker <point3> <marker_name> [ color:<color> ]
Draws a marker at the specified location. This is can be paired with pickpoint() to
quickly show where the user has clicked. These markers are temporary and will be erased
whenever the viewports are updated. If the color is not specified, a default color of red is
used. The valid <marker_name> types are:
#point
#hollowBox
#plusSign
#asterisk
#xMarker
#bigBox
#circle
#triangle
#diamond
#smallHollowBox
#smallCircle
#smallTriangle
#smallDiamond
 Viewport Drawing Methods 1601

The following is an example that creates an instance of all types of markers,

spaced equally:
arr = #(”point”,”hollowBox”,”plusSign”,”asterisk”,”xMarker”,
“bigBox”,”circle”,”triangle”,”diamond”,”smallHollowBox”,
“smallCircle”,”smallTriangle”,”smallDiamond” )

for i=1 to arr.count do

gw.hMarker [100, (50 + i*10), 50](arr[i] as name)

gw.enlargeUpdateRect #whole
gw.updateScreen()

gw.Polyline <vertex_point3_array> <isClosed_boolean> \

[ rgb:<color_array> ]
gw.hPolyline <vertex_point3_array> <isClosed_boolean> \
[ rgb:<color_array> ]
gw.wPolyline <vertex_point3_array> <isClosed_boolean> \
[ rgb:<color_array> ]
This method draws a multi-segment polyline. Each value in <vertex_point3_array> is
a vertex on the polyline. If <isClosed_boolean> is true, the first point is connected to
the last point, that is, the polyline is closed. If false, the polyline is left open. If the
optional rgb color array is specified, and shade mode is set to smooth, the polyline will be
drawn Gourand shaded. This is how 3ds max draws lit wireframes for instance. If the
optional rgb color array is not specified, the line is drawn with the line color specified via
gw.setColor(). The number of elements in <color_array> must be the same as in
<vertex_point3_array>.

gw.Polygon <vertex_point3_array> <color_array> \

<uvw_point3_array>
gw.hPolygon <vertex_point3_array> <color_array> \
<uvw_point3_array>
gw.wPolygon <vertex_point3_array> <color_array> \
<uvw_point3_array>
This method draws a multi-point polygon. Each value in <vertex_point3_array> is a
vertex on the polygon. <color_array> specifies the color at each vertex. The rendering
mode (set via gw.setRndLimits()) must include #illum for the color values to be used.
<uvw_point3_array> specifies the UVW coordinates at each. The rendering mode must
include #texture for the UVW coordinates to be used. The number of elements in each
array must be identical.

gw.hTriStrip <vertex_point3_array> <color_array> \

<uvw_point3_array>
gw.wTriStrip <vertex_point3_array> <color_array> \
<uvw_point3_array>
This method is used for drawing a series of triangles specified as ‘strips’. It takes a count of
3 or more, and builds triangles in a strip. This sends a lot less data and the underlying
graphics library has to set up a lot less data since it can use the previous information to
1602 Chapter 13 | Interacting with the 3ds max User Interface

start the rasterization. This results in a significant speed increase. This routine does no
clipping so all the vertices passed must be within view. The parameters are the same as for
the gw.Polygon(). However, how the <vertex_point3_array> is handled is different.
After the first two vertices, each new vertex is used to create a new triangle. For instance, to
draw a quad, the first three vertices specify the first triangle and the next one is combined
with the previous two to complete the square
The following is an example of using the above functions:
Script:
-- Draw some primitives
gw.hPolyline #([300,50,16], [300,200,8], [450,250,4]) true
--
gw.hPolygon #([200,100,16], [280,100,8], [250,200,4]) \
#(red, blue, green) \
#([1.0,.5,0], [0.5,0.5,0], [0,0,0.5])
--
gw.hTriStrip #([50,50,0], [175,100,0], [25,100,0], [150,250,0]) \
#(red, blue, green, white) \
#([1.0,.5,0], [0.5,0.5,0], [0,0,0.5], [0.5,1,0])
--
-- Update the viewports
gw.enlargeUpdateRect #whole
gw.updateScreen()

gw.setColor <type_name> <color_value>

Sets the RGB color used for the specified drawing type. The valid <type_name> values are:
#line -- line drawing color
#fill -- polygon fill color
#text -- text drawing color
#clear -- The color that the viewport is cleared to
when you call gw.clearScreen()

gw.clearScreen <Box2> [ useBkg:<boolean> ]

Clears the specified rectangular region of the screen. If the optional useBkg parameter is
set to false, the region is set to the “clear” color (see gw.setColor() above). If true, the
background should be used to fill the cleared area. The default useBkg value is false.
 Miscellaneous Viewport Methods and System Globals 1603

Miscellaneous Viewport Methods and System Globals

createPreview()
Creates a viewport preview using the current values in the Make Preview dialog.
getVPortBGColor()
setVPortBGColor()
Get and set the viewport background color as a Color value.
isCPEdgeOnInView()
This method returns true if the construction plane is ‘head on’ in the current viewport.
For example if the construction plane was XY and you were looking from the Front view,
this method would return true. This is used for example during object creation because
this process doesn’t work very well when the view is ‘head on’.
axisTripodLocked()
This method returns true if the axis tripods are locked, that is, they won’t move when
you move an object or sub-object, false otherwise.
lockAxisTripods <boolean>
If <boolean> is true, this method locks the axis tripods so that they will not be updated.
If false, the axis tripods will be updated.
Note: In certain cases, the lockAxisTripods() method can cause multiple Assertion
Failures. This occurs when one or more objects are selected, lockAxisTripods true is
executed, and then the objects are deselected.
flashNodes <node_array>
This method is used to ‘flash’ a group of nodes. This is usually used as a confirmation of
some operation (for example as an indication of the completion of a pick node operation.)
The nodes are briefly erased and then redrawn in the viewport to flash them.
Note: The flashNodes() method does not redraw the viewports after displaying the
specified nodes as white wireframes. To properly redraw the viewports, call the
forceCompleteredraw() method immediately after calling flashNodes().
The following 3ds max system global variables are applicable to the viewports:
displaySafeFrames
Lets you get and set whether Show Safe Frames is on for the active viewport. A Boolean
value - true if Show Safe Frames is on, false if off.
preferences.useLargeVertexDots
Lets you get and set whether to use small or large dots when representing vertices as dots.
A Boolean value set to true if you when using dots to represent vertices and a large size is
desired. The value of this variable only has effect when UseVertexDots is set to true.
This variable contains the corresponding value set in the Viewports page of Customize >
Preferences.
preferences.useTransformGizmos
Lets you get and set whether to use the Transform Gizmos. A Boolean value - true if on,
false if off. This variable contains the corresponding value set in the Viewports page of
Customize > Preferences.
1604 Chapter 13 | Interacting with the 3ds max User Interface

preferences.useVertexDots
Lets you get and set whether to represent vertices as dots. A Boolean value set to true
when you want to use dots as the representation of the vertices in a mesh. If set to false,
ticks will be used. This variable contains the corresponding value set in the Viewports page
of Customize > Preferences.

3ds max User Interface Colors

The following methods are used to get and set the 3ds max user interface colors.
GetUIColor <index_integer>
Returns a Point3 value corresponding to the color value used for drawing the specified
item type in the 3ds max viewports. Each component of the Point3 value is in a range of 0
to 1, corresponding to a color component value of 0 to 255. See the list of
<index_integer> values below.
GetDefaultUIColor <index_integer>
Returns a Point3 value corresponding to the default color used for drawing the specified
item type in the 3ds max user interface. Each component of the Point3 value is in a range
of 0 to 1, corresponding to a color component value of 0 to 255. The values returned are
not affected by the user’s color selections or those set by SetUIColor(). See the list of
<index_integer> values below.
SetUIColor <index_integer> <point3>
Sets the color value used for drawing the specified item type in the 3ds max viewports.
Each component of the Point3 value is in a range of 0 to 1, corresponding to a color
component value of 0 to 255. See the list of <index_integer> values below.
The valid <index_integer> values and the corresponding item type are as follow:
0 COLOR_SELECTION Main UI Selection
1 COLOR_SUBSELECTION Main UI Subselection
2 COLOR_FREEZE Main UI Freeze
3 COLOR_GRID Grids Grid
4 COLOR_GRID_INTENS Grids Grid Intensity
5 COLOR_SF_LIVE Main UI Safe Frame Live
6 COLOR_SF_ACTION Main UI Safe Frame Action
7 COLOR_SF_TITLE Main UI Safe Frame Title
8 COLOR_VP_LABELS Main UI Viewport Label
9 COLOR_VP_INACTIVE Main UI Inactive Viewport Label
10 COLOR_ARCBALL Main UI Arcball
11 COLOR_ARCBALL_HILITE Main UI Arcball Highlight
12 COLOR_ANIM_BUTTON Main UI Animate Button
14 COLOR_LINK_LINES Gizmos & Apparatuses Bones and Link Lines
15 COLOR_TRAJECTORY Gizmos & Apparatuses Trajectory
16 COLOR_ACTIVE_AXIS Gizmos & Apparatuses Active Axis
17 COLOR_INACTIVE_AXIS Gizmos & Apparatuses Inactive Axis
18 COLOR_SPACE_WARPS Objects Space Warp
19 COLOR_DUMMY_OBJ Objects Dummy Object
20 COLOR_POINT_OBJ Objects Point Object
21 COLOR_POINT_AXES Objects Point Axis
 Miscellaneous Viewport Methods and System Globals 1605

22 COLOR_TAPE_OBJ Objects Tape Object

24 COLOR_GIZMOS Gizmos & Apparatuses Gizmos
25 COLOR_SEL_GIZMOS Gizmos & Apparatuses Selected Gizmos
26 COLOR_SPLINE_VECS Main UI Spline Vectors
27 COLOR_SPLINE_HANDLES Main UI Spline Handles
29 COLOR_PARTICLE_EM Gizmos & Apparatuses Particle Emitter
30 COLOR_CAMERA_OBJ Objects Camera Object
31 COLOR_CAMERA_CONE Gizmos & Apparatuses Camera Cone
32 COLOR_CAMERA_HORIZ Gizmos & Apparatuses Camera Horizon
33 COLOR_NEAR_RANGE Gizmos & Apparatuses Camera Near Range
34 COLOR_FAR_RANGE Gizmos & Apparatuses Camera Far Range
35 COLOR_LIGHT_OBJ Objects Light Object
36 COLOR_TARGET_LINE Gizmos & Apparatuses Target Line
37 COLOR_HOTSPOT Gizmos & Apparatuses Light Hotspot
38 COLOR_FALLOFF Gizmos & Apparatuses Light Falloff
39 COLOR_START_RANGE Gizmos & Apparatuses Light Far Start
40 COLOR_END_RANGE Gizmos & Apparatuses Light Far End
41 COLOR_VIEWPORT_BKG Main UI Viewport Background
42 COLOR_TRAJ_TICS_1 Gizmos & Apparatuses Trajectory Frames 1
43 COLOR_TRAJ_TICS_2 Gizmos & Apparatuses Trajectory Frames 2
44 COLOR_TRAJ_TICS_3 Gizmos & Apparatuses Trajectory Frames 3
45 COLOR_GHOST_BEFORE Main UI Ghost (Before)
46 COLOR_GHOST_AFTER Main UI Ghost (After)
47 COLOR_12FIELD_GRID Main UI 12-Field Grid
48 COLOR_START_RANGE1 Gizmos & Apparatuses Light Near Start
49 COLOR_END_RANGE1 Gizmos & Apparatuses Light Near End
50 COLOR_CAMERA_CLIP Gizmos & Apparatuses Camera Clip
51 COLOR_NURBS_CV Main UI NURBS Control Vertex
52 COLOR_NURBS_LATTICE Main UI NURBS Lattice
53 COLOR_NURBS_CP Main UI NURBS Con Point
54 COLOR_NURBS_FP Main UI NURBS Fit Point
55 COLOR_NURBS_DEP Main UI NURBS Dep Object
56 COLOR_NURBS_ERROR Main UI NURBS Error Object
57 COLOR_NURBS_HILITE Main UI NURBS Hilite
58 COLOR_NURBS_FUSE Main UI NURBS Fuse
59 COLOR_END_EFFECTOR Gizmos & Apparatuses End Effector
60 COLOR_END_EFFECTOR_STRING Gizmos & Apparatuses End Effector String
61 COLOR_JOINT_LIMIT_SEL Gizmos & Apparatuses Selected Joint Limits
62 COLOR_JOINT_LIMIT_UNSEL Gizmos & Apparatuses Joint Limits
63 COLOR_IK_TERMINATOR Gizmos & Apparatuses IK Terminator
64 COLOR_SF_USER Main UI Safe Frame User
65 COLOR_VERT_TICKS Main UI Vertex Ticks
66 COLOR_XRAY Main UI See Through
67 COLOR_GROUP_OBJ Objects Group Object
68 COLOR_MANIPULATOR_X Gizmos & Apparatuses Transform Gizmo X
69 COLOR_MANIPULATOR_Y Gizmos & Apparatuses Transform Gizmo Y
70 COLOR_MANIPULATOR_Z Gizmos & Apparatuses Transform Gizmo Z
71 COLOR_MANIPULATOR_ACTIVE Gizmos & Apparatuses Active Transform Gizmo
72 COLOR_VPT_CLIPPING Main UI Viewport Clipping
73 COLOR_DECAY_RADIUS Gizmos & Apparatuses Light Decay Start
74 COLOR_VERT_NUMBERS Main UI Vertex Numbers
1606 Chapter 13 | Interacting with the 3ds max User Interface

75 COLOR_CROSSHAIR_CURSOR Main UI Cross Hair Cursor

76 COLOR_SV_WINBK Other Views SV Window Bkg
77 COLOR_SV_NODEBK Other Views SV Node Bkg
78 COLOR_SV_SELNODEBK Other Views SV Selected Node Bkg
79 COLOR_SV_NODE_HIGHLIGHT Other Views SV Node Highlight
80 COLOR_SV_MATERIAL_HIGHLIGHT Other Views SV Material Highlight
81 COLOR_SV_MODIFIER_HIGHLIGHT Other Views SV Modifier Highlight
82 COLOR_SV_PLUGIN_HIGHLIGHT Other Views SV Plugin Highlight
83 COLOR_SV_SUBANIM_LINE Other Views SV Sub-Anim Line
84 COLOR_SV_CHILD_LINE Other Views SV Child Line
85 COLOR_SV_FRAME Other Views SV Frame
86 COLOR_SV_SELTEXT Other Views SV Selected Label
87 COLOR_SV_TEXT Other Views SV Label
88 COLOR_UNSEL_TAB Main UI Unselected Tabs
89 COLOR_ATMOS_APPARATUS Gizmos & Apparatuses Atmospheric Apparatuses
90 COLOR_SUBSELECTION_HARD Main UI SubSelection Hard
91 COLOR_SUBSELECTION_MEDIUM Main UI SubSelection Medium
92 COLOR_SUBSELECTION_SOFT Main UI SubSelection Soft
93 COLOR_SV_UNFOLD_BUTTON Other Views SV Unfold Children Button
94 COLOR_SV_GEOMOBJECT_BK Other Views SV Geometry Node Bkg
95 COLOR_SV_LIGHT_BK Other Views SV Light Node Bkg
96 COLOR_SV_CAMERA_BK Other Views SV Camera Node Bkg
97 COLOR_SV_SHAPE_BK Other Views SV Shape Node Bkg
98 COLOR_SV_HELPER_BK Other Views SV Helper Node Bkg
99 COLOR_SV_SYSTEM_BK Other Views SV System Node Bkg
100 COLOR_SV_CONTROLLER_BK Other Views SV Controller Node Bkg
101 COLOR_SV_MODIFIER_BK Other Views SV Modifier Node Bkg
102 COLOR_SV_MATERIAL_BK Other Views SV Material Node Bkg
103 COLOR_SV_MAP_BK Other Views SV Map Node Bkg

Material Editor
The following functions are specific to materials and the use of materials with the Material Editor:
getMeditMaterial <slot_index>
you can get the materials in the material editor slots 1 through 24. For example:
foo = getMeditMaterial 3

setMeditMaterial <slot_index> <material>

complements the getMeditMaterial function allowing you to place a material into the
numbered material editor slots. Accepts either materials or texture maps as <material>.
loadDefaultMatLib()
Loads the default 3ds max material library file.
loadMaterialLibrary <filename_string>
Loads the named 3ds max material library file, which becomes the current material library.
If the file name does not have a fully specified directory path, the function searches
through all the currently configured bitmap paths. Returns true if the loads succeeds,
false if it fails.
 Miscellaneous Viewport Methods and System Globals 1607

saveMaterialLibrary <filename_string>
Saves the current material library into the named file. Returns true if the save succeeds,
false if it fails.
fileOpenMatLib()
This method displays the File Open dialog and allows the user to select a material library
to load.
fileSaveAsMatLib()
Displays the standard Save File As dialog to allow the user to save the current material
library.
fileSaveMatLib()
If the current material library has been saved previously (has been named) this method
saves the material library to the same file. Otherwise it displays the standard Save File As
dialog to allow the user to save the current material library.
getMatLibFileName()
Returns the current material library file name as a String value.
renderMap <textureMap> [ into:<bitmap> ] \
[ size:<point2> ] \
[ filename:<string> ] \
[ scale:<float> ] \
[ filter:<boolean> ] \
[ display:<boolean> ]
provides access to the Render Map function available in the Material Editor. The function
returns a Bitmap value containing a rendering of the given texture map. If you specify the
optional into: argument, the function renders the map into the supplied bitmap, taking
size and other attributes from the existing bitmap. If you don’t, a new bitmap value is
created using the size: and fileName: arguments in its creation. If the into: and
size: parameters are not specified, the default size in [200,200].
The scale: argument is a scale factor applied to 3D TextureMaps. This is the scale of the
surface in 3d space that is mapped to UV and controls how much of the texture appears in
the bitmap representation.
If the filter: argument is true, the bitmap is filtered. It is quite a bit slower to rescale
bitmaps with filtering on. Defaults to false.
If the display: argument is true, the resulting bitmap is displayed using the virtual
frame buffer; otherwise it is not. Defaults to false.
Example:
rm = renderMap $foo.material.diffuseMap size:[640,480] \
fileName:”foodif.bmp”
save rm
close rm

The above will render a map to a bitmap and save it as a .bmp file.
1608 Chapter 13 | Interacting with the 3ds max User Interface

showTextureMap <material> <texmap> <boolean>

This provides control over the visibility of textures in the shaded viewport. You specify the
material containing the texture map, the texture map in that material to be controlled and
a boolean to turn the display on or off, for example:
Example:
showTextureMap $foo.material $foo.material.diffuseMap on
tm = checker()
mat = standardMaterial diffuseMap:tm
mm = multimaterial()
mm[1] = mat
$box01.material = mm
showTextureMap mm[1] tm on

Note that for multimaterials, you need to specify the appropriate sub-material (using [] indexing, for
example).
The following 3ds max system global variables are applicable to the Material Editor:
currentMaterialLibrary
Contains a virtual array of materials and root level maps corresponding to the currently
opened material library. You can get library materials via array indexing and iterate over
them in a for loop. The array can be indexed by number, or by name or string to select by
material name. This variable is read-only. See the MaterialLibrary Values (p. 795) topic for
more information.
meditMaterials
Contains a virtual array of materials and root level maps corresponding to the slots in the
material editor. You can access material editor materials and root level maps via array
indexing and iterate over them in a for loop. The array can be indexed by number to
specify slot number or name or string to select by material and root level map name. For
example:
$foo.material = meditMaterials[1]
meditMaterials[”foo mat”].diffuse = red
for m in meditMaterials do print m.diffuseMap
meditMaterials[1]=standard()
print meditMaterials.count -- number of slots

This variable is read-only, but the elements (the materials in the slots) are assignable. See
the MaterialLibrary Values (p. 795) topic for more information.
sceneMaterials
Contains a virtual array of materials and root level maps corresponding to the materials
and root level maps present in the scene. You can get scene materials and root level maps
via array indexing and iterate over them in a for loop. The array can be indexed by
number, or by name or string to select by material or root level map name. This variable is
read-only. See the MaterialLibrary Values (p. 795) topic for more information.
 Miscellaneous Viewport Methods and System Globals 1609

Track View
The Track View window functions are in a structure package named trackView. These functions
operate on named Track Views, and in many cases you identify the Track View window by this name.
The Track View functions are:
trackView.open <name_string>
Opens an existing Track View with the specified name, or creates a new Track View with
specified name. Returns the value true.
trackView.zoomSelected <name_string>
Zoom the named Track View on the currently selected object. The World track must be
expanded for this function to operate. The Object track will automatically be expanded if
is closed. The hierarchy display is scrolled such that the selected object’s track is placed at
the top of the window. If multiple objects are selected, the first object in the hierarchy that
is selected will be placed at the top of the window. If there are no selected objects, no
operation occurs. This method will return true, except when the named Track View does
not exist or is not open, when it returns false.
trackView.close <name_string>
Closes the named Track View. This method will return true, except when the named
Track View does not exist or is not open, when it returns false.
trackView.numTrackViews()
Returns the number of named Track Views defined
trackView.getTrackViewName <index_integer>
Returns the name of the indexed Track View as a String. Index values are 1-based.
trackView.setFilter “name_string” {<filter_flag_name>} [#noRedraw]
trackView.clearFilter “name_string” {<filter_flag_name>} [#noRedraw]
These methods allow you to set and clear display filters flags to control what is visible in a
named Track View. This method will return true, except when the named Track View does
not exist or is not open, when it returns false. You can supply as many filter flags as
desired per call. The valid filter flag names are:
#all -- set or clear all flags
#default -- set default view flags
#selectedObjects
#selectedTracks
#animatedTracks
#spacewarpBindings
#modifiedObjects
#transforms
#baseObjects
#positionX
#positionY
#positionZ
#rotationX
#rotationY
#rotationZ
#scaleX
1610 Chapter 13 | Interacting with the 3ds max User Interface

#scaleY
#scaleZ
#red
#green
#blue
#controllerTypes
#noteTracks
#sound
#materialsMaps
#materialParameters
#visibilityTracks
#hideGeometry
#hideShapes
#hideLights
#hideCameras
#hideHelpers
#hideSpacewarps
#visibleObjects
#position
#rotation
#scale
#curveX
#curveY
#curveZ
#staticValues
#hierarchy
#objects

The following 3ds max system global variables are applicable to Track View:
globalTracks
Contains a MAXTVNode value that defines the top-level Global Tracks node in Track View.
See Track View Nodes (p. 1382). This variable is read-only.
trackViewNodes
Contains a MAXTVNode value that defines top-level World node in Track View. See Track
View Nodes (p. 1382). This variable is read-only.
videoPostTracks
Contains a MAXTVNode value that defines the top-level Video Post Track View node. See
Track View Nodes (p. 1382). This variable is read-only. This variable contains the value
undefined in 3D Studio VIZ.
 Miscellaneous Viewport Methods and System Globals 1611

Render Scene Dialog

Note:
Changing the render scene dialog settings via the scripter should be done with the actual
render scene dialog in a closed state. Leaving the dialog open will make the attempted
scripter modifications non-sticky.
The following methods get and set options in the Render Scene dialog:
getRendApertureWidth()
Get the Aperture Width in millimeters for the current renderer.
getRendImageAspect()
Get the Image Aspect Ratio for the current renderer.
getUseDraftRenderer()
Returns true if the Draft renderer is the default renderer, false if the Production renderer
is the default renderer.
SetUseDraftRenderer <boolean>
Specifies which renderer is active -- draft or production. Pass true to use the draft
renderer and false to use the production renderer.
The following 3ds max system global variables are applicable to the Render Scene dialog:
renderer
Lets you switch between the draft and production renderers and test which one is active. A
Name value that accepts and contains the values #draft or #production, for example:
if renderer == #draft then ...
renderer = #production
render camera:c ...

renderDisplacements
Lets you get and set whether to perform displacement mapping during a render. A Boolean
value - true if displacement mapping is to be performed, false if not.
renderEffects
Lets you get and set whether to perform Render Effects after a scene render. A Boolean
value - true if Render Effects are to be performed, false if not.
renderHeight
Lets you get and set an Integer value that defines the output size height for the active
renderer.
renderPixelAspect
Lets you get and set an Integer value that defines the output pixel aspect for the active
renderer.
renderWidth
Lets you get and set an Integer value that defines the output size width for the active
renderer.
1612 Chapter 13 | Interacting with the 3ds max User Interface

rendOutputFilename
Lets you get and set a String value that defines the output file name for the active renderer.
It contains the corresponding value set in the Render Scene dialog. If this global variable is
set to ““ then Save File check box in the Render Scene dialog is unchecked.
skipRenderedFrames
Lets you get and set whether to skip rendered frames during a render. A Boolean Value –
true if rendered frames are to be skipped, false if not.
Note: The following globals should not be used if the Render Scene dialog is open. These globals do
not update the dialog if it is open, and closing the dialog or rendering from the dialog will cause the
displayed settings to be stored and used.
rendTimeType -- integer
Get/set the type of time range to be rendered. One of the following values:
1 - A single frame.
2 - The active time segment.
3 - The user specified range.
4 - The user specified frame pickup string (for example “1,3,5-12”).
rendStart -- time
Get/set the renderer’s start time setting.
rendEnd -- time
Get/set the renderer’s end time setting.
rendNThFrame -- integer
Get/set the renderer’s ‘n-th’ frame setting. Minimum value = 1
rendShowVFB -- boolean
Get/set the state of the renderer’s show virtual frame buffer flag. TRUE = on; FALSE = off
rendSaveFile -- boolean
Get/set the state of the renderer’s save file flag. TRUE = on; FALSE = off
rendUseDevice -- boolean
Get/set the state of the renderer’s use device flag. TRUE = on; FALSE = off
rendUseNet -- boolean
Get/set the state of the renderer’s use net flag. TRUE = on; FALSE = off
rendFieldRender -- boolean
Get/set the renderer’s field render flag. TRUE = on; FALSE = off
rendColorCheck -- boolean
Get/set the renderer’s color check flag. TRUE = on; FALSE = off
rendSuperBlack -- boolean
Get/set the renderer’s super black flag. TRUE = on; FALSE = off
rendHidden -- boolean
Get/set the renderer’s render hidden objects flag. TRUE = on; FALSE = off
rendForce2Side -- boolean
Get/set the renderer’s force two-sided flag. TRUE = on; FALSE = off
 Miscellaneous Viewport Methods and System Globals 1613

rendAtmosphere -- boolean
Get/set the renderer’s uses atmospheric effects flag. TRUE = on; FALSE = off
rendDitherTrue -- boolean
Get/set the renderer’s dither true color flag. TRUE = on; FALSE = off
rendDither256 -- boolean
Get/set the renderer’s dither 256 color flag. TRUE = on; FALSE = off
rendMultiThread -- boolean
Get/set the renderer’s multi-threaded flag. TRUE = on; FALSE = off
rendNThSerial -- boolean
Get/set the output file sequencing nth serial numbering setting. TRUE = on; FALSE = off
rendVidCorrectMethod -- integer
Get/set the video color check method. One of the following values:
1 = FLAG
2 = SCALE_LUMA
3 = SCALE_SAT
rendFieldOrder -- integer
Get/set the rendering field order. One of the following values:
1 is Even
2 is Odd
rendNTSC_PAL -- integer
Get/set the video color check NTSC or PAL setting. One of the following values:
1 is NTSC
2 is PAL
rendSuperBlackThresh -- integer
Get/set the super black threshold setting. Range 0 to 255.
rendFileNumberBase -- integer
Get/set the File Number Base in the ‘Common Parameters’ rollup of the Render
Scene dialog.
rendPickupFrames -- string
Get/set the Frames string in the ‘Common Parameters’ rollup of the Render Scene dialog.
The following 3ds max system global variables are applicable to the Renderer, but corresponds to the
Gbuffer Layers Maximum Number parameter in the Rendering page of the Preference Settings
dialog:
preferences.maximumGBufferLayers
Lets you get and set an Integer value that specifies the maximum number of g-buffer layers
generated during a render.
1614 Chapter 13 | Interacting with the 3ds max User Interface

The following 3ds max system global variables are specific to 3ds max’s default scanline A-Buffer
renderer. These variables return undefined if the current renderer is not 3ds max’s default scanline
A-Buffer renderer.
scanlineRender.antiAliasFilter
Lets you get and set the anti-aliasing filter. For a list of all of the anti-aliasing filters you
can say:
showClass “*:filter*”

For example:
scanlineRender.antiAliasFilter = quadratic()

The anti-aliasing filters and their parameters are described in the 3ds max Scanline A-Buffer
Renderer Anti-Aliasing Filters (p. 1614) topic.
scanlineRender.antiAliasFilterSize
Contains a float value that defines the anti-aliasing filter size.
scanlineRender.enablePixelSampler
Lets you enables and disables global super sampling. A Boolean value - true if Disable all
Samplers is off, false if on.
Note:
Changing the render scene dialog settings via the scripter should be done with the actual
render scene dialog in a closed state. Leaving the dialog open will make the attempted
scripter modifications non-sticky.

3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters

The following Filter class values are available as 3ds max Scanline A-Buffer renderer anti-aliasing
filters. The renderer anti-aliasing filter is accessed using the following 3ds max system global
variable:
scanlineRender.antiAliasFilter
Lets you get and set the anti-aliasing filter. For a list of all of the anti-aliasing filters you
can say:
showClass “*:filter*”

For example:
scanlineRender.antiAliasFilter = quadratic()

Constructors and Properties:

Area:
Area()

Blackman:
Blackman()
 3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters 1615

Blendfilter:
Blendfilter ...
<Blendfilter>.Blend Float default: 0.3

Catmull_Rom:
Catmull_Rom()

Cook_Variable:
Cook_Variable()

Cubic:
Cubic()

Mitchell_Netravali:
Mitchell_Netravali ...
<Mitchell_Netravali>.Blur Float default: 0.3333
<Mitchell_Netravali>.Ringing Float default: 0.3333

Plate_Match_MAX_R2: (3ds max only)

Plate_Match_MAX_R2()
Plate_Match_VIZ_R2: (3D Studio VIZ only)
Plate_Match_VIZ_R2()
Quadratic:
Quadratic()

Sharp_Quadratic:
Sharp_Quadratic()

Soften:
Soften()

Video:
Video()

Schematic View
The Schematic View window functions are in a structure package named schematicView. These
functions operate on named Schematic Views, and in many cases you identify the Schematic View
window by this name. The Schematic View functions are:
schematicView.open <name_string>
Opens an existing Schematic View with the specified name, or creates a new Schematic
View with specified name. Returns the value true.
schematicView.zoomSelected <name_string>
Zooms the named Schematic View on the currently selected objects. The display is zoomed
such that all of the selected objects are displayed. If there are no selected objects, no
operation occurs. This method will return true, except when the named Schematic View
does not exist or is not open, when it returns false.
1616 Chapter 13 | Interacting with the 3ds max User Interface

schematicView.close <name_string>
Closes the named Schematic View. This method will return true, except when the named
Schematic View does not exist or is not open, when it returns false.
schematicView.numSchematicViews()
Returns the number of named Schematic Views defined
schematicView.getSchematicViewName <index_integer>
Returns the name of the indexed Schematic View as a String. Index values are 1-based.

Time Configuration Dialog

The following methods get and set options in the Time Configuration dialog:
getKeyStepsPos()
setKeyStepsPos <boolean>
Get and set whether to jump to next position key when Key Mode Toggle is on.
getKeyStepsRot()
setKeyStepsRot <boolean>
Get and set whether to jump to next rotation key when Key Mode Toggle is on.
getKeyStepsScale()
setKeyStepsScale <boolean>
Get and set whether to jump to next scale key when Key Mode Toggle is on.
getKeyStepsSelOnly()
setKeyStepsSelOnly <boolean>
Get and set whether to use Selected Objects Only when Key Mode Toggle is on.
getKeyStepsUseTrans()
setKeyStepsUseTrans <boolean>
Get and set whether to Use Current Transform when Key Mode Toggle is on.
The following 3ds max system global variables are applicable to the Time Configuration dialog:
animationRange
Lets you get and set an Interval value that defines the start and end of the current active
animation range. It contains the corresponding values set in the Time Configuration
dialog.
frameRate
Lets you get and set an Integer value that defines the current scene frame rate in frames-
per-second. It contains the corresponding value set in the Time Configuration dialog.
playActiveOnly
Lets you get and set whether to playback the active viewport only. It contains the
corresponding value set in the Time Configuration dialog. A Boolean value - true if Active
Viewport Only is on, false if off.
realTimePlayback
Lets you get and set whether to playback in real time mode. It contains the corresponding
value set in the Time Configuration dialog. A Boolean value - true if Real Time is on,
false if off.
 3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters 1617

timeConfiguration.playActiveOnly
Lets you get and set whether to playback the active viewport only. It contains the
corresponding value set in the Time Configuration dialog. A Boolean value - true if Active
Viewport Only is on, false if off.
timeConfiguration.playbackSpeed
Get/set viewport playback speed as an indexed <integer>. The valid values for theinteger
are: 1 - 1 / 4x, 2 - 1 / 2x, 3 - 1x, 4 - 2x, 5 - 4x.
timeConfiguration.realTimePlayback
Lets you get and set whether to playback in real time mode. It contains the corresponding
value set in the Time Configuration dialog. A Boolean value - true if Real Time is on,
false if off.
timeConfiguration.useTrackBar
Lets you get and set the state of the Time Configuration dialog ‘Key Steps / Use TrackBar’
check box. A Boolean Value – true if checked, false if not.

RAMPlayer
The following method is associated with the RAMPlayer:
RAMPlayer <filename1_string> <filename2_string>
Opens RAMPlayer with filename1 as Channel A and filename2 as Channel B. You can pass
a null string (““) as a filename string, in which case no file is loaded into that channel.

Track View Pick Dialog

The Track View Pick dialog displays the hierarchy for the 3ds max scene in a manner similar to what
is seen in Track View. The user can select one or more items from this dialog. The following method
displays the Track View Pick dialog:
trackView.pickTrackDlg [#multiple]
This method brings up the Track View Pick dialog and returns a TrackViewPick value when
the user selects a track and clicks “Ok”, or undefined if the user clicks “Cancel”. If the
optional argument #multiple is passed, multiple tracks can be picked in the dialog and
an array of TrackViewPick values is returned instead of single value.
TrackViewPick : Value
Instances of the TrackViewPick class store the result of a selection from the Track View Pick dialog.
A TrackViewPick value has the following properties:
<trackViewPick>.name : string
The name of the picked item as shown in the Track View Pick dialog.
<trackViewPick>.anim : subAnim
The subAnim for the item the user picked.
<trackViewPick>.client : MAXWrapper
The owner of the subAnim for the item the user picked. If the owner is a subclass of
MAXWrapper, the MAXWrapper value for the owner is returned, otherwise a value of
undefined is returned.
1618 Chapter 13 | Interacting with the 3ds max User Interface

<trackViewPick>.subNum : integer
The subAnim index for anim in client.
Here is an example:
-- Create a sphere and apply a bend modifier and execute
tvp=trackview.pickTrackDlg()
-- pick objects->Sphere01->Modified object->Bend->Angle
tvp.anim -- returns SubAnim:Angle
tvp.client -- returns Bend:Bend
tvp.subNum -- returns 3
tvp.name -- returns “Angle”
tvp.client[tvp.subNum] -- returns SubAnim:Angle

Picking Scene Nodes

Picking Scene Nodes By Hit

pickObject [ message:<string> ] [ prompt:<string> ] \
[count:n|#multiple] [ filter:fn ] \
[ select:<boolean> ]
The pickObject() function lets the user pick one or more scene objects in the 3ds max
viewports. It takes several optional keyword arguments. The message: argument takes a
string value which is displayed in the status bar prompt line. The prompt: argument takes
a string value which is displayed in the Listener window. The count: argument takes
either a positive integer or the symbol #multiple to specify how many objects are to be
picked (default is 1). If the count specified is greater than 1 or the value #multiple, an
array is returned containing the picked objects. The symbol #multiple indicates that any
number of objects can be selected and the user terminates the selection with a right mouse
click or, if the Listener window has focus, any character key of the keyboard. If the ESC key
is pressed while the Listener windows has focus, an #escape value will be returned. If the
ESC key is pressed while a viewport has focus, selection is terminated and the selection
result is returned.
If #multiple was specified, and no objects had been selected when the selection was
terminated, an empty array is returned. If #multiple was not specified, and an object had
not been selected when the selection was terminated, a value of undefined is returned.
 Picking Scene Nodes by Name 1619

The filter: function takes a MAXScript function of one argument that is called
whenever the cursor is over an object in the scene and is passed that object under the
cursor. It returns true if the object is eligible for picking, or false if not. Typically, the
function would contain some object class testing, for example:
fn shapeFilt o = superClassOf o == Shape
which you could use like this:
pickObject prompt:”enter a shape” filter:shapeFilt
The optional keyword argument select: controls whether the picked objects
become the new current selection in the 3ds max scene. If you supply true for
that argument, the current selection is replaced with the objects that you pick.
The default is false in which case the picker doesn’t affect the selection set.

Picking Scene Nodes by Name

You can use the selectByName() function to open the standard 3ds max Select By Name dialog
allowing users to pick objects which are then returned as an array of MAXScript node values. The
form is:
selectByName [ title:<string> ] [ buttonText:<string> ] \
[ filter:<fn>] [ showHidden:<boolean> ] \
[ single:<boolean>]

The optional keyword arguments are interpreted as follows:

title:”string” specifies the dialog window title.
buttonText:”string” lets you specify the label text in the ‘accept’ button in the dialog.
The default value is “Select”.
filter:<fn> lets you specify a filter function that determines which objects should be
displayed in the list. This is similar to the filter functions elsewhere in MAXScript. The
function you supply should take one argument, which the current object being tested for
inclusion and the function should return true for include, false for exclude. If you don’t
specify a filter, all objects are displayed. For example, the following function limits the
choices to shape objects:
fn shape_filt obj = isKindOf obj Shape

showHidden:<boolean> controls whether hidden and frozen objects are eligible for
display. The default value is false.
single:<boolean> controls whether single or multiple objects may be selected in the
selector. The default is false, meaning multiple objects may be selected, and they are
returned in an array. If single:true is specified, a single object may be selected and is
returned directly, not in an array.
If the user cancels out of the dialog, the function returns the value undefined.
1620 Chapter 13 | Interacting with the 3ds max User Interface

Picking Scene Nodes By Region

The following methods allow you to pick one or more objects based on their position in the
viewports. All coordinates used in these methods are in Windows format, with the origin in the
upper left. The gw.getWinSizeX() and gw.getWinSizeY() methods can be used to determine the
size of the viewport in pixels. The objects to picked are filtered based on the Selection Filter specified
in the 3ds max main toolbar.
boxPickNode <box2> [crossing:<boolean>]
Returns an array of the nodes within the specified rectangular region. The <box2> value
specifies the corner in pixel values within the active viewport. If the crossing: parameter
value is true, an object only partially in the region will be picked. If false, the object
must be completely within the region to be picked. The default crossing: value is true.
For example:
boxPickNode (box2 [0,0] [1000,1000])

circlePickNode <box2> [crossing:<boolean>]

Returns an array of the nodes within the specified circular region. The <box2> value
specifies the center of the circle and a point on the circle in pixel values within the active
viewport. If the crossing: parameter value is true, an object only partially in the region
will be picked. If false, the object must be completely within the region to be picked. The
default crossing: value is true. The [left, bottom] and [right, top] components
of the box2 parameter value correspond to the center and radius points, respectively. The
box2 parameter value needs to be set up in a specific manner, as shown in the following
script:
vpCenter = (point2 (gw.getWinSizeX()) (_gw.getWinSizeY()))/2
vpQuarter = point2 (vpCenter.x/2) vpCenter.y
circleRegion = box2 0 0 0 0 -- initialize circleRegion to a box2 value
circleRegion.left = vpCenter.x -- the center of the circle
circleRegion.bottom = vpCenter.y
circleRegion.right = vpCenter.x/2 -- a point on the circle
circleRegion.top = vpCenter.y
for obj in (circlePickNode circleRegion crossing:false) do print obj.name

will print the names of all nodes completely within a circular region, where the center of
the circle is the center of the viewport and the point on the circle is located one quarter of
the distance from the edge to the center of the viewport.
fencePickNode <point2_array> [crossing:<boolean>]
Returns an array of the nodes within the specified fenced region. The fenced area is
defined by the array of point2 values. The default crossing: value is true.
 Picking Scene Nodes By Region 1621

Miscellaneous Dialogs
For methods associated with the Render Effects dialog, see the RenderEffect : MAXWrapper (p. 1347)
topic.
For methods associated with the Render Environment dialog, see the Atmospheric : MAXWrapper
(p. 1337) topic.
exclusionListDlg()
Displays the Exclude/Include dialog used for Lights, and returns an array of the node
names moved into the Include/Exclude list.
configureBitmapPaths()
This method puts up the Configure Bitmap Paths dialog to let the user configure the
bitmap loading paths. Returns false if the user cancels out of the Configure Bitmap Paths
dialog, true otherwise.
materialBrowseDlg [#mats] [#maps] [#incNone] [#instanceOnly]
This method puts up the Material/Map Browser. This method returns undefined if no
Material or TextureMap is picked, otherwise a copy or instance of the Material or
TextureMap is returned. The definition of the parameters are:
#mats
Display Materials only.
#maps
Display TextureMaps only.
#incNone
Include “None” as a Material and TextureMap.
#instanceOnly
If the selected Material or TextureMap already exists, the returned value contains an
instance. Otherwise a dialog is displayed for the user to specify Copy or Instance.
If neither #mats or #maps is specified, both Materials and TextureMaps are displayed. If
both are specified, TextureMaps are displayed.
mtlBrowser.browseFrom [#mtlLibrary | #mtlEditor | #activeSlot | #selected | #scene
| #new]
Lets you set the Browse From: source for the modeless material browser.
nodeColorPicker()
This method displays the Object Color picker dialog, and returns the selected color as a
Color value.
OSnap()
This method displays the Grid and Snap Settings dialog.
USetup()
This method displays the Units Setup dialog.
1622 Chapter 13 | Interacting with the 3ds max User Interface

MAXScript Message and Query Dialogs

These functions let you display a message box or a yes/no query dialogs from within MAXScript.
messageBox <message_string> [ title:<window_title_string> ] \
[ beep:<boolean> ]
displays a modal message box containing the message string and an OK button. The
message box window title an be set with the title: keyword parameter. You can control
whether a beep is made with the beep: keyword parameter, which defaults to true.
queryBox <message_string> [ title:<window_title_string> ] \
[ beep:<boolean> ]
displays a modal message box similar to the one that the messageBox() function creates,
except it contains a Yes and a No button. The queryBox() function returns true if the
user clicks Yes and false if the user clicks No.
yesNoCancelBox <message_string> [ title:<window_title_string> ] \
[ beep:<boolean> ]
displays a modal message box similar to the one that the messageBox() function creates,
except it contains a Yes, a No, and a Cancel button. The yesNoCancelBox() function
returns #yes, #no or #cancel depending on which button the user clicked to dismiss the
message box.
Examples:
messageBox “You shouldn’t have done that”
if queryBox “Do you want to continue?” beep:false then ...
Notes:
In some cases, MAXScript statements occurring after a statement containing one of the above dialog
function calls may be executed before they are supposed to be. For example, if your execute:
Script:
for _t=0 to 3 do
(
messagebox “Press Me”
format “_t= %\n” _t
)
print “Should print last”

Listener will show:

Output:
_t= 0
“Should print last”
“Should print last”
_t= 1
_t= 2
_t= 3

And the MessageBox will be displayed 4 times, once each time before the value of _t is printed
to Listener.
 Picking Scene Nodes By Region 1623

The reason for this is that Listener is looking for expressions to compile and run in a background
thread. In the above example there are 2 expressions – the for loop expression and the final print
expression. The messageBox() function goes on waiting for and processing UI events in the main
UI thread, but the compiler has already compiled ahead and scheduled the print “Should print last”.
To prevent this out-of-order execution, you need to bracket the script in parenthesis. This will force
the sequencing to be correct because the script would now contain a single expression rather
than two.

Keyboard Entry
The following are keyboard input functions for doing simple interactivity directly in the Listener or
Mini Listener. All keyboard input functions take input from Mini Listener if Listener is closed, but if
it is open, input will always be taken from Listener.
getKBValue [ prompt:<string> ]
The getKBValue() function lets the user enter a MAXScript value into the Listener. The
optional prompt: keyword argument takes a string that is displayed in the Listener as a
prompt message. Any valid MAXScript expression can be entered into the Listener and is
evaluated to become the result of the getKBValue() function. Expressions include the
literals for integer, float, string, name, array, point2, point3, and scene object pathnames,
or they can be expressions involving math operations and functions, script supplied
functions, global variables, etc. You can test the type of value returned using MAXScript’s
classOf function.
Example:
v = getKBValue prompt:”Enter object count:”
if classOf v != integer then
print “Value entered must be an integer”

The user can abort the entry by pressing the ESC key in which case the function returns
the special value #escape.
getKBLine [ prompt:<string> ]
getKBChar [ prompt:<string> ]
These functions let the user type characters into the Listener that are returned as a
MAXScript string. getKBLine() returns all the characters up until the user presses ENTER,
getKBChar() returns each character immediately as it is entered. The user can abort the
entry by pressing the ESC key in which case the function returns the special value
#undefined.
getKBPoint [ prompt:<string> ]
This function lets the user type in a 3D point in the syntax supported by the
pickPoint() function. See the pickPoint() description above for details about the
syntax. The function interprets the 3D point as relative to the current active grid
construction plane and returns a Point3 in world-coordinates.
1624 Chapter 13 | Interacting with the 3ds max User Interface

The following are system global variables related to the keyboard:

keyboard.shiftPressed
keyboard.controlPressed
keyboard.altPressed
These variables access the current state of the keyboard shift keys and return true or
false depending on the pressed state of the key at the time the variable is read and are
read-only variables.

Macro Scripts
The Macro Script functions are in a structure package named macros. These functions allow you to
access and run Macro Scripts. See the Defining Macro Scripts (p. 1521) topic for information on
creating Macro Scripts. The Macro Script functions are:
macros.load [ <path_name_string> ]
Loads all of the Macro Script definition (.mcr) files in the current UI directory path, or in
directory path specified by <path_name_string>. You can get the current UI directory
path with the function:
local ui_dir = cui.getDir ()

macros.new <name_string> <category_string> <toolTip_string> \

<buttonText_string> <body_string>
Creates a new Macro Script with the specified name and category. Returns an Integer
Macro Script ID value that uniquely identifies the new Macro Script. See the Defining Macro
Scripts (p. 1521) topic for a description of Macro Script definitions.
macros.run <category_string> <name_string>
macros.run <macro_id_integer>
Executes the specified Macro Script. The Macro Script is identified by either its category
and name, or by its unique Macro Script ID value.
macros.edit <category_string> <name_string>
macros.edit <macro_id_integer>
These methods will open the Macro Script definition (.mcr) file that defines the specified
Macro Script in a script Editor window. The Macro Script is identified by either its category
and name, or by its unique Macro Script ID value.
Example:
macros.load “f:/gametools/macros”
macros.edit “objects” “box”
macros.run 132
macros.run “modifiers” “bend”
 Picking Scene Nodes By Region 1625

3ds max System Directories

The following methods allow you to access the 3ds max system directories:
GetDir <filetype_name>
Returns as a string the directory specified in the Customize > Configure Paths dialog for
the specified file type. The valid <filetype_name> values are:
#autoback
#drivers
#export
#expression
#font
#help
#image
#import
#matlib
#maxroot
#maxstart
#plugcfg
#preview
#scene
#scripts
#sound
#startupScripts
#ui
#vpost

The following functions let you get, add or delete Bitmap and XRef paths, corresponding to the
Bitmaps and XRefs tabs in the Configure Paths dialog in 3ds max. Any changes made through these
functions are immediately reflected in the 3dsmax.ini file and so are persistent.
mapPaths.add <path_string>
Appends the specified path to the list of Bitmap search paths.
mapPaths.count()
Returns the number of Bitmap search paths defined.
mapPaths.get <index>
Returns the indexed Bitmap search path as a string. The index is 1-based.
mapPaths.delete() <index>
Deletes the indexed Bitmap search path. The index is 1-based.
sysinfo.getSystemMemoryInfo()
Returns a 7 element array containing system memory status data. The array elements
contain the following, respectively:
percent of memory in use
bytes of physical memory
free physical memory bytes
bytes of paging file
1626 Chapter 13 | Interacting with the 3ds max User Interface

free bytes of paging file

user bytes of address space
free user bytes
Example:
(
r=sysinfo.getSystemMemoryInfo()
for i=2 to 7 do r[i] /= (1024*1024.)
format “percent of memory in use:\t%\n” r[1]
format “total physical memory:\t% MB\n” r[2]
format “free physical memory:\t% MB\n” r[3]
format “used physical memory:\t% MB\n” (r[2]-r[3])
format “total paging file size:\t% MB\n” r[4]
format “free paging file size:\t% MB\n” r[5]
format “used paging file size:\t% MB\n” (r[4]-r[5])
format “total virtual memory:\t% MB\n” r[6]
format “free virtual memory:\t\t% MB\n” r[7]
format “used virtual memory:\t\t% MB\n” (r[6]-r[7])
ok
)

Returns:
percent of memory in use:0
total physical memory:255.359 MB
free physical memory:16.5156 MB
used physical memory:238.844 MB
total paging file size:1016.3 MB
free paging file size:757.898 MB
used paging file size:258.398 MB
total virtual memory:2047.88 MB
free virtual memory:1846.55 MB
used virtual memory:201.328 MB
OK

sysinfo.getMAXMemoryInfo()
Returns a 9 element array containing 3ds max memory status data. The array elements
contain the following, respectively:
Page Fault Count
Peak Working Set Size
Working Set Size
Quota Peak Paged Pool Usage
Quota Paged Pool Usage
Quota Peak NonPaged Pool Usage
Quota NonPaged Pool Usage
Pagefile Usage
Peak Pagefile Usage
 Picking Scene Nodes By Region 1627

Example:
(
r=sysinfo.getMAXMemoryInfo()
for i=2 to 9 do r[i] /= (1024*1024.)
format “Page Fault Count:\t\t\t%\n” r[1]
format “Peak Working Set Size:\t\t% MB\n” r[2]
format “Working Set Size:\t\t\t% MB\n” r[3]
format “Quota Peak Paged Pool Usage:\t% MB\n” r[4]
format “Quota Paged Pool Usage:\t\t% MB\n” r[5]
format “Quota Peak NonPaged Pool Usage:\t% MB\n” r[6]
format “Quota NonPaged Pool Usage:\t\t% MB\n” r[7]
format “Pagefile Usage:\t\t\t% MB\n” r[8]
format “Peak Pagefile Usage:\t\t\t% MB\n” r[9]
ok
)

Returns:
Page Fault Count:32948
Peak Working Set Size:70.3594 MB
Working Set Size:70.3594 MB
Quota Peak Paged Pool Usage:0.166186 MB
Quota Paged Pool Usage:0.161236 MB
Quota Peak NonPaged Pool Usage:0.0213509 MB
Quota NonPaged Pool Usage:0.0213509 MB
Pagefile Usage:58.9023 MB
Peak Pagefile Usage:58.9219 MB

xrefPaths.add <path_string>
Appends the specified path to the list of XRef search paths.
xrefPaths.count()
Returns the number of XRef search paths defined.
xrefPaths.get <index>
Returns the indexed XRef search path as a string. The index is 1-based.
xrefPaths.delete <index>
Deletes the indexed XRef search path. The index is 1-based.
1628 Chapter 13 | Interacting with the 3ds max User Interface

3ds max Scene File Properties

The File Properties can be accessed in MAXScript using the methods described in this topic. The File
Properties are organized into three sets. These sets do directly does not correspond to the three pages
in File Properties dialog. The three sets are:
#summary
This set contains the Title, Subject, Author, Keywords, Comments fields from the
Summary page.
#contents
This set contains the Manager, Company, Category and an array of all headers from the
Contents page like General, Mesh Totals etc. Note that the Contents page contents are
only update when the file is saved. You can perform a max hold to perform a scene hold,
which causes the file to be saved and the Contents page contents to be updated.
#custom
This set contains all the fields from the Custom page.
The following methods are used to access the above sets. <set_name> can be any of the values from
above.
fileProperties.getNumProperties <set_name>
Returns the number of properties in the given set. For example:
numProps=fileProperties.getNumProperties #summary

fileProperties.getPropertyName <set_name> <index>

Returns as a string the property name of the given index. The index is 1-based.
For example:
nameProp=fileProperties.getPropertyName #summary 1

fileProperties.getPropertyValue <set_name> <index>

Returns the property value of given index. The value type can be one of the following four
types of values currently supported by 3ds max in the File Properties dialog. The values in
bracket are the MAXScript equivalent value type.
Property Value Types:
Text [String]
Date [String] - contains the date eg:”03/23/99”
Number [Integer or Float based on actual value]
Yes or No [Boolean]
Headers [Array of strings]

Headers are items like General, Mesh Totals, etc. that appear in contents page. For
example, an array of headers from contents page obtained using:
getPropertyValue #contents “Headers”

will return
#(”General”, “Mesh Totals”,…)
 Picking Scene Nodes By Region 1629

fileProperties.getItems <header_string>
Returns an array of strings containing all the items under the given header. For example,
fileProperties.getItems “Mesh Totals”

might return
#(”Vertices: 488”, “Faces: 968”)

fileProperties.findProperty <set_name> <prop_name_string>

Given the set name and property name string, will return the index of the property if
found, 0 if not found. For example:
fileProperties.findProperty #custom “BoolVal”

fileProperties.addProperty <set_name> <prop_name_string> \

<prop_value> [#date]
Adds a new property with the property name and property value to the specified set. The
property values can be any of the types previously described except an Array as you cannot
add anything to contents page.
If string containing a date is passed then the optional #date argument has to be passed for
it to be added as a date value. For example,
fileProperties.addProperty #custom “DateVal” “03/23/99” #date

will add a date property named DateVal to the custom page.

fileProperties.deleteProperty <set_name> <prop_name_string>
Delete the property indicated by <prop_name_string> in the specified set.
Following is an example of printing all the File Properties in an hierarchial fashion for the
current scene.
Script:
-- Add some properties
fileProperties.addProperty #summary “Title” “Title val”
fileProperties.addProperty #custom “IntVal” 30
fileProperties.addProperty #custom “FloatVal” 30.034
fileProperties.addProperty #custom “BoolVal” true
fileProperties.addProperty #custom “DateVal” “03/23/99” #date
--
-- Perform a scene hold to update the Contents set.
max hold
--
-- Get all properties
pages = #(#summary, #contents, #custom)
for pg in pages do
(
format “--- % ---\n” (pg as string)
for i=1 to (fileProperties.getNumProperties pg) do
(
local pname = (fileProperties.getPropertyName pg i)
local pval = (fileProperties.getPropertyValue pg i)
1630 Chapter 13 | Interacting with the 3ds max User Interface

format “\t% : “ pname

if (pname == “Headers”) then
(
format “\n”
for hdr in pval do
(
format “\t\t%\n” hdr
local docs = fileProperties.getItems hdr
if docs != undefined then
for d in docs do format “\t\t\t%\n” d
)
)
else format “ %\n” pval
)
)

3ds max Commands

The general syntax for 3ds max commands is:
max <command_name>

MAXScript allows you to invoke 3ds max menu and toolbar commands from within scripts using
the max construct. For example:
max file open
max unhide all
max hold
max time play

The keyword max is followed by one or more words that describe the command. The available
commands can be displayed using the ‘?’ character in a partial max command:
max time ? -- show all the time-related commands
max sel ? -- show all the commands with ‘sel’ in them as a substring
max ? -- show all the commands (there are a lot!)

The max command always returns the system value ok.

 Picking Scene Nodes By Region 1631

Note: The max spacebar max command appears to do nothing when invoked from the Listener
window, because the spacebar command is window-specific and only locks selections in the active
window. Because it is the Listener window that is active, 3ds max effectively ignores this command.

3ds max Command Name Command description

max ? Displays all max commands to listener
max accel pan Activates viewport Pan mode
max acthomegrid Makes home grid the active grid
max activate home grid
max activate grid object Makes selected grid the active grid
max adaptive persp grid Changes look of grid in non-orthographic viewports.
max adaptive perspective grid toggle
max align Activates Align mode
max align normals Activates Align Normals mode
max alignnormals
max align camera Places you in Align Camera mode
max angle snap toggle Toggles Angle Snap toggle
max apply ik Same as clicking Apply IK button in Hierarchy/IK panel
max array Displays Array dialog
max backface Toggles Backface Cull for selected objects
max backface cull toggle
max background Displays Viewport Background dialog
max background display toggle
max bind space warp mode Activates Bind to Space Warp mode
max bindwsm
max box mode Toggles Display as Box for selected objects
max box mode selected
max box mode toggle Toggles active viewport’s shading mode to/from Bounding Box
max box toggle
max configure paths Displays Configure Paths dialog
max create mode Sets Create command mode active
max customize UI Displays Customize User Interface dialog
max cycle select Cycles through Selection Region types – Rectangular, Circular, Fence
max cycle sublevel Cycles through sub-object levels. Must be in Modify panel with
max cycle subobject level Sub-Object active.
max default lighting toggle Toggles between default viewport lights and scene lights for viewport
max def lgt toggle rendering
max delete Deletes selected objects or sub-objects
max display floater Displays Display Floater dialog
max display mode Sets Display command mode active
1632 Chapter 13 | Interacting with the 3ds max User Interface

3ds max Command Name Command description

max dolly Activates Zoom/Dolly mode
max dolly mode
max drawingaids Displays Grid and Snap Setting dialog
max drawing aids
max fetch Activates Edit/Fetch – displays About to Fetch dialog
max file archive Activates File/Archive – performs a scene file archive operation
max file export selected Activates File/Export Selected – displays Select File to Export dialog
max file import Activates File/Import – displays Select File to Import dialog
max file insert tracks Activates File/Merge – displays Merge Animation dialog
max file merge Activates File/Merge – displays Merge File dialog
max file new Activates File/New
max file open Activates File/Open – displays Open File dialog
max file preferences Activates Customize/Preferences – displays Preference Settings dialog
max file replace Activates File/Replace – displays Replace File dialog
max file save Activates File/Save
max file saveas Activates File/Save As – displays Save File As dialog
max file xref object Activates File/XRef Objects - displays XRef Objects dialog
max file xref scene Activates File/XRef Scenes - displays XRef Scenes dialog
max fov Activates Region Zoom/FOV/Falloff mode
max freeze inv Freezes non-selected objects. Same as clicking Freeze Unselected in
Display panel.
max freeze selection Freezes selected objects. Same as clicking Freeze Selected in Display
panel.
max fullinteract No operation
max grid nudge down Nudges active grid down
max grid nudge up Nudges active grid up
max grid toggle Toggles display of active grid in active viewport
max grids align Aligns active grid to active viewport
max group attach Enters Attach Object to Group mode – user clicks on group to attach
selected objects to the group
max group close Closes active group
max group detach Detaches selected objects from group
max group group Groups selected objects – displays Group dialog
max group open Opens selected group
max group ungroup Ungroups objects in selected group
max help about Activates Help/About – displays the About 3ds max dialog
max hide camera toggle Toggles Camera in Hide by Category rollout in Display panel.
max hide command panel toggle Toggles display of command panel
 Picking Scene Nodes By Region 1633

3ds max Command Name Command description

max hide floating toolbars toggle Toggles display of floating toolbars
max hide helper toggle Toggles Helpers in Hide by Category rollout in Display panel.
max hide inv Hides un-selected objects. Same as clicking Hide Unselected in Display
panel.
max hide light toggle Toggles Lights in Hide by Category rollout in Display panel.
max hide main toolbar toggle No operation
max hide object toggle Toggles Geometry in Hide by Category rollout in Display panel.
max hide tab panel toggle Toggles display of Tab Panel
max hide selection Hides selected objects. Same as clicking Hide Selected in Display panel.
max hide shape toggle Toggles Shapes in Hide by Category rollout in Display panel.
max hide system toggle Toggles Particle Systems in Hide by Category rollout in Display panel.
max hide wsm toggle Toggles Space Warps in Hide by Category rollout in Display panel.
max hierarchy mode Sets Hierarchy command mode active
max hold Activates Edit/Hold
max ik terminator Toggles Terminator in Hierarchy/IK, Object Parameters rollout
max ipan Interactive Pan – places center of active viewport at current mouse
location
max izoom in Interactive Zoom In – zooms in active viewport at current mouse
location
max izoom out Interactive Zoom Out – zooms out active viewport at current mouse
location
max key mode Toggles Key Mode Toggle
max link Activates Link mode
max load custom UI Activates Customize/Load Custom UI – displays Load UI File dialog
max lock UI layout Toggles locking of the UI layout
max material browser Displays the Material/Map Browser dialog
max mirror Activates Mirror mode – displays Mirror dialog
max modify mode Sets Modify command mode active
max motion mode Sets Motion command mode active
max move Activates Select and Move mode
max mtledit Activates Tools/Material Editor – displays Material Editor dialog
max next mod Moves up one level in modifier stack
max override Toggles Degradation Override. Executing this command works on the
active window only, so if executed from Listener does nothing.
max pancamera Activates Arc Rotate/Orbit mode
max panview Activates Pan/Truck mode
max persp Activates Zoom All/Perspective/Hotspot mode
max prev mod Moves down one level in modifier stack
1634 Chapter 13 | Interacting with the 3ds max User Interface

3ds max Command Name Command description

max preview Activates Rendering/Make Preview – displays Make Preview dialog
max properties Displays Object Properties dialog
max quick render Performs Quick Render
max redo Performs Redo operation
max renamepreview Activates Rendering/Rename Preview – displays Save Preview As dialog
max render last Performs Render Last
max render scene Activate Render Scene – displays Render Scene dialog
max reset file Activates File/Reset
max revert custom UI Activates Customize/Revert to Startup UI – displays confirmation dialog
max rns Activates Edit/Edit Named Selections – displays Edit Named Selection
dialog
max roll Activates Roll mode – active viewport must camera or light viewport
max rotate Activates Select and Rotate mode
max rotateview Activates Arc Rotate/Orbit mode
max save custom UI as Activates Customize/Save Custom UI As - displays Save UI File as dialog
max safeframe toggle Toggles viewport Show Safe Frames
max saveplus Activates File/Save As in incremental file naming mode
max scale Activates Select and Scale mode
max scale cycle Cycles through Scale modes – Scale, Non-Uniform Scale, Squash
max select Activates Select mode
max select all Activates Edit/Select All – selects all objects
max select by color Activates Edit/Select by Color – user then picks object, all objects with
same wireframe color selected
max select child Selects all 1st level children of currently selected objects
max select invert Activates Edit/Select Invert
max select none Activates Edit/Select None
max select parent Selects parents of currently selected objects
max selection floater Displays Selection Floater dialog
max shade selected Toggles Views/Shade Selected
max show last img Displays last rendered image
max showaxisicon Toggles Views/Show Transform Gizmo
max showhomegrid Toggles display of home grid
max snap toggle Toggles Snap Toggle
max spacebar Toggles Lock Selection Set. Executing this command works on the active
window only, so if executed from Listener does nothing.
max spacing tool Displays Spacing Tool dialog
max spinsnap toggle Toggles Spinner Snap Toggle
max subobject sel Toggles Sub-Object button in Modify panel
 Picking Scene Nodes By Region 1635

3ds max Command Name Command description

max swap layouts No operation – no A/B layout any more
max texture correct Toggles viewport Texture Correction
max time back Sets time slider to previous frame or keyframe (Previous Frame/Previous
Key)
max time config Displays Time Configuration dialog
max time end Sets time slider to end frame (Go to End)
max time forward Sets time slider to next frame or keyframe (Next Frame/Next Key)
max time play Plays animation
max time start Sets time slider to start frame (Go to Start)
max toggle key mode No operation
max toggle keyboard shortcuts Toggles Plug-in Keyboard Shortcut Toggle
max toggle ik Toggles IK Toggle
max toggle sound Toggles Active in Audio group of Sound Options dialog
max tool animmode Taggles Animate button
max tool center Cycles through transform centers – Pivot Point, Selection, Transform
max tool dualplanes Toggles state of Use Dual Planes in Preference Settings dialog, Viewports
tab.
max tool hlist Activates Select by Name – displays Select Objects dialog
max tool maximize Maximizes/Minimizes active viewport
max tool x Activates Restrict to X
max tool xy Activates Restrict to XY
max tool y Activates Restrict to Y
max tool z Activates Restrict to Z
max tool zoom Activates Zoom/Dolly mode
max tool zoomall Activates Zoom All
max tool zoomextents Activates Zoom Extents
max tool zoomextents all Activates Zoom Extents All
max tool zoomregion Activates Zoom Region/FOV/Falloff mode
max trajectories Toggles trajectory display for selected objects
max treeview Activates Track View/Open Track View – displays Track View dialog
max truck Activates Pan/Truck mode
max tti Activates Tools/Transform Type-In – display Transform Type-In dialog
max undo Performs undo operation
max unfreeze all Unfreezes all objects. Same as clicking Unfreeze All in Display panel.
max unfreeze by hit Activates Unfreeze by Hit mode. Same as clicking Unfreeze by Hit in
Display panel.
max unfreeze by name Displays Unfreeze Objects dialog. Same as clicking Unfreeze by Name in
Display panel.
1636 Chapter 13 | Interacting with the 3ds max User Interface

3ds max Command Name Command description

max unhide all Unhides all objects. Same as clicking Unhide All in Display panel.
max unhide by name Displays Unhide Objects dialog. Same as clicking Unhide by Name in
Display panel.
max unitsetup Activates Customize/Units Setup – displays Units Setup dialog
max unlink Unlinks selected objects from their parents
max utility mode Sets Utility command mode active
max videopost Activates Rendering/Video Post – displays Video Post dialog
max view file Activates File/View File – displays View File dialog
max view redo Performs viewport redo operation
max viewpreview Activates Rendering/View Preview – displays last preview
max views redraw Redraws all viewports
max views undo Performs viewport undo operation
max vpt back Sets active viewport to Back
max vpt bottom Sets active viewport to Bottom
max vpt camera Sets active viewport to Camera. If only 1 camera in scene, or a camera is
selected, that camera will be used for the viewport. If there is more than
one camera, and no cameras are selected, the Select Camera dialog will
be displayed. If there is no camera in the scene, a No Camera in Scene
warning is displayed.
max vpt disable Toggles Disabled state of active viewport
max vpt front Sets active viewport to Front
max vpt grid Sets active viewport to Grid
max vpt iso user Sets active viewport to User
max vpt left Sets active viewport to Left
max vpt persp user Sets active viewport to Perspective
max vpt right Sets active viewport to Right
max vpt shape Sets active viewport to Shape
max vpt spot Sets active viewport to Spotlight. If only 1 spotlight/directional light in
scene, or a spotlight/directional light is selected, that light will be used
for the viewport. If there is more than one spotlight/directional light,
and no lights are selected, the Select Light dialog will be displayed. If
there is no spotlight/directional light in the scene, a No Light in Scene
warning is displayed.
max vpt tab Cycles between Restrict to axes – X, Y, Z, XY
max vpt top Sets active viewport to Top
max vpt track Sets active viewport to Track View
max vptconfig Activates Customize/Viewport Configuration - displays Viewport
Configuration dialog
max wire facet Sets active viewport shading mode to Facets + Highlights
max wire smooth Sets active viewport shading mode to Wireframe

3ds max Command Name
max zoom in 2x
max zoom in 2x all
max zoom out 2x
max zoom out 2x all
max zoomext sel
max zoomext sel all
Picking Scene Nodes By Region 1637
Command description
Zooms in active viewport by 2x
Zooms in all viewports by 2x
Zooms out active viewport by 2x
Zooms out all viewports by 2x
Activates Zoom Extends Selected
Activates Zoom Extends All Selected
1638 Chapter 13 | Interacting with the 3ds max User Interface
Chapter 14: File Access

3ds max File Loading and Saving

The following methods are used to load, save, merge, import, and export 3ds max scenes.
loadMaxFile <filename_string>
Returns true if the file was found and loaded successfully.
mergeMAXFile <filename_string> [ <name_array> ] [ #prompt ] \
[ [ #select ] #noRedraw ] \
[ #deleteOldDups | #mergeDups | #skipDups | #promptDups ]
All arguments are optional except the initial file name. The flag arguments can be specified
in any order. The arguments details are as follows:
<name_array>
An optional array of names or strings identifying the objects in the source scene file to
be merged; all objects are merged if not specified.
#prompt
If specified causes the standard merge dialog to be opened.
#select
If specified causes the newly merged objects to be selected when merged.
#noRedraw
If specified causes the screen redraw to be delayed in case you want to call
mergeMAXFile several times and delay the redraw until after the last file merge.
#deleteOldDups
Deletes existing scene objects with the same names as incoming objects, equivalent to
a replace.
#mergeDups
Ignore name conflicts, merge anyway resulting in possibly duplicated names.
1640 Chapter 14 | File Access

#promptDups
Throw up the duplicates resolution dialog for the user to choose.
Returns true if the file was found and loaded successfully.
If you don’t specify a full path name, the file is looked for in the 3ds max scene directory,
then in the 3ds max executable directory, and then in the PATH environment directories.
getMAXSaveFileName filename: <seed_filename_string>
Displays standard 3ds max file save dialog, returns file name or value ‘undefined’ if
canceled.
getMAXOpenFileName filename: <seed_filename_string> dir:<seed_directory_string>
Displays standard 3ds max file open dialog, returns file name or value ‘undefined’ if
canceled.
getMAXFileObjectNames <max_filename_string>
Returns an array of names, one for each of the names of the objects in the given 3ds max
file. This provides a way to get a preview list of the objects in another scene file (by name)
to set up user selection of the objects to be merged under script control using the
mergeMAXFile() function, for example.
Example:
p=[1000,1000,1000]
for i = 1 to 5 do box pos:(random p -p) -- create some boxes
savemaxfile “mergetest.max” -- save to file
for obj in objects do obj.name = “_”+obj.name -- rename the boxes
objects.pos += [0,-1000,0] -- move them off to the side
fobj_names = getmaxfileobjectnames “mergetest.max” -- get the object names from the
file
deleteitem fobj_names 3 -- delete the third name from the array
mergemaxfile “mergetest.max” fobj_names #select -- merge in the objects and select
them
selection.count -- should be 4
objects.count -- should be 9

saveMaxFile <filename_string>
Saves the scene to the current 3ds max scene directory if there is no explicit directory path
on the supplied file name. If no filename extension is specified, “.max” is automatically
appended to the filename.
holdMaxFile()
Equivalent to the 3ds max Edit > Hold operation.
fetchMaxFile()
Equivalent to the 3ds max Edit > Fetch operation.
importFile <filename_string> [ #noPrompt ]
Lets you import files using any of the import plug-ins that are available. The kind of file
imported is determined by the file name suffix such as DFX for .dxf, 3DS DOS for .3ds, etc.
The #noPrompt flag prevents any configuration or control dialogs from being displayed in
which case the default configuration is used.
 Bitmap Files 1641

exportFile <filename_string> [ #noPrompt ]

Lets you export files using any of the export plug-ins that are available. The kind of file
exported is determined by the file name suffix such as DFX for .dxf, 3DS DOS for .3ds, etc.
The #noPrompt flag prevents any configuration or control dialogs from being displayed in
which case the default configuration is used.
saveNodes <node_collection> <filename_string>
Creates a new .max scene file with the given name and stores the node collection to it. The
<node_collection> argument can be a single node, an array of nodes you gathered, a
wild-card path name, one of the built-in objects sets such as selection or lights, or a
<node>.children array. If no filename extension is specified, “.max” is automatically
appended to the filename.
checkForSave()
If the scene has been modified since the last file save (if any), calling this function displays
the message box prompting the user that the scene has been modified and requests to
save. Function returns false if the user cancels out of the save, true otherwise.

See also
External File Methods (p. 1645)
File Name Parsing (p. 1644)
Standard Open and Save File Dialogs (p. 1643)

Bitmap Files
The following method is used to collect a list of the bitmap files used in a scene. For the properties
and methods associated with bitmap values, including reading and writing bitmap files, see the
Bitmap Values (p. 755) topic.
enumerateFiles [ <maxwrapper_obj> ] <function> [ <arg> ] \
[ #inactive ] [ #videoPost ] [ #render ] [ #missing ] \
[ #localOnly ]
Lets you run through all the bitmap files currently used in the scene or in an individual
object. You can filter this so it just gives you those for video post or the renderer or the
ones that are inactive or missing.
The enumerator works by calling a function you give it once for each of the file names it
finds corresponding to the filters switches and other arguments you set.
The only required argument is the <function> argument. The details are:
<maxwrapper_obj>
An optional 3ds max object, such as a node or a material. Supplying this argument
causes the enumerator to only consider files associated with this object. See the
#localOnly switch for more info.
1642 Chapter 14 | File Access

<function>
The function to be called for each file found. It should be a function of one or two
arguments, the first one is the string file name supplied by the enumerator. See
example below.
<arg>
If specified is passed to the <function> as its second argument by the enumerator.
This is useful if you have a general purpose enumerator function that can be
conditioned by the argument you pass in on a particular enumeration, or if you want
to pass in an array that the found names should be appended to.
#inactive
Include the inactive files.
#videoPost
Include the files used in video post.
#render
Include the files used during rendering.
#missing
include files that are missing in the file system
If you don’t specify any of the above filter flags, all the files are enumerated.
#localOnly
use in conjunction with the <maxwrapper_obj> argument. If specified, limits the
enumeration to those files used directly in the object, if not then any referenced
objects are scanned.
For example:
function get_names name a = append a name
files = #()
enumerateFiles get_names files #missing

Example:
The following script will print out a sorted list of all the bitmap files used in the current scene file:
Script:
(
local mapfiles=#()
fn addmap mapfile =
( local mapfileN=mapfile as name
local index=finditem mapfiles mapfileN
if index == 0 do append mapfiles mapfileN
)
enumeratefiles addmap
sort mapfiles
for mapfile in mapfiles do print (mapfile as string)
)
 XRef Files 1643

By replacing line 8 with

enumeratefiles addmap #missing
only the missing bitmap files will be printed.

See also
External File Methods (p. 1645)
File Name Parsing (p. 1644)
Standard Open and Save File Dialogs (p. 1643)

XRef Files
See the XRefObject (p. 1037) and XRefScene (p. 1038) topics for information on XRef object and XRef
scene files.

Text File Input and Output

See the FileStream Values (p. 763) topic for information on creating, opening, closing, and accessing
external text files.

Standard Open and Save File Dialogs

The following methods display the standard 3ds max file open, file save, or folder selection
browser dialog:
getOpenFileName [ caption:<title> ] \
[ filename:<seed_filename_string> ] \
[ types:<description1>|<pattern1>|<description2>|<pattern2>|...| ]

getSaveFileName [ caption:<title>] \
[ filename:<seed_filename_string> ] \
[ types:<description1>|<pattern1>|<description2>|<pattern2>|...| ]

Both functions return a fully-specified file path name or undefined if the user cancels
out. The types: parameter lets you specify custom file types and suffixes for the file type
drop-down list in the open and save dialogs. You supply a string for this argument that is
formatted in a special way, as follows:
“<description1>|<pattern1>|<description2>|<pattern2>|...|”
1644 Chapter 14 | File Access

In other words, a sequence of file type descriptions and file type patterns each separated by
a ‘|’ vertical bar and terminated by a ‘|’ vertical bar. For example:
f = getOpenFileName \
types:”Data(*.dat)|*.dat|Excel(*.csv)|*.csv|All|*.*|”

Specifies three types in the file type drop-down list, the first reading “Data(*.dat)” and
matching *.dat and the second reading “Excel(*.csv)” and matching *.csv and the third
reading “All” and matching any file.
The getSaveFileName() function tests for the pre-existence of the file with the chosen
file type suffix added.
getSavePath [ caption:<window_caption_string> ]
This function displays a folder selection browser for the user to select a folder. Returns a
string path name for the selected folder or the value undefined if the user presses Cancel
in the folder browser.

See also
Filestream Values (p. 763)
External File Methods (p. 1645)
File Name Parsing (p. 1644)

File Name Parsing

filenameFromPath <filename_string>
Returns the file name and extension of a full file name, useful for labeling file buttons in
rollout panels.
getFilenamePath <filename_string>
Returns the directory path part of a full file name.
getFilenameFile <filename_string>
Returns the file name part of a full file name.
getFilenameType <filename_string>
Returns the type extension part of a full file name.
doesFileExist <filename_string>
Returns true if the file exists, false otherwise
Examples:
file=”g:\\subdir1\\subdir2\\myImage.jpg”
filenameFromPath file -- returns: “myImage.jpg”
getFilenamePath file -- returns: “g:\subdir1\subdir2\”
getFilenameFile file -- returns: “myImage”
getFilenameType file -- returns: “.jpg”
 External File Methods 1645

See also
Filestream Values (p. 763)
External File Methods (p. 1645)
Standard Open and Save File Dialogs (p. 1643)

External File Methods

getFiles <wild_card_filename_string>
Returns an array of file names that match the given wild-card path name. The following
example gets an array of all the .max scene files in c:\foo and then loops over the array,
opening each file and printing the objects in each:
files = getFiles “c:\\foo\\*.max”
for f in files do (loadMAXFile f; print objects)

getFiles() can also be used to determine if a file exists. For example, the following
function will return true if the specified file name exists:
fn existFile fname = (getfiles fname).count != 0

getDirectories <wild_card_directory_name_string>
Returns an array of directory paths that match the given wild-card directory path name.
makeDir <directory_path_string>
Creates a new directory with the given name. Returns true on success, false on failure.
deleteFile <filename_string>
Deletes the named file. Fails if the file is open in MAXScript. Returns true on success,
false on failure.
renameFile <old_filename_string> <new_filename_string>
Renames the old file to the new file. This can also be used to move a file between
directories. Fails if new file already exists or if the old file is open in MAXScript. Returns
true on success, false on failure.
copyFile <existing_filename_string> <new_filename_string>
Copies the existing file to the new file. Fails if the new file already exists, the new file
cannot be created, or the existing file is open in MAXScript. Returns true on success,
false on failure.
1646 Chapter 14 | File Access

getFileAttribute <filename_string> <attribute>

setFileAttribute <filename_string> <attribute> <boolean>
Get and set the attributes associated with a file. The get function returns true or false
depending on the state of the specified attribute, the set function sets the state of the
individual attribute specified (leaving other attributes as they were). The valid
<attribute> values are:
#readOnly
#hidden
#system
#directory
#archive
#temporary
#normal

getFileModDate <filename_string>
Returns a String value containing the modification date for the specified file, for example
“1/29/99 1:52:05 PM”.
getFileCreateDate <filename_string>
Returns a String value containing the creation date for the specified file.
getFileVersion <filename_string>
Returns the file and product version for the specified file, or unknown if this data is not
specified in the file. This data is typically specified only for executable and application
extension (i.e., .dll) files. For example:
GetFileVersion “g:\\3dsmax25\3dsmax.exe”

returns “2,5,0,0 2,5,0,0”

Examples:
for f in getFiles “3dsmax\\maps\\*.jpg” do deleteFile f
for d in getDirectories “D:\\foo\\*” do
for f in getFiles (d + “*.*”) do
copyFile f (”C:\\temp\\“ + getFilenameFile f + getFilenameType f)
if (getFiles “foo.max”).count == 0 then print “File missing”

See also
Filestream Values (p. 763)
File Name Parsing (p. 1644)
Standard Open and Save File Dialogs (p. 1643)
 Encrypted Files 1647

Encrypted Files
encryptFile <in_filename_string> <out_filename_string> <key_integer>
Creates an encrypted copy of the file named by <in_filename_string> using the
integer supplied as a key, naming the encrypted file <out_filename_string>.
openEncryptedFile <filename_string> <key_integer>
Opens the encrypted file using the given integer key and returns a FileStream value that
you can then do read calls on, exactly as you can on FileStreams returned from the
openFile() function.
encryptFile() and openEncryptedFile() let you encrypt a text file with your own
key and open an encrypted file via a key for reading. Among other things, you can use this
to write and read an encrypted file containing a hardware lock ID for doing authorization-
based piracy protection.
For example, here’s some code that creates an encrypted lock ID file in some
authorization process:
f = createFile “lock.tmp”
format “%” hardwareLockID to:f
close f
encryptFile “lock.tmp” “lock.dat” 5476557
deleteFile “lock.tmp”

The following code can be used to read and check the lock ID (obviously, all this is only
safe if the creation and checking scripts are themselves encrypted):
f = openEncryptedFile “lock.dat” 5476557
id = readValue f
close f
if id != hardwareLockID then
(
message “Lock ID’s don’t match”
return 0
)

Accessing INI File Keys

The following methods allow you to read and write key values in .INI files.
getINISetting <filename_string> <section_string> <key_string>
Reads an INI setting from the specified file. Within the file, the section identified by
<section_string> is located, and then the key specified by the <key_string> is
located. The value assigned to this key is then returned as a string. If the specified file,
section, or key is not found, a null string is returned. For example:
GetINISetting “c:\\3dsmax2\\3dsmax.ini” “Directories” “Scenes”

If the specified file, section, or key is not found, a null string is returned.
1648 Chapter 14 | File Access

setINISetting <filename_string> <section_string> <key_string> <key_value_string>

Sets an INI setting in the specified file. Returns a value of true if the key value was written
to the file, false if the key was not written. Within the file, the section identified by
<section_string> is located, and then the key specified by the <key_string> is
located. The <key_value_string> is then assigned to this key. For example:
setINISetting “c:\\3dsmax2\\3dsmax.ini” “Directories” “Scenes”
“c:\\3dsmax\\scenes”

If the specified file, section, or key is not found, a new file, section, or key is created.
If the specified file is read-only, or the file is open in MAXScript, the key value is not
written to the file.

Custom User Interface Files

The following methods provide access to Custom User Interface (CUI) files. The CUI functions are
in a structure package named cui.
cui.getDir()
Returns the directory of the currently active CUI file as a string.
cui.getConfigFile()
Returns the currently active CUI file name as a string.
cui.setConfigFile <filename_string>
Sets the currently active CUI file to the specified file name.
cui.saveConfig()
Saves the current CUI configuration data to the active .cui file
cui.saveConfigAs <filename_string>
Saves current CUI configuration data to the specified file. The specified file is made the
current CUI file.
cui.loadConfig <filename_string>
Loads the CUI configuration data from supplied file. The specified file is made the current
CUI file.
Chapter 15: Change Handlers and Callbacks

Change Handlers and Callbacks are used to detect when certain types of events occur to scene
objects or within 3ds max.
Change Handlers are applied to individual MAXWrapper objects and specify an attribute to monitor
for that object and an expression to evaluate when that attribute changes. Example attributes that
can be monitored are geometry, name, transform, and parameters. Change Handlers are not stored
in a 3ds max scene.
Callbacks are used to register with 3ds max functions that are called when specific events occur
within 3ds max. Events that can be monitored are changes to the time slider time and redrawing of
viewports. Callbacks are not stored in a 3ds max scene.
MAXScript also provides several methods that automatically tie into 3ds max’s Callback system.
These methods are used to register and unregister 3ds max scripts that are called for a variety of
3ds max events. These scripts can optionally be saved with the currently-open file and stay
permanently with it, running whenever the scene is loaded, until they are explicitly removed.
The above are described in more detail in the following topics:
Change Handlers and When Constructs (p. 1650)
Time Change Callback Mechanism (p. 1654)
Viewport Redraw Callback Mechanism (p. 1655)
RenderEffect Progress Callback Mechanism (p. 28)
General Event Callback Mechanism (p. 29)
MAXScript also allows you to register a scripted menu that is invoked when the user performs a
right-click in a 3ds max viewport. See the Scripted Right-Click Menus (p. 1514) topic for more
information.
1650 Chapter 15 | Change Handlers and Callbacks

Change Handlers and When Constructs

Change Handlers are used to detect when certain types of user events are performed on objects in
the scene, allowing you to write scripts that respond to user operations like object moves, vertex
edits, object deletions, name changes, etc.. Change Handlers are applied to individual MAXWrapper
objects and specify an attribute to monitor for that object and an expression to evaluate when that
attribute changes. Example attributes that can be monitored are geometry, name, transform, and
parameters. Change Handlers are not stored in a 3ds max scene.
The ChangeHandler : Value class instances represent change handler setups. ChangeHandler
values are created using the when construct. Each time a when construct is executed, it creates and
returns a new ChangeHandler instance. You should store this ChangeHandler value in a variable or
array so that you can dismiss the handler when it is appropriate to do so.
The when construct defines a change handler function for a certain type of event on one or more
objects. The system then automatically calls this function whenever the event occurs. The syntax of
the when construct has two forms as follows:
when <attribute> <objects> change[s] [ id:<name> ] \
[ handleAt:#redrawViews|#timeChange ] \
[ <object_parameter> ] do <expr>

when <objects> deleted [ id:<name> ] \

[ handleAt:#redrawView|#timeChange ] \
[ <object_parameter> ] do <expr> \

In the first form, the <attribute> can be one of:

topology
geometry
name[s]
transform
select
parameters
subAnimStructure
controller
children

These specify the attribute of the given object(s) to be tracked for change (see below for more details).
The second form tracks object deletion by the user or other scripts. For object deletion events, the
handler is called after the object is deleted, so you cannot perform any 3ds max operations on it.
This is typically used if you have tables or other structures containing MAXScript object values and
you want to remove deleted objects from them as the user modifies the scene.
In both forms, the <objects> argument can be one of the following:
• a single 3ds max object, such as a scene node, controller, modifier, or material, etc.
• one of the object sets, such as ‘selection’, or ‘cameras’, etc.
• a wild-card pathname like $foo*.
• an array of 3ds max objects.
 Change Handlers and When Constructs 1651

If more than one object is specified, the handler is called each time the given attribute of any of the
objects is signaled as changed by the 3ds max core.
The optional id: parameter specifies an ID for one or more handlers as a name literal. The ID name
can later be used to delete the handler and, if the same name is given to several handlers, they can
be deleted as a group.
The optional handleAt: parameter signals that the change handler expression should not be
executed immediately upon notification, but delayed until the either the 3ds max viewports are
redrawn (#redrawViews) or current 3ds max animation time is changed (#timeChange). Delaying
the processing of the change handler expression is highly recommended, as described in the
Caution section below. An example usage of the handleAt: parameter is:
when select $ changes id:#foo handleAt:#redrawViews do ...

The optional <object_parameter> lets you specify the name of a parameter variable that will be
accessible in the do <expr> and will hold the actual object that has changed. You typically specify
this parameter name if the handler will respond to changes in many objects, so you can determine
which one has changed. The <expr> can be a single expression or block expression.
Examples:
when transform $box01 changes do
$box02.pos = $box01.pos + delta

when names selection change obj do update_name_table obj

when #($foo, $baz, $bar) deleted obj do

(
messageBox “Warning!”
deleteItem obj_table (findItem obj_table obj)
)

The change attributes are interpreted as follows:

topology
signaled when the topology of an object changes in the Modify panel, such as via a mesh
smooth, optimize, or vertex delete.
geometry
signaled when the geometry of an object changes, such as by moving a vertex or via an
animated modifier.
name or names
signaled when the name of an object is changed if this occurs because a user edits the
name in one of the 3ds max command panels. The handler is called repeatedly with each
character that is changed.
transform
signaled when the transform of an object is changed, such as by a move, rotate, or scale.
select
signaled when a scene node moves into or out of the current selection set. You should
interrogate the <node>.isSelected property to determine the new state.
1652 Chapter 15 | Change Handlers and Callbacks

parameters
signaled when any parameters are changed in the object. This is something of a catch all,
because the core signals this event in many situations.
subAnimStructure
signaled when the dynamic subAnim structure changes, such as when a new vertex
becomes animated in an editable mesh, or when a new controller is added to a list
controller. Also called when subAnims are reassigned, for example, when a material is
changed in an object.
controller
signaled when a new controller is assigned to one of the object’s tracks.
children
signaled when an object has immediate children added or removed.
You can use the following two methods for deleting change handlers:
deleteChangeHandler <change_handler>
deletes specified change handler. change_handler is the value returned by a
when construct.
deleteAllChangeHandlers [ id:<name> ]
If optional id: parameter is not specified, deletes all change handlers. If optional id:
parameter is specified, deletes all change handlers with the specified id. For example:
deleteAllChangeHandlers id:#foo

For efficiency reasons, you don’t want irrelevant change handlers running in the background, so it
is essential that you delete those that you no longer need.
Special Considerations
• If a runtime error occurs in the body of a change handler while it is being executed, an error
message is displayed and that handler is permanently disabled.
• If all of the objects being tracked by a change handler are deleted, the change handler is
also deleted.
• The do <expr> change handler code is executed in a special context and not in the context of
the code that created it. This means that the <expr> code cannot contain references to local
variables in outer code nestings surrounding the when, since those variables are on an execution
stack that does not exist at the time the when handler is called. The compiler detects any illegal
references to outer locals and generates a compiler message. An important exception to this is
utility and rollout panel locals, such as local functions, rollout variables and nested rollouts. You
can refer to them in change handler code inside rollout code as they are associated directly with
their rollout or utility object.
• Change handlers are called only for user initiated events, and not for changes resulting from a
change in controller values. For example, a change handler on the transform attribute of a node
would be called when the user moves the node. If the position of the node is animated, and you
play back the animation, the transform attribute change handler is not called.
 Change Handlers and When Constructs 1653

• If you assign a change handler to an attribute on multiple objects, the change hander is called
once per object if that object’s attribute changes. For example, if you say:
when select $ changes obj do update_modifier_list obj
function update_modifier_list is called whenever any object is selected or
deselected. This is true even if you do an Edit/Select All. In this case,
update_modifier_list will be called once for each object currently selected (as the
objects are deselected), and then once for all objects in the scene (as the objects are
selected). If update_modifier_list is at all processor-intensive, a significant system
slowdown can occur.
• Change handlers are only applied to object already present in the scene. Change handlers are
not automatically applied to newly created objects.
• If you have multiple change handlers defined, the order in which the change handlers are called
is somewhat arbitrary.
• Due to the way that 3ds max internally processes notification signals, the $ form of accessing
selected objects is not recommended in a select change handler. To access the selected objects,
you should use the selection objectset. This is because $ relies on information that has not yet
been set in the selection processing whereas selection uses a different method of accessing
selections and the information it uses has been set up.
Caution:
The change handler system is based on 3ds max’s internal notification system which essentially
drives all animation and interactivity within 3ds max. There are cases when the core sends many,
many signals for the same change, so setting up change handlers on many objects that do vast
amounts of computing can significantly slow down the system. Strictly speaking, change handlers
are supposed to be used to just set “dirty flags” in a lightweight, order-independent way, and then
use Redraw Views or Time Change callbacks to actually cause the triggered processing. You should
attempt to use change handlers judiciously, and not, for example, as a simple way to get scripted
controllers. If you do find that a desired setup is being flooded with unnecessary signals, you should
use the handleAt: to delay the actual processing of the event handler script until a redrawViews or
timeChange event occurs.
1654 Chapter 15 | Change Handlers and Callbacks

Time Change Callback Mechanism

You can register one or more functions to be called whenever the current 3ds max animation time
is changed, such as when the user drags the time slider or plays the animation. The following
methods let you register and unregister these callbacks:
registerTimeCallback <fn>
unRegisterTimeCallback <fn>

You can register as many functions as you like. Each one is individually called whenever the time
changes. The functions you register must take no arguments. They can access the updated current
time through the MAXScript system variable currentTime.
Example:
fn time_p = print currentTime
registerTimeCallback time_p

In the above example, the registered function causes the current time to be printed in the Listener
window whenever the user moves the time slider or plays the animation.
Special Considerations
• If a runtime error occurs in a callback function while it is being executed, an error message is
displayed and that callback function is permanently disabled.
• The time callback is not called during rendering, even if multiple frames are rendered.
• The registered function is executed in a special context and not in the context of the code that
created it. This means that the function cannot contain references to local variables in outer
code nestings surrounding the function definition since those variables are on an execution
stack that does not exist at the time the function is called. An important exception to this is
utility and rollout panel locals, such as local functions, rollout variables and nested rollouts. You
can refer to them in change handler code inside rollout code as they are associated directly with
their rollout or utility object.
• Note that it is the function value that is being registered, not the function name or global
variable. This means that redefining the same-named function after registering it does not
change the callback. You either need to unregister, re-define the function and then register it
again, or make the registered function an intermediary which calls another function, for
example:
fn time_cb = print currentTime
fn tcb = time_cb()
registerTimeCallback tcb

In this case, the registered callback function, tcb, calls the real call back, time_cb, (by
referencing the global variable it is defined in), meaning you can redefine time_cb() as often
as you need and the callback will always invoke the latest definition. This is a useful technique
to employ while you are developing and debugging a callback.
• Callback functions remain registered after loading a new file or performing a 3ds max reset.
 Viewport Redraw Callback Mechanism 1655

Viewport Redraw Callback Mechanism

You can register one or more functions to be called whenever the 3ds max viewports are redrawn.
The following methods let you register and unregister these callbacks:
registerRedrawViewsCallback <fn>
unRegisterRedrawViewsCallback <fn>

You can register as many functions as you like. Each one is individually called whenever the
viewports are redrawn. The functions you register must take no arguments.
Example:
fn redrawviews_p = print “Viewports Redrawn”
registerRedrawViewsCallback redrawviews_p

In the above example, the registered function causes the string “Viewports Redrawn” to be printed
in the Listener window whenever the 3ds max viewports are redrawn.
Special Considerations
• If a runtime error occurs in a callback function while it is being executed, an error message is
displayed and that callback function is permanently disabled.
• The registered function is executed in a special context and not in the context of the code that
created it. This means that the function cannot contain references to local variables in outer
code nestings surrounding the function definition since those variables are on an execution
stack that does not exist at the time the function is called. An important exception to this is
utility and rollout panel locals, such as local functions, rollout variables and nested rollouts. You
can refer to them in change handler code inside rollout code as they are associated directly with
their rollout or utility object.
• Note that it is the function value that is being registered, not the function name or global
variable. This means that redefining the same-named function after registering it does not
change the callback. You either need to unregister, re-define the function and then register it
again, or make the registered function an intermediary which calls another function, for
example:
fn redrawviews_cb = print currentTime
fn rvcb = redrawviews_cb()
registerRedrawViewsCallback rvcb

In this case, the registered callback function, rvcb, calls the real call back, redrawviews_cb,
(by referencing the global variable it is defined in), meaning you can redefine
redrawviews_cb() as often as you need and the callback will always invoke the latest
definition. This is a useful technique to employ while you are developing and debugging
a callback.
• Callback functions remain registered after loading a new file or performing a 3ds max reset.
1656 Chapter 15 | Change Handlers and Callbacks

General Event Callback Mechanism

MAXScript allows you to register callback scripts for all of the notification events supported by
3ds max, such as pre/post scene file open, new, reset, scene file save, pre/post render, selection
change, etc. You can specify any number of callback scripts per notification event. Callback scripts
can be bundled into ID’d sets, and can be deleted individually or all callback scripts in and ID’d set
can be deleted. Callback scripts can be specified as persistent so that they are saved and loaded with
the currently open file.
The callbacks are maintained by the following set of functions:
callbacks.addScript <callback_type_name> \
( <script_string> | <script_stringstream> | \
fileName:<filename_string> ) \
[ id:<name> ] [ persistent:<boolean> ]
This method is used to register a new callback script. Requires as the first argument a name
that specifies which type of notify event this script is associated with. The list of valid
callback_type_name values is listed below.
The script is supplied either as a direct String or StringStream value containing the text of
the script to run, or as a fileName: keyword argument, in which case the named file is
loaded and run whenever the event notification callback occurs. You can specify either a
direct string or a fileName:, but not both.
The optional id: parameter lets you tag one or a group of callbacks with a unique name so
that you can remove them all as a group without interfering with other callbacks, perhaps
registered by other scripted tools.
The optional persistent: parameter lets you control whether the script is saved
permanently in the currently open scene file or is a global callback script that remains in
place no matter what file opening and closing is performed. A true value for the
parameter specifies that the script should be stored in the current file and loaded and
registered for callback whenever that file is opened again. Persistent callback scripts are
always removed when a new file is loaded or a reset is performed so that persistent scripts
in one file don’t accidentally get copied to a later file. The default for this parameter is
false, indicating the script is a global script and is not persistent.
For example:
callbacks.addScript #preRender “setUpRenderGeom()” \
id:#jbwRender
registers a new callback script that will be called just before a render is performed.
The script invokes a function (that has presumably already been set up). An
unique ID has been assigned to the script for later selective removal.
callbacks.removeScripts [ <callback_type_name> ] [ id:<name> ]
This method is used to unregister and remove one or more callback scripts. Specifying just
a callback event type name removes all the callback scripts for that event. Specifying just
an id:<name> removes all callback scripts in all events with that ID. Specifying both
limits the ID-based removal to the specified event type.
 General Event Callback Mechanism 1657

callbacks.show ()
This method lists out the current callback scripts in the Listener window.
callbacks.broadcastCallback <callback_type_name>
This method provides a way for you to simulate one of the events and have all the callback
scripts for it executed. Within 3ds max, the #preRenderFrame and #preRenderFrame
callbacks can only be called by the renderer. These callbacks can not be called by using this
method.
The following is a list of valid callback event type names:
#unitsChange
Sent if the user changes the unit setting.
#timeunitsChange
Sent if the user changes the time format setting.
#viewportChange
Sent if the user changes the viewport layout.
#spacemodeChange
Sent if the user changes the reference coordinate system.
#modPanelSelChanged
Sent whenever the Modify panel opens on a new selection, either because the Modify
panel was just selected or because a new selection is made in the scene. The notify occurs
at a point just prior to panel redraw but after the selection has been established, so that
callback functions can modify the panel state without it being overwritten.

System Notifications
#systemPreReset
Sent before 3ds max is reset.
#systemPostReset
Sent after 3ds max is reset.
#postSystemStartup
Sent when the software goes live.
#pluginLoaded
Sent whenever a plug-in is loaded.
#systemPreNew
Sent just before 3ds max is reset.
#systemPostNew
Sent just after 3ds max is reset.
#preSystemShutdown
Sent just before the software enters the shutdown process.
#postSystemShutdown
Sent just before the software finishes the shutdown process.
#colorChanged
Sent when the system is updating it’s custom colors.
1658 Chapter 15 | Change Handlers and Callbacks

File Notifications
#filePreOpen
Sent before a new file is opened.
#filePostOpen
Sent after a new file is opened successfully.
#filePreMerge
Sent before a file is merged.
#filePostMerge
Sent after a file is merged successfully.
#filePreSave
Sent before a file is saved.
#filePostSave
Sent after a file is saved.

Renderer Notifications
#preRender
Sent before rendering is started. This notification is sent out before the renderer creates the
render instance objects, which means that you can create nodes and other objects as a
response to this event. When rendering multiple frames, this event is sent only once at the
beginning of the rendering phase, and not on a per-frame basis. In the #preRender
callback, you can’t change any of the render parameters (height, width, aliasing, etc) and
effect the current render sessions. Those parameters have already been set up internally in
3ds max, and so changes to them won’t occur until the next render session occurs.
#postRender
Sent after rendering has finished. This notification is sent out after the renderer destroys
the render instance objects, which means that you can create nodes and other objects as a
response to this event. When rendering multiple frames, this event is sent only once at the
end of the rendering phase, and not on a per-frame basis.
#preRenderEval
Sent just before the renderer starts evaluating objects.
#preRenderFrame
Sent just before each frame is rendered by the renderer. This notification is sent out after
the renderer has taken a snapshot of the scene geometry. At the time of this call the scene
cannot be modified. The renderer has already called GetRenderMesh() on all the object
instances, and the materials and lights are already updated. If you don’t modify anything
that is rendered, then it is okay to use this callback. The current frame being rendered is set
into the MAXScript currentTime context and system global, so any references to other
scene object properties will automatically be resolved at the currently rendering frame’s
time. This notification is not sent out when the renderer is called to update the Material
Editor sample spheres, only during output rendering.
 General Event Callback Mechanism 1659

#postRenderFrame
Sent just after each frame is rendered by the renderer. The current frame being rendered is
set into the MAXScript currentTime context and system global, so any references to other
scene object properties will automatically be resolved at the currently rendering frame’s
time. This notification is not sent out when the renderer is called to update the Material
Editor sample spheres, only during output rendering.
#renderParamsChanged
Sent whenever the common renderer parameters have changed.

Import/Export Notifications
#preImport
Sent before a file is imported.
#postImport
Sent after a file is imported successfully.
#importFailed
Sent if import fails.
#preExport
Sent before a file is exported.
#postExport
Sent after a file is exported successfully.
#exportFailed
Sent if export fails.

Node Related Notifications

#nodeCreated
Sent when a node is created.
#nodeRenamed
Sent if a scene node is renamed.
#nodeHide
Sent when a node is hidden.
#nodeUnhide
Sent when a node is unhidden.
#nodeFreeze
Sent when a node is frozen.
#nodeUnfreeze
Sent when a node is unfrozen.
#nodeLinked
Sent when a new parent-child link is made.
#nodeUnlinked
Sent when a parent-child link is broken.
1660 Chapter 15 | Change Handlers and Callbacks

#nodePreMaterial
Sent just before a node gets a new material
#nodePostMaterial
Sent just after a node gets a new material
#sceneNodeAdded
Sent just after a node is added to the scene.
#selNodesPreDelete
Sent just before selected nodes are deleted.
#selNodesPostDelete
Sent just after selected nodes are deleted.
#nodeMaterialChanged
Sent after the material is changed for the selected nodes.
#nodeWSCacheUpdated
Sent whenever the modifier stack display is reevaluated.

Material Library Notifications

#matLibPreOpen
Sent just before loading a material library.
#matLibPostOpen
Sent just after loading a material library.
#matLibPreSave
Sent just before saving a material library.
#matLibPostSave
Sent just after saving a material library.
#matLibPreMerge
Sent just before merging a material library.
#matLibPostMerge
Sent just after merging a material library.

Asset Browser Notifications

#abPreNavigate
Sent whenever a URL is loaded into the Asset Browser.

VIZ-Only Notifications
#heightMenuChanged
Sent when a user operated the height menu.
#fileLinkPreBind
Sent just before a file link bind.
#fileLinkPostBind
Sent just after a file link bind.
 General Event Callback Mechanism 1661

#fileLinkPreDetach
Sent just before a file link detach.
#fileLinkPostDetach
Sent just after a file link detach.
#fileLinkPreReload
Sent just before a file link reload.
#fileLinkPostReload
Sent just after a file link reload.
#fileLinkPreAttach
Sent just before a file link attach.
#fileLinkPostAttach
Sent just after a file link attach.

Other Notifications
#wmEnable
Sent when main window gets an wm_enable (BOOL enabled).
#selectionSetChanged
Sent after the selection set has changed.
#bitmapChanged
Sent after a bitmap is reloaded.
1662 Chapter 15 | Change Handlers and Callbacks
Chapter 16: Miscellaneous Functions

freeSceneBitmaps()
Frees up all the memory used by the image file bitmap caches. This is useful if memory is
fragmented with a lot of different bitmaps and you want to have just the ones currently
active reloaded.
rescaleWorldUnits <factor> [ #selOnly ]
This method provides functionality similar to that of Rescale World Utility plug-in in
3ds max. <factor> is the factor the objects should be scaled by. If #selOnly is specified
then only the selected objects are scaled.
IsNetServer()
Returns true if 3ds max is operating in network rendering mode and false if operating
in normal interactive mode.
loadDllsFromDir <directory_path_string> <filename_wildcard_string>
Load all the plug-ins found in the specified directory. The directory_path_string must
be terminated with a ‘\’. For example:
LoadDllsFromDir “f:\\maxsdk\\plugin\\“ “*.dlc”

maxVersion()
Returns an Array with three integers like #(3000, 6, 0) with 3ds max release number, max
API number, revision number of the SDK.
swap <destination> <destination>
Takes two valid assignment destinations (property, array index, or variable) as arguments
and swaps their values. For example:
swap myMaterial.diffuseMap.map1 myMaterial.diffuseMap.map2
1664 Chapter 16 | Miscellaneous Functions

Pausing Script Execution

The sleep function lets you pause script execution for a given amount of time.
The form is:
sleep <time_in_seconds>

The time argument is a floating point number of seconds to sleep.

Note that the sleep time is not guaranteed to be extremely accurate. You can interrupt a sleep with
the ESC key which halts all execution or with the SPACE bar which simply causes the sleep
function to terminate and the script to continue executing. In both cases, you may need to hold the
key down for up to half a second for MAXScript to respond.

Time Stamping
The timeStamp() function gives time-of-day in milliseconds.
The form is:
timeStamp()

The function returns the number of milliseconds since 00:00 hours that day. This is useful for timing
operations (presuming you are not timing across midnight.)
Example:
start = timeStamp()
process_mesh() -- do some big job
end = timeStamp()
format “Processing took % seconds\n” ((end - start) / 1000.0)

Controlling the Renderer

You can use the render() function to invoke the 3ds max renderer. It can take many optional
parameters to control the rendering.
render
[ camera: <camera_node> ]
Defaults to active viewport.
[ frame: <number> | #current ]
Defaults to #current.
[ framerange: <interval> | #active ]
[ fromframe: <number> ]
[ toframe: <number> ]
[ nthframe: <number> ]
Defaults to unsupplied, and the frame value controls which frames to render.
[ outputwidth: <number> ]
Defaults to current render width.
 Controlling the Renderer 1665

[ outputheight: <number> ]
Defaults to current render height.
[ outputSize: <point2> ]
An alternative way to specify the output size of the rendered image. The point2 value
is in the form: [width,height]
[ pixelaspect: <number> ]
Defaults to 1.0.
[ renderhiddenobjects: <boolean> ]
Defaults to current renderer Render Hidden Objects state.
[ superblack: <boolean> ]
Defaults to current renderer Superblack state.
[ force2sided: <boolean> ]
Defaults to current renderer Force 2 Sided state.
[ renderatmosphericeffects: <boolean> ]
Defaults to current renderer Render Atmospheric Effects state.
[ renderfields: <boolean> ]
Defaults to current renderer Render Fields state.
[ fieldorder: #odd | #even ]
Defaults to current renderer preferences Field Order state.
[ outputfile: <string> ]
The frame number is appended to the filename if the file image type is a single image
type (.bmp, .jpg, .tga, etc.), and a frame range is being rendered. Defaults to rendering
to just the virtual frame buffer.
[ vfb: <boolean> ]
Defaults to current renderer Show VFB state.
[ netrender: <boolean> ]
Defaults to current renderer Net Render state.
[ renderer: #draft | #production]
Allows the selection of draft or production renderer. By default, the currently selected
renderer is used.
[ renderType: #normal | #region | #regionCrop | #blowup | #selection ]
[ region: #(left,top,right,bottom) ]
Provides control over the type of rendering, corresponding to the Render Type menu
in the 3ds max toolbar. If #region or #blowUp is selected, the region: parameter
may be used to override the currently set regions for the active viewport, specified as
pixel coordinates relative to the top-left corner in the bitmap (VFB). Note that
#region and #blowUp can only be selected for an active viewport rendering. An error
will be reported if they are specified for a camera rendering. Defaults to #normal.
[ to: <bitmap> ]
Specifies an existing bitmap to render into. The render() function takes image size
and other parameter settings from the existing bitmap. If not supplied, a new bitmap
is created and returned by the render() function.
1666 Chapter 16 | Miscellaneous Functions

[ channels: <array_of_channel_names> ]
Specifies which g-buffer channels should be created during the rendering. For example:
bm = render camera:$cam2 channels:#(#zDepth, #coverage, #objectID)

causes $cam2 to be rendered into a new bitmap that will contain z-depth, pixel coverage
and object g-buffer ID channels. The channels: argument must always be an array of
channels identifiers, chosen from the following:
#zDepth
#matID
#objectID
#UVCoords
#normal
#unClamped
#coverage
#node
#shaderColor
#shaderTransparency
#velocity
#weight

Defaults to no g-buffer channels.

[ aperture: <float> ]
Defaults to current renderer Aperture Width value.
[ ditherTrueColor: <boolean> ]
Defaults to current rendering preferences Dither True Color state.
[ ditherPaletted: <boolean> ]
Defaults to current rendering preferences Dither Paletted state.
[ videocolorcheck: <boolean> ]
Defaults to current renderer Video Color Check state.
[ renderPAL: <boolean> ]
Defaults to current rendering preferences Video Color Check NTSC/PAL state. If true,
and video color checking is enabled, PAL video color checking is performed.
[ superBlackThreshold: <integer> ]
Defaults to current rendering preferences Super Black Threshold value.
[ maxPixelSize: <float> ]
All correspond to items in the 3ds max Render Scene setup dialogs.
 Controlling the Renderer 1667

The following are also available if the 3ds max standard scanline renderer is being used:
[ antiAliasing: <boolean> ]
Defaults to current renderer Anti-Aliasing state.
[ antiAliasFilterSize: <float> ]
Defaults to current renderer Anti-Aliasing Filter Size value.
[ antiAliasFilter: <filter> ]
Defaults to current renderer Anti-Aliasing filter.
[ enablePixelSampler: <boolean> ]
Defaults to the current renderer Global SuperSampling state. This state is true if
Disable all Samplers is checked, otherwise false.
[ mapping: <boolean> ]
Defaults to current renderer Mapping state.
[ shadows: <boolean> ]
Defaults to current renderer Shadows state.
[ autoReflect: <boolean> ]
Defaults to current renderer Auto-Reflect/Refract and Mirrors state.
[ forceWireframe: <boolean> ]
Defaults to current renderer Force Wireframe state.
[ wireThickness: <float> ]
Defaults to 1.0.
[ filterMaps: <boolean> ]
Defaults to current renderer Anti-Aliasing Filter Maps state.
[ objectMotionBlur: <boolean> ]
Defaults to current renderer Object Motion Blur Apply state.
[ objectBlurDuration: <float> ]
Defaults to 0.5.
[ objectBlurSamples: <integer> ]
Defaults to 10.
[ objectBlurSubdivisions: <integer> ]
Defaults to 10.
[ imageMotionBlur: <boolean> ]
Defaults to current renderer Image Motion Blur Apply state.
[ imageBlurDuration: <float> ]
Defaults to 0.5.
[ autoReflectLevels: <integer> ]
Defaults to 1.
You can invoke the renderer and have it do one or more of four things with the rendered output:
• Display it in a virtual frame buffer (the default), controlled with the vfb: parameter.
• Store the rendering in an image file by supplying an outputfile: parameter. The type of image
file to be created is determined from the file suffix you specify.
1668 Chapter 16 | Miscellaneous Functions

• Return the result as a MAXScript Bitmap value that you can perform Bitmap operations on (see
the Bitmap Values (p. 755) topic).
• Store the rendering in an existing MAXScript Bitmap value by supplying the to: parameter.
Supplying this parameter causes settings such as height, width, aspect, gamma, file name, etc.
to be taken from the supplied bitmap.
Notes:
The render() function interruptible mid-frame using the ESC key.
Examples:
render camera:$cam01 outputwidth:320 outputheight:240
for c in cameras do render c outputFile:(c.name + “.bmp”) vfb:off
rollout1.image.bitmap = render camera:$cam01 ...

Executing External Commands and Programs

MAXScript provides two methods for executing external programs. DOSCommand() takes a DOS
command as a string and send it to the system for execution. It has the form:
DOSCommand <command_string>

Examples:
DOSCommand “delete c:\\temp\\foo.dat”
DOSCommand (”copy “ + source_file + “ “ + dest_folder)

You can use this function to launch other programs, for example, or perform such tasks as gathering
all the material texture and displacement image files in your scene into one folder.
The DOSCommand() function returns an integer which is the status result returned by the executed
system command.
ShellLaunch() emulates a user double-clicking on a specified file in Windows. It has the form:
ShellLaunch <filename_string> <parameters_string>

Whatever you send to ShellLaunch will be run by the Windows shell automatically, ie:
ShellLaunch “E:\\tests\\lookup.html” ““
would launch Netscape/Ie4 with lookup.html.
If a file-name extension is not specified in <filename_string>, Windows will search the specified
directory for executable files. If no directory is specified, Windows will search the paths in the Path
environment variable for the executable file. For example:
shellLaunch “e:/program files/ucalc/ucalc” ““
will execute the ucalc.exe file in the specified directory.
 Exiting and Resetting 3ds max 1669

The <parameters_string> is passed to the launched application as command line parameters.

For example:
shellLaunch “e:/t.avi” “/play /loop”
Will launch the application associated with .avi files, and pass /play and /loop as
command line parameters.

Exiting and Resetting 3ds max

The quitMAX() function lets you exit 3ds max under script control. This function is typically used
in batch processing or render scripts. The function has the form:
quitMAX [ #noPrompt ]

If the #noPrompt optional argument is not specified and there are unsaved changes in the scene,
3ds max will prompt with its standard save changes dialog.
Additionally, you can control the scene save and undo states in 3ds max with the following
functions:
setSaveRequired <boolean>
lets you set the 3ds max system “dirty” flag. If this flag is set or there are entries in the
Undo buffer, the user is asked if they want to save the scene file on a File > New or File >
Reset.
getSaveRequired()
returns true if the 3ds max system “dirty” flag is set to true or if the Undo buffer is not
empty. If the Undo buffer if not empty, this function will still return true, even if you just
called setSaveRequired false.
clearUndoBuffer()
empties the Undo buffer, both providing a way to reset the undo state and another way to
control the save-changes requester.
Normally, if there are entries in the Undo buffer when the scene is closed, 3ds max will prompt with
a save-changes requester. In some cases, where you are controlling undo in MAXScript, you may
want to force the need for a save-changes prompt.
The resetMAXFile() function lets you reset 3ds max under script control. This function is
typically used in batch processing or render scripts. The function has the form:
resetMaxFile() [ #noPrompt ]

If the #noPrompt optional argument is not specified and there are unsaved changes in the scene,
3ds max will prompt with its standard save changes dialog.
1670 Chapter 16 | Miscellaneous Functions
Chapter 17: OLE Automation

OLE Server
OLE Automation capability is provided in MAXScript that allows 3ds max to act as an OLE
Automation server for applications such as Visual Basic, Excel, Paradox, etc. With it, you can publish
MAXScript functions that can then be called from OLE Automation clients like VB and Excel to
generate models or animations or return data from the current scene, etc. There is an example
supplied in the script samples that defines a set of simple business graphing MAXScript functions
and an Excel spreadsheet with some Excel VB-scripted menus that will pass a selection of cells across
to these MAXScript functions to generate an animated bar chart.
This facility has the following features and limitations:
• It exposes a single server object to which you can attach a list of MAXScript functions that then
appear as the methods of that object to an OLE Automation client. Future releases will allow you
to construct any number of OLE Automation objects and give them any number of interfaces.
• It is registered as a separate process, local server supporting multiple use of its exposed object.
• It does not support in-place activation or object linking and embedding and provides no
containers for other OLE objects. In future versions, you will be able to pass rendered images
and animations to OLE clients for direct linking and embedding.
• It supports only the IDispatch form of interface with no accessible type information -- clients
need to declare their reference to the 3ds max server object as an untyped generic object.
• It supports the following method argument and result data types:
integers
reals (floats)
currency (floats)
string
boolean
empty (an empty spreadsheet cell, for example)
the equivalent MAXScript value for empty is undefined
OLE Objects (interfaces)
1672 Chapter 17 | OLE Automation

• You need to have 3ds max running and MAXScript activated before OLE Clients can access
3ds max. MAXScript is activated (and the startup.ms script run) when you first access its
Utility panel rollout. Alternatively, you can use launch script facilities described in Running
Scripts from the Command Line (p. lvii) to establish an OLE server interface as soon as
3ds max runs.
• You need to have registered 3ds max with Windows as an OLE server using the registration script
supplied with this release. See the instructions in the Setting Up MAXScript OLE Automation
(p. 1673) for details.
OLE Client
With the MAXScript OLE Automation Client system, you can use MAXScript to create OLE
Automation (now called Active-X) objects within 3ds max and control the associated OLE
Automation Servers servers with MAXScript, such as making an Excel spreadsheet and inserting
3ds max object information directly into cells there.
The function createOLEObject() is used for establishing a connection to OLE Auto Servers. The
return value of createOLEObject() is an instance of the OLEObject class. For example,
xl = createOLEObject “Excel.Sheet”
opens a connection to Excel and creates a sheet object and puts it in the variable xl. The
single argument to this function is an OLE progID string. You can then access properties
and call methods on the new OLE object. For example,
xl.application.name
will return
“Microsoft Excel”

xl.application.visible = true
will make Excel visible on the desktop. You get properties on OLE objects with the dot ‘.’
notation, just as you do in MAXScript. You also refer to OLE object methods as properties
of the OLE object. For example, the Sheet has a method ‘cells’ which takes a cell
coordinate and returns a Cell OLE object.
xlc = xl.application.cells 1 1
puts the top-left-hand cell into xlc. Set its value like this:
xlc.value = 123.45

The server application that was attached with createOLEObject() is released and terminated
when the created MAXScript OLE object is eventually garbage-collected. You can explicitly
disconnect from an OLE server application with the releaseOLEObject() function. The form is:
releaseOLEObject <ole_object>

The OLE object becomes disabled once releaseOLEObject() has been called on it and further
attempts to use it results in a descriptive error message.
 Setting Up MAXScript OLE Automation 1673

You can explicitly disconnect from all active OLE server applications with the
releaseAllOLEObjects() function. Its form is:
releaseAllOLEObjects()

After calling this function, all existing OLE objects become disabled and any attempt to use them
further will generate a runtime error.

Setting Up MAXScript OLE Automation

In order to use the OLE Automation features in MAXScript, you need to register 3ds max as an OLE
Automation server in the system registry:
1. Open the Maxscrpt.reg file that ships with 3ds max in Notepad or some other text editor.
2. Edit this registry entry file to make sure it references the correct 3ds max executable. Make sure
the last line specifies the correct location for your 3ds max executable. The supplied
Maxscrpt.reg file points to c:\3dsmax\3dsmax.exe by default.
3. Save the file and exit the editor.
4. Locate the Maxscrpt.reg registry file in Windows Explorer and double-click it.
This registers 3ds max as an OLE server. You need to do this on all the systems you expect to run
3ds max as an OLE server.
For more information, see the following topics:
Exposing MAXScript Functions (p. 1673)
3ds max Specific Errors (p. 1674)
Running the OLE Demo (p. 1674)

Exposing MAXScript Functions

The list of OLE Automation-callable MAXScript functions is defined using the
registerOLEInterface() function. It takes an array of functions to be exposed:
registerOLEInterface <array_of_fns>

For example:
registerOLEInterface #(get_object_count,
get_object_name,
get_object_position)

Each time you call this function, it replaces the current set of exposed functions with the new set --
it does not add to the existing set. The functions you expose should limit themselves to passing and
returning only the following data types: integers, reals (floats), currency, string, boolean and empty
(undefined).
1674 Chapter 17 | OLE Automation

3ds max Specific Errors

There are two errors that may be reported to OLE clients when calling exposed MAXScript functions
that are specific to 3ds max:
#512 -- an exception or interrupt occurred while running the called function
#513 -- the called function attempted to return an unsupported data type

Running the OLE Demo

The example supplied consists of 2 files:
ole.ms -- a MAXScript script containing a grapher interface
oledemo.xls -- an Excel spreadsheet with some data and a VBA script to call the grapher
To run the example, make sure you’ve registered 3ds max as an OLE server as described in the Setting
Up MAXScript OLE Automation (p. 1673) topic, start 3ds max and open the ole.ms script file in a
script Editor window. You’ll see it contains definitions for six functions and a call to
registerOLEInterface() to expose some of those functions. Select the whole script and press
number pad ENTER to evaluate it. This defines the functions and exposes them through OLE.
Start Excel and open the oledemo.xls spreadsheet (in the scripts directory). It contains one
worksheet and one module sheet and defines a new Max menu. The worksheet contains some
example data to be charted and the module sheet contains the VBA scripts that implement the menu
commands in the new 3ds max menu.
Bring up the sheet1 worksheet. It contains a table of numbers representing quarterly sales figure
for a number of regions. Drag-select all the label and figure cells and choose the Max > Build
Animated Chart menu. This opens a connection to 3ds max and passes the selected column labels
and figures to the appropriate functions in the exposed interface. It then brings 3ds max to the front
which chugs away for a bit building the labeled bar chart and animating the bars over the range of
quarters given. Drag the slider to see the bars animate. Business graphs in 3ds max!
The Max > Render Movie menu in Excel invokes another of the exposed MAXScript functions that
creates and animates a camera in the bar chart scene and then sets off a render to an AVI file. (If you
want to interrupt the render, hold down the ESC key until it stops at the beginning of the next
frame - currently the MAXScript renderer interface only looks at the ESC key between frames).
Chapter 18: Trigonometric Functions and Vector Arithmetic

Trigonometric Functions
This topic is a quick review for readers who need a reminder about this area of mathematics. If you’re
familiar with trigonometry, you can skip this topic. If you find this topic difficult to follow, you
might consult a more basic reference on mathematics.
Trigonometric functions are principally used to model or describe:
• The relation between angles in a triangle (hence the name).
• Rotations about a circle, including locations given in polar coordinates.
• Cyclical or periodic values, such as sound waves.
The three basic trigonometric functions are derived from an angle rotating about a unit circle.

Trigonometric functions based on the unit circle

1676 Chapter 18 | Trigonometric Functions and Vector Arithmetic

The tangent function is undefined for x = 0. Another way to define the target is:

Because XYR defines a right-angled triangle, the relation between the sine and cosine is:

The graphs of the basic trigonometric functions illustrate their cyclical nature.

Graphs of basic trigonometric functions

The sine and cosine functions yield the same values, but the phase differs along the X-axis by ?/2:
in other words, 90 degrees.
The inverse functions for the trigonometric functions are the arc functions—the inverse only applies
to values of x restricted by –?/2 = X = ?/2. The graphs for these functions appear like the basic
trigonometric function graphs, but turned on their sides.

Graphs of basic arc functions

 Vector Arithmetic 1677

The hyperbolic functions are based on the exponential constant e instead of on circular
measurement. However, they behave similarly to the trigonometric functions and are named for
them. The basic hyperbolic functions are:

Graphs of basic hyperbolic functions

Vector Arithmetic
This topic is a quick review for readers who need a reminder about vector arithmetic. If you’re
familiar with vectors and vector calculations, you can skip this topic. If this topic is difficult to
follow, you might consult a more basic reference on mathematics.
A vector expresses a length and a direction in a particular space. The vector is expressed as a point;
for example, [5, 5, 7]. The length is the distance from the origin to that point, and the direction is
similarly from the origin to (and through) the point.
In 3ds max, vectors have three values and describe positions in three-dimensional space. They can
also represent percent scaling in X, Y, and Z; and—more abstractly—describe locations in RGB
color space.
1678 Chapter 18 | Trigonometric Functions and Vector Arithmetic

Unit Vectors and Basic Vectors

A unit vector has a length of one. Unit vectors are often used to express direction only. The three
basic vectors are unit vectors that describe the three axes (X, Y, and Z) of 3D space.

Basic vectors and the XYZ axes

Adding and Subtracting Vectors

Adding two vectors creates a new vector that combines the length and direction of the original two.
Vector addition is commutative: V+W = W+V.

Adding two vectors

Subtracting two vectors gives the vector between the two points.
 Vector Arithmetic 1679

Subtracting two vectors

Scalar Multiplication and Division

Multiplying a vector by a scalar changes the vector’s length, as does dividing the vector by a scalar.

Vector Length and Direction

The length of a vector is obtained from the Pythagorean theorem.

In MAXScript, the length() function returns this value.

The direction of the vector is the vector divided by its length; this gives you a unit vector with the
same direction.

The distance between two points is the length of the vector between them.

Subtracting vectors to obtain a distance

1680 Chapter 18 | Trigonometric Functions and Vector Arithmetic
Chapter 19: MAXScript Grammar and Class Hierarchy

MAXScript Grammar
The following is the complete MAXScript grammar in EBNF form. It differs slightly in factoring from
the syntax forms given in the online reference, so that all precedence is explicit in the rules.
These rules, or syntax definitions, follow the standard EBNF notation (Extended Backus-Naur Form).
The rules typically contain a number of characters with special meanings. For example, brackets
enclose optional items, such as the minus sign in front of the number. Braces enclose items you can
use repeatedly, and bars separate multiple items from which you can choose one. Sometimes, rules
are given names so they can be referred to in the documentation or as parts of other rules. The
special characters in the rules have the following meaning:
[...] -- items inside the brackets are optional
(...|...|...) -- choose one of the items separated by the bars
{...} -- you can specify the braced item ZERO or more times
{...}+ -- you can specify the braced item ONE or more times
::= -- define a name for a syntax rule
<rule> -- you can insert what is defined by the named rule
bold_characters -- characters or token as written

An example of an EBNF form is:

[-]{<digit>}[.{<digit>}][(e | E)[+ | -]{<digit>}+]

which is interpreted as follows:

Syntax Definition
[-]{<digit>} an optional minus sign (the sign), followed by
0 or more digits (the integer part), followed by
[.{<digit>}] an optional sequence (the fraction part) comprised of:
a period character, followed by
0 or more digits, followed by
1682 Chapter 19 | MAXScript Grammar and Class Hierarchy

Syntax Definition
[(e | E)[+ | -]{<digit>}+] an optional sequence (the exponent part) comprised of:
either an ‘e’ or ‘E’, followed by
an optional plus or minus sign, followed by
one or more digits.
<program> ::= { <expr> }+

<expr> ::= <simple_expr>

<variable_decls>
<assignment>
<if_expr>
<while_loop>
<do_loop>
<for_loop>
<loop_exit>
<case_expr>
<struct_def>
<try_expr>
<variable_decls>
<function_def>
<function_return>
<context_expr>
<max_command>
<utility_def>
<rollout_def>
<tool_def>
<rcmenu_def>
<macroscript_def>
<plugin_def>

<variable_decls> ::= ( local | global ) <decl> { , <decl> }

persistent global <decl> { , <decl> }

<decl> ::= <var_name> [ = <expr> ] -- name and optional

-- initial value

<var_name> ::= { <alphanumeric> | _ }

‘{ <any_char_except_quote> }‘

<assignment> ::= <destination> = <expr>

<destination> += <expr>
<destination> -= <expr>
<destination> *= <expr>
<destination> /= <expr>

<destination> ::= <var_name>

<property>
<index>
 MAXScript Grammar 1683

<if_expr> ::= if <expr> then <expr> [ else <expr> ]

if <expr> do <expr>

<while_loop> ::= while <expr> do <expr>

<do_loop> ::= do <expr> while <expr>

<for_loop> ::= for <name> ( in | = ) <source> (do | collect) <expr>

<source> ::= <expr> to <expr> [ by <expr> ] [ where <expr> ]

<expr> [ where <expr> ]

<loop-exit> ::= exit [ with <expr> ]

<loop-continue> ::= continue

<case_expr> ::= case [ <expr> ] of ( { <case_item> } )

<case_item> ::= <factor> : <expr>

default : <expr>

<struct_def> ::= struct (<member> { , <member> } )

<member> ::= <name> [ = <expr> ] -- name and optional initial value

<function_def>

<try_expr> ::= try <expr> catch <expr>

<function_def> ::= [ mapped ] (function | fn) <var_name> { <arg> } = <expr>

<arg> ::= <var_name>

<var_name>: [ <operand> ]

<function_return> ::= return <expr>

<context_expr> ::= <context> { , <context> } <expr>

<context> ::= [with] animate <logical_expr>

at level <operand>
at time <operand>
in <operand>
[in] coordsys ( local | world | parent | <operand> )
about ( pivot | selection | coordsys | <operand> )
[ with ] undo <logical_expr>

<set_context> ::= set <context>

<utility_def> ::= utility <var_name> <string> { <var_name>:<operand> } \

( { <utility_clause> }+ )
1684 Chapter 19 | MAXScript Grammar and Class Hierarchy

<utility_clause> ::= <rollout>

<rollout_clause>

<rollout_def> ::= rollout <var_name> <string> { <var_name>:<operand> } \

( { <rollout_clause> }+ )

<rollout_clause> ::= local <decl> { , <decl> }

<function_def>
<struct_def>
<mousetool>
<item_group>
<rollout_item>
<rollout_handler>

<item_group> ::= group <string> ( { <rollout_item> } )

<rollout_handler> ::= on <var_name> <var_name> { <var_name> } do <expr>

<rollout_item> ::= <item_type> <var_name> [ <string> ] { <var_name>:<operand> }

<item_type> ::= label

button
edittext
combobox
dropdownList
listbox
spinner
slider
pickbutton
radiobuttons
checkbox
checkbutton
colorPicker
mapbutton
materialbutton
progressbar
timer
bitmap

<rcmenu_def> ::= rcmenu <var_name> ( { <rcmenu_clause> }+ )

<rcmenu_clause> ::= local <decl> { , <decl> }

<function_def>
<struct_def>
<rcmenu_item>
<rcmenu_handler>

<rcmenu_handler> ::= on <var_name> <var_name> do <expr>

<rcmenu_item> ::= <rcmenu_item_type> <var_name> <string>

{ <var_name>:<operand> }
 MAXScript Grammar 1685

<rcmenu_item_type>::= menuitem
separator
submenu

<macroscript_def> ::= macroscript <var_name> <string> { <var_name>:<operand> } \

( <expr_seq> )

<mousetool_def> ::= tool <var_name> {<var_name>:<operand>} ({ <tool_clause> }+ )

<tool_clause> ::= local <decl> { , <decl> }

<function_def>
<struct_def>
<tool_handler>

<tool_handler> ::= on <var_name> <var_name> { <var_name> } do <expr>

<plugin_def> ::= plugin <var_name> <var_name> { <var_name>:<operand> } \

( { <plugin_clause> }+ )

<plugin_clause> ::= local <decl> { , <decl> }

<function_def>
<struct_def>
<parameters>
<mousetool_def>
<rollout_def>
<plugin_handler>

<parameters> ::= parameters <var_name> { <var_name>:<operand> }

( { <param_clause> }+ )

<param_clause> ::= { <param_defs> }+

{ <param_handler> }

<param_defs> ::= <var_name> { <var_name>:<operand> }

<param_handler> ::= on <var_name> <var_name> { <var_name> } do <expr>

<plugin_handler> ::= on <var_name> do <expr>

<simple_expr> ::= <operand>

<math_expr>
<compare_expr>
<logical_expr>
<function_call>
<expr_seq>
1686 Chapter 19 | MAXScript Grammar and Class Hierarchy

<math_expr> ::= <math_operand> + <math_operand> -- standard arithmetic

addition
<math_operand> - <math_operand> -- standard arithmetic
subtraction
<math_operand> * <math_operand> -- standard arithmetic
multiplication
<math_operand> / <math_operand> -- standard arithmetic
division
<math_operand> ^ <math_operand> -- exponential, raise to the
power
<math_operand> as <class> -- conversion between types

<math_operand> ::= <operand>

<function_call>
<math_expr>

<logical_expr> ::= <logical_operand> or <logical_operand>

<logical_operand> and <logical_operand>
not <logical_operand>

<logical_operand> ::= <operand>

<compare_expr>
<function_call>
<logical_expr>

<compare_expr> ::= <compare_operand> == <compare_operand> -- equal

<compare_operand> != <compare_operand> -- not equal
<compare_operand> > <compare_operand> -- greater than
<compare_operand> < <compare_operand> -- less than
<compare_operand> >= <compare_operand> -- greater than
or equal
<compare_operand> <= <compare_operand> -- less than or equal

<compare_operand> ::= <math_expr>

<operand>
<function_call>

<function_call> ::= <operand> ()

<operand> { <parameter> } -- up to an end of line or
-- lower precedence token

<parameter> ::= <operand>

<name>: <operand>

<operand> ::= <factor>

<property>
<index>

<property> ::= <operand> . <var_name> -- properties and indexes

-- left associate
 MAXScript Grammar 1687

<index> ::= <operand> [ <expr> ]

<factor> ::= <number>

<string>
<path_name>
<var_name>
#<var_name>
<array>
<bitarray>
<point3>
<point2>
true
false
on
off
ok
undefined
unsupplied
- <expr> -- unary minus
<expr_seq>
? -- last Listener result

<expr_seq> ::= ( <expr> { (; | <eol>) <expr> } )

<number> ::= [-]{<digit>}[.{<digit>}[(e | E)[+ | -]{<digit>}+] -- decimal

number
0x{<hex_digit>}+ -- hexadecimal number

<string> ::= “{ <any_char_except_quote> | \“ | \n | \r | \t | \* | \? | \\

| \% | \x{<hex_digit>}+ }“

<time> ::= [-]{<decimal_number>[m | s | f | t]}+ -- minutes/sec/

frames/ticks
[-]{<digit>}:{<digit>}[.{<digit>}] -- SMPTE mins:secs.frame
[-]<decimal_number>n -- active segment normalized time

<box2> ::= [ <expr>, <expr>, <expr>, <expr> ]

<point3> ::= [ <expr>, <expr>, <expr> ]

<point2> ::= [ <expr>, <expr> ]

<array> ::= #()

#( <expr> { , <expr> } )

<bitarray> ::= #{}

#{[<expr> | <expr>..<expr>] { , [<expr> | <expr>..<expr>] }}

<path_name> ::= $<path> | $

<path> ::= [ <objectset> ] [ / ] [ <levels> ] <level_name>

1688 Chapter 19 | MAXScript Grammar and Class Hierarchy

<levels> ::= <level> { / <level> }

<level> ::= <level_name>

...

<level_name> ::= { <alphanumeric> | _ | * | ? | \ }

‘{ <any_char_except_single_quote> | \* | \? | \\ }‘

MAXScript Class Hierarchy

The following is the complete MAXScript class hierarchy. Each class typically inherits the properties,
operators, and methods of its parent class.
Value
AngleAxis
Array
ArrayParameter
AtmosphericClass
BigMatrix
BigMatrixRowArray
BipedExportInterface
BitArray
Bitmap
BitmapControl
BooleanClass
Box2
ButtonControl
CTBitMap
CTMotionTracker
ChangeHandler
CharStream
CheckBoxControl
CheckButtonControl
Class
Color
ColorPickerControl
ComboBoxControl
Control
EdgeSelection
EditTextControl
EffectClass
EmptyClass
EulerAngles
FaceSelection
FileStream
Float
GeomObject
GroupEndControl
GroupStartControl
HashTable
Integer
 MAXScript Class Hierarchy 1689

Interval
LabelControl
ListBoxControl
MAXClass
MAXFilterClass
MAXKey
MAXKeyArray
MAXMeshClass
MAXModifierArray
MAXNoteKey
MAXNoteKeyArray
MAXObject
MAXRootNode
MAXScriptFunction
MAXSuperClass
MAXTVNode
MSPluginClass
MapButtonControl
MapSupportClass
MaterialLibrary
Matrix3
MeditMaterialsClass
Menuitem
ModifierClass
MotionTracker
MouseTool
MtlButtonControl
MultiMaterialClass
NURBSDisplay
NURBSObject
NURBSControlVertex
NURBSCurve
NURBSBlendCurve
NURBSCVCurve
NURBSCurveOnSurface
NURBSChamferCurve
NURBSFilletCurve
NURBSIsoCurve
NURBSMirrorCurve
NURBSOffsetCurve
NURBSPointCurve
NURBSPointCurveOnSurface
NURBSProjectNormalCurve
NURBSProjectVectorCurve
NURBSSurfSurfIntersectionCurve
NURBSSurfaceEdgeCurve
NURBSSurfaceNormalCurve
NURBSXFormCurve
NURBSPoint
NURBSCurveConstPoint
NURBSCurveIntersectPoint
1690 Chapter 19 | MAXScript Grammar and Class Hierarchy

NURBSCurveSurfaceIntersectPoint
NURBSIndependentPoint
NURBSPointConstPoint
NURBSSurfConstPoint
NURBSSurface
NURBS1RailSweepSurface
NURBS2RailSweepSurface
NURBSBlendSurface
NURBSCVSurface
NURBSCapSurface
NURBSExtrudeSurface
NURBSFilletSurface
NURBSLatheSurface
NURBSMirrorSurface
NURBSMultiCurveTrimSurface
NURBSNBlendSurface
NURBSOffsetSurface
NURBSPointSurface
NURBSRuledSurface
NURBSULoftSurface
NURBSUVLoftSurface
NURBSXFormSurface
NURBSTexturePoint
NURBSSelection
NURBSSet
NURBSSurfaceApproximation
NURBSTextureSurface
Name
NodeChildrenArray
NoteTrack
Number
OLEMethod
OLEObject
Object
OkClass
PathName
PhyBlendedRigidVertex
PhyContextExport
PhyRigidVertex
PickerControl
Point2
Point3
ProgressBar
Quat
RadioControl
Ray
RolloutControl
RolloutFloater
SelectionSet
SelectionSetArray
Set
 MAXScript Class Hierarchy 1691

SliderControl
SpinnerControl
StandardMaterialClass
String
StringStream
StructDef
SubAnim
Time
Timer
TriMesh
UndefinedClass
UnsuppliedClass
UserGeneric
VertexSelection
WindowStream
XRefScene
MAXWrapper
atmospheric
Combustion
Fog
Missing_Atmospheric
RenderEnvironment
Volume_Fog
Volume_Light
filter
Area
Blackman
Blendfilter
Catmull_Rom
Cook_Variable
cubic
Mitchell_Netravali
Plate_Match_MAX_R2
Plate_Match_VIZ_R2
Quadratic
Sharp_Quadratic
Soften
Video
FloatController
AudioFloat
bezier_float
Block
Float_Expression
float_list
Float_Motion_Capture
Float_Reactor
float_script
linear_float
LOD_Controller
Missing_Float_Control
Noise_float
1692 Chapter 19 | MAXScript Grammar and Class Hierarchy

On_Off
SlaveFloat
tcb_float
Waveform_Float
Layer_Manager
MasterBlockController
Block_Control
Free_Center
MasterBlock
material
Blend
compositematerial
DoubleSided
doubleSidedMat
Matte
MatteShadow
Missing_Mtl
Morphermaterial
Multimaterial
multiSubMaterial
NoMaterial
RaytraceMaterial
Shellac
standard
Standardmaterial
TexOutputClass
StandardTextureOutput
textureMap
Adobe_Photoshop_Plug_In_Filter
Adobe_Premiere_Video_Filter
bitmapTex
Bitmaptexture
Bricks
Cellular
Checker
compositeTexture
CompositeTexturemap
Dent
falloff
fallofftextureMap
FlatMirror
Gradient
Gradient_Ramp
Marble
Mask
maskTex
Missing_TextureMap
Mix
Noise
NoTexture
output
 MAXScript Class Hierarchy 1693

Paint
Particle_Age
Particle_MBlur
Perlin_Marble
Planet
Raytrace
Reflect_Refract
RGB_Multiply
RGB_Tint
Smoke
Speckle
Splat
Stucco
Swirl
Thin_Wall_Refraction
Vertex_Color
Water
Wood
TopBottom
topBottomMat
UVGenClass
Missing_UVGen
StandardUVGen
XYZGenClass
Missing_XYZGen
StandardXYZGen
Matrix3Controller
IK_ControllerMatrix3Controller
Link_Control
Link_Transform
lookat
Missing_Matrix3_Control
prs
Slave_Control
TVDummyControl
modifier
Affect_Region
Bend
Bevel
Bevel_Profile
CameraMap
Cap_Holes
CrossSection
DeleteMesh
DeleteSplineModifier
Displace
Disp_Approx
Edit_Mesh
Edit_Patch
Edit_Spline
Extrude
1694 Chapter 19 | MAXScript Grammar and Class Hierarchy

Face_Extrude
FFDBox
FFDCyl
FFD_2x2x2
FFD_3x3x3
FFD_4x4x4
FFD_Select
Fillet_Chamfer
Flex
Lathe
Lattice
Linked_xform
MaterialByElement
Materialmodifier
Melt
MeshSmooth
Mesh_Select
MIrror
Missing_OSM
Morpher
NCurve_Sel
Noisemodifier
Normalize_Spline
Normalmodifier
NSurf_Sel
optimizeValue
ActionPredicate
ActiveXControl
AngleAxis
AngleControl
Array
ArrayParameter
AtmosphericClass
AttributeDef
Layer_Manager
BigMatrix
BigMatrixRowArray
BinStream
BitArray
bitmap
BitmapControl
BooleanClass
Box2
ButtonControl
ccCurve
ccPoint
CCRootClass
ChangeHandler
CharStream
CheckBoxControl
CheckButtonControl
 MAXScript Class Hierarchy 1695

class
color
ColorPickerControl
ComboBoxControl
Control
CTBitMap
CTMotionTracker
CurveCtlGeneric
CurvePointsArray
EdgeSelection
EditTextControl
EffectClass
EmptyClass
EulerAngles
FaceSelection
FileStream
float
Generic
GeomObject
GroupBoxControl
GroupEndControl
GroupStartControl
HashTable
ImgTag
integer
Interface
InterfaceFunction
Interval
IObject
LabelControl
LinkControl
ListBoxControl
MapButtonControl
MappedGeneric
MappedPrimitive
MapSupportClass
MaterialLibrary
Matrix3
MAXAKey
MAXClass
MAXCurveCtl
MAXFilterClass
MAXKey
MAXKeyArray
MAXMeshClass
mesh
MAXModifierArray
MAXNoteKey
MAXNoteKeyArray
MAXObject
MAXRefTarg
1696 Chapter 19 | MAXScript Grammar and Class Hierarchy

MAXRootNode
MAXScriptFunction
MAXSuperClass
MAXTVNode
MeditMaterialsClass
menuitem
MixinInterface
ModifierClass
MotionTracker
MouseTool
MPassCamEffectClass
MSComMethod
MSCustAttribDef
MSDispatch
MSPluginClass
MtlButtonControl
MultiListBoxControl
MultiMaterialClass
name
NodeChildrenArray
NodeGeneric
NoteTrack
Number
NURBSDisplay
NURBSObject
NURBSControlVertex
NURBSCurve
NURBSBlendCurve
NURBSChamferCurve
NURBSCVCurve
NURBSCurveOnSurface
NURBSFilletCurve
NURBSIsoCurve
NURBSMirrorCurve
NURBSOffsetCurve
NURBSPointCurve
NURBSPointCurveOnSurface
NURBSProjectNormalCurve
NURBSProjectVectorCurve
NURBSSurfaceEdgeCurve
NURBSSurfaceNormalCurve
NURBSSurfSurfIntersectionCurve
NURBSXFormCurve
NURBSPoint
NURBSCurveConstPoint
NURBSCurveIntersectPoint
NURBSCurveSurfaceIntersectPoint
NURBSIndependentPoint
NURBSPointConstPoint
NURBSSurfConstPoint
NURBSSurface
 MAXScript Class Hierarchy 1697

NURBS1RailSweepSurface
NURBS2RailSweepSurface
NURBSBlendSurface
NURBSCapSurface
NURBSCVSurface
NURBSExtrudeSurface
NURBSFilletSurface
NURBSLatheSurface
NURBSMirrorSurface
NURBSMultiCurveTrimSurface
NURBSNBlendSurface
NURBSOffsetSurface
NURBSPointSurface
NURBSRuledSurface
NURBSULoftSurface
NURBSUVLoftSurface
NURBSXFormSurface
NURBSTexturePoint
NURBSSelection
NURBSSet
NURBSSurfaceApproximation
NURBSTextureSurface
object
OkClass
OLEMethod
OLEObject
PathName
PickerControl
Point2
point3
Primitive
progressBar
Quat
RadioControl
Ray
RCMenu
RolloutClass
RolloutControl
RolloutFloater
SelectionSet
SelectionSetArray
Set
ObjectSet
SliderControl
SpinnerControl
StandardMaterialClass
StaticMethodInterface
String
StringStream
StructDef
subAnim
1698 Chapter 19 | MAXScript Grammar and Class Hierarchy

TextureClass
time
Timer
TriMesh
UndefinedClass
UnsuppliedClass
UserGeneric
ValueRef
VertexSelection
WindowStream
XRefScene
MAXWrapper
atmospheric
Fire_Effect
Fog
Missing_Atmospheric
RenderEnvironment
Volume_Fog
Volume_Light
BitmapIO
Autodesk_Animator_Flic
AVI
BMP
bmpio
CIN
CMB
EPS_Image
GIF
IFL
JPEG
jpegio
pngio
Portable_Network_Graphics
PSD_I_O
QTime
rgb
RLA
RPF
Targa
tgaio
TIF
YUV
CustAttrib
Missing_Custom_Attribute_Plugin
filter
Area
Blackman
Blendfilter
Catmull_Rom
Cook_Variable
cubic
 MAXScript Class Hierarchy 1699

Filter_kernel_plug_in_not_found
Mitchell_Netravali
Plate_Match_MAX_R2
Quadratic
Sharp_Quadratic
Soften
Video
FloatController
AudioFloat
bezier_float
Block
Float_Expression
float_list
Float_Motion_Capture
Float_Reactor
float_script
Float_Wire
FloatList
FloatReactor
linear_float
LOD_Controller
Missing_Float_Control
Noise_float
On_Off
SlaveFloat
tcb_float
Waveform_Float
WireFloat
GlobalUtilityPlugin
MaxRenderer_COM_Server
Plugin_Manager
IKSolver
IKHISolver
IKLimb
MasterBlockController
Block_Control
Master_Controller_plugin_not_found
MasterBlock
MasterList
material
Blend
compositematerial
DoubleSided
doubleSidedMat
Matte
MatteShadow
Missing_Mtl
Morphermaterial
Multimaterial
multiSubMaterial
NoMaterial
1700 Chapter 19 | MAXScript Grammar and Class Hierarchy

RaytraceMaterial
Shellac
standard
Standardmaterial
TexOutputClass
StandardTextureOutput
textureMap
Adobe_Photoshop_Plug_In_Filter
Adobe_Premiere_Video_Filter
bitmapTex
Bitmaptexture
Bricks
Cellular
cellularTex
Checker
Combustion
compositeTexture
CompositeTexturemap
Dent
dents
falloff
fallofftextureMap
Flat_Mirror
flatMirror
Gradient
Gradient_Ramp
Marble
Mask
maskTex
Missing_TextureMap
Mix
mixTexture
Noise
NoTexture
output
Particle_Age
Particle_MBlur
particleBlur
Perlin_Marble
perlinMarble
Planet
Raytrace
Reflect_Refract
reflectRefract
RGB_Multiply
RGB_Tint
rgbMult
rgbTint
Smoke
Speckle
Splat
 MAXScript Class Hierarchy 1701

Stucco
Swirl
Thin_Wall_Refraction
thinWallRefraction
Vertex_Color
Water
Wood
TopBottom
topBottomMat
UVGenClass
Missing_UVGen
StandardUVGen
XYZGenClass
Missing_XYZGen
StandardXYZGen
Matrix3Controller
IK_ControllerMatrix3Controller
IKChainControl
IKControl
Link
Link_Constraint
lookat
Missing_Matrix3_Control
prs
Slave_Control
transform_script
TVDummyControl
modifier
Affect_Region
Bend
BendMod
Bevel
Bevel_Profile
CameraMap
Cap_Holes
ConvertToPatch
CrossSection
DeleteMesh
DeletePatch
DeleteSplineModifier
Disp_Approx
Displace
Edit_Mesh
Edit_Patch
Edit_Spline
Extrude
Face_Extrude
FFD_2x2x2
FFD_3x3x3
FFD_4x4x4
FFD_Select
1702 Chapter 19 | MAXScript Grammar and Class Hierarchy

FFD2x2x2
FFD3x3x3
FFD4x4x4
FFDBox
FFDCyl
Fillet_Chamfer
Flex
HSDS_Modifier
HSDSObject
Lathe
Lattice
Linked_XForm
LinkedXForm
MaterialByElement
Materialmodifier
Melt
Mesh_Select
MeshSelect
meshsmooth
MIrror
Missing_OSM
Morpher
MultiRes
NCurve_Sel
Noisemodifier
Normalize_Spl
Normalize_Spline
Normalmodifier
NSurf_Sel
optimize
Patch_Select
PatchDeform
PathDeform
Point_Cache
PointCache
Poly_Select
Preserve
Push
Relax
Ripple
Skew
Skin
SliceModifier
smooth
SmoothModifier
Spherify
SplineSelect
Squeeze
STL_Check
Stretch
surface
 MAXScript Class Hierarchy 1703

SurfDeform
Taper
tessellate
Trim_Extend
Turn_to_Mesh
Turn_to_Patch
Turn_to_Poly
Twist
Unwrap_UVW
UVW_Xform
Uvwmap
UVWUnwrap
Vertex_Colors
VertexPaint
Vol__Select
VolumeSelect
Wave
XForm
MorphController
Barycentric_Morph_Controller
Cubic_Morph_Controller
Missing_Morph_Control
MPassCamEffect
Depth_of_FieldMPassCamEffect
Motion_BlurMPassCamEffect
multiPassDOF
multiPassMotionBlur
Standin_for_missing_MultiPass_Camera_Effect_Plugin
node
camera
Freecamera
Missing_Camera
Targetcamera
GeometryClass
Apollo_Param_Container
apolloParamContainer
Blizzard
BoneGeometry
BoneObj
Boolean2
Box
C_Ext
Capsule
ChamferBox
ChamferCyl
Cone
Conform
Connect
ControlContainer
CV_Surf
Cylinder
1704 Chapter 19 | MAXScript Grammar and Class Hierarchy

Damper
Editable_mesh
Editable_Patch
Editable_Poly
EditablePolyMesh
Gengon
GeoSphere
Hedra
Hose
L_Ext
Loft
LoftObject
Mesher
meshGrid
Missing_GeomObject
Morph
Nurbs
NURBS_Imported_Objects
NURBSSurf
OilTank
OldBoolean
PArray
particleMesher
PCloud
Plane
Point_Surf
Point_SurfGeometry
PolyMeshObject
Prism
Pyramid
Quadpatch
RingWave
RmModel
RmModelGeometry
Scatter
ShapeMerge
SlidingDoor
SlidingWindow
Snow
Sphere
Spindle
Spray
Spring
SuperSpray
Targetobject
Teapot
Terrain
Torus
Torus_Knot
TriMeshGeometry
Tripatch
 MAXScript Class Hierarchy 1705

Tube
helper
Anchor
AudioClip
Background
Billboard
Bone
BoxGizmo
CamPoint
Compass
Cone_Angle
ConeAngleManip
CylGizmo
Dummy
Falloff_Manipulator
FalloffManip
FogHelper
grid
Hotspot_Manip
HotspotManip
IK_Chain_Object
IK_Swivel_Manip
IKSwivelManip
Inline
LOD
Missing_Helper
NavInfo
Plane_Angle
PlaneAngleManip
Point
PointHelperObj
Position_Manip
PositionManip
Protractor
ProxSensor
radiusManip
Reactor_Angle_Manip
Reactor_Vector_Handle_Manip
ReactorAngleManip
ReactorVectorHandleManip
Rotation_
Rotation_Valuehelper
RotationValueManip
Slider_Manip
SliderManip
sliderManipulator
Sound
SphereGizmo
Tape
TimeSensor
TouchSensor
1706 Chapter 19 | MAXScript Grammar and Class Hierarchy

uvwMappingHeightManip
uvwMappingLengthManip
uvwMappingUTileManip
uvwMappingVTileManip
uvwMappingWidthManip
light
Directionallight
freeSpot
Missing_Light
Omnilight
TargetDirectionallight
targetSpot
NodeObject
shape
Arc
Circle
CV_Curve
CV_Curveshape
Donut
Ellipse
Helix
line
LinearShape
Lines
Missing_Shape
Ngon
NURBSCurveShape
Point_Curve
Point_Curveshape
Rectangle
section
Simple_Shape
Simple_Spline
SplineShape
Star
text
SpacewarpObject
BendModWSM
Bomb
CameraMapSpaceWarp
ConformSpaceWarp
Deflector
Drag
gravity
MapScalerSpaceWarp
Missing_WSM_Object
Motor
Path_Follow
PathDeformSpaceWarp
PBomb
PDynaFlect
 MAXScript Class Hierarchy 1707

PDynaflector
POmniFlect
PSpawnflector
PushSpaceWarp
SDeflector
SDynaFlect
SDynaflector
SOmniFlect
SpaceBend
Spacedisplace
SpaceFFDBox
SpaceFFDCyl
SpaceNoise
Spaceripple
SpaceSkew
SpaceStretch
SpaceTaper
SpaceTwist
Spacewave
SSpawnflector
UDeflector
UDynaDeflector
UDynaFlect
UOmniFlect
USpawnDeflector
Vortex
Wind
System
Bones
Missing_System
Ring_Array
Sunlight
XRefObject
ParamBlock
ParamBlockParamBlock
ParamBlock2
ParamBlock2ParamBlock2
Point3Controller
AudioPoint3
bezier_color
bezier_point3
Color_RGB
Missing_Point3_Control
Noise_point3
Point3_Expression
point3_list
Point3_Motion_Capture
Point3_Reactor
point3_script
Point3_Wire
Point3_XYZ
1708 Chapter 19 | MAXScript Grammar and Class Hierarchy

Point3List
Point3Reactor
Point3Spring
Slave_Point3
SlavePoint3
SpringPoint3Controller
tcb_point3
WirePoint3
PositionController
Attachment
AudioPosition
bezier_position
Dynamics_Position_Controller
linear_position
Missing_Position_Control
Noise_position
path
Path_Constraint
Position_Constraint
Position_Expression
position_list
Position_Motion_Capture
Position_Reactor
position_script
Position_Wire
Position_XYZ
PositionList
PositionReactor
PositionSpring
SlavePos
SpringPositionController
Sunlight_Slave_Controller
Surface_position
tcb_position
WirePosition
QuatController
RadiosityEffect
Missing_Radiosity
ReferenceMaker
CurveControl
CustAttribContainer
Deform_Curve
HSUtil
Material_Editor
MeshCollision
Missing_RefMaker
MtlBaseLib
MtlLib
NamedSelSetList
NodeNamedSelSet
PlanarCollision
 MAXScript Class Hierarchy 1709

Scene
SphericalCollision
StdDualVS
Texmaps
TexmapsReferenceMaker
ReferenceTarget
Auto_Secondary_Element
Bulge_Angle_Deformer
gizmoBulge
gizmoJoint
gizmoJointMorph
Glow_Element
Gradient_GradCtlData
IK_Controller
JAngleData
JBinaryData
JBoolData
JColor3Data
JColorData
JFlagCtlData
JFlagSetData
JFloat3Data
JFloatData
JGradCtlData
Joint_Angle_Deformer
Joystick_Input_Device
JPercent3Data
JPercentData
JSubtex
JWorld3Data
JWorldData
LZFlare_AutoSec_Base
LZFlare_AutoSec_Data
LZFlare_Aux_Data
LZFlare_Data
LZFlare_Glow_Data
LZFlare_Inferno_Data
LZFlare_ManSec_Base
LZFlare_ManSec_Data
LZFlare_Prefs_Data
LZFlare_Rays_Data
LZFlare_Rend_Data
LZFlare_Ring_Data
LZFlare_Star_Data
LZFlare_Streak_Data
LZFocus_Data
LZGlow_Aux_Data
LZGlow_Data
LZGlow_Rend_Data
LZHilight_Aux_Data
LZHilight_Data
1710 Chapter 19 | MAXScript Grammar and Class Hierarchy

LZHilight_Rend_Data
Manual_Secondary_Element
MIDI_Device
Missing_RefTarget
Morph_Angle_Deformer
Mouse_Input_Device
Ray_Element
Ray_Engine
Raytrace_Engine_Global_Parameters
Raytrace_Texture_ParamBlock
RenderElementMgr
Ring_Element
Star_Element
Streak_Element
This_Data
TVNode
renderEffect
blur
Brightness_and_Contrast
briteCon
Color_Balance
colorBalance
Depth_of_Field
DOFEffect
File_Output
fileOut
Film_Grain
FilmGrain
imageMotionBlur
Lens_Effects
Missing_Render_Effect
Motion_Blur
RenderElement
Alpha
alphaRenderElement
Atmosphere
atmosphereRenderElement
BackgroundRenderElement
Beauty
beautyRenderElement
bgndRenderElement
BlendRenderElement
clrShadowRenderElement
Colored_Shadow
Diffuse
diffuseRenderElement
emissionRenderElement
Missing_Render_Element_Plug_in
Reflection
reflectionRenderElement
Refraction
 MAXScript Class Hierarchy 1711

refractionRenderElement
Self_Illumination
ShadowRenderElement
Specular
specularRenderElement
Z_Depth
ZRenderElement
RendererClass
Default_Scanline_Renderer
DefaultScanlineRenderer
Missing_Renderer
VUE_File_Renderer
RotationController
AudioRotation
bezier_rotation
Dynamics_Rotation_Controller
Euler_XYZ
linear_rotation
Local_Euler_XYZ
LookAt_Constraint
Missing_Rotation_Control
Noise_rotation
Orientation_Constraint
rotation_list
Rotation_Motion_Capture
Rotation_Reactor
rotation_script
Rotation_Wire
RotationList
RotationReactor
SlaveRotation
tcb_rotation
WireRotation
ScaleController
AudioScale
bezier_scale
linear_scale
Missing_Scale_Control
Noise_scale
Scale_Expression
scale_list
Scale_Motion_Capture
Scale_Reactor
scale_script
Scale_Wire
ScaleList
ScaleReactor
ScaleXYZ
SlaveScale
tcb_scale
WireScale
1712 Chapter 19 | MAXScript Grammar and Class Hierarchy

Shader
Anisotropic
Blinn
Blinn2
BlinnShader
Metal
Metal2
Missing_Shader_Plug_in
Multi_Layer
MultiLayer
Oren_Nayar_Blinn
OrenNayarBlinn
Phong
Phong2
Strauss
Shadow
raytraceShadow
shadowMap
SpacewarpModifier
Bombbinding
Deflectorbinding
Displace_Mesh
Displace_NURBS
Displacebinding
DragMod
FFD_Binding
Gravitybinding
MapScaler
Missing_WSM
MotorMod
Particle_Cache
ParticleCache
Path_FollowMod
PBombMod
PDynaFlectMod
Point_CacheSpacewarpModifier
PointCacheWSM
POmniFlectMod
PushMod
Ripplebinding
SDeflectMod
SDynaFlectMod
SimpleOSMToWSMMod
SOmniFlectMod
SpaceCameraMap
SpaceConform
SpacePatchDeform
SpacePathDeform
SpaceSurfDeform
Surface_Mapper
UDeflectorMod
 MAXScript Class Hierarchy 1713

UDynaFlectMod
UOmniFlectMod
VortexMod
Wavebinding
Windbinding
ToneOperator
Automatic_Exposure_Control
AutomaticAdaptiveExposureControl
Missing_Exposure_Control
UtilityPlugin
ASCII_Object_Output
Asset_Browser
Assign_Vertex_Colors
Camera_Match
Camera_Tracker
collapse
Color_Clipboard
COM_DCOM_Server_Control
Dynamics
Follow_Bank
IFL_Manager
Level_of_Detail
Link_Inheritance__Selected
MapPath_Editor
MAX_File_Finder
MAXScript
Measure
Motion_Capture
Polygon_Counter
Rescale_World_Units
Reset_XForm
Resource_Collector
Shape_Check
Strokes
Surface_Approximation
UVW_Remove
Visual_MAXScript
VisualMSUtil
1714 Chapter 19 | MAXScript Grammar and Class Hierarchy
Chapter 20: Using the HTML Help Viewer

Using the HTML Help Viewer

This online information system is a compiled HTML help (.chm) file; you view it using Microsoft’s
HTML Help Viewer, powered by Internet Explorer. The HTML Help Viewer is a three-pane window:
• The Navigation pane (p. 1717) is on the left side of the window. It contains four navigational tabs,
for Contents, Index, Search (p. 1718), and Favorites (p. 1721).
• The Topic pane is on the right side of the window. It displays the selected help topic, or the
default help topic.
• The toolbar (p. 1721) is the third pane, located below the help window title bar.
Here are some tips on how to find more information when using the HTML Help Viewer:
• To link to another topic or a list of other topics, click the colored, underlined words in the
Topic pane.
• If you use a particular help topic often, you can add it to your favorites list (p. 1721).
• Right-click the Contents or Favorites tab or the Topic pane for shortcut menu commands.

See also
Finding Information Fast (p. 1717)
Searching for Help Topics (p. 1718)
Note: Most of information about using the HTML Help Viewer has been supplied directly by
Microsoft. It has been made freely available for inclusion in HTML help projects such as this one.
This information has been edited and reformatted to match the Discreet online information
systems.
1716 Chapter 20 | Using the HTML Help Viewer

Procedures
To find a help topic
1. In the Navigation pane, click one of the following tabs:
• To browse through a table of contents, click the Contents tab. The table of contents is an
expandable list of important topics.
• To see a list of index entries, click the Index tab, and then type a word or scroll through the
list. Topics are often indexed under more than one entry.
• To locate every occurrence of a word or phrase that may be contained in a help file, click the
Search tab, and then type the word.
2. Click the contents entry, index entry, or search results entry to display the corresponding topic.

To copy a help topic

1. In the Topic pane, right-click the topic you want to copy, and then click Select All.
2. Right-click again, and then click Copy. This copies the topic to the Clipboard.
3. Open the document you want to copy the topic to.
4. Position your cursor where you want the information to appear.
5. On the Edit menu, click Paste.

To copy only part of a topic

• Select the text you want to copy, right-click, and then click Copy.

To print the current help topic

• Right-click a topic, and then click Print.
If you print from the Contents tab (by right-clicking an entry, and then clicking Print) you will
see options to print only the current topic, or the current topic and all subtopics.

To hide or show the Navigation pane

• On the toolbar, click Hide or Show to close or display the Navigation pane, which contains the
Contents, Index, Search, and Favorites tabs.
If you close the Help Viewer with the Navigation pane hidden, it will appear that way when you
open the Help Viewer again.
 Finding Information Fast 1717

Finding Information Fast

Use the Navigation pane in the Help Window to get to information quickly. It contains tabs that let
you use Contents, Index, or Search techniques to get to topics you need.

Contents Tab
The Contents tab displays the main sections of this 3ds max online system as book icons. When
you click a book, it expands to show the list of topics contained within it, like chapters in hard-copy
books.

To go to a topic from the Contents tab

1. Click the Contents tab to display the Table of Contents view.
2. Click the book icon representing the area for which you want information.
The page icons for the book expand below representing all the topics for the book’s feature area.
3. Click the page icon for the topic you want.

Index Tab
The Index is an alphabetical listing of keywords found in each topic. A single keyword may be linked
to more than one topic. You may type the first few letters of a subject to jump to an index entry that
matches what you are looking for.

To go to a topic from the Index tab

1. Click the Index tab to display the Help Index.
2. In the form at the top of the Index, type the subject you want to find, or scroll through the
alphabetical list to find the term for which you need information.
3. Click the term, then click Display to see the topic for that term, or double-click the term to see
its topic.
The topic displays in the right pane and may show links to related topics.

Search Tab
The Search tab summons a full-text search engine that operates on a database of every word in the
help system, created when the HTML Help system was compiled. You can use tools on the Search
tab to find the help topics (p. 1718) containing any word or phrase.
1718 Chapter 20 | Using the HTML Help Viewer

Searching for Help Topics

A basic search consists of the word or phrase you want to find. You can use Boolean, wildcard, and
nested expressions. You can also limit the search to previous results, match similar words, or search
topic titles only to further define your search.
The basic rules for formulating queries are as follows:
• Searches are not case-sensitive, so you can type your search in uppercase or lowercase characters.
• You may search for any combination of letters (a through z) and numbers (0 through 9).
• Punctuation marks such as the period, colon, semicolon, comma, and hyphen are ignored
during a search.
• Group the elements of your search using double quotes (p. 1718) or parentheses (p. 1719) to set
apart each element. You cannot search for quotation marks.
Note: If you are searching for a file name with an extension, you should group the entire string
in double quotes, (“filename.ext”). Otherwise, the period will break the file name into two
separate terms. The default operation between terms is AND, so you will create the logical
equivalent to “filename AND ext.”

Searching for Words or Phrases: Using Wildcards

You can search for words or phrases and use wildcard expressions. Wildcard expressions allow you
to search for one or more characters using a question mark or asterisk. The table below describes the
results of these different kinds of searches.

Search for Example Results

A single word select Topics that contain the word “select.” (You will also find its grammatical
variations, such as “selector” and “selection.”)
A phrase “new operator” Topics that contain the literal phrase “new operator” and all its
or grammatical variations.
new operator Without the quotation marks, the query is equivalent to specifying “new
AND operator,” which will find topics containing both of the individual
words, instead of the phrase.
Wildcard expressions esc* Topics that contain the terms “ESC,” “escape,” “escalation,” and so on.
or The asterisk cannot be the only character in the term.
80?86 Topics that contain the terms “80186,” “80286,” “80386,” and so on.
The question mark cannot be the only character in the term.

Turn on Match Similar Words to include minor grammatical variations for the phrase you search.
 Searching for Help Topics 1719

Defining Search Terms: Using Boolean Expressions

The AND, OR, NOT, and NEAR operators enable you to precisely define your search by creating a
relationship between search terms. The following table shows how you can use each of these
operators. If no operator is specified, AND is used. For example, the query “spacing border printing”
is equivalent to “spacing AND border AND printing.”

Search for Example Results

Both terms in the dib AND palette Topics containing both the words “dib” and “palette.”
same topic.
Either term in raster OR vector Topics containing either the word “raster” or the word “vector”
a topic. or both.
The first term without ole NOT dde Topics containing the word “OLE,” but not the word “DDE.”
the second term.
Both terms in the user NEAR kernel Topics containing the word “user” within eight words of the
same topic, close word “kernel.”
together.

Note: The |, &, and ! characters don’t work as Boolean operators (you must use OR, AND, and NOT).

Using Nested Expressions When Searching

Nested expressions allow you to create complex searches for information. For example, “control
AND ((active OR dde) NEAR window)” finds topics containing the word “control” along with the
words “active” and “window” close together, or containing “control” along with the words “dde”
and “window” close together.
The basic rules for searching help topics using nested expressions are as follows:
• You can use parentheses to nest expressions within a query. The expressions in parentheses are
evaluated before the rest of the query.
• If a query does not contain a nested expression, it is evaluated from left to right. For example:
“Control NOT active OR dde” finds topics containing the word “control” without the word
“active,” or topics containing the word “dde.” On the other hand, “control NOT (active OR
dde)” finds topics containing the word “control” without either of the words “active” or “dde.”
• You cannot nest expressions more than five levels deep.

Procedures
To go to a topic from the Search tab
1. Click the Search tab, and then type the word or phrase you want to find.

2. Click the Boolean button (to the right of the test field) to add Boolean operators to your
search.
3. Click List Topics, choose the topic you want, and then click Display.
4. To sort the topic list alphabetically, click the Title column heading.
1720 Chapter 20 | Using the HTML Help Viewer

You can precisely define a search by using wildcard expressions, nested expressions, and Boolean
operators.
You can request similar word matches, search only the topic titles, or search the results of a previous
search.
You can set the Help Viewer to highlight all instances of search terms that are found in topic files.
Click the Options button, and then click Search Highlight On.

To highlight words in searched topics

When searching for words in help topics, you can have each occurrence of the word or phrase
highlighted in the topics that are found.
• To highlight all instances of a search word or phrase, click Options on the toolbar, and then click
Search Highlight On.
To turn off this option, click Options on the toolbar, and then click Search Highlight Off.
If you are viewing a long topic, only the first 500 instances of a search word or phrase will be
highlighted.

To search for words in the titles of HTML files

1. Click the Search tab, type the word or phrase you want to find, and then turn on Search
Titles Only.
2. Click List Topics, choose the topic you want, and then click Display.
If you use this option, all HTML topic files will be searched, including any that are not listed in
the table of contents.

To find words similar to your search term

This feature enables you to include minor grammatical variations for the phrase you search. For
example, a search on the word “add” will find “add,” “adds,” and “added.”
1. Click the Search tab, type the word or phrase you want to find, and then turn on Match
Similar Words.
2. Click List Topics, choose the topic you want, and then click Display.
This feature only locates variations of the word with common suffixes. For example, a search on
the word “add” will find “added,” but it will not find “additive.”

To search only the last group of topics you searched

This feature enables you to narrow a search that results in too many topics found. You can search
through your results list from previous search by using this option.
1. On the Search tab, turn on Search Previous Results.
2. Click List Topics, choose the topic you want, and then click Display.
If you want to search through all of the files in a help system, this check box must be off.
If you previously used this feature, the Search tab opens with this check box turned on.
 Favorites Tab 1721

To repeat an earlier search

• Click the down arrow on the text-entry field and choose a previously used search string, and
then click List Topics.

Favorites Tab
Use tools on the Favorites tab to create a set of topics you use often; you can name them as you
choose.

Procedures
To create a list of favorite help topics
1. Locate the help topic you want to make a favorite topic.
2. Click the Favorites tab, and then click Add.

To return to a favorite topic

1. Click the Favorites tab.
2. Choose the topic, and then click Display.

To rename a topic in the Favorites list

• Choose the topic, and then enter a new name in the Current topic box.

To remove a favorite topic

• Choose the topic, and then click Remove.

HTML Help Viewer Toolbar

The Help Viewer toolbar contains the following features.
Hide/Show: Click this toggle to hide the Navigation pane when it is displaying, or show it when it’s
hidden.
Back/Forward: Click to move to the previously viewed topic, or forward to the following previously-
viewed topic.
Print: Prints the current topic (if the Topic pane is active). If the table of contents is active on the
Navigation pane, you can choose to print the current topic, or the topic and its subtopics. This is a
way of printing a collection of topics.
Options menu: Contains the following commands.
Hide/Show Tabs: Same as Hide/Show buttons, above.
Back/Forward: Same as Back/Forward buttons, above.
Home: Displays the main topic of this online system.
Stop: Halts display of a topic.
Refresh: Redraws the Help Viewer display.
1722 Chapter 20 | Using the HTML Help Viewer

Internet Options: Displays a dialog to change Internet Explorer (IE) settings. The 3ds max
information systems do not use this feature. Making changes here does not affect these systems,
but will alter your IE browser settings. We do not recommend you use this option.
Print: Same as the Print button, above.
Search Highlight On/Off: Toggles highlighting on and off for each occurance of a word or phrase
found with a search.

HTML Help Viewer Right-Click Menus

There are several commands on the shortcut menu that you can use to display information.

Command Description
Right-click in the table of contents, and then click Opens all books or folders in the table of contents. This
Open All. command only works if the Contents tab is displayed.
Right-click in the table of contents, and then click Closes all books or folders. This command only works if
Close All. the Contents tab is displayed.
Right-click in the Topic pane, or an entery in the table of Prints the topic.
contents, and then click Print.
Right-click an entry in the Favorites tab. Choose to display, add, remove, or rename a topic.

Keyboard Shortcuts in the Help Viewer

The following keyboard shortcuts can be used for navigation in the HTML Help Viewer, or the
Contents (p. 1723), Index (p. 1723), Search (p. 1723), or Favorites (p. 1724) tabs on the Navigation
pane.

Help Viewer

To Press
Close the Help Viewer. ALT+F4
Switch between the Help Viewer and other open ALT+TAB
windows.
Display the Options menu. ALT+O
Hide or show the Navigation pane. ALT+O, and then press T
Print a topic. ALT+O, and then press P, or right-click in the Topic pane
and choose Print.
Move back to the previous topic. ALT+LEFT ARROW, or ALT+O, and then press B
Move forward to the next topic (provided you have ALT+RIGHT ARROW, or ALT+O, and then press F
viewed it just previously).
Turn on or off search highlighting. ALT+O, and then press O
Refresh the topic that appears in the Topic pane (this is F5, or ALT+O, and then press R
useful if you have linked to a Web page).
 Keyboard Shortcuts in the Help Viewer 1723

To Press
Return to the home page (help authors can specify a ALT+O, and then press H
home page for a help system).
Switch between the Navigation and Topic panes. F6
Scroll through a topic. UP ARROW and DOWN ARROW, or PAGE UP and PAGE
DOWN
Scroll through all the links in a topic or through all the TAB
options on a Navigation pane tab.

Contents Tab

To Press
Display the Contents tab. ALT+C
Open and close a book or folder. PLUS SIGN and MINUS SIGN, or LEFT ARROW and RIGHT
ARROW
Choose a topic. DOWN ARROW and UP ARROW
Display the selected topic. ENTER

Index Tab

To Press
Display the Index tab. ALT+N
Type a keyword to search for. ALT+W, and then type the word
Choose a keyword in the list. UP ARROW and DOWN ARROW
Display the associated topic. ALT+D

Search Tab

To Press
Display the Search tab. ALT+S
Type a keyword to search for. ALT+W, and then type the word
Start a search. ALT+L
Choose a topic in the results list. ALT+T, and then UP ARROW and DOWN ARROW
Display the selected topic. ALT+D
Search for a keyword in the result list of a prior search. ALT+U
Search for words similar to the keyword. For example, ALT+M
to find words like “running” and “runs” for the
keyword “run.”
Only search through topic titles. ALT+R
1724 Chapter 20 | Using the HTML Help Viewer

Favorites Tab

To Press
Display the Favorites tab. ALT+I
Add the currently displayed topic to the Favorites list. ALT+A
Choose a topic in the Favorites list. ALT+P, and then UP ARROW and DOWN ARROW
Display the selected topic. ALT+D
Remove the selected topic from the list. ALT+R

Notes:
• There are also shortcut menu commands (p. 1722) that can be accessed through the keyboard.
• Every time you use a shortcut key in the Navigation pane, you lose focus in the Topic pane. To
return to the Topic pane, press F6.
• The Match Similar Words check box, on the Search tab, will be turned on if you used it for your
last search.
Chapter 21: character studio 3 MAXScript Extensions

Biped General Topics

Biped Load and Save Methods

This topic will cover the load and save methods for motion, figure, score, keys, motion capture, and
talent files.
-- Motion File Access Methods
biped.LoadBipFile <biped_ctrl> <filename>
Load a biped motion file. Motion files include, footsteps, keyframe settings, the biped
scale, and the active gravity value (GravAccel). IK Blend values for the keys and Object
Space Object information are also loaded.
biped.SaveBipFile <biped_ctrl> <filename>
Save a biped motion file. A .bip file includes footsteps and keyframe data. Biped files store
the complete movement and allow you to create libraries of motion. Create your own .bip
library by animating the biped and saving a .bip file.
Notes:
Load/Save a Biped (.BIP) file
-- Figure File Access Methods
biped.LoadFigFile <biped_ctrl> <filename>
Load a Figure file. Figure mode must be active to load a Figure file. Figure files allow you to
apply the structure of one biped to another. Reload a Figure file if you accidentally lose
your biped Figure mode pose; this pose is the biped fitted to a mesh.
biped.SaveFigFile <biped_ctrl> <filename>
Save the structure and position of a biped in Figure mode. After fitting the biped to a mesh
in Figure mode, save a figure file. If the biped is accidentally moved in Figure mode, reload
this file.
1726 Chapter 21 | character studio 3 MAXScript Extensions

Notes:
Load/Save a Figure (*.FIG) file
-- Score File Access Methods
biped.LoadScoreFile <biped_ctrl> <filename>
biped.SaveScoreFile <biped_ctrl> <filename>
Score files are Step files which save footsteps, but don’t save body keyframes. They are an
ASCII file format that enables developers to write programs that generate step files for
biped motion. The online document stp.rtf, provided with character studio in the
\cstudio\docs directory, describes the .stp format.
Notes:
Load/Save a Step (*.STP) file
-- Motion Capture File Access Methods
biped.loadMocapFile <biped_ctrl> <file_name> [#prompt]
Load a motion capture (.BIP, .BVH, .CSM) file. If #prompt is specified, the file is not
automatically loaded, rather the Motion Capture Conversion Parameters dialog is
displayed with the specified file as the motion capture file.
-- Talent File Access Methods
biped.adjustTalentPose <biped_ctrl>
After loading a marker file, use Adjust Talent Pose to correct the biped position relative to
the markers. Align the biped limbs to the markers then call biped.adjustTalentPose to
compute this offset for all the loaded marker data.
Note:
Calibration controls are only enabled when a marker or .bvh file is imported in its raw form. Do not
use key reduction or extract footsteps when you import a marker file for the first time.
biped.saveTalentFigFile <biped_ctrl> <file_name>
After changing the biped scale in Talent Figure mode, save the changes into a .fig file. Use
this file in the Motion Capture Conversion Parameters dialog to adjust marker files created
by the same actor.
biped.saveTalentPoseFile <biped_ctrl> <file_name>
Save a Talent Pose adjustment as a .cal file.
Save a .cal file after adjusting the biped relative to the markers. A .cal file is used for
processing marker files that require the same adjustment. A .cal file can be loaded in the
Motion Capture Conversion Parameters dialog during marker file importation.
-- Layer related methods
biped.collapseAtLayer <biped_ctrl> <index>
Collapses all layers till the specified layer. All underneath should be active for this function
to work. Return true if successful, otherwise false.
biped.createLayer <biped_ctrl> <index> <name>
Creates a layer at the specified position, maximum index value can be NumLayers + 1
 Biped Creation 1727

biped.deleteLayer <biped_ctrl> <index>

Deletes the specified layer
biped.getCurrentLayer <biped_ctrl>
Returns the position of the currently active layer in the UI
biped.getLayerActive <biped_ctrl> <index>
Returns true if the specified layer is active.
biped.getLayerName <biped_ctrl> <index>
Returns the specified layer name
biped.numLayers <biped_ctrl>
Returns the number of layers
biped.setCurrentLayer <biped_ctrl> <index>
Sets the active layer in the UI to the specified layer
biped.setLayerActive <biped_ctrl> <index> <bool_val>
Sets the specified layer to active/inactive based upon the bool_val passed
biped.setLayerName <biped_ctrl> <index> <name>
Sets the specified layer name to the value passed
The following example will create a new Biped, access it’s Vertical_Horizontal_Turn(Body) controller
and load a specific *.Bip file:
Script Example:
-- create a new Biped
bipObj = biped.createNew 100 100 [0,0,0]
-- select bipObj
bip = bipObj.transform.controller
max motion mode
-- File I/O
biped.LoadBipFile bip (CSPATH + “scripts\\Limploop.bip”)

See Also
Biped Creation (p. 1727)
Biped Controllers (p. 1735)
Biped MaxScript Extensions (p. 1725)

Biped Creation
The following properties and methods are applicable to any created Biped.
Constructor:
biped.createNew <height_float> <angle_float> <wpos_point3> . . .

<height_float> the height of the Biped to be created

<angle_float> angle in degrees
0( will make the Biped face towards the right.
<wpos_point3> world position of the Biped. This is the position of the COM
shadow.
1728 Chapter 21 | character studio 3 MAXScript Extensions

Creation Properties:
<biped>.arms Boolean Default: True
Specifies whether or not arms will be generated for the current biped.
<biped>.neckLinks Integer Default: 1
Specifies the number of links in the biped neck.
<biped>.spineLinks Integer Default: 4
Specifies the number of links in the biped spine.
<biped>.legLinks Integer Default: 3
Specifies the number of links in the biped legs.
<biped>.tailLinks Integer Default: 0
Specifies the number of links in the biped tail. A value of 0 specifies no tail.
<biped>.ponytail1Links Integer Default: 0
Specifies the number of Ponytail links.
<biped>.ponytail2Links Integer Default: 0
Specifies the number of Ponytail links.
<biped>.fingers Integer Default: 1
Specifies the number of biped fingers.
<biped>.fingerLinks Integer Default: 3
Sets the number of links per finger.
<biped>.toes Integer Default: 5
Specifies the number of biped toes.
<biped>.toeLinks Integer Default: 3
Specifies the number of links per toe.
<biped>.ankleAttach Float Default: 0.2
Specifies the right and left ankles’ point of attachment along the corresponding foot block.
The ankles may be placed anywhere along the center line of the foot block from the heel
to the toe.
A value of 0 places the ankle attachment point at the heel. A value of 1 places the ankle
attachment point at the toes.
<biped>.trianglePelvis Boolean Default: True
Select this control to create links from the upper legs to the lowest biped spine object
when Physique is applied. Normally, the legs are linked to the biped pelvis object.
The pelvis area can be a problem when the mesh is deformed with Physique. Triangle
Pelvis creates a more natural spline for mesh deformation.
 Biped Display Preferences Access 1729

Notes:
Creates a new Biped with the given keyword parameters. All UI limit constraints apply on keyword
parameters, example: fingers and fingerLinks parameters are not respected when arms is set to false.
The following example will create a Biped with specific non default values and facing the front.
Script Example:
bipObj = biped.createNew 100 -90 [0,0,0] arms:true neckLinks:2 \
spineLinks:4 legLinks:4 tailLinks:1 ponyTail1Links:1 \
ponyTail2Links:1 fingers:5 fingerLinks:2 toes:4 \
toesLinks:2 ankleAttach:0.3 trianglePelvis:True

See also
Biped MAXScript Extensions (p. 1725)

Biped Display Preferences Access

Displays the Biped Display Preferences dialog.
Method:
biped.displayPrefsDlg <biped_ctrl>

<biped_ctrl> Controller which is attached to the transform track of the Biped

root objects.
A Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller (p. 1736)

The following example will display the Biped Display Preferences dialog:
Script Example:
bipObj = biped.createNew 100 100 [0,0,0]
select bipObj
bip = bipObj.transform.controller
-- Display properties
biped.displayPrefsDlg bip

See Also
Biped Creation (p. 1727)
Biped Controllers (p. 1735)
Biped MaxScript Extensions (p. 1725)
1730 Chapter 21 | character studio 3 MAXScript Extensions

Biped Sample Scripts

Here are the sample scripts that ship with character studio 3.
The custom user interface, CS3Tools.cui, character studio 3 one-touch preset custom keys for
rapid animation. It uses the MAXScripts: CS3Customkeys.ms, CS3convertBips.ms and
CS3Bip2BonesFloater.ms and CS3CustomKeysPresetFloater.ms.
Please see the CS3Tools.cui Tutorial (p. 1825) Tutorial_CSCustomKeys_cui2.
An updated ../Cstudio/Docs/Readcsm.ms.
-- Fixed frame-off-by-1 bug by making keyframes start at 0 instead of 1, to match biped
-- Fixed frame rate interpretation - it was dropping mocap data correctly, but not skipping
max frames
../Cstudio/Docs/csmxport.ms
-- A script to output a .csm file
-- This script assumes that you have set up a .max file containing a biped or bone structure
with a set of markers linked to the skeleton.
-- The markers you want to record should be contained in a Selection Set titled “markers”
-- The script will output the data at every frame for the entire animation range.

See also
Biped MAXScript Extensions (p. 1725)

biped_object : GeometryClass
This class represents the individual Biped body part and footstep nodes’ baseobject.
Properties:
<biped_object>.rootNode Node Default: Varies -- Read-only
The controller for the biped_object. For the COM, the controller type is
Vertical_Horizontal_Turn. For footsteps, the controller type is FootSteps. For the remaining
biped body parts, the controller type is BipSlave_Control.

See Also
Vertical_Horizontal_Turn Matrix3 Controller (p. 1736)
FootSteps : Matrix3 Controller (p. 1744)
BipSlave_Control Controllers (p. 1745)
 Biped Layers 1731

Biped Layers
Layer Related Methods
biped.collapseAtLayer <biped_ctrl> <index_integer>
Collapses all layers till the specified layer. All underneath must be active for this function
to work. Return true if successful, otherwise false.
biped.createLayer <biped_ctrl> <index_integer> <name_string>
Creates a layer at the specified position, maximum index value can be NumLayers + 1.
biped.deleteLayer <biped_ctrl> <index_integer>
Deletes the specified layer
biped.getCurrentLayer <biped_ctrl>
Returns the position of the currently active layer in the UI.
biped.getLayerActive <biped_ctrl> <index_integer>
Returns true if the specified layer is active.
biped.getLayerName <biped_ctrl> <index_integer>
Returns the specified layer name.
biped.numLayers <biped_ctrl>
Returns the number of layers.
biped.setCurrentLayer <biped_ctrl> <index_integer>
Sets the active layer in the UI to the specified layer.
biped.setLayerActive <biped_ctrl> <index_integer> <boolean_val>
Sets the specified layer to active/inactive based upon the boolean_val passed.
biped.setLayerName <biped_ctrl> <index_integer> <name_string>
Sets the specified layer name to the value passed.

Biped Node Hierarchy

biped.getNode <biped | biped_ctrl> <name | index> [link:<int_link>]
Returns the specified limbnode where the second argument can be a named limb like
#larm, #rarm, #lfingers, #rfingers, #lleg, #rleg, #ltoes, #rtoes, #spine, #tail, #head, #pelvis,
#footprints, #neck, #pony1, #pony2 or an integer index. . If you don’t specify the link
argument the top (first) node is returned. The only exception to this is for the biped COM,
which does not contain any linked nodes (including itself). If the specified node does not
exist, a value of undefined is returned.
1732 Chapter 21 | character studio 3 MAXScript Extensions

The top level and their link nodes in character studio 3 are:

Link Nodes in Link

Index Top Level Index Order
1 L Clavicle L Clavicle L UpperArm L Forearm L Hand
2 R Clavicle R Clavicle R UpperArm R Forearm R Hand
3 L Finger0 L Finger0 L Finger01 L Finger02 L Finger1
L Finger11 L Finger12 L Finger2 L Finger21
L Finger22 L Finger3 L Finger31 L Finger32
L Finger4 L Finger41 L Finger42
4 R Finger0 R Finger0 R Finger01 R Finger02 R Finger1
R Finger11 R Finger12 R Finger2 R Finger21
R Finger22 R Finger3 R Finger31 R Finger32
R Finger4 R Finger41 R Finger42
5 L Thigh L Thigh L Calf L HorseLink L Foot
6 R Thigh R Thigh R Calf R HorseLink R Foot
7 L Toe0 L Toe0 L Toe01 L Toe02 L Toe1
L Toe11 L Toe12 L Toe2 L Toe21
L Toe22 L Toe3 L Toe31 L Toe32
L Toe4 L Toe41 L Toe42
8 R Toe0 R Toe0 R Toe01 R Toe02 R Toe1
R Toe11 R Toe12 R Toe2 R Toe21
R Toe22 R Toe3 R Toe31 R Toe32
R Toe4 R Toe41 R Toe42
9 Spine Spine Spine1 Spine2 Spine3
Spine4
10 Tail Tail Tail1 Tail2 Tail3
Tail4
11 Head Head
12 Pelvis Pelvis
13 Biped COM
14 Biped COM
15 Biped COM
16 Footsteps Footsteps
17 Neck Neck Neck1 Neck2 Neck3
Neck4
18 Ponytail1 Ponytail1 Ponytail11 Ponytail12 Ponytail13
Ponytail14
19 Ponytail2 Ponytail2 Ponytail21 Ponytail22 Ponytail23
Ponytail24
 Biped Node Hierarchy 1733

Example:
bipObj = biped.createNew 100 100 [0,0,0] -- create a biped
nn = biped.maxNumNodes bipObj
nl = biped.maxNumLinks bipObj
for i = 1 to nn do
( anode = biped.getNode bipObj i
if anode != undefined do
( format “% :\t%\n” i anode.name
for j = 1 to nl do
( alink = biped.getNode bipObj i link:j
if alink != undefined do
format “% : % \t%\n” i j alink.name
)
)
)

Biped Node Hierarchy related methods:

biped.maxNumNodes <biped | biped_ctrl>
Maximum nodes supported by Biped. In character studio 3, this value is 19. In future
versions of character studio, additional top level nodes may be present. See the desrciption
of biped.getNode() for a list of the top level nodes.
biped.maxNumLinks <biped | biped_ctrl>
Maximum link nodes supported by Biped. In character studio 3 this value is 16. In future
versions of character studio, additional link nodes may be present. See the desrciption of
biped.getNode() for a list of the link nodes.
There are two levels of nodes in biped hierarchy, the top level ones are:
L Clavicle
R Clavicle
L Thigh
R Thigh
Head
Spine
Pelvis
Footsteps
Neck
1734 Chapter 21 | character studio 3 MAXScript Extensions

The rest of the nodes are links just like what you see in the structure rollout.
UpperArm
L Hand
Finger2
Calf
Foot
...etc
You can get to left hand as follows: biped.getNode $ #lArm link:4
If the link argument is not specified then the top(first) node is returned.

Biped and Crowd Interaction

It is possible to influence clip selection for bipeds during a Crowd solution by using preferred clips.
The following biped MAXScript functions allow users to set the biped preferred clip during a crowd
solution (p. 1771).
biped.numPrefClips <biped_ctrl>
Returns the number of preferred clips
biped.getPrefClip <biped_ctrl> <index_integer>
Returns the name of the nth preferred clip.
biped.clearPrefClips <biped_ctrl>
Clears the preferred clip list.
biped.addPrefClip <biped_ctrl> <name_string>
Adds the clip to the preferred clip list. returns true if added, false if not added because it
was already in the list.
biped.deletePrefClip <biped_ctrl> <name_string>
Deletes the named clip from the preferred clip list. Returns true is successful, false if the
clip was not in the list.
biped.isPrefClip <biped_ctrl> <name_string>
Returns true if the clip is in the list, false if not.
biped.getCurrentClip <biped_ctrl>
Returns the name of the currently active clip for this biped - only relevant during a
crowd solve.
 Biped and Crowd Interaction 1735

The following are examples showing how the crowd system “PerFrameFn” (p. 1771) can be used to
dynamically change the biped preferred clip.
Example:
-- changes the preferred clip as a function of frame number.
fn PerFrameFn crwd t = (
if (t == 200f) then
(
a = $bip100
a = a.transform.controller
biped.addprefclip a “jog_L45”
))

Example:
-- changes the preferred clip as a function of the current clip.
fn PerFrameFn crwd t = (
a = $bip100
a = a.transform.controller
if (biped.getcurrentclip a == “jog_L135”) then
biped.addprefclip a “jog_L45”
)

See Also
Crowd : helper (p. 1771)

Biped Controllers
The Biped controller, referred to as “<biped_ctrl>” in this documentation, is called the Biped
Vertical_Horizontal_Turn(Body):Matrix3 Controller (p. 1736). This is sometimes also called the body
controller because it is equivalent to the Biped’s.transform.controller.
The Biped footsteps have a controller. It is referred to as “<footsteps_ctrl>” in this documentation.
See Biped Footsteps (p. 1745) for details regarding the FootSteps:Matrix3 Controller.
Individual Biped body part objects and the Vertical, Horizontal, and Turning tracks of the Biped
Vertical Horizontal Turn(Body):Matrix3_Controller (p. 1736) use the Biped Slave
ControllerBiped_Slave_Controller Biped_Slave_Controller. This type of controller is attached to the
transform track.

See also
Biped Slave Controller (p. 1745)
Biped MAXScript Extensions (p. 1725)
1736 Chapter 21 | character studio 3 MAXScript Extensions

Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller

This controller is attached to the transform track of the Biped root objects.
Constructor:
biped_ctrl=bipobj.transform.controller

or:
<biped_ctrl>=$bip01.controller

Properties:
All the following properties are get/set properties unless specified.
-- Structure properties
<biped_ctrl>.rootName String Default: BipXX,
where XX is a number
The name of the biped center of mass object. The center of mass (COM) is the root of the
biped hierarchy, and is visible as a diamond shaped object in the biped pelvis area. The
Root Name is appended to all the links of the biped hierarchy.
<biped_ctrl>.rootNode Node Default: Varies -- Read-only
The root node (COM) of the Biped system this biped_ctrl belongs to.
<biped_ctrl>.arms Boolean Default: True
Specifies whether or not arms will be generated for the current biped.
<biped_ctrl>.neckLinks Integer Default: 1 range: 1-5
Specifies the number of links in the biped neck.
<biped_ctrl>.spineLinks Integer Default: 4 range: 1-5
Specifies the number of links in the biped spine.
<biped_ctrl>.legLinks Integer Default: 3 range: 3-4
Specifies the number of links in the biped legs.
<biped_ctrl>.tailLinks Integer Default: 0 range: 0-5
Specifies the number of links in the biped tail. A value of 0 specifies no tail.
<biped_ctrl>.ponytail1Links Integer Default: 0 range: 0-5
Specifies the number of Ponytail links.
<biped_ctrl>.ponytail2Links Integer Default: 0 range: 0-5
Specifies the number of Ponytail links.
<biped_ctrl>.fingers Integer Default: 1 range: 0-5
Specifies the number of biped fingers.
<biped_ctrl>.fingerLinks Integer Default: 3 range: 1-3
Sets the number of links per finger.
Note: If the number of fingers is 0, fingerLinks is always equal to 1.
<biped_ctrl>.toes Integer Default: 5 range: 1-5
Specifies the number of biped toes.
 Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller 1737

<biped_ctrl>.toeLinks Integer Default: 3 range: 1-3

Specifies the number of links per toe.
<biped_ctrl>.ankleAttach Float Default: 0.2 range: 0-1
Specifies the right and left ankles’ point of attachment along the corresponding foot block.
The ankles may be placed anywhere along the center line of the foot block from the heel
to the toe.
A value of 0 places the ankle attachment point at the heel. A value of 1 places the ankle
attachment point at the toes.
<biped_ctrl>.height Float Default: Defined at creation
Sets the height of the current biped.
<biped_ctrl>.trianglePelvis Boolean Default: True
Select this control to create links from the upper legs to the lowest biped spine object
when Physique is applied. Normally, the legs are linked to the biped pelvis object.
The pelvis area can be a problem when the mesh is deformed with Physique. Triangle
Pelvis creates a more natural spline for mesh deformation.
-- Animation properties
<biped_ctrl>.gravAccel Float Default: 5.63855*Body height
Sets the strength of the gravitational acceleration used to calculate the biped’s motion.
By default, this parameter is set to accurately simulate Newtonian gravity as found on the
Earth’s surface.
<biped_ctrl>.dynamicsType Integer Default: 0 range: 0-1
0 – Biped Dynamics
Keys for the center of mass Balance Factor and Dynamics Blend parameters are set to a
value of 1. Biped calculates airborne trajectories and biped balance.
1 – Spline Dynamics
Create new center of mass keys using full spline interpolation.

Adapt Locks Group

Lock specified tracks to prevent automatic adjustments being made to those tracks when footsteps
are moved in space or edited in time. All the locks except for Time work for footstep editing in space.
Time, locks upper body keys when footsteps are edited in time (Track View). Adapt Locks only
applies to a Footstep animation not a freeform animation.
When you move a footstep in space or adjust footstep timing, Biped automatically adapts existing
keyframes to match the new footsteps. Adapt locks allows you to preserve the exact position of
already created keys for a selected track.
Adapt Locks does not need to be on all the time. For example, if you want to raise all the footsteps
along the world Z-axis, without changing the upper body position, turn on Adapt Locks Body
Vertical Keys, turn on Footstep mode, select all the footsteps and move them up along the world Z-
axis. The footsteps are repositioned, the legs are adapted, but the upper body retains the same
motion rather than being raised with the footsteps. Now turn off Adapt Locks Body Vertical Keys,
the upper body still retains its original motion.
1738 Chapter 21 | character studio 3 MAXScript Extensions

<biped_ctrl>.adaptLockFreeform Boolean Default: False

Turn on to prevent adaptation of a freeform period in a footstep animation. The biped’s
position during a freeform period will not move if footsteps after the freeform period are
moved further away.
<biped_ctrl>.adaptLockHorz Boolean Default: False
Turn on to prevent adaptation of body horizontal keys when footsteps are edited in space.
<biped_ctrl>.adaptLockTurn Boolean Default: False
Turn on to prevent adaptation of body turning keys when footsteps are edited in space.
<biped_ctrl>.adaptLockVert Boolean Default: False
Turn on to prevent adaptation of body vertical keys when footsteps are edited in space.
<biped_ctrl>.adaptLockLLeg Boolean Default: False
Turn on to prevent adaptation of left leg move keys (a leg move key, is a leg key between
footsteps) when footsteps are edited in space.
<biped_ctrl>.adaptLockRLeg Boolean Default: False
Turn on to prevent adaptation of right leg move keys (a leg move key, is a leg key between
footsteps) when footsteps are edited in space.
<biped_ctrl>.adaptLockTime Boolean Default: False
Use Adapt Locks Time to retain upper body motion while editing footstep duration in
Track View. When the duration of a footstep is changed, the biped leg will adapt by
re-timing the touch, plant and lift keys. The biped upper body keys will retain their exact
motion.

Separate Tracks Group

By default character studio stores a finger, hand, forearm, and upper-arm key in the clavicle track.
The toe, foot and calf keys are stored in the thigh track. This optimized approach to key storage
works well in most cases. If you need extra tracks, turn them on for a specific biped body part.
For example, turn on Arms if you plan on extensive finger-hand animation; if an arm key is deleted,
it will not affect the finger-hand keys. Notice that in Track View a transform track is now available
for the first link of the thumb (stores all finger keys), hand, forearm, and upper-arm.
<biped_ctrl>.sepArmsTracks Boolean Default: False
Turn on to create separate transform tracks for the finger, hand, forearm and upper-arm.
There is one finger track per hand. All finger keys are stored in the “Finger0” transform
track, the first link of the biped thumb.
<biped_ctrl>.sepLegsTracks Boolean Default: False
Turn on to create separate toe, foot, and calf transform tracks.
<biped_ctrl>.sepPonytail1Tracks Boolean Default: False
Turn on to create separate ponytail 1 transform tracks.
<biped_ctrl>.sepPonytail2Tracks Boolean Default: False
Turn on to create separate ponytail 2 transform tracks.
 Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller 1739

Note:
If the number of pony tail links is 0, you cannot set Separate Ponytail Tracks to true.
<biped_ctrl>.sepNeckTracks Boolean Default: False
Turn on to create separate transform tracks for the neck links.
<biped_ctrl>.sepTailTracks Boolean Default: True
Turn on to create separate transform tracks for each tail link.
<biped_ctrl>.sepSpineTracks Boolean Default: False
Turn on to create separate spine transform tracks.
-- Modes
<biped_ctrl>.figureMode Boolean Default: False
-- cannot be in Buffer mode to enter figureMode
Use Figure mode to fit a biped to the mesh or mesh objects representing your character.
Leave Figure Mode on when you attach the mesh to the biped with Physique. Figure mode
is also used to scale a biped with a mesh attached, to make biped “fit” adjustments after
Physique is applied, and to correct posture in motion files that need a global posture
change.
<biped_ctrl>.footstepMode Boolean Default: False
Create and edit footsteps; generate a walk, run, or jump footstep pattern; edit selected
footsteps in space; and append footsteps using parameters available in Footstep mode.
<biped_ctrl>.motionMode Boolean Default: False
-- cannot be in Buffer mode to enter motionMode
Create scripts and use editable transitions to combine .bip files together (to create character
animation) in Motion Flow mode. After creating a script and editing transitions, use Save
Segment on the General rollout to store a script as one long .bip file. Save a .mfe file, this
enables you to continue Motion Flow work in progress.
<biped_ctrl>.bufferMode Boolean Default: False
Footsteps are required in the buffer to enter bufferMode.
Edit segments of an animation in Buffer mode. Copy footsteps and associated biped keys
into the buffer using Copy Footsteps on the Footstep Operation rollout first, then turn on
Buffer mode to view and edit the copied segment of your animation.
Note:
Paste buffered motion back to the original animation repeatedly to create looping motions.
Edit footsteps and biped animation that has been copied into the buffer using Copy Footsteps on
the Footsteps Operation rollout. The changes can be pasted back by turning off Buffer Mode, turning
on Paste Footsteps on the Footstep Operation rollout and overlapping the buffered footsteps with
the original footsteps. The buffered motion is spliced into the original animation.
1740 Chapter 21 | character studio 3 MAXScript Extensions

<biped_ctrl>.bendLinksMode Boolean Default: False

Bend all the biped spine objects naturally by rotating a biped spine object. Bend Links also
works for the biped tail and ponytail links.
<biped_ctrl>.rubberBandMode Boolean Default: False
Use this to reposition the biped elbows and knees without moving the biped hands or feet
in Figure mode. Reposition the biped center of mass to simulate the physics of wind or
weight pushing against the biped. Figure mode must be turned on to enable Rubber
Band Mode.
Note:
Rubber Band mode behaves differently than Non-Uniform Scale. If you “Rubber Band” the biped
thigh, for example, the thigh and biped calf objects scale proportionally to keep the biped foot
stationary. Using Non-Uniform Scale, the calf retains its scale and the foot moves.
<biped_ctrl>.scaleStrideMode Boolean Default: True
Footstep stride length and width are scaled to match the stride length and width of the
biped figure. scaling occurs automatically when you load a .bip, .stp, or .fig file. When you
paste footsteps; or when you scale the biped’s legs or pelvis.
<biped_ctrl>.inPlaceMode Boolean Default: False
-- cannot be in Figure mode to enter inPlaceMode
Keep the biped visible in the viewports while the animation plays. Use this for biped key
editing or adjusting envelopes with Physique. Prevents XY movement of the biped center
of mass during animation playback; motion along the Z-axis is preserved. In Place mode is
stored with the 3ds max file.
<biped_ctrl>.inPlaceXMode Boolean Default: False
-- cannot be in Figure mode to enter inPlaceXMode
Lock center of mass X-axis motion. Use this for game export where the character stays in
place but the swinging motion of the hips and upper body along the Y-axis is preserved.
<biped_ctrl>.inPlaceYMode Boolean Default: False
-- cannot be in Figure mode to enter inPlaceYMode
Lock center of mass Y-axis motion. Use this for game export where the character stays in
place but the swinging motion of the hips and upper body along the X-axis is preserved.
Biped limbs, footsteps, and center of mass keys can be adjusted using In Place mode (when
the center of mass is moved on the XY-axes in this mode, the footsteps move). View biped
playback without requiring a follow camera. In this viewing mode, visible footsteps “slide”
under the biped.
For export to games, this feature is valuable since many game engines intelligently move
the character’s center of mass laterally according to game play. In Place mode makes it easy
to view, tune, and export animation in a manner that is complimentary to game engine
playback.
 Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller 1741

Note:
Trajectories do not display when In Place mode is active.
-- Track Selection
<biped_ctrl>.trackSelection Integer Default: 0
0 - No track selection
While a trackSelection value of 0 is a valid return value, setting trackSelection to 0 is
meaningless and will not change the current track selection.
1 - Body Horizontal
Turn on to prevent adaptation of body horizontal keys when footsteps are edited in space.
2 - Body Vertical
Turn on to prevent adaptation of body vertical keys when footsteps are edited in space.
3 - Body Rotation
Turn on to prevent adaptation of body turning keys when footsteps are edited in space.
-- Display properties
<biped_ctrl>.displayBones Boolean Default: False
Displays biped bones. Bones are represented as yellow lines, which do not render. Selecting
Bones is useful for seeing exactly where the joints fall in relation to the biped objects.
<biped_ctrl>.displayObjects Boolean Default: True
Displays biped body objects (objects).
<biped_ctrl>.displayFootsteps Boolean Default: True
Displays biped footsteps in the viewport. Footsteps are represented as green and blue foot-
shaped outlines by default; these are also visible in preview renderings. Turning off the
Footsteps button also turns off the footstep numbers and the center of mass shadow.
<biped_ctrl>.displayFSNumbers Boolean Default: True
Displays biped footstep numbers. Footstep numbers specify the order in which the biped
will move along the path created by the footsteps. Footstep numbers are displayed in
white and do not render, but do appear in preview renderings.
<biped_ctrl>.displayTrajectories Boolean Default: False
Displays trajectories for selected biped limbs.
-- Layers
<biped_ctrl>.visibleBefore Integer Default: 1
Set the number of preceding layers too display as stick figures.
<biped_ctrl>.visibleAfter Integer Default: 0
Set the number of succeeding layers too display as stick figures.
<biped_ctrl>.keyHighlight Boolean Default: False
Display keys by highlighting the stick figures.
1742 Chapter 21 | character studio 3 MAXScript Extensions

-- Footstep related properties

<biped_ctrl>.fsAppendState Boolean Default: False
Each new footstep is appended to the end of the biped’s footstep sequence.
<biped_ctrl>.fsCreateState Boolean Default: False
Set to true to create new states. The first state you add is, by default, the first state in the
controller that executes when the simulation is run.
<biped_ctrl>.fsGroundDuration Time Default: 18f

<biped_ctrl>.fsAirDuration Time Default: 3f

Specifies the number of frames when the body will be in the air during a run or a jump.
Note:
If fsGaitMode is #walk, the above 2 parameters are the Walk Footstep and Double Support durations,
respectively. If fsGaitMode is #run, the above 2 parameters are the Run Footstep and Airborne
durations, respectively. If fsGaitMode is #jump, the above 2 parameters are the 2-Feet down and
Airborne durations, respectively.
<biped_ctrl>.fsGaitMode Name Default: #walk

fsGaitMode can be set to any of the three gaits: #walk, #run, #jump

-- Motion Flow properties

<biped_ctrl>.motionFlow MoFlow
Returns an instance of MoFlow. See Biped Motion Flow (p. 1752) section for more details.
-- Motion Capture properties
<biped_ctrl>.displayBuffer Boolean Default: False
A red stick figure appears, representing the raw motion capture data.
<biped_ctrl>.displayBufferTraj Boolean Default: False
Display a trajectory based on the buffered raw motion capture data for any biped body
part. Use this in combination with Show/Hide Trajectories on the Display rollout to see
how closely the raw and filtered data match.
<biped_ctrl>.talentFigMode Boolean Default: False
Turn on Talent Figure mode to scale the biped relative to the markers. Calibration for the
entire marker file takes place when you exit Talent Figure mode.
Keyframe adaptation takes place in order to accommodate the new biped scale; because of
this, you should adjust the biped scale before adjusting the biped position relative to the
markers.
Use Rubber Band Mode on the General rollout and Non-Uniform Scale to size the biped in
Talent Figure mode.
Ideally, you will not need to use this feature. When loading a motion capture file, Biped
attempts to extract the appropriate figure scale from the given data. Use Talent Figure
mode only if the extracted scale of the biped doesn’t match the scale of the original talent.
Minor differences in scale will alter the motion.
 Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller 1743

Note:
Calibration controls are only enabled when a marker or .bvh file is imported in its raw form. Do not
use key reduction or extract footsteps when you import a marker file for the first time.
-- Object Space Object
<biped_ctrl>.osObject Node Default: Undefined
The Object Space Object for the currently selected body part. The osObject can be specified
for the Clavicle or any of its decendents, and the Thigh or any of its decendents. The
osObject is undefined for all other body parts. The osObject is normally specified in the IK
Key Info rollout.
-- SubAnim Properties (as seen in Track View)
<biped_ctrl>.vertical Matrix3 -- Animatable
The vertical track of controller
<biped_ctrl>.horizontal Matrix3 -- Animatable
The horizontal track of controller
<biped_ctrl>.turning Matrix3 -- Animatable
The turning track of controller
<biped_ctrl>.Ease_Curve Point3 -- Animatable
Animated over range 0 to 1

Script Example:
bipObj = biped.createNew 100 100 [0,0,0]
select bipObj
bip = bipObj.transform.controller
-- Display properties
bip.displayBones = true
bip.displayObjects = false
bip.displayFootsteps = false
bip.displayFSNumbers = false
-- Animations properties
bip.gravAccel = 700
bip.dynamicsType = 1

See Also
Biped Creation (p. 1727)
1744 Chapter 21 | character studio 3 MAXScript Extensions

FootSteps : Matrix3 Controller

Constructor:
<footsteps_ctrl> = $’Bip01 Footsteps’.transform.controller

or:
<footsteps_ctrl>=$’Bip01 Footsteps’.controller

Notes:
This controller is attached to the transform track of the named Biped footstep object.
Properties:
<footsteps_ctrl>.freeFormMode Boolean Default: False
false - Edit Footsteps
true - Edit Free Form (no physics)

<footsteps_ctrl>.dispNumType Integer Default: 0

0 - Start and End Frame
1 - Start Frame
2 - Duration
3 - Double Support

<footsteps_ctrl>.dispAirDur Boolean Default: False

Displays the foot air duration. This is the number of frames each foot is in the air in the
lower part of each footstep’s portion of the track.
<footsteps_ctrl>.dispNoSupport Boolean Default: False
Displays the number of frames when both feet are off the ground, directly above the areas
without footsteps.
<footsteps_ctrl>.rootName String Default: Varies
Contains the root name of the Biped using the Foootsteps Controller. Changing the value
of this property also changes the root name of the Biped.
<footsteps_ctrl>.rootNode Node Default: Varies -- Read-only
The root node (COM) of the Biped system this footstep_ctrl belongs to.
The following example will access the footstep controller, set several values and then display all of
its properties.
Script Example:
fsCont = $’Bip01 Footsteps’.transform.controller
fsCont.freeFormMode = true
fsCont.dispNumType = 3
fsCont.dispAirDur = false
fsCont.dispNoSupport = false
showProperties fsCont
 Biped Slave Controller 1745

See Also
Biped Footprints (p. 1745)
Biped Keys (p. 1759)

Biped Slave Controller

Individual Biped body part objects and the Vertical, Horizontal, and Turning tracks of the
Biped_Vertical_Horizontal_Turn_Body_Matrix3_Controller (p. 1736) use the Biped_Slave
ControllerBiped_Slave_Controller. This type of controller is attached to the transform track.
<bipslave_ctrl>=$’Bip01 Pelvis’.controller

It is not always possible to get the controller via

<biped_object>.transform.controller. The transform track is not exposed for all
nodes but it is possible to get the controller via: <biped_object>.controller.
Properties:
<bipslave_ctrl>.rootName String Default: Varies
The name of the root node (COM) of the Biped system this bipslave_ctrl belongs to.
Note: changing the value of this property also changes the root name of the biped.
<bipslave_ctrl>.rootNode Node Default: Varies -- Read-only
The root node (COM) of the Biped system this bipslave_ctrl belongs to.

See also
Biped MAXScript Extensions (p. 1725)

Biped Footsteps and Footprints

This topic will cover the Biped’s footsteps controller, individual footprints, the multiple footstep
creation dialog, as well as obtaining and setting the parameters for multiple footsteps.
Biped Footsteps (p. 1744)
Biped Footprints (p. 1745)

Biped Footprints
Methods:
biped.addFootprint <biped_ctrl> <matrix3> [append:<boolean>]
Specifies the position and rotation of the footstep. The scale portion of the matrix3 should
always be the identity matrix ([1,1,1]).
Creates a single footprint for the biped, where matrix3 specifies the position and rotation
of the footstep. The scale portion of the matrix3 should always by unity ([1,1,1]).
Notes:
Creates a single footprint for the Biped.
1746 Chapter 21 | character studio 3 MAXScript Extensions

Global Properties:
biped.fsAddSide Integer Default:0
0 - Start Right
1 - Start Left

Notes:
For multiple footstep creation, the starting foot needs to be identified. There is a UI radio button in
the Multiple Footstep Creation dialog “Start Right/Start Left”. The biped global property,
fsAddSide, exposes access to this UI element.
This property also effects the start foot when manually creating footsteps in the viewports and when
using biped.addFootprint. If the biped.fsAddSide is 1, a left footstep is created. If 0, a right
footstep is created. When you create a footstep in the viewports or by using biped.addFootprint,
the value of biped.fsAddSide is flipped, resulting in alternating footsteps being created by default.
Methods:
biped.multipleFSDlg <biped_ctrl>
Displays the Multiple Footstep Creation dialog
biped.getMultipleFSParams <gait_type_name>
Returns an instance of MultFprintParams, gait_type_name can be #walk, #run or #jump.
For information on MultFprintParams and gait_type_name see Biped MultFprintParams
ClassBiped_MultFprintParams_Class.
The following example will obtain the MultipleFSParams for a walk cycle, set several of its values and
then show all of the properties.
Script Example:
walk = biped.getMultipleFSParams #walk
walk.numFootsteps = 5
walk.actualStrideWidth = 2.5
walk.paramStrideWidth = 2.5
walk.actualStrideLength1 = .6
walk.paramStrideLength1 = .6
walk.actualStrideHeight1 = .6
walk.cycle1 = 6
walk.actualStrideLength2 = .7
walk.paramStrideLength2 = .7
walk.actualStrideHeight2 = .7
walk.cycle2 = 7
walk.autoTiming = true
walk.interpTiming = true
walk.alternate = true
walk.multiInsertInTime = true
showProperties walk
 Biped Footprints 1747

Method:
biped.addMultipleFootprints <biped_ctrl> <MultFprintParams>
Create footsteps for a Biped based on the MultFprintParams value
biped.newFootprintKeys <biped_ctrl>
Activates all inactive footsteps. Activation creates default keys for any footsteps that do not
have them. If a footstep does not have keys, it is displayed as bright green (right foot) or
bright blue (left foot). After keys are created for the footsteps, the footsteps change color to
pastel green and pastel blue.
Create Biped keys for inactive footsteps on the Biped
The following example will create a biped, create 10 footsteps and then have Biped create default
keys for the footsteps.
Script Example:
-- create a Biped
bipObj = biped.createNew 100 100 [0,0,0]
-- get the transform controller for the Biped
bip = bipObj.transform.controller
-- get the multiple footstep parameters interface
mfsp=biped.getMultipleFSParams #walk
-- set the number of footsteps to 10
mfsp.numFootsteps=10
-- create the inactive footsteps
biped.addMultipleFootprints bip mfsp
-- create the Biped keys for inactive footsteps
biped.newFootprintKeys bip

See Also
Biped Controllers (p. 1735)
Biped MultFprintParams Class (p. 1748)
Biped MaxScript Extensions (p. 1725)
Biped Keys (p. 1759)
1748 Chapter 21 | character studio 3 MAXScript Extensions

Biped Class : MultFprintParams

This class represents multiple footstep creation parameters of a Biped. An instance of this class is
returned by the biped.getMultipleFSParams <gait_type_name> method, where gait_type_name can
be #walk, #run or #jump.
Properties:
#walk #run #jump
<MultFprintParams>.alternate Boolean Default: true true true
Footsteps will alternate between right and left. Alternate is always selected when the Walk
gait is selected. You can only clear Alternate when Run or Jump gaits are selected.
<MultFprintParams>.numFootsteps Integer Default: 4 4 4
Determines the number of new footsteps to be created.
<MultFprintParams>.paramStrideWidth Float Default: 1.0 1.0 1.0
Sets the stride width as a percentage of the pelvis width. A value of 1.0 produces a stride
width equal to the pelvis width. A value of 3.0 produces a wide, waddling stride. Changes
to this setting automatically change the Actual Stride Width.
Parametric describes the parameter in terms of biped anatomy, and Actual describes the
value in 3ds max units.
<MultFprintParams>.actualStrideWidth Float Default: 0.0 0.0 0.0
Sets the stride width in modeling units. Changes to this setting automatically change the
Parametric Stride Width.
<MultFprintParams>.autoTiming Boolean Default: true true true
Sets timing parameters automatically. Auto Timing affects the following timing parameters
for the Walk gait:
Walk footstep, Double Support:
When Auto Timing is selected, these parameters are automatically adjusted to reasonable
values. Control the footstep sequence by adjusting the Stride Length and Time to Next
Footstep parameters.
When Auto Timing is cleared, you can control the footstep sequence by adjusting the gait
timing parameters, but you can’t change the Time to Next Footstep parameter.
<MultFprintParams>.interpTiming Boolean Default: false false false
Control acceleration or deceleration of the series of footsteps.
<MultFprintParams>.multiInsertInTime Boolean Default: false false false
false - Start after last footstep
Appends the newly created footsteps to the end of the existing footstep sequence.
true - Start at current frame
Inserts the newly created footsteps at the current frame after the existing footstep
sequence allowing you to make a gap in time before the footsteps start again.
<MultFprintParams>.actualStrideLength1 Float Default: 0.0 0.0 0.0
Sets the stride length for new footsteps in 3ds max units.
 Biped Class : MultFprintParams 1749

<MultFprintParams>.paramStrideLength1 Float Default: 0.75 1.5 2.4

Sets the stride length for the new footsteps as a percentage of the length of the biped’s leg.
The default value of 0.75 gives an average stride of normal proportions.
A value of 1.0 will produce a stride length equal to the leg length, which makes the biped
stretch slightly to reach the next step. A value of 0.0 will make the biped walk in place. A
negative stride length will make the biped walk backwards.
When a biped walks backwards, it does not simply reverse the forward movement but
maintains the correct foot-state sequence with the toe touching the ground first, followed
by the heel.
Adjusting Parametric Stride Length automatically changes the value for Actual Stride
Length.
<MultFprintParams>.actualStrideHeight1 Float Default: 0.0 0.0 0.0
Sets the rise or fall between footsteps. You can use this parameter to create a set of
footsteps going up or down a slope or a stairway.
The value for Actual Stride Height is the difference in height in units between each of the
new footsteps. Positive values step up and negative values step down.
<MultFprintParams>.cycle1 Time Default: 15f 15f 15f
<MultFprintParams>.actualStrideLength2 Float Default: 0.0 0.0 0.0
Sets the stride length for new footsteps in 3ds max units. The same rules apply as for
Parametric Stride Length. Adjusting Actual Stride Length automatically changes the value
for Parametric Stride Length.
<MultFprintParams>.paramStrideLength2 Float Default: 0.75 1.5 2.4
Sets the stride length for the new footsteps as a percentage of the length of the biped’s leg.
The default value of 0.75 gives an average stride of normal proportions.
A value of 1.0 will produce a stride length equal to the leg length, which makes the biped
stretch slightly to reach the next step. A value of 0.0 will make the biped walk in place. A
negative stride length will make the biped walk backwards. When a biped walks
backwards, it does not simply reverse the forward movement but maintains the correct
foot-state sequence with the toe touching the ground first, followed by the heel.
Adjusting Parametric Stride Length automatically changes the value for Actual Stride
Length.
<MultFprintParams>.actualStrideHeight2 Float Default: 0.0 0.0 0.0
Sets the rise or fall between footsteps. You can use this parameter to create a set of
footsteps going up or down a slope or a stairway.
The value for Actual Stride Height is the difference in height in units between each of the
new footsteps. Positive values step up and negative values step down.
<MultFprintParams>.cycle2 Time Default: 15f 15f 15f

See the biped.addMultipleFootprints method for creating footsteps based on a

MultFprintParams, and biped.newFootprintKeys creating the biped keys for the inactive
footsteps.
1750 Chapter 21 | character studio 3 MAXScript Extensions

Since MultFprintParams is biped independent, the actual stride lengths and heights are not
accessible in this class. To convert from a paramStrideWidth value to an actualStrideWidth
value, multiply the paramStrideWidth value by the width of the pelvis. Given a biped_ctrl, the
pelvis width can be calculated by:
thePelvis = biped.getNode biped_ctrl #pelvis
pelvisWidth = in coordsys thePelvis (thePelvis.max- thePelvis.min).z

To convert from a paramStrideLength value to an actualStrideLength value, multiply the

paramStrideLength value by the length of the right leg. Given a biped_ctrl, the length of the
right leg can be calculated by:
legLength = distance (biped.getNode biped_ctrl #rleg link:1) (biped.getNode
biped_ctrl #rleg link:2) -- thigh

legLength += distance (biped.getNode biped_ctrl #rleg link:2) (biped.getNode

biped_ctrl #rleg link:3) -- calf

if ((biped_ctrl.rootnode).controller.leglinks) > 3 do

legLength += distance (biped.getNode biped_ctrl #rleg link:3) (biped.getNode

biped_ctrl #rleg link:4) – horsellink, if present

See Also
Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller (p. 1736)
Biped Slave Controller (p. 1745)
FootSteps : Matrix3 Controller (p. 1744)
Biped Footsteps (p. 1745)
Biped MAXScript Extensions (p. 1725)

FootSteps : Matrix3 Controller

Constructor:
<footsteps_ctrl> = $’Bip01 Footsteps’.transform.controller

or:
<footsteps_ctrl>=$’Bip01 Footsteps’.controller

Notes:
This controller is attached to the transform track of the named Biped footstep object.
Properties:
<footsteps_ctrl>.freeFormMode Boolean Default: False
false - Edit Footsteps
true - Edit Free Form (no physics)
 BipedFSKey : MAXObject 1751

<footsteps_ctrl>.dispNumType Integer Default: 0

0 - Start and End Frame
1 - Start Frame
2 - Duration
3 - Double Support

<footsteps_ctrl>.dispAirDur Boolean Default: False

Displays the foot air duration. This is the number of frames each foot is in the air in the
lower part of each footstep’s portion of the track.
<footsteps_ctrl>.dispNoSupport Boolean Default: False
Displays the number of frames when both feet are off the ground, directly above the areas
without footsteps.
<footsteps_ctrl>.rootName String Default: Varies
Contains the root name of the Biped using the Foootsteps Controller. Changing the value
of this property also changes the root name of the Biped.
<footsteps_ctrl>.rootNode Node Default: Varies -- Read-only
The root node (COM) of the Biped system this footstep_ctrl belongs to.
The following example will access the footstep controller, set several values and then display all of
its properties.
Script Example:
fsCont = $’Bip01 Footsteps’.transform.controller
fsCont.freeFormMode = true
fsCont.dispNumType = 3
fsCont.dispAirDur = false
fsCont.dispNoSupport = false
showProperties fsCont

See Also
Biped Footprints (p. 1745)
Biped Keys (p. 1759)

BipedFSKey : MAXObject
This class represents a Biped footstep in the viewports and trackview.
Properties:
<fskey>.time Time Default: Varies
A value indicating when in time the key occurs.
<fskey>.duration Time Default: Varies
The number of frames in each footstep.
1752 Chapter 21 | character studio 3 MAXScript Extensions

<fskey>.selected Boolean Default: False

<fskey>.edgeSel Integer Default: 0
0 - no edges selected
1 - left edge Selected
2 - right edge selected
3 - both edges Selected

<fskey>.active Boolean Default: True

Activate or make inactive the footstep.
<fskey>.transform Matrix3 Default: Varies
<fskey>.side Name Default: #left or #right --
Read-only

See Also
Biped Controllers (p. 1735)
Biped Footsteps (p. 1745)
Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller (p. 1736)
Biped Keys (p. 1759)
Biped MAXScript Extensions (p. 1725)

Biped Motion Flow

MoFlow : MaxWrapper (p. 1752)
MoFlowScript : MaxWrapper (p. 1754)
MoFlowSnippet : MaxWrapper (p. 1755)
MoFlowTranInfo : MaxWrapper (p. 1756)
MoFlowTransition : MaxWrapper (p. 1758)

MoFlow : MaxWrapper
This class can be used to access features in the Biped Motion Flow panel. An instance of this class is
returned by the .motionFlow property of a Biped Body Controller (p. 1736).
Properties:
<moflow>.scripts Array Default: #()
-- Read-only
An array of motion flow scripts (MoFlowScript values).
A Script is a list of clips (.bip files) that are executed sequentially to animate a character.
<moflow>.activeScript MoFlowScript Default:undefined
Get/set which MoFlowScript in scripts array is the active script. If the specified
MoFlowScript is not in the scripts array, no action occurs.
 MoFlow : MaxWrapper 1753

<moflow>.snippets Array Default: #()

-- Read-only
An array of motion flow snippets (MoFlowSnippet values).
<moflow>.selSnippets BitArray Default: #{}
A bitarray specifying the motion flow snippets that are selected in the Motion Flow Graph.
<moflow>.startFrame Integer Default: 0
-- Read-only
The start frame of currently active motion flow script.
<moflow>.endFrame Integer Default: 0
-- Read-only
The last frame of currectly active motion flow script.
Methods:
loadMoFlowFile <moflow> <file_name> [ quiet:<boolean> ]
If quiet:true, which is the default, any warning message dialogs are suppressed.

Load a Motion Flow Editor file (.mfe). Motion Flow Editor files include:
Clips: references to biped animation files.
Transitions: The names, attributes, and connections between clips.
Scripts: different paths through a set of connected clips and transitions.
saveMoFlowFile <moflow> <file_name>
Save a Motion Flow Editor file (.mfe).
Load/Save a motion flow (.MFE) file.
Note:
The location of the referenced .bip files is saved in the .mfe file. If the .bip file cannot be found, the
program looks to the motion flow directory specified in \plugcfg\biped.ini. By default, this setting is
MoFlowDir=<maxdir>\cstudio\scripts
If a referenced .bip file cannot be found in its current location, you will need to move it to the
specified Motion Flow directory. You can change the location of this directory at any time by editing
your biped.ini file with a text editor. The new directory will be used the next time you restart
3ds max. You can also add multiple search paths to your biped.ini file by repeating the MoFloDir=
line multiple times. The program will search the directories in the order they appear and will use the
first instance of the file that it finds.
loadSnippetFiles <moflow>
Loads the snippet files whose file names are assigned. This function should be called
whenever new snippets are added.
Clips represent all or part of a .bip file.
addScript <moflow> <name>
Scripts represent different paths through the clips in the Motion Flow Graph.
Creates a new motion flow script with the given name and adds it to the motion flow.
Returns the new MoFlowScript.
1754 Chapter 21 | character studio 3 MAXScript Extensions

deleteScript <moflow> <MoFlowScript>

deleteScript <moflow> <index_integer>
Deletes the specified script. If the second argument is an integer, the script deleted is the
indexed script in the motion flow’s .scripts array.
getScriptIndex <moflow> <MoFlowScript>
Given the script, returns its index in the script’s combobox.
getSnippetIndex <moflow> <MoFlowSnippet>
Given the snippet, returns its index in the in the motion flow’s .snippets array.
computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]
Computes the global flow network. This function has to be called to update any changes
made to the motion flow network. redraw:true will redraw the viewports.
incGlobals:true will also include the global motion flow network.
Related Methods:
newSnippet <filename> <point2_pos> <redraw:true> <load:true>
Adds a new MoFlowSnippet to the motion flow network, from the given .bip file.
<point2_pos> is the position in windows coordinates where the origin is the top left of
the snippet in the motion flow graph. Redraw:true will redraw the graph window.
Load:true will immediately load the snippet

See also
Biped Controllers (p. 1735)
MoFlowScript : MaxWrapper (p. 1754)
MoFlowSnippet : MaxWrapper (p. 1755)
Biped MAXScript Extensions (p. 1725)

MoFlowScript : MaxWrapper
Constructor:
addScript <moflow> <script_name>
Create a new motion flow script with the given name to the motion flow. Returns the new
MoFlowScript.
Properties:
<MoFlowScript>.startFrame Integer Default: 0f
<MoFlowScript>.snippets Array Default: #() -- Read-only
Array of MoFlowSnippet values defined in the motion flow script
<MoFlowScript>.name String Default: Varies
<MoFlowScript>.startPos Point3 Default: [0,0,0]
<MoFlowScript>.startRot Float Default: 0
 MoFlowScript : MaxWrapper 1755

Methods:
addSnippet < MoFlowScript > < MoFlowSnippet >
Adds the specified MoFlowSnippet to a motion flow script. Returns the MoFlowSnippet
value.
insertSnippet < MoFlowScript > < MoFlowSnippet > <index_integer>
Inserts the snippet at the location specified and returns the new script item. Returns the
MoFlowSnippet value.
deleteSnippet < MoFlowScript > <index_integer>
Deletes the indexed MoFlowSnippet from the motion flow script.
Related Methods:
deleteScript <moflow> <index_integer>
Deletes the indexed MoFlowScript from the motion flow.
computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]
Computes the global flow network. This function has to be called to update any changes
made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true
will also include the global motion flow network
NotesC:
Changes to the MoFlowScript property values do not cause an immediate update of the biped.
ComputeAnimation must be called on the MoFlow value to recompute the biped motion.
Constructor:
newSnippet <moflow> <filename> <point2_pos> <redraw:true> <load:true>
Adds a new MoFlowSnippet to the motion flow network, from the given .bip file.
<point2_pos> is the position in windows coordinates where the origin is the top left of the
snippet in the motion flow graph. Redraw :true will redraw the graph window. Load:true
will immediately load the snippet. Returns the new MoFlowSnippet.
Properties:
<MoFlowSnippet>.start Integer Default: 0
The start frame in the snippet file.
<MoFlowSnippet>.end Integer Default: Varies
The end frame in the snippet file.
<MoFlowSnippet>.clipName String Default: Varies
<MoFlowSnippet>.fileName String Default: Varies
<MoFlowSnippet>.pos Point2 Default: Varies
The coordinates of the snippet in the Motion Flow Graph.
<MoFlowSnippet>.active Boolean Default: True
<MoFlowSnippet>.transitions Array Default: #(MoFlowTransition :
[X,X]) – read only
An array of the transitions defined for the snippet (MoFlowTransition values). The
MoFlowTransition values printed show the the from and to MoFlowSnippet names.
<MoFlowSnippet>.randomStartProbability Integer Default: 100
1756 Chapter 21 | character studio 3 MAXScript Extensions

Methods:
addTransition <from_MoFlowSnippet > <to_MoFlowSnippet > <bool_optimize>
Adds a new MoFlowTransition to a motion flow Snippet. The optimize parameter acts as
the “Optimize Selected Transition” in the Motion Flow Editor.
deleteTransition < MoFlowSnippet > <index_integer>
Deletes the indexed MoFlowTransition emanating from the MoFlowSnippet.
deleteTransitionTo <from_MoFlowSnippet > <to_MoFlowSnippet >
Deletes the transition that’s emanating to the specified snippet.
Related Methods:
addSnippet < MoFlowScript > < MoFlowSnippet >
Adds the specified MoFlowSnippet to a motion flow script. Returns the MoFlowSnippet
value.
insertSnippet < MoFlowScript > < MoFlowSnippet > <index_integer>
Inserts a snippet at the location specified and returns the new script item. Returns the
MoFlowSnippet value.
deleteSnippet < MoFlowScript > <index_integer>
Deletes the indexed MoFlowSnippet from the motion flow script.
loadSnippetFiles <moflow>
Loads all of the snippet files whose file names are assigned. This function should be called
whenever new snippets are added.
getSnippetIndex <moflow> <MoFlowSnippet>
Given the snippet, returns its index in the motion flow’s .snippets array.
computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]
Computes the global flow network. This function has to be called to update any changes
made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true
will also include the global motion flow network
Notes:
Changes to the MoFlowSnippet property values do not cause an immediate update of the biped.
ComputeAnimation must be called on the MoFlow value to recompute the biped motion.

MoFlowTranInfo : MaxWrapper
Constructor:
addTranInfo < MoFlowTransition >
Adds a new MoFlowTranInfo to the MoFlowTransition and returns the newly created
MoFlowTranInfo.
Properties:
<MoFlowTranInfo>.length Integer Default: 25
The transition length in frames.
<MoFlowTranInfo>.angle Float Default: 0.0
The direction of the destination clip
 MoFlowTranInfo : MaxWrapper 1757

<MoFlowTranInfo>.easeFrom Float Default: 0.5

<MoFlowTranInfo>.easeTo Float Default: 0.5
<MoFlowTranInfo>.sourceStart Integer Default: Varies
The start frame for the source clip
<MoFlowTranInfo>.destStart Integer Default: Varies
The start frame for the destination clip
<MoFlowTranInfo>.sourceState Boolean Default: True
false - Fixed
true - Rolling
<MoFlowTranInfo>.destState Boolean Default: True
false – Fixed
true – Rolling
<MoFlowTranInfo>.length Integer Default: 25
The transition length in frames.
<MoFlowTranInfo>.note String Default: ““
<MoFlowTranInfo>.probability Integer Default: 100

Related Methods:
deleteTranInfo < MoFlowTransition > <index_integer>
Deletes the indexed MoFlowTranInfo from the MoFlowTransition. . If the MoFlowTranInfo
is the only MoFlowTranInfo in MoFlowTransition, it is not deleted.
computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]
Computes the global flow network. This function has to be called to update any changes
made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true
will also include the global motion flow network
Notes:
Changes to the MoFlowTranInfo property values do not cause an immediate update of the biped.
ComputeAnimation must be called on the MoFlow value to recompute the biped motion.
The following example will find the transition information from the first clip (snippet) to the next
in the first script defined for the Biped motion flow.
Script Example:
CSPATH = “f:\\3dsmax31_86\\cstudio\\“
bipObj = biped.createNew 100 100 [0,0,0]
select bipObj
max motion mode
bip = bipObj.transform.controller
-- get the MoFlow value from the biped controller:
mf=bip.motionFlow
-- go into motion flow mode and load a motion flow file
bip.motionmode=true
loadMoFlowFile mf (CSPATH + “scripts\\4floloop.mfe”)
--
-- get the script of interest from the MoFlow:
mfs=mf.scripts[1]
1758 Chapter 21 | character studio 3 MAXScript Extensions

-- the script items from the script are in mfs.scriptItems.

-- get the snippet (snippet_from) from the first script item:
snippet_from=mfs.snippets[1].snippet
-- get the snippet (snippet_to) from the second script item:
snippet_to=mfs.snippets[2].snippet
-- search the transitions in snippet_from to find
-- the one whose toSnippet property == snippet_to:
theTrans=undefined
for trans in snippet_from.transitions where (trans.toSnippet == snippet_to) do
( theTrans=trans
break
)
--get the transition information for the from script item:
theTransInfo=theTrans.tranInfos

See also
Biped MAXScript Extensions (p. 1725)

MoFlowTransition : MaxWrapper
Constructor:
addTransition <from_MoFlowSnippet > <to_MoFlowSnippet > <bool_optimize>
Adds a new MoFlowTransition from the from_MoFlowSnippet to the
to_MoFlowSnippet if one doesn’t already exist. The optimize parameter acts as the
“Optimize Selected Transition” in the Motion Flow Editor.
Properties:
<MoFlowTransition>.fromSnippet MoFlowSnippet Default: Varies
Specifies the MoFlowSnippet transitioning from.
<MoFlowTransition>.toSnippet MoFlowSnippet Default: Varies
Specifies the MoFlowSnippet transitioning to.
<MoFlowTransition>.active Boolean Default: True -- Read-only
Specifies whether the MoFlowTransition is active.
<MoFlowTransition>.selected Boolean Default: False
Specifies whether the MoFlowTransition line is selected in the Motion Flow Graph.
<MoFlowTransition>.tranInfos Array Default: #(MoFlowTranInfo :[X,X])
-- Read-only
Array of motion flow transition info blocks (MoFlowTranInfo values). The element of this
array used is determined by the <mfscriptItem>.tranIndex property.
Methods:
addTranInfo < MoFlowTransition >
Adds a new MoFlowTranInfo to the MoFlowTransition and returns the newly created
MoFlowTranInfo.
 MoFlowTransition : MaxWrapper 1759

deleteTranInfo < MoFlowTransition > <index_integer>

Deletes the indexed MoFlowTranInfo from MoFlowTransition. If the MoFlowTranInfo is
the only MoFlowTranInfo in MoFlowTransition, it is not deleted.
Related Methods:
deleteTransition < MoFlowSnippet > <index_integer>
Deletes the indexed MoFlowTransition emanating from the MoFlowSnippet.
deleteTransitionTo <from_MoFlowSnippet > <to_MoFlowSnippet >
Deletes the transition that’s emanating to the specified snippet.
computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]
Computes the global flow network. This function has to be called to update any changes
made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true
will also include the global motion flow network
Notes:
Changes to the MoFlowTransition property values do not cause an immediate update of the biped.
ComputeAnimation must be called on the MoFlow value to recompute the biped motion.

See also
Biped MAXScript Extensions (p. 1725)

Biped Keys
All common MAXScript key functions like deleteKey, selectKeys, moveKeys etc. can be used with
Biped keys. The exceptions addNewKey and deleteKeys are substituted with the following methods.
Method:
biped.addNewKey <biped_controller> <time> [ #select ]
<time> Adds a new key to the controller track at the time specified.
[ #select ] The new key is also selected if the #select optional argument is
specified.

The value for the new key is the interpolated controller value at the specified time. The
value for the new key is the interpolated controller value at that time. The new key is also
selected if the #select optional argument is specified.
addNewKey() will not add a key if a key already exists at the specified time. The return
value is the key located at the specified time.
Method:
biped.deleteKeys <biped_controller> [ #allKeys ] [ #selection ]
[ #allKeys ]
[ #selection ]
Deletes either all keys or all selected keys from the controller. If neither #allKeys or
#selection is specified, all keys are deleted.
1760 Chapter 21 | character studio 3 MAXScript Extensions

Accessing a Biped controller key by index

Accessing a Biped controller key by indexing into the .keys property of the controller returns a type
of key that MAXScript does not recognize. To get a Biped controller key by index use the following
method:
Method:
biped.getKey ( <biped_controller> | <footstep_ctrl> ) <index>
<biped_controller>
<footstep_ctrl>
<index>

Notes:
Returns an instance of BipedKey for Biped body controllers and BipedFSKey for footstep controllers.
BipedKey and BipedFSKey are defined below.
Not all of the Biped elements contain a transform controller. Rather, a controller on an object
typically higher in the hierarchy may store the transform key for an element. For example, the
transforms for all the fingers on a hand are stored in either the Finger0 or Clavicle transform
controller. This depends on whether “Separate Tracks for Arms” is set to true or false, respectively.
The following example will get the first key for each of the subcontrollers of the $Bip01
Vertical_Horizontail_Turn transform controller and show their properties. Additionally, the first key
of the $Bip01 Footstep transform controller will have its properties shown.
Script Example:
bip = $Bip01.transform.controller
-- Obtain the subcontrollers
vertCont = bip.vertical.controller
horzCont = bip.horizontal.controller
turnCont = bip.turning.controller
-- Get the first key for each subcontroller
vk = biped.getKey vertCont 1
hk = biped.getKey horzCont 1
tk = biped.getKey turnCont 1
-- Show the properties for the individual subcontroller key types
showProperties vk
showProperties hk
showProperties tk
-- Obtain the Biped’s Footstep controller
fsCont = $’Bip01 Footsteps’.transform.controller
-- Show the Footstep controller properties
showProperties fsCont
-- Get the first Footstep controller key
fk = biped.getkey fsCont 1
showProperties fk

See also
BipedKey : MAXObject (p. 1761)
 BipedKey : MAXObject 1761

BipedKey : MAXObject
All Biped vertical, horizontal, turning, and body keys are represented by this class.
Properties:
<bipedkey>.time Time Default: Varies
Enter a value to specify when in time the key occurs.
<bipedkey>.selected Boolean Default: False
<bipedkey>.tension Float Default: 25.0
Controls the amount of curvature in the animation curve.
High Tension produces a linear curve. It also has a slight Ease To and Ease From effect.
Low Tension produces a very wide, rounded, curve. It also has a slight negative Ease To and
Ease From effect.
<bipedkey>.continuity Float Default: 25.0
Controls the tangential property of the curve at the key. The default setting is the only
value that produces a smooth animation curve through the key. All other values produce a
discontinuity in the animation curve causing an abrupt change in the animation.
<bipedkey>.bias Float Default: 25.0
Controls where the animation curve occurs with respect to the key.
<bipedkey>.easeTo Float Default: 0.0
Slows the velocity of the animation curve as it approaches the key.
High Ease To causes the animation to decelerate as it approaches the key.
The default setting causes no extra deceleration.
<bipedkey>.easeFrom Float Default: 0.0
Slows the velocity of the animation curve as it leaves the key.
High Ease From causes the animation to start slow and accelerate as it leaves the key.
The default setting causes no change of the animation curve.
<bipedkey>.type Name Default: Varies
-- Read-only
Contains #vertical, #horizontal, #turning, or #body based on the key type
There are additional properties based on the type of the key:
-- #vertical
<vertkey>.z Float Default: Varies
Reposition the selected biped part in z.
<vertkey>.dynamicsBlend Float Default: 1.0
Control the amount of gravity in an airborne period, as in a running or jumping motion.
This parameter has no effect on a walking motion where footsteps overlap.
<vertkey>.ballisticTension Float Default: 0.5
Control the amount of spring or tension when the biped lands or takes off from a jump or
run step. The change is subtle.
A walk cycle will not activate this value. The biped has to be airborne, then the Lift and
Touch vertical keys will display a Ballistic Tension value.
1762 Chapter 21 | character studio 3 MAXScript Extensions

-- #horizontal
<horzkey>.x Float Default: Varies
Reposition the selected biped part in x.
<horzkey>.y Float Default: Varies
Reposition the selected biped part in y.
<horzkey>.balanceFactor Float Default: 1.0
Position the biped’s weight anywhere along a line that extends from the center of mass to
the biped’s head. A value of 0 places the biped’s weight at the center of mass. A value of 1
places the biped’s weight above the center of mass. A value of 2 places the biped’s weight
in the head.
-- #body
<bodykey>.ikBlend Float Default: 0.0
Determines how forward kinematics and inverse kinematics are blended to interpolate an
intermediate position.
<bodykey>.ikSpace Integer Default: 0
0 - Body
The biped limb is in biped coordinate space.
1 - Object
The biped limb is either in World coordinate space or the coordinate space of the selected
object. Coordinate space can be blended between keys.
<bodykey>.ikAnkleTension Float Default: 0.0
Adjusts the precedence of the ankle joint over the knee joint. When set to 0, the knee takes
precedence. When set to 1, the ankle takes precedence.
<bodykey>.ikJoinedPivot Boolean Default: True
Put the biped foot in the coordinate space of the previous key.
<bodykey>.ikPivotIndex Integer Default: 1
Index into <bodykey>.ikPivots array of active (selected) pivot
<bodykey>.ikNumPivots Integer Default: Varies – Read only
Number of pivot points in <bodykey>.ikPivots array
<bodykey>.ikPivots Array Deafult: Varies - Array of Point3 values
Array of positions of all the pivot points for the body part
Here is an example:
Script Example:
k = biped.getKey $’bip01 L clavicle’.transform.controller 2
showProperties k
k.ikBlend = .5
k.ikSpace = 0
k.ikAnkleTension = .8
k.ikJoinedPivot = false
k.ikPivotIndex = 8
k.ikNumPivots = 2
k.ikPivots
-- to add a new one
k = biped.addNewKey $’bip01 L clavicle’.transform.controller 10f
 BipedFSKey : MAXObject 1763

BipedFSKey : MAXObject
This class represents a Biped footstep in the viewports and trackview.
Properties:
<fskey>.time Time Default: Varies
A value indicating when in time the key occurs.
<fskey>.duration Time Default: Varies
The number of frames in each footstep.
<fskey>.selected Boolean Default: False
<fskey>.edgeSel Integer Default: 0
0 - no edges selected
1 - left edge Selected
2 - right edge selected
3 - both edges Selected

<fskey>.active Boolean Default: True

Activate or make inactive the footstep.
<fskey>.transform Matrix3 Default: Varies
<fskey>.side Name Default: #left or #right --
Read-only

See Also
Biped Controllers (p. 1735)
Biped Footsteps (p. 1745)
Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller (p. 1736)
Biped Keys (p. 1759)
Biped MAXScript Extensions (p. 1725)

Biped Motion Capture

All motion capture properties in Biped are global parameters and cannot be varied from Biped to
Biped. Hence they are exposed as system globals residing in the mocap struct.
Properties:
mocap.fsExtractionMode Integer Default: 0
0 - None: Freeform
No footsteps are extracted.
1 - On
Extract footsteps.
2 - Fit to existing
For motion data that has both footstep motion and flying, swimming, falling, or
tumbling motions.
1764 Chapter 21 | character studio 3 MAXScript Extensions

mocap.fsConversionMode Integer Default: 0

0 - No Key Reduction
Do not reduce keys. Use this on files that are already key reduced or if you want to work
with all the data in a raw motion capture file.
1 - Use Key Reduction
Reduce keys for simpler key editing.
2 - Load Buffer Only
Do not apply the data to the biped, load the data to the motion capture buffer only. Use
this to either compare your edited version with the original or to paste postures from the
motion capture buffer to the biped in the scene.
mocap.upVector Integer Default: 2
Set the vertical axis used in the motion capture data.
0 - X
1 - Y
2 - Z

mocap.scaleFactor Float Default: 1.0

Multiply the stored talent size by this value and size the biped accordingly.
-- range: 1+

-- Footstep Extraction
mocap.fsExtractionTol Float Default: 0.05
Set the sensitivity of footstep extraction. Biped determines if the footstep is there by
checking that the foot does not move beyond the distance determined by the Extraction
Tolerance value. Smaller numbers are more sensitive and extract more footsteps. Value is a
percentage of foot length.
-- range: 0+

mocap.fsSlidingDist Float Default: 0.0

Create a sliding footstep when positional tolerance is reached. This value is a percentage of
foot length. By default the foot must slide its own distance (100), before a sliding footstep
is created.
-- range: 0+

mocap.fsSlidingAngle Float Default: 0.0

Create a sliding footstep when rotational tolerance is reached. This value is in degrees. If
this is set high (360 degrees), the foot must make a complete turn before a sliding footstep
is created.
-- range: 0-360
 BipedFSKey : MAXObject 1765

mocap.fsUseVerticalTol Boolean Default: False

Turn on Z-axis Tolerance. The control filters out footsteps that do not fall within a given
range of the ground plane. Use this when filtering motions, such as hopping or pitching a
baseball, in which a foot may come off the ground and remain stationary, but its position
is not intended as a footstep.
mocap.fsVerticalTol Float Default: 0.5
Value is a percentage of leg length
-- range: 0+

mocap.fsZLevel Float Default: 0.0

Set a Z value (ground).
mocap.fsUseFlatten Boolean Default: False
Extracted footsteps are moved to Z=0. Use this to flatten out minor differences in the
height of the extracted footsteps.
-- Load Frames
mocap.startFrame Integer Default: 0
Start importing at this frame. Default is frame 0, the first frame.
mocap.endFrame Integer Default:0
Stop importing at this frame. Default is the last frame of the clip.
mocap.loop Boolean Default: False
Loop the data by the value set here.
This is relative. Succeeding loops start where the previous loop left off. The clips are not
blended and may require editing unless the original clip was designed to loop.
Use this for clips designed to loop.
Note:
This often works best if Footstep Extraction is tuned off.
mocap.loopFrameCount Integer Default: 0

-- range: 0+

-- Key Reduction Settings

Tolerance: Set the maximum angular or positional deviation for a track.
Values are in degrees for rotation tracks. Values are in units of translation for position tracks.
Minimum Key Spacing: Set the minimum number of frames between keys.
Tolerance is computed first, then Minimum Key Spacing computes further key reduction.
A Minimum Key Spacing value of 10 for the head track ensures that no two keys are closer than
10 frames for this track.
1766 Chapter 21 | character studio 3 MAXScript Extensions

Set All: Force all tracks to the values set in these fields.
Higher values here can determine how much key reduction is possible while preserving the
original motion.
Filter: Clear to prevent filtering of the motion capture data into a track. If this is cleared, there
will be no key reduction for the track.
mocap.allTol Float Default: 0.0

-- range: 0+

mocap.allSpacing Integer Default: 3

-- range: 0+

mocap.allFilter Boolean Default: False

mocap.horzTol Float Default: 1.0

-- range: 0+

mocap.horzSpacing Integer Default: 3

-- range: 0+

mocap.horzFilter Boolean Default: True

mocap.rotTol Float Default: 1.0

-- range: 0+

mocap.rotSpacing Integer Default: 3

-- range: 0+

mocap.rotFilter Boolean Default: True

mocap.vertTol Float Default: 1.0

-- range: 0+

mocap.vertSpacing Integer Default: 4

-- range: 0+

mocap.vertFilter Boolean Default: True

mocap.pelvisTol Float Default: 6.0

-- range: 0+
 BipedFSKey : MAXObject 1767

mocap.pelvisSpacing Integer Default: 3

-- range: 0+

mocap.pelvisFilter Boolean Default: True

mocap.spineTol Float Default: 6.0

-- range: 0+

mocap.spineSpacing Integer Default: 3

-- range: 0+

mocap.spineFilter Boolean Default: True

mocap.neckTol Float Default: 6.0

-- range: 0+

mocap.neckSpacing Integer Default: 3

-- range: 0+

mocap.neckFilter Boolean Default: True

mocap.leftArmTol Float Default: 6.0

-- range: 0+

mocap.leftArmSpacing Integer Default: 3

-- range: 0+

mocap.leftArmFilter Boolean Default: True

mocap.rightArmTol Float Default: 6.0

-- range: 0+

mocap.rightArmSpacing Integer Default: 3

-- range: 0+

mocap.rightArmFilter Boolean Default: True

mocap.leftLegTol Float Default: 6.0

-- range: 0+
1768 Chapter 21 | character studio 3 MAXScript Extensions

mocap.leftLegSpacing Integer Default: 3

-- range: 0+

mocap.leftLegFilter Boolean Default: True

mocap.rightLegTol Float Default: 6.0

-- range: 0+

mocap.rightLegSpacing Integer Default: 3

-- range: 0+

mocap.rightLegFilter Boolean Default: True

mocap.tailTol Float Default: 6.0

-- range: 0+

mocap.tailSpacing Integer Default: 3

-- range: 0+

mocap.tailFilter Boolean Default: True

-- Limb orientation
Angle: Move the knee or Elbow position to create the biped joint key.
Point: Rotate the shoulder-elbow-wrist or hip-knee-ankle to create the biped joint key.
Auto: Auto reads exact hand and foot positions from the motion capture data, character studio
then places the knees and elbows in a natural position. For marker files involving running and
walking, this option can clean up the data nearly instantly, regardless of how many markers
were used (and where they were placed).
mocap.kneeOrient Integer Default: 0

0 - angle
1 - point
2 - auto

The biped knee hinge joints are perpendicular to the triangles formed by the hip-knee-
ankle. Resolve errors in the motion capture data that break this rule by using either the
angle or point method.
 BipedFSKey : MAXObject 1769

mocap.elbowOrient Integer Default: 0

0 - angle
1 - point
2 - auto

The biped elbow hinge joints are perpendicular to the triangles formed by the shoulder-
elbow-wrist. Resolve errors in the motion capture data that break this rule by using either
the angle or point method.
mocap.footOrient Integer Default: 0

0 - angle
1 - auto

The biped foot hinge joints are perpendicular to the triangles formed by the hip-knee-
ankle respectively. Resolve errors in the motion capture data that break this rule by using
either the angle or point method.
mocap.handOrient Integer Default: 0

0 - angle
1 - auto

The biped hand hinge joints are perpendicular to the triangles formed by the shoulder-
elbow-wrist. Resolve errors in the motion capture data that break this rule by using either
the angle or point method.
-- Talent Definition
mocap.talentFigStrucFile String Default: ““ -- figure
structure file (.fig)
A .fig file containing changes made to the biped scale while in Talent Figure mode.
mocap.useTalentFigStrucFile Boolean Default: False
Turn on useTalentFigStrucFile to use the file whose string is defined in
mocap.talentFigStrucFile.
mocap.talentPoseAdjFile String Default: ““ -- pose
adjustment file (.cal)
A .cal file containing changes made to the biped while in Adjust Talent Pose mode.
mocap.useTalentPoseAdjFile Boolean Default: False
Turn on useTalentPoseAdjFile to use the file whose string is defined in mocap.
talentPoseAdjFile.
1770 Chapter 21 | character studio 3 MAXScript Extensions

-- Marker Name Files

mocap.markerNameFile String Default: ““ -- csm
marker name file (.mnm)
A Marker Name file to map incoming marker names in motion capture files (.bvh or .csm)
to the character studio marker naming convention.
mocap.useMarkerNameFile Boolean Default: False
When set to true, use the file defined in mocap.markerNameFile.
mocap.jointNameFile String Default: ““ -- bvh
marker name file (.mnm)
A Marker Name file to map incoming marker names in motion capture files (.bvh or .csm)
to the character studio marker naming convention.
mocap.useJointNameFile Boolean Default: False
When set to true, use the file defined in mocap.jointNameFile.
-- Marker Display Options
Marker and marker names are displayed around the biped. Discrepencies like the biped
elbow position relative to the elbow marker can be spotted and adjusted.
mocap.dispKnownMarkers Boolean Default: False
mocap.dispKnownMarkersType Boolean Default: False
true – on all props
false – on selected props

mocap.dispPropMarkers Boolean Default: False

mocap.dispUnKnownMarkers Boolean Default: False

-- Load Save Methods

mocap.loadParameters <file_name>
mocap.saveParameters <file_name>

Load/Save a motion capture parameter (.MOC) file

 Crowd : helper 1771

Crowds

Crowd : helper
Constructor:
crowd ...

Properties:
<crowd>.simStart Integer Default: 0
The first frame of the simulation.
<crowd>.solveStart Integer Default: 0
The frame at which you begin solving.
<crowd>.solveEnd Integer Default: 100
Specifies the last frame considered for the solution.
<Crowd>.deleteKeys Boolean Default: False
When true, Crowd deletes the keys of active delegates in the range over which the solution
takes place.
<Crowd>.saveNthPos Integer Default: 1
Saves every nth position frame after the solution.
<Crowd>.saveNthRot Integer Default: 1
Saves every nth rotation frame after the solution.
<Crowd>.flashing Boolean Default: True Alias:
Hilite_Delegates_During_Assignments
<crowd>.vectorScale Float Default: 1.0
Globally scales all force and velocity vectors that are displayed during the simulation.
Scaling vectors up helps to see them better when they are very small. It does not effect the
simulation.
<Crowd>.useScript Boolean Default: False
When true, Crowd executes a script at each frame of the solution.
<Crowd>.functionName String Default: “PerFrameFn” Alias:
Script_Context_Name
The name of the function to be executed. This name must also be specified in the script.
<Crowd>.script String Default: Undefined
<crowd>.update Boolean Default: True Alias:
Update_Display_During_Solve
When true, motion produced during solution of a crowd simulation appears in the
viewports.
<Crowd>.updateFrequency Integer Default: 1
How often the display is updated during the solution. If 1, the update occurs every frame.
If 2, the update occurs every other frame, and so on.
1772 Chapter 21 | character studio 3 MAXScript Extensions

<Crowd>.solveForBipeds Boolean Default: False

When on, only biped/delegates are included in the computation. Also, the options to use
priorities and backtracking become available. These options are available only for biped-
only computations.
<Crowd>.usePriorities Boolean Default: False
When on, biped/delegates are computed one delegate at a time, in order of their Priority
values, from lowest to highest. Also, backtracking becomes available and Step Solve
becomes unavailable.
<Crowd>.backtracking Boolean Default: False
Turns on backtracking functionality when solving a crowd simulation that uses bipeds.
When Backtracking is on during the solution, in the case of an impending collision
between bipeds, the Crowd system will back up the simulation to the beginning of the
current clip, and then try a different traversal of the lower-priority delegate/biped’s motion
flow graph. If necessary, the system will back up two or more clips.
<crowd>.showCollisions Boolean Default: False Alias:
ClearColl
When true the delegates that collide are highlighted in the collision color.
<crowd>.whenToShowCollisions Integer Default: 0
0 – only during collisions: Colliding delegates are highlighted only in frames in which
they actually collide.
1 – always: Colliding delegates are highlighted in frames in which they collide and all
subsequent frames.
<crowd>.collisionColor Color Default: (color 255 0 0)
The color swatch indicates the color used to highlight colliding delegates.
<crowd>.IconSize Float Default: 0.0
<crowd>.behaviors ArrayParameter Default: #()
Array of Behavior objects
<crowd>.teams ArrayParameter Default: #()
Array of Team objects
<crowd>.assignments ArrayParameter Default: #()
<crowd>.cogcontrols ArrayParameter Default: #() Alias:
Cognitive_Controllers
CogControl : MAXObject (p. 1791)
<crowd>.scatter MAXObject Default: Scatter_Parameters
CrowdScatter: (p. 1778)
<crowd>.objAssoc MAXRefTarg Default: ObjAssoc Alias:
Object_Delegate_Associations_Parameters
Display the dialog to link any number of delegate-object pairs.
 Delegate : Helper 1773

<crowd>.smooth MAXRefTarg Default: Smooth Alias:

Smoothing_Parameters
Display the Smoothing dialog to smooth existing animation keys on a solved simulation
to create more natural-looking animation
<Crowd>.priority MAXRefTarg Default: Priority -- Read-only;
Alias: Priority_Parameters
See Priority PropertiesCrowd_Priority_Properties.

See Also
Biped and Crowd Interaction (p. 1734)

Delegate : Helper
The Delegate helper object is a special pyramidal object used in crowd animation. By default, the
point of the pyramid indicates the forward direction.
The Crowd object controls the delegate or delegates, whose motion can then be imparted to a biped
or other object.
Constructor:
Delegate ...
CrowdDelegate ...

Properties:
<Delegate>.width Float Default: 0.0 -- world units
The width of the Delegate object.
<Delegate>.depth Float Default: 0.0 -- world units
The depth of the Delegate object.
<Delegate>.height Float Default: 0.0 -- world units
The height of the Delegate object.
<Delegate>.velocityColor Color Default: (color 0 0 0)
When showVelocity is true, uses the specified color to draw a vector in the delegate’s
center during the simulation solution. The vector length indicates the delegate’s relative
speed.
<Delegate>.active Boolean Default: True
The delegate object is subject to control by a Crowd object.
<Delegate>.showForces Boolean Default: True
The forces being applied to a delegate by any applicable behaviors are drawn as vectors
whose length indicate the extent of the forces. For example, if the delegate is affected by a
Space Warp behavior and a Wander behavior, the vectors (using default colors) are yellow
and blue-green, respectively. These vectors are visible only during solution of the crowd
simulation.
1774 Chapter 21 | character studio 3 MAXScript Extensions

<Delegate>.showVelocity Boolean Default: False

Uses the Velocity Color (see above) to draw a vector whose length depicts the delegate’s
relative speed. This vector is visible only during solution of the crowd simulation.
<Delegate>.showCogStates Boolean Default: True
During a solve, a text label appears next to the delegate showing the name of the cognitive
controller state or transition that currently directs its behavior, if any.
<Delegate>.xyConstrain Boolean Default: True
The delegate remains at its initial height (position on the world XY axis) throughout the
simulation. When off, the delegate’s height can change during the simulation, for example
when seeking an object at a different height.
<Delegate>.useHierBbox Boolean Default: True
Alias Use_Hierarchy_in_Bounding_Box_Computation
When true, the Avoid behavior uses the bounding box of the delegate and all of its
children to perform its behavior.
This bounding box is computed by the Crowd object, is used by the collision detector, and
can be accessed by other behaviors.
<Delegate>.averageSpeed Float Default: 5.0 -- animatable;
world units
Specifies the delegate’s baseline velocity in 3ds max units (or the current unit type) per
second. This can be modified during the simulation by a variety of factors, such as a linked
biped’s built-in speed and Deviation settings in a behavior.
<Delegate>.maxAccel Float Default: 0.1 -- animatable;
world units
Multiplied times Average Speed to determine the maximum acceleration.
<Delegate>.turnDecel Float Default: 0.3 -- animatable;
Alias: Turn_Deceleration_Weight
Specifies how much a delegate should slow down when turning. The higher this setting,
the more the delegate slows down when it reaches the turn angle (see following
parameter). A value of 0 specifies no slowdown; a value of 1 tells the delegate to stop.
The algorithm computes a value, d, which goes linearly from 0 to (1 - Decel Weight) as the
turn angle of the delegate goes from 0 to the Turn Angle specified by the user. The speed of
the delegate is then multiplied by d. For example, when the delegate turns at the Turn
Angle or greater, its speed will be multiplied by 1 - Decel Weight, slowing it down as much
as possible based on this parameter. When the delegate is not turning at all, its speed is not
affected by the Decel Weight. When the delegate is turning at half the specified Turn
Angle, d = Decel Weight / 2, so its speed will be multiplied by (1 - Decel Weight / 2).
As a practical example, take a delegate traveling at 10 units/sec, Decel Weight is set to 0.4,
and At Turn Angle is set to 30. When the delegate has turned 15 degrees (half the At Turn
Angle), the effective deceleration weight is 0.2. Subtract that quantity from 1 to get 0.8,
and then multiply that times the delegate’s speed to get 8 units per second halfway into
the turn. At the full turn (30 degrees), the delegate travels at 6 units per second.
 Delegate : Helper 1775

<Delegate>.turnDecelAngle Float Default: 10.0 -- animatable;

Alias: Turn_Deceleration_Angle
Specifies the turn angle at which Decel Weight’s full slowdown effect is applied. If the
current turn angle is less than At Turn Angle, the algorithm divides the latter by the
former, and then divides the Decel Weight setting by the result to derive the effective
decel weight.
<Delegate>.inclineDecel Float Default: 0.1 -- animatable;
Alias: Incline_Deceleration_Weight
Specifies how much the delegate should slow down when moving at an upward slant.
<Delegate>.inclineDecelAngle Float Default: 90.0 -- animatable;
Alias: Incline_Deceleration_Angle
Specifies the upward slant angle at which Decel Weight’s full slowdown effect is applied.
<Delegate>.declineAccel Float Default: 0.1 -- animatable;
Alias: Decline_Acceleration_Weight
Specifies how much the delegate should speed up when moving at a downward slant.
See Decel Weight for a full explanation, taking into account that Accel Weight produces a
speedup effect rather than a slowdown. Thus, the effective acceleration weight is added
to 1, not subtracted from it.
<Delegate>.declineAccelAngle Float Default: 90.0 -- animatable;
Alias: Decline_Acceleration_Angle
Specifies the downward slant angle at which Accel Weight’s full speedup effect is applied.
<Delegate>.maxTurnVel Float Default: 30.0 -- animatable;
Alias: Max_Turn_Velocity
Specifies the maximum number of degrees a delegate can turn.
<Delegate>.maxTurnAccel Float Default: 3.0 -- animatable;
Alias: Max_Turn_Acceleration
Specifies how much the delegate’s turn angle can change per frame. If this is not small, the
delegate’s direction might jerk around. It would be allowed to turn suddenly, rather than
smoothly.
<Delegate>.maxIncline Float Default: 90.0 -- animatable;
Alias: Max_Incline_Velocity
Specifies the maximum number of degrees a delegate can turn upward per frame.
<Delegate>.maxDecline Float Default: 90.0 -- animatable;
Alias: Max_Decline_Velocity
Specifies the maximum number of degrees a delegate can turn downward per frame.
<Delegate>.maxBank Float Default: 30.0 -- animatable
Specifies the maximum number of degrees a delegate can bank.
<Delegate>.maxBankVel Float Default: 3.0 -- animatable;
Alias: Max_Bank_Velocity
Specifies how much the delegate’s bank angle can change per frame.
1776 Chapter 21 | character studio 3 MAXScript Extensions

<Delegate>.bankPerTurn Float Default: 1.0 -- animatable

The number of degrees the delegate will bank as a function of the turn angle at the current
frame. For example, if Bank per Turn=1, the delegate will bank one degree for every degree
it is turning at a given frame.
<Delegate>.useBiped Boolean Default: False
When true, the delegate is associated with a biped.
<Delegate>.biped Node Default: Undefined
The biped with which the delegate is associated.
<Delegate>.startFrame Integer Default: 0
The frame at which the associated biped’s first clip will begin to play.
<Delegate>.priority Integer Default: 0
Sets the delegate priority, which determines the order of solution in biped/delegate
simulations.
<Delegate>.s Integer Default: 0
0 – First clip of current script
1 – Random start clip
<Delegate>.duration Integer Default: 0
The number of frames the delegate has been in the current state.
<Delegate>.behaviors ArrayParameter Default: #()
The behaviors property contains valid values only during a solve. Contains the behaviors
being used during the solve.
<Delegate>.weights ArrayParameter Default: #()
The weights property contains valid values only during a solve. Each element contains the
weight of the corresponding behavior in the behaviors property value.
<Delegate>.simpos Point3 Default: [0,0,0]
The simpos property contains a valid value only during a solve. Contains the current
position of the delegate during the simulation.
<Delegate>.randID Integer Default: 0
A possibly non-unique identifier whose purpose is to be used by behaviors as part of it’s
seed calculation. If more than one delegate has the the same randId then they should
have the same random behavior. By defualt, crowd creates unique randIds.
<Delegate>.index Integer Default: -1 -- Read-only
Index used by various behaviors as indices into internal arrays. Before a solve, Crowd
makes sure that the delegates who are participating in the solve are given a contiguous set
of indices, so that behaviors can set up arrays which use these indices.
 Delegate : Helper 1777

Related Delegates Methods:

delegates.isComputing <delegate_node>
Returns a ‘1’ if the delegate is currently active in a crowd solve simulation, it returns a ‘0’
otherwise.
delegates.velocity <delegate_node>
Returns the normalized velocity of the delegate at the current simulation frame as a
Point3 value.
delegates.prevVelocity <delegate_node>
Returns the normalized velocity of the delegate at the previous simulation frame as a
Point3 value.
delegates.startVelocity <delegate_node> <time>
Returns the normalized velocity of the delegate at the start of the crowd simulation as a
Point3 value. Thus the <time> parameter is a time value that should be equal to
crowd.simStart.
delegates.speed <delegate_node>
Returns the speed of the delegate at the current simulation frame as a float.
delegates.isAssignmentActive <delegate_node> <assignmentIndex> <time>
Returns a ‘1’ if the delegate is active for a particular crowd assignment at the time
specified, if not it returns a ‘0’. The <assignmentIndex> directly corresponds to the index
of the assignment in the crowds.assignment array.
Note:
The functions lineDisplay ,sphereDisplay ,bboxDisplay , and textDisplay are all functions which can
be used to draw a graphic primitive for a particular delegate when the crowd simulation is being
solved. All of the positional values are in world space. Usually these functions will be used within a
scripted behavior to visually demonstrate the behavior. For example, lineDisplay could be used to
draw a line that represents the force that the behavior is exerting on that delegate.
delegates.lineDisplay <delegate_node> <startPosition> <endPosition> <color>
<vectorScale>
This function will draw a line from the start position to the endPosition with the color
specified.
<startPosition> is a point3 value.
<endPositions> is a point3 value.
<color> is a color value.
<vectorScale> boolean value. Whether or not to scale the line display by the
Crowd.vectorScale value.
delegates.sphereDisplay <delegate_node> <position> <radius> <color>
This function will draw a sphere at the position <position>, with a radius of size <radius>,
and a color of <color>. <position> is a point3 value, radius is a float and <color> is a color
value.
1778 Chapter 21 | character studio 3 MAXScript Extensions

delegates.bboxDisplay <delegate_node> <minPosition> <maxPosition> <color>

This function will draw a bounding box specifed by the two extrema points,
<minPosition> and <maxPosition>, with the color specified. <minPosition> and
<maxPosition> are point3 values and <color> is a color value.
delegates.textDisplay <delegate_node> <position> <color> <string>
This function will draw the text found in the <string> parameter at the position specified
at <position>, with the color found in <color>. <position> is a point3 value, <color> is a
color value, and <string> is a string value.
delegates.simTransform <delegate> <time>
Returns the delegate’s transformation matrix at the specified time as a Matrix3 value. This
method returns valid values during a solve.
Note:
During a Solve, the simulation doesn’t set the delegate nodes’ position and rotation keys until the
simulation stops. As such, accessing the delegate nodes’ position and rotation during the solve will
return incorrect results. The position of a delegate during a solve can be accessed via the .simpos
property.
Delegates cannot be rendered, so the size of the Delegate object is primarily for use in scene setup
and for determining bounding box extents.

See Also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

CrowdScatter:
These properties correspond to the Scatter Objects dialog displayed by clicking the Scatter
Objects icon.
Clone Tab Properties:
<crowd.scatter>.cloneObject Node Default: Undefined
Object in the scene to be cloned.
<crowd.scatter>.numClones Integer Default: 10
The number of clones to be generated.
<crowd.scatter>.cloneType Integer Default: 0 Alias
(0_copy__1_reference__2_instance)
0 - copy
1 - Instance
2 - Reference
Specify how the object is cloned. It can be cloned as a copy, an instance, or a reference.
 CrowdScatter: 1779

<crowd.scatter>.cloneHierarchy Boolean Default: True

When true, all objects linked to the selected object are cloned as well, with the hierarchical
structure retained intact for each clone.
<crowd.scatter>.cloneControllers Boolean Default: True
Set true to clone an object when calling Scatter All. The object is cloned and then any
specified transforms are applied to the clones.
Position Tab Properties:
<crowd.scatter>.positionSpace Integer Default: 0 Alias
0_Grid__1_Box___2_Sphere__3_Surface
0 - On Grid
1 - Inside Box
2 - Inside Sphere
3 - On Surface
4 - In Radial Area
Choose position object before selecting the reference object. On Grid distributes the clones
over the surface of a grid object. Inside Box and Inside Sphere distribute the clones within
the volume of a primitive box or sphere object, respectively.
<crowd.scatter>.positionObject Node Default: Undefined Alias:
Grid_Box_Sphere_Surface
An object in the scene to be used as a reference object.
Note:
You can use only a primitive sphere, a primitive box, or a grid helper object as a reference object. A
primitive sphere or box that has been converted to a editable mesh object can’t be used as a
reference object.
<Crowd.scatter>.surfaceOffset Float Default: 0.0
On Surface specifies a consistent distance above the surface using surface normals for
distribution. Available only when .positionSpace is set to On Surface.
<Crowd.scatter>.centerX Float Default: 0.0
Specifies the X value for the center of the distribution in world coordinates.
<Crowd.scatter>.centerY Float Default: 0.0
Specifies the Y value for the center of the distribution in world coordinates.
<Crowd.scatter>.centerZ Float Default: 0.0
Specifies the Z value for the center of the distribution in world coordinates.
<Crowd.scatter>.radius Float Default: 10.0
Specifies the maximum distance from the center within which clones are to be positioned.
<Crowd.scatter>.XYPlane Boolean Default: False
Specifies that clones are to be distributed on the world XY plane only, resulting in a disc-
like array.
1780 Chapter 21 | character studio 3 MAXScript Extensions

<crowd.scatter>.childBbox Boolean Default: True Alias:

Include_childrens__bounding_boxes_in_spacing_calculations
When true, all of a hierarchical object’s sub-objects are considered when determining
spacing. When false, only the selected object is considered.
<crowd.scatter>.spacing Float Default: 1.0 Alias:
Bounding_Box_Multiplier_for_Position_Spacing
Specifies the minimum distance between cloned objects. The Spacing setting is multiplied
by the size of the object’s bounding sphere to determine how close objects can get. If
Spacing is left at 1.0, the default, objects normally cannot be positioned within each
others’ bounding spheres. If Spacing is set to 2.0, objects are separated by a distance equal
to or greater than the size of the bounding sphere.
<crowd.scatter>.positionSeed Integer Default: 0
Specifies a seed value for randomizing the clones’ locations. If a scene has more than one
crowd, each should use a different seed to avoid having identical configurations.
Rotation Tab Properties:
<Crowd.scatter>.forwardAxisSign Boolean Default: True
If true, the forward axis is in the positive direction. If false the forward axis is in the
negative direction.
<crowd.scatter>.forwardAxis Integer Default: 1
0-X
1-Y
2-Z
Specifies which axis of the cloned objects points forward, for use with the Look At
Target option.
<crowd.scatter>.UpAxisSign Boolean Default: True
If true the up axis is in the positive direction. If false the up axis is in the negative
direction.
<crowd.scatter>.UpAxis Integer Default: 2
0-X
1-Y
2-Z
Axis of the cloned objects points upward; this axis is aligned with the world Z axis.
Note:
You cannot specify the same axis as Local Forward and Local Up simultaneously. If you choose an
axis for one that’s already chosen for the other, the software switches the other to a different axis.
 CrowdScatter: 1781

<crowd.scatter>.lookFrom Integer Default: 0

0 - Look From Self
1 - Look From Selected Object
Determines the direction from which the clones look. By default, each clone looks from its
own position (Self), so that when several clones are looking at a single target, each is
oriented differently. To orient each clone so that it’s parallel to an imaginary line between
two objects (the “from” object and the “to” object), choose Selected Object and specify the
object with the (None) button.
<crowd.scatter>.lookFromObject Node Default: Undefined
An object from which the clones are to look if lookFrom = 1.
<crowds.scatter>.LookTowards Integer Default: 0
0 - Look Toward Self
1 - Look Toward Selected Object
Determines the direction toward which the scatter objects look. By default, each object
retains its current orientation.
<crowd.scatter>.lookAtTarget Node Default: Undefined
An object toward which the clones are to look.
<crowd.scatter>.sideDeviation Float Default: 0.0
Sets a maximum deviation angle in degrees for the clones’ sideways orientation. If clones
should look in an object’s general direction but may look at a spot to either side of the
target, use Sideways Deviation to set the maximum amount by which they can deviate
from the calculated angle. The actual deviation amount for each clone is calculated at
random, based on the Deviation settings and the Rand Seed setting. Range=0.0 to 180.0.
<crowd.scatter>.upDownDeviation Float Default: 0.0
Sets a maximum deviation angle in degrees for the clones’ up/down orientation. If clones
should look in an object’s general direction but may look at a spot above or below the
target, use Up/Down Deviation to set the maximum amount by which they can deviate
from the calculated angle. The actual deviation amount for each clone is calculated at
random, based on the Deviation settings and the Rand Seed setting. Range=0.0 to 180.0.
<crowd.scatter>.rotationSeed Integer Default: 0
Specifies a seed value for randomizing the clones’ orientations, based on the Deviation
settings. If a scene has more than one crowd, each should use a different seed to avoid
having identical configurations.
Scale Tab Properties:
Contains options for scaling object clones. For each scaling axis you can specify alternative
forward and up axes, plus a target object toward which the clones will point. In addition,
you can specify a source object; when using both source and target objects, the clones are
rotated so they’re parallel to the line between the two.
<crowd.scatter>.xScale Float Default: 1.0
Sets scaling on the X axis as a multiplier.
1782 Chapter 21 | character studio 3 MAXScript Extensions

<crowd.scatter>.xScaleDeviation Float Default: 0.0

Sets the maximum factor for randomization of scaling. For each clone, Deviation is
multiplied by a random number between 0.0 and 1.0, and then added to the Scale
multiplier.
<crowd.scatter>.matchXtoYscale Boolean Default: False
Lets you use the same scaling as on the Y axis, whether explicit or randomized. When you
specify an axis, the parameters group for that axis becomes unavailable.
<crowd.scatter>.matchXtoZscale Boolean Default: False
Lets you use the same scaling as on the Z axis, whether explicit or randomized. When you
specify an axis, the parameters group for that axis becomes unavailable.
<crowd.scatter>.yScale Float Default: 1.0
Sets scaling on the Y axis as a multiplier.
<crowd.scatter>.yScaleDeviation Float Default: 0.0
Sets the maximum factor for randomization of scaling. For each clone, Deviation is
multiplied by a random number between 0.0 and 1.0, and then added to the Scale
multiplier.
<crowd.scatter>.matchYtoXscale Boolean Default: False
Lets you use the same scaling as on the X axis, whether explicit or randomized. When you
specify an axis, the parameters group for that axis becomes unavailable
<crowd.scatter>.matchYtoZscale Boolean Default: False
Lets you use the same scaling as on the Z axis, whether explicit or randomized. When you
specify an axis, the parameters group for that axis becomes unavailable
<crowd.scatter>.zScale Float Default: 1.0
Sets scaling on the Z axis as a multiplier.
<crowd.scatter>.zScaleDeviation Float Default: 0.0
Sets the maximum factor for randomization of scaling. For each clone, Deviation is
multiplied by a random number between 0.0 and 1.0, and then added to the Scale
multiplier.
<crowd.scatter>.matchZtoXScale Boolean Default: False
Lets you use the same scaling as on the X axis, whether explicit or randomized. When you
specify an axis, the parameters group for that axis becomes unavailable.
<crowd.scatter>.matchZtoYScale Boolean Default: False
Lets you use the same scaling as on the Y axis, whether explicit or randomized. When you
specify an axis, the parameters group for that axis becomes unavailable.
<crowd.scatter>.scaleSeed Integer Default: 0
Specifies a seed value for randomizing the clones’ scales, based on the Deviation settings.
 CrowdScatter: 1783

All Ops Tab Properties:

<crowd.scatter>.ComputeClones Boolean Default: False
Set true to clone an object when calling Scatter All. The object is cloned, then any specified
transforms are applied to the clones.
Turning on Clones makes the Select Objects to Transform button unavailable. The object
to clone and cloning parameters must be specified on the with .ComputeClone.
<crowd.scatter>.ComputePositions Boolean Default: False
When true and crowds.scatterall is called, the transforms are applied according to the
settings in the Position panel.
<crowd.scatter>.ComputeRotations Boolean Default: False
When true and crowds.scatterall is called, the transforms are applied according to the
settings in the Rotation panel.
<crowd.scatter>.ComputeScales Boolean Default: False
When true and crowds.scatterall is called, the transforms are applied according to the
settings in the Scale panel.
<Crowd.scatter>.IncPosSeed Boolean Default: False
When true, add 1 to the .positionSeed value, and redistributes the objects using the
new random seed.
<Crowd.scatter>.IncRotSeed Boolean Default: False
When true, add 1 to the .rotationSeed value, and redistributes the objects using the new
random seed.
<Crowd.scatter>.IncSclSeed Boolean Default: False
When true, add 1 to the .scaleSeed value, and redistributes the objects using the new
random seed.
<crowd.scatter>.ObjectsToScatter ArrayParameter Default: #()
Objects to be affected by calling crowds.scatterall
ObjAssoc Properties:
These properties correspond to the Object/Delegate dialog displayed by clicking the Associate
Objects with Delegates icon.
<ObjAssoc>.objects ArrayParameter Default: #() -- node array
Array of linked Objects.
<ObjAssoc>.delegates ArrayParameter Default: #() -- node array
Array of linked delegates.
<ObjAssoc>.alignScale Boolean Default: True
When true, Align Objects with Delegates sets each object’s absolute scaling factor to that of
its corresponding delegates. This is useful if, for example, you’ve randomized delegates’
sizes with the Scatter Objects Scale panel, and want the associated objects to match.
1784 Chapter 21 | character studio 3 MAXScript Extensions

Smooth Properties:
These properties correspond to the Smoothing dialog displayed by clicking the Smooth Paths button
in the Solve rollout.
<Crowd.smooth>.objects ArrayParameter Default: #() -- node array;
Alias: Objects_to_Smooth
Specify which objects’ positions and/or rotations to smooth.
<Crowd.smooth>.filterDelegates Boolean Default: True Alias:
Filter_Delegate_Selection
When true, the Select dialog opened by the Select Objects to Smooth button shows only
delegates. When off, it shows all scene objects.
<Crowd.smooth>.wholeAnim Integer Default: 0
0 - Whole Animation: Smoothes all animation frames.
1 - Animation Segment: Smoothes only the frame ranges specified in the From and
To fields.
<Crowd.smooth>.from Integer Default: 0 Alias:
smooth_from_frame
When Animation Segment is chosen, specifies the first animation frame for smoothing.
<Crowd.smooth>.to Integer Default: 0 Alias:
smooth_to_frame
When Animation Segment is chosen, specifies the last animation frame for smoothing.
<Crowd.smooth>.positions Boolean Default: True Alias:
Smooth_positions
When true, selected objects’ animation paths generated via the simulation are smoothed
after the simulation has finished.
<Crowd.smooth>.rotations Boolean Default: True Alias:
Smooth_rotations
When true, selected objects’ rotations generated via the simulation are smoothed after the
simulation has finished.

CrowdAssignment : MAXObject
Constructor:
CrowdAssignment ...

Properties:
<crowdassignment>.team CrowdTeam Default: Undefined
A named group of delegates.
<crowdassignment>.delegate Node Default: Undefined
A delegate object. See the CrowdDelegate : Helper (p. 1773) topic.
<crowdassignment>.behavior MAXObject Default: Undefined
One of the Crowd Behavior (p. 1792) classes.
 CrowdTeam : ReferenceTarget 1785

<crowdassignment>.cogcontrol CogControl Default: Undefined Alias:

CognitiveController
A cognitive controller. See CogControl:MAXObject (p. 1791) for more details.
<crowdassignment>.weight Float Default: 1.0 --
animatable
The relative effect of the assigned behavior or cognitive controller. The higher an
assignment’s weight setting is than others’, the more effect it will have. This setting is
animatable. Range=0.0 to 1.0.
<crowdassignment>.active : Boolean
When true, the assignment is currently in effect. When false, the assignment has no effect.
Default=true.
Notes:
Normally either the team or the delegate property will contain a value of undefined. If both
properties contain a value other than undefined, the assigment is applied to the team.
Normally either the cogcontrol or the behavior property will contain a value of undefined. If both
properties contain a value other than undefined, the behavior will be used.
Do not assign a value other than undefined or a CrowdTeam value to the team property.
Do not assign a value other than undefined or a Behavior value to the behavior property.
Do not assign a value other than undefined or a CogControl value to the cogcontrol property.
Do not assign a node type other than a Delegate node to the delegate property.

See also
CrowdTeam : MAXObject (p. 1785)
Crowd Behaviors (p. 1792)
CogControl : MAXObject (p. 1791)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

CrowdTeam : ReferenceTarget
Constructor:
CrowdTeam ...
CrowdGroup ...

Properties:
<crowdteam>.name String Default: “CrowdTeam”
The default team name is Team followed by number one more than the last added team.
<crowdteam>.members ArrayParameter Default: #() -- array
of Delegate nodes
Participants of the current team.
1786 Chapter 21 | character studio 3 MAXScript Extensions

Notes:
You can perform the following MAXScript operations
deleteitem <array> <itemnumber>
<array> = #(item,item...)
<array> = append <array> <item>
on all of the properties containing an ArrayParamater of objects listed below. You can also
undo/redo these operations.
<CrowdTeam>.members -- array of Delegate nodes
Notes:
The following MAXScript operations will cause Crowd to fail, either right away or later:
NEVER set a Members ArrayParameter element to undefined.
Assigning a non-Delegate node to the Members ArrayParameter.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

CrowdState:ReferenceTarget
Constructor:
CrowdState ...
Properties:
<crowdstate>.name String Default: “State”
The name of the state.
<crowdstate>.behaviors ArrayParameter Default: #() -- array of
behaviors
See Notes below.
The names of all behaviors associated with the state.
<crowdstate>.weights ArrayParameter Default: #() -- array of floats
See Notes below.
Specifies the selected behavior’s weight. The higher the weight in relation to other
behaviors’ weights, the more evident the results of the behavior in the state. Default=1.0.
Range=0.0 to 1.0.
<crowdstate>.transitions ArrayParameter Default: #() -- array of
CrowdTransition objects
See Notes below.
Notes:
You can perform the following MAXScript operations:
deleteitem <array> <itemnumber>
<array> = #(item,item...)
 CrowdTransition : MAXObject 1787

<array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also
undo/redo these operations.
<CrowdState>.behaviors -- array of behaviors
<CrowdState>.weights -- array of floats
<CrowdState>.transitions -- array of CrowdTransition objects

If you add or delete elements to the Behaviors ArrayParameter, the corresponding

element in the Weights ArrayParameter must be added or deleted.

The following MAXScript operations will cause Crowd to fail, either right away or later:
NEVER set Behavior ArrayParameter element to undefined.
NEVER set a Behavior ArrayParameter element to anything other than an object of the
appropriate type.

See Also
Crowd Behaviors (p. 1792)
CrowdTransition : MAXObject (p. 1787)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

CrowdTransition : MAXObject
Constructor:
CrowdTransition ...
Transition ...

Properties:
<crowdtransition>.priority Integer Default: 0
Sets the transition’s priority.
<crowdtransition>.duration Integer Default: 25
The number of frames the software takes to affect the transition between states.
<crowdtransition>.easeIn Float Default: 0.5
Ease in value for the source clip.
<crowdtransition>.easeOut Float Default: 0.5
Ease out value for the destination clip.
<crowdtransition>.functionName String Default: “transFunc” Alias:
Script_Context_Name
The name of the MAXScript conditional that specifies when/how the transition is to occur.
<crowdtransition>.script String Default: Undefined
<crowdtransition>.from CrowdState Default: Undefined Alias:
FromState
The state that the transition originated from.
1788 Chapter 21 | character studio 3 MAXScript Extensions

<crowdtransition>.to CrowdState Default: Undefined Alias:

ToState
The state that the transition is destined for.
Notes:
The <CrowdTransition>.functionName value must match the name of the function defined in
<CrowdTransition>.script.
The script function is compiled with the function name in global scope. The function name cannot
be the same as a MAXScript-defined global variable name.
The <CrowdTransition>.script is of the form:
fn transFunc del trans t =
( if t < 50 then 0 else 1
)

where del is the delegate node, trans is the CrowdTransition value, and t is the time value
of the frame being evaluated. The 3ds max time context will also be frame being
evaluated. The return value must be an integer value. If the return value is 0, the transition
is not taken. For any other return value, the transition is taken.
The <CrowdTransition>.script is not evaluated for a delegate while the delegate is in
transition between states.
The following MAXScript operations will cause Crowd to fail, either right away or later:
NEVER set the from or to properties to undefined.
NEVER set the from or to properties to anything other than a CrowdState object.

See also
CrowdState : MAXObject (p. 1786)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Crowds - Methods
crowds.solve <crowd_node>
Equivalent to clicking Solve in the crowd’s Solve rollout. .solve starts the solving, based on
all other current crowd parameter settings.
crowds.genclones <crowd_node>
Equivalent to clicking Generate Clones in the Scatter Objects dialog, Clone tab, displayed
by clicking the Scatter Objects icon. Generates clones based on all other current crowd
parameter settings.
crowds.genlocations <crowd_node>
Equivalent to clicking Generate Locations in the Scatter Objects dialog, Position tab,
displayed by clicking the Scatter Objects icon. Generates locations based on all other
current crowd parameter settings.
 Crowds - Methods 1789

crowds.genrotations <crowd_node>
Equivalent to clicking Generate Orientations in the Scatter Objects dialog, Rotation tab,
displayed by clicking the Scatter Objects icon. Generates rotations based on all other
current crowd parameter settings.
crowds.genscales <crowd_node>
Equivalent to clicking Generate Scales in the Scatter Objects dialog, Scale tab, displayed by
clicking the Scatter Objects icon. Generates scales based on all other current crowd
parameter settings.
crowds.scatterall <crowd_node>
Equivalent to clicking Scatter button in the Scatter Objects dialog, All Ops tab. Scatters
objects based on all other current crowd parameter settings.
crowds.alignObjects <crowd_node>
Equivalent to clicking Align Objects with Delegates in the Object/Delegates dialog
displayed by clicking the Associate Objects with Delegates icon. Aligns objects based on all
other current crowd parameter settings.
crowds.linkObjects <crowd_node>
Equivalent to clicking Link Objects to Delegates in the Object/Delegates dialog displayed
by clicking the Associate Objects with Delegates icon. Links objects based on all other
current crowd parameter settings.
crowds.assignControllers <crowd_node>
Equivalent to clicking Assign Delegate Controllers to Objects in the Object/Delegates
dialog displayed by clicking the Associate Objects with Delegates icon. Assigns controllers
based on all other current crowd parameter settings.
crowds.smooth <crowd_node>
Equivalent to clicking OK in the Smoothing dialog displayed by clicking the Smooth Paths
button in the Solve rollout. Smooths objects motions based on all other current crowd
parameter settings.
crowds.assignGridProximityPriorities <crowd_node>
Equivalent to clicking Proximity to a Grid/Assign in the Priority rollout. Assigns priorities
to the delegates specified in <Crowd.priority>.delegates based on their distance from the
grid specified in <Crowd.priority>.grid.
crowds.assignObjectProximityPriorities <crowd_node>
Equivalent to clicking Proximity to an Object/Assign in the Priority rollout. Assigns
priorities to the delegates specified in <Crowd.priority>.delegates based on their distance
from the object specified in <Crowd.priority>.object.
crowds.assignRandomPriorities <crowd_node>
Equivalent to clicking Assign Random Priorities in the Priority rollout. Assigns random
priorities to the delegates specified in <Crowd.priority>.delegates.
crowds.assignUniquePriorities <crowd_node>
Equivalent to clicking Make Priorities Unique in the Priority rollout. Ensures that the
priorities of the delegates specified in <Crowd.priority>.delegates are unique. If two
delegates share the same priority, one of them will be given a new priority.
1790 Chapter 21 | character studio 3 MAXScript Extensions

crowds.incrementPriorities <crowd_node>
Equivalent to clicking Increment Priorities in the Priority rollout. Increments the priorities
of the delegates specified in <Crowd.priority>.delegates by the value in
<Crowd.priority>.increment.
Notes - MAXScript Group:
The MAXScript group of the Solve Rollout has a feature to control the execution of a MAXScript
script at each frame.
Use MAXScript: When on, a user-specified script is executed at each frame during the
solution. Default=off.
Function Name: The name of the function to be executed. This name must be identical to
the one specified in the script.
Edit MAXScript: Click this button to open a MAXScript window for displaying and
modifying the script.
The crowd function needs two parameters defined. The 1st parameter passed in is the current
crowd and the 2nd parameter passed in is the solve frame.
Here is simple example:
fn g_PerFrameFn current_crowd the_frame_time =
(
if the_frame_time == 1f then
(_g_mydebugwindow = newScript()
format “% %\n” current_crowd the_frame_time to:_g_mydebugwindow
)
)

Notes:
You can perform the following MAXScript operations:
deleteitem <array> <itemnumber>
<array> = #(item,item...)
<array> = append <array> <item>
on all of the properties containing an ArrayParamater of objects listed below. You can also
undo/redo these operations.
<Crowd>.behaviors -- array of Behavior objects
<Crowd>.teams -- array of CrowdTeam objects
<Crowd>.assignments -- array of Assignment objects
<Crowd>.cogcontrols -- array of CognotiveController objects
<Crowd.scatter>.ObjectsToScatter -- node array
<Crowd.objAssoc>.objects -- node array
<Crowd.objAssoc>.delegates -- node array
<Crowd.smooth>.objects -- node array

If you delete a team or a cognitive controller via MAXScript deleteitem $crowd01.teams[1] 1 or

deleteitem $crowd01.cogcontrols[1] 1, it may still be referenced by some assignments. Nothing
will go wrong, but it’s a strange thing to do and one probably should not do it.
 CogControl : MAXObject 1791

The following MAXScript operations will cause Crowd to fail, either right away or later:
NEVER set a Crowd ArrayParameter element to undefined.
NEVER set a Crowd ArrayParameter element to to anything other than an object of the
appropriate type.

CogControl : MAXObject
Constructor:
CogControl ...

Properties:
<cogcontrol>.name String Default: “ CognitiveControl”
The name of the state diagram.
<cogcontrol>.startState CrowdState Default: Undefined
Set the starting CrowdState (p. 1786). By default the state that executes first in a cognitive
controller is the one that was added first.
<cogcontrol>.states ArrayParameter Default: #() -- array of
CrowdState objects
All of the states used by this cognitive controller.
Notes:
You can perform the following MAXScript operations
deleteitem <array> <itemnumber>
<array> = #(item,item...)
<array> = append <array> <item>
on all of the properties containing an ArrayParamater of objects listed below. You can also
undo/redo these operations.
<CogControl>.states -- array of CrowdState objects

If you delete a CrowdState (deleteitem $crowd01.cogcontrols[1].states 1), it may still be

referenced by either the startState or by a CrowdTransition stored in another CrowdState.
The following MAXScript operations will cause Crowd to fail, either right away or later:
NEVER set a States ArrayParameter element or the startState to undefined.
NEVER set a States ArrayParameter element or the startState to anything other than a
CrowdState.

See also
CrowdState:MAXObject (p. 1786)
CrowdAssignment : MAXObject (p. 1784)
CrowdTeam : MAXObject (p. 1785)
CogControl : MAXObject (p. 1791)
1792 Chapter 21 | character studio 3 MAXScript Extensions

Node Common Properties, Operators, and Methods (p. 820)

MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Crowd Priority Properties

<Crowd.priority>.start Integer Default: 0

<Crowd.priority>.delegates ArrayParameter Default: #() -- node array

<Crowd.priority>.object Node Default: Undefined

<Crowd.priority>.grid Node Default: Undefined

<Crowd.priority>.increment Integer Default: 0

<Crowd.priority>.showPriorities Boolean Default: False

See Also
Crowd : helper (p. 1771)

Crowd Behaviors
Avoid_Behavior : MAXObject (p. 1793)
Orientation_Behavior : MAXObject (p. 1794)
Path_Follow_Behavior : MAXObject (p. 1796)
Repel_Behavior : MAXObject (p. 1798)
Scripted_Behavior : MAXObject (p. 1799)
Seek_Behavior : MAXObject (p. 1807)
Space_Warp_Behavior: MAXObject (p. 1809)
Speed_Vary_Behavior : MAXObject (p. 1809)
Surface_Arrive_Behavior : MAXObject (p. 1811)
Surface_Follow_Behavior : MAXObject (p. 1814)
Wall_Repel_Behavior : MAXObject (p. 1816)
Wall_Seek_Behavior : MAXObject (p. 1817)
Wander_Behavior : MAXObject (p. 1819)
 Avoid_Behavior : MAXObject 1793

Avoid_Behavior : MAXObject
Constructor:
Avoid_Behavior ...
AvoidBehavior ...

Properties:
<Avoid_behavior>.name String Default: “Avoid”

<Avoid_behavior>.obstacles ArrayParameter Default: #() -- node array

Any object or objects that the delegates must keep away from. See Notes below.
<Avoid_Behavior>.lookAhead Integer Default: 30 -- animatable
The number of frames in advance of the current frame that the software looks for potential
collisions.
<Avoid_behavior>.hardRadius Float Default: 1.0 -- animatable
Distance from center of the delegate(s), where no penetration should occur.
<Avoid_Behavior>.showHardRadius Boolean Default: False
Enables display of a wireframe sphere that depicts the extent of the .hardRadius setting.
<Avoid_Behavior>.detourAngle Float Default: 360.0 -- animatable
Maximum necessary turning angle relative to the direction of delegate’s goal that the
delegate will steer to avoid rather than slow down and wait.
<Avoid_Behavior>.brakePressure Float Default: 2.0 -- animatable
Determines how strongly the brakes are applied. Higher values induce more gradual and
slower stops, but may cause brakes to “pump” in order to slow down.
<Avoid_behavior>.repelStrength Float Default: 0.2 -- animatable
Determines the strength of the repelling force; higher values result in greater repulsion
force.
<Avoid_behavior>.repelRadius Float Default: 3.0
Distance from hard radius of delegate where “repel” avoidance is sensed and carried out.
<Avoid_behavior>.repelFalloff Float Default: 3.0 -- animatable
Higher values cause the repel to fall off to zero more rapidly with distance, thus focusing
its effect closer to the delegate’s hard radius.
<Avoid_behavior>.vfieldStrength Float Default: 1.0 Alias
Vector_Field_Avoid_Strength -- animatable
Higher values result in more severe influence. Delegates will be directed to move
perpendicular to the field.
<Avoid_behavior>.vfieldFalloff Float Default: 8.0 Alias
Vector_Field_Falloff -- animatable
Higher values cause vector field influence to fall off to zero more rapidly with distance,
thus focusing its effect closer to the delegate’s hard radius.
<Avoid_Behavior>.showRepelRadius Boolean Default: False
When true, displays a wireframe sphere that depicts the extent of the .repelRadius
setting.
1794 Chapter 21 | character studio 3 MAXScript Extensions

<Avoid_Behavior>.showPotentialCols Boolean Default: False

When true, displays a green line from the delegate to the location of a potential collision.
<Avoid_Behavior>.showRepelActivity Boolean Default: False
When true, displays a white line between the delegate and target when the repel force is
in effect.
<Avoid_Behavior>.showLookAhead Boolean Default: False
When true, displays a sphere that shows the current distance used to check for potential
collisions.
<Avoid_behavior>.forceColor Color Default: (color 255 0 0)
Sets the color used to draw the Avoid force vector during the solution.
<Avoid_behavior>.displayForce Boolean Default: True
When true, force exerted on the delegate(s) by the Avoid behavior is drawn in the
viewports as a vector during the simulation solution.
Notes:
You can perform the following MAXScript operations:
deleteitem <array> <itemnumber>
<array> = #(item,item...)
<array> = append <array> <item>
on all of the properties containing an ArrayParamater of objects listed below. You can also
undo/redo these operations.
<Avoid_Behavior>.obstacles

The following MAXScript operations will cause Crowd to fail, either right away or later:
NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See also
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Orientation_Behavior : MAXObject
Constructor:
Orientation_Behavior ...

OrientationBehavior ...

Properties:
<orientation_behavior>.name String Default: “Orientation”

<Orientation_Behavior>.headingRelative Boolean Default: False

 Orientation_Behavior : MAXObject 1795

<orientation_behavior>.minheading Float Default: -180.0 Alias:

HeadingMin – animatable
The minimum permissible heading. This number should be lower than the Min Heading
value. Range=-180 to 180.
<orientation_behavior>.maxheading Float Default: 180.0 –HeadingMax –
animatable
The maximum permissible heading. This number should be higher than the Min Heading
value. Range=-180 to 180.
<orientation_behavior>.maxHeadingVel Float Default: 180.0 Alias:
maxHeadingVelocity – animatable
Specifies how much the delegate’s heading can change per frame. This controls angular
acceleration and deceleration.
<orientation_behavior>.headingresponse Float Default: 1.0 – animatable
Determines how quickly the heading follows the direction the object is moving in. A value
of 1.0 indicates maximum responsiveness, and will point in the direction the delegate is
moving while a lower value means that it is less responsive. Range=0 to 1.
<orientation_behavior>.minpitch Float Default: -180.0 Alias: PitchMin
– animatable

The minimum number of degrees a delegate can incline or decline. This number should be
lower than the Max Pitch value. Range=-180 to 180.
<orientation_behavior>.maxpitch Float Default: 180.0 Alias: PitchMax
– animatable
The maximum number of degrees a delegate can incline or decline. This number should be
higher than the Min Pitch value. Range=-180 to 180.
<orientation_behavior>.maxpitchVel Float Default: 1.0 Alias:
maxPitchVelocity – animatable
Specifies how much the delegate’s pitch can change per frame. This controls angular
acceleration and deceleration.
<orientation_behavior>.pitchresponse Float Default: 1.0 – animatable
Determines how quickly the pitch follows the direction the object is moving in. A value of
1.0 indicates maximum responsiveness while a lower value means that it is less responsive.
Range=0 to 1.
<orientation_behavior>.maxbank Float Default: 30.0 – animatable
The maximum number of degrees the delegate can bank.
<orientation_behavior>.maxbankAccel Float Default: 3.0 Alias:
MaxBank_Change – animatable
The maximum number of degrees the delegate’s bank angle can change per frame. This
controls angular acceleration and deceleration.
<orientation_behavior>.bankPerTurn Float Default: 1.0 – animatable
The number of degrees the delegate will bank as a function of the turn angle at the current
frame. For example, if Bank per Turn=1, the delegate will bank one degree for every degree
it is turning at a given frame.
1796 Chapter 21 | character studio 3 MAXScript Extensions

Notes:
If this behavior is active, it controls the orientation of the delegate by allowing the animator to
specify limits and responsiveness on the pitch and heading of the object.
The animator can limit the min and max values, the rate, and can also set a ‘response’ value which
controls how quickly the pitch or heading follows the direction the object is moving in. A value
of 1.0 means it’s responsive, and will point in the direction the delegate is moving (within the
limits), while a lower value means that it is less responsive. It also calculates the roll, which is done
using the same parameters that the default behavior does.

See also
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Path_Follow_Behavior : MAXObject
Constructor:
Path_Follow_Behavior ...

PathFollowBehavior ...

Properties:
<path_follow_behavior>.name String Default: “Path Follow”

<path_follow_behavior>.path Node Default: Undefined

A path object. Suitable path objects include splines and NURBS curves. If a path object
contains more than one spline or curve, character studio uses the lowest-numbered
element (usually the earliest created one).
<path_follow_behavior>.radius Float Default: 20.0 Alias:
Radius_about_Path -- animatable
The radial distance from the path within which the delegate stays while traversing the
path. Range=0.0 to 99,999.0.
<path_follow_behavior>.awareness Float Default: 0.5 -- animatable
Specifies how “intelligent” the delegate is while traversing this path. A high Awareness
setting means that it takes into account the curve of the path while moving and will try to
anticipate changes. A low value for Awareness, on the other hand, means that the delegate
notices the path only when leaving it. Range=0.0 to 1.0.
Note: You can randomize awareness behavior with the Deviation and Seed settings.
 Path_Follow_Behavior : MAXObject 1797

<path_follow_behavior>.awareDeviation Float Default: 0.0 Alias:

AwarenessDeviation -- animatable
Specifies the maximum amount by which Awareness should vary. character studio takes a
random number between the negative and positive values of the Deviation setting,
multiplies it by the Awareness setting, and adds the result to Awareness. Range=0.0 to 1.0.
Note: You can vary behaviors among different Path Follow behaviors that use the same
Awareness and Deviation settings by changing the Seed value.
<path_follow_behavior>.start Integer Default: 0 -- animatable
0 - Path Beginning
1 - Path End
This setting determines where on the path the delegate begins to follow the path.
<path_follow_behavior>.direction Integer Default: 0 -- animatable
0 – Forwards: The delegate moves along path vertices in ascending order.
1 – Backwards: The delegate moves along path vertices in descending order.
<path_follow_behavior>.endAction Integer Default: 0 -- animatable
0 – Loop: The delegate loops around the path, even if it isn’t closed. If Beginning of Path or
End of Path is chosen, it returns to the path’s start or end point each time it finishes
traversing the path. If Nearest Point is chosen, it returns to an arbitrary point determined
by its position and the path shape.
1 – Reverse: The delegate reverses direction at the end of the path. Use this choice to
simulate a back-and-forth “patrol” behavior.
2 – Continue: The delegate continues moving in the same direction it faced at the end of
the path until the simulation ends or it’s acted upon by another force or behavior.
<path_follow_behavior>.seed Integer Default: 1 -- animatable
Specifies a seed value for randomizing Awareness.
<path_follow_behavior>.forceColor Color Default: (color 0 0 255)
The color used to draw the Path Follow force vector during the solution.
<path_follow_behavior>.displayForce Boolean Default: True
When true, force exerted on the delegate(s) by the Path Follow behavior is drawn in the
viewports as a vector during the simulation solution.
<path_follow_behavior>.targetColor Color Default: (color 0 0 127.5)
Sets the color used to draw the target icon.
<path_follow_behavior>.displayTarget Boolean Default: True
Enables display of the target icon, which appears during the solution when a new interim
goal is calculated for the delegate.
<path_follow_behavior>.targetScale Float Default: 5.0 -- animatable
The overall size of the target icon.
1798 Chapter 21 | character studio 3 MAXScript Extensions

See also
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Repel_Behavior : MAXObject
Constructor:
Repel_Behavior ...
RepelBehavior ...

Properties:
<Repel_Behavior>.name String Default: “Repel”

<Repel_Behavior>.repulsionSources ArrayParameter Default: #() -- node array

See Notes below
<Repel_Behavior>.targetComp Integer Default: 0
0 – Closest Source: Each delegate is repelled by the closest of the assigned sources. Use this
to have delegates assigned a single Repel behavior move away from sources in different
directions.
1 – Average of Sources: All delegates head to a common point determined by averaging all
sources’ locations.
<Repel_Behavior>.repelMethod Integer Default: 0 -- animatable
0 – Angle: Applies a force to the delegate based on the angle between the delegate’s current
direction and the direction it would need to take in order to be moving directly away from
the source. If the behavior’s Weight is set to 1, the delegate will be given a force that points
directly away from the source. If Weight is set to .5, the force will bisect the angle between
its current direction and the direction opposite that of the source.
1 – Force: Always applies a force directly away from the source, but at different
magnitudes. If the behavior’s Weight is 1, the magnitude of the force will be the average
speed. If the Weight is .5, the magnitude of the force will be half the average speed.
<Repel_Behavior>.useRadii Boolean Default: True
When true, the behavior applies only to delegates closer to the target than the Outer
Distance value.
<Repel_Behavior>.innerRadius Float Default: 0.0 -- animatable
The distance from the target at which the force is applied at full strength.
<Repel_Behavior>.outerRadius Float Default: 10.0 – animatable
The distance from the target at which the force begins to be applied.
<Repel_Behavior>.falloff Float Default: 2.0 -- animatable
<Repel_Behavior>.forceColor Color Default: (color 255 0 255)
The color used to draw the Repel force vector.
 Scripted_Behavior : MAXObject 1799

<Repel_Behavior>.showRadii Boolean Default: True

When true, the radii are displayed when the force is active.
<Repel_Behavior>.displayForce Boolean Default: True
When true, force exerted on the delegate(s) by the Repel behavior is drawn in the
viewports as a vector during the simulation solution. If Use Radii is turned on, the radii are
also displayed when the force is active.
Notes:
You can perform the following MAXScript operations:
deleteitem <array> <itemnumber>
<array> = #(item,item...)
<array> = append <array> <item>
on all of the properties containing an ArrayParamater of objects listed below. You can also
undo/redo these operations.
<Repel_Behavior>.repulsionSources

The following MAXScript operations will cause Crowd to fail, either right away or later:
NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See Also
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Scripted_Behavior : MAXObject
Introduction to the Crowd System
The crowd system works by assembling all of the force vectors (p. 1677) and speeds for a delegate from
its active force behaviors. Then based upon the delegate’s motion parameters, these force vectors
(p. 1677) and speeds are averaged and integrated to create a velocity for the delegate. This velocity
may then be modified if the delegate has an active constraint behavior or if it has an active default
Avoidance behavior.
After the velocity is set, if there is an active orientation behavior, it is used to set the orientation of
the delegate, otherwise the orientation is calculated from the default delegate parameters. Finally,
the velocity is integrated and a new position is calculated.
The new position of the delegate isn’t set until after all of the forces are calculated for all of the
behaviors.
For a biped crowd, bipeds work off of goals and not forces when determining which direction they
should go in. So, in order to create a force behavior that will work with a Biped, a goal position must
be specified. No forces need to be integrated into velocities because the movement of the Biped isn’t
based upon calculating velocities but rather by selecting clips found in the motion flow graph.
1800 Chapter 21 | character studio 3 MAXScript Extensions

Constructor:
Scripted_Behavior ...
ScriptedBehavior ...

Properties:
<scripted_behavior>.name String Default: “Scripted”

<Scripted_Behavior>.scriptContextName String Default: “apply” Alias:

Script_Context_Name
The script functions declared in the Edit MaxScript window are declared in a hidden
MaxScript context. This textbox specifies the name of the context. Giving a unique name
here avoids conflicts between different scripted behaviors.
<Scripted_Behavior>.type Integer Default: 0 Alias:
Behavior_Type
One of three behavior types: Force, Constraint, or Orientation.
Force: Behaviors of this type force the delegates to move in a particular direction, for
example, Seek and Repel. Force behaviors work by returning a force vector (p. 1677) in the
direction that the behavior want’s the delegate to go in, and in some cases the speed it
should be traveling at and the goal at which it is trying to reach.
Constraint: Behaviors of this type restrict the position and velocity of a delegate, for
example, SurfaceFollow. Constraint behaviors set the velocity and sometimes may even
change the delegate’s position, in order to meet the constraint. You may only have one
active constraint behavior per delegate per frame.
Orientation: Behaviors of this type affect only the orientation of the delegates, for example
Orientation. These behaviors don’t work with forces but instead return an orientation that
the delegate should be at, represented by a quaternion. Any active orientation behavior
will override the default orientation of the delegate. The velocity determines the default
orientation. Like a constraint behavior, you may only have one active orientation
behavior per delegate per frame.
Note:
Though there are no avoid behavior types, a force or constraint behavior may be used to create an
avoidance behavior. We do recommend though that the default Avoidance behavior be used due to
the fact that it is well integrated into the crowd solution pipeline.
<scripted_behavior>.script : string
 Scripted_Behavior : MAXObject 1801

Edit MaxScript:
This button “Edit MaxScript”, in the Scripted Behavior Rollout, opens a MAXScript editor window
that can be used to enter a scripted behavior script. The editor window is similar to other MaxScript
editor window but is slightly customized for scripted behaviors.

The following elements in the File Menu work differently:

New: disabled since only one editor per scripted behavior can be open at any time
Open: opens a file in the existing editor window. Any existing text will be lost.
Evaluate: evaluates the script and saves it into the behavior’s paramblock
Close: saves into the behavior’s paramblock and closes the editor if no errors found
1802 Chapter 21 | character studio 3 MAXScript Extensions

Scripted Behavior Syntax:

The scripted behavior script is implemented by defining a set of event handlers that get called by
the crowd system when solving the simulation. The event handlers are automatically enclosed into
a hidden MAXScript context. The name of the context is taken from the dialog’s Script Context
Name text box or its equivalent .scriptContextName.
Event Handlers for Scripted Behaviors:
on execute do <expr>
Called whenever the script is evaluated. All initializing should be done here.
on setupDelegates <delegates> <behavior> do <expr>
<delegates> an array of all the delegates after they are ordered
participating in the simulation. All delegates listed in the Behavior
Assignments pane of the Behavior and Team Assignment dialog are found in
this list.
<behavior> the current behavior

Called before the simulation starts.

Note:
All of the delegates are passed in, regardless if they have this behavior assigned, so the behavior
knows the max number of delegates that may be used and therefore set up whatever data structures
required. Some behaviors need to keep track of parameters on a per delegate basis. This function
allows the behavior to set up data structures to get that info. Also that is one of the reasons why the
delegate.id is unique, so it can be used to hash or index these data structures. Due to cognitive
controllers, you never really know exactly all of the delegates which will be active for a particular
behavior.
on display <behavior> <time> do <expr>

<behavior> the current behavior

<time> current time of the simulation

Called every time the crowd system is redrawn. You can use the low level drawing
functions from the gw struct, Viewport Drawing Methods (p. 1592), to have a custom display
for the behaviors.
Note:
This handler gets called a number of times, so the system will slow down if implemented.
on behaviorStarted <delegate> <behavior> <time> do <expr>

<delegate> the delegate node the behavior is assigned to

<behavior> the current behavior
<time> current time of the simulation
Called whenever a behavior becomes active for a particular delegate. This can occur at the
beginning of the simulation for an assigned behavior or when a cognitive controller
activates the behavior.
 Scripted_Behavior : MAXObject 1803

on initAtThisTime <behavior> <time>

This function is called for each behavior at the beginning of the frame.
on applyForce <delegate> <behavior> <time> <numSubSamples> <displayHelpers>
<weight> do <expr>
If the behavior type is Force or Orientation, this handler is called every frame to move
the delegate.
<delegate> the delegate node the behavior is assigned to
<behavior> the current behavior
<time> current time of the simulation
<numSubSamples> is the number of sub samples required per frame.
<displayHelpers> this value is true/false depending on the <Crowd>.update
and <Crowd>.updateFrequency, as well as the current frame. If it is true,
you should display any helper imagery you want using the display functions
available from the delegates structure. For instance, most behaviors
display their force if this is true, and pathfollow also displays its
target. The delegates.lineDisplay (p. 1773),.sphereDisplay, .bboxDisplay, and
.textDisplay are all functions which can be used to draw a graphic primitive
for a particular delegate when the crowd simulation is being solved. Please
see Viewport Drawing Methods for additional viewport drawing methods.
Note:
The graphic window functions gw.* described in Viewport Drawing Methods will not display
correctly or at all while in Step Solve.
<weight> this behavior’s weight on the delegate

The event handler should return an array of the following type:

#(<int_flags>, <point3_force>, <point3_goal>, <float_speed>,
<Speed_Weight_at_the_Goal>)

<int_flags> sum of any of the following values:

0 – the return value is not used by the crowd system
1 - only force is affected
2 - only goal is affected
4 - only speed is affected

For example, a value of 5, (1+4), indicates that the force and speed are affected.
<point3_force> the force vector (p. 1677). It should be unit normalized and
then multiplied by the delegate’s average speed. Modify this value, greater
or less, to make the force stronger or weaker.

<point3_goal> the goal position in world space.

1804 Chapter 21 | character studio 3 MAXScript Extensions

<float_speed> the net speed of the delegate. This value should be

normalized to the average speed of the delegate. A value of 1.0 means go at
the average speed.

<Speed_Weight_at_the_Goal> will represent the

speed that the delegate should be at when it reaches
its goal. This value should be normalized by the average speed of the
delegate, so that a value of 1.0 equal it’s average speed.

Notes:
Any behavior that sets the <int_flags> with a speed affected setting should ensure that a valid value
is set for <float_speed> and <Speed_Weight_at_the_Goal>. Note that a goal doesn’t need to be set for
this to work. This is how the ‘SpeedVary’ behavior works with Biped. It doesn’t explicitly set a goal
but still modifies the <Speed_Weight_at_the_Goal> value.
on constraint <delegate> <behavior> <time> <numSubSamples> <displayHelpers>
<finalSet> <velocity> <speed> <pos> do <expr>

If the behavior type, <Scripted_Behavior>.type, is Constraint, this handler is called

at least once every frame to constrain the delegate. The constraint behavior will override
any other force behavior, the Avoidance Behavior, plus it will override any acceleration
limits, speed limits etc. So it should be used with caution in a simulation.
The constraint behavior constrains the position that the delegate is moving towards by
changing the current position that the delegate is already at, it’s current velocity, and it’s
current speed. These values are combined to get the next position, Next_position =
Current_Position +Normalized(vel) * Speed. Changing the current position
doesn’t actually change where it is at though, it just changes the position that is used to
calculate it’s new position. This design allows the constraint to make the objects velocity
change abruptly and keep its speed, thus conserving the energy of the delegate.
<delegate> the delegate node the behavior is assigned to
<behavior> the current behavior
<time> current time of the simulation
<numSubSamples> is the number of sub samples required per frame.
<displayHelpers> this value is true/false depending on the <Crowd>.update
and <Crowd>.updateFrequency, as well as the current frame. If it is true,
you should display any helper imagery you want using the display functions
available from the delegate. For instance, most behaviors display their
force if this is true, and pathfollow also displays its target. The
delegates (p. 1773) .lineDisplay, .sphereDisplay, .bboxDisplay, and
.textDisplay are all functions which can be used to draw a graphic primitive
for a particular delegate when the crowd simulation is being solved. Please
see Viewport Drawing Methods for additional viewport drawing methods.
<finalSet> whether or not this is the final time this behavior will be
called during the current frame.
 Scripted_Behavior : MAXObject 1805

Note:
In order to handle constraints working correctly within the avoidance system the constraint
behavior may be called more than once per frame. When the passed in parameter, finalSet, is true,
it will be the last time the constraint function is called for that frame.
Currently the constraint behavior’s “on constraint” event handler is called twice per frame. The first
call occurs before an existing Avoid_Behavior with the passed in parameter finalSet having a value
of false. The second call occurs, after the delegate’s limits and Avoid_Behavior are applied with the
passed in parameter finalSet having a value of true. This evaluation order is done so that the
delegate’s limits and the Avoid_Behavior can affect the changes that the constraint performs. The
second call is made to make sure that the constraint is still being met.
One reason to check the state of finalSet is if internally something was cached and you didn’t want
it to change. For example, the Surface_Follow constraint behavior keeps track of which triangle it’s
on and the barycentric coordinates of where it’s at. The simulation will not change these values until
finalSet is true.
<velocity> the current velocity of the delegate at this frame.
<speed> the current speed of the delegate at this frame.
<pos> the current position of the delegate at this frame.

Note:
After the last delegate’s “on constraint” has executed for the last frame of the simulation, “on
setupDelegates delegates behavior do” will be called with an empty array “#()
ReferenceTarget:Scripted_Behavior”. This is guarenteed and can be used by written constraint
behaviors to clear out any internal caches.
The event handler should return an array of the following type:
#(<int_flags>, <point3_velocity>, <point3_pos>, <point3_goal>,
<float_speed>)

<int_flags> sum of any of the following values:

0 – the return value is not used by the crowd system
1 – the return value is used by the crowd system

<point3_velocity> the velocity.

<point3_pos> the modified current position that is used to calculate it’s
new position. In order to meet a constraint this behavior is allowed to
modify the current position of a delegate.
<point3_goal> the goal position in world space.
<float_speed> the net speed of the delegate. This value should be
normalized to the average speed of the delegate.

on orient <delegate> <behavior> <time> <velocity> do <expr>

1806 Chapter 21 | character studio 3 MAXScript Extensions

If the behavior type, <Scripted_Behavior>.type, is Orientation, this handler is called

every frame. This handler is always called in conjunction with the applyForce handler.
<delegate> the delegate node the behavior is assigned to
<behavior> the current behavior
<time> current time of the simulation
<velocity> the current velocity of the delegate at this frame.

The event handler should return an array of the following type:

#(<int_flags>, quat_orientation)

<int_flags> sum of any of the following values:

0 – the return value is not used by the crowd system
1 – the return value is used by the crowd system

<quat_orientation> the orientation of the delegate in quaternions.

Notes:
The purpose of passing the crowd delegate and behavior to all of the event handlers is that you can
call persisted global, saved with scene, MAXScript functions that work for more than one crowd
simulation.
Example:
The following is a pair of scripted behaviors called “FormationConstraint” and
“FormationOrientation”.
The “FormationOrientation” will constrain the orientation to a fixed location, in this case based on
the current delegate’s orientation found at its first rotation keyframe. The entire scripted orientation
behavior can be implemented with one event handler:
on orient delegate behavior time vel do
(
#(1,delegate.rotation.keys[1].value as quat )
)

The “FormationConstraint” keeps a team of delegates in a given positional formation while

maintaining the pace and direction of a designated leader named “FormationLeader”. This is
similar to a drum major and a marching band or like football blockers running in front of a
running back who may dart in any direction. This person dictates how and where the formation
will move. This “FormationLeader” is not using the scripted behavior.
This behavior will affect both the position and orientation of the delegate. The orientation is
being calculated by the delegate’s velocity, and the velocity is being set correctly.
on execute do ( print “ executed” )
on constraint delegate behavior time numsubsamples displayHelpers finalSet vel
speed pos do
(
leader_velocity = delegates.velocity $TheFormationLeader
Normalized_Leader_Velocity = normalize (delegates.velocity
$TheFormationLeader)
 Seek_Behavior : MAXObject 1807

magVel = speed* Normalized_Leader_Velocity

temp_dis = (pos + leader_velocity) – magVel
the_goal = temp_dis + magVel

if displayHelpers == true then

(
delegates.textDisplay delegate the_goal delegate.wirecolor
delegate.name
delegates.lineDisplay delegate pos (pos+leader_velocity)
delegate.wirecolor true
delegates.sphereDisplay delegate (pos+ (leader_velocity *
$Crowd01.vectorScale)) 4 delegate.wirecolor
)
#(1, Normalized_Leader_Velocity, temp_dis, the_goal, speed)
)

See Also
Delegate:Helper (p. 1773)
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
value_common_properties_operators_and_methods

Seek_Behavior : MAXObject
Constructor:
Seek_Behavior ...
SeekBehavior ...

Properties:
<seek_behavior>.name String Default: “Seek”

<seek_behavior>.targets ArrayParameter Default: #() -- node array

See Notes below.
Specify the object or objects as a stationary or moving target for delegates. Delegates move
toward the target during the crowd simulation while turning as necessary.
<seek_behavior>.targetComp Integer Default: 0
0 – Closest Source Only: Each delegate seeks the closest of the assigned targets. Use this to
have delegates assigned a single Seek behavior move in different directions.
1 – Average of Sources: All delegates head to a common point determined by averaging all
targets’ locations.
1808 Chapter 21 | character studio 3 MAXScript Extensions

<seek_behavior>.seekMethod Integer Default: 0 -- animatable

0 – Angle: Applies a force to the delegate based on the angle between the delegate’s current
direction and the direction it would need to take in order to be moving directly towards
the goal. If the Weight of the Seek behavior is 1, the delegate will be given a force that
points directly towards the goal. If it’s .5 it will bisect the angle between its current
direction and the direction of the goal.
1 – Force: Applies a force in the direction of the goal always, but at different magnitudes. If
the Weight of the Seek behavior is 1, the magnitude of the force will be the average speed.
If the Weight of the Seek behavior is .5, the magnitude of the force will be half the average
speed.
<seek_behavior>.forceColor Color Default: (color 0 255 0)
The color used to draw the Seek force vector during the solution.
<seek_behavior>.displayForce Boolean Default: True
When true, force exerted on the delegate(s) by the Seek behavior is drawn in the viewports
as a vector during the simulation solution.
<Seek_Behavior>.useRadii Boolean Default: False
When true, the Seek behavior applies only to delegates less than the Outer Radius distance
from the target.
<Seek_Behavior>.showRadii Boolean Default: True
When true, the radii are displayed when the force is active.
<Seek_Behavior>.innerRadius Float Default: 0.0 -- animatable
The distance from the target at which Seek is applied at full strength.
<Seek_Behavior>.outerRadius Float Default: 10.0 -- animatable
The distance from the target at which Seek begins to be applied.
<Seek_Behavior>.falloff Float Default: 2.0 -- animatable

Notes:
You can perform the following MAXScript operations:
deleteitem <array> <itemnumber>
<array> = #(item,item...)
<array> = append <array> <item>
on all of the properties containing an ArrayParamater of objects listed below. You can also
undo/redo these operations.
<Seek_Behavior>.targets

The following MAXScript operations will cause Crowd to fail, either right away or later:
NEVER set a Crowd/Behavior ArrayParameter element to undefined.
 Space_Warp_Behavior: MAXObject 1809

See Also
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Space_Warp_Behavior: MAXObject
Constructor:
Space_Warp_Behavior ...
WSMBehavior ...

Properties:
<space_warp_behavior>.name String Default: “Space Warp”
<space_warp_behavior>.spaceWarp Node Default: Undefined

<space_warp_behavior>.forceColor Color Default: (color 255 255 0)

The color used to draw the Space Warp force vector during the solution.
<space_warp_behavior>.displayForce Boolean Default: True
When true, force exerted on the delegate(s) by the Space Warp behavior is drawn in the
viewports as a vector during the simulation solution.

See also
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Speed_Vary_Behavior : MAXObject
Constructor:
Speed_Vary_Behavior ...
SpeedVaryBehavior ...

Properties:
<speed_vary_behavior>.name String Default: “Speed Vary”

<speed_vary_behavior>.period Integer Default: 10 -- animatable

Specifies how many frames should elapse before a new speed is chosen.
1810 Chapter 21 | character studio 3 MAXScript Extensions

<speed_vary_behavior>.period_deviation Float Default: 0.5 -- animatable;

Alias: Period_Deviation
Specifies the maximum amount by which Period should vary. Each time a period ends,
character studio takes a random number between the negative and positive values of the
Deviation setting, multiplies it by the Period setting, and adds the result to Period.
Range=0.0 to 1.0.
<speed_vary_behavior>.center_speed Float Default: 1.0 -- animatable;
Alias: Center_Speed
Specifies the speed the delegate should change to. Center is a multiplier: A value of 0.0
means to stop, a value of 1.0 means to move at its average speed, and a value greater than
1.0 means to move faster than its average speed. Range=0.0 to 99,999.0.
<speed_vary_behavior>.speed_deviation Float Default: 0.25 -- animatable;
Alias: Speed_Deviation
Specifies the maximum amount by which the delegate’s calculated speed (Average
Speed*Center) should vary. Each time a period ends, character studio takes a random
number between the negative and positive values of the Deviation setting, multiplies it by
the calculated speed, and adds the result to the calculated speed. Range=0.0 to 99,999.0.
<speed_vary_behavior>.seed Integer Default: 1 -- animatable;
Alias: Speed_Vary_Seed
Specifies a seed value for randomizing the Wander behavior.
<speed_vary_behavior>.accelPeriod Float Default: 0.5 -- animatable;
Alias: Acceleration_Period
Specifies the rate at which the delegate’s speed should change. An acceleration of 1.0
means that the transition to the new speed will proceed as quickly as possible to its new
speed, while a value of 0.0 means the transition will take the entire period. Range=0.0
to 1.0.
<speed_vary_behavior>.accelDeviation Float Default: 0.5 -- animatable;
Alias: Acceleration_Deviation
Specifies the maximum amount by which the delegate’s calculated speed (Average
Speed*Center) should vary. Each time a period ends, character studio takes a random
number between the negative and positive values of the Deviation setting, multiplies it by
the calculated speed, and adds the result to the calculated speed. Range=0.0 to 99,999.0.

See also
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Surface_Arrive_Behavior : MAXObject 1811

Surface_Arrive_Behavior : MAXObject
Constructor:
Surface_Arrive_Behavior ...
SurfaceArriveBehavior ...

Properties:
<Surface_Arrive_Behavior>.name String Default: “Surface Arrive”

<Surface_Arrive_Behavior>.surfaces ArrayParameter Default: #() -- node

array
See Notes below
<Surface_Arrive_Behavior>.disableAfterArriving Boolean Default: True
When true, turns off the Surface Arrive behavior after the delegate arrives at the surface.
<Surface_Arrive_Behavior>.rate Float Default: 0.5 --
animatable
A multiple of the delegate’s Max Accel setting that specifies the acceleration with which it
will try to arrive. A value of 1.0 uses the full acceleration of the delegate.
<Surface_Arrive_Behavior>.rateDeviation Float Default: 0.0 --
animatable
Adds a variation to the to the rate setting.
<Surface_Arrive_Behavior>.speed Float Default: 0.0 --
animatable
The speed at which to arrive and relative to the speed of the target.
<Surface_Arrive_Behavior>.speedDeviation Float Default: 0.0 --
animatable
Adds a variation to the to the speed setting.
<Surface_Arrive_Behavior>.distance Float Default: 1e+008 --
animatable
The maximum radial distance from the target within which the behavior will be active.
Until the delegate is within this radius, the behavior will have no influence.
<Surface_Arrive_Behavior>.distanceDeviation Float Default: 0.0 --
animatable
Adds a variation to the to the distance setting.
<Surface_Arrive_Behavior>.offset Float Default: 0.0 --
animatable
Specifies a consistent distance from the calculated arrival point, based on the surface
normal, for the delegate to use.
<Surface_Arrive_Behavior>.facing Boolean Default: False --
animatable
When true, the delegate will try to arrive only at points on triangles on the surface that are
facing it.
1812 Chapter 21 | character studio 3 MAXScript Extensions

<Surface_Arrive_Behavior>.random_closest Integer Default: 0

0 – Random: The software chooses a random point on the target surface as the
arrival point.
1 – Closest: The software chooses the closest point on the target surface as the
arrival point.
<Surface_Arrive_Behavior>.everyFrame Boolean Default: False --
animatable
When true, the software chooses arrival points for delegates at every frame. Available only
when Closest is chosen.
<Surface_Arrive_Behavior>.displayOffset Boolean Default: False
When true, shows the Offset distance as lines emanating from each vertex in the surface
object, perpendicular to the surface.
<Surface_Arrive_Behavior>.height Float Default: 0.0 --
animatable
Specifies a distance from the arrival point along its face normal. This is the point that the
delegate will go to first before descending to the arrival point.
<Surface_Arrive_Behavior>.heightDeviation Float Default: 0.0 --
animatable
Adds random variation to the to the Height setting. See introduction for the formula used
to calculate the deviation.
<Surface_Arrive_Behavior>.descentStart Float Default: 0.0 --
animatable
Specifies the distance between the delegate and the arrival point at which the descent
should start.
Note:
Be careful that Descent Start is set high enough that the delegate won’t overshoot when descending
because its speed is too high and deceleration too low, compared to when it should start descending.
<Surface_Arrive_Behavior>.descentstartDeviation Float Default: 0.0 --
animatable
Adds a variation to the to the Descent Start setting.
<Surface_Arrive_Behavior>.useNormal Boolean Default: False Alias:
Off_This_Normal
When true, use vector specified in the .xNormal, .yNormal, and .zNormal to specify the
angle at which the final approach occurs.
<Surface_Arrive_Behavior>.xNormal Float Default: 0.0 --
animatable; Alias: X_Normal
Specify the final approach X value for the vector in world coordinates.
<Surface_Arrive_Behavior>.yNormal Float Default: 0.0 --
animatable; Alias: Y_Normal
Specify the final approach Y value for the vector in world coordinates.
<Surface_Arrive_Behavior>.zNormal Float Default: 1.0 --
animatable; Alias: Z_Normal
Specify the final approach Z value for the vector in world coordinates.
 Surface_Arrive_Behavior : MAXObject 1813

<Surface_Arrive_Behavior>.seed Integer Default: 1 --

animatable
Affects the random numbers used to calculate the Deviation settings.
<Surface_Arrive_Behavior>.targetColor Color Default: (color 0 0 127.5)
The color used to draw the target icon.
<Surface_Arrive_Behavior>.displayTarget Boolean Default: True
When true, displays the target icon which appears during the solution when a new interim
goal is calculated for the delegate.
<Surface_Arrive_Behavior>.targetScale Float Default: 5.0 --
animatable
Specifies the overall size of the target icon.
Methods:
SurfaceArriveBhvr.Getstate <Surface_Arrive_Behavior> <delegate_node>
Returns an integer value giving the state the delegate is in with respect to the
Surface_Arrive_Behavior. A return value of -1 means that the delegate isn’t active for that
state, 0 means that the delegate is outside the distance radius and so isn’t arriving, 1 means
that the delegate is in the process of arriving, and 2 means that the delegate has arrived. If
‘Disable After Arriving’ is TRUE, the delegates will never reach state 2.
The main purpose of this funtion is so that the ‘State’ of a delegate as it arrives to a surface
can be determined from MAXScript. It can be used for both the cognitive controller
transitions as well as the script definable in MotionClips. See the ClipState Dialog and the
Cognitive Controller topics in the character studio 3 online reference for more details.
Track View > Global Tracks > Block Control > GlobalClip Properties > Synthesis
dialog > State Tab > New State > Edit Properties > ClipState dialog

Select a Crowd helper. > Modify panel > Global Clip Controllers rollout > New >
Choose GlobalClip object. > Select object in list. > Edit > Synthesis dialog >
State Tab > New State > Edit Properties > Clip State dialog

Create panel > Helpers > Object Type rollout > Crowd > Setup rollout > Cognitive
Controllers

Select a Crowd object. > Modify panel > Setup rollout > Cognitive Controllers

SurfaceArriveBhvr.getPos <Surface_Arrive_Behavior> <delegate_node>

Returns a Point3 value of the position that the delegate is arriving to at the time the
function is called.
1814 Chapter 21 | character studio 3 MAXScript Extensions

Notes:
You can perform the following MAXScript operations:
deleteitem <array> <itemnumber>
<array> = #(item,item...)
<array> = append <array> <item>
on all of the properties containing an ArrayParamater of objects listed below. You can also
undo/redo these operations.
<Surface_Arrive_Behavior>.surfaces

The following MAXScript operations will cause Crowd to fail, either right away or later:
NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See Also
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Surface_Follow_Behavior : MAXObject
Constructor:
Surface_Follow_Behavior ...
SurfaceFollowBehavior ...

Properties:
<Surface_Follow_Behavior>.name String Default: “Surface Follow”

<Surface_Follow_Behavior>.surfaces ArrayParameter Default: #() -- node array

See Notes below.
<Surface_Follow_Behavior>.useProjection Bolean Default: False
When true, Surface Follow calculates delegate direction from the specified vector, rather
than using the default.
<Surface_Follow_Behavior>.xVector Float Default: 0.0 -- animatable
Specifies the x component of a vector using world coordinates. . Range=-1.0 to 1.0.
<Surface_Follow_Behavior>.yVector Float Default: 0.0 -- animatable
Specifies the y component of a vector using world coordinates. . Range=-1.0 to 1.0.
<Surface_Follow_Behavior>.zVector Float Default: 1.0 -- animatable
Specifies the z component of a vector using world coordinates. . Range=-1.0 to 1.0.
<space_warp_behavior>.targetColor Color Default: (color 0 0 127.5)
Sets the color used to draw the Surface Follow during the solution.
<space_warp_behavior>.displayTarget Boolean Default: True
When true, the interim goal for each delegate influenced by the Surface Follow behavior is
drawn in the viewports as a wireframe sphere during the simulation solution.
 Surface_Follow_Behavior : MAXObject 1815

Notes:
If the delegate starts out away from the surface to be followed then the target is most visible before
the delegate reaches the surface where the target is positioned along the surface edge.
While the delegate is actually following the surface, the target is usually coincident with the delegate
because Surface follow sets a new destination only a frame or two ahead.
<space_warp_behavior>.targetScale Float Default: 5.0
Specifies the overall size of the target icon.
<Surface_Follow_Behavior>.offset Float Default: 0.0 -- animatable
Specifies the delegate’s distance above the surface, using the surface normal.
<Surface_Follow_Behavior>.displayOffset Boolean Default: False
When true, shows the .offset distance as lines emanating from each vertex in the surface
object, perpendicular to the surface.
Notes:
You can perform the following MAXScript operations:
deleteitem <array> <itemnumber>
<array> = #(item,item...)
<array> = append <array> <item>
on all of the properties containing an ArrayParamater of objects listed below. You can also
undo/redo these operations.
<Surface_Follow_Behavior>.surfaces

The following MAXScript operations will cause Crowd to fail, either right away or later:
NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See also
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
1816 Chapter 21 | character studio 3 MAXScript Extensions

Wall_Repel_Behavior : MAXObject
Constructor:
Wall_Repel_Behavior ...
WallRepelBehavior ...

Properties:
<Wall_Repel_Behavior>.name String Default: “Wall Repel”
<Wall_Repel_Behavior>.repelGrids ArrayParameter Default: #() -- node array
Set the repelling grid.
<Wall_Repel_Behavior>.repelMethod Integer Default: 0 -- animatable
Determines whether delegate direction as influenced by the behavior is calculated by an
angular method or a force method.
0 – Angle: Applies a force to the delegate based on the angle between the delegate’s current
direction and the direction it would need to take in order to be moving directly away from
the source. If the behavior’s Weight is set to 1 the delegate will be given a force that points
directly away from the source. If Weight is set to .5, the force will bisect the angle between
its current direction and the direction opposite that of the source.
1 – Force: Always applies a force directly away from the source, but at different
magnitudes. If the behavior’s Weight is 1, the magnitude of the force will be the average
speed. If the Weight is .5, the magnitude of the force will be half the average speed.
<Wall_Repel_Behavior>.repelDirection Integer Default: 0 -- animatable
Determines whether the grid repels from its positive-axis side, its negative-axis side,
or both.
0 – Positive Axis: The grid repels only from the positive-axis side.
1 – Negative Axis: The grid repels only from the negative-axis side.
2 – Both Axes: The grid repels from both sides.
<Wall_Repel_Behavior>.useDistance Boolean Default: True
When true, the behavior applies only to delegates closer to the target than the
outerRadius value.
<Wall_Repel_Behavior>.innerDistance Float Default: 0.0 -- animatable
The distance from the target at which the force is applied at full strength.
<Wall_Repel_Behavior>.outerDistance Float Default: 10.0 -- animatable
The distance from the target at which the force begins to be applied.
<Wall_Repel_Behavior>.falloff Float Default: 2.0 -- animatable

<Wall_Repel_Behavior>.showDistance Boolean Default: True

Shows the inner and outer distance settings as grids offset from the target grid in the
viewports. The .innerDistance grid is light blue, while .outerDistance grid is
blue-white.
 Wall_Seek_Behavior : MAXObject 1817

<Wall_Repel_Behavior>.gridSpacing Integer Default: 500

Specifies the spacing of grid lines used to draw the Inner/Outer Distance grids. The lower
the value, the closer the spacing.
<Wall_Repel_Behavior>.gridEnd Boolean Default: True Alias:
End_force_at_grid_edges
When true, the force emanates only from the grid object. When off, the force emanates
from an imaginary infinite grid created by extending the grid plane in all directions.
<Wall_Repel_Behavior>.forceColor Color Default: (color 255 0 255)
Sets the color used to draw the Wall Repel force during the solution.
<Wall_Repel_Behavior>.displayForce Boolean Default: True
The force, when activated, is drawn in the viewports as a wireframe rectangle during the
simulation solution.

See also
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

Wall_Seek_Behavior : MAXObject
Constructor:
Wall_Seek_Behavior ...
WallSeekBehavior ...

Properties:
<Wall_Seek_Behavior>.name String Default: “Wall Seek”

<Wall_Seek_Behavior>.seekGrids ArrayParameter Default: #() -- node array

Set the repelling grid.
<Wall_Seek_Behavior>.seekMethod Integer Default: 0 -- animatable
Determines whether delegate direction as influenced by the behavior is calculated by an
angular method or a force method.
0 – Angle: Applies a force to the delegate based on the angle between the delegate’s current
direction and the direction it would need to take in order to be moving directly toward the
target. If the behavior’s Weight is set to 1, the delegate will be given a force that points
directly away from the target. If Weight is set to .5, the force will bisect the angle between
its current direction and the direction opposite that of the target.
1 – Force: Always applies a force directly toward the target. If the behavior’s Weight is 1,
the magnitude of the force will be the average speed. If the Weight is .5, the magnitude of
the force will be half the average speed.
1818 Chapter 21 | character studio 3 MAXScript Extensions

<Wall_Seek_Behavior>.seekDirection Integer Default: 0 -- animatable

Determines whether the grid attracts from its positive-axis side, its negative-axis side,
or both.
0 – Positive Axis: The grid attracts only from the positive-axis side.
1 – Negative Axis: The grid attracts only from the negative-axis side.
2 – Both Axes: The grid attracts from both sides.
<Wall_Seek_Behavior>.useDistance Boolean Default: True
When true, the behavior applies only to delegates closer to the target than the Outer
Distance value.
<Wall_Seek_Behavior>.innerDistance Float Default: 0.0 -- animatable
The distance from the target at which the force is applied at full strength.
<Wall_Seek_Behavior>.outerDistance Float Default: 10.0 -- animatable
The distance from the target at which the force begins to be applied.
<Wall_Seek_Behavior>.falloff Float Default: 2.0 -- animatable

<Wall_Seek_Behavior>.showDistance Boolean Default: True

<Wall_Seek_Behavior>.gridSpacing Integer Default: 500

<Wall_Seek_Behavior>.gridEnd Boolean Default: True Alias:

End_force_at_grid_edges
When true, the force emanates only from the grid object. When off, the force emanates
from an imaginary infinite grid created by extending the grid plane in all directions.
<Wall_Seek_Behavior>.forceColor Color Default: (color 255 0 255)
Sets the color used to draw the Seek force vector during the solution.
<Wall_Seek_Behavior>.displayForce Boolean Default: True
When true, force exerted on the delegate(s) by the Seek behavior is drawn in the viewports
as a vector during the simulation solution. If useRadii is turned on, the radii are also
displayed when the force is active.

See also
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
 Wander_Behavior : MAXObject 1819

Wander_Behavior : MAXObject
Constructor:
Wander_Behavior ...
WanderBehavior ...

Properties:
<wander_behavior>.name String Default: “Wander”

<wander_behavior>.period Integer Default: 10 -- animatable;

Alias: Wander_Period
Specifies how many frames should elapse before a new direction is chosen.
<wander_behavior>.periodDeviation Float Default: 0.5 -- animatable;
Alias: Wander_Period_Deviation
Specifies the maximum amount by which Period should vary. Each time a period ends,
character studio takes a random number between the negative and positive values of the
Deviation setting, multiplies it by the Period setting, and adds the result to Period.
Range=0.0 to 1.0.
<wander_behavior>.turnAngle Float Default: 0.5 -- animatable
Specifies how far to turn when changing direction. A small value means to change
direction only by a small amount, while as the value approaches 1.0 it will randomly turn
in any direction. Range=0.5 to 1.0.
<wander_behavior>.turnPeriod Float Default: 0.5 -- animatable
Specifies how long over the current period it takes to turn. A value of 0.0 means that it will
rotate as quickly as possible to face a direction and then travel in that a direction, while a
value of 1.0 means it will take the entire period to rotate in that direction. Range=0.5
to 1.0.
<wander_behavior>.turnPeriodDeviation Float Default: 0.5 -- animatable
Specifies the maximum amount by which Angle should vary. Each time a period ends,
character studio takes a random number between the negative and positive values of the
Deviation setting, multiplies it by the Angle setting, and adds the result to Angle.
Range=0.0 to 1.0.
<wander_behavior>.seed Integer Default: 1 -- animatable
Specifies a seed value for randomizing the Wander behavior.
<wander_behavior>.forceColor Color Default: (color 0 255 255)
The color used to draw the Wander force vector during the solution.
<wander_behavior>.displayForce Boolean Default: True
When true, force exerted on the delegate(s) by the Wander behavior is drawn in the
viewports as a vector during the simulation solution.
1820 Chapter 21 | character studio 3 MAXScript Extensions

See Also
Crowd : Helper (p. 1771)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)

MotionClips and GlobalMotionClip

globalMotionClipOps const StructDef Struct:
globalMotionClipOps(

globalMotionClipOps.loadfile Primitive loadfile()

‘loadfile’ expects a GlobalMotionClip, then a filename for a “*.ant” GlobalMotionClip file
to load.
globalMotionClipOps.savefile Primitive savefile()
‘savefile’ expects a GlobalMotionClip, then a filename for the “*.ant” file to save.
globalMotionClipOps.synthesize Primitive synthesize()
‘synthesize’ expects a GlobalMotionClip and will synthesize it.
Note that the GlobalMotionClip objects are found under the GlobalTracks.Block_Control list
controller.
So to call savefile, one would call:
GlobalMotionClipOps.savefile
GlobalTracks.Block_Control.globalMotionClip__globalObject “globalObject.ant”‘
The following classes exist but are not supported.
MotionClipSlaveRotation : RotationController {4306d06,97c6025}
MotionClip : FloatController {e937ded,5a002ad2}
MotionClipSlavePos : PositionController {18c22740,522802b9}
ClipAssignerReferenceTarget : ReferenceTarget {2cb93ce2,33825f4}
MotionClipSlaveFloat : FloatController {31822cdf,34c146b}
Global_MotionClip : MasterBlockController {37d25755,278c6957}
ClipState : ReferenceTarget {455d5a81,3dcb1dc2}
ClipAssigner : ReferenceTarget {49f14ffa,33801afd}
MasterMotionClip : MasterBlockController {532a2038,6acd39bf}
MotionClipSlave_Point3 : Point3Controller {6c95514a,801b4f}
MotionClipSlaveScale : ScaleController {71031345,770b4347}
MotionClipFloatController : FloatController {7f016988,1f9f0342}
 Vector_Field: SpacewarpObject 1821

SpaceWarps

Vector_Field: SpacewarpObject
Constructor:
Vector_Field ...
VectorField ...

Properties:
<Vector_Field>.Length Float Default: 0.0 -- world units
Specify the length dimension of the vector field lattice. The lattice should be larger than
the vector field object.
<Vector_Field>.Width Float Default: 0.0 -- world units
Specify the width dimension of the vector field lattice. The lattice should be larger than
the vector field object.
<Vector_Field>.Height Float Default: 0.0 -- world units
Specify the height dimension of the vector field lattice. The lattice should be larger than
the vector field object.
<Vector_Field>.LenSegs Integer Default: 1 Alias:
Length_Segments
Specify the resolution of the vector field lattice’s length segments. The greater the
resolution, the higher the accuracy of the simulation.
<Vector_Field>.WidSegs Integer Default: 1 Alias:
Width_Segments
Specify the resolution of the vector field lattice’s width segments. The greater the
resolution, the higher the accuracy of the simulation.
<Vector_Field>.HgtSegs Integer Default: 1 Alias:
Height_Segments
Specify the resolution of the vector field lattice’s height segments. The greater the
resolution, the higher the accuracy of the simulation.
<Vector_Field>.showLattice Boolean Default: True
Set on to display the vector field lattice as a yellow wireframe box. The vectors are
generated at lattice intersections inside the vector field range.
<Vector_Field>.showRange Boolean Default: True
Set on to display the volume about the obstacle object within which vectors are generated
as an olive-colored wireframe.
<Vector_Field>.showVectors Boolean Default: False
Set on to display vectors, which appear as blue lines emanating outward from the lattice
intersections within the range volume.
<Vector_Field>.showSurfSamps Boolean Default: False
Set on to display short green lines emanating from sample points on the surface of the
obstacle object.
1822 Chapter 21 | character studio 3 MAXScript Extensions

<Vector_Field>.vecScale Float Default: 1.0 -- world units

Scales the vectors so they’re more visible or less obtrusive. This setting does not affect the
strength of the vectors only their visibility.
<Vector_Field>.iconSize Float Default: 0.0 -- world units
Adjusts the size of the Vector Field space warp icon. The icon is a pair of crossed double-
headed arrows. Increase the size for easier viewport selection.
<Vector_Field>.strength Float Default: 1.0 -- animatable;
world units
Sets the degree of effect the vectors have on the movement of an object entering the vector
field. Changing Strength does not require that you recalculate the vector field.
<Vector_Field>.falloff Float Default: 2.0 --
animatable; world units
Determines the rate at which the strength of the vectors falls off with distance from the
surface of the object. A value of 0 will make all the vectors the same size. A value greater
than 0 will make them get smaller as they get further away. A value less then 0 will make
them get larger as they get further away.
<Vector_Field>.direction Integer Default: 1 -- animatabl
Sets whether the force generated by the vectors works parallel or perpendicular to the
vector field. Because the vectors are perpendicular to the object surface, and you typically
would want delegates to travel parallel to the surface, you would normally use a
perpendicular force.
0 – Parallel
1 – Perpendicular
<Vector_Field>.pull Float Default: 0.0 --
animatable; world units
Adjusts objects’ position relative to the field. Available only when Perpendicular is chosen.
Range=-1.0 to 1.0. Objects moving perpendicular to a vector field sometimes tend to drift
away from it, due to lack of subsampling. The Pull parameter helps to pull objects back.
Pull values greater than 0 create a pulling force towards the source of the vector field
vector. Values less than 0 pull the force towards the direction in which the vector field’s
vector is pointing. A value of 0.0 produces a force perfectly perpendicular to the vector
field’s vector.
<Vector_Field>.object Node Default: Undefined Alias:
Vector_Field_Object
The obstacle object around which the vector field is to be generated. Only primitives and
unmodified editable mesh objects can be used as obstacles. The object should be fully
enclosed in the Vector Field lattice.
<Vector_Field>.range Float Default: 1.0 -- world units
Determines the volume within which vectors are generated. The Range is represented in
viewports as an olive-colored wireframe that starts out the same size and shape as the
obstacle object. Increasing the Range setting moves the wireframe away from the obstacle
object in the direction of its surface normals.
 Vector_Field: SpacewarpObject 1823

Notes:
In crowd simulations, the Range outline is where the delegates start to “see” the obstacle object, and
begin to turn to avoid it. If your crowd members are penetrating the obstacle, or even just coming
too close to it before turning, increase the Range setting. Also try increasing the Vector Field lattice
resolution and/or the Sample Res setting.
<Vector_Field>.resolution Integer Default: 1
Acts as a multiplier of the effective sampling rate used on the obstacle object’s surface to
calculate vector directions in the field. The basic sampling rate is determined by the
program from the size of the lattice and the size of each polygon.
<Vector_Field>.flipFaces Boolean Default: False
Setting to true causes flipped normals to be used during the computation of the vector
field. By default, vectors are generated in the same direction as the obstacle object’s face
normals, so that assuming its face normals point outward, objects move around its exterior
in a crowd simulation. However, if you want objects to remain within an object’s interior,
turn on flipFaces.
<Vector_Field>.blendStart Float Default: 0.0 -- world units
The distance from the object at which blending the vectors starts.
<Vector_Field>.blendFalloff Float Default: 2.0 -- world units
The falloff of the blend of the surrounding vectors.
<Vector_Field>.blendWidSegs Integer Default: 1
The number of adjacent lattice points to blend on the X axis.
<Vector_Field>.blendLenSegs Integer Default: 1
The number of adjacent lattice points to blend on the Y axis.
<Vector_Field>.blendHgtSegs Integer Default: 1
The number of adjacent lattice points to blend on the Z axis.
Methods:
vfields.computeVectors <Vector_Field>
Calculates the vector field using the current Vector Field parameters. Always recalculate
the vector field after changing any of the non-display related parameters.
vfields.BlendVectors <Vector_Field>
Blends the vectors for reducing abrupt changes in angles of neighboring vectors.
Associated Methods:
bindSpaceWarp <node> <Vector_Field_node>

Associated Binding Modifier:

Vector_Field_Mod
This modifier is automatically created by the bindSpaceWarp() (p. 820)method, and is not
otherwise creatable by MAXScript. There are no properties associated with this binding
modifier.
1824 Chapter 21 | character studio 3 MAXScript Extensions

See Also
Node Common Properties, Operators, and Methods (p. 820)
MAXWrapper Common Properties, Operators, and Methods (p. 809)
Value Common Properties, Operators, and Methods (p. 714)
Chapter 22: CS3Tools.cui Tutorial

The CS3Tools Custom User Interface implements several very useful tools. This tutorial will
concentrate on the Custom Keys Utility, a custom keys mechanism that gives one-touch access to 6
key frame settings that you use most when animating a Biped. The Custom Keys Utility uses 13 icon
buttons. The first 6 are “Set custom Biped Keys”. The next 6 are “Change Preset to current key”. The
following one is “Launch Preset Floater”.
Once you have stored your favorite custom keys, animation workflow is greatly improved, since you
spend little or no time tuning default key frame attributes that don’t fit your current character’s
situation or style. Simply pose your character and click on the custom key icon that fits your current
situation.

Overview
Custom Keys are implemented via a new dedicated 3ds max Tool Bar, called character studio Tool.
This tool bar is the home base for a growing number of MAXScript-enabled character studio
commands. All operations associated with Tool Bars are available. For example, individual icons can
be relocated, deleted, and renamed. Tool tips can also be customized, as implied above, to let you
annotate each custom key type for rapid recall. Custom Keys are displayed on the character studio
Tool Bar as color-coded “set key” icons, similar to the standard Biped red set key icon in the Biped
Motion panel. Each color indicates a specific custom key type. There are two icons for each key type
– one for setting a key, and second for storing the preset value, based on the currently selected track
and key. The second icon – used for storing the preset values – displays a small black arrow pointing
to the center of the icon – indicating that a value will be stored. Once you have set your keys as you
like them, you may choose to delete the storage icons entirely, to save space. You can also float or
re-dock the Custom Key icons to customize access to suit your style and needs. Additionally, you can
launch a floating rollout of the same set of custom keys.
To use Custom Keys, simply set a Biped key as you normally would using the Biped Motion Panel
and set its Key Info settings as you prefer. Next store that key for the currently selected track at the
current frame into one of the six preset custom key icons using the set key icons with the black
arrows.
1826 Chapter 22 | CS3Tools.cui Tutorial

Launching the CS3CustomKeys User Interface

The file named CS3Tools.cui is found in the 3ds max UI directory.
Choose Customize -> Load Custom UI…-> CS3Tools.cui
The user interface is displayed on the left side of the screen made with bitmapped buttons icons. You
can also build a Tab Panel from scratch and manually add these icons by selecting from the
character studio Tool category of the Customize UI Dialog.
See help page Macro Scripts (p. 1624) in the “Interacting with the 3ds max User Interface” topic and
Defining Macro Scripts (p. 1521) in the “Creating MAXScript Tools” topic for additional details
regarding Macro Scripts.
 1827

The icon buttons of CS3Tools.cui are displayed in the above image.

The bitmaps for the custom ui are installed into the 3ds max UI directory. See the Creating Icon
Bitmap Files (p. 1530) topic for more information on creating and customizing icon bitmaps.
For access to Custom User Interface (CUI) files via MAXScript, see the help page Custom User Interface
Files (p. 1648) in the “File Access”. Note that the *.cui file format specification is not currently
provided.

File Details
character studio 3 ships with the following character studio Tool files:
..\ui\CS3Tools.cui
..\Scripts\Startup\CS3Customkeys.ms
..\Scripts\Startup\CS3CustomKeys-presets.ini
..\Scripts\Startup\CS3convertBips.ms
..\Scripts\Startup\CS3Bip2BonesFloater.ms
..\Stdplugs\stdscripts\CS3CustomKeysPresetFloater.ms
Tutorial_Filename_CS3CustomKeysPresetFloater_ms bitmap files:
\3ds3.1\Cstudio\ui\Cstudio_16a.bmp, Cstudio_16i.bmp, Cstudio_24a.bmp, and
Cstudio_24i.bmp.

Design Details
Custom Keys operate similar to channel buttons on a car radio. Anytime you “dial in” a set of
parameters for a particular Biped key using the standard Biped “Key Info” rollout, you can store
those values in one of the 6 custom key buttons available, by clicking on the associated tool bar icon.
All of the standard Biped Key Info parameters are supported, including: ease to, ease from, tension,
continuity, bias, IK Blend value, IK body/space setting, and pivot point information. This can be
seen by reviewing the struct Biped_key defined in ..\Scripts\Startup\CS3Customkeys.ms.
Custom Keys do not store transformation information (like a pose). Only Key Info attributes that
affect the interpolation of a Biped’s motion are stored. This allows stylistic settings to be easily
transferred from frame to frame and even from Biped to Biped.
Each Custom Key is stored in a structure (p. 707) with the name Biped_key. Here is the definition
of Biped_key:
struct Biped_key (type, ikblend, ikspace, easefrom, easeto, tension,
continuity, bias, ikAnkleTension, balanceFactor, dynamicsBlend,
ballisticTension)

Here is the initial Custom Key definition for the buffer “Preset Key A”. Note that it is global
(p. 646) and therefore visible in all running MAXScript code and will hold its value until
3ds max is exited.
Global keya_buffer = Biped_key type:#body ikblend:0.1 ikspace:1
easefrom:0.0 easeto:0.0 tension:25.0 continuity:0.0 bias:25.0
ikAnkleTension:.8 balanceFactor:1 dynamicsBlend:1 ballisticTension:0.5
1828 Chapter 22 | CS3Tools.cui Tutorial

The CS3Tools.cui has 13 icon buttons. The first 6 are “Set custom Biped Key *”. The next 6 are
“Change Preset * to current key”. The last one is “Launch Preset Floater”.
Pressing the 7th icon, “Change Preset A to current key”, will change the value of the specified
Preset A Key’s keya_buffer to the value of the currently selected key. This will trigger the
execution of the code:
macros.run “character studio Tool” “Change_Preset_Key_A”

The line above will be displayed in the MacroRecorder (p. l) if the MacroRecorder is enabled.
This macro, “Change_Preset_Key_A”, is defined in the file \3ds3.1\ui\macroscripts\character
studio Tool-Change_Preset_Key_A.mcr and contains:
macroScript Change_Preset_Key_A
category:”character studio Tool”
toolTip:”Change Preset A to current key”
Icon:#(”cstudio”,7)
(
keya_buffer = CS3Change_Key_FN keya_buffer
CS3Save_presets()
)

See help page Macro Scripts (p. 1624) in the “Interacting with the 3ds max User Interface” topic
and Defining Macro Scripts (p. 1521) in the “Creating MAXScript Tools” topic for additional
details on creating and using Macro Scripts.
Select the last icon, “Launch Preset Floater”, in the CS3Tools.cui. The Preset Floater dialog is
launched and displayed. There are 6 “Change *” buttons and 6 “Show *” buttons. The 6
“Change *” buttons on the floating rollout perform the same actions as the 6 icon buttons on
the CS Custom Key toolbar.
 1829

Pressing the “Change A” button executes the following code from the file
..\Scripts\Startup\CS3CustomKeys.ms
on ChangeA pressed do
(
keya_buffer = CS3Change_Key_FN keya_buffer
CS3Save_presets()
)
Pressing the “Show A” button will display the current contents of the keya_buffer as seen here:

Note that in both cases of Changing Preset A, the same function “CS3Change_Key_FN“ was
called. Additionally, notice that CS3Save_presets() is called anytime that a preset is changed.
CS3Save_presets() will save all key values to a file called CS3CustomKeys-presets.ini that can be
included in next launch of CS3Customkeys.ms. This is accomplished by Save_presets formating
the presets as valid MAXScript code and using the include statement (p. lix) to include the code
in CS3Customkeys.ms. The included code redefines the global key_buffers already defined.
The file \3ds3.1\Scripts\Startup\CS3Customkeys.ms Tutorial_File_name_CS3Customkeys_ms
contains the following functions:
fn Set_One_Key_FN
fn Set_Key_FN
fn CS3Save_Presets
fn CS3Show_key_FN
fn CS3Change_Key_FN
fn ControllerOf
fn RootOf

The functions Change_Key_FN, Save_Presets and Set_Key_FN will be reviewed in more detail
below.
1830 Chapter 22 | CS3Tools.cui Tutorial

As seen in the above examples of “ChangeA”, the Change_Key_FN function is called with a single
parameter, the particular local_key_buffer, and in the above examples with the keya_buffer. The
local_key_buffer will either be returned unmodified or it will be returned modified.
The values for easeto, easeFrom, tension, continuity, bias, and ikAnkleTension are stored for all valid
keytypes while ikblend and ikspace is stored for only #body keys. For #vertical keys, dynamicsblend
and ballistictension are also stored. For #horizontal, balancefactor is also stored.
See BipedKey:MAXObject (p. 1761) for more details.

The Change_Key_FN Code

The pseudo code for the Change_Key_FN is as follows:
function Change_Key_FN local_key_buffer
if nothing selected return local_key_buffer
if more than one selected return local_key_buffer
if not of class Biped_Object return local_key_buffer
get root node of the biped and controller for this body part
If body part is COM and trackselection not vertical, horizontal or turning
then
print skipped and return local_key_buffer
else
save controller selection
if in figuremode return local_key_buffer
if in motion mode return local_key_buffer
if in footstepmode return local_key_buffer
if save controller selection not undefined then
set my_index to getkeyindex my_controller slidertime
if a key was found then
set my_key to biped.getKey my_controller my_index
if (my_key.type equals #body) then
(
set local_key_buffer.ikblend to my_key.ikblend
set local_key_buffer.ikspace to my_key.ikspace
set local_key_buffer.ikAnkleTensio to my_key.ikAnkleTension
)
if (my_key.type equals #vertical) then
(
set local_key_buffer.dynamicsblend to my_key.dynamicsblend
set local_key_buffer.ballistictension to my_key.ballistictension
)
if (my_key.type equals #horizontal) then
(
set local_key_buffer.balancefactor to my_key.balancefactor
)
set local_key_buffer.easefrom to my_key.easeto
set local_key_buffer.easeto to my_key.easefrom
set local_key_buffer.tension to my_key.tension
set local_key_buffer.continuity to my_key.continuity
set local_key_buffer.bias to my_key.bias
set return modified local_key_buffer
 1831

else
return local_key_buffer
else
return local_key_buffer

The actual function can be seen here:

FN CS3Change_Key_FN local_key_buffer =
(
if ($selection.count (p. 781) == 0 ) then
(
messagebox “No object selected.\nPlease select a Biped Object first.\n”
return local_key_buffer
)

if ($selection.count (p. 781) > 1) then

(
messagebox “There are multiple objects selected.\nPlease select a single
Biped Object first.”
return local_key_buffer
)
if ((classof $ (p. 820)) != Biped_Object) then
(
messagebox “The selected object is not a Biped Object.\n Please select a
Biped Object first\n.”
return local_key_buffer
)

my_root = $.controller.rootnode
my_controller = $.controller

if (my_root == $) then -- user is working on COM

(
if (my_controller.trackselection (p. 1736) == 2) then
(
my_controller = my_controller.vertical.controller (p. 1736)
)

else if (my_controller.trackselection (p. 1736) ==1) then

(
my_controller = my_controller.horizontal.controller (p. 1736)
)

else if (my_controller.trackselection (p. 1736) == 3) then

(
my_controller = my_controller.turning.controller (p. 1736)
)

else
(
msgtext = “‘” + $.name + “‘ skipped.\n”
messagebox msgtext
1832 Chapter 22 | CS3Tools.cui Tutorial

return local_key_buffer
)
)
if (my_root.transform.controller.figuremode (p. 1736) == true) then
(
messagebox “Change Preset Key is not supported in Figure Mode.\n Please
exit Figure Mode first.\n”
return local_key_buffer
)

if (my_root.transform.controller.motionmode (p. 1736) == true) then

(
messagebox “Change Preset Key is not supported in Motion Flow Mode.\n
Please exit Motion Flow Mode first.\n”
return local_key_buffer
)

if (my_root.transform.controller.footstepmode (p. 1736) == true) then

(
messagebox “Change Preset Key is not supported in Footstep Mode.\n Please
exit Footstep Mode first.\n”
return local_key_buffer
)

if (my_controller != undefined) then

(
-- format “Controller: %\n” my_controller

my_index = getkeyindex (p. 1294) my_controller slidertime (p. 1580)

-- format “Key Index = %\n” my_index
if (my_index>0) then
(
my_key = biped.getKey (p. 1761) my_controller my_index

-- format “key type is % \n” my_key.type

if (my_key.type == #body (p. 1761)) then

(
local_key_buffer.ikblend = my_key.ikblend (p. 1761)
local_key_buffer.ikspace = my_key.ikspace (p. 1761)
local_key_buffer.ikAnkleTension = my_key.ikAnkleTension (p. 1761)
)
if (my_key.type == #vertical (p. 1761)) then
(
local_key_buffer.dynamicsblend = my_key.dynamicsblend (p. 1761)
local_key_buffer.ballistictension = my_key.balistictension (p. 1761)
)

if (my_key.type == #horizontal (p. 1761)) then

(
local_key_buffer.balancefactor = my_key.balancefactor (p. 1761)
 1833

)
local_key_buffer.easefrom = my_key.easeto (p. 1761)
local_key_buffer.easeto = my_key.easefrom (p. 1761)
local_key_buffer.tension = my_key.tension (p. 1761)
local_key_buffer.continuity = my_key.continuity (p. 1761)
local_key_buffer.bias = my_key.bias (p. 1761)

return (local_key_buffer)
)

else
(
messagebox “Cannot change this preset because there is no key for
the selected track at the current frame.\n Please advance the time slider to a
frame where a key exists.\nOr select a track and frame where a key exists.\nOr set
a key first.\n”
return (local_key_buffer)
)
)
else
(
messagebox “There is no controller for the selected track.\nYou may need
to enable separate tracks.\n”
return (local_key_buffer)
)
)

CS3Save_Presets Code
-- *************************************************************
-- CS3Save_Presets - save all key values to a .ms file that can be re-read at next
launch
-- *************************************************************
FN CS3Save_Presets =
(
my_path = scriptspath (p. 630) + “startup\CS3CustomKeys-presets.ini”
outfile = createfile (p. 763) my_path
format “-- This file was created by the CS3 Custom Key Macro
\“Save_Key_Presets\“ to store user-customized presets for Biped custom key macro
tools\n” to:outfile
format “-- These values can be editted by hand for existing fields\n\n”
to:outfile

k = keya_buffer
format “Global keya_buffer = Biped_key type:% ikblend:% ikspace:% easefrom:%
easeto:% tension:% continuity:% bias:%\n” k.type k.ikblend k.ikspace k.easefrom
k.easeto k.tension k.continuity k.bias to:outfile
k = keyb_buffer
format “Global keyb_buffer = Biped_key type:% ikblend:% ikspace:% easefrom:%
easeto:% tension:% continuity:% bias:%\n” k.type k.ikblend k.ikspace k.easefrom
k.easeto k.tension k.continuity k.bias to:outfile
k = keyc_buffer
1834 Chapter 22 | CS3Tools.cui Tutorial

format “Global keyc_buffer = Biped_key type:% ikblend:% ikspace:% easefrom:%

easeto:% tension:% continuity:%
k.easeto k.tension k.continuity
k = keyd_buffer
format “Global keyd_buffer
easeto:% tension:% continuity:%
k.easeto k.tension k.continuity
k = keye_buffer
format “Global keye_buffer
easeto:% tension:% continuity:%
k.easeto k.tension k.continuity
k = keyf_buffer
format “Global keyf_buffer
easeto:% tension:% continuity:%
k.easeto k.tension k.continuity
bias:%\n” k.type k.ikblend k.ikspace k.easefrom
k.bias to:outfile
= Biped_key type:% ikblend:% ikspace:% easefrom:%
bias:%\n” k.type k.ikblend k.ikspace k.easefrom
k.bias to:outfile
= Biped_key type:% ikblend:% ikspace:% easefrom:%
bias:%\n” k.type k.ikblend k.ikspace k.easefrom
k.bias to:outfile
= Biped_key type:% ikblend:% ikspace:% easefrom:%
bias:%\n” k.type k.ikblend k.ikspace k.easefrom
k.bias to:outfile

close (p. 763) outfile

)

Set_Key_FN Code
The pseudo code for the Set_Key_FN is as follows:
function Set_Key_FN local_key_buffer
store state of shift key
if nothing selected then return false
if one object selected and not a Biped Object then return false
if local_key_buffer undefined then return false
-- process multiple selections independently so that we can
-- support key setting of multiple bipeds
else for each of the items in the selection
( if current item not a Biped Object then get next item
set my_root to the root of the hierarchy
if my_root is in figuremode then get the next item
if my_root is in motionmode then get the next item
if my_root is in footstepmode then get the next item
set my_controller to the item’s controller
if hierarchy root is the current item then
set my_controller to the current track ( horizontal / vertical /
turning)
else get the next item

if shift key was pressed then

(
for each key in my_controller
if key is selected set values for key
)
else
(
add a new key to my_controller at the current time and select the new key
get the index of the newly created key
if the index is greater than 0 then
 1835

get the newly created key

if (my_key.type == #body) then
(
set my_key.ikblend to local_key_buffer.ikblend
set my_key.ikspace to local_key_buffer.ikspace
)
set my_key.easeto to local_key_buffer.easefrom
set my_key.easefrom to local_key_buffer.easeto
set my_key.tension to local_key_buffer.tension
set my_key.continuity to local_key_buffer.continuity
set my_key.bias to local_key_buffer.bias
)
The actual function can be seen here:
FN Set_Key_FN local_key_buffer =
(
if (keyboard.shiftpressed) then
keyboardshiftpressed_atstart = true
else
keyboardshiftpressed_atstart = false
if ($selection (p. 781).count == 0 ) then
(
messagebox “There are no objects selected.\nPlease select a Biped Object
first.\n”
return false
)

-- Showclass “Biped_” reports Biped_Object:GeometryClass{9125,0}

if (($selection (p. 781).count == 1) and ((classof $ (p. 820)) != Biped_Object))
then
(
messagebox “The selected object is not a Biped Object.\nPlease select a
Biped Object first\n.”
return false
)

if (local_key_buffer == undefined) then

(
messagebox “This preset key has not been initialized.\nPlease select a
key first, and set its preset\n.”
return false
)

-- process multiple selections independently so that we can support key setting

of multiple bipeds

else for i=1 to $selection (p. 781).count do

(
if ((classof (p. 820) $selection[i]) != Biped_Object) then
(
msgtext = “The selected object ‘” + $selection[i].name + “‘ is not
a Biped Object.\nObject Skipped.\n”
1836 Chapter 22 | CS3Tools.cui Tutorial

messagebox msgtext
continue
)

my_root = $selection[i].controller.rootnode
if (my_root.transform.controller.figuremode (p. 1736) == true) then
(
msgtext = “‘” + $selection[i].name + “‘ is in Figure Mode.\nSet Key
is not supported in Figure Mode.\nPlease exit Figure Mode for this object
first.\nObject Skipped.\n”
messagebox msgtext
continue
)

if (my_root.transform.controller.motionmode (p. 1736) == true) then

(
msgtext = “‘” + $selection[i].name + “‘ is in Motion Flow Mode.\nSet
Key is not supported in Motion Flow Mode.\nPlease exit Motion Flow Mode for this
object first.\nObject Skipped.\n”
messagebox msgtext
continue
)

if (my_root.transform.controller.footstepmode (p. 1736) == true) then

(
msgtext = “‘” + $selection[i].name + “‘ is in Footstep Mode.\nSet
Key is not supported in Footstep Mode.\nPlease exit Footstep Mode for this object
first.\nObject Skipped.\n”
messagebox msgtext
continue
)
-- find the root controller of this object
-- my_controller = (controllerof ($selection[i]))

my_controller = $selection[i].controller
if (my_root == selection[i) then -- user is working on COM
(
if (my_controller.trackselection (p. 1736) == 1) then
(
my_controller = my_controller.horizontal.controller (p. 1736)
)

else if (my_controller.trackselection (p. 1736) == 2) then

(
my_controller = my_controller.vertical.controller (p. 1736)
)

else if (my_controller.trackselection (p. 1736) == 3) then

(
my_controller = my_controller.turning.controller (p. 1736)
)
 1837

else
(
msgtext = “‘” + $selection[i].name + “‘ skipped.\n”
messagebox msgtext
continue
)
)
-- loop through all keys and call only if a key is selected

if (keyboardshiftpressed_atstart == true) then -- user wants to process

all selected keys in this track
(

found_selected_keys = 0

for temp_index=1 to (numkeys my_controller) do

(
if (iskeyselected my_controller temp_index) then
(
set_one_key_FN my_controller temp_index local_key_buffer -- set
this key to the local key buffer
found_selected_keys += 1
)
)

if (found_selected_keys == 0 ) then
(
msgtext = “Warning: No keys selected.\nNo changes made to “ +
$selection[i].name + “.”
messagebox (msgtext)
)
else
(
msgtext = “Changed “ + (found_selected_keys as string) + “ keys
in “ + $selection[i].name + “.”
messagebox (msgtext)
)
)

else -- (default) user wants to process just the current key

(
temp_index = getkeyindex my_controller slidertime
-- format “index of key at this frame (temp_index) is %\n” temp_index

if (temp_index == 0) then -- no key at this frame yet, let’s create

one...
(
biped.addNewKey my_controller slidertime #select
temp_index = getkeyindex my_controller slidertime
)
1838 Chapter 22 | CS3Tools.cui Tutorial

-- temp_index should now indicate the ordinal index of the key for
this track, 1st, 2nd, 3rd, etc.
-- if it is still zero, then the user has selected a track or mode
that prevents adding a key, like footsteps

if (temp_index >0) then -- key was created ok

(
set_one_key_FN my_controller temp_index local_key_buffer
)
else -- addnewkey failed, probably because the footstep track is
selected
(
msgtext = “The selected track ‘” + ($selection[i]).name + “‘ does
not support keys.\n Object Skipped.\n”
messagebox msgtext
)
)
)

return true
)

Naming the Buttons

You can name the key button accordingly to help you remember the purpose for that key type:
“heel down”, “finger point”, “hand grab”, etc.
To change the tooltip for the buttons on the CS3Tools.cui toolbar, right click on the button,
choose “Edit Button Appearance”, modify the text in the “Tooltip:” text box and choose the OK
button.

Extending the Number of Presets

The number of different settings that CS3Tools.cui supports can be extended. Two new macro
files (*.mcr) for each new additional custom key, one for “Set” and one for “Change Preset”,
need to be added to the ..\ui\macroscripts directory and identical macros need to be added to
..\Scripts\Startup\CS3Customkeys.ms as well. Global key*_buffer’s that matched the number of
pairs of new macros added to the CS3Tools.cui need to be inserted into the file
..\Scripts\Startup\CS3Customkeys.ms Tutorial_File_name_CS3Customkeys_ms. Finally, the
new macro files (*.mcr) have to be incorprated into the CS3Tools.cui. See help page Macro Scripts
(p. 1624) in the “Interacting with the 3ds max User Interface” topic and Defining Macro Scripts
(p. 1521) in the “Creating MAXScript Tools” topic for additional details.

See Also
Biped MaxScript Extensions (p. 1725)
Crowd MaxScript Extensions (p. 1771)
Index

Symbols animatable properties in 3ds max objects

character lvii 806
? symbol xli INI file keys 1647
and output pane xli locals and other items in a rollout from ex-
capturing values xli ternal code 1480
evaluating code xli MAXScript 579
MAXScript classes and properties 799
Numerics scripted utilities l
2 New Scripted Pug-in Superclasses 162 subAnims 806
2D and 3D point literals 665 Accessing The Material Editor Active Slot 163
3D vector for programming xxxii Action Manager 9
3ds max 4 MAXScript Online Reference xxxi ActiveX Controls in MAXScript Rollouts 10
3ds max file loading and saving 1639 Adapt Link Controller for Constraints 42
3ds max Scanline A-Buffer Renderer Anti-Alias- Adapted Path Constraint 39
ing Filters 1614 addAndWeld() 1079
3ds max Scene File Properties 1628 adding objects 591
3ds max specific errors 1674 Additional Keyword Parameter On pickObject()
3ds max system global variables 630 127
3ds max-specific classes 808 Additive_Euler_XYZ - superclass RotationCon-
troller 262
addKnot() 1079
A
addNewSpline() 1079
aborting execution lv
addNewXRefFile() - xrefs 1038
about context 686
Adobe_Photoshop_Plug_In_Filter - TextureMap
Access to the new node bone properties and
1241
methods 23
Adobe_Premiere_Video_Filter - TextureMap
Accessing
1242
AppData 813
AEC Extended Objects
accessing
Terrain 894
active viewport info
Affect Region Function 127
type
Affect_Region - Modifier 1103
and transforms 1581
alert box liii
Alpha - superclass MAXObject 262
1840 Index

alphaRenderElement - superclass MAXObject attachment controller keys 1305

263 attachMultiple() - splineOps 1079
Anchor- Helper 986 audio controllers 1306
Angle UI element 168 AudioClip - helper 986
AngleAxis Values 741 auto open listener on output xxxvi
animate 603 auto start MAXScript lvi
animate context 683 autoBackup const StructDef 232
animateVertex() 1041 auto-load lvi
animation controllers 1288 automatic loading lvi
animation mode xxxii Automatic_Exposure_Control - superclass
Anti-Aliasing Filters 1614 MAXObject 268
AppData 813 AutomaticAdaptiveExposureControl - super-
applying standard transformations 598 class MAXObject 267
ApplyOperation function 54 Avoid_Behavior ReferenceTarget 1793
Apropos” and “ShowProperties” and now awning - GeometryClass 897
“Help” and “Show” 128 axisTripodLocked() 1603
Arc - Shape 949
arguments - positional and keyword 676 B
array literals 666 background - Helper 987
array values 776 BackgroundRenderElement - superclass MAX-
ArrayParameter values 770 Object 269
ASCII editors - opening script files 624 backslash - for line continuation lvii
Asset Browser enhancements 22 Barycentric_Morph_Controller - MorphCon-
assigning variables 585 troller 1306
assignment Barycentric_Morph_Controller Keys 1308
math 671 basic data values 717
to variables 643 batch scripts vs. launch scripts lvii
association rules 672 bend - modifier 1104
at 685 bevel - modifier 1106
at level context 684 Bevel_Profile - Modifier 1108
at time context 685 Bezier controller keys 1310
Atmosphere - superclass MAXObject 264 Bezier controllers 1309
atmosphereRenderElement 264, 265 Bezier Keys inTangentLength and outTan-
atmospheric - MAXWrapper 1337 gentLength 158
atmospheric effects bgndRenderElement - superclass MAXObject
combustion 1339 270
common properties BiFold - GeometryClass 897
operators BigMatrix values 748
and methods 1338 BigMatrixRowArray values 748
fog 1342 billboard - helper 987
scripted plug-ins 1569 bindKnot() 1079
types 1339 BinStream for Binary Reading and Writing 128
Volume_Fog 1343 biped - system 1456
Volume_Light 1344 Biped and Crowd Interaction 1734
working with 1345 biped and physique 1456
AttachCtrl const StructDef 232 Biped Classes 1748
attachment - PositionController 1304
 Index 1841

Biped Controllers 1735 Bones - System 991

Biped Creation 1727 Boolean - mesh 852
Biped Footprints 1745 Boolean2 - GeometryClass 887
Biped Footsteps 1745 BooleanClass values 728
Biped Keys 1759 boolObj const StructDef 233
Biped Layers 1731 box 591
Biped Load and Save 1725 box - GeometryClass 853
Biped MaxScript Extensions 1725 box transformations 603
Biped Motion Flow 1752 box2 values 750
Biped MultFprintParams Class 1748 BoxGizmo - helper 982
Biped Node Hierarchy 1731 brackets
Biped Slave Controller 1745 balancing in long code xxxviii, xlvi
Biped Vertical_Horizontal_Turn(Body) nested xxxviii, xlvi
Matrix3 Controller 1736 Bricks - TextureMap 1245
biped_object GeometryClass 1730 Brightness_and_Contrast - RenderEffect 1353
BipedExportInterface Values 1458 buffers
BipedFSKey MAXObject 1751, 1763 cut/paste xxxviii, xlvi
BipedKey MAXObject 1761 logging xli
Biped-Related Classes 1457 button 1488
bit const StructDef 233 By-Reference parameter passing 129
BitArray values 791
bitmap C
files 1641 C++-style bracketing comments 131
rollout user-interface item 1487 C_Ext - GeometryClass 854
texture - TextureMap 1243 call stack trace-back liii
values 755 error messages liii
Bitmap Manager – Function Published BMM function parameters liii
control 161 local variables liii
BitmapTex fnReload and fnCrop 164 callbacks
bitmapTex interfaces 434 and change handlers 1649
blend - material 1205 general event 29, 1656
BlendRenderElement - superclass MAXObject time change 1654
271 viewport redraw 1655
blizzard - GeometryClass 906 callbacks const StructDef 233
Block - FloatController 1311 camera
block expressions 679 common properties
as commands xxxviii operators
executing xxxviii and methods 974
selecting xxxviii FreeCamera 976
Block_Control - MasterBlockController 1311 TargetCamera 976
Block_Control interfaces 435 camera - Node 974
blur - RenderEffect 1349 Camera_Map - modifier 1109
BMP I/O Interface 164 CamPoint - helper 984
BMP interfaces 437 Cap_Holes - modifier 1110
bomb - SpacewarpObject 993 Capsule - GeometryClass 855
bone - helper 978 cascading contexts 688
Bone Creation 25
1842 Index

case/of expression 693 saving in editor windows xliv

casement - GeometryClass 898 Coercion of bitArray to array and integer arrays
catch 697 to bitArrays 132
Cellular - TextureMap 1247 CogControl ReferenceTarget 1791
ChamferBox - GeometryClass 856 collections 773
ChamferCyl - GeometryClass 857 ArrayParameter 770
change handlers 1650 EdgeSelection 790
and callbacks 1649 FaceSelection 788
ChangeHandler - value 1650 MAXKeyArray 793
Changes to Undeclared Implicit Global Vari- MAXNoteKeyArray 794
ables 163 ModifierArray 794
checkbox 1489 NURBSSet 797
checkbutton 1490 SelectionSet 785
checker - TextureMap 1249 Types 775
circle - shape 950 VertexSelection 786
class Color
and object inspector functions 799 values 729
hierarchy 1688 color coding text - listener window xxxvii
property inspection 799 Color Manager 35
Class and Object Inspector Functions 159 Color_Balance - RenderEffect 1354
class id filter 59 Colored_Shadow - superclass MAXObject 273
classes and objects in object-oriented program- colorpicker 1492
ming lxii combobox 1493
clauses Combustion 38
mouse tool 1532 combustion
RCMenu 1515 atmospheric 1339
Rollout 1470 setting explosion start and end times for
scripted plug-in 1542 1341
Utility 1466 Combustion.coordinates - superclass MAXOb-
close() 755, 1079 ject 274
close() - splineOps 1079 Command line -U MAXScript startup scripts
clrShadowRenderElement - superclass MAXOb- 133
ject 272 command lines - running scripts lvii
code command panel switching - macro recorder
aborting lv method l
bracket balancing xxxviii, xlvi command panels
comments style lvii Create 1572
evaluating in editor windows xlvi general 1571
evaluating in listener window xlvi Modify 1572
evaluation results xli commands
extended blocks xxxvi aborting multiline lv
inserting script files lix block expressions xxxviii
layout lvii, 678 clear all in listener window xxxviii
line brakes lvii close in editor windows xlvi
punctuation lvii copy in editor windows xlvi
rules for layout lvii copy in listener window xxxviii
running conflicts lv cut in editor windows xlvi
 Index 1843

cut in listener window xxxviii ConeAngleManip - superclass helper 277

delete in editor windows xlvi conform - GeometryClass 889
delete in listener window xxxviii ConformSpaceWarp - SpacewarpObject 995
editor xlvi connect - GeometryClass 889
end-of-text xxxviii Const Generic 195
entering in listener window xxxvi Const NodeGeneric 209
evaluate all in editor windows xlvi Const Primitives 213
executing 3ds max commands 1630 Const StructDef 231
executing in listener window xxxviii constructs - compile time lix
executing in MAXScript xxxvii contents 577
find in editor windows xlvi context
find in listener window xxxviii about 686
find next in editor windows xlvi animate 683
find next in listener window xxxviii at level 684
help in editor windows xlvi at time 685
help in listener window xxxviii cascading 688
indent in editor windows xlvi coordsys 685
listener xxxvii expressions 681
menu bar for listener window xxxviii in 684
new in editor windows xlvi nested 688
new script in listener window xxxviii set 689
open in editor windows xlvi undo 687
open script in listener window xxxviii Context Filters 43
paste in editor windows xlvi continuation lines lvii
paste in listener window xxxviii continue 696
recording xxxii control constructs
replace in editor windows xlvi case/of expression 693
replace in listener window xxxviii controlling program flow 691
run script in listener window xxxviii for loop 694
save as in editor windows xlvi if/then/else 692
save as in listener window xxxviii loop exit 697
save in editor windows xlvi try expression 697
select all in editor windows xlvi while and do loops 694
select all in listener window xxxviii control point animation 1461
undo in editor windows xlvi Controller
undo in listener window xxxviii FloatController Superclass 1301
unindent in editor windows xlvi MasterBlockController Superclass 1301
using number pad ENTER xlvi MorphController Superclass 1302
comments lvii Point3Controller Superclass 1302
comparison expressions 673 PositionController Superclass 1303
compass - helper 979 QuatController Superclass 1304
CompositeMaterial - material 1206 RGB 1335
CompositeTextureMap - TextureMap 1250 RotationController Superclass 1303
compound objects - geometry 886 ScaleController Superclass 1304
conditional statements 607 XYZ 1335
cone - GeometryClass 858 controller
Cone_Angle - superclass helper 276 Animation 1288
1844 Index

Attachment 1305 coordinates - macro recorder l

Audio 1306 coordsys 685
Barycentric_Morph_Controller 1306 coordsys context 685
Bezier 1309 copy
Block 1311 editor windows command xlvi
Block_Control 1311 listener window command xxxviii
common properties Core Interfaces 70, 352
operators Create Panel 1572
and methods 1289 CreateDialog 169
Cubic_Morph_Controller 1312 createPreview() 1603
Dynamics 1312 creating functions 699
ease and multiplier curve functions 1297 Creating Icon Bitmap Files 1530
Expression 1313 creating new NURBS objects 1389
IK_ControllerMatrix3Controller 1313 creating NURBS scene objects 1392
key functions 1294 creating NURBSCVSurface values 1394
key reducer 1299 CrossSection - Modifier 1110
Linear 1315 Crowd Behaviors 1792
Link_Control 1316 Crowd helper 1771
List 1317 Crowd Priority Properties 1792
LOD_Controller 1319 Crowd R3.0 MaxScript Extentions 1771
LookAt 1319 CrowdAssignment ReferenceTarget 1784
MasterBlock 1320 Crowds Methods 1788
Matrix3Controller Superclass 1302 CrowdScatter 1778
Motion Capture 1321 CrowdState ReferenceTarget 1786
nested object functions 814 CrowdTeam ReferenceTarget 1785
Noise 1322 CrowdTransition ReferenceTarget 1787
On_Off 1323 CS3Tools.cui Tutorial 1825
out-of-range functions 1296 Cubic_Morph_Controller - MorphController
Path 1324 1312
PositionController 1304 Cubic_Morph_Controller Keys 1312
PRS 1325 cui const StructDef 234
Reactor 1326 cursor
Script in bracket balancing xxxviii, xlvi
return() 1329 placement in panes xxxvi
Slave 1333 cursors
Slave_Control 1333 for drag-and-drop l
Superclass Level Types 1300 searching last position xlvi
SurfacePositionController 1334 Curve Control 170
TCB 1334 custAttributes const StructDef 234
time functions 1292 custom functions 614
Waveform_Float 1335 custom user interface files 1648
Controller Functions for use with Constraint Customize The Order of Rollup Pages 185
Assignments 42 cut
controlling program flow in scripts 607 cut/paste buffer xxxviii, xlvi
controlling the renderer 1664 editor windows command xlvi
ConvertToPatch - superclass modifier 278 listener window command xxxviii
Coordinate Display 1578 CV_Curve - Shape 964
 Index 1845

cycle() - splineOps 1079 Disp_Approx - Modifier 1111

CylGizmo - helper 983 Displace - Modifier 1112
cylinder - GeometryClass 859 Displace_Mesh - SpacewarpModifier 1198
Displace_NURBS - SpacewarpModifier 1198
D display() 755
damper - GeometryClass 880 displaySafeFrames 1603
default mode - logging xli divide() - splineOps 1079
defaults - macro recorder l do and while loops 607, 694
defining do loop exit 697
custom functions 614 do/while expression 694
local functions in structures 709 DOF const StructDef 234
macro scripts 1521 DontCollect Value 754
utilities l donut - shape 951
Definition Constructs Can Include Global Vari- door objects - geometry 896
able Declarations At Top Level 162 DOS - and listener window xxxvi
definitions lx double-hyphen - for code comments lvii
Definitions for MAXScript internal organiza- DoubleSided - Material 1207
tion 188 Drag - superclass SpacewarpObject 149, 281
deflector - SpacewarpObject 1024 drag-and-drop
Delegate Helper 1773 editor windows xliv
delete listener window xxxvii
editor windows command xlvi using cursor l
listener window command xxxviii drawing a box with MAXScript 591
delete() 1038 dropdownlist 1494
delete() - splineOps 1079 dummy - helper 979
deleteAllXRefs() - xrefs 1038 dynamic properties 805
deleteKnot() 1079 Dynamics Controllers 1312
DeleteMesh - Modifier 1111 dynamics objects - geometry 879
DeletePatch - superclass modifier 279 dynamics space warps 1003
deleteSpline() 1079
DeleteSplineModifier - Modifier 1111 E
Dent - TextureMap 1251 EdgeSelection values 790
dependent NURBS objects 1386 Edit_Mesh - modifier 1114
dependsOn For Scripted Controllers 95 Edit_Patch - modifier 1115
Depth_of_Field - RenderEffect 1354 Edit_Spline - modifier 1115
Dereferencing Operator 133 editable meshes 1041, 1077
desktop editable patches 1041
configuring setups lvi editable splines 1041
location of windows lvi Editable_Mesh - GeometryClass 1041
storing state lvi editor
detach() - splineOps 1079 commands xlvi
Detecting Deleted Nodes 133 description xliv
Diffuse - superclass MAXObject 279 editor windows xliv
diffuseRenderElement - superclass MAXObject and script files xliv
280 creating empty xliv
DirectionalLight - Light 970 drag-and-drop functions xxxvii
1846 Index

editing text xliv context 681

evaluating code xlvi for/do
keyboard shortcuts xlvi for/collect 694
list of features xliv function call 675
loading files xliv function definition 699
menu bar commands xlvi if/then/else 692
opening xxxiv, xliv logical 674
saving code xliv logical - short-circuiting 675
syntax coloring xlvi math 670
edittext 1496 return 705
ellipse - shape 953 simple 669
emissionRenderElement - superclass MAXOb- struct 707
ject 285 throw 697
encrypted files 1647 try 697
encrypting scripts lx when 1650
end-of-text while/do 694
aborting xxxviii expression controllers 1313
listener window command xxxviii expressions 588, 667
entering arrays 582 determining if complete lvii
entering information in MAXScript 582 evaluating xli
entering numbers 582 extended objects - geometry 852
entering strings 582 external file methods 1645
error messages liii extrude - modifier 1115
call stack trace-back liii
embedded liii F
in alert box liii Face_Extrude - modifier 1127
in listener panes xxxviii FaceSelection values 788
in output pane liii Fallof2 - TextureMap 1252
logging xli FalloffTextureMap - TextureMap 1255
errors - locating in MAXScript liii favorites tab (HTML help viewer) 1721
ESC - aborting execution lv FFD_2x2x2 - Modifier 1121
escape lv FFD_3x3x3 - Modifier 1123
escapeEnable lv FFD_4x4x4 - Modifier 1124
EulerAngles Values 742 FFD_Box - Modifier 1117
evaluating expressions xli FFD_Cyl - Modifier 1119
example scripts 624 FFD_Select - Modifier 1126
executing external commands 1668 file name parsing 1644
exit - loops 697 file open dialog - opening xxxiv
exiting 3ds max 1669 File_Output - RenderEffect 1356
explicit scene objects - macro recorder l fileIn() lix
explode() - splineOps 1079 fileProperties const StructDef 235
exposing MAXScript functions 1673 files
expression 3ds max file loading and saving 1639
blocks 679 bitmap 1641
case/of 693 custom user interface files 1648
catch 697 encrypted 1647
comparison 673
 Index 1847

external file methods 1645 exit 697

INI files 1647 expression 694
loading in editor windows xliv skipping iterations 696
name parsing 1644 forceUpdate Function 134
searching directories for xliv, lvi FreeCamera - Camera 976
standard open and save dialogs 1643 freeform language - defined lvii
text file input and output 1643 freeSceneBitmaps() 755
XRef files 1643 FreeSpot - Light 971
FileStream Values 763 function
Fillet_Chamfer - Modifier 1127 definition 699
Film_Grain - RenderEffect 1356 in structures 709
filter options - macro recorder l parameters 702
Filters - Anti-Aliasing 1614 return 705
find variables 701
editor windows command xlvi function calls
listener window command xxxviii arguments 676
find next general 675
editor windows command xlvi precedence 677
listener window command xxxviii special notes 678
findUnresolvedXRefs() - xrefs 1038 function libraries lvi
Fixed - GeometryClass 899
flagChanged() 1038 G
flashNodes() 1603 garbage collection 655, 656
FlatMirror - TextureMap 1255 general event callback mechanism 29, 1656
Flex - modifier 1128 general node properties 836
Flex interfaces 438 general topics lii
flexOps const StructDef 235 Gengon - GeometryClass 861
float_list interfaces 441 Geometry
Float_Reactor interfaces 443 scripted plug-ins 1555
Float_Wire interfaces 448, 569 geometry
FloatController Awning 897
Block 1311 BiFold 897
LOD_Controller 1319 Blizzard 906
On_Off 1323 Boolean2 887
Waveform_Float 1335 Box 853
FloatController - MAXWrapper 1301 C_Ext 854
FloatList - superclass FloatController 286 Capsule 855
FloatList interfaces 450 Casement 898
FloatReactor - superclass FloatController 287 ChamferBox 856
FloatReactor interfaces 452 ChamferCyl 857
fn function definition 699 common properties
fog - atmospheric 1342 operators
FogHelper - helper 987 and methods 852
FootSteps Compound Objects 886
Matrix3 Controller 1745 Cone 858
FootSteps Matrix3 Controller 1744, 1750 Conform 889
for loop 607
1848 Index

Connect 889 Torus_Knot 877

Cylinder 859 TriPatch 904
Damper 880 Tube 878
Doors and Windows 896 geometry - Node 850
Dynamics Objects 879 geosphere - GeometryClass 862
Editable_Mesh 1041 getActive 176
Fixed 899 getChannel() 755
Gengon 861 getChannelAsMask() 755
Geosphere 862 GetEndTime() - ik 1313
Hedra 863 getIndexedPixels() 755
L_Ext 865 getInVec() 1079
Loft 890 GetIterations() - ik 1313
Morph 891 getKnotPoint() 1079
NURBS Objects 943 getKnotSelection() 1079
NURBSSurf 943 getKnotType() 1079
OilTank 866 getOutVec() 1079
OldBoolean 887 getPixels() 755
PArray 913 GetPosThreshold() - ik 1313
Particle Systems 904 GetRotThreshold() - ik 1313
Patch 1088 getSegLengths 1079
Patch Objects 903 getSegmentType() 1079
PCloud 923 getSegSelection() 1079
Pivot 899 getSplineSelection() 1079
Pivoted 900 GetStartTime() - ik 1313
Plane 867 getSubAnimName() 806
Point_Surf 943 getSubAnimNames() 806
Prism 868 getTextExtent 175
Projected 901 getXRefFile() - xrefs 1038
Pyramid 869 global 646
Quadpatch 903 global variables 614
RingWave 870 gotoFrame() 755
Scatter 891 gradient - TextureMap 1257
ShapeMerge 893 Gradient_Ramp - TextureMap 1259
SimpleObject scripted plug-ins 1556 gravity - SpacewarpObject 1003
SlidingDoor 901 grid - helper 980
SlidingWindow 902 gw const StructDef 235
Snow 931
Sphere 872 H
Spindle 873 hasProperty() function 135
Spray 933 HD IK controller chains can be assigned to ex-
Spring 883 isting hierarchies 73
Standard and Extended Objects 852 Hedra - GeometryClass 863
SuperSpray 935 Helix - Shape 954
TargetObject 874 help
Teapot 875 about HTML help 1717
Terrain 894 contents 1717
Torus 875
 Index 1849

editor windows command xlvi HSDSObject - superclass modifier 292

index 1717 HSDSObject interfaces 453
listener window command xxxviii HTML help viewer
search 1717 favorites tab 1721
Helper keyboard shortcuts 1722
scripted plug-ins 1561 right-click menus 1722
helper searching in 1718
Anchor 986 toolbar 1721
Atmospheric 982 using 1715
AudioClip 986
Background 987 I
Billboard 987 Icon Bitmap Files - Creating 1530
Bone 978 Identifying and Accessing MAXScript Classes
BoxGizmo 982 and Properties 799
Camera Match 984 iDrop - drag and drop 62
CamPoint 984 if/do expression 692
Compass 979 if/then/else expression 607, 692
CylGizmo 983 ik
Dummy 979 GetEndTime() 1313
FogHelper 987 GetIterations() 1313
Grid 980 GetPosThreshold() 1313
Inline 984 GetRotThreshold() 1313
InlineHelper 988 GetStartTime() 1313
LOD 985 SetEndTime() 1313
LODHelper 988 SetIterations() 1313
NavInfo 988 SetPosThreshold() 1313
Point 980 SetStartTime() 1313
Protractor 981 ik const StructDef 237
ProxSensor 989 IK controller methods 1313
Sound 989 IK_ControllerMatrix3Controller -
SphereGizmo 983 Matrix3Controller 1313
Standard 978 IKChainControl interfaces 453
Tape 981 IKLimb Solver 74
TimeSensor 990 image buttons 1513
TouchSensor 990 imageMotionBlur - superclass renderEffect 294
VRML 1.0/VRBL 984 imageMotionBlur interfaces 454
VRML_VRBL 985 Improved the Performance of Itterating and In-
VRML97 985 dexing the 135
helper - Node 977 in context 684
hide() - splineOps 1079 including scripts within scripts lix
hideselectedsegments() 1079 incrementing 588
hideselectedsplines() 1079 independent NURBS object 1386
hideselectedverts() 1079 indexed access to animatable properties in 3ds
Hierarchy - MAXScript Class 1688 max objects 806
Hose - superclass GeometryClass 146, 287 inheritance lxiii
HSDS_Modifier - superclass modifier 290 inline - helper 984
HSDS_Modifier interfaces 453
1850 Index

InlineHelper - helper 988 K

insertion point xlii keyboard
installing - listener window xxxvi keyboard entry 1623
instance 1778 keyboard const StructDef 237
interface keyboard shortcuts
elements of xxxiv HTML help viewer 1722
extending xxxii keyboard.escPressed 176
replacing xxxii keys
Interface actionMan 353 Attachment Controller 1305
Interface BoneSys 354 Barycentric_Morph_Controller 1308
Interface browserMgr 355 Bezier Controller 1310
Interface cmdPanel 356 Cubic_Morph_Controller 1312
Interface colorMan 356 Linear Controller 1315
Interface dragAndDrop 362 MAXKey Values 767
Interface HDIKSys 365 On_Off Controller 1323
Interface IKSys 365 TCB Controller 1335
Interface manip 366 keywords
Interface maxOps 368 keyword arguments 676
Interface medit 371 reserved 625
Interface menuMan 372
Interface msZip 378 L
Interface NetRender 379 L_Ext - GeometryClass 865
Interface NullInterface 409 label 1497
Interface objXRefs 409 language
Interface paramWire 410 basic learning requirements xxxiii
Interface pluginManager 414 freeform
Interface quadMenuSettings 414 defined lvii
Interface rollup 427 reserved keywords 625
Interface SceneExposureControl 427 lathe - modifier 1133
Interface SceneRadiosity 428 lattice - modifier 1135
Interface timeSlider 428 launch scripts vs. batch scripts lvii
Interface trackviews 429 layout parameters - rollout user-interface con-
Interfaces 67 trols 1483
interrupt execution lv LE const StructDef 237
intersect() - splineOps 1079 learning MAXScript 577
intersection - mesh 852 the macro recorder 624
Interval Values 752 walking through a script 623
inverse kinematics controller methods 1313 Lens_Effects - RenderEffect 1357
isClosed() 1079 Light
isCPEdgeOnInView() 1603 scripted plug-ins 1561
isValidNode 136 light
ItrackBar 113 common properties
operators
J and methods 966
JPEG interfaces 454 DirectionalLight 970
FreeSpot 971
 Index 1851

Omnilight 972 output xxxiv

TargetDirectionalLight 972 panes defined xxxvi
TargetSpot 973 running scripts xlix
light - Node 966 similarities to DOS xxxvi
Line - Shape 955 literals lxiv
line breaks 580 2D and 3D points 665
in MAXScript code lvii arrays 666
invalid lvii constants 659
line selection margin float 660
editor windows xliv integer 660
listener window xxxvii names 657
linear controller keys 1315 numbers 660
linear controllers 1315 pathnames 662
Link - superclass Matrix3Controller 294 strings 660
Link interfaces 455 time 662
Link.link_params - superclass MAXObject 295 loading - automatic lvi
Link_Constraint - superclass Matrix3Controller loading and running your script file 621
295 loading other scripts 623
Link_Constraint interfaces 455 local 646
Link_Constraint.link_params - superclass local variables 614
MAXObject 296 lockAxisTripods() 1603
Link_Control - Matrix3Controller 1316 LOD - Helper 985
Linked_XForm - Modifier 1136 LOD_Controller - FloatController 1319
LinkedXForm - superclass modifier 297 LODHelper - Helper 988
List Controller 143 Loft - GeometryClass 890
List Controllers 1317 log files
listbox 1497 closing xli
ListCtrl const StructDef 238 creating xli
listener logging
? symbol xli capturing output xli
contents xlii capturing text xli
description xxxvi default mode xli
using xxxvii error messages xli
listener window xxxvi in listener window xli
aborting code lv writing data xli
and 3D Studio MAX xxxvi logical expressions 674
and block expressions xxxviii logsystem const StructDef 239
creating editor windows xliv LookAt - Matrix3Controller 1319
defined xxxvi LookAt Constraint 40
entering commands xxxvi LookAt_Constraint - superclass RotationCon-
evaluating code xlvi troller 297
features of xxxvii LookAt_Constraint interfaces 455
installing xxxvi loop exit 697
keyboard shortcuts xxxviii loops 607
logging xli
menu bar commands xxxviii
opening xxxiv, xxxvi
1852 Index

M MultiMaterial 1210
macro recorder l NoMaterial 1212
default options l RayTraceMaterial 1212
displaying output l Shellac 1233
explicit scene objects l StandardMaterial 1224
filter options l StandardXYZGen 1238
recording user actions l TexOutputClass 1239
selection-relative scene objects l TextureMap 1234
sub-object sets l TopBottom 1233
using MAXScript commands l Types 1204
macro recorder pane UVGenClass 1237
listener window xxxvi, xxxviii material - MAXWrapper 1203
macro scripts 1624 Material Editor 1606
creating xxxviii, xliv Material Level Show-in-viewport State 166
defining 1521 materialbutton 1500
macros const StructDef 239 MaterialByElement - Modifier 1136
macroScript 1521 materialID() 1079
macroScript Localization Support for CUI and MaterialLibrary values 795
menu files 176 MaterialModifier - modifier 1137
main toolbar 1574 materials assignment and texture coordinates
makeFirst() - splineOps 1079 1391
managing multiple rollouts in a scripted utility math 588
1468 math assignment 671
manual garbage collection 656 math expressions 670
mapbutton 1499 mathematical operations in MAXScript 588
mapKeys() method 144 Matrix3 Scripted Controller 96
mapPaths const StructDef 239 Matrix3 Values 744
mapped function definition 699 Matrix3Controller
MapScaler - SpacewarpModifier 1198 IK_ControllerMatrix3Controller 1313
marble - TextureMap 1261 Link_Control 1316
Mask - TextureMap 1262 LookAt 1319
MasterBlock - MasterBlockController 1320 MAXWrapper 1302
MasterBlockController PRS 1325
Block_Control 1311 Slave_Control 1333
MasterBlock 1320 MatteShadow - Material 1208
MasterBlockController - MAXWrapper 1301 MAX commands 1630
Material MAX commands in MAXScript 620
scripted plug-ins 1565 MAX Open & Save Dialogs 177
material MAXKey
Blend 1205 common properties
common properties operators
operators and methods 768
and methods 1203 values 767
CompositeMaterial 1206 MAXKeyArray Values 793
DoubleSided 1207 MAXNoteKey Values 818
MatteShadow 1208 MAXNoteKeyArray Values 817
MorpherMaterial 1209 maxOps 87
 Index 1853

MAXScript Class Hierarchy 1688 scripted plug-in 1551

MAXScript commands mini listener - defined xxxvi
in macro recorder l mirror - modifier 1143
MAXScript grammar 1681 mirrorBoth() - splineOps 1079
MAXScript message and query dialogs 1622 mirrorHoriz() - splineOps 1079
MAXScript overview xxxii mirrorVert() - splineOps 1079
MAXScript system globals 640 miscellaneous
MAXScript.reg - Registery file 84 dialogs 1621
MAXScriptFunction List 190 functions 1663
maxscrpt.dsk lvi viewport methods and system globals 1603
MAX-specific classes - dynamic properties 805 Missing Object Classes 1460
MAXWrapper mix - TextureMap 1262
AppData 813 modification 593
Atmospheric 1337 color 593
common properties name 593
operators position 593
and methods 809 scale 593
Controllers 1288 showClass() 593
Material 1203 size 593
Modifier 1095 Modifier
nested controllers 814 scripted plug-ins 1562
nested object properties 815 scripted SimpleMod plug-ins 1563
Node 820 modifier
RenderEffect 1347 Affect_Region 1103
SpacewarpModifier 1095 Bend 1104
MAXWrapper - Value 808 Bevel 1106
Melt - Modifier 1138 Bevel_Profile 1108
memory allocation 655 Camera_Map 1109
Menu and CUI Loading 178 Cap_Holes 1110
Menu Manager 75 change 603
menuItem 1518 common properties
menus operators
mouse right-click 1514 and methods 1096
right-click in editor windows xlvi creation 603
right-click in listener window xxxviii CrossSection 1110
merge() 1038 DeleteMesh 1111
mesh DeleteSplineModifier 1111
nodeTM 1556 Disp_Approx 1111
Mesh_Select - modifier 1142 Displace 1112
Mesher 82 Edit_Mesh 1114
Mesher - superclass GeometryClass 298 Edit_Patch 1115
meshop const StructDef 239 Edit_Spline 1115
meshOps const StructDef 243 Extrude 1115
MeshSmooth - modifier 1139 Face_Extrude 1127
meshsmooth - superclass modifier 298 FFD_2x2x2 1121
methods lxiv FFD_3x3x3 1123
for macro recorder l FFD_4x4x4 1124
1854 Index

FFD_Box 1117 UVWmap 1188

FFD_Cyl 1119 Vertex_Colors 1191
FFD_Select 1126 VertexPaint 1191
Fillet_Chamfer 1127 VolumeSelect 1192
Flex 1128 Wave 1194
Lathe 1133 XForm 1195
Lattice 1135 Modifier - MAXWrapper 1095
Linked_XForm 1136 ModifierArray Values 794
MaterialByElement 1136 Modify panel 1572
MaterialModifier 1137 modifying existing NURBS objects 1390
Melt 1138 modifying the box 593
Mesh_Select 1142 modPanel const StructDef 244
MeshSmooth 1139 MoFlowScript MaxWrapper 1754
Mirror 1143 MoFlowSnippet MaxWrapper 1755
Morpher 1144 MoFlowTranInfo MaxWrapper 1756
NCurve_Sel 1145 MoFlowTransition MaxWrapper 1758
NoiseModifier 1145 morph - GeometryClass 891
Normalize_Spline 1146 MorphController
NormalModifier 1147 Barycentric_Morph_Controller 1306
NSurf_Sel 1147 Cubic_Morph_Controller 1312
Optimize 1148 MorphController - MAXWrapper 1302
PatchDeform 1150 morpher - modifier 1144
PathDeform 1151 MorpherMaterial - material 1209
Physique 1458 Motion Capture 1763
Preserve 1152 motion capture controllers 1321
Push 1153 Motion Flow 1752
Relax 1154 Motion_Blur - superclass renderEffect 302
Ripple 1154 Motion_Blur interfaces 462
Skew 1155 MotionClips and GlobalMotionClip 1820
Skin 1157 Motor- SpacewarpObject 1004
SliceModifier 1165 mouse const StructDef 244
Smooth 1166 mouse cursors 1588
Spherify 1167 mouse right-click menus 1514
SplineSelect 1167 mouse tools - scripted 1531
Squeeze 1167 mouseTrack() Function 180
STL_Check 1169 move() 598
Stretch 1170 moveKeys function 145
sub-object transform properties 1099 mtlBrowser 180
Surface 1171 mtlBrowser const StructDef 244
SurfDeform 1171 Multi/Sub Material 75
Taper 1173 Multi-line editText UI items in Scripted Roll-
Tessellate 1174 outs 108
Trim_Extend 1175 MultiListBox 1502
Twist 1175 MultiMaterial - material 1210
Types 1100 MultiRes - superclass modifier 153, 302
Unwrap_UVW 1176
UVW_Xform 1187
 Index 1855

N Notetrack Values 816

Name NoTexture - TextureMap 1265
literals 657 Notify Callbacks for Animate button on and off
values 727 Transitions 27
NavInfo - Helper 988 NSurf_Sel - modifier 1147
NCurve_Sel - Modifier 1145 Number
nested contexts 688 literals 660
nested object controller functions 814 values 717
nested object properties 815 numKnots() 1079
nesting numSegments() 1079
brackets xxxviii, xlvi numSplines() 1079
script files lix NURBS
Network Render iMaxNet 82 classes 1401
New Classes in release 4 259 classes - overview 1386
new script node properties and methods 1397
listener window command xxxviii working with 1384
NGon - Shape 957 NURBS Curves - Shapes 964
node NURBS Objects
Camera 974 NURBSSurf 943
common properties Point_Surf 943
operators NURBS1RailSweepSurface - NURBSSurface 1427
and methods 820 NURBS2RailSweepSurface - NURBSSurface 1429
general properties 836 NURBSBlendCurve - NURBSCurve 1410
GeometryClass 850 NURBSBlendSurface - NURBSSurface 1430
Helper 977 NURBSCapSurface - NURBSSurface 1432
Light 966 NURBSChamferCurve - NURBSCurve 1411
MAXWrapper 820 NURBSControlVertex - NURBSObject 1409
SpacewarpObject 992 NURBSCurve
subclasses 849 NURBSBlendCurve 1410
System 991 NURBSChamferCurve 1411
transform properties 841 NURBSCurveOnSurface 1414
using 843 NURBSCVCurve 1412
user-defined properties and methods 848 NURBSFilletCurve 1415
XRefObject 1037 NURBSMirrorCurve 1417
node - Shape 944 NURBSOffsetCurve 1417
Node Handles 83 NURBSPointCurve 1418
Node vertexColorType 83 NURBSPointCurveOnSurface 1419
NodeChildrenArray Values 785 NURBSProjectNormalCurve 1420
noise - TextureMap 1263 NURBSProjectVectorCurve 1421
noise controllers 1322 NURBSSurfaceEdgeCurve 1422
NoiseModifier - modifier 1145 NURBSSurfaceNormalCurve 1422
NoMaterial - material 1212 NURBSSurfSurfIntersectionCurve 1423
Normalize_Spl - superclass modifier 305 NURBSXFormCurve 1424
Normalize_Spline - modifier 1146 NURBSCurve - NURBSObject 1409
NormalModifier - modifier 1147 NURBSCurveConstPoint - NURBSPoint 1403
note keys - value 818 NURBSCurveIntersectPoint - NURBSPoint 1404
note track access 816 NURBSCurveOnSurface - NURBSCVCurve 1414
1856 Index
NURBSCurveSurfaceIntersectPoint - NURB-
SPoint 1405
NURBSCVCurve
NURBSCurveOnSurface 1414
NURBSCVCurve - NURBSCurve 1412
NURBSCVSurface - NURBSSurface 1433
NURBSDisplay - Value 1447
NURBSExtrudeSurface - NURBSSurface 1435
NURBSFilletCurve - NURBSCurve 1415
NURBSFilletSurface - NURBSSurface 1436
NURBSIndependentPoint - NURBSPoint 1406
NURBSIsoCurve - NURBSCurve 1416
NURBSLatheSurface - NURBSSurface 1437
NURBSMirrorCurve - NURBSCurve 1417
NURBSMirrorSurface - NURBSSurface 1437
NURBSMultiCurveTrimSurface - NURBSSurface
1438
NURBSNBlendSurface - NURBSSurface 1439
NURBSObject
NURBSControlVertex 1409
NURBSCurve 1409
NURBSPoint 1403
NURBSSurface 1425
NURBSTexturePoint 1446
NURBSObject - Value 1402
NURBSOffsetCurve - NURBSCurve 1417
NURBSOffsetSurface - NURBSSurface 1440
NURBSPoint
NURBSCurveConstPoint 1403
NURBSCurveIntersectPoint 1404
NURBSCurveSurfaceIntersectPoint 1405
NURBSIndependentPoint 1406
NURBSPointConstPoint 1407
NURBSSurfConstPoint 1407
NURBSPoint - NURBSObject 1403
NURBSPointConstPoint - NURBSPoint 1407
NURBSPointCurve
NURBSPointCurveOnSurface 1419
NURBSPointCurve - NURBSCurve 1418
NURBSPointCurveOnSurface - NURBSPoint-
Curve 1419
NURBSPointSurface - NURBSSurface 1441
NURBSProjectNormalCurve - NURBSCurve
1420
NURBSProjectVectorCurve - NURBSCurve 1421
NURBSRuledSurface - NURBSSurface 1442
NURBSSelection - Value 1448
NURBSSet - Value 1450
NURBSSurf - GeometryClass 943
NURBSSurface
NURBS1RailSweepSurface 1427
NURBS2RailSweepSurface 1429
NURBSBlendSurface 1430
NURBSCapSurface 1432
NURBSCVSurface 1433
NURBSExtrudeSurface 1435
NURBSFilletSurface 1436
NURBSLatheSurface 1437
NURBSMirrorSurface 1437
NURBSMultiCurveTrimSurface 1438
NURBSNBlendSurface 1439
NURBSOffsetSurface 1440
NURBSPointSurface 1441
NURBSRuledSurface 1442
NURBSULoftSurface 1443
NURBSUVLoftSurface 1444
NURBSXFormSurface 1445
NURBSSurface - NURBSObject 1425
NURBSSurfaceApproximation - Value 1453
NURBSSurfaceEdgeCurve - NURBSCurve 1422
NURBSSurfaceNormalCurve - NURBSCurve
1422
NURBSSurfConstPoint - NURBSPoint 1407
NURBSSurfSurfIntersectionCurve - NURBSCur-
ve 1423
NURBSTexturePoint - NURBSObject 1446
NURBSTextureSurface - Value 1455
NURBSULoftSurface - NURBSSurface 1443
NURBSUVLoftSurface - NURBSSurface 1444
NURBSXFormCurve - NURBSCurve 1424
NURBSXFormSurface - NURBSSurface 1445
O
object hierarchies
time and key functions on 1299
object hierarchy xxxii
object path names 662
objects
and classes in object-oriented program-
ming lxii
property inspection 799
scene xxxii
use of xxxiii
 Index 1857

ObjectSet values 781 use of ? symbol xli

OilTank - GeometryClass 866 overview of the principal NURBS classes 1386
Ok value 754
OldBoolean - GeometryClass 887 P
OLE automation 1671 Paint - TextureMap 1266
Omnilight - light 972 panes
on cursor placement xxxvi
mouse tool event handlers 1531 defined in listener window xxxvi
rolloutfloater event handlers 1474 editing xxxvi
utility/rollout event handlers 1474 error messages xxxviii
on detachedFromNode For Object Scripted executing code xxxvi
Plug-ins 106 macro recorder xxxviii, l
on MAX Objects Now Takes Subanim Names mini listener xxxvi
139 output xxxviii
On_Off - FloatController 1323 parameter blocks 1542
On_Off controller keys 1323 parameter ranges for curves and surfaces 1391
online reference Parameter Wiring 85
searching in 1718 parameters - functions 702
using HTML help viewer 1715 PArray - GeometryClass 913
open particle space warps 1003
editor windows commands xlvi particle systems
script Blizzard 906
listener window command xxxviii common properties
open() 1079 operators
openBitMap() 755 and methods 905
opening PArray 913
editor window xxxiv PCloud 923
editor windows xliv Snow 931
file open dialog xxxiv Spray 933
listener window xxxiv SuperSpray 935
MAXScript 579 particle systems - Geometry 904
operands 669 Particle_Age - TextureMap 1266
operations with strings 588 Particle_MBlur - TextureMap 1267
operators lxiv particleMesher - superclass GeometryClass 306
Optimize - Modifier 1148 paste
options const StructDef 245 editor windows command xlvi
Orientation Constraint Controller 40 listener window command xxxviii
Orientation_Behavior ReferenceTarget 1794 patch - GeometryClass 1088
Orientation_Constraint - superclass Rotation- patch const StructDef 245
Controller 306 patch objects
Orientation_Constraint interfaces 462 Patch 1088
Other Interfaces 71, 432 Quadpatch 903
Output - TextureMap 1265 TriPatch 904
output pane patch objects - Geometry 903
error messages liii Patch_Select - superclass modifier 307
listener window xxxvi, xxxviii PatchDeform - modifier 1150
running scripts xlix
1858 Index
Patches 55
patchOps const StructDef 247
path - PositionController 1324
path interfaces 462
Path_Constraint - superclass PositionController
307
Path_Constraint interfaces 468
Path_Follow - SpacewarpObject 1025
Path_Follow_Behavior ReferenceTarget 1796
PathDeform - Modifier 1151
PathName
literals 662
values 780
pausing script execution 1664
PBomb - SpacewarpObject 1006
PCloud - GeometryClass 923
PDynaFlect - SpacewarpObject 1019
PDynaflector - superclass SpacewarpObject 309
Perlin_Marble - TextureMap 1268
persistent global variables 651
persistents const StructDef 247
PhyBlendingRigidVertex Values 1459
PhyContextExport Values 1458
PhyRigidVertex Values 1459
physique - modifier 1458
pickbutton 1504
picking
points in the viewports 1589
scene nodes by hit 1618
scene nodes by name 1619
scene nodes by region 1620
pivot - GeometryClass 899
pivoted - GeometryClass 900
plane - GeometryClass 867
Plane_Angle - superclass helper 310
PlaneAngleManip - superclass helper 311
planet - TextureMap 1269
Plug In Manager 86
Plugin_Manager interfaces 473
plug-ins
defining lvi
scripted 1538
point - helper 980
Point Cache Modifier 26
Point_Cache - superclass modifier 314
Point_Cache interfaces 484
Point_CacheSpacewarpModifier - superclass
SpacewarpModifier 315
Point_CacheSpacewarpModifier interfaces 485
Point_Curve - Shape 965
Point_Surf - GeometryClass 943
Point2
literals 665
values 736
Point3
literals 665
values 731
point3_list interfaces 475
Point3_Reactor interfaces 477
Point3_Wire interfaces 477, 570
Point3Controller - MAXWrapper 1302
Point3List - superclass Point3Controller 312
Point3List interfaces 479
Point3Reactor - superclass Point3Controller
312
Point3Reactor interfaces 481
Point3Spring - superclass Point3Controller 313
Point3Spring interfaces 482
PointCache - superclass modifier 316
PointCache interfaces 486
PointCacheWSM - superclass SpacewarpModifi-
er 317
PointCacheWSM interfaces 487
PointHelperObj - superclass helper 318
Poly_Select - superclass modifier 319
polymorphism lxiii, 672
polyop const StructDef 248
polyOps const StructDef 251
POmniFlect - SpacewarpObject 1027
Portable_Network_Graphics interfaces 473
Position Constraint 41
Position_Constraint - superclass PositionCon-
troller 320
Position_Constraint interfaces 488
position_list interfaces 490
Position_Reactor interfaces 492
Position_Wire interfaces 492
positional arguments 676
PositionController
Attachment 1304
Path 1324
SurfacePositionController 1334
PositionController - MAXWrapper 1303
PositionList - superclass PositionController 321
 Index 1859

PositionList interfaces 494 R

PositionReactor - superclass PositionController radiobuttons 1506
321 radiusManip interfaces 500
PositionReactor interfaces 496 RAMPlayer() 1617
PositionSpring - superclass PositionController random numbers 588
321 random() 588
PositionSpring interfaces 497 ray values 737
precedence Raytrace - TextureMap 1271
function calls and parameters 677 RayTraceMaterial - Material 1212
rules 672 RCMenu
predefined global variables 629 clauses 1515
preferences user-interface items 1518
auto open listener on output xxxvi RCMenu User-Interface Item
useLargeVertexDots 1603 menuItem 1518
useTransformGizmos 1603 separator 1519
useVertexDots 1603 subMenu 1520
preferences onst StructDef 252 Reactor controller 91
preserve - modifier 1152 reactor controllers 1326
prism - GeometryClass 868 Readable/Writable Checks 135
progress bar display 1578 recorder - macro l
progressBar 1505 recording commands xxxii
progressCB 28, 107 rectangle - shape 958
projected - GeometryClass 901 reference assignment 653
prompt line 1577 refineSegment() 1079
properties lxiv Reflect_Refract - TextureMap 1276
dynamic 805 Reflection - superclass MAXObject 323
nested objects 815 reflectionRenderElement - superclass MAXOb-
protractor - helper 981 ject 324
ProxSensor - helper 989 Refraction - superclass MAXObject 326
PRS - Matrix3Controller 1325 refractionRenderElement - superclass MAXOb-
PSpawnflector - superclass SpacewarpObject ject 327
322 refreshing the viewports 1585
punctuation refs const StructDef 252
and symbols 627 relax - modifier 1154
in MAXScript code lvii Render Element Manager 92
push - modifier 1153 render scene dialog 1611
PushSpaceWarp - SpacewarpObject 1008 render() Function Re-entrant 160
pyramid - GeometryClass 869 RenderEffect
Blur 1349
Q Brightness_and_Contrast 1353
Quad Menu 90 Color_Balance 1354
quadpatch - GeometryClass 903 common properties
Quat Values 738 operators
QuatController - MAXWrapper 1304 and methods 1347
quitMAX() lvii Depth_of_Field 1354
File_Output 1356
Film_Grain 1356
1860 Index

Lens_Effects 1357 visibility of locals

Lens_Effects - Auto_Secondary 1360 functions
Lens_Effects - Glow 1363 structures and UI items 1478
Lens_Effects - Manual_Secondary 1366 rollout
Lens_Effects - Ray 1370 accessing locals and other items from ex-
Lens_Effects - Ring 1373 ternal code 1480
Lens_Effects - Star 1376 clauses 1470
Lens_Effects - Streak 1379 event handlers 1474
scripted plug-ins 1566 floater windows 1477
Types 1348 options
RenderEffect - MAXWrapper 1347 list of xxxiv
RenderEffect Progress Callback Mechanism 28, properties
107 methods
RenderElementMgr interfaces 503 and event handlers 1474
Renderer 162 rollout - value 1463
Renderer Anti-Aliasing Filters 1614 Rollout .Controls Property 187
Repel_Behavior 1798 Rollout Floaters as Extended viewports 186
replace rollout user-interface controls
editor windows command xlvi bitmap 1487
listener window command xxxviii button 1488
replacing text - editor windows xliv checkbox 1489
reserved checkbutton 1490
global variables 628 colorpicker 1492
keywords 625 combobox 1493
punctuation 625 Common Layout Parameters 1483
symbols 625 Common Properties 1481
variables 625 dropdownlist 1494
resetShape() 1079 edittext 1496
resetting 3ds max 1669 image buttons 1513
return expression 705 label 1497
reverse() 1079 listbox 1497
reverse() - splineOps 1079 mapbutton 1499
RGB Controllers 1335 materialbutton 1500
RGB_Multiply - TextureMap 1278 pickbutton 1504
RGB_Tint - TextureMap 1278 progressbar 1505
right-click menu radiobuttons 1506
editor windows xlvi slider 1507
HTML help viewer 1722 spinner 1509
listener window xxxviii timer 1512
scripted 1515 Types 1484
right-click menus 1514 RolloutFloater - Value 1477
RingArray - System 992 rollouts
RingWave - GeometryClass 870 closing xxxiv
RingWave - superclass GeometryClass 328 creating new scripts xliv
ripple - modifier 1154 developing l
Rollout loading lvi
user-interface controls 1481 reexecuting script l
 Index 1861

run script option xlix scope of variables 646

updating l script controller dialog - aborting code lv
utilities l script controllers 1329
Rollup Systems 188 script files
rotate() 598 and editor windows xliv
rotation_list interfaces 505 example scripts 624
Rotation_Reactor interfaces 507 executing content xlix
Rotation_Wire interfaces 508, 572 global scope xlix
RotationController - MAXWrapper 1303 inserting into code lix
RotationList - superclass RotationController nesting lix
328 run existing xlix
RotationList interfaces 510 running from the command line lvii
RotationReactor - superclass saving xliv
RotationController 328 startup lvi
RotationReactor interfaces 512 Scripted Cameras 94
RubberBanding in pickObject() Function 136 Scripted Custom Attributes 45
run script Scripted Manipulators 97
listener window command xxxviii scripted mouse tool event handlers 1531
running code scripted mouse tools 1531
aborting lv scripted plug-ins
conflicts with 3D Studio MAX lv Atmospheric 1569
running scripts xxxiv, xlix, lvii clauses 1542
running the OLE demo 1674 defining 1538
runtime - detecting errors liii geometry 1555
Helper 1561
S Light 1561
Sample Scripts 1730 Material 1565
save as methods 1551
editor windows commands xlvi Modifier 1562
listener window command xxxviii RenderEffect 1566
save() 755 Shape 1560
Saving your Commands in a Script File 621 SimpleMod 1563
scale() 598 SimpleObject 1556
scale_list interfaces 513 TextureMap 1566
Scale_Reactor interfaces 515 updating 1553
Scale_Wire interfaces 515, 574 scripted plugins events 93
ScaleController - MAXWrapper 1304 scripted right-click menus 1514
ScaleList - superclass ScaleController 328 scripted utilities l, 1463
ScaleList interfaces 517 available
ScaleReactor - superclass ScaleController 329 list of xxxiv
ScaleReactor interfaces 519 defining xxxiv
scanlineRender const StructDef 252 scripted utility panels 1464
Scatter - GeometryClass 891 Scripted_Behavior ReferenceTarget 1799
Scene File Properties 1628 scripting vertex and control point animation
Schematic View 1615 1461
schematicView const StructDef 252 scripts
and sub-objects l
1862 Index

automatic loading lvi setIndexedPixels() 755

choosing existing xxxiv setInVec() 1079
creating new xliv SetIterations() - ik 1313
description of purpose 624 setKnotPoint() 1079
included with 3DS MAX 624 setKnotSelection() 1079
installing as toolbar buttons xxxii setKnotType() 1079
interrupt detection lv setOutVec() 1079
managing large scripts lix setPixels() 755
navigating large scripts xlvi setSegmentType() 1079
new in editor windows xlvi setSegSelection() 1079
packaging xxxii setSilentMode() 755
running xxxiv, xlix setSplineSelection() 1079
runtime errors liii SetStartTime() - ik 1313
stepping through 624 Setting explosion start and end times for Com-
writing new xxxiv bustion 1341
SDeflector - SpacewarpObject 1030 setting up MAXScript OLE automation 1673
SDynaFlect - SpacewarpObject 1020 ShadowRenderElement - superclass MAXObject
SDynaflector - superclass SpacewarpObject 329 332
searching Shape
for help topics 1718 scripted plug-ins 1560
searching text SplineShape 1079
editor windows xliv shape
listener window xxxvii Arc 949
restricting xlvi Circle 950
restrictions xxxviii common properties
section - shape 959 operators
section - superclass shape 330 and methods 945
Seek_Behavior ReferenceTarget 1807 CV_Curve 964
select all Donut 951
editor windows command xlvi Ellipse 953
listener window command xxxviii Helix 954
Select by Name 1619 Line 955
selectBitMap() 755 NGon 957
selecting text - multiple lines xxxviii Node 944
Selection Filter 61 NURBS Curves 964
selection-relative scene objects l Point_Curve 965
SelectionSet values 785 Rectangle 958
SelectionSetArray values 783 Section 959
selectSaveBitMap() 755 Splines 947
Self_Illumination - superclass MAXObject 331 Star 960
separator 1519 Text 962
set context 689 ShapeMerge - GeometryClass 893
SetBackground Method 180 shellac - material 1233
SetDir 136 short-circuiting logical expressions 675
SetEndTime() - ik 1313 Shortcut system replaced 137
setFirstKnot() 1079 showClass() 593
setFirstSpline() 1079 showTextureMap() function 167
 Index 1863

silentMode() 755 SpacewarpModifier

simple expressions 669 Displace_Mesh 1198
skew - modifier 1155 Displace_NURBS 1198
skin - modifier 1157 MapScaler 1198
skinOps const StructDef 253 SpaceCameraMap 1199
skipping loop iterations 696 SpacePatchDeform 1199
slave controllers 1333 SpacePathDeform 1200
Slave_Control - Matrix3Controller 1333 SpaceSurfDeform 1201
SliceModifier - modifier 1165 SpaceWarp Binding 1196
slider 1507 Surface_Mapper 1202
sliderManipulator - superclass helper 333 Types 1100
sliderManipulator interfaces 520 SpacewarpModifier - MAXWrapper 1095
SlidingDoor - GeometryClass 901 SpacewarpObject
SlidingWindow - GeometryClass 902 Bomb 993
smoke - TextureMap 1279 ConformSpaceWarp 995
smooth - Modifier 1166 Deflector 1024
snapMode 182 Gravity 1003
snapMode const StructDef 254 Motor 1004
snow - GeometryClass 931 Path 1025
SOmniFlect - SpacewarpObject 1031 PBomb 1006
sound - helper 989 PDynaFlect 1019
source code layout 580 POmniFlect 1027
source code layout and continuation lines lvii PushSpaceWarp 1008
Space_Warp_Behavior 1809 SDeflector 1030
SpaceBend - SpacewarpObject 1011 SDynaFlect 1020
SpaceCameraMap - SpacewarpModifier 1199 SOmniFlect 1031
SpaceDisplace - SpacewarpObject 996 SpaceBend 1011
SpaceFFDBox - SpacewarpObject 998 SpaceDisplace 996
SpaceFFDCyl - SpacewarpObject 999 SpaceFFDBox 998
SpaceNoise - SpacewarpObject 1012 SpaceFFDCyl 999
SpacePatchDeform - SpacewarpModifier 1199 SpaceNoise 1012
SpacePathDeform - SpacewarpModifier 1200 SpaceRipple 1001
SpaceRipple - SpacewarpObject 1001 SpaceSkew 1014
spaces and other special characters in path- SpaceStretch 1015
names 665 SpaceTaper 1016
SpaceSkew - SpacewarpObject 1014 SpaceTwist 1017
SpaceStretch - SpacewarpObject 1015 SpaceWave 1002
SpaceSurfDeform - SpacewarpModifier 1201 UDeflector 1033
SpaceTaper - SpacewarpObject 1016 UDynaFlect 1022
SpaceTwist - SpacewarpObject 1017 UOmniFlect 1034
Spacewarp Wind 1010
Dynamics Interface 1018 SpacewarpObject - Node 992
Geometric/Deformable 993 SpaceWave - SpacewarpObject 1002
Modifier-Based 1011 special characters in pathnames 665
Particles Only 1024 special data values 753
Spacewarp - particles and dynamics 1003 special notes about function calls 678
SpaceWarp Binding SpacewarpModifiers 1196 speckle - TextureMap 1280
1864 Index

Specular - superclass MAXObject 334 unbind() 1079

specularRenderElement - superclass MAXOb- unhideAll() 1079
ject 335 weld() 1079
Speed_Vary_Behavior ReferenceTarget 1809 splineOps const StructDef 255
sphere - GeometryClass 872 SplineSelect - modifier 1167
SphereGizmo - helper 983 SplineShape - shape 1079
spherify - modifier 1167 spray - GeometryClass 933
spindle - GeometryClass 873 spring - GeometryClass 883
spinner 1509 Spring Controller 109
Spinner UI Item setKeyBrackets 182 SpringPoint3Controller - superclass
splat - TextureMap 1281 Point3Controller 336
spline SpringPositionController - superclass Position-
common properties Controller 337
operators SpringPositionController interfaces 526
and methods 947 squeeze - modifier 1167
Shape 947 SSpawnflector - superclass SpacewarpObject
splineOps 338
attachMultiple() 1079 standard objects - geometry 852
close() 1079 standard open and save file dialogs 1643
cycle() 1079 StandardMaterial - material 1224
delete() 1079 StandardXYZGen - material 1238
detach() 1079 star - shape 960
divide() 1079 startAttach() - splineOps 1079
explode() 1079 startBind() - splineOps 1079
hide() 1079 startBreak() - splineOps 1079
intersect() 1079 startChamfer() - splineOps 1079
makeFirst() 1079 startConnect() - splineOps 1079
mirrorBoth() 1079 startCreateLine() - splineOps 1079
mirrorHoriz() 1079 startCrossInsert() - splineOps 1079
mirrorVert() 1079 startExtend() - splineOps 1079
reverse() 1079 startFillet() - splineOps 1079
startAttach() 1079 startInsert() - splineOps 1079
startBind() 1079 startObjectCreation() 138
startBreak() 1079 startOutline() - splineOps 1079
startChamfer() 1079 startRefine() - splineOps 1079
startConnect() 1079 startRefineConnect() - splineOps 1079
startCreateLine() 1079 startSubtract() - splineOps 1079
startCrossInsert() 1079 startTrim() - splineOps 1079
startExtend() 1079 startUnion() - splineOps 1079
startFillet() 1079 startup
startInsert() 1079 MAXScript xxxiv
startOutline() 1079 organizing scripts lvi
startRefine() 1079 script files lvi
startRefineConnect() 1079 scripts directory lvii
startSubtract() 1079 status bar 1577
startTrim() 1079 status bar buttons 1579
startUnion() 1079 sticky contexts 689
 Index 1865

STL_Check - modifier 1169 system global variables 630

storing desktop state lvi System Information 141
stream values 763 System Tools 112
stretch - modifier 1170 systemTools const StructDef 256
String
literals 660 T
values 722 tape - helper 981
string operations 588 taper - modifier 1173
string variables 585 Targa interfaces 529
StringStream values 766 TargetCamera - camera 976
struct 707 TargetDirectionalLight - light 972
structure definition 707 TargetObject - GeometryClass 874
structure definitions 618 TargetSpot - Light 973
structure inherited methods 711 TCB controller keys 1335
stucco - TextureMap 1282 TCB controllers 1334
subAnims 806 teapot - GeometryClass 875
sub-expressions terrain - GeometryClass 894
displaying values xxxviii terrainOps const StructDef 256
line breaks lvii tessellate - modifier 1174
subMenu 1520 TexOutputClass - material 1239
sub-object transform properties 1099 text
subtraction - mesh 852 and editor windows xliv
Sunlight - System 991 capturing xli
Sunlight_Slave_Controller 991 color coding xxxvii
superclasses read-only global variable 139 dragging to toolbars xxxviii
SuperSpray - GeometryClass 935 editing in listener window xxxviii
surface - modifier 1171 evaluating selection xxxviii
Surface_Arrive_Behavior MAXObject 1811 executing current xxxviii
Surface_Follow_Behavior ReferenceTarget 1814 in current bracket xxxviii
Surface_Mapper - SpacewarpModifier 1202 inserting new xxxviii
SurfacePositionController - PositionController restoring xxxviii
1334 restricting search xlvi
SurfDeform - modifier 1171 searching in listener window xxxvii
swirl - TextureMap 1283 selecting multiple lines xxxviii
Symbolic Pathnames 140 syntax coloring xlvi
symbols 627 text - shape 962
syntax lx text file input and output 1643
syntax definitions in this document lx TextureMap
sysInfo const StructDef 255 Adobe_Photoshop_Plug_In_Filter 1241
System Adobe_Premiere_Video_Filter 1242
Bones 991 BitmapTexture 1243
RingArray 992 Bricks 1245
Sunlight 991 Cellular 1247
system Checker 1249
Biped 1456 common properties
System - Node 991 operators
system directories 1625
1866 Index

and methods 1235 timeConfiguration const StructDef 256

CompositeTextureMap 1250 timer 1512
Dent 1251 Timer UI element 183
Falloff 1252 TimeSensor - yelper 990
FalloffTextureMap 1255 TimeSlider on/off toggle 183
FlatMirror 1255 tokens
Gradient 1257 comments lvii
Gradient_Ramp 1259 inserting files lix
Marble 1261 tool
Mask 1262 clauses 1532
Mix 1262 toolbar
Noise 1263 HTML help viewer 1721
NoTexture 1265 toolbar buttons
Output 1265 creating in macro script l
Paint 1266 installing with scripts xxxii
Particle_Age 1266 toolMode const StructDef 257
Particle_MBlur 1267 tools
Perlin_Marble 1268 scripted mouse 1531
Planet 1269 scripting for specific job xxxii
Raytrace 1271 selecting in macro recorder l
Reflect_Refract 1276 TopBottom - material 1233
RGB_Multiply 1278 torus - GeometryClass 875
RGB_Tint 1278 Torus_Knot - GeometryClass 877
scripted plug-ins 1566 TouchSensor - Helper 990
Shared Classes 1236 trace-back of call stack liii
Smoke 1279 Track View 1609
Speckle 1280 Track View nodes 1382
Splat 1281 Track View Pick Dialog 1617
Stucco 1282 trackbar 1581
Swirl 1283 trackbar const StructDef 257
Thin_Wall_Refraction 1284 trackView const StructDef 257
Types 1240 Trackviews 114
Vertex_Color 1285 transform properties - sub-object 1099
Water 1286 transform_script - superclass Matrix3Controller
Wood 1287 339
TextureMap - Material 1234 transformation
The Super Class ID and the Class ID 141 moving 598
Thin_Wall_Refraction - TextureMap 1284 rotating 598
third-party plug-in classes 808 scaling 598
throw() 697 transformations 603
time change callback 1654 trigonometric functions 1675
time configuration dialog 1616 Trim_Extend - modifier 1175
time control 1580 TriMesh 1041
time data values 751 TriPatch - GeometryClass 904
time literal 662 try expression 697
time stamping 1664 tube - GeometryClass 878
time values 751 Turn_to_Mesh - superclass modifier 340
 Index 1867

Turn_to_Patch - superclass modifier 342 and modify 3ds max NURBS models 1389
Turn_to_Poly - superclass modifier 343 USpawnDeflector - superclass SpacewarpObject
twist - modifier 1175 346
type #integer parameters in scripted plug-in pa- utilities
rameter blocks 93 defining l
type-free variables 653 list in MAXScript l
scripted l
U displaying xxxiv
-U switch (command line) lvii Utilities Global Utilities and Render Element
UDeflector - SpacewarpObject 1033 plug-ins 161
UDynaDeflector - superclass SpacewarpObject utility
345 clauses 1466
UDynaFlect - SpacewarpObject 1022 event handlers 1474
UI setting - customizing lvi managing multiple rollouts 1468
unbind() - splineOps 1079 properties
unBindKnot() 1079 methods
undefined value 753 and event handlers 1474
unDisplay() 755 scripted 1463
undo scripted utility panels 1464
editor windows commands xlvi utility panel xxxiv, l
listener window command xxxviii UVGenClass - material 1237
undo context 687 UVW_Xform - modifier 1187
Undo/Redo Dropdown Labels 184 UVWmap - modifier 1188
unhideAll() - splineOps 1079 uvwMappingHeightManip interfaces 551
unhidesegments() 1079 uvwMappingLengthManip interfaces 555
union - mesh 852 uvwMappingUTileManip interfaces 558
units const StructDef 258 uvwMappingVTileManip interfaces 562
unsupplied value 754 uvwMappingWidthManip interfaces 565
Unwrap_UVW - modifier 1176 UVWUnwrap - superclass modifier 347
Unwrap_UVW interfaces 530 UVWUnwrap interfaces 568
UOmniFlect - SpacewarpObject 1034
updateBindList() 1079 V
updateChangedXRefs() - xrefs 1038 validModifer() function 142
updateShape() 1079 Value
updateXRef() 1038 NURBSDisplay 1447
updating scripted plug-ins 1553 NURBSSelection 1448
useLargeVertexDots - preferences 1603 NURBSSet 1450
user interface colors 1604 NURBSSurfaceApproximation 1453
user-defined properties - node methods 848 value
useTransformGizmos - preferences 1603 Array 776
useVertexDots - preferences 1603 ArrayParameter 770
using BigMatrix 748
HTML help viewer 1715 BigMatrixRowArray 748
listener xxxvii BipedExportInterface 1458
MAXScript documentation xxxiii BitArray 791
using the NURBS classes and functions to create Bitmap 755
1868 Index

Boolean 728 WindowStream 767

Box2 750 working with 716
ChangeHandler 1650 XRefScene 1038
Color 729 variables 585
common properties 3ds max system globals 630
operators and ? symbol xli
and methods 714 assignment to 643
DontCollect 754 functions 701
EdgeSelection 790 global scope lix
EulerAngles 742 MAXScript system global 640
FaceSelection 788 persistent globals 651
FileStream 763 predefined globals 629
general 713 reference assignment 653
Interval 752 reserved global 628
MaterialLibrary 795 scope 643, 646
Matrix3 744 type free 653
MAXKey 767 variables - 3ds max system globals
MAXKeyArray 793 preferences.useLargeVertexDots 1603
MAXNoteKey 818 preferences.useTransformGizmos 1603
MAXNoteKeyArray 817 preferences.useVertexDots 1603
MAXWrapper 808 vector arithmetic 1677
ModifierArray 794 Vector_Field SpacewarpObject 1821
Name 727 vertex animation 1461
NodeChildrenArray 785 Vertex_Color - TextureMap 1285
Notetrack 816 Vertex_Colors - modifier 1191
NURBSObject 1402 VertexPaint - modifier 1191
ObjectSet 781 VertexSelection values 786
Ok 754 viewport
PathName 780 background images 1586
PhyBlendingRigidVertex 1459 displaying listener windows xxxvi
PhyContextExport 1458 drawing methods 1592
PhyRigidVertex 1459 grids 1587
Point2 736 info 1581
Point3 731 redraw callback 1655
Quat 738 refreshing 1585
Ray 737 transforms 1581
RCMenu 1514 type 1581
Rollout 1463 viewport const StructDef 258
RolloutFloater 1477 visibility of locals functions structures and user-
SelectionSet 785 interface items in rollout code 1478
SelectionSetArray 783 Visible Class For 142
String 722 Visual MAXScript 117
StringStream 766 Volume_Fog - atmospheric 1343
Time 751 Volume_Light - atmospheric 1344
Undefined 753 VolumeSelect - modifier 1192
Unsupplied 754 Vortex - superclass SpacewarpObject 156, 347
VertexSelection 786 VRML_VRBL - helper 985
 Index 1869

VRML97 - helper 985 XYZ Controllers 1335

W Z
Wall_Repel_Behavior MAXObject 1816 Z_Depth - superclass MAXObject 350
Wall_Seek_Behavior MAXObject 1817 Zip-file Script Packages 122
Wander_Behavior ReferenceTarget 1819 Zoom to Bounds 184
water - TextureMap 1286 ZRenderElement - superclass MAXObject 351
wave - modifier 1194
Waveform_Float - FloatController 1335
WAVsound const StructDef 258
weld() - splineOps 1079
What 1
when construct 1650
while loop exit 697
while/do expression 694
wind - SpacewarpObject 1010
window objects - geometry 896
WindowStream values 767
with - loop exit 697
with animate context 683
wood - TextureMap 1287
working with
Atmospherics 1345
Editable Meshes 1077
MAXKey Values 769
Note Tracks 818
NURBS 1384
Values 716
working with the NURBS classes 1385

X
XForm - Modifier 1195
XRef files 1643
Xref Objects API 120
XRefObject - Node 1037
xrefPaths const StructDef 259
xrefs
addNewXRefFile() 1038
attemptUnresolvedXRefs() 1038
deleteAllXRefs() 1038
findUnresolvedXRefs() 1038
getXRefFile() 1038
getXRefFileCount() 1038
updateChangedXRefs() 1038
xrefs const Structdef 259
XRefScene Values 1038
1870 Index