VERSION FOUR

www.discreet.com

4

MAXSCRIPT REFERENCE

January 2001

Copyright 2001 Autodesk, Inc.All Rights ReservedThis 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 TrademarksThe 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, AutoArchitect, 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 TrademarksAll other brand names, product names, or trademarks belong to their respective holders.

Third-Party Software Program CreditsACIS 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........................................................................................................xxxi3ds 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 Whats New in 3ds max 4 MAXScript .................................................... 1 Whats 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 ............................................................................................