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