VERSION FOUR

www.discreet.com

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

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

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) Whats 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 its 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 Whats 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 inputTextColor outputTextColor messageTextColor black blue red Default Color

typed input text output text error message text

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 Listeners 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 commands 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 isnt 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 logs buffer is flushed so that all output is written to the file:
flushLog()

You can stop logging, flush the logs 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 panes 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 -- than inside just -- expression ( setListenerSel #(0,-1) -ListenerText=getListenerSelText() -setListenerSel #(-1,-1) --) so its scope is higher the following block select all the text get selected text 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 files 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 dont 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 functions definition. The form is:
showSource <fn>

xlvi

Chapter

Introduction

A MAXScript Editor window has the following features: Titles that display only the current scripts 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 Windows 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 windows scroll position does not change.

MAXScript Editor Commands

xlvii

Edit > Undo, CTRL+Z Undoes the last change made to the MAXScript Editors 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

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 utilitys 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 doesnt 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

[...] (...|...|...) {...} {...}+ ::= <rule> bold_characters

-- 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 -- you can insert what is defined by the named rule -- characters or token as written

The previous number syntax example is interpreted as follows:

Syntax [-]{<digit>} [.{<digit>}] [(e | E)[+ | -]{<digit>}+] Definition an optional minus sign (the sign), followed by 0 or more digits (the integer part), followed by an optional sequence (the fraction part) comprised of: a period character, followed by 0 or more digits, followed by 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 objectoriented languages. Weve 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 well 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. Well 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:

Whats New in 3ds max 4 MAXScript

Whats 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, ParamBlock2s 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.

Chapter 1

Whats 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)

Whats New in 3ds max 4 MAXScript

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)

Chapter 1

Whats 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)

Whats New in 3ds max 4 MAXScript

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)

Chapter 1

Whats 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)

Whats New in 3ds max 4 MAXScript

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)

Chapter 1

Whats 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)

Whats New in 3ds max 4 MAXScript

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

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

Whats 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 labellblStatuspos:[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

Whats 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

Whats 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

Whats 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 youll 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

Whats 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

Whats 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

Whats 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 Maxs 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

Whats 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

Whats 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

Whats 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()

Whats 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

Whats 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 bones 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 parents 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 bones 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

Whats 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

Whats 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 objects 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

Whats 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 IDd sets, and can be deleted individually or all callback scripts in and IDd 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 dont 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

Whats 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 its 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 cant 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 wont 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

Whats 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 dont 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 frames 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 frames 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

Whats 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 #text #activeCommand #hilight #shadow #window windows #activeCaption #appWorkspace --------The The The The The The background for all controls and buttons text for all controls and buttons color command mode buttons turn when pressed hilight color for 3d controls shadow color for 3d controls background color for edit boxes, list boxes and other

36

Chapter 1

Whats 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 #repaintTrackBar #repaintTimeBar -- repaint all of MAXs UI. Can be slow. -- just repaint the track bar -- 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

Whats 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 Users 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 paths 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

Whats 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 objects orientation so that its 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 wont 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 objects 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 objects 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 targets 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 targets weight value defines how much it influences the constrained object. For example if a sphere is Position constrained between 2 targets and each targets 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

Whats 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

Whats 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 objects 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

Whats 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 objects 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

Whats 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 attribIDs 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 internallygenerated 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 box01s and box02s 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

Whats 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 objects custom attributes, you might use this sequence:
old_def = custAttributes.getDef $box03 1 old_def_data = custAttributes.getDefData old_def new_def_string = generate_new_def old_def_data ... custAttributes.redefine old_def new_def_string ----get existing def get my defData from it make 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 objects 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

Whats 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 blocks 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 parameters 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

Whats 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 cameras 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

Whats 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 MAXScripts 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 va = vab = vba = vb = vbc = vcb = vc = vcd = vdc = vd = vda = vad = i1 = i2 = i3 = i4 = sm = = The index of the patch to create (0> = index < numPatches). The first vertex. Vector ab. Vector ba. The second vertex. Vector bc. Vector cb. The third vertex. Vector cd. Vector dc. The fourth vertex. Vector da. Vector ad. Interior 1. Interior 2. Interior 3. Interior 4. 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 va = vab = vba = vb = vbc = vcb = vc = vca = vac = i1 = i2 = i3 = sm = = The index of the patch to create (0> = index < numPatches). The first vertex. Vector ab. Vector ba. The second vertex. Vector bc. Vector cb. The third vertex. Vector ca. Vector ac. Interior 1. Interior 2. Interior 3. 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> <integer_array> <integer_array> <integer> <integer_array> <integer> <integer> <integer> <integer> patch.getVertVecs <obj> <index> patch.getVertPatches <obj> <index> patch.getVertEdges <obj> <index> patch.getVecVert <obj> <index> patch.getVecPatches <obj> <index> patch.getEdgeVert1 <obj> <index> patch.getEdgeVert2 <obj> <index> patch.getEdgeVec12 <obj> <index> patch.getEdgeVec21 <obj> <index>

The following functions access and manipulate the texture mapping information in the patch object.
<integer> <boolean> patch.setNumMaps <obj> <num> [keep:<bool>] patch.getNumMaps <obj> patch.setMapSupport <obj> <map_chan> [init:<boolean>] patch.getMapSupport <obj> <map_chan> patch.maxMapChannels <obj> patch.setNumMapVerts <obj> <map_chan> <num> [keep:<boolean>] patch.getNumMapVerts <obj> <map_index>

<integer>

58

Chapter 1

Whats New in 3ds max 4 MAXScript

patch.setNumMapPatches <obj> <map_chan> <num> [keep:<boolean>] 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> <point3>

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

Whats 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

Whats 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-11D2ADE7-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

Whats 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: Heres 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

Whats 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 doesnt 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 systems 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 MAXs 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 Windows 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

Whats 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 $foos 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

Whats 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

Whats 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

Whats 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 wont 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

Whats 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 MAXs 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 maxs 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 MAXs main menu bar.

menuMan.setMainMenuBar menu

Sets the menu being used as MAXs 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

Whats 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 MAXs 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 MAXs 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

Whats 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 MAXs 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 its 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 MAXs 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

Whats 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 nodes 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 objects 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

Whats 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-B26000A0240CEEA3}\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

Whats 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

Whats 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

Whats 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

Whats 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

Whats 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. Doesnt look like any broadcasts are made after the new values are set, and if safe frames isnt 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

Whats 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 dont 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

Whats 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 objects 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

Whats 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 isnt 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. Thats 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

Whats 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

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

Whats 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

Whats 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 objects 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 points Mass and Drag, the springs 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

Whats 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

Whats 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

Whats 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 its index or name.

trackviews.open <fpvalue>name or index

You can now open a trackview based on its index or name.

trackviews.getTrackView <fpvalue>name or index

This method will get a trackview based on its 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 objects 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

Whats 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

Whats 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), youd 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

Whats 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 xrefd 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 objects 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 xrefd 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 xrefd. 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, youd say something like:
global s1, s2 dependsOn s1 s2 (s1.pos + s2.pos) / 2

Note this uses global not persistent global, so you dont go making them persistent again when they get xrefd 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

Whats 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

Whats 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

Whats 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

Whats 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 callers context as a parameter to a function and any assignments to that parameter in the called function will be assigned directly to the callers 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

Whats 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

Whats 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

Whats 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 $foos 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 cant 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

Whats 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 its 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, youll 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 actions tool tip. The parameters of actionMan.executeAction are the integer ActionTableId of the table the action comes

138

Chapter 1

Whats 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 doesnt 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

Whats 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() render()

in the fileName: parameter 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

Whats 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 doesnt 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 showInterfaces lst -- if this is a list controller -- 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

Whats 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

Whats 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. Its 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 <Hose>.Generate_Mapping_Coordinates Integer Integer default: 1 default: 0 --integer integer

Sets up required coordinates for applying mapped materials to the hose. Default=off.
<Hose>.Hose_Height float Float default: 1.0 -animatable;

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 Integer default: 45 -animatable;

The total number of segments in the hoses 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 Float default: 0.2 -animatable;

The maximum width of the hose at the ends.

Hose - superclass: GeometryClass

147

<Hose>.Round_Hose_Sides integer

Integer

default: 8

--

animatable;

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 Float default: 0.2 -animatable;

The width of the hose.

<Hose>.Rectangular_Hose_Depth float Float default: 0.2 -animatable;

The height of the hose.

<Hose>.Rectangular_Hose_Fillet_Size float Float default: 0.0 -animatable;

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 Integer default: 0 -animatable;

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 angle; Controller Scaling: (1 : 57.2958) <Hose>.D_Section_Hose_Width float Float default: 0.0 -animatable;

The orientation of the hose along its long axis. Default=0.

default: 0.2 -animatable;

The width of the hose.

<Hose>.D_Section_Hose_Depth float Float default: 0.2 -animatable;

The height of the hose.

<Hose>.D_Section_Hose_Fillet_Size float Float default: 0.0 -animatable;

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 Integer default: 0 -animatable;

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 Integer default: 8 -animatable;

The number of segments on the rounded side. Increase for a smoother profile. Default=4.
<Hose>.D_Section_Hose_Section_Rotation Float angle; Controller Scaling: (1 : 57.2958) default: 0.0 -animatable;

The orientation of the hose along its long axis. Default=0.

148

Chapter 1

Whats 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 hoses diameter is uniform throughout its length.
<Hose>.Flex_Section_Start Float percentage; Controller Scaling: (1 : 100.0) default: 10.0 -animatable;

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 percentage; Controller Scaling: (1 : 100.0) default: 90.0 -animatable;

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 Integer default: 5 -animatable;

The number of corrugations in the flex section. The number of visible cycles is limited by the number of segments; if Segments isnt 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 percentage; Controller Scaling: (1 : 100.0) default: -20.0 -animatable;

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 Float default: 100.0 -animatable;

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 Float default: 100.0 -animatable;

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 <Drag>.time off Time_Off <Drag>.symmetry Damping_Symmetry Integer Integer default: 0 -integer; Time_On -animatable; integer;

The frame numbers at which the space warp becomes active and becomes inactive.
default: 16000

The frame numbers at which the space warp becomes active and becomes inactive.
Integer default: 0 -radio button number;

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 X_Damping; Controller Scaling: (1 : 100.0) -animatable; percentage;

Specifies the percentage of particle motion along the local Drag space warp axis thats 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 X_Falloff Float default: 1000.0 -animatable; float;

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 Y_Damping; Controller Scaling: (1 : 100.0) -animatable; percentage;

Specifies the percentage of particle motion along the local Drag space warp axis thats affected by the damping.

150

Chapter 1

Whats 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 Y_Falloff Float default: 1000.0 -animatable; float;

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 Z_Damping; Controller Scaling: (1 : 100.0) -animatable; percentage;

Specifies the percentage of particle motion along the local Drag space warp axis thats 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 Z_Falloff Float default: 1000.0 -animatable; float;

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 Radial_Damping; Controller Scaling: (1 : 100.0) -animatable; percentage;

Radial specifies the percentage of particle motion toward or away from the center of the Drag icon thats affected by the damping. Tangential specifies the percentage of particle motion across the body of the Drag icon thats affected by the damping.
<Drag>.ranger Radial_Range Float default: 100.0 -animatable; float;

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 Radial_Falloff Float default: 1000.0 -animatable; float;

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 -Tangential_Damping; Controller Scaling: (1 : 100.0)

animatable; percentage;

Radial specifies the percentage of particle motion toward or away from the center of the Drag icon thats affected by the damping. Tangential specifies the percentage of particle motion across the body of the Drag icon thats affected by the damping.
<Drag>.rangegc Tangential_Range Float default: 100.0 -animatable; float;

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 Tangential_Falloff Float default: 1000.0 -animatable; float;

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 Radial_Damping; Controller Scaling: (1 : 100.0) -animatable; percentage;

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 icons long axis (Axial) thats affected by the damping, on a per-frame basis.
<Drag>.rangerc Radial_Range Float default: 100.0 -animatable; float;

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 Radial_Falloff Float default: 1000.0 -animatable; float;

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 -Tangential_Damping; Controller Scaling: (1 : 100.0) animatable; percentage;

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 icons long axis (Axial) thats affected by the damping, on a per-frame basis.

152

Chapter 1

Whats New in 3ds max 4 MAXScript

<Drag>.rangec Tangential_Range

Float

default: 100.0

--

animatable; float;

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 Tangential_Falloff Float default: 1000.0 -animatable; float;

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 Axial_Damping; Controller Scaling: (1 : 100.0) -animatable; percentage;

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 icons long axis (Axial) thats affected by the damping, on a per-frame basis.
<Drag>.rangeax Axial_Range Float default: 100.0 -animatable; float;

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 Axial_Falloff Float default: 1000.0 -animatable; float;

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 <Drag>.iconsize BooleanClass Float default: true default: 10.0 --boolean; Unlimited_Range 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 Integer default: 0 -animatable;

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 animatable; float Float default: 100.0 --

The modified objects 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

Whats 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 dont 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 subobject 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

Whats 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 <Vortex>.time off integer; Time_Off <Vortex>.axialstrength Axial_Drop_Strength <Vortex>.axialrange float; Axial_Range Integer Integer default: 0 -integer; Time_On -animatable;

The frame numbers at which the space warp becomes active and becomes inactive.
default: 16000

The frame numbers at which the space warp becomes active and becomes inactive.
Float default: 0.1 -animatable; float;

Specifies how quickly particles move in the direction of the drop axis.
Float default: 100.0 -animatable;

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; Axial_Falloff Float default: 1000.0 -animatable;

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 -percentage; Axial_Damping; Controller Scaling: (1 : 100.0) animatable;

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 Orbital_Speed_Strength Float default: 0.5 -animatable; float;

Specifies how quickly the particles rotate.

Vortex - superclass: SpacewarpObject

157

<Vortex>.rotationrange float; Orbital_Range

Float

default: 100.0

--

animatable;

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; Orbital_Falloff Float default: 1000.0 -animatable;

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 -percentage; Orbital_Damping; Controller Scaling: (1 : 100.0) animatable;

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 Radial_Pull_Strength <Vortex>.radialrange float; Radial_Range Float default: 0.5 -animatable; float;

Specifies the distance from the drop axis at which the particles rotate.
Float default: 100.0 -animatable;

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; Radial_Falloff Float default: 1000.0 -animatable;

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 -percentage; Radial_Damping; Controller Scaling: (1 : 100.0) animatable;

Controls the degree to which Radial Pull is restrained per frame. Default=5.0. Range=0 to 100.
<Vortex>.taperstrength float; Taper_Length Float default: 100.0 -animatable;

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 Taper_Curve Float default: 1.0 -animatable; float;

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

Whats New in 3ds max 4 MAXScript

<Vortex>.rangeless Unlimited_Range

BooleanClass

default: true

--

boolean;

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

Whats 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

Whats 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 spinner bar Bar checkBox baz Baz: on bar changed do ... )

-- now possible

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

Whats 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

Whats 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 arent 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

Whats 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.
rollout test Angle Test ( Angle ang2 Angle diameter:40 align:#center range:[-180,180,45] startdegrees:270 dir:#cw ) createdialog test 200 100

Example:

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

Whats New in 3ds max 4 MAXScript

Curve Control
Topic: version 4 MAXScript Language Improvements /User Interface

You can create CurveControls 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 points 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

Whats 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 Visiblechecked:true checkBox chk_enable Enablechecked: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

Whats 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 Curves 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

Whats 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

Whats 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 MAXs default main menu:

menuMan.setMainMenuBar Main Menu Bar

The function returns true of it succeeds and false if it cant 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

Whats 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 dont 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 #mousePoint #mouseMove #mouseAbout means means means means the the the the mouse is moved without a button left mouse button has just been mouse is being dragged with the right mouse button was clicked, being pressed pressed left button down 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 normals 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

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

Whats 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 quadmenu 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

Whats 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

Whats New in 3ds max 4 MAXScript

See Also
Rollout User-Interface Controls (p. 1481) Rollout User-Interface Controls Types (p. 1484) Rollout User-Interface Controls Common Properties (p. 1481) Rollout User-Interface Controls Common Layout Parameters (p. 1483)

Rollout Systems category Mechanism

Topic: version 4 MAXScript Language Improvements/User Interface/Command Panels and Rollout Pages You can control the grouping of rollups for a plug-in by supplying a category:<integer> header parameter, before the opening parenthesis of the rollout body. Example:
rollout foo Frabulator category:3 ( .... )

Category number orders the rollouts.

See Also
Rollout User-Interface Controls (p. 1481) Rollout User-Interface Controls Types (p. 1484) Rollout User-Interface Controls Common Properties (p. 1481) Customize The Order of Rollup Pages (p. 185) Interface: cmdPanel (p. 356) Rollout User-Interface Controls Common Layout Parameters (p. 1483) Visual MAXScript (p. 117)

version 4 All Const and MAXScript Functions

Definitions for MAXScript internal organization
MAXScriptFunction Const Generic Const MappedGeneric Const NodeGeneric Const Primitives Const StructDef

Definitions for MAXScript internal organization

189

Const Class When you say something like fn test val = ..., a MAXScriptFunction value is created and stored in variable test. If variable test was passed into another method, for example as a filter function, that method would test the class of the value to make sure its a MAXScriptFunction and then call it using apply(). The Const preceding the following simply says that it is a value that is created during MAXScript initialization. A Generic is one or more methods with the same name, but defined for different classes. Which method is called depends on the class of the first argument to the method. For example, random is declared as a Generic, and there are methods implementing random in several classes - Integer, Float, Point3, Color, Quat, etc. When MAXScript sees random v1 v2 in a script, it looks at the class of v1, and then calls the random method for that class. So if v1 were a float, MAXScript would call the Float::random() method. A MappedGeneric is the same as a Generic, but the first argument can be a collection. If it is a collection, the the method is called individually on each member of the collection. For example, deleteTime $box* 10f 10f deletes 10f at frame 10 in all keys in all objects named $box*. deleteTime can also be used on controllers, thats why it is a Generic A NodeGeneric is the same as a MappedGeneric, but its first argument has to be a node or a collection of nodes. But given the definition of Generic, that doesnt make much sense. If the first argument is a collection, and the method is applied to each member of the collection. Primitives are methods that arent class specific. The method is responsible for checking the types of its arguments (if any) and throwing an error if one isnt correct. There is only one definition of the Primitive. A StructDef is a structure value. If the structure value is created by a script, its class is StructDef. If MAXScript creates the structure during initialization, its class is Const StructDef. So, for example, my meshop methods are defined to exist in a structure called meshop. Since this structure is created during initialization, the class of meshop is Const StructDef. Const Class is just a class that is defined in MAXScript itself. So, for example, BitArray is a Const Class. MAXScript also scans the classes registered with MAX - these classes will be created in MAXScript as Const MAXClass.

190

Chapter 1

Whats New in 3ds max 4 MAXScript

See Also
MAXScriptFunction List (p. 190) Const Generic (p. 195) Const MappedGeneric (p. 207) Const NodeGeneric (p. 209) Const Primitives (p. 213) Const StructDef (p. 231) Const Class (p. 191)

MAXScriptFunction List
AddConstraint Controller Functions for use with Constraint Assignments (p. 42) Camera Common Properties, Operators, and Methods (p. 974) - in example Scripted Geometry Plug-ins (p. 1555) - in example Scripted Shape Plug-ins (p. 1560) - in example Scripted SimpleObject Plug-ins (p. 1556) - in example The Return Expression (p. 705) - in example Time Values (p. 751) AddConstraintTargets AddListController AddMod ApplyOperation ChangeSystemColorsAnimateOff ChangeSystemColorsAnimateOn help KindOfRenderElement RElements2cws SaveQuadClr SetActiveController show TurnToSeq Controller Functions for use with Constraint Assignments (p. 42) Apropos and ShowProperties and now Help and Show (p. 128) ApplyOperation function (p. 54) Controller Functions for use with Constraint Assignments (p. 42) Controller Functions for use with Constraint Assignments (p. 42)

See Also
Definitions for MAXScript internal organization (p. 188)

Const Class

191

Const Class
ActionPredicate ActiveXControl def AngleAxis AngleControl Array ArrayParameter AtmosphericClass BigMatrix ActiveX Controls in MAXScript Rollouts (p. 10) - in example with

BigMatrixRowArray

MAXScript Class Hierarchy (p. 1688) BigMatrix Values (p. 748) - in example with def Basic Data Values (p. 717) Const Generic (p. 195) links Const MappedGeneric (p. 207) MAXScript Class Hierarchy (p. 1688) BigMatrix Values (p. 748) - in example with def MAXScript Class Hierarchy (p. 1688)

BinStream BipedExportInterface BipedFSKey BipedGeneric BipedKey BitArray bitmap BitmapControl BooleanClass Box2 ButtonControl ccCurve ccPoint CCRootClass ChangeHandler CharStream CheckBoxControl CheckButtonControl class color ColorPickerControl ComboBoxControl Control CTBitMap CTMotionTracker CurveCtlGeneric CurvePointsArray EdgeSelection EditTextControl EffectClass EmptyClass EulerAngles FaceSelection

192

Chapter 1

Whats New in 3ds max 4 MAXScript

FileStream float Function Generic GeomObject GroupBoxControl GroupEndControl GroupStartControl HashTable ImgTag integer Interface InterfaceFunction Interval IObject LabelControl LinkControl ListBoxControl MapButtonControl MappedGeneric MappedPrimitive MapSupportClass MaterialLibrary Matrix3 MAXAKey MAXClass MAXCurveCtl MAXFilterClass MAXKey MAXKeyArray MAXMeshClass MAXModifierArray MAXNoteKey MAXNoteKeyArray MAXObject MAXRefTarg MAXRootNode MAXScriptFunction MAXSuperClass MAXTVNode MeditMaterialsClass menuitem MixinInterface ModifierClass MoFlow MoFlowScript MoFlowSnippet MoFlowTranInfo MoFlowTransition MotionTracker MouseTool

Const Class

193

MSBipedRootClass MSComMethod MSCustAttribDef MSDispatch MSPluginClass MtlButtonControl MultiListBoxControl MultiMaterialClass MultipleFSParams name NodeChildrenArray NodeGeneric NoteTrack Number NURBS1RailSweepSurface NURBS2RailSweepSurface NURBSBlendCurve NURBSBlendSurface NURBSCapSurface NURBSChamferCurve NURBSControlVertex NURBSCurve NURBSCurveConstPoint NURBSCurveIntersectPoint NURBSCurveOnSurface NURBSCurveSurfaceIntersectPoint NURBSCVCurve NURBSCVSurface NURBSDisplay NURBSExtrudeSurface NURBSFilletCurve NURBSFilletSurface NURBSIndependentPoint NURBSIsoCurve NURBSLatheSurface NURBSMirrorCurve NURBSMirrorSurface NURBSMultiCurveTrimSurface NURBSNBlendSurface NURBSObject NURBSOffsetCurve NURBSOffsetSurface NURBSPoint NURBSPointConstPoint NURBSPointCurve NURBSPointCurveOnSurface NURBSPointSurface NURBSProjectNormalCurve NURBSProjectVectorCurve NURBSRuledSurface NURBSSelection

194

Chapter 1

Whats New in 3ds max 4 MAXScript

NURBSSet NURBSSurface NURBSSurfaceApproximation NURBSSurfaceEdgeCurve NURBSSurfaceNormalCurve NURBSSurfConstPoint NURBSSurfSurfIntersectionCurve NURBSTexturePoint NURBSTextureSurface NURBSULoftSurface NURBSUVLoftSurface NURBSXFormCurve NURBSXFormSurface object ObjectSet OkClass OLEMethod OLEObject PathName PhyBlendedRigidVertex PhyContextExport PhyRigidVertex PickerControl Point2 point3 Primitive progressBar Quat RadioControl Ray RCMenu RolloutClass RolloutControl RolloutFloater SelectionSet SelectionSetArray set SliderControl SpinnerControl StandardMaterialClass StaticMethodInterface String StringStream StructDef subAnim TxtureClass time Timer TriMesh UndefinedClass UnsuppliedClass

Const Generic

195

UserGeneric value ValueRef VertexSelection WindowStream XRefScene

See Also
Definitions for MAXScript internal organization (p. 188)

Const Generic
abs Number Values (p. 717) - in example with def Camera Common Properties, Operators, and Methods (p. 974) - in example Scripted Geometry Plug-ins (p. 1555) - in example Scripted Shape Plug-ins (p. 1560) - in example Scripted SimpleObject Plug-ins (p. 1556) - in example The Return Expression (p. 705) - in example Time Values (p. 751) addMultiplierCurve addNewNoteKey Controller Ease and Multiplier Curve Functions (p. 1297) - in example with def MAXNoteKeyArray Values (p. 817) - in example MAXNoteKey Values (p. 818) - in example Working with Note Tracks (p. 818) - in example addNewNoteKey MAXNoteKeyArray Values (p. 817) - in example MAXNoteKey Values (p. 818) - in example Working with Note Tracks (p. 818) - in example addPluginRollouts AllowBlending append appendCurve NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSULoftSurface : NURBSSurface (p. 1443) appendCurveByID NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSULoftSurface : NURBSSurface (p. 1443) appendGizmo Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) Working with Atmospherics (p. 1345) - example Scripted Plug-in Methods (p. 1551) PhyContextExport Values (p. 1458)

196

Chapter 1

Whats New in 3ds max 4 MAXScript

appendObject

Modifying Existing NURBS Objects (p. 1390) Creating New NURBS Objects (p. 1389) - in example NURBSSet : Value (p. 1450)

appendUCurve appendUCurveByID appendVCurve appendVCurveByID applyEaseCurve attach buildTVFaces buildVCFaces canConvertTo classOf clear clearAllAppData clearCacheEntry clearProdTess clearViewTess close closeU closeV collapseface composite Conjugate contains ConvertToRigid createInstance

NURBSUVLoftSurface : NURBSSurface (p. 1444) NURBSUVLoftSurface : NURBSSurface (p. 1444) NURBSUVLoftSurface : NURBSSurface (p. 1444) NURBSUVLoftSurface : NURBSSurface (p. 1444) Controller Ease and Multiplier Curve Functions (p. 1297) - in example with def Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Working with Editable Meshes (p. 1077) - in example Editable_Mesh : GeometryClass and TriMesh : Value (p. 1041) Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397)

Access to MAXWrapper AppData (p. 813) NURBSSet : Value (p. 1450) NURBSSurface : NURBSObject (p. 1425) NURBSSet : Value (p. 1450) NURBSSurface : NURBSObject (p. 1425) NURBSCVSurface : NURBSSurface (p. 1433) NURBSPointSurface : NURBSSurface (p. 1441) NURBSCVSurface : NURBSSurface (p. 1433) NURBSPointSurface : NURBSSurface (p. 1441) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Quat Values (p. 738) PhyContextExport Values (p. 1458) MAXWrapper Common Properties, Operators, and Methods (p. 809) Scripted Manipulator (p. 97) - in example Scripted Manipulators (p. 97) - in example Scripted SimpleObject Plug-ins (p. 1556) - in example with def

Const Generic

197

crop

bgndRenderElement - superclass: MAXObject (p. 270) - in example BitmapTex fnReload and fnCrop (p. 164) bitmapTex interfaces: (p. 434) - in example BitmapTexture : TextureMap (p. 1243)

cross defaultVCFaces deleteAppData deleteface deleteGizmo deleteItem deleteKey Attachment : PositionController (p. 1304) Biped Keys (p. 1759) Controller Key Functions (p. 1294) MAXKeyArray Values (p. 793) deleteMultiplierCurve deleteNoteKey deleteNoteKeys deleteObjects deleteTracker deletevert deselectKey detachFaces detachVerts disconnect displacementToPreset display distance dot empty eof evalPos evalTangent evalUTangent evalVTangent execute NURBSCurve : NURBSObject (p. 1409) NURBSSurface : NURBSObject (p. 1425) NURBSCurve : NURBSObject (p. 1409) NURBSSurface : NURBSObject (p. 1425) NURBSSurface : NURBSObject (p. 1425) -jpr see above Interface: paramWire (p. 410) - in example Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Controller Key Functions (p. 1294) Controller Ease and Multiplier Curve Functions (p. 1297) MAXNoteKeyArray Values (p. 817) Working with Note Tracks (p. 818) - in example MAXNoteKeyArray Values (p. 817) Working with Note Tracks (p. 818) - in example NURBSSet : Value (p. 1450) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Access to MAXWrapper AppData (p. 813) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Atmospheric Effect Types (p. 1339)

198

Chapter 1

Whats New in 3ds max 4 MAXScript

exp

Number Values (p. 717) Mathematical Operations in MAXScript (p. 588) Quat Values (p. 738) - in example with def

exprForMAXObject extrudeface filepos findItem findPattern findString

Mesher - superclass: GeometryClass (p. 298) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Scripted SimpleObject Plug-ins (p. 1556) FileStream Values (p. 763) StringStream Values (p. 766)

String Values (p. 722) Function Parameters (p. 702) Pickbutton (p. 1504)

flagChanged flush

XRefScene Values (p. 1038) FileStream Values (p. 763) StringStream Values (p. 766) Turning On the Listener Log (p. xli)

getAfterORT getAppData getBeforeORT getChannel getChannelAsMask getCurve

Controller Out-Of-Range Functions (p. 1296) Controller Key Reducer Access to MAXWrapper AppData (p. 813) Controller Out-Of-Range Functions (p. 1296) Bitmap Values (p. 755) Bitmap Values (p. 755) Scripted RenderEffect Plug-ins (p. 1566) - in example NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSULoftSurface : NURBSSurface (p. 1443)

getCurveID

NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSULoftSurface : NURBSSurface (p. 1443)

getCurveStartPoint getCV

NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSControlVertex : NURBSObject (p. 1409) NURBSCVCurve : NURBSCurve (p. 1412) NURBSCVSurface : NURBSSurface (p. 1433)

getDisplacementMapping getEdge getEdgeVis

Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) NURBSBlendSurface : NURBSSurface (p. 1430) NURBSNBlendSurface : NURBSSurface (p. 1439) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)

Const Generic

199

getface getFaceMatID getFaceNormal getFaceSmoothGroup getFlip

Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Working with Editable Meshes (p. 1077) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSULoftSurface : NURBSSurface (p. 1443) Path interfaces: (p. 462) Path Constraint interfaces: (p. 468)

getFlipTrim getGenerateUVs getGizmo getIndexedPixels getKey getKeyIndex getKnot getModContextBBoxMax

NURBSFilletSurface : NURBSSurface (p. 1436) NURBSSurface : NURBSObject (p. 1425) Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) Bitmap Values (p. 755) Controller Key Functions (p. 1294) NURBSCVCurve : NURBSCurve (p. 1412) Modifier Common Properties, Operators, and Methods (p. 1096) Modifier Sub-Object Transform Properties (p. 1099) Node Common Properties, Operators, and Methods (p. 820)

getModContextBBoxMin

Modifier Common Properties, Operators, and Methods (p. 1096) Modifier Sub-Object Transform Properties (p. 1099) Node Common Properties, Operators, and Methods (p. 820) Scripting Vertex and Control Point Animation (p. 1461)

getModContextTM

Modifier Common Properties, Operators, and Methods (p. 1096) Modifier Sub-Object Transform Properties (p. 1099) Node Common Properties, Operators, and Methods (p. 820)

getMultiplierValue GetNode getnormal getNoteKeyIndex getNoteKeyTime getNumCPVVerts getNumFaces getNumTVerts getNumVerts

Controller Ease and Multiplier Curve Functions (p. 1297) Biped and Physique (p. 1456) - in example Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Scripted Manipulators (p. 97) Notetrack Values (p. 816) MAXNoteKeyArray Values (p. 817) Notetrack Values (p. 816) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Patches (p. 55)

200

Chapter 1

Whats New in 3ds max 4 MAXScript

getObject GetOffsetVector getParent

Patches Biped and Physique (p. 1456) - in example NURBSBlendSurface : NURBSSurface (p. 1430) NURBSFilletSurface : NURBSSurface (p. 1436) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSNBlendSurface : NURBSSurface (p. 1439) Trackviews (p. 114)

getParentID

NURBSBlendSurface : NURBSSurface (p. 1430) NURBSFilletSurface : NURBSSurface (p. 1436) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSNBlendSurface : NURBSSurface (p. 1439)

getPixels getPoint

Bitmap Files (p. 1641) Scripted RenderEffect Plug-ins (p. 1566) NURBSIndependentPoint : NURBSPoint (p. 1406) NURBSPointCurve : NURBSCurve (p. 1418) NURBSPointSurface : NURBSSurface (p. 1441) NURBSTexturePoint : NURBSObject (p. 1446) NURBSTextureSurface : Value (p. 1455) Curve Control (p. 170) Scripted Manipulators (p. 97)

getProdTess getPropNames

NURBSSet : Value (p. 1450) NURBSSurface : NURBSObject (p. 1425) Class and Object Inspector Functions (p. 799) Array Values (p. 776) - in example ActiveX Controls in MAXScript Rollouts (p. 10) Scripted Manipulators (p. 97) - in example

getRadius getSeed getSplitMesh getSubAnim getSubAnimName getSubAnimNames

NURBSFilletSurface : NURBSSurface (p. 1436) NURBSFilletSurface : NURBSSurface (p. 1436) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Indexed Access to Animatable Properties in 3D Studio MAX Objects (p. 806) Indexed Access to Animatable Properties in 3D Studio MAX Objects (p. 806) Subanim Indexing Operator, [], on MAX Objects Now Takes Subanim Names (p. 139) Indexed Access to Animatable Properties in 3D Studio MAX Objects (p. 806) Subanim Indexing Operator, [], on MAX Objects Now Takes Subanim Names (p. 139)

getSubdivisionDisplacement Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) getTextureSurface getTextureUVs getTiling getTilingOffset NURBSSurface : NURBSObject (p. 1425) NURBSTextureSurface : Value (p. 1455) NURBSSurface : NURBSObject (p. 1425) NURBSSurface : NURBSObject (p. 1425) NURBSSurface : NURBSObject (p. 1425)

Const Generic

201

getTimeRange getTracker getTrimSurface getTVert getTVFace getUCurve getUCurveID getUKnot getVCFace getVCurve getVCurveID getVert

Controller Time Functions (p. 1292) NURBSFilletSurface : NURBSSurface (p. 1436) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Node Common Properties, Operators, and Methods (p. 820) - in example Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Node Common Properties, Operators, and Methods (p. 820) - in example NURBSUVLoftSurface : NURBSSurface (p. 1444) NURBSUVLoftSurface : NURBSSurface (p. 1444) NURBSCVSurface : NURBSSurface (p. 1433) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) NURBSUVLoftSurface : NURBSSurface (p. 1444) NURBSUVLoftSurface : NURBSSurface (p. 1444) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Patches (p. 55) Script Controllers (p. 1329) - in example

getvertcolor getVertexInterface

Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) PhyBlendingRigidVertex Values (p. 1459) PhyContextExport Values (p. 1458) PhyRigidVertex Values (p. 1459) Biped and Physique (p. 1456) - in example

getViewTess getVKnot getWeight

NURBSSet : Value (p. 1450) NURBSSurface : NURBSObject (p. 1425) NURBSCVSurface : NURBSSurface (p. 1433) PhyBlendingRigidVertex Values (p. 1459) Class and Object Inspector Functions (p. 159) - in example LookAt Constraint - superclass: RotationController (p. 297) LookAt Constraint interfaces: (p. 455) Orientation Constraint Controller (p. 40) Path Constraint interfaces: (p. 468) Position Constraint (p. 41) Position Constraint interfaces: (p. 488)

gotoFrame invalTrack Inverse invert

Bitmap Values (p. 755) Matrix3 Values Matrix3 Values Using Node Transform Properties (p. 843) - in example BigMatrix Values (p. 748) VolumeSelect : Modifier (p. 1192) Volume Light : Atmospheric (p. 1344) Volume Fog : Atmospheric (p. 1343)

202

Chapter 1

Whats New in 3ds max 4 MAXScript

isEmpty isIdentity isKeySelected isKindOf

Box2 Values (p. 750) Coercion of bitArray to array and integer arrays to bitArrays (p. 132) Matrix3 Values (p. 744) Quat Values (p. 738) Controller Key Functions (p. 1294) CS3Tools.cui Tutorial (p. 1825) - in example Working with Values (p. 716) ObjectSet Values (p. 781) - in example Structure Inherited Methods (p. 711)

join length LnDif loadFrames LogN merge

BitArray Values (p. 791) Array Values (p. 776) Quat Values (p. 738) Quat Values (p. 738) XRefScene Values (p. 1038) Zip-file Script Packages (p. 122) NURBSSet : Value (p. 1450)

moveKey normalize

Controller Key Functions (p. 1294) Quat Values (p. 738) Point3 Values (p. 731) Point2 Values (p. 736) Scripted Plug-in Methods (p. 1551) - in example

numEaseCurves numKeys numMultiplierCurves numSelKeys perspectiveMatch QCompA qorthog random readChar readChars readDelimitedString

Controller Ease and Multiplier Curve Functions (p. 1297) Controller Key Functions (p. 1294) Controller Ease and Multiplier Curve Functions (p. 1297) Controller Key Functions (p. 1294) Quat Values (p. 738) Quat Values (p. 738) Number Values (p. 717) Node Common Properties, Operators, and Methods (p. 820) FileStream Values (p. 763) StringStream Values (p. 766) FileStream Values (p. 763) StringStream Values (p. 766) FileStream Values (p. 763) StringStream Values (p. 766)

Const Generic

203

readExpr

MAXScript System Globals (p. 640) Value Common Properties, Operators, and Methods (p. 714) FileStream Values (p. 763) StringStream Values (p. 766)

readLine readValue

FileStream Values (p. 763) StringStream Values (p. 766) FileStream Values (p. 763) StringStream Values (p. 766) Access to MAXWrapper AppData (p. 813) - in example Encrypted Files (p. 1647) - in example MAXScript System Globals (p. 640) Node User-Defined Properties and Methods (p. 848) - in example

rectify refine

Box2 Values (p. 750) NURBSCVCurve : NURBSCurve (p. 1412) NURBSCVSurface : NURBSSurface (p. 1433) NURBSPointCurve : NURBSCurve (p. 1418) NURBSPointSurface : NURBSSurface (p. 1441)

refineU refineV removeObject renderMap reparameterize replace resample reset resetZoom save seek selectKey setAppData setCacheEntry

NURBSCVSurface : NURBSSurface (p. 1433) NURBSPointSurface : NURBSSurface (p. 1441) NURBSCVSurface : NURBSSurface (p. 1433) NURBSPointSurface : NURBSSurface (p. 1441) Modifying Existing NURBS Objects (p. 1390) NURBSSet : Value (p. 1450) Material Editor (p. 1606) TextureMap Common Properties, Operators, and Methods (p. 1235) NURBSCVCurve : NURBSCurve (p. 1412) NURBSCVSurface : NURBSSurface (p. 1433) String Literals (p. 660) Curve Control (p. 170) Flex interfaces: (p. 438) Bitmap Values (p. 755) FileStream Values (p. 763) StringStream Values (p. 766) Controller Key Functions (p. 1294) Access to MAXWrapper AppData (p. 813)

204

Chapter 1

Whats New in 3ds max 4 MAXScript

setCurve

NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSULoftSurface : NURBSSurface (p. 1443)

setCurveByID

NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSULoftSurface : NURBSSurface (p. 1443)

setCurveStartPoint setCV

NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSCVCurve : NURBSCurve (p. 1412) NURBSCVSurface : NURBSSurface (p. 1433) Creating New NURBS Objects (p. 1389) - in example

setDisplacementMapping setEdge setEdgeVis setface setFaceMatID setfacenormal setFaceSmoothGroup setFade setFlip

Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) NURBSBlendSurface : NURBSSurface (p. 1430) NURBSNBlendSurface : NURBSSurface (p. 1439) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Working with Editable Meshes (p. 1077) in example Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSULoftSurface : NURBSSurface (p. 1443) path interfaces: (p. 462) Path Constraint interfaces: (p. 468)

setFlipTrim setGenerateUVs setIndexedPixels setKnot setMesh SetNonUniformScale setnormal setNumCPVVerts setNumFaces setNumTVerts setNumVerts

NURBSFilletSurface : NURBSSurface (p. 1436) NURBSSurface : NURBSObject (p. 1425) Bitmap Files (p. 1641) NURBSCVCurve : NURBSCurve (p. 1412) Creating New NURBS Objects (p. 1389) in example Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Scripted SimpleObject Plug-ins (p. 1556) in example BipedExportInterface Values (p. 1458) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Patches (p. 55)

Const Generic

205

setObject setParent

NURBSSet : Value (p. 1450) Modifying Existing NURBS Objects (p. 1390) NURBSBlendSurface : NURBSSurface (p. 1430) NURBSFilletSurface : NURBSSurface (p. 1436) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSNBlendSurface : NURBSSurface (p. 1439)

setParentID

NURBSBlendSurface : NURBSSurface (p. 1430) NURBSFilletSurface : NURBSSurface (p. 1436) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSNBlendSurface : NURBSSurface (p. 1439)

setPixels setPoint

Bitmap Files (p. 1641) Scripted RenderEffect Plug-ins (p. 1566) in example Curve Control (p. 170) NURBSPointCurve : NURBSCurve (p. 1418) NURBSPointSurface : NURBSSurface (p. 1441) NURBSTextureSurface : Value (p. 1455)

setProdTess setRadius setSeed setSize setSplitMesh setStruct

NURBSSet : Value (p. 1450) NURBSSurface : NURBSObject (p. 1425) NURBSFilletSurface : NURBSSurface (p. 1436) NURBSFilletSurface : NURBSSurface (p. 1436) BigMatrix Values (p. 748) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)

setSubdivisionDisplacement Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) setTextureSurface setTextureUVs setTiling setTilingOffset setTrimSurface settvert setTVFace setUCurve setUCurveByID setUKnot setVCFace setVCurve NURBSSurface : NURBSObject (p. 1425) NURBSTextureSurface : Value (p. 1455) NURBSSurface : NURBSObject (p. 1425) Materials Assignment and Texture Coordinates (p. 1391) NURBSSurface : NURBSObject (p. 1425) NURBSSurface : NURBSObject (p. 1425) NURBSFilletSurface : NURBSSurface (p. 1436) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Working with Editable Meshes (p. 1077) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Working with Editable Meshes (p. 1077) NURBSUVLoftSurface : NURBSSurface (p. 1444) NURBSUVLoftSurface : NURBSSurface (p. 1444) NURBSCVSurface : NURBSSurface (p. 1433) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) NURBSUVLoftSurface : NURBSSurface (p. 1444)

206

Chapter 1

Whats New in 3ds max 4 MAXScript

setVCurveByID setVert setVertColor setViewTess setVKnot showInterface showInterfaces showProperties showTrack skipToNextLine skipToString Slerp sort sortNoteKeys squad substring superClassOf

NURBSUVLoftSurface : NURBSSurface (p. 1444) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Patches (p. 55) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) NURBSSet : Value (p. 1450) NURBSSurface : NURBSObject (p. 1425) NURBSCVSurface : NURBSSurface (p. 1433) Class and Object Inspector Functions (p. 159) Trackviews (p. 114) Class and Object Inspector Functions (p. 159) List Controller (p. 143) Apropos and ShowProperties and now Help and Show (p. 128) Class and Object Inspector Functions (p. 799) FileStream Values (p. 763) StringStream Values (p. 766) FileStream Values (p. 763) StringStream Values (p. 766) EulerAngles Values (p. 742) Quat Values (p. 738) Array Values (p. 776) MAXNoteKeyArray Values (p. 817) Working with Note Tracks (p. 818) - in example Quat Values (p. 738) String Literals (p. 660) Working with Values (p. 716) Structure Inherited Methods (p. 711) Value Common Properties, Operators, and Methods (p. 714) Picking Scene Nodes By Hit (p. 1618)

supportsTimeOperations transform transpose unDisplay update updateXRef XFormMat zoom

Controller Time Functions (p. 1292) BigMatrix Values (p. 748) Bitmap Files (p. 1641) XRefObject : Node (p. 1037) XRefScene Values (p. 1038) Matrix3 Values (p. 744)

Const MappedGeneric

207

See Also
Definitions for MAXScript internal organization (p. 188)

Const MappedGeneric
addEaseCurve Controller Ease and Multiplier Curve Functions (p. 1297) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) addNewKey deleteEaseCurve MAXKey Common Properties, Operators, and Methods (p. 768) Controller Ease and Multiplier Curve Functions (p. 1297) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) deleteKeys MAXKeyArray Values (p. 793) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) Controller Key Functions (p. 1294) deleteTime Controller Time Functions (p. 1292) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) deselectKeys Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) Controller Key Functions (p. 1294) enableORTs Controller Out-Of-Range Functions (p. 1296) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) Identity insertTime BigMatrix Values (p. 748) Controller Time Functions (p. 1292) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) mapKeys moveKeys mapKeys() method (p. 144) MAXKeyArray Values (p. 793) Controller Key Functions (p. 1294) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) Orthogonalize PreRotate PreRotateX PreRotateY PreRotateZ PreScale Matrix3 Values (p. 744) Matrix3 Values (p. 744) Matrix3 Values (p. 744) Matrix3 Values (p. 744) Matrix3 Values (p. 744) Matrix3 Values (p. 744)

208

Chapter 1

Whats New in 3ds max 4 MAXScript

PreTranslate print reduceKeys

Matrix3 Values (p. 1299) Value Common Properties, Operators, and Methods (p. 714) Controller Key Reducer (p. 1299) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)

reverseTime

Controller Time Functions (p. 1292) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)

RotateX RotateY RotateZ scaleTime

Matrix3 Values (p. 744) Matrix3 Values (p. 744) Matrix3 Values (p. 744) Controller Time Functions (p. 1292) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)

selectKeys

Controller Key Functions (p. 1294) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) Attachment : PositionController (p. 1304)

setAfterORT

Controller Ease and Multiplier Curve Functions (p. 1297) Controller Out-Of-Range Functions (p. 1296) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)

setBeforeORT

Names (p. 657) Controller Ease and Multiplier Curve Functions (p. 1297) Controller Out-Of-Range Functions (p. 1296) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies

setTimeRange

Controller Time Functions (p. 1292) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies

sortKeys

MAXKeyArray Values (p. 793) Controller Key Functions (p. 1294) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) Working with MAXKey Values (p. 769) Working with Note Tracks (p. 818)

Translate Zero

Matrix3 Values (p. 744) Box2 Values (p. 750)

Const NodeGeneric

209

See Also
Definitions for MAXScript internal organization (p. 188)

Const NodeGeneric
addAndWeld addKnot addModifier addNewSpline addNURBSSet SplineShape : Shape (p. 1079) Modifying Existing NURBS Objects (p. 1390) NURBS Node Properties and Methods (p. 1397) Parameter Ranges for Curves and Surfaces (p. 1391) bindKnot bindSpaceWarp breakCurve breakSurface collapseStack NURBS Node Properties and Methods (p. 1397) Modifying Existing NURBS Objects (p. 1390) NURBS Node Properties and Methods (p. 1397) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Modifier Common Properties, Operators, and Methods (p. 1096) Node Common Properties, Operators, and Methods (p. 820) Patch : GeometryClass (p. 1088) convertTo Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397) Patch : GeometryClass (p. 1088) Patches (p. 55) convertToMesh convertToNURBSCurve Collections (p. 773) Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397) convertToNURBSSurface convertToPoly convertToSplineShape Modifier Common Properties, Operators, and Methods (p. 1096) Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397) Scripting Vertex and Control Point Animation (p. 1461) Section : Shape (p. 959) SplineShape : Shape (p. 1079) copy Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397) SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079)

210

Chapter 1

Whats New in 3ds max 4 MAXScript

curveLength deleteKnot deleteModifier deleteSpline deselect flagForeground

Shape Common Properties, Operators, and Methods (p. 945) SplineShape : Shape (p. 1079) Modifier Common Properties, Operators, and Methods (p. 1096) Node Common Properties, Operators, and Methods (p. 820) SplineShape : Shape (p. 1079) Modifier and SpacewarpModifier Types (p. 1100) Node Common Properties, Operators, and Methods (p. 820) Scripted Atmospheric Plug-ins (p. 1569) - in example Slider (p. 1507) Spinner (p. 1509)

freeze getEdgeSelection Edit Mesh : Modifier (p. 1114) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Mesh Select : Modifier (p. 1142) polyop const StructDef (p. 248) getFaceSelection Edit Mesh : Modifier (p. 1114) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Mesh Select : Modifier (p. 1142) polyop const StructDef (p. 248) getInVec getKnotPoint getKnotType getNURBSSet getOutVec getSegmentType getUserProp getUserPropBuffer getVertSelection SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079) Node Common Properties, Operators, and Methods (p. 820) Node User-Defined Properties and Methods (p. 848) Node Common Properties, Operators, and Methods (p. 820) Node User-Defined Properties and Methods (p. 848) Edit Mesh : Modifier (p. 1114) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Mesh Select : Modifier (p. 1142) polyop const StructDef (p. 248) hide hideSelectedSegments hideSelectedSplines hideSelectedVerts instance instanceReplace Node Common Properties, Operators, and Methods (p. 820) SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079)

Const NodeGeneric

211

intersectRay intersects isClosed isDeleted joinCurves joinSurfaces lengthInterp lengthTangent lengthToPathParam makeIndependent materialID

mouseTrack() Function (p. 180) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Scripted Manipulator (p. 97) NURBSCurve : NURBSObject (p. 1409) SplineShape : Shape (p. 1079) Node Common Properties, Operators, and Methods (p. 820) - in example with def PathName Values (p. 780) - in example with def NURBS Node Properties and Methods (p. 1397) NURBS Node Properties and Methods (p. 1397) Shape Common Properties, Operators, and Methods (p. 945) Shape Common Properties, Operators, and Methods (p. 945) Shape Common Properties, Operators, and Methods (p. 945) NURBS Node Properties and Methods (p. 1397) Bitmap Values (p. 755) MaterialModifier : Modifier (p. 1137) SplineShape : Shape (p. 1079)

move nearestPathParam numKnots Shape Common Properties, Operators, and Methods (p. 945) NURBSCVCurve : NURBSCurve (p. 1412) Creating New NURBS Objects (p. 1389) in example Shape Common Properties, Operators, and Methods (p. 945) SplineShape : Shape (p. 1079) numSegments numSplines open particleAge particleCount particlePos particleSize particleVelocity pathInterp pathTangent pathToLengthParam printstack reference referenceReplace refineSegment resetShape Node Common Properties, Operators, and Methods (p. 820) SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079) Particle System Common Properties, Operators, and Methods (p. 905) Particle System Common Properties, Operators, and Methods (p. 905) Particle System Common Properties, Operators, and Methods (p. 905) Particle System Common Properties, Operators, and Methods (p. 905) Particle System Common Properties, Operators, and Methods (p. 905) Particle System Common Properties, Operators, and Methods (p. 905) Particle System Common Properties, Operators, and Methods (p. 905) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079)

212

Chapter 1

Whats New in 3ds max 4 MAXScript

reverse rotate scale select selectmore setEdgeSelection setFaceSelection setFirstKnot setFirstSpline setInVec setKnotPoint setKnotType setOutVec setRenderApproximation setSegmentType setSurfaceDisplay setUserProp setUserPropBuffer setVertSelection setViewApproximation snapShot unbindKnot unfreeze Node Common Properties, Operators, and Methods (p. 820) ObjectSet Values (p. 781) - In Example With Def polyop const StructDef (p. 248) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) - In Example polyop const StructDef (p. 248) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) - In Example SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079) NURBS Node Properties and Methods (p. 1397) NURBSSurfaceApproximation : Value (p. 1453) SplineShape : Shape (p. 1079) NURBS Node Properties and Methods (p. 1397) NURBSSurfaceApproximation : Value (p. 1453) Node Common Properties, Operators, and Methods (p. 820) Node User-Defined Properties and Methods (p. 848) - In Example With Def Node Common Properties, Operators, and Methods (p. 820) Node User-Defined Properties and Methods (p. 848) - In Example With Def Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) - In Example With Def polyop const StructDef (p. 248) NURBS Node Properties and Methods (p. 1397) NURBSSurfaceApproximation : Value (p. 1453) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Node Common Properties, Operators, and Methods (p. 820) SplineShape : Shape (p. 1079) MAX Commands (p. 1630) MAX Commands in MAXScript (p. 620) Node Common Properties, Operators, and Methods (p. 820) Unwrap UVW interfaces: (p. 530) UVWUnwrap interfaces: (p. 568) Visual MAXScript (p. 117) unhide unhideSegments SplineShape : Shape (p. 1079)

Const Primitives

213

updateBindList updateShape

SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079)

See Also
Definitions for MAXScript internal organization (p. 188)

Const Primitives
All known const Primitives.
acos addAtmospheric addEffect addMorphTarget addNoteTrack addRollout Number Values (p. 717) Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) Render Effects Common Properties, Operators, and Methods (p. 1347) Barycentric Morph Controller : MorphController (p. 1306) Notetrack Values (p. 816) Working with Note Tracks (p. 818) Utility Clauses (p. 1466) Managing Multiple Rollouts in a Scripted Utility (p. 1468) Rollout Floater Windows (p. 1477) Scripted Utilities (p. 1463) Utility and Rollout Properties, Methods, and Event Handlers (p. 1474) addTrackViewController affectRegionVal amax amin animateAll animateVertex Track View Nodes (p. 1382) Affect Region Function (p. 127) Array Values (p. 776) Array Values (p. 776) Scripting Vertex and Control Point Animation (p. 1461) Modifier Sub-Object Transform Properties (p. 1099) SplineShape : Shape (p. 1079) Scripting Vertex and Control Point Animation (p. 1461) Modifier Sub-Object Transform Properties (p. 1099) appendSubSelSet apropos arbAxis asin assignNewName atan atan2 attachObjects Main Toolbar (p. 1574) Class and Object Inspector Functions (p. 799) Apropos and ShowProperties and now Help and Show (p. 128) Point3 Values (p. 731) Number Values (p. 717) Material Common Properties, Operators, and Methods (p. 1203) Number Values (p. 717) Number Values (p. 717) Node Common Properties, Operators, and Methods (p. 820)

214

Chapter 1

Whats New in 3ds max 4 MAXScript

averageSelVertCenter averageSelVertNormal axisTripodLocked boxPickNode break ceil checkForSave circlePickNode clearCurSelSet clearListener clearNodeSelection clearSelection

Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Miscellaneous Viewport Methods and System Globals (p. 1603) Picking Scene Nodes By Region (p. 1620) Number Values (p. 717) 3ds max File Loading and Saving (p. 1639) Picking Scene Nodes By Region (p. 1620) Main Toolbar (p. 1574) Controlling the Listener Contents and the Insertion Point (p. xlii) Node Common Properties, Operators, and Methods (p. 820) ObjectSet Values (p. 781) Node Common Properties, Operators, and Methods (p. 820) Trackviews (p. 114)

ClearSubSelSets clearUndoBuffer closelog closeRolloutFloater closeUtility completeRedraw configureBitmapPaths conformToShape

Main Toolbar (p. 1574) undo (p. 687) Exiting and Resetting 3ds max (p. 1669) Turning On the Listener Log (p. xli) Rollout Floater Windows (p. 1477) Utility and Rollout Properties, Methods, and Event Handlers (p. 1474) Refreshing the Viewports (p. 1585) Miscellaneous Dialogs (p. 1621) FFD 2x2x2 : Modifier (p. 1121) FFD 3x3x3 : Modifier (p. 1123) FFD 4x4x4 : Modifier (p. 1124) FFD Box : Modifier (p. 1117) FFD Cyl : Modifier (p. 1119)

copyFile cos

External File Methods (p. 1645) Trigonometric Functions (p. 1675) Function Variables (p. 701) Number Values (p. 717)

cosh CreateDialog createfile createLockKey

Mathematical Operations in MAXScript (p. 588) Number Values (p. 717) CreateDialog (p. 169) FileStream Values (p. 763) Encrypted Files (p. 1647) Controller Key Functions (p. 1294)

Const Primitives

215

createMorphObject

Barycentric Morph Controller : MorphController (p. 1306) Barycentric Morph Controller Keys (p. 1308) Morph : GeometryClass (p. 891)

createOLEObject createPreview createReaction degToRad deleteAllChangeHandlers deleteAtmospheric deleteChangeHandler deleteEffect deleteFile deleteMorphTarget deleteNoteTrack deleteReaction deleteTrackViewController deleteTrackViewNode dependsOn deselectHiddenEdges deselectHiddenFaces deselectNode DestroyDialog DisableSceneRedraw disableStatusXYZ displayControlDialog displayTempPrompt doesFileExist DOSCommand dumpMAXStrings editAtmosphere editAtmospheric editEffect enableCoordCenter enableRefCoordSys EnableSceneRedraw enableShowEndRes enableStatusXYZ

OLE Automation (p. 1671) Miscellaneous Viewport Methods and System Globals (p. 1603) Reactor Controllers (p. 1326) Number Values (p. 717) Change Handlers and When Constructs (p. 1650) Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) Change Handlers and When Constructs (p. 1650) Render Effects Common Properties, Operators, and Methods (p. 1347) External File Methods (p. 1645) Barycentric Morph Controller : MorphController (p. 1306) Notetrack Values (p. 816) Working with Note Tracks (p. 818) Reactor Controllers (p. 1326) Track View Nodes (p. 1382) Track View Nodes (p. 1382) dependsOn For Scripted Controllers (p. 95) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Node Common Properties, Operators, and Methods (p. 820) CreateDialog (p. 169) Refreshing the Viewports (p. 1585) Coordinate Display (p. 1578) Controller Common Properties, Operators, and Methods (p. 1289) Prompt Line (p. 1577) File Name Parsing (p. 1644) Executing External Commands (p. 1668) Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) Render Effects Common Properties, Operators, and Methods (p. 1347) Main Toolbar (p. 1574) Main Toolbar (p. 1574) Refreshing the Viewports (p. 1585) Modify Panel (p. 1572) Coordinate Display (p. 1578)

216

Chapter 1

Whats New in 3ds max 4 MAXScript

enableSubObjSel enableUndo encryptFile encryptScript enumerateFiles eulerToQuat exclusionListDlg explodeGroup exportFile fclose fencePickNode fetchMaxFile filein

Modify Panel (p. 1572) Main Toolbar (p. 1574) Encrypted Files (p. 1647) Encrypting Script Files (p. lx) Bitmap Files (p. 1641) BitmapTexture : TextureMap (p. 1243) Quat Values (p. 738) EulerAngles Values (p. 742) Miscellaneous Dialogs (p. 1621) Node Common Properties, Operators, and Methods (p. 820) 3ds max File Loading and Saving (p. 1639) BinStream for Binary Reading and Writing (p. 128) Picking Scene Nodes By Region (p. 1620) 3ds max File Loading and Saving (p. 1639) Zip-file Script Packages (p. 122) Running Scripts (p. xlix) Including Scripts Within Scripts (p. lix) Creating Functions (p. 699) Encrypting Script Files (p. lx) Symbolic Pathnames (p. 140)

filenameFromPath fileOpenMatLib fileSaveAsMatLib fileSaveMatLib filterString flashNodes floor flushlog fopen ForceCompleteRedraw format fractalNoise freeSceneBitmaps

File Name Parsing (p. 1644) Material Editor (p. 1606) MaterialLibrary Values (p. 795) Material Editor (p. 1606) MaterialLibrary Values (p. 795) Material Editor (p. 1606) MaterialLibrary Values (p. 795) String Values (p. 722) Miscellaneous Viewport Methods and System Globals (p. 1603) Number Literals (p. 660) Turning On the Listener Log (p. xli) BinStream for Binary Reading and Writing (p. 128) Refreshing the Viewports (p. 1585) StringStream Values (p. 766) Color Values (p. 729) Point3 Values (p. 731) Bitmap Values (p. 755) BitmapTexture : TextureMap (p. 1243) Miscellaneous Functions (p. 1663)

Const Primitives

217

freezeSelection fseek ftell gc genClassID getActiveCamera

Status Bar Buttons (p. 1579) BinStream for Binary Reading and Writing (p. 128) BinStream for Binary Reading and Writing (p. 128) Manual Garbage Collection (p. 656) Bitmap Values (p. 755) Scripted Plug-ins (p. 1538) Scripted Custom Attributes (p. 45) Accessing Active Viewport Info, Type, and Transforms (p. 1581) Defining Macro Scripts (p. 1521) Viewport Drawing Methods (p. 1592)

getAtmospheric getBackGround getBackGroundController getBipedExportInterface getBitmapOpenFileName getBitmapSaveFileName getBkgFrameNum getBkgImageAnimate getBkgImageAspect getBkgORType getBkgRangeVal getBkgStartTime getBkgSyncFrame getCommandPanelTaskMode getCoordCenter getCoreInterfaces getCPTM getCrossing getCurNameSelSet getCurrentSelection getCVertMode GetDefaultUIColor GetDialogPos getDimensions

Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) Setting explosion start and end times for Combustion (p. 1341) SetBackground Method (p. 180) Working with Atmospherics (p. 1345) BipedExportInterface Values (p. 1458) Bitmap Values (p. 755) Bitmap Values (p. 755) Viewport Background Images (p. 1586) Viewport Background Images (p. 1586) Viewport Background Images (p. 1586) Viewport Background Images (p. 1586) Viewport Background Images (p. 1586) Viewport Background Images (p. 1586) Viewport Background Images (p. 1586) Command Panels (p. 1571) Main Toolbar (p. 1574) Node Common Properties, Operators, and Methods (p. 820) in example Interfaces (p. 67) Accessing Active Viewport Info, Type, and Transforms (p. 1581) Status Bar Buttons (p. 1579) Collections (p. 773) ObjectSet Values (p. 781) Node Common Properties, Operators, and Methods (p. 820) 3ds max User Interface Colors (p. 1604) -jprBuild: M023-Title: Added Simon Feltmans CtrlLib classes to MXSAgni FFD Box : Modifier (p. 1117) FFD Cyl : Modifier (p. 1119)

218

Chapter 1

Whats New in 3ds max 4 MAXScript

GetDir getDirectories GetDisplayFilter getEffect getEulerMatAngleRatio getEulerQuatAngleRatio getFileAttribute getFileCreateDate getFileModDate getFilenameFile

3ds max System Directories (p. 1625) SetDir (p. 136) External File Methods (p. 1645) Selection Filter (p. 61) Render Effects Common Properties, Operators, and Methods (p. 1347) EulerAngles Values (p. 742) Matrix3 Values (p. 744) Quat Values (p. 738) EulerAngles Values (p. 742) External File Methods (p. 1645) External File Methods (p. 1645) External File Methods (p. 1645) Viewport Drawing Methods (p. 1592) File Name Parsing (p. 1644) External File Methods (p. 1645) Defining Macro Scripts (p. 1521)

getFilenamePath getFilenameType getFiles getFileVersion getGridMajorLines getGridSpacing getHashValue getImageBlurMultController getInheritanceFlags getInheritVisibility getINISetting getKBChar getKBLine getKBPoint getKBValue getKeyStepsPos getKeyStepsRot getKeyStepsScale getKeyStepsSelOnly getKeyStepsUseTrans getKnotSelection

File Name Parsing (p. 1644) External File Methods (p. 1645) File Name Parsing (p. 1644) External File Methods (p. 1645) External File Methods (p. 1645) Viewport Grids (p. 1587) Viewport Grids (p. 1587) Value Common Properties, Operators, and Methods (p. 714) Node Common Properties, Operators, and Methods (p. 820) General Node Properties (p. 836) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Accessing INI File Keys (p. 1647) Keyboard Entry (p. 1623) Keyboard Entry (p. 1623) Keyboard Entry (p. 1623) Keyboard Entry (p. 1623) Time Configuration Dialog (p. 1616) Time Configuration Dialog (p. 1616) Time Configuration Dialog (p. 1616) Time Configuration Dialog (p. 1616) Time Configuration Dialog (p. 1616) SplineShape : Shape (p. 1079)

Const Primitives

219

getListenerSel getListenerSelText getMaterialID getMatLibFileName getMAXFileObjectNames getMAXOpenFileName getMAXSaveFileName getMeditMaterial

Controlling the Listener Contents and the Insertion Point (p. xlii) Controlling the Listener Contents and the Insertion Point (p. xlii) SplineShape : Shape (p. 1079) Material Editor (p. 1606) MaterialLibrary Values (p. 795) 3ds max File Loading and Saving (p. 1639) Zip-file Script Packages (p. 122) MAX Open & Save Dialogs (p. 177) MAX Open & Save Dialogs (p. 177) Material Common Properties, Operators, and Methods (p. 1203) Material Editor (p. 1606) MaterialLibrary Values (p. 795)

getMKKey getMKKeyIndex getMKTargetNames getMKTargetWeights getMKTime getMKWeight getMTLMEditFlags getMTLMeditObjType getMTLMeditTiling getNamedSelSetItem getNamedSelSetItemCount getNamedSelSetName getNodeByName getNoteTrack

Barycentric Morph Controller : MorphController (p. 1306) Barycentric Morph Controller Keys (p. 1308) Barycentric Morph Controller : MorphController (p. 1306) Barycentric Morph Controller : MorphController (p. 1306) Barycentric Morph Controller : MorphController (p. 1306) Barycentric Morph Controller Keys (p. 1308) Barycentric Morph Controller Keys (p. 1308) Material Common Properties, Operators, and Methods (p. 1203) Material Common Properties, Operators, and Methods (p. 1203) Material Common Properties, Operators, and Methods (p. 1203) SelectionSetArray Values (p. 783) SelectionSetArray Values (p. 783) SelectionSetArray Values (p. 783) Node Common Properties, Operators, and Methods (p. 820) Notetrack Values (p. 816) MAXNoteKeyArray Values (p. 817) Working with Note Tracks (p. 818)

getNumAxis getNumberDisplayFilters getNumberSelectFilters getNumNamedSelSets getOpenFileName getPatchSteps getPhyContextExport getPointController

Main Toolbar (p. 1574) Selection Filter (p. 61) Selection Filter (p. 61) SelectionSetArray Values (p. 783) Standard Open and Save File Dialogs (p. 1643) ActiveX Controls in MAXScript Rollouts (p. 10) in example Patch : GeometryClass (p. 1088) Biped and Physique (p. 1456) PhyContextExport Values (p. 1458) Controller Common Properties, Operators, and Methods (p. 1289)

220

Chapter 1

Whats New in 3ds max 4 MAXScript

getPointControllers getPolygonCount getPosTaskWeight getProgressCancel getProperty

Controller Common Properties, Operators, and Methods (p. 1289) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Progress Bar Display (p. 1578) Class and Object Inspector Functions (p. 799) Curve Control (p. 170) - in example ActiveX Controls in MAXScript Rollouts (p. 10) - in example

getPropertyController getReactionCount getReactionFalloff getReactionInfluence getReactionName getReactionState getReactionStrength getReactionValue getRefCoordSys getRendApertureWidth getRenderID getRendImageAspect getRotTaskWeight getSaveFileName

Class and Object Inspector Functions (p. 799) Reactor Controllers (p. 1326) Reactor Controllers (p. 1326) Reactor Controllers (p. 1326) Reactor Controllers (p. 1326) Reactor controller (p. 91) - in example Reactor Controllers (p. 1326) Reactor Controllers (p. 1326) Reactor controller (p. 91) - in example Reactor Controllers (p. 1326) Main Toolbar (p. 1574) Render Scene Dialog (p. 1611) Node Common Properties, Operators, and Methods (p. 820) Render Scene Dialog (p. 1611) Node Common Properties, Operators, and Methods (p. 820) Standard Open and Save File Dialogs (p. 1643) Viewport Drawing Methods (p. 1592) - in example Defining Macro Scripts (p. 1521) - in example

getSavePath getSaveRequired getScreenScaleFactor getSegLengths getSegSelection getSelectedReactionNum GetSelectFilter getShadeCVerts getSnapMode getSnapState getSplineSelection getTaskAxisState getTextExtent

Standard Open and Save File Dialogs (p. 1643) Exiting and Resetting 3ds max (p. 1669) undo (p. 687) Accessing Active Viewport Info, Type, and Transforms (p. 1581) SplineShape : Shape (p. 1079) SplineShape : Shape (p. 1079) Reactor Controllers (p. 1326) Selection Filter (p. 61) Node Common Properties, Operators, and Methods (p. 820) Status Bar Buttons (p. 1579) Status Bar Buttons (p. 1579) SplineShape : Shape (p. 1079) Node Common Properties, Operators, and Methods (p. 820) getTextExtent (p. 175)

Const Primitives

221

GetTMController gettoolbtnstate getTrajectoryOn getTransformAxis getTransformLockFlags GetUIColor getUseDraftRenderer getUseEnvironmentMap getViewFOV getViewSize getViewTM getVisController getVPortBGColor getXYZControllers group hasNoteTracks hasProperty HitByNameDlg holdMaxFile importFile include insertItem interpCurve3D intersectRayEx invalidateTM invalidateTreeTM invalidateWS isActive isBoneOnly isController isCPEdgeOnInView isCreatingObject isGroupHead Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Value Common Properties, Operators, and Methods (p. 714) Miscellaneous Viewport Methods and System Globals (p. 1603) Main Toolbar (p. 1574) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) 3ds max User Interface Colors (p. 1604) Render Scene Dialog (p. 1611) Working with Atmospherics (p. 1345) Accessing Active Viewport Info, Type, and Transforms (p. 1581) Accessing Active Viewport Info, Type, and Transforms (p. 1581) ActiveX Controls in MAXScript Rollouts (p. 10) - in example Accessing Active Viewport Info, Type, and Transforms (p. 1581) General Node Properties (p. 836) Node Common Properties, Operators, and Methods (p. 820) Miscellaneous Viewport Methods and System Globals (p. 1603) XYZ Controllers (p. 1335) Node Common Properties, Operators, and Methods (p. 820) Notetrack Values (p. 816) Working with Note Tracks (p. 818) - in example hasProperty() function (p. 135) Main Toolbar (p. 1574) 3ds max File Loading and Saving (p. 1639) Zip-file Script Packages (p. 122) 3ds max File Loading and Saving (p. 1639) Including Scripts Within Scripts (p. lix) Symbolic Pathnames (p. 140) Array Values (p. 776) SplineShape : Shape (p. 1079) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820)

222

Chapter 1

Whats New in 3ds max 4 MAXScript

isGroupMember IsNetServer isOpenGroupHead isOpenGroupMember IsPointSelected isreadOnly isSceneRedrawDisabled isSelectionFrozen IsShapeObject isStruct isStructDef IsSubSelEnabled isSurfaceUVClosed LoadDefaultMatLib loadDllsFromDir loadMaterialLibrary

Node Common Properties, Operators, and Methods (p. 820) Miscellaneous Functions (p. 1663) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397) Refreshing the Viewports (p. 1585) Status Bar Buttons (p. 1579) Node Common Properties, Operators, and Methods (p. 820) Value Common Properties, Operators, and Methods (p. 714) Value Common Properties, Operators, and Methods (p. 714) Modify Panel (p. 1572) Node Common Properties, Operators, and Methods (p. 820) Material Editor (p. 1606) MaterialLibrary Values (p. 795) Miscellaneous Functions (p. 1663) Material Editor (p. 1606) MaterialLibrary Values (p. 795) Zip-file Script Packages (p. 122)

loadMaxFile

3ds max File Loading and Saving (p. 1639) Zip-file Script Packages (p. 122) Running Scripts from the Command Line (p. lvii) - in example Mouse Cursors (p. 1588) - in example External File Methods (p. 1645) - in example

locals

Visibility of Locals, Functions, Structures and User-Interface Items in Rollout Code (p. 1478) Whats New in MAXScript (p. 1) Viewport Redraw Callback Mechanism (p. 1655) Time Change Callback Mechanism (p. 1654) String Values (p. 722) Scripted Plug-in Clauses (p. 1542) Scripted Custom Attributes (p. 45) Script Controllers (p. 1329) Scope of Variables (p. 646)

lockAxisTripods log log10 makeDir MakeNURBSConeSurface

Miscellaneous Viewport Methods and System Globals (p. 1603) Number Values (p. 717) Number Values (p. 717) External File Methods (p. 1645) Creating NURBSCVSurface Values (p. 1394)

Const Primitives

223

MakeNURBSCylinderSurface MakeNURBSLatheSurface MakeNURBSSphereSurface MakeNURBSTorusSurface mapScreenToCP mapScreenToView mapScreenToWorldRay matchPattern MaterialBrowseDlg MatrixFromNormal maxVersion mergeMaxFile

Creating NURBSCVSurface Values (p. 1394) Creating NURBSCVSurface Values (p. 1394) Creating NURBSCVSurface Values (p. 1394) Creating NURBSCVSurface Values (p. 1394) Accessing Active Viewport Info, Type, and Transforms (p. 1581) Accessing Active Viewport Info, Type, and Transforms (p. 1581) Accessing Active Viewport Info, Type, and Transforms (p. 1581) String Values (p. 722) ActiveX Controls in MAXScript Rollouts (p. 10) - in example Miscellaneous Dialogs (p. 1621) Matrix3 Values (p. 744) Point3 Values (p. 731) Miscellaneous Functions (p. 1663) Node Common Properties, Operators, and Methods (p. 820) 3ds max File Loading and Saving (p. 1639) Zip-file Script Packages (p. 122)

messageBox mirrorIKConstraints mod mouseTrack namedSelSetListChanged newRolloutFloate

MAXScript Message and Query Dialogs (p. 1622) Node Common Properties, Operators, and Methods (p. 820) MAX Commands (p. 1630) mouseTrack() Function (p. 180) Main Toolbar (p. 1574) Rollout Floater Windows (p. 1477) Scripted Utilities (p. 1463) Curve Control (p. 170) - in example

newScript newTrackViewNode nodeColorPicker nodeIKParamsChanged nodeInvalRect noise3 noise4 normtime numMapsUsed numNoteTracks

WindowStream Values (p. 767) The MAXScript Editor Windows (p. xliv) Track View Nodes (p. 1382) Miscellaneous Dialogs (p. 1621) Node Common Properties, Operators, and Methods (p. 820) Refreshing the Viewports (p. 1585) Node Common Properties, Operators, and Methods (p. 820) - in example Color Values (p. 729) Point3 Values (p. 731) Color Values (p. 729) Point3 Values (p. 731) Time Values (p. 751) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Notetrack Values (p. 816) Working with Note Tracks (p. 818) - in example

224

Chapter 1

Whats New in 3ds max 4 MAXScript

numSurfaces NURBSExtrudeNode NURBSLatheNode NURBSNode OkMtlForScene OKToBindToNode openBitMap openCTBitMap openEncryptedFile openfile openlog openUtility pickObject

Node Common Properties, Operators, and Methods (p. 820) Creating NURBS Scene Objects (p. 1392) Creating NURBS Scene Objects (p. 1392) Using the NURBS Classes and Functions to Create and Modify 3ds max NURBS Models (p. 1389) Interface: medit (p. 371) Node Common Properties, Operators, and Methods (p. 820) Bitmap Values (p. 755) FileStream Values (p. 763) Encrypted Files (p. 1647) Function Parameters (p. 702) - in example FileStream Values (p. 763) Turning On the Listener Log (p. xli) Utility and Rollout Properties, Methods, and Event Handlers (p. 1474) startObjectCreation() (p. 138) RubberBanding in pickObject() Function (p. 136) Picking Scene Nodes By Hit (p. 1618)

pickOffsetDistance pickPoint playAnimation pointSelection popPrompt popupMenu pow progressEnd progressStart progressUpdate PushPrompt qsort quatToEuler queryBox quitMax radToDeg

Picking Points in the Viewports (p. 1589) Keyboard Entry (p. 1623) Picking Points in the Viewports (p. 1589) Time Control (p. 1580) NURBS Node Properties and Methods (p. 1397) Node Common Properties, Operators, and Methods (p. 820) Prompt Line (p. 1577) Number Values (p. 717) Progress Bar Display (p. 1578) Progress Bar Display (p. 1578) Progress Bar Display (p. 1578) Prompt Line (p. 1577) Array Values (p. 776) EulerAngles Values (p. 742) Quat Values (p. 738) MAXScript Message and Query Dialogs (p. 1622) Running Scripts from the Command Line (p. lvii) Exiting and Resetting 3ds max (p. 1669) Number Values (p. 717)

Const Primitives

225

reactTo ReadByte ReadFloat ReadLong ReadShort ReadString redrawViews

Reactor controller (p. 91) Reactor Controllers (p. 1326) BinStream for Binary Reading and Writing (p. 128) BinStream for Binary Reading and Writing (p. 128) BinStream for Binary Reading and Writing (p. 128) BinStream for Binary Reading and Writing (p. 128) BinStream for Binary Reading and Writing (p. 128) Refreshing the Viewports (p. 1585) Picking Points in the Viewports (p. 1589) Node Common Properties, Operators, and Methods (p. 820) - in example Change Handlers and When Constructs (p. 1650)

registerDisplayFilterCallback registerOLEInterface registerRedrawViewsCallback registerRightClickMenu Exposing MAXScript Functions (p. 1673) Running the OLE Demo (p. 1674) Viewport Redraw Callback Mechanism (p. 1655) Scripted Right-Click Menus (p. 1514) subMenu (p. 1520) - in example separator (p. 1519) - in example menuItem (p. 1518) - in example registerSelectFilterCallback registerTimeCallback registerViewWindow releaseAllOLEObjects releaseOLEObject removeRollout class id filter (p. 59) Time Change Callback Mechanism (p. 1654) Rollout Floaters as Extended viewports (p. 186) ActiveX Controls in MAXScript Rollouts (p. 10) OLE Automation (p. 1671) OLE Automation (p. 1671) Utility and Rollout Properties, Methods, and Event Handlers (p. 1474) Rollout Floater Windows (p. 1477) Managing Multiple Rollouts in a Scripted Utility (p. 1468) Utility Clauses (p. 1466) - in example Visibility of Locals, Functions, Structures and User-Interface Items in Rollout Code (p. 1478) removeTempPrompt renameFile render replaceInstances replacePrompt rescaleWorldUnits Prompt Line (p. 1577) External File Methods (p. 1645) Controlling the Renderer (p. 1664) General Event Callback Mechanism (p. 29) MAXWrapper Common Properties, Operators, and Methods (p. 809) Prompt Line (p. 1577) Miscellaneous Functions (p. 1663)

226

Chapter 1

Whats New in 3ds max 4 MAXScript

resetLattice

FFD 2x2x2 : Modifier (p. 1121) FFD 3x3x3 : Modifier (p. 1123) FFD 4x4x4 : Modifier (p. 1124) FFD Box : Modifier (p. 1117) FFD Cyl : Modifier (p. 1119)

resetLengthInterp resetMaxFile rotateXMatrix rotateYMatrix rotateYPRMatrix rotateZMatrix saveMaterialLibrary saveMaxFile saveNodes scaleMatrix seed selectBitMap selectByName selectCTBitMap selectReaction selectSaveBitMap setActive setArrowCursor setAtmospheric setBackGround setBackGroundController setBkgFrameRange setBkgImageAnimate setBkgImageAspect setBkgORType setBkgStartTime setBkgSyncFrame SetCommandPanelTaskMode setCoordCenter setCurNamedSelSet setCVertMode

Shape Common Properties, Operators, and Methods (p. 945) Exiting and Resetting 3ds max (p. 1669) Matrix3 Values (p. 744) Matrix3 Values (p. 744) Matrix3 Values (p. 744) Matrix3 Values (p. 744) Material Editor (p. 1606) 3ds max File Loading and Saving (p. 1639) 3ds max File Loading and Saving (p. 1639) SelectionSetArray Values (p. 783) Matrix3 Values (p. 744) Number Values (p. 717) Bitmap Values (p. 755) Picking Scene Nodes by Name (p. 1619) Reactor Controllers (p. 1326) Bitmap Values (p. 755) Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) Render Effects Common Properties, Operators, and Methods (p. 1347) Mouse Cursors (p. 1588) Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) Working with Atmospherics (p. 1345) SetBackground Method (p. 180) Working with Atmospherics (p. 1345) Viewport Background Images (p. 1586) Viewport Background Images (p. 1586) Viewport Background Images (p. 1586) Viewport Background Images (p. 1586) Viewport Background Images (p. 1586) Viewport Background Images (p. 1586) Command Panels (p. 1571) Main Toolbar (p. 1574) Main Toolbar (p. 1574) Node Common Properties, Operators, and Methods (p. 820)

Const Primitives

227

setDimension SetDir SetDisplayFilter setEffect setFileAttribute setFocus setGroupHead setGroupMember setGroupOpen setImageBlurMultController setImageBlurMultiplier setInheritanceFlags setInheritVisibility setINISetting setKeyStepsPos setKeyStepsRot setKeyStepsScale setKeyStepsSelOnly setKeyStepsUseTrans setKnotSelection setListenerSel setListenerSelText setMaterialID setMeditMaterial

FFD Box : Modifier (p. 1117) FFD Cyl : Modifier (p. 1119) SetDir (p. 136) Selection Filter (p. 61) Render Effects Common Properties, Operators, and Methods (p. 1347) External File Methods (p. 1645) -jpr M029-SO selection as bitArray, ConvertTo for PolyMesh, SetFocus Minton Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) General Node Properties (p. 836) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Accessing INI File Keys (p. 1647) Time Configuration Dialog (p. 1616) Time Configuration Dialog (p. 1616) Time Configuration Dialog (p. 1616) Time Configuration Dialog (p. 1616) Time Configuration Dialog (p. 1616) SplineShape : Shape (p. 1079) Controlling the Listener Contents and the Insertion Point (p. xlii) Controlling the Listener Contents and the Insertion Point (p. xlii) SplineShape : Shape (p. 1079) Material Common Properties, Operators, and Methods (p. 1203) Material Editor (p. 1606) MaterialLibrary Values (p. 795)

setMKTime setMKWeight setMorphTarget setMorphTargetName setMotBlur setMTLMEditFlags setMTLMeditObjType setMTLMeditTiling setOpenSceneScript setPatchSteps

Barycentric Morph Controller Keys (p. 1308) Barycentric Morph Controller Keys (p. 1308) Barycentric Morph Controller : MorphController (p. 1306) Barycentric Morph Controller : MorphController (p. 1306) Node Common Properties, Operators, and Methods (p. 820) Material Common Properties, Operators, and Methods (p. 1203) Material Common Properties, Operators, and Methods (p. 1203) Material Common Properties, Operators, and Methods (p. 1203) Patch : GeometryClass (p. 1088)

228

Chapter 1

Whats New in 3ds max 4 MAXScript

setPosTaskWeight setProgressCancel setProperty SetPropertyController setReactionFalloff setReactionInfluence setReactionName setReactionState setReactionStrength setReactionValue setRefCoordSys setRenderable setRenderID setRotTaskWeight setSaveRequired setSaveSceneScript setSegSelection SetSelectFilter setShadeCVerts setSilentMode setSplineSelection setStatusXYZ setSysCur setTaskAxisState setToolBtnState setTrajectoryOn setTransformLockFlags SetUIColor setupEvents SetUseDraftRenderer setUseEnvironmentMap setVPortBGColor setWaitCursor ShellLaunch showAllActiveXControls

Node Common Properties, Operators, and Methods (p. 820) Progress Bar Display (p. 1578) Class and Object Inspector Functions (p. 799) ActiveX Controls in MAXScript Rollouts (p. 10) - in example Class and Object Inspector Functions (p. 799) Reactor Controllers (p. 1326) Reactor Controllers (p. 1326) Reactor Controllers (p. 1326) Reactor Controllers (p. 1326) Reactor Controllers (p. 1326) Reactor Controllers (p. 1326) Main Toolbar (p. 1574) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Exiting and Resetting 3ds max (p. 1669) undo (p. 687) SplineShape : Shape (p. 1079) Selection Filter (p. 61) Node Common Properties, Operators, and Methods (p. 820) Bitmap Values (p. 755) SplineShape : Shape (p. 1079) Coordinate Display (p. 1578) Mouse Cursors (p. 1588) Node Common Properties, Operators, and Methods (p. 820) Main Toolbar (p. 1574) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) 3ds max User Interface Colors (p. 1604) Render Scene Dialog (p. 1611) Working with Atmospherics (p. 1345) Miscellaneous Viewport Methods and System Globals (p. 1603) Mouse Cursors (p. 1588) Executing External Commands (p. 1668) ActiveX Controls in MAXScript Rollouts (p. 10)

Const Primitives

229

showClass showEvents showMethods showSource showTextureMap

Class and Object Inspector Functions (p. 799) Dynamic Properties (p. 805) ActiveX Controls in MAXScript Rollouts (p. 10) ActiveX Controls in MAXScript Rollouts (p. 10) The MAXScript Editor Windows (p. xliv) Creating Functions (p. 699) showTextureMap() function (p. 167) Material Editor (p. 1606) Node Common Properties, Operators, and Methods (p. 820) - in example TextureMap Common Properties, Operators, and Methods (p. 1235) Working with Editable Meshes (p. 1077)

silentMode sin sinh sleep snapshotAsMesh sqrt squadrev startObjectCreation

Bitmap Values (p. 755) Number Values (p. 717) Number Values (p. 717) Pausing Script Execution (p. 1664) Node Common Properties, Operators, and Methods (p. 820) Number Values (p. 717) Quat Values (p. 738) Create Panel (p. 1572) Defining Macro Scripts (p. 1521) startObjectCreation() (p. 138)

startTool stopAnimation stopCreating

Mouse Tool Clauses (p. 1532) Scripted Mouse Tools (p. 1531) Time Control (p. 1580) Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397) Modifying Existing NURBS Objects (p. 1390)

stopTool subdivideSegment swap tan tangentCurve3D tanh thawSelection timeStamp TransMatrix

Scripted Mouse Tools (p. 1531) SplineShape : Shape (p. 1079) Miscellaneous Functions (p. 1663) Number Values (p. 717) SplineShape : Shape (p. 1079) Number Values (p. 717) Status Bar Buttons (p. 1579) Time Stamping (p. 1664) Matrix3 Values (p. 744) Scripted Manipulator (p. 97) - in example Scripted Manipulators (p. 97) - in example

230

Chapter 1

Whats New in 3ds max 4 MAXScript

turbulence ungroup uniqueName unregisterAllRightClickMenus unregisterRightClickMenu unregisterSelectFilterCallback unregisterTimeCallback unRegisterViewWindow updateMTLInMedit updateSurfaceMapper validModifier

Color Values (p. 729) Point3 Values (p. 731) Node Common Properties, Operators, and Methods (p. 820) Node Common Properties, Operators, and Methods (p. 820) Scripted Right-Click Menus (p. 1514) Scripted Right-Click Menus (p. 1514) class id filter (p. 59) Time Change Callback Mechanism (p. 1654) Rollout Floaters as Extended viewports (p. 186) Material Common Properties, Operators, and Methods (p. 1203) Surface Mapper : SpacewarpModifier (p. 1202) Node Common Properties, Operators, and Methods (p. 820) validModifer() function (p. 142) Modifier Common Properties, Operators, and Methods (p. 1096)

unregisterRedrawViewsCallback Viewport Redraw Callback Mechanism (p. 1655)

WriteByte WriteFloat WriteLong WriteShort WriteString yesNoCancelBox

BinStream for Binary Reading and Writing (p. 128) BinStream for Binary Reading and Writing (p. 128) BinStream for Binary Reading and Writing (p. 128) BinStream for Binary Reading and Writing (p. 128) BinStream for Binary Reading and Writing (p. 128) MAXScript Message and Query Dialogs (p. 1622)

See Also
Definitions for MAXScript internal organization (p. 188)

Const StructDef

231

Const StructDef
AttachCtrl (p. 232) autoBackup (p. 232) bit (p. 233) boolObj (p. 233) callbacks (p. 233) cui (p. 234) custAttributes (p. 234) DOF (p. 234) fileProperties (p. 235) flexOps (p. 235) gw (p. 235) ik (p. 237) keyboard (p. 237) LE (p. 237) LinkCtrl (p. 238) ListCtrl (p. 238) logsystem (p. 238) macros (p. 239) mapPaths (p. 239) meshop (p. 239) meshOps (p. 243) modPanel (p. 244) mouse (p. 244) mtlBrowser (p. 244) options (p. 245) patch (p. 245) patchOps (p. 247) persistents (p. 247) polyop (p. 248) polyOps (p. 251) patch.getEdgeVec21 preferences (p. 252) refs (p. 252) scanlineRender (p. 252) schematicView (p. 252)

232

Chapter 1

Whats New in 3ds max 4 MAXScript

skinOps (p. 253) snapMode (p. 254) splineOps (p. 255) sysInfo (p. 255) systemTools (p. 256) terrainOps (p. 256) timeConfiguration (p. 256) toolMode (p. 257) trackbar (p. 257) trackview (p. 257) units (p. 258) viewport (p. 258) WAVsound (p. 258) xrefPaths (p. 259) xrefs (p. 259)

See Also
Definitions for MAXScript internal organization (p. 188)

Const StructDef Pages

AttachCtrl const StructDef
Attachment : PositionController (p. 1304)
AttachCtrl.addNewKey AttachCtrl.getKey

Attachment Controller Keys (p. 1305)

autoBackup const StructDef

3D Studio MAX System Globals (p. 630)
autoBackup.enabled autoBackup.time SystemGlobal:enabled SystemGlobal:time false 5.0

bit const StructDef

233

bit const StructDef

Number Values (p. 717)
bit.and bit.charAsInt bit.flip bit.get bit.intAsChar bit.intAsHex bit.not bit.or bit.set bit.shift bit.xor

boolObj const StructDef

Boolean2 : GeometryClass (p. 887)
boolObj.createBooleanObject boolObj.GetBoolCutType boolObj.GetBoolOp boolObj.GetDisplayResult boolObj.GetOperandSel boolObj.GetOptimize boolObj.GetShowHiddenOps boolObj.GetUpdateMode boolObj.SetBoolCutType boolObj.SetBoolOp boolObj.SetDisplayResult boolObj.setOperandB boolObj.SetOperandSel boolObj.SetOptimize boolObj.SetShowHiddenOps boolObj.SetUpdateMode

callbacks const StructDef

General Event Callback Mechanism (p. 29)
callbacks.addScript callbacks.broadcastCallback callbacks.removeScripts callbacks.show

234

Chapter 1

Whats New in 3ds max 4 MAXScript

cui const StructDef

3D Studio MAX System Globals (p. 630) Menu and CUI Loading Command Panels (p. 1571) Custom User Interface Files (p. 1648)
cui.commandPanelOpen cui.expertModeOff cui.expertModeOn cui.getConfigFile cui.GetDir cui.getExpertMode cui.loadConfig cui.saveConfig cui.saveConfigAs cui.setConfigFile SystemGlobal:commandPanelOpen true

custAttributes const StructDef

Scripted Custom Attributes (p. 45)
custAttributes.add custAttributes.count custAttributes.delete custAttributes.deleteDef custAttributes.get custAttributes.getDef custAttributes.getDefData custAttributes.getDefs custAttributes.getDefSource custAttributes.getPBlockDefs custAttributes.getSceneDefs custAttributes.makeUnique custAttributes.redefine custAttributes.setDefData

DOF const StructDef

Depth of Field : RenderEffect (p. 1354)
DOF.addCam DOF.addFocalNode DOF.deleteCam DOF.deleteCamByName DOF.deleteFocalNode DOF.deleteFocalNodeByName

fileProperties const StructDef

235

fileProperties const StructDef

3ds max Scene File Properties (p. 1628)
fileProperties.addProperty fileProperties.deleteProperty fileProperties.findProperty fileProperties.getItems fileProperties.getNumProperties fileProperties.getPropertyName fileProperties.getPropertyValue

flexOps const StructDef

Flex : Modifier (p. 1128)
flexOps.ClearEdgeVertices flexOps.GetNumberVertices flexOps.GetVertexWeight flexOps.isEdgeVertex flexOps.SelectVertices flexOps.SetEdgeVertices flexOps.SetVertexWeights

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

gw const StructDef
Viewport Drawing Methods (p. 1592)
gw.clearScreen gw.enlargeUpdateRect gw.GetCPDisp gw.getDriverString gw.getFlipped gw.GetFocalDist gw.getHitherCoord gw.getMaxLights

236

Chapter 1

Whats New in 3ds max 4 MAXScript

gw.GetPointOnCP gw.getRndLimits gw.getRndMode gw.getSkipCount gw.getUpdateRect gw.getViewportDib gw.GetVPWorldWidth gw.getWinDepth gw.getWinSizeX gw.getWinSizeY gw.getYonCoord gw.hMarSker gw.hPolygon gw.hPolyline gw.hText gw.hTransPoint gw.hTriStrip gw.isPerspectiveView gw.IsPerspView gw.MapCPToWorld gw.marker gw.NonScalingObjectSize gw.polygon gw.polyline gw.querySupport gw.resetUpdateRect gw.setColor gw.setPos gw.setRndLimits gw.setSkipCount gw.setTransform gw.SnapLength gw.SnapPoint gw.text gw.transPoint gw.updateScreen gw.wMarker gw.wPolygon gw.wPolyline gw.wText gw.wTransPoint gw.wTriStrip

See Also
Accessing Active Viewport Info, Type, and Transforms (p. 1581)

ik const StructDef

237

ik const StructDef
IK_ControllerMatrix3Controller : Matrix3Controller (p. 1313)
ik.getBindOrient ik.getBindPos ik.GetEndTime ik.getIsTerminator ik.GetIterations ik.getPinNode ik.GetPosThreshold ik.getPrecedence ik.GetRotThreshold ik.GetStartTime ik.setBindOrient ik.setBindPos ik.SetEndTime ik.setIsTerminator ik.SetIterations ik.setPinNode ik.SetPosThreshold ik.setPrecedence ik.SetRotThreshold ik.SetStartTime

keyboard const StructDef

3D Studio MAX System Globals (p. 630) Keyboard Entry (p. 1623)
keyboard.altPressed keyboard.controlPressed keyboard.escPressed keyboard.shiftPressed SystemGlobal:altPressed SystemGlobal:controlPressed SystemGlobal:escPressed SystemGlobal:shiftPressed false false false false

LE const StructDef
Lens Effects : RenderEffect (p. 1357)
LE.addASec LE.addGlow LE.addLight LE.addLightNode LE.addMSec (p. 1366) LE.addRay LE.addRing LE.addStar LE.addStreak (p. 1379) LE.deleteElement LE.deleteElementByName LE.deleteLight

238

Chapter 1

Whats New in 3ds max 4 MAXScript

LE.deleteLightByName LE.lightIndex LE.lightName LE.load LE.numLights LE.save

LinkCtrl const StructDef

Link Control : Matrix3Controller (p. 1316)
LinkCtrl.addLink LinkCtrl.deleteLink LinkCtrl.getLinkCount LinkCtrl.getLinkNode LinkCtrl.getLinkTime LinkCtrl.setLinkNode LinkCtrl.setLinkTime

ListCtrl const StructDef

List Controller (p. 143)
ListCtrl.getActive ListCtrl.getName ListCtrl.setActive ListCtrl.setName

See Also
List Controllers (p. 1317)

ListCtrl const StructDef

List Controller (p. 143)
ListCtrl.getActive ListCtrl.getName ListCtrl.setActive ListCtrl.setName

See Also
List Controllers (p. 1317)

logsystem const StructDef

239

logsystem const StructDef

3D Studio MAX System Globals (p. 630)
logsystem.quietMode SystemGlobal:quietMode false

macros const StructDef

Macro Scripts (p. 1624) Defining Macro Scripts (p. 1521)
macros.edit macros.load macros.new macros.run

mapPaths const StructDef

3ds max System Directories (p. 1625)
mapPaths.add mapPaths.count mapPaths.delete mapPaths.get

meshop const StructDef

Editable_Mesh : GeometryClass and TriMesh : Value (p. 1041)
meshop.applyUVWMap meshop.attach meshop.autoEdge meshop.autosmooth meshop.bevelFaces meshop.breakVerts meshop.buildMapFaces meshop.chamferEdges meshop.chamferVerts meshop.cloneEdges meshop.cloneFaces meshop.cloneVerts meshop.collapseEdges meshop.collapseFaces meshop.createPolygon meshop.cut meshop.defaultMapFaces meshop.deleteEdges meshop.deleteFaces meshop.deleteIsoMapVerts meshop.deleteIsoMapVertsAll meshop.deleteIsoVerts

240

Chapter 1

Whats New in 3ds max 4 MAXScript

meshop.deleteMapVertSet meshop.deleteVerts meshop.detachFaces meshop.detachVerts meshop.divideEdge meshop.divideEdges meshop.divideFace meshop.divideFaceByEdges meshop.divideFaces meshop.edgeTessellate meshop.explodeAllFaces meshop.explodeFaces meshop.extrudeEdges meshop.extrudeFaces meshop.flipNormals meshop.freeMapChannel meshop.freeMapFaces meshop.freeMapVerts meshop.freeVAlphas meshop.freeVData meshop.freeVertCorners meshop.freeVertWeights meshop.freeVSelectWeights meshop.getAffectBackfacing meshop.getBaryCoords meshop.getBubble meshop.getDisplacementMapping meshop.getEdgesReverseEdge meshop.getEdgesUsingFace meshop.getEdgesUsingVert meshop.getElementsUsingFace meshop.getExtrusionType meshop.getFaceArea meshop.getFaceCenter meshop.getFaceRNormals meshop.getFacesUsingEdge meshop.getFacesUsingVert meshop.getFalloff meshop.getHiddenFaces meshop.getHiddenVerts meshop.getIgnoreBackfacing meshop.getIgnoreVisEdges meshop.getIsoMapVerts meshop.getIsoVerts meshop.getMapFace meshop.getMapFacesUsingMapVert meshop.getMapSupport meshop.getMapVert meshop.getMapVertsUsingMapFace meshop.getNormalSize meshop.getNumCPVVerts

meshop const StructDef

241

meshop.getNumFaces meshop.getNumMapFaces meshop.getNumMaps meshop.getNumMapVerts meshop.getNumTVerts meshop.getNumVDataChannels meshop.getNumVerts meshop.getOpenEdges meshop.getPinch meshop.getPlanarThreshold meshop.getPolysUsingEdge meshop.getPolysUsingFace meshop.getPolysUsingVert meshop.getSelByVertex meshop.getShowFNormals meshop.getShowVNormals meshop.getSoftSel meshop.getSplitMesh meshop.getSSEdgeDist meshop.getSSUseEdgeDist meshop.getSubdivisionAngle meshop.getSubdivisionDisplacement meshop.getSubdivisionDistance meshop.getSubdivisionEdge meshop.getSubdivisionMaxLevels meshop.getSubdivisionMaxTriangles meshop.getSubdivisionMethod meshop.getSubdivisionMinLevels meshop.getSubdivisionSteps meshop.getSubdivisionStyle meshop.getSubdivisionView meshop.getUIParam meshop.getVAlpha meshop.getVDataChannelSupport meshop.getVDataValue meshop.getVert meshop.getVertCorner meshop.getVertexAngles meshop.getVertsByColor meshop.getVertsUsedOnlyByFaces meshop.getVertsUsingEdge meshop.getVertsUsingFace meshop.getVertWeight meshop.getVSelectWeight meshop.getWeldPixels meshop.getWeldThreshold meshop.makeFacesPlanar meshop.makeMapPlanar meshop.makeVertsPlanar meshop.minVertexDistanceFrom meshop.minVertexDistancesFrom

242

Chapter 1

Whats New in 3ds max 4 MAXScript

meshop.moveVert meshop.moveVertsToPlane meshop.optimize meshop.removeDegenerateFaces meshop.removeIllegalFaces meshop.resetVAlphas meshop.resetVertCorners meshop.resetVertWeights meshop.resetVSelectWeights meshop.setAffectBackfacing meshop.setBubble meshop.setDisplacementMapping meshop.setExtrusionType meshop.setFaceAlpha meshop.setFaceColor meshop.setFalloff meshop.setHiddenFaces meshop.setHiddenVerts meshop.setIgnoreBackfacing meshop.setIgnoreVisEdges meshop.setMapFace meshop.setMapSupport meshop.setMapVert meshop.setNormalSize meshop.setNumCPVVerts meshop.setNumFaces meshop.setNumMapFaces meshop.setNumMaps meshop.setNumMapVerts meshop.setNumTVerts meshop.setNumVDataChannels meshop.setNumVerts meshop.setPinch meshop.setPlanarThreshold meshop.setSelByVertex meshop.setShowFNormals meshop.setShowVNormals meshop.setSoftSel meshop.setSplitMesh meshop.setSSEdgeDist meshop.setSSUseEdgeDist meshop.setSubdivisionAngle meshop.setSubdivisionDisplacement meshop.setSubdivisionDistance meshop.setSubdivisionEdge meshop.setSubdivisionMaxLevels meshop.setSubdivisionMaxTriangles meshop.setSubdivisionMethod meshop.setSubdivisionMinLevels meshop.setSubdivisionSteps meshop.setSubdivisionStyle

meshOps const StructDef

243

meshop.setSubdivisionView meshop.setUIParam meshop.setVAlpha meshop.setVDataChannelSupport meshop.setVDataValue meshop.setVert meshop.setVertAlpha meshop.setVertColor meshop.setVertCorner meshop.setVertWeight meshop.setVSelectWeight meshop.setWeldPixels meshop.setWeldThreshold meshop.slice meshop.supportVAlphas meshop.supportVertCorners meshop.supportVertWeights meshop.supportVSelectWeights meshop.turnEdge meshop.unifyNormals meshop.weldVertsByThreshold meshop.weldVertSet

meshOps const StructDef

Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
meshOps.attachList meshOps.autoEdge meshOps.autosmooth meshOps.break meshOps.clearAllSG meshOps.collapse meshOps.createShapeFromEdges meshOps.delete meshOps.detach meshOps.explode meshOps.flipNormal meshOps.gridAlign meshOps.hide meshOps.invisibleEdge meshOps.makePlanar meshOps.removeIsolatedVerts meshOps.selectByColor meshOps.selectByID meshOps.selectBySG meshOps.selectOpenEdges meshOps.showNormal meshOps.slice meshOps.startAttach meshOps.startBevel

244

Chapter 1

Whats New in 3ds max 4 MAXScript

meshOps.startChamfer meshOps.startCreate meshOps.startCut meshOps.startDivide meshOps.startExtrude meshOps.startFlipNormalMode meshOps.startSlicePlane meshOps.startTurn meshOps.startWeldTarget meshOps.tessellate meshOps.unhideAll meshOps.unifyNormal meshOps.viewAlign meshOps.visibleEdge meshOps.weld

modPanel const StructDef

Modify Panel (p. 1572)
modPanel.addModToSelection modPanel.getCurrentObject modPanel.getModifierIndex modPanel.setCurrentObject

See Also
Modifier Common Properties, Operators, and Methods (p. 1096) Modifier : MAXWrapper and SpacewarpModifier : MAXWrapper (p. 1095)

mouse const StructDef

Mouse Cursors (p. 1588)
mouse.buttonStates mouse.mode mouse.pos mouse.screenpos SystemGlobal:screenpos SystemGlobal:buttonStates SystemGlobal:mode SystemGlobal:pos [657,577] #{} 0 [106,85]

mtlBrowser const StructDef

Miscellaneous Dialogs (p. 1621)
mtlBrowser.browseFrom

See Also
mtlBrowser (p. 180)

options const StructDef

245

options const StructDef

MAXScript System Globals (p. 640)
options.oldPrintStyles SystemGlobal:oldPrintStyles false

See Also
Value Common Properties, Operators, and Methods (p. 714)

patch const StructDef

Patches (p. 55) Patch : GeometryClass (p. 1088)
patch.addQuadPatch patch.addTriPatch patch.autosmooth patch.changePatchInteriorType patch.changeVertType patch.clonePatchParts patch.deletePatchParts patch.edgeNormal patch.flipPatchNormal patch.getAdaptive patch.getEdges patch.getEdgeVec12 patch.getEdgeVert1 patch.getEdgeVert2 patch.getMapPatch patch.getMapSupport patch.getMapVert patch.getMesh patch.getMeshSteps patch.getMeshStepsRender patch.getMtlID patch.getNumEdges patch.getNumMaps patch.getNumMapVerts patch.getNumPatches patch.getNumVecs patch.getNumVerts patch.getPatches patch.getPatchInteriorType patch.getPatchMtlID patch.getShowInterior patch.getVec patch.getVecPatches patch.getVectors patch.getVecVert patch.getVert

246

Chapter 1

Whats New in 3ds max 4 MAXScript

patch.getVertEdges patch.getVertPatches patch.getVertType patch.getVertVecs patch.interpQuadPatch patch.interpTriPatch patch.makeQuadPatch patch.makeTriPatch patch.maxMapChannels patch.patchNormal patch.setAdaptive patch.setMapPatch patch.setMapSupport patch.setMapVert patch.setMeshSteps patch.setMeshStepsRender patch.setMtlID patch.setNumEdges patch.setNumMapPatches patch.setNumMaps patch.setNumMapVerts patch.setNumPatches patch.setNumVecs patch.setNumVerts patch.setPatchMtlID patch.setShowInterior patch.setVec patch.setVert patch.subdivideEdges patch.subdividePatches patch.transform patch.unifyNormals patch.update patch.updatePatchNormals patch.weld2Verts patch.weldEdges patch.weldVerts

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

patchOps const StructDef

247

patchOps const StructDef

Patch : GeometryClass (p. 1088)
patchOps.addQuad patchOps.addTri patchOps.break patchOps.clearAllSG patchOps.createShapeFromEdges patchOps.delete patchOps.detach patchOps.flipNormal patchOps.hide patchOps.selectByID patchOps.selectBySG patchOps.selectOpenEdges patchOps.startAttach patchOps.startBevel patchOps.startBind patchOps.startCreate patchOps.startExtrude patchOps.startFlipNormalMode patchOps.startWeldTarget patchOps.subdivide patchOps.unbind patchOps.unhideAll patchOps.unifyNormal patchOps.weld

See Also
Patches (p. 55) patch const StructDef (p. 245) patchOps const StructDef (p. 247) Patch_Select - superclass: modifier (p. 307)

persistents const StructDef

Persistent Global Variables (p. 651)
persistents.remove persistents.removeAll persistents.show

248

Chapter 1

Whats New in 3ds max 4 MAXScript

polyop const StructDef

polyop.applyUVWMap polyop.attach polyop.autosmooth polyop.breakVerts polyop.capHolesByEdge polyop.capHolesByFace polyop.capHolesByVert polyop.collapseDeadStructs polyop.collapseEdges polyop.collapseFaces polyop.collapseVerts polyop.createEdge polyop.createPolygon polyop.createShape polyop.createVert polyop.cutEdge polyop.cutFace polyop.cutVert polyop.defaultMapFaces polyop.deleteEdges polyop.deleteFaces polyop.deleteIsoVerts polyop.deleteVerts polyop.detachEdges polyop.detachFaces polyop.detachVerts polyop.divideEdge polyop.divideFace polyop.fillInMesh polyop.flipNormals polyop.forceSubdivision polyop.freeEData polyop.freeVData polyop.getBorderFromEdge polyop.getDeadEdges polyop.getDeadFaces polyop.getDeadVerts polyop.getEDataChannelSupport polyop.getEDataValue polyop.getEdgeFaces polyop.getEdgeFlags polyop.getEdgesByFlag polyop.getEdgeSelection polyop.getEdgesUsingFace polyop.getEdgesUsingVert polyop.getEdgeVerts polyop.getEdgeVis polyop.getElementsUsingFace polyop.getFaceArea

polyop const StructDef

249

polyop.getFaceCenter polyop.getFaceDeg polyop.getFaceEdges polyop.getFaceFlags polyop.getFaceMatID polyop.getFaceNormal polyop.getFacesByFlag polyop.getFaceSelection polyop.getFaceSmoothGroup polyop.getFacesUsingEdge polyop.getFacesUsingVert polyop.getFaceVerts polyop.getHasDeadStructs polyop.getHiddenFaces polyop.getHiddenVerts polyop.getMapFace polyop.getMapSupport polyop.getMapVert polyop.getNumEDataChannels polyop.getNumEdges polyop.getNumFaces polyop.getNumMapFaces polyop.getNumMaps polyop.getNumMapVerts polyop.getNumVDataChannels polyop.getNumVerts polyop.getOpenEdges polyop.getSafeFaceCenter polyop.getSlicePlane polyop.getVDataChannelSupport polyop.getVDataValue polyop.getVert polyop.getVertFlags polyop.getVertsByColor polyop.getVertsByFlag polyop.getVertSelection polyop.getVertsUsedOnlyByFaces polyop.getVertsUsingEdge polyop.getVertsUsingFace polyop.inSlicePlaneMode polyop.isEdgeDead polyop.isFaceDead polyop.isMeshFilledIn polyop.isVertDead polyop.makeEdgesPlanar polyop.makeFacesPlanar polyop.makeVertsPlanar polyop.meshSmoothByEdge polyop.meshSmoothByFace polyop.meshSmoothByVert polyop.moveEdgesToPlane

250

Chapter 1

Whats New in 3ds max 4 MAXScript

polyop.moveFacesToPlane polyop.moveVert polyop.moveVertsToPlane polyop.propagateFlags polyop.resetEData polyop.resetSlicePlane polyop.resetVData polyop.retriangulate polyop.setDiagonal polyop.setEDataChannelSupport polyop.setEDataValue polyop.setEdgeFlags polyop.setEdgeSelection polyop.setEdgeVis polyop.setFaceColor polyop.setFaceFlags polyop.setFaceMatID polyop.setFaceSelection polyop.setFaceSmoothGroup polyop.setHiddenFaces polyop.setHiddenVerts polyop.setMapFace polyop.setMapSupport polyop.setMapVert polyop.setNumEDataChannels polyop.setNumMapFaces polyop.setNumMaps polyop.setNumMapVerts polyop.setNumVDataChannels polyop.setSlicePlane polyop.setVDataChannelSupport polyop.setVDataValue polyop.setVert polyop.setVertColor polyop.setVertFlags polyop.setVertSelection polyop.slice polyop.splitEdges polyop.tessellateByEdge polyop.tessellateByFace polyop.tessellateByVert polyop.unHideAllFaces polyop.unHideAllVerts polyop.weldEdges polyop.weldEdgesByThreshold polyop.weldVerts polyop.weldVertsByThreshold

polyOps const StructDef

251

polyOps const StructDef

polyOps.attachList polyOps.autosmooth polyOps.break polyOps.cap polyOps.clearAllSG polyOps.collapse polyOps.createShapeFromEdges polyOps.delete polyOps.detach polyOps.flipNormal polyOps.gridAlign polyOps.hide polyOps.makePlanar polyOps.meshsmooth polyOps.NamedSelCopy polyOps.NamedSelPaste polyOps.removeIsolatedVerts polyOps.resetPlane polyOps.retriangulate polyOps.selectByColor polyOps.selectByID polyOps.selectBySG polyOps.slice polyOps.split polyOps.startBevel polyOps.startChamferEdge polyOps.startChamferVertex polyOps.startCreateEdge polyOps.startCreateFace polyOps.startCreateVertex polyOps.startCutEdge polyOps.startCutFace polyOps.startCutVertex polyOps.startDivideEdge polyOps.startDivideFace polyOps.startEditTri polyOps.startExtrudeEdge polyOps.startExtrudeFace polyOps.startExtrudeVertex polyOps.startSlicePlane polyOps.startWeldTarget polyOps.tessellate polyOps.unhide polyOps.update polyOps.viewAlign polyOps.weld

252

Chapter 1

Whats New in 3ds max 4 MAXScript

preferences const StructDef

3D Studio MAX System Globals (p. 630)
preferences.constantReferenceSystem preferences.flyOffTime preferences.maximumGBufferLayers preferences.spinnerWrap preferences.useLargeVertexDots preferences.useTransformGizmos preferences.useVertexDots SystemGlobal:constantReferenceSystem SystemGlobal:flyOffTime SystemGlobal:maximumGBufferLayers SystemGlobal:spinnerWrap SystemGlobal:useLargeVertexDots SystemGlobal:useTransformGizmos SystemGlobal:useVertexDots false 300 10 false false true true

See Also
Miscellaneous Viewport Methods and System Globals (p. 1603)

refs const StructDef

MAXWrapper Common Properties, Operators, and Methods (p. 809)
refs.dependents

scanlineRender const StructDef

Render Scene Dialog (p. 1611)
scanlineRender.antiAliasFilter scanlineRender.antiAliasFilterSize scanlineRender.enablePixelSampler SystemGlobal:antiAliasFilter SystemGlobal:antiAliasFilterSize SystemGlobal:enablePixelSampler Area: 1.5 true

See Also
3D Studio MAX System Globals (p. 630) 3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters (p. 1614)

schematicView const StructDef

Schematic View (p. 1615)
schematicView.close schematicView.getSchematicViewName schematicView.numSchematicViews schematicView.open schematicView.zoomSelected

skinOps const StructDef

253

skinOps const StructDef

Skin : Modifier (p. 1157)
skinOps.AddBone skinOps.addBoneFromViewEnd skinOps.addBoneFromViewStart skinOps.AddCrossSection skinOps.buttonAdd skinOps.buttonAddCrossSection skinOps.buttonAddGizmo skinOps.buttonCopyGizmo skinOps.buttonExclude skinOps.buttonInclude skinOps.buttonPaint skinOps.buttonPasteGizmo skinOps.buttonRemove skinOps.buttonRemoveCrossSection skinOps.buttonRemoveGizmo skinOps.buttonSelectExcluded skinOps.copySelectedBone skinOps.enableGizmo skinOps.GetBoneName skinOps.getBonePropEnvelopeVisible skinOps.getBonePropFalloff skinOps.getBonePropRelative skinOps.GetCrossSectionU skinOps.GetEndPoint skinOps.GetInnerRadius skinOps.GetNumberBones skinOps.GetNumberCrossSections skinOps.getNumberOfGizmos skinOps.getNumberOfGizmoTypes skinOps.GetNumberVertices skinOps.GetOuterRadius skinOps.GetSelectedBone skinOps.getSelectedBonePropEnvelopeVisible skinOps.getSelectedBonePropFalloff skinOps.getSelectedBonePropRelative skinOps.getSelectedGizmo skinOps.getSelectedGizmoType skinOps.GetStartPoint skinOps.GetVertexWeight skinOps.GetVertexWeightBoneID skinOps.GetVertexWeightCount skinOps.isBoneSelected skinOps.IsVertexModified skinOps.IsVertexSelected skinOps.loadEnvelope skinOps.multiRemove skinOps.pasteToAllBones skinOps.pasteToBone

254

Chapter 1

Whats New in 3ds max 4 MAXScript

skinOps.pasteToSelectedBone skinOps.RemoveBone skinOps.RemoveCrossSection skinOps.ReplaceVertexWeights skinOps.resetAllBones skinOps.resetSelectedBone skinOps.resetSelectedVerts skinOps.saveEnvelope skinOps.SelectBone skinOps.selectCrossSection skinOps.selectEndPoint skinOps.selectGizmo skinOps.selectGizmoType skinOps.selectNextBone skinOps.selectPreviousBone skinOps.selectStartPoint skinOps.SelectVertices skinOps.setBonePropEnvelopeVisible skinOps.setBonePropFalloff skinOps.setBonePropRelative skinOps.SetCrossSectionU skinOps.SetEndPoint skinOps.SetInnerRadius skinOps.SetOuterRadius skinOps.setSelectedBonePropEnvelopeVisible skinOps.setSelectedBonePropFalloff skinOps.setSelectedBonePropRelative skinOps.SetStartPoint skinOps.SetVertexWeights skinOps.ZoomToBone skinOps.ZoomToGizmo

snapMode const StructDef

Status Bar Buttons (p. 1579)
snapMode.active snapMode.type SystemGlobal:active SystemGlobal:type false 3D

See Also
snapMode (p. 182) 3D Studio MAX System Globals (p. 630)

splineOps const StructDef

255

splineOps const StructDef

SplineShape : Shape (p. 1079)
splineOps.attachMultiple splineOps.close splineOps.cycle splineOps.delete splineOps.detach splineOps.divide splineOps.explode splineOps.fuse splineOps.hide splineOps.intersect splineOps.makeFirst splineOps.mirrorBoth splineOps.mirrorHoriz splineOps.mirrorVert splineOps.reverse splineOps.selectByID splineOps.startAttach splineOps.startBind splineOps.startBreak splineOps.startChamfer splineOps.startConnect splineOps.startCreateLine splineOps.startCrossInsert splineOps.startExtend splineOps.startFillet splineOps.startInsert splineOps.startIntersect splineOps.startOutline splineOps.startRefine splineOps.startRefineConnect splineOps.startSubtract splineOps.startTrim splineOps.startUnion splineOps.unbind splineOps.unhideAll splineOps.weld

sysInfo const StructDef

System Information (p. 141)
sysInfo.computername sysInfo.cpucount sysInfo.currentdir sysInfo.DesktopBPP sysInfo.DesktopSize sysInfo.getMAXMemoryInfo sysInfo.getSystemMemoryInfo SystemGlobal:computername SystemGlobal:cpucount SystemGlobal:currentdir SystemGlobal:DesktopBPP SystemGlobal:DesktopSize P3 2 F:\M042 16 [1280,1024]

256

Chapter 1

Whats New in 3ds max 4 MAXScript

sysInfo.MAXPriority sysInfo.systemdir NT\System32 sysInfo.tempdir SystemGlobal:tempdir sysInfo.username strator sysInfo.windowsdir NT

SystemGlobal:MAXPriority SystemGlobal:systemdir

normal D:\WIN

D:\TEMP\ SystemGlobal:username SystemGlobal:windowsdir

Admini D:\WIN

systemTools const StructDef

System Tools (p. 112)
systemTools.GetScreenHeight systemTools.GetScreenWidth systemTools.IsDebugging systemTools.IsWindows98or2000 systemTools.IsWindows9x systemTools.NumberOfProcessors

terrainOps const StructDef

Terrain : GeometryClass (p. 894)
terrainOps.addOperand terrainOps.deleteOperand terrainOps.getOperand terrainOps.getOperandTM terrainOps.setOperandTM terrainOps.update

timeConfiguration const StructDef

Time Configuration Dialog (p. 1616)
timeConfiguration.playActiveOnly timeConfiguration.playbackSpeed timeConfiguration.realTimePlayback timeConfiguration.useTrackBar SystemGlobal:playActiveOnly SystemGlobal:playbackSpeed SystemGlobal:realTimePlayback SystemGlobal:useTrackBar true 3 true true

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

toolMode const StructDef

257

toolMode const StructDef

Main Toolbar (p. 1574)
toolMode.AxisConstraints toolMode.CommandMode toolMode.coordsys toolMode.nonUniformScale toolMode.pivotCenter toolMode.selectionCenter toolMode.squashScale toolMode.transformCenter toolMode.uniformScale SystemGlobal:AxisConstraints SystemGlobal:CommandMode XY select

See Also
Trackbar (p. 1581)

trackbar const StructDef

3D Studio MAX System Globals (p. 630)
trackbar.filter trackbar.GetNextKeyTime trackbar.GetPreviousKeyTime trackbar.visible SystemGlobal:filter all

SystemGlobal:visible

true

See Also
Trackbar (p. 1581) maxOps (p. 87) ItrackBar (p. 113)

trackView const StructDef

Track View (p. 1609)
trackView.clearFilter trackView.close trackView.getTrackViewName trackView.numTrackViews trackView.open trackView.pickTrackDlg trackView.setFilter trackView.zoomSelected

See Also
Trackviews (p. 114)

258

Chapter 1

Whats New in 3ds max 4 MAXScript

units const StructDef

3D Studio MAX System Globals (p. 630)
units.CustomName units.CustomUnit units.CustomValue units.decodeValue units.DisplayType units.formatValue units.MetricType units.SystemScale units.SystemType units.USFrac units.USType ft_Dec_In SystemGlobal:CustomName SystemGlobal:CustomUnit SystemGlobal:CustomValue SystemGlobal:DisplayType SystemGlobal:MetricType SystemGlobal:SystemScale SystemGlobal:SystemType SystemGlobal:USFrac SystemGlobal:USType FL feet 660.0 Generic meters 1.0 inches frac_1_8

viewport const StructDef

Accessing Active Viewport Info, Type, and Transforms (p. 1581)
viewport.activeViewport viewport.GetCamera viewport.GetLayout viewport.GetTM viewport.GetType viewport.numViews viewport.resetAllViews viewport.SetCamera viewport.SetLayout viewport.SetTM viewport.SetType viewport.ZoomToBounds SystemGlobal:activeViewport 4

SystemGlobal:numViews

See Also
3D Studio MAX System Globals (p. 630) Zoom to Bounds (p. 184)

WAVsound const StructDef

Sound : Helper (p. 989)
WAVsound.end WAVsound.filename WAVsound.isPlaying WAVsound.mute WAVsound.scrub WAVsound.start 1.34218e+007f SystemGlobal:end SystemGlobal:filename SystemGlobal:isPlaying SystemGlobal:mute SystemGlobal:start -1.34218e+007f false true -

xrefPaths const StructDef

259

xrefPaths const StructDef

3ds max System Directories (p. 1625)
xrefPaths.add

Appends the specified path to the list of XRef search paths.

xrefPaths.count

Returns the number of XRef search paths defined.

xrefPaths.delete

Returns the indexed XRef search path as a string. The index is 1-based.
xrefPaths.get

Deletes the indexed XRef search path. The index is 1-based.

xrefs const Structdef

XRefScene Values (p. 1038)
xrefs.addNewXRefFile xrefs.addNewXRefObject xrefs.attemptUnresolvedXRefs xrefs.deleteAllXRefs xrefs.findUnresolvedXRefs xrefs.getXRefFile xrefs.getXRefFileCount xrefs.updateChangedXRefs

version 4 New Classes

New Classes in version 4
Note: The name of the atmosphere in releases prior to 3ds max 4, known as the Combustion effect is now called Fire Effect. Additive Euler XYZ - superclass: RotationController (p. 262) Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) AutomaticAdaptiveExposureControl - superclass: MAXObject (p. 267) Automatic Exposure Control - superclass: MAXObject (p. 268) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) BlendRenderElement - superclass: MAXObject (p. 271) clrShadowRenderElement - superclass: MAXObject (p. 272)

260

Chapter 1

Whats New in 3ds max 4 MAXScript

Colored Shadow - superclass: MAXObject (p. 273) Combustion.coordinates - superclass: MAXObject (p. 274) Cone Angle - superclass: helper (p. 276) ConeAngleManip - superclass: helper (p. 277) ConvertToPatch - superclass: modifier (p. 278) DeletePatch - superclass: modifier (p. 279) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) Drag - superclass: SpacewarpObject (p. 149) emissionRenderElement - superclass: MAXObject (p. 285) FloatList - superclass: FloatController (p. 286) FloatReactor - superclass: FloatController (p. 287) Hose - superclass: GeometryClass (p. 146) HSDS Modifier - superclass: modifier (p. 290) HSDSObject - superclass: modifier (p. 292) imageMotionBlur - superclass: renderEffect (p. 294) Link - superclass: Matrix3Controller (p. 294) Link.link params - superclass: MAXObject (p. 295) Link Constraint - superclass: Matrix3Controller (p. 295) Link Constraint.link_params - superclass: MAXObject (p. 296) LinkedXForm - superclass: modifier (p. 297) LookAt Constraint - superclass: RotationController (p. 297) Mesher - superclass: GeometryClass (p. 298) meshsmooth - superclass: modifier (p. 298) Motion Blur - superclass: renderEffect (p. 302) MultiRes - superclass: modifier (p. 153) Normalize Spl - superclass: modifier (p. 305) Orientation Constraint - superclass: RotationController (p. 306) particleMesher - superclass: GeometryClass (p. 306) Patch Select - superclass: modifier (p. 307) Path Constraint - superclass: PositionController (p. 307) PDynaflector - superclass: SpacewarpObject (p. 309) Plane Angle - superclass: helper (p. 310) PlaneAngleManip - superclass: helper (p. 311)

New Classes in version 4

261

Point3List interfaces: (p. 479) Point3Reactor - superclass: Point3Controller (p. 312) Point3Spring - superclass: Point3Controller (p. 313) Point Cache - superclass: modifier (p. 314) Point CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315) PointCache - superclass: modifier (p. 316) PointCacheWSM - superclass: SpacewarpModifier (p. 317) PointHelperObj - superclass: helper (p. 318) Poly Select - superclass: modifier (p. 319) Position Constraint - superclass: PositionController (p. 320) PositionList superclass_PositionController (p. 321) PositionReactor - superclass: PositionController (p. 321) PositionSpring - superclass: PositionController (p. 321) PSpawnflector superclass_SpacewarpObject (p. 322) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement superclass_MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) RingWave - superclass: GeometryClass (p. 328) RotationList - superclass: RotationController (p. 328) RotationReactor - superclass: RotationController (p. 328) ScaleList - superclass: ScaleController (p. 328) ScaleReactor - superclass: ScaleController (p. 329) SDynaflector - superclass: SpacewarpObject (p. 329) section - superclass: shape (p. 330) Self_Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) sliderManipulator - superclass: helper (p. 333) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335) SpringPoint3Controller - superclass: Point3Controller (p. 336) SpringPositionController - superclass: PositionController (p. 337) SSpawnflector - superclass: SpacewarpObject (p. 338) transform_script - superclass: Matrix3Controller (p. 339)

262

Chapter 1

Whats New in 3ds max 4 MAXScript

Turn_to_Mesh - superclass: modifier (p. 340) Turn_to_Patch - superclass: modifier (p. 342) Turn_to_Poly - superclass: modifier (p. 343) UDynaDeflector - superclass: SpacewarpObject (p. 345) USpawnDeflector - superclass: SpacewarpObject (p. 346) UVWUnwrap - superclass: modifier (p. 347) Vortex - superclass: SpacewarpObject (p. 156) Z_Depth - superclass: MAXObject (p. 350) ZRenderElement - superclass: MAXObject (p. 351)

New Classes in version 4 Pages

Additive_Euler_XYZ - superclass: RotationController
Additive_Euler_XYZ - superclass: RotationController; super-superclass:MAXWrapper 3:3 - classID: #(8226, 0) <Additive_Euler_XYZ>.additive_x_rotation Float default: 0.0 -animatable; float; Controller Scaling: (1 : 57.2958) <Additive_Euler_XYZ>.additive_y_rotation Float default: 0.0 -animatable; float; Controller Scaling: (1 : 57.2958) <Additive_Euler_XYZ>.additive_z_rotation Float default: 0.0 -animatable; float; Controller Scaling: (1 : 57.2958)

Alpha - superclass: MAXObject

Alpha - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(13, 0) Constructor:
Alpha ...

Properties:
<Alpha>.enabled <Alpha>.filterOn <Alpha>.elementName BooleanClass BooleanClass String default: true default: true default: Alpha --boolean boolean; FilteringOn -string

Shows whether the element is enabled. Shows whether the active antialiasing filter is enabled for the element. Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<Alpha>.bitmap UndefinedClass default: undefined -bitmap

alphaRenderElement - superclass: MAXObject

263

See Also
alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

alphaRenderElement - superclass: MAXObject

alphaRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(13, 0) Constructor:
alphaRenderElement ...

Properties:
<alphaRenderElement>.enabled <alphaRenderElement>.filterOn boolean; FilteringOn <alphaRenderElement>.elementName string BooleanClass BooleanClass default: true default: true --boolean

Shows whether the element is enabled.

Shows whether the active antialiasing filter is enabled for the element.
String default: Alpha --

Shows the name of the currently selected element. You can type in a custom name for the element.

264

Chapter 1

Whats New in 3ds max 4 MAXScript

This control is unavailable when multiple elements are selected.

<alphaRenderElement>.bitmap bitmap UndefinedClass default: undefined --

See Also
Alpha - superclass: MAXObject (p. 262) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored_Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self_Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

Atmosphere - superclass: MAXObject

Atmosphere - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(9, 0) Constructor:
Atmosphere ...

Properties:
<Atmosphere>.enabled <Atmosphere>.filterOn FilteringOn <Atmosphere>.elementName BooleanClass BooleanClass default: true default: true --boolean boolean;

Shows whether the element is enabled.

Shows whether the active antialiasing filter is enabled for the element.
String default: Atmosphere -string

atmosphereRenderElement - superclass: MAXObject

265

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<Atmosphere>.bitmap UndefinedClass default: undefined -bitmap

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

atmosphereRenderElement - superclass: MAXObject

atmosphereRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(9, 0) Constructor:
Atmosphere ...

Properties:
<atmosphereRenderElement>.enabled boolean BooleanClass default: true --

Shows whether the element is enabled.

<atmosphereRenderElement>.filterOn boolean; FilteringOn BooleanClass default: true --

Shows whether the active antialiasing filter is enabled for the element.

266

Chapter 1

Whats New in 3ds max 4 MAXScript

<atmosphereRenderElement>.elementName Atmosphere -- string

String

default:

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<atmosphereRenderElement>.bitmap - bitmap UndefinedClass default: undefined -

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

AutomaticAdaptiveExposureControl - superclass: MAXObject

267

AutomaticAdaptiveExposureControl - superclass: MAXObject

AutomaticAdaptiveExposureControl - superclass: MAXObject; super-superclass:Value - 5:0 - classID: #(2020371114, 1150503387) Constructor:
AutomaticAdaptiveExposureControl ...

Properties:
<AutomaticAdaptiveExposureControl>.physicalScale -- animatable; float; Physical_Scale Float default: 1500.0

Sets a physical scale for exposure control to use. This is a light intensity value, in candelas. It can range from 0.0 to 200,000.0. The physical scale is factored into light multiplier values, and self-illumination, reflection, and refraction maps. Default=1500.0. Decreasing the physical scale dims the scene. Increasing the physical scale increases brightness, up to a scale value at which the scene grows no brighter. This parameter is animatable.
<AutomaticAdaptiveExposureControl>.chromaticAdaptation BooleanClass false -- boolean; Chromatic_Adaptation default:

When the check box is turned on, chromatic adaptation converts all colors so the color displayed in the color swatch appears as white. Default=off. Clicking the color swatch displays a Color Selector so you can choose the color to adapt to. Chromatic adaptation is a form of color correction. You can use this control to simulate the eye adjusting to lighting. For example, when the light in a room has a yellow cast, our mind adjusts it so that objects we know to be white, such as printed pages, appear as white.
<AutomaticAdaptiveExposureControl>.colorDiscrimination BooleanClass false -- boolean; Color_Discrimination default:

When on, renders dimly lit colors as if the light were too dim for the eye to distinguish between colors. When on, renders even dimly lit colors. Default=off. Color differentiation simulates the eyes response to dim lighting. In dim lighting, the eye does not perceive colors and sees tones of gray instead. The effect of this setting is not apparent except at very low light levels: below 5.62 candelas. This occurs only if the Physical Scale is less than 5.62, if a lights Multiplier is less than 0.00017, or both. When Physical Scale is less than 0.00562, the scene is completely gray.
<AutomaticAdaptiveExposureControl>.whiteColor Color default: (color 255 255 255) -- animatable; RGB color; Color_Discrimination; Controller Scaling: ([1,1,1] : (color 255 255 255))

268

Chapter 1

Whats New in 3ds max 4 MAXScript

<AutomaticAdaptiveExposureControl>.exposureValue -- animatable; float; Exposure_Value

Float

default:

0.0

Adjusts the overall brightness of the rendering. Can range from -5.0 to 5.0. Negative values make the image darker, and positive values make it brighter. Default=0.0. The exposure value is comparable to the exposure compensation setting in cameras with automatic exposure. This parameter is animatable.

Automatic_Exposure_Control - superclass: MAXObject

Automatic_Exposure_Control - superclass: MAXObject; super-superclass:Value - 5:0 - classID: #(2020371114, 1150503387) Constructor:
Automatic_Exposure_Control ...

Properties:
<Automatic_Exposure_Control>.physicalScale -- animatable; float; Physical_Scale Float default: 1500.0

Sets a physical scale for exposure control to use. This is a light intensity value, in candelas. It can range from 0.0 to 200,000.0. The physical scale is factored into light multiplier values, and self-illumination, reflection, and refraction maps. Default=1500.0. Decreasing the physical scale dims the scene. Increasing the physical scale increases brightness, up to a scale value at which the scene grows no brighter. This parameter is animatable.
<Automatic_Exposure_Control>.chromaticAdaptation BooleanClass -- boolean; Chromatic_Adaptation default: false

When the check box is turned on, chromatic adaptation converts all colors so the color displayed in the color swatch appears as white. Default=off. Clicking the color swatch displays a Color Selector so you can choose the color to adapt to. Chromatic adaptation is a form of color correction. You can use this control to simulate the eye adjusting to lighting. For example, when the light in a room has a yellow cast, our mind adjusts it so that objects we know to be white, such as printed pages, appear as white.
<Automatic_Exposure_Control>.colorDiscrimination BooleanClass -- boolean; Color_Discrimination default: false

When on, renders dimly lit colors as if the light were too dim for the eye to distinguish between colors. When on, renders even dimly lit colors. Default=off. Color differentiation simulates the eyes response to dim lighting. In dim lighting, the eye does not perceive colors and sees tones of gray instead. The effect of this setting is not apparent except at very low light levels: below 5.62 candelas. This occurs only if the Physical Scale is less than 5.62, if a lights Multiplier is less

BackgroundRenderElement - superclass: MAXObject

269

than 0.00017, or both. When Physical Scale is less than 0.00562, the scene is completely gray.
<Automatic_Exposure_Control>.whiteColor Color default: (color 255 255 255) -animatable; RGB color; Color_Discrimination; Controller Scaling: ([1,1,1] : (color 255 255 255)) <Automatic_Exposure_Control>.exposureValue -- animatable; float; Exposure_Value Float default: 0.0

Adjusts the overall brightness of the rendering. Can range from -5.0 to 5.0. Negative values make the image darker, and positive values make it brighter. Default=0.0. The exposure value is comparable to the exposure compensation setting in cameras with automatic exposure. This parameter is animatable.

BackgroundRenderElement - superclass: MAXObject

BackgroundRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(15, 0) Constructor:
BackgroundRenderElement ...

Properties:
<BackgroundRenderElement>.enabled boolean BooleanClass default: true --

Shows whether the element is enabled.

<BackgroundRenderElement>.filterOn boolean; FilteringOn <BackgroundRenderElement>.elementName Background -- string BooleanClass default: true --

Shows whether the active antialiasing filter is enabled for the element.
String default:

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<BackgroundRenderElement>.bitmap bitmap UndefinedClass default: undefined --

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) bgndRenderElement - superclass: MAXObject (p. 270)

270

Chapter 1

Whats New in 3ds max 4 MAXScript

clrShadowRenderElement - superclass: MAXObject (p. 272) Colored Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

bgndRenderElement - superclass: MAXObject

bgndRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(15, 0) Constructor:
bgndRenderElement ...

Properties:
<bgndRenderElement>.enabled <bgndRenderElement>.filterOn FilteringOn <bgndRenderElement>.elementName string BooleanClass BooleanClass default: true default: true --boolean boolean;

Shows whether the element is enabled.

Shows whether the active antialiasing filter is enabled for the element.
String default: Background --

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<bgndRenderElement>.bitmap bitmap UndefinedClass default: undefined --

See Also
bitmapTex interfaces: (p. 434) Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264)

BlendRenderElement - superclass: MAXObject

271

atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

BlendRenderElement - superclass: MAXObject

BlendRenderElement - superclass: MAXObject; super-superclass:Value - 12:0 - classID: #(11, 0) Constructor:
BlendRenderElement

Properties:
<BlendRenderElement>.enabled <BlendRenderElement>.filterOn FilteringOn <BlendRenderElement>.elementName BooleanClass BooleanClass default: true default: true --boolean boolean;

Shows whether the element is enabled.

Shows whether the active antialiasing filter is enabled for the element.
String default: Blend -string

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<BlendRenderElement>.bitmap <BlendRenderElement>.atmosphereOn <BlendRenderElement>.shadowOn ShadowsOn UndefinedClass BooleanClass BooleanClass default: undefined default: true default: true ---bitmap

boolean boolean;

When on, include atmospheric effects. Default=on.

When on, include shadows. Default=on.

272

Chapter 1

Whats New in 3ds max 4 MAXScript

<BlendRenderElement>.diffuseOn Diffuse_On <BlendRenderElement>.ambientOn Ambient_On <BlendRenderElement>.specularOn Specular_On <BlendRenderElement>.emissionOn Self_Illumination <BlendRenderElement>.reflectionOn Reflection_On <BlendRenderElement>.refractionOn Refraction_On

BooleanClass

default: true

--

boolean;

When on, include the diffuse color component. Default=on.

BooleanClass default: true -boolean;

When on, include the ambient color component. Default=on.

BooleanClass default: true -boolean;

When on, include the specular color component. Default=on.

BooleanClass default: true -boolean;

When on, include self-illumination. Default=on.

BooleanClass default: true -boolean;

When on, include reflections. Default=on.

BooleanClass default: true -boolean;

When on, include refractions. Default=on.

clrShadowRenderElement - superclass: MAXObject

clrShadowRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(14, 0) Constructor:
clrShadowRenderElement ...

Properties:
<clrShadowRenderElement>.enabled boolean BooleanClass default: true --

Shows whether the element is enabled.

<clrShadowRenderElement>.filterOn boolean; FilteringOn <clrShadowRenderElement>.elementName Shadow -- string BooleanClass default: true --

Shows whether the active antialiasing filter is enabled for the element.
String default: Colored

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<clrShadowRenderElement>.bitmap bitmap UndefinedClass default: undefined --

Colored_Shadow - superclass: MAXObject

273

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) Colored Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

Colored_Shadow - superclass: MAXObject

Colored_Shadow - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(14, 0) Constructor:
Colored_Shadow ...

Properties:
<Colored_Shadow>.enabled <Colored_Shadow>.filterOn FilteringOn <Colored_Shadow>.elementName string BooleanClass BooleanClass default: true default: true --boolean boolean;

Shows whether the element is enabled.

Shows whether the active antialiasing filter is enabled for the element.
String default: Colored Shadow --

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<Colored_Shadow>.bitmap UndefinedClass default: undefined -bitmap

274

Chapter 1

Whats New in 3ds max 4 MAXScript

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

Combustion.coordinates - superclass: MAXObject

Combustion.coordinates - superclass: MAXObject; super-superclass:Value - 16:0 - classID: #(256, 0) Constructor:
Combustion.coordinates ...

Properties:
<Combustion.coordinates>.blur float Float default: 1.0 -animatable;

Affects the sharpness or blurriness of the map based on its distance from the view. The farther away the map is, the greater the blurring. The Blur value blurs maps in world space. Blur is primarily used to avoid aliasing.
<Combustion.coordinates>.mapping <Combustion.coordinates>.mapChannel <Combustion.coordinates>.mappingType <Combustion.coordinates>.phase Float Integer Integer Integer default: 0 default: 1 default: 0 -animatable; float

default: 0.0

Combustion.coordinates - superclass: MAXObject

275

<Combustion.coordinates>.U_Offset float

Float

default: 0.0

--

animatable;

Changes the position of the map in UV coordinates. The map moves in relation to its size. For example, if you want to shift the map its full width to the left, and half its width downward from its original position, you enter -1 in the U Offset field and 0.5 in the V offset field.
<Combustion.coordinates>.V_Offset float Float default: 0.0 -animatable;

Changes the position of the map in UV coordinates. The map moves in relation to its size. For example, if you want to shift the map its full width to the left, and half its width downward from its original position, you enter -1 in the U Offset field and 0.5 in the V offset field.
<Combustion.coordinates>.U_Tiling float <Combustion.coordinates>.V_Tiling float Float default: 1.0 -animatable;

Determines the number of times the map is tiled (repeated) along each axis.
Float default: 1.0 -animatable;

Determines the number of times the map is tiled (repeated) along each axis.
<Combustion.coordinates>.U_Angle Float angle; Controller Scaling: (1 : 57.2958) <Combustion.coordinates>.V_Angle Float angle; Controller Scaling: (1 : 57.2958) <Combustion.coordinates>.W_Angle Float angle; Controller Scaling: (1 : 57.2958) <Combustion.coordinates>.Noise_Amount float <Combustion.coordinates>.Noise_Size float <Combustion.coordinates>.Noise_Levels integer <Combustion.coordinates>.Blur_Offset float Float default: 0.0 -animatable;

Rotates the map about the U, V, or W axis (in degrees).

default: 0.0 -animatable;

Rotates the map about the U, V, or W axis (in degrees).

default: 0.0 -animatable;

Rotates the map about the U, V, or W axis (in degrees).

default: 1.0 -animatable;

Float

default: 1.0

--

animatable;

Integer

default: 1

--

animatable;

Float

default: 0.0

--

animatable;

Affects the sharpness or blurriness of the map without regard to its distance from the view. Blur Offset blurs the image itself in object space. Use this option when you want to soften or defocus the details in a map to achieve the effect of a blurred image.

See Also
Combustion (p. 38) Material Common Properties, Operators, and Methods (p. 1203)

276

Chapter 1

Whats New in 3ds max 4 MAXScript

Cone_Angle - superclass: helper

Cone_Angle - superclass: helper; super-superclass:node - 6:0 - classID: #(629233518, 624568848) Constructor:
Cone_Angle ...

Properties:
<Cone_Angle>.Origin Point3 <Cone_Angle>.Direction Point3 <Cone_Angle>.Angle Float Controller Scaling: (1 : 57.2958) default: [0,0,0] default: [0,0,-1] default: 15.0 --- point3 -- point3 animatable; angle;

The initial angle of the manipulator.

<Cone_Angle>.Distance Float default: 0.0 -float

The length of the manipulator, in 3ds max units. Default=the distance of mouse drag when the manipulator was created.
<Cone_Angle>.UseSquare Use_Square <Cone_Angle>.Aspect BooleanClass default: false -boolean;

When on, the base of the cone is square or rectangular, rather than circular. Default=off.
Float default: 1.0 -float

When Use Square is on, adjusts the aspect ratio of the rectangular cone base. Default=1.0.

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

ConeAngleManip - superclass: helper

277

ConeAngleManip - superclass: helper

ConeAngleManip - superclass: helper; super-superclass:node - 6:0 - classID: #(629233518, 624568848) Constructor:
ConeAngleManip ...

Properties:
<ConeAngleManip>.Origin Point3 <ConeAngleManip>.Direction Point3 <ConeAngleManip>.Angle Float Controller Scaling: (1 : 57.2958) default: [0,0,0] -- point3 default: [0,0,-1] -- point3 default: 15.0 -- animatable; angle;

The initial angle of the manipulator.

<ConeAngleManip>.Distance Float default: 0.0 -float

The length of the manipulator, in 3ds max units. Default=the distance of mouse drag when the manipulator was created.
<ConeAngleManip>.UseSquare Use_Square <ConeAngleManip>.Aspect BooleanClass default: false -boolean;

When on, the base of the cone is square or rectangular, rather than circular. Default=off.
Float default: 1.0 -float

When Use Square is on, adjusts the aspect ratio of the rectangular cone base. Default=1.0.

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

278

Chapter 1

Whats New in 3ds max 4 MAXScript

ConvertToPatch - superclass: modifier

ConvertToPatch - superclass: modifier; super-superclass:MAXWrapper - 4:0 - classID: #(1011577041, 590161861) The Turn To Patch modifier lets you apply object conversions in the modifier stack. Using the Turn To Patch modifier, you can fine-tune the conversion process such as turning quads into quad patches. Note: Converting from one object type to another causes a complete caching in the modifier stack. When you have large objects in your scene, this can take up a lot of space. For example, an object that starts as a mesh, converts to a patch, and then back to a mesh takes 3 times as much space as a mesh which just has ordinary modifiers like Bend or UVW Map applied. Note: Converting from one object type to another causes a complete caching in the modifier stack. When you have large objects in your scene, this can take up a lot of space. For example, an object that starts as a mesh, converts to a patch, and then back to a mesh takes 3 times as much space as a mesh which just has ordinary modifiers like Bend or UVW Map applied. Constructor:
ConvertToPatch ...

Properties:
<ConvertToPatch>.quadsToQuads BooleanClass animatable; boolean; Quads_to_Quad_Patches <ConvertToPatch>.selectionConversion Selection_Conversion <ConvertToPatch>.useSoftSelection Use_Soft_Selection Integer Integer default: true --

Turns quad faces in meshes or polymeshes into quad patches.

default: 0 default: 1 --integer; integer;

When these are on, 3ds max applies a spline curve deformation to unselected vertices surrounding the transformed selected sub-object. This provides a magnet-like effect, with a sphere of influence around the transformation. Use this when you want to preserve the soft selection from beneath. For example, if Use Soft Selection is on when you select vertices on an editable mesh, and you apply Turn To Patch with Include Soft Selection on, then the same soft selection will apply to the patch vertices.
<ConvertToPatch>.selectionLevel Selection_Level Integer default: 0 -integer;

These options set the sub-object selection level for passing up the rest of the stack. From Pipeline: Uses the equivalent of whatever the input object uses. (Patch level becomes face level, and so on.). For example, if you create a box, convert it to an editable mesh in face mode and apply a Turn To Patch modifier to it, 3ds max passes a sub-object selection in patch mode up the stack. The Turn To Patch modifier takes the sub-object face selection into account and selects the patches that derive from the face selection.

DeletePatch - superclass: modifier

279

Object: Uses object as the selection level for passing up the rest of the stack. Edge: Uses edge as the sub-object selection level for passing up the rest of the stack. Vertex: Uses vertex as the sub-object selection level for passing up the rest of the stack. Patch: Uses patch as the sub-object selection level for passing up the rest of the stack.

DeletePatch - superclass: modifier

DeletePatch - superclass: modifier; super-superclass:MAXWrapper - 0:0 - classID: #(2134166570, 0) Apply the Delete Patch modifier to delete the geometry specified at that sub-object level.

Diffuse - superclass: MAXObject

Diffuse - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(4, 0) Constructor:
Diffuse ...

Properties:
<Diffuse>.enabled <Diffuse>.filterOn FilteringOn <Diffuse>.elementName BooleanClass BooleanClass default: true default: true --boolean boolean;

Shows whether the element is enabled.

Shows whether the active antialiasing filter is enabled for the element.
String default: Diffuse -string

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<Diffuse>.bitmap UndefinedClass default: undefined -bitmap

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored Shadow - superclass: MAXObject (p. 273) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285)

280

Chapter 1

Whats New in 3ds max 4 MAXScript

Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

diffuseRenderElement - superclass: MAXObject

diffuseRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(4, 0) Constructor:
diffuseRenderElement ...

Properties:
<diffuseRenderElement>.enabled boolean BooleanClass default: true --

Shows whether the element is enabled.

<diffuseRenderElement>.filterOn boolean; FilteringOn <diffuseRenderElement>.elementName string BooleanClass default: true --

Shows whether the active antialiasing filter is enabled for the element.
String default: Diffuse --

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<diffuseRenderElement>.bitmap bitmap UndefinedClass default: undefined --

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored Shadow - superclass: MAXObject (p. 273)

Drag - superclass: SpacewarpObject

281

Diffuse - superclass: MAXObject (p. 279) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

Drag - superclass: SpacewarpObject

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

Properties:
<Drag>.time on <Drag>.time off Time_Off <Drag>.symmetry Damping_Symmetry Integer Integer default: 0 -integer; Time_On -animatable; integer;

The frame numbers at which the space warp becomes active and becomes inactive.
default: 16000

The frame numbers at which the space warp becomes active and becomes inactive.
Integer default: 0 -radio button number;

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 X_Damping; Controller Scaling: (1 : 100.0) -animatable; percentage;

Specifies the percentage of particle motion along the local Drag space warp axis thats affected by the damping.
<Drag>.rangex Float default: 100.0 -animatable; float; X_Range

282

Chapter 1

Whats New in 3ds max 4 MAXScript

Sets the thickness of the range plane, or the infinite plane perpendicular to the specified axis. Takes effect only when Unlimited Range is turned off.
<Drag>.falloffx X_Falloff Float default: 1000.0 -animatable; float;

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 Y_Damping; Controller Scaling: (1 : 100.0) -animatable; percentage;

Specifies the percentage of particle motion along the local Drag space warp axis thats affected by the damping.
<Drag>.rangey Float default: 100.0 -animatable; float; Y_Range

Sets the thickness of the range plane, or the infinite plane perpendicular to the specified axis. Takes effect only when Unlimited Range is turned off.
<Drag>.falloffy Y_Falloff Float default: 1000.0 -animatable; float;

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 Z_Damping; Controller Scaling: (1 : 100.0) -animatable; percentage;

Specifies the percentage of particle motion along the local Drag space warp axis thats 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 Z_Falloff Float default: 1000.0 -animatable; float;

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 Radial_Damping; Controller Scaling: (1 : 100.0) -animatable; percentage;

Radial specifies the percentage of particle motion toward or away from the center of the Drag icon thats affected by the damping. Tangential specifies the percentage of particle motion across the body of the Drag icon thats affected by the damping.

Drag - superclass: SpacewarpObject

283

<Drag>.ranger Radial_Range

Float

default: 100.0

--

animatable; float;

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 Radial_Falloff Float default: 1000.0 -animatable; float;

Specifies the distance beyond the Radial/Tangential Range within which Linear Damping is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of the Falloff, and has no effect beyond that. While Falloff is effected only beyond the Range, it is measured from the center of the icon, and always has a minimum value equal to the Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampinggc Float default: 0.0 -Tangential_Damping; Controller Scaling: (1 : 100.0) animatable; percentage;

Radial specifies the percentage of particle motion toward or away from the center of the Drag icon thats affected by the damping. Tangential specifies the percentage of particle motion across the body of the Drag icon thats affected by the damping.
<Drag>.rangegc Tangential_Range Float default: 100.0 -animatable; float;

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 Tangential_Falloff Float default: 1000.0 -animatable; float;

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 Radial_Damping; Controller Scaling: (1 : 100.0) -animatable; percentage;

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 icons long axis (Axial) thats affected by the damping, on a per-frame basis.
<Drag>.rangerc Radial_Range Float default: 100.0 -animatable; float;

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 Radial_Falloff Float default: 1000.0 -animatable; float;

Specifies the distance beyond the Radial/Tangential/Axial Range within which Linear Damping is applied. Damping is strongest at the Range distance, decreases linearly out to the limit of the Falloff, and has no effect beyond that. While Falloff is effected only

284

Chapter 1

Whats New in 3ds max 4 MAXScript

beyond the Range, it is measured from the center of the icon, and always has a minimum value equal to the Range value. Takes effect only when Unlimited Range is turned off.
<Drag>.dampingc Float default: 0.0 -Tangential_Damping; Controller Scaling: (1 : 100.0) animatable; percentage;

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 icons long axis (Axial) thats affected by the damping, on a per-frame basis.
<Drag>.rangec Tangential_Range Float default: 100.0 -animatable; float;

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 Tangential_Falloff Float default: 1000.0 -animatable; float;

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 Axial_Damping; Controller Scaling: (1 : 100.0) -animatable; percentage;

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 icons long axis (Axial) thats affected by the damping, on a per-frame basis.
<Drag>.rangeax Axial_Range Float default: 100.0 -animatable; float;

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 Axial_Falloff Float default: 1000.0 -animatable; float;

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 <Drag>.iconsize BooleanClass Float default: true default: 10.0 --boolean; Unlimited_Range float; Icon_Size

Specifies the size of the icon.

emissionRenderElement - superclass: MAXObject

285

Example:
Drag time_on:0 time_off:10 symmetry:0 dampingx:5 rangex:100 falloffx:1000 dampingy:0 rangey:100 falloffy:1000 dampingz:0 rangez:100 falloffz:1000 dampingr:5 ranger:100 falloffr:1000 dampinggc:0 rangegc:100 falloffgc:1000 dampingrc:5 rangerc:100 falloffrc:1000 dampingc:0 rangec:100 falloffc:1000 dampingax:0 rangeax:100 falloffax:1000 rangeless:on pos:[-16.2008,-105.647,0] isSelected:on iconSize:13.7761

See Also
Modifier and SpacewarpModifier Types (p. 1100)

emissionRenderElement - superclass: MAXObject

emissionRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(5, 0) Constructor:
emissionRenderElement ...

Properties:
<emissionRenderElement>.enabled boolean BooleanClass default: true --

Shows whether the element is enabled.

<emissionRenderElement>.filterOn boolean; FilteringOn <emissionRenderElement>.elementName Illumination -- string BooleanClass default: true --

Shows whether the active antialiasing filter is enabled for the element.
String default: Self-

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<emissionRenderElement>.bitmap bitmap UndefinedClass default: undefined --

See Also
Self Illumination - superclass: MAXObject (p. 331) Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272)

286

Chapter 1

Whats New in 3ds max 4 MAXScript

Colored Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

FloatList - superclass: FloatController

FloatList - superclass: FloatController; super-superclass:MAXWrapper - 1:1 - classID: #(1263210496, 0) The List controller combines multiple controllers into a single effect. It is a compound controller with tools for managing the order in which its internal controllers are calculated. Controllers are evaluated in a top to bottom order; the controller at the top of the list is evaluated first. When you assign a List controller to a parameter, the current controller is moved one level below the List controller; it becomes the first controller in the list. A second parameter is added below the List controller and is named Available. This is an empty placeholder for the next controller you add to the list. Constructor:
...

Properties:
<FloatList>.available Float default: 0.0 Controller Scaling: (1 : 0.0); WeirdScaled (0.0) -animatable; float;

See Also
FloatList interfaces: (p. 450)

FloatReactor - superclass: FloatController

287

FloatReactor - superclass: FloatController

FloatReactor - superclass: FloatController; super-superclass:MAXWrapper - 0:0 classID: #(1904049439, 306976571)

See Also
FloatReactor interfaces: (p. 452)

Hose - superclass: GeometryClass

Hose - superclass: GeometryClass; super-superclass:node - 27:0 - classID: #(1777953373, 593249034) The Hose object is a flexible object that you can connect between two objects, whereupon it reacts to their movement. Its 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 <Hose>.Generate_Mapping_Coordinates <Hose>.Hose_Height float Integer Integer Float default: 1 default: 0 default: 1.0 ---integer integer animatable;

Sets up required coordinates for applying mapped materials to the hose. Default=off.

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 Integer default: 45 -animatable;

The total number of segments in the hoses length. Increase this setting for a smooth profile when the hose is curved. Default=16.
<Hose>.Smooth_Spring Integer default: 0 -integer

Choose one of the following smoothing options: All: The entire hose is smoothed. Sides: Smoothing is applied along the length of the hose but not around its circumference. None: No smoothing is applied. Segments: Smoothing is applied only on the inner section of the hose.
<Hose>.Renderable_Hose Integer default: 1 -integer

When on, the hose is rendered using the specified settings. When off, the hose is not rendered. Default=on.

288

Chapter 1

Whats New in 3ds max 4 MAXScript

<Hose>.Hose_Cross_Section_Type

Integer

default: 0

--

integer

Sets a circular cross-section. Lets you specify different settings for width and depth. Similar to Rectangular Hose, but rounds one side for a D-shaped cross-section.
<Hose>.Round_Hose_Diameter float <Hose>.Round_Hose_Sides integer Float default: 0.2 -animatable;

The maximum width of the hose at the ends.

Integer default: 8 -animatable;

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 Float default: 0.2 -animatable;

The width of the hose.

<Hose>.Rectangular_Hose_Depth float Float default: 0.2 -animatable;

The height of the hose.

<Hose>.Rectangular_Hose_Fillet_Size float Float default: 0.0 -animatable;

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 Integer default: 0 -animatable;

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 angle; Controller Scaling: (1 : 57.2958) <Hose>.D_Section_Hose_Width float Float default: 0.0 -animatable;

The orientation of the hose along its long axis. Default=0.

default: 0.2 -animatable;

The width of the hose.

<Hose>.D_Section_Hose_Depth float Float default: 0.2 -animatable;

The height of the hose.

<Hose>.D_Section_Hose_Fillet_Size float Float default: 0.0 -animatable;

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 Integer default: 0 -animatable;

The number of segments across each filleted corner. A Fillet Segs setting of 1 cuts the corner straight across; use higher settings for rounded corners. Default=0.

Hose - superclass: GeometryClass

289

<Hose>.D_Section_Hose_Round_Segs integer

Integer

default: 8

--

animatable;

The number of segments on the rounded side. Increase for a smoother profile. Default=4.
<Hose>.D_Section_Hose_Section_Rotation Float angle; Controller Scaling: (1 : 57.2958) <Hose>.Flex_Section_Enabled Integer default: 0.0 -animatable;

The orientation of the hose along its long axis. Default=0.

default: 1 -integer

When on, lets you set the following four parameters for the central, flexible section of the hose. When off, the hoses diameter is uniform throughout its length.
<Hose>.Flex_Section_Start Float percentage; Controller Scaling: (1 : 100.0) default: 10.0 -animatable;

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 percentage; Controller Scaling: (1 : 100.0) default: 90.0 -animatable;

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 Integer default: 5 -animatable;

The number of corrugations in the flex section. The number of visible cycles is limited by the number of segments; if Segments isnt 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 percentage; Controller Scaling: (1 : 100.0) default: -20.0 -animatable;

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 Float default: 100.0 -animatable;

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 Float default: 100.0 -animatable;

Determines the arc of the hose near the Bottom object. Lower the tension to decrease the arc, and raise the tension to increase the arc. Default=100.

290

Chapter 1

Whats New in 3ds max 4 MAXScript

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

HSDS_Modifier - superclass: modifier

HSDS_Modifier - superclass: modifier; super-superclass:MAXWrapper - 12:0 - classID: #(341062, 28997) Constructor:
HSDS_Modifier ...

Properties:
<HSDS_Modifier>.levelOfDetail Integer default: 0 -integer; LOD

Shows the current level of the subdivision hierarchy. Automatically increments when you subdivide a sub-object selection. To edit at a different level of detail, change the setting to the desired level.
<HSDS_Modifier>.matId Material_Id Integer default: 1 -integer;

Displays the material ID assigned to the current selection. Available only in Polygon and Element sub-object modes. If multiple sub-objects are selected and they dont share an ID, this field is blank.
<HSDS_Modifier>.shadedLattice Shaded_Lattice BooleanClass default: false -boolean;

Displays only polygons at the current level of detail, with highlights, but without smoothing. Use this option to speed up the display when working with complex objects. Default=off.
<HSDS_Modifier>.ignoreBackface Ignore_Backface BooleanClass default: false -boolean;

When on, you can select only those sub-objects whose normals are visible in the viewport. When off (the default), selection includes all sub-objects, regardless of the direction of their normals.
<HSDS_Modifier>.useSoftSel Use_Soft_Selection BooleanClass default: false -boolean;

These controls let you set a gradual falloff of influence between selected and unselected vertices. See Soft Selection Rollout (Edit/Editable Mesh). Vertex Interpolation rollout Determines how selected vertices are treated during subdivision. Available only in Vertex sub-object mode.

HSDS_Modifier - superclass: modifier

291

For best results, use when moving control grid vertices at a level of detail lower than the highest in which the vertex resides.
<HSDS_Modifier>.useEdgeDist Use_Edge_Distance <HSDS_Modifier>.affectBackface Affect_Backface BooleanClass default: false -boolean;

BooleanClass

default: false

--

boolean;

When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the normals of faces to which theyre attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence. Turn off Affect Backfacing when you want to pull faces of a thin object, such as a thin box, but dont want to affect faces on the other side of the object. Note: Affect Backfacing is not available when editing splines. When using Edit/Editable Mesh, you can also use the keyboard shortcut CTRL+F to toggle Affect Backfacing (while the Keyboard Shortcut Override Toggle button is turned on).
<HSDS_Modifier>.edgeDistance Edge_Dist Integer default: 1 -integer;

This spinner setting limits the region affected by the number of edges between the selection and the affected vertices. The affected region is measured in terms of edgedistance space, along the surface, rather than real space.
<HSDS_Modifier>.falloff Float default: 20.0 -float

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry. Default=20. Note: At the Vertex sub-object level, the region specified by the Falloff setting is depicted graphically in the viewports as a vertex-color gradient from the Sub-selection color (normally red) to the Vertex Ticks color (normally blue). In addition, this gradient is updated in real time as you change the Falloff setting.
<HSDS_Modifier>.pinch Float default: 0.0 -float

Raises and lowers the top point of the curve along the vertical axis. Sets the relative pointedness of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis. Default=0.
<HSDS_Modifier>.bubble Float default: 0.0 -float

Expands and contracts the curve along the vertical axis. Sets the relative fullness of the region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble move the bottom of the curve below the surface, creating a valley around the base of the region. Default=0.

292

Chapter 1

Whats New in 3ds max 4 MAXScript

<HSDS_Modifier>.vertexType Vertex_Type]

Integer

default: 0

--

integer;

Standard/Conic/Cusp/Corner: Determines how closely mesh vertices follow the movement of control grid vertices. Standard provides the least amount of relative movement, while Cusp and Corner provide the most. Corner also more closely matches mesh edges to the control grid edges attached to the moved vertex. Default=Standard.

See Also
HSDS Modifier interfaces: (p. 453)

HSDSObject - superclass: modifier

HSDSObject - superclass: modifier; super-superclass:MAXWrapper - 12:0 - classID: #(341062, 28997) Constructor:
HSDSObject ...

Properties:
<HSDSObject>.levelOfDetail Integer default: 0 -integer; LOD

Shows the current level of the subdivision hierarchy. Automatically increments when you subdivide a sub-object selection. To edit at a different level of detail, change the setting to the desired level.
<HSDSObject>.matId Integer default: 1 -integer; Material_Id

Displays the material ID assigned to the current selection. Available only in Polygon and Element sub-object modes. If multiple sub-objects are selected and they dont share an ID, this field is blank.
<HSDSObject>.shadedLattice Shaded_Lattice BooleanClass default: false -boolean;

Displays only polygons at the current level of detail, with highlights, but without smoothing. Use this option to speed up the display when working with complex objects. Default=off.
<HSDSObject>.ignoreBackface Ignore_Backface BooleanClass default: false -boolean;

When on, you can select only those sub-objects whose normals are visible in the viewport. When off (the default), selection includes all sub-objects, regardless of the direction of their normals.
<HSDSObject>.useSoftSel Use_Soft_Selection BooleanClass default: false -boolean;

These controls let you set a gradual falloff of influence between selected and unselected vertices. See Soft Selection Rollout (Edit/Editable Mesh). Vertex Interpolation rollout

HSDSObject - superclass: modifier

293

Determines how selected vertices are treated during subdivision. Available only in Vertex sub-object mode. For best results, use when moving control grid vertices at a level of detail lower than the highest in which the vertex resides.
<HSDSObject>.useEdgeDist Use_Edge_Distance BooleanClass default: false -boolean;

This setting limits the region affected by the number of edges between the selection and the affected vertices. The affected region is measured in terms of edge-distance space, along the surface, rather than real space.
<HSDSObject>.affectBackface Affect_Backface BooleanClass default: false -boolean;

When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the normals of faces to which theyre attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence. Turn off Affect Backfacing when you want to pull faces of a thin object, such as a thin box, but dont want to affect faces on the other side of the object. Note: Affect Backfacing is not available when editing splines. When using Edit/Editable Mesh, you can also use the keyboard shortcut CTRL+F to toggle Affect Backfacing (while the Keyboard Shortcut Override Toggle button is turned on).
<HSDSObject>.edgeDistance Integer default: 1 -integer; Edge_Dist

This setting limits the region affected by the number of edges between the selection and the affected vertices. The affected region is measured in terms of edge-distance space, along the surface, rather than real space.
<HSDSObject>.falloff Float default: 20.0 -float

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry. Default=20. Note: At the Vertex sub-object level, the region specified by the Falloff setting is depicted graphically in the viewports as a vertex-color gradient from the Sub-selection color (normally red) to the Vertex Ticks color (normally blue). In addition, this gradient is updated in real time as you change the Falloff setting.
<HSDSObject>.pinch Float default: 0.0 -float

Raises and lowers the top point of the curve along the vertical axis. Sets the relative pointedness of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis. Default=0.
<HSDSObject>.bubble Float default: 0.0 -float

Expands and contracts the curve along the vertical axis. Sets the relative fullness of the region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for

294

Chapter 1

Whats New in 3ds max 4 MAXScript

Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble move the bottom of the curve below the surface, creating a valley around the base of the region. Default=0.
<HSDSObject>.vertexType Vertex_Type] Integer default: 0 -integer;

Standard/Conic/Cusp/Corner: Determines how closely mesh vertices follow the movement of control grid vertices. Standard provides the least amount of relative movement, while Cusp and Corner provide the most. Corner also more closely matches mesh edges to the control grid edges attached to the moved vertex. Default=Standard.

See Also
HSDSObject interfaces: (p. 453)

imageMotionBlur - superclass: renderEffect

imageMotionBlur - superclass: renderEffect; super-superclass:MAXWrapper - 2:0 - classID: #(141333203, 1612379012) Constructor:
imageMotionBlur ...

Properties:
<imageMotionBlur>.duration Float default: 1.0 -animatable; float

Specifies how long the virtual shutter is open. When this is set to 1.0, the virtual shutter is open for the entire duration between one frame and the next. The higher the value, the greater the motion Blur effect. Default=1.0.
<imageMotionBlur>.transparency BooleanClass default: true -boolean

When on, motion blur is applied to objects behind transparent objects. When off, objects behind transparent objects receive no motion blur. Turning off this toggle can improve rendering speed. Default=on.

See Also
imageMotionBlur interfaces: (p. 454)

Link - superclass: Matrix3Controller

Link - superclass: Matrix3Controller; super-superclass:MAXWrapper - 2:1 - classID: #(-2025855132, 1430354431) A Link constraint is used to animate an object linking from one target object to another. The Link constraint causes an object to inherit the position, rotation and scale of its target object.

Link.link_params - superclass: MAXObject

295

Constructor:
Link ...

Properties:
<Link>.key_mode <Link>.link_params Integer SubAnim default: 0 -- integer; Link_KeyMode default: SubAnim:Link_Params -- transform

See Also
Link.link_params - superclass: MAXObject (p. 295)

Link.link_params - superclass: MAXObject

Link.link_params - superclass: MAXObject; super-superclass:Value - 3:3 - classID: #(8197, 0) Constructor:
Link.link_params ...

Properties:
<Link.link_params>.position point3 <Link.link_params>.rotation quat <Link.link_params>.scale point3 Point3 Quat Point3 default: [0,0,0] -animatable; -animatable;

default: (quat 0 0 0 1) default: [1,1,1] --

animatable;

See Also
Link interfaces: (p. 455) Link - superclass: Matrix3Controller (p. 294)

Link_Constraint - superclass: Matrix3Controller

Link_Constraint - superclass: Matrix3Controller; super-superclass:MAXWrapper - 2:1 - classID: #(2025855132, -1430354431) A Link constraint is used to animate an object linking from one target object to another. The Link constraint causes an object to inherit the position, rotation and scale of its target object. Constructor:
Link_Constraint ...

Properties:
<Link_Constraint>.key_mode Integer default: 0 -integer; Link_KeyMode

Remarks: You can choose between 3 different Key Modes which will determine how keyframes are written on the linked objects as part of the link constraint. These options will provide the following:

296

Chapter 1

Whats New in 3ds max 4 MAXScript

No Key Mode: No keys are created any of the objects involved. Key Nodes: Sets keys for some of the objects. Child: Applied keys to the child object only. Parents: Applies keys to both parents and the child object. Key Entire Hierarchy: This applies keyframes to the chosen nodes and their entire hierarchies. Child: Keys the chosen object and the nodes in its hierarchy up to the world. Parents: Keys both parents and the child and all three hierarchies up to the world.
<Link_Constraint>.link_params transform SubAnim default: SubAnim:Link_Params --

See Also
Link Constraint.link params - superclass: MAXObject (p. 296) Link Constraint interfaces: (p. 455)

Link Constraint.link params - superclass: MAXObject

Link Constraint.link params - superclass: MAXObject; super-superclass:Value - 3:3 - classID: #(8197, 0) Constructor:
Link_Constraint.link_params ...

Properties:
<Link_Constraint.link_params>.position animatable; point3 <Link_Constraint.link_params>.rotation animatable; quat <Link_Constraint.link_params>.scale animatable; point3 Point3 Quat Point3 default: [0,0,0] ---

default: (quat 0 0 0 1) default: [1,1,1] --

See Also
Link_Constraint interfaces: (p. 455) Link_Constraint - superclass: Matrix3Controller (p. 295)

LinkedXForm - superclass: modifier

297

LinkedXForm - superclass: modifier

LinkedXForm - superclass: modifier; super-superclass:MAXWrapper - 1:0 - classID: #(806195, 0) Constructor:
LinkedXForm ...

Properties:
<LinkedXForm>.node UndefinedClass default: undefined -node

Object that the vertices are linked to. When transformed, the vertices follow.

LookAt_Constraint - superclass: RotationController

LookAt_Constraint - superclass: RotationController; super-superclass:MAXWrapper - 11:0 - classID: #(8225, 0) Constructor:
LookAt_Constraint ...

Properties:
<LookAt_Constraint>.relative boolean <LookAt_Constraint>.lookat_vector_length animatable; float; Vector_Length <LookAt_Constraint>.set_orientation boolean <LookAt_Constraint>.target_axis <LookAt_Constraint>.target_axisFlip boolean <LookAt_Constraint>.upnode_axis <LookAt_Constraint>.upnode_world boolean <LookAt_Constraint>.pickUpNode node; Pick_Upnode <LookAt_Constraint>.StoUP_axis <LookAt_Constraint>.StoUP_axisFlip boolean <LookAt_Constraint>.viewline_length_abs boolean; Viewline_Abs BooleanClass Float BooleanClass Integer BooleanClass Integer BooleanClass default: false default: 100.0 default: false default: 2 -default: false ---integer --

default: 0 -- integer default: true ---

UndefinedClass default: undefined Integer BooleanClass BooleanClass default: 0 -default: false default: true

integer ---

See Also
LookAt Constraint interfaces: (p. 455)

298

Chapter 1

Whats New in 3ds max 4 MAXScript

Mesher - superclass: GeometryClass

Mesher - superclass: GeometryClass; super-superclass:node - 8:0 - classID: #(998877, 32670) Constructor:
Mesher ...

Properties:
<Mesher>.pick UndefinedClass default: undefined -node

Click this button and then select the object to be instanced by the Mesher object. After doing so, the name of the instanced object appears on the button.
<Mesher>.renderTimeOnly BooleanClass default: false -boolean

When on, the Mesher particles do not appear in the viewports, but only when you render the scene. Default=off.
<Mesher>.extranodes <Mesher>.time ArrayParameter Float default: #() default: 0.0 --node array float

The number of frames ahead of or behind the original particle system that the Meshers particle system will run. Default=0.
<Mesher>.radius <Mesher>.useCustomBounds Use_Custom_Bounds Float BooleanClass default: 10.0 default: false -- float -- boolean;

When on, Mesher replaces the dynamic bounding box derived from the particle system and modifier with a static bounding box of the users choice.
<Mesher>.boundsMin <Mesher>.boundsMax BoundsB Point3 Point3 default: [1,1,1] -- point3; BoundsA default: [-1,-1,-1] -- point3;

The coordinates of the opposite corners of the custom bounding box.

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

meshsmooth - superclass: modifier

meshsmooth - superclass: modifier; super-superclass:MAXWrapper - 29:0 - classID: #(50, 32670) Constructor:
meshsmooth ...

Properties:
<meshsmooth>.subdivMethod Subdivision_Method Integer default: 2 -integer;

Selects the Subdivision method to use:

meshsmooth - superclass: modifier

299

0-Classic (Produces three- and four-sided facets.) 1-Quad Output (Produces only four-sided facets.) 2-NURMS (Produces Non-Uniform Rational MeshSmooth object.)
<meshsmooth>.ignoreSel Apply_To_Whole_Mesh BooleanClass default: true -boolean;

When turned on, any sub-object selection passed up the stack is ignored and MeshSmooth is applied to the entire object.
<meshsmooth>.oldMapping Old_style_Mapping BooleanClass default: false -boolean;

Uses the algorithm from the previous release of the program to apply MeshSmooth to the mapping coordinates. This technique tends to distort the underlying mapping coordinates as it creates new faces and as texture coordinates shift.
<meshsmooth>.iterations Integer default: 0 -animatable; integer

The number of iterations used to smooth the mesh. Each iteration generates new faces using the vertices created from the previous iteration.
<meshsmooth>.smoothness Smoothness_Filter Float default: 1.0 -animatable; float;

Determines how sharp a corner must be before faces are added to smooth it. Smoothness is calculated as the average angle of all edges connected to a vertex. A value of 0.0 prevents the creation of any faces. A value of 1.0 adds faces to all vertices even if they lie on a plane.
<meshsmooth>.useRenderIterations Use_Render_Iterations BooleanClass default: false -boolean;

Turn on/off use of render iterations, for using a different number of iterations at render time. When off, the software will use the iterations value.
<meshsmooth>.renderItSerations integer; Render_Iterations <meshsmooth>.useRenderSmoothness Use_Render_Smoothness Integer default: 0 -animatable;

Number of smoothing iterations to be applied to the object at render time.

BooleanClass default: false -boolean;

Turn on/off use of render smoothness, for using a different smoothness value at render time. When off, the software will use the smoothness value.
<meshsmooth>.renderSmoothness Render_Smoothness <meshsmooth>.faceType Integer Float default: 1.0 -animatable; float;

Lets you choose a different Smoothness value to be applied to the object at render time.
default: 1 -integer; Face_Type

Select the type to operate on during input conversion: 0-Faces 1-Polygons Operate On Faces treats every triangle as a face and smooths across all edges, even invisible edges. Operate On Polygons ignores invisible edges, treating polygons (like the quads making up a box or the cap on a cylinder) as a single face.

300

Chapter 1

Whats New in 3ds max 4 MAXScript

<meshsmooth>.keepConvex Keep_Input_Faces_Convex

BooleanClass

default: false

--

boolean;

Keeps all input polygons convex. Selecting this option causes non-convex polygons to be handled as a minimum number of separate faces, each of which is convex.
<meshsmooth>.update Integer default: 0 -integer; Update_Options

Set update options: 0-Always update 1-Update when rendering 2-Update Manually
<meshsmooth>.limitSurface Project_to_Limit_Surface BooleanClass default: false -boolean;

Places all points on the limit surface of the MeshSmooth result, which is the surface youd get after an infinite number of iterations.
<meshsmooth>.smoothResult Smooth_Output <meshsmooth>.sepByMats Separate_By_Materials <meshsmooth>.sepBySmGroups Separate_By_Smoothing_Group BooleanClass default: true -boolean;

Applies the same smoothing group to all faces.

BooleanClass default: false -boolean;

Prevents the creation of new faces for edges between faces that do not share Material IDs.
BooleanClass default: false -boolean;

Prevents the creation of new faces at edges between faces that dont share at least one smoothing group.
<meshsmooth>.ignoreBackfacing Ignore_Backfacing BooleanClass default: false -boolean;

When on, selection of sub-objects selects only those sub-objects whose normals are visible in the viewport. When off (the default), selection includes all sub-objects, regardless of the direction of their normals.
<meshsmooth>.displayCage Display_Control_Mesh BooleanClass default: false -boolean;

Displays an orange wireframe gizmo that shows what the control mesh looks like after its been converted to polygons (if applicable) and before the smoothing occurs.
<meshsmooth>.controlLevel Integer default: 0 -integer; Control_Level

Allows you to see the control mesh after one or more iterations and to edit sub-object points and edges at that level.
<meshsmooth>.useSoftSel Use_Soft_Selection BooleanClass default: false -boolean;

Affects the action of Move, Rotate, and Scale functions within editable object or edit modifier, and the action of deformation modifiers applied to the object if they are operating on a sub-object selection. When on, 3ds max applies a spline curve deformation to the unselected sub-objects surrounding the selection that you transform.

meshsmooth - superclass: modifier

301

<meshsmooth>.useEdgeDist Use_Edge_Distance <meshsmooth>.edgeDist

BooleanClass

default: false

--

boolean;

Turn on/off use Edge Distance.

Integer default: 1 -integer; Edge_Distance

Limits the region affected by the number of edges between the selection and the affected vertices.
<meshsmooth>.affectBackfacing Affect_Backfacing BooleanClass default: false -boolean;

When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the normals of faces to which theyre attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence.
<meshsmooth>.falloff Float default: 20.0 -float

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry.
<meshsmooth>.pinch Float default: 0.0 -float

Raises and lowers the top point of the curve along the vertical axis. Sets the relative pointedness of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis.
<meshsmooth>.bubble Float default: 0.0 -float

Expands and contracts the curve along the vertical axis. Sets the relative fullness of the region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble move the bottom of the curve below the surface, creating a valley around the base of the region.
<meshsmooth>.reset Integer default: 1 -integer; Update_Options

Select reset settings: 0-Reset all levels 1-Reset this level

See Also
MeshSmooth : Modifier (p. 1139)

302

Chapter 1

Whats New in 3ds max 4 MAXScript

Modifier and SpacewarpModifier Types (p. 1100)

Motion_Blur - superclass: renderEffect

Motion_Blur - superclass: renderEffect; super-superclass:MAXWrapper - 2:0 - classID: #(141333203, 1612379012) Constructor:
Motion_Blur ...

Properties:
<Motion_Blur>.duration float Float default: 1.0 -animatable;

Specifies how long the virtual shutter is open. When this is set to 1.0, the virtual shutter is open for the entire duration between one frame and the next. The higher the value, the greater the motion Blur effect. Default=1.0.
<Motion_Blur>.transparency BooleanClass default: true -boolean

When on, motion blur is applied to objects behind transparent objects. When off, objects behind transparent objects receive no motion blur. Turning off this toggle can improve rendering speed. Default=on.

See Also
Motion_Blur interfaces: (p. 462)

MultiRes - superclass: modifier

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

Properties:
<MultiRes>.Vtx_Count integer Integer default: 0 -animatable;

The total number of vertices in the modified object. Use this control to set the maximum number of vertices in the output mesh. Adjusting this setting alters the Percent value as well.

MultiRes - superclass: modifier

303

<MultiRes>.Vertex_Percentage animatable; float

Float

default: 100.0

--

The modified objects vertex count as a percentage of the overall number of vertices in the original mesh. Adjusting this setting alters the Count value as well. Note: After you type in a specific percentage, such as 30, you might find that the software changes the value to a slightly lower one, such as 29.971. This is due to the relationship between the overall number of vertices in the model and the percentage calculation. It is not a bug, but simply the closest solution to your request.
<MultiRes>.Vertex_Merging BooleanClass default: false -boolean

When on, lets MultiRes merge vertices between discrete elements in a model. For example, if you apply MultiRes to a teapot, which comprises four separate elements, and turn on Vertex Merging, as you adjust the vertex resolution, the separate components will meld together into one contiguous lower-resolution object. To control Vertex Merging, you can set a Merge Threshold. This value determines the 3ds max unit distance within which to merge elements.
<MultiRes>.Threshold Float default: 0.0 -float

This spinner value sets the maximum distance in 3ds max units between vertices in order for those vertices to be considered for merging. Once this threshold is achieved, then the vertices between elements will be welded together as the mesh is reduced in complexity. Note: To eliminate only coincident vertices, set Merge Threshold to 0.0. This is similar to the Weld Vertex function.
<MultiRes>.Merge_Within BooleanClass default: false -boolean

When on, MultiRes merges the boundaries of adjacent elements and vertices within elements. Many objects can contain multiple groups of vertices that dont share connectivity. A simple example of this is the Teapot object. It comprises four different elements: the body, the handle, the spout, and the lid. Normally, MultiRes optimizes each discrete element in a mesh on its own. The default behavior of the Vertex Merging option is to merge vertices between elements. Turning on Within Mesh? causes vertices within elements to be merged as well.
<MultiRes>.Boundary_Metric BooleanClass default: false -boolean

When on, MultiRes preserves materials assigned to the selected model. The material boundaries defined by Material IDs are retained as long as possible, and are the last to be eliminated at low vertex counts. Default=off.
<MultiRes>.Maintain_Base_Vertices BooleanClass default: false -boolean

When on, overrides the MultiRes optimization algorithms and preserves any vertices selected at the MultiRes Vertex sub-object level as critical ones. Use this feature to retain critical features of an object or character such as its fingers or claws, or other geometry that might become unrecognizable if reduced too severely. To select vertices for use with this option, use the MultiRes Vertex sub-object level. To access this level, first go to the modifier stack display and click the plus-sign icon next to the MultiRes modifier. This opens up its hierarchy, which consists of the single Vertex sub-

304

Chapter 1

Whats New in 3ds max 4 MAXScript

object level. Next, click the Vertex entry. The MultiRes vertices appear on the mesh as blue dots. You can select these using any standard interactive method, but you cannot transform them. Important: After selecting MultiRes sub-object vertices with Maintain Base Vertices turned on, re-generate the mesh before changing the vertex resolution. In the following illustration, the clown started out as a high-resolution mesh. All of the MultiRes vertices in the right half were selected, Maintain Base Vertices was turned on, and then the vertices were reduced. {mrm_clown.bmp}
<MultiRes>.Multiple_Normals_Per_Vertex BooleanClass default: true -boolean

When on, lets MultiRes assign multiple normals for each vertex. By default, MultiRes generates a single normal per vertex. If multiple normals are generated, they are applied as the vertex resolution is decreased and increased. When the Multiple Normals Per Vertex option is checked, the MultiRes modifier generates normal updates when the geometry surrounding a vertex changes. You must specify a crease angle in degrees (0.0 - 180.0). The crease angle is the angle between the face normals. It is used to decide when a normal should be shared across an edge between two faces. For example, in a plane defined as a mesh grid of 10 x 10 faces, any two adjacent faces have a crease angle of zero. In a cube, adjacent faces have a crease angle of 90 degrees. In general, crease angles approaching 0 yield smoother shading. Crease angles approaching 180 yield more visible corners.
<MultiRes>.Crease_Angle Float default: 75.0 -float

The value of the crease necessary in order to generate multiple normals. Available only when Multiple Normals Per Vertex is on. The optimal crease angle depends on the model; set it interactively and check the viewport and rendered images for shading effects. While use of multiple normals per vertex enables more accurate shading, it can require more internal data.
<MultiRes>.Generate BooleanClass default: false -boolean

Applies the current MultiRes settings to the modified object. When you first apply MultiRes to an object, it must initialize its mesh-optimizing algorithm; you are prompted by the modifier to Generate when ready. Note: When working with complex meshes, the initial analysis may take a little while. During this time, MultiRes displays a special cursor to indicate it is working. Progress is indicated on this cursor by the movement of the gray area from top to bottom. To cancel this process, press ESC.

Normalize_Spl - superclass: modifier

305

Example:
modPanel.addModToSelection(MultiRes()) $.modifiers[#MultiRes].Vtx_Count = 482 $.modifiers[#MultiRes].Vertex_Percentage = 100 $.modifiers[#MultiRes].Vertex_Percentage = 99 $.modifiers[#MultiRes].Vtx_Count = 476 $.modifiers[#MultiRes].Vertex_Percentage = 98.7552 $.modifiers[#MultiRes].Vertex_Merging = on $.modifiers[#MultiRes].Threshold = 0.01 $.modifiers[#MultiRes].Merge_Within = on $.modifiers[#MultiRes].Boundary_Metric = on $.modifiers[#MultiRes].Maintain_Base_Vertices = on $.modifiers[#MultiRes].Crease_Angle = 75.75

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Normalize_Spl - superclass: modifier

Normalize_Spl - superclass: modifier; super-superclass:MAXWrapper - 1:0 - classID: #(474287708, 772671746) Constructor:
Normalize_Spl ...

Properties:
<Normalize_Spl>.Length Float default: 20.0 -float

Determines how many control points are added. Smaller values produce more control points; larger values produce fewer. The positions of the original vertices are disregarded. Vertices are set to regular intervals once the Normalize Spline modifier is applied.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods

306

Chapter 1

Whats New in 3ds max 4 MAXScript

Orientation_Constraint - superclass: RotationController

Orientation_Constraint - superclass: RotationController; super-superclass:MAXWrapper - 2:0 classID: #(8224, 0) Constructor:
Orientation_Constraint ...

Properties:
<Orientation_Constraint>.relative boolean <Orientation_Constraint>.local_world LocalOrWorld BooleanClass Integer default: false default: 0 --integer;

See Also
Orientation_Constraint interfaces: (p. 462)

particleMesher - superclass: GeometryClass

particleMesher - superclass: GeometryClass; super-superclass:node - 8:0 - classID: #(998877, 32670) The Mesher compound object converts procedural objects to mesh objects on a per-frame basis so that you can apply modifiers such as Bend or UVW Map. It can be used with any type of object, but is designed primarily to work with particle systems. Mesher is also useful for low-overhead instancing of objects with complex modifier stacks. Constructor:
particleMesher ...

Properties:
<particleMesher>.pick UndefinedClass default: undefined -node

Click this button and then select the object to be instanced by the Mesher object. After doing so, the name of the instanced object appears on the button.
<particleMesher>.renderTimeOnly BooleanClass default: false -boolean

When on, the Mesher particles do not appear in the viewports, but only when you render the scene. Default=off. Use this option to reduce the amount of computation required for the viewport display.
<particleMesher>.extranodes <particleMesher>.time ArrayParameter Float default: #() default: 0.0 --node array float

The number of frames ahead of or behind the original particle system that the Meshers particle system will run. Default=0.

Patch_Select - superclass: modifier

307

<particleMesher>.radius <particleMesher>.useCustomBounds Use_Custom_Bounds

Float BooleanClass

default: 10.0 default: false

-- float -- boolean;

When on, Mesher replaces the dynamic bounding box derived from the particle system and modifier with a static bounding box of the users choice.
<particleMesher>.boundsMin BoundsA <particleMesher>.boundsMax point3; BoundsB Point3 Point3 default: [1,1,1] default: [-1,-1,-1] -point3; --

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

Patch_Select - superclass: modifier

Patch_Select - superclass: modifier; super-superclass:MAXWrapper - 0:0 - classID: #(425273138, 54557306) The Patch Select modifier lets you pass a sub-object selection up the stack to subsequent modifiers. It provides a superset of the selection functions available in the Edit Patch modifier. You can select vertices, edges, patches and elements. You can also change the selection from sub-object level to object level.

See Also
Patches (p. 55) patch const StructDef (p. 245) patchOps const StructDef (p. 247) Patch : GeometryClass (p. 1088)

Path_Constraint - superclass: PositionController

Path_Constraint - superclass: PositionController; super-superclass:MAXWrapper - 12:0 - classID: #(8209, 0) Constructor:
Path_Constraint ...

Properties:
<Path_Constraint>.percent Float default: 0.0 animatable; percentage; Controller Scaling: (1 : 100.0) --

Sets the percent that the object is positioned along the path. This duplicates the Value spinner in the track Properties dialog for the Percent track in Track View. If you want to set keys to place an object at a certain percent along the path, turn on Animate, move to the

308

Chapter 1

Whats New in 3ds max 4 MAXScript

frame where you want the key set, and adjust the % Along Path spinner to move the object.
<Path_Constraint>.follow <Path_Constraint>.path node; Path_Constraint BooleanClass UndefinedClass default: false -boolean --

Aligns the object to the trajectory as it follows the contour.

default: undefined

Add Path: is used to add a new spline path that influences the constrained object. Delete path : is used to remove a path from the target list. Once removing the path target, it will no longer influence the constrained object
<Path_Constraint>.bank <Path_Constraint>.bankAmount animatable; float; Bank_Amount BooleanClass Float default: false default: 0.5 --boolean

Allows the object to bank (roll) as it negotiates the curves of the spline.

Adjusts the amount of the banking to one side or the other, depending on whether the value is positive or negative
<Path_Constraint>.smoothness animatable; float Float default: 0.5 --

Controls how rapidly the roll angle changes as the object moves through bends in the trajectory. Smaller values will make the object more responsive to subtle changes in the curve, while larger values smooth out jerking. The default value is a good value for general damping along the curve. Values below 2 tend to make the action jerky, but values around 3 can be very useful for simulating a certain degree of realistic instability.
<Path_Constraint>.allowUpsideDown boolean; Allow_Upside_Down BooleanClass default: false --

Turn on to avoid the situation in which an object flips when going around a vertically oriented path.
<Path_Constraint>.constantVel boolean; Constant_Velocity BooleanClass default: false --

Provides a constant velocity along the path. When off, the velocity of the object along the path varies depending on the distance between the vertices on the path.
<Path_Constraint>.axis <Path_Constraint>.axisFlip boolean; Axis_Flip Integer BooleanClass default: 0 -integer --

Defines which axis of the object is aligned to the trajectory of the path.
default: false

Turn on to flip the direction of the axis

<Path_Constraint>.loop BooleanClass default: false -boolean

By default, when the constrained object reaches the end of a path it can no longer move past the end point. The loop option changes this behavior so that when the constrained object reaches the end of the path it loops back to the starting point.
<Path_Constraint>.relative BooleanClass default: false -boolean

Turn on to maintain the original position of the constrained object. The object will follow the path with an offset distance based on its original world space position

PDynaflector - superclass: SpacewarpObject

309

See Also
Path_Constraint interfaces: (p. 468)

PDynaflector - superclass: SpacewarpObject

PDynaflector - superclass: SpacewarpObject; super-superclass:node - 21:0 - classID: #(11824263, 1055795908) Constructor:
...

Properties:
<PDynaflector>.time on Time_On <PDynaflector>.time off Time_Off Integer default: 0 -animatable; integer;

Integer

default: 16000

--

animatable; integer;

<PDynaflector>.affects Float default: 10000.0 Reflects; Controller Scaling: (1 : 100.0) <PDynaflector>.bounce Float default: 1.0 --

--

animatable; percentage;

animatable; float -animatable; percentage;

<PDynaflector>.bouncevar Float default: 0.0 Bounce_Variation; Controller Scaling: (1 : 100.0) <PDynaflector>.chaos Float Controller Scaling: (1 : 100.0) <PDynaflector>.inheritVelocity Velocity_Inheritance <PDynaflector>.width <PDynaflector>.height <PDynaflector>.mass Particle_Mass Float Float Float default: 0.0 --

animatable; percentage;

Float

default: 1.0

--

animatable; float;

default: 0.0 default: 0.0 default: 1.0

----

animatable; float animatable; float animatable; float;

<PDynaflector>.mass units Particle_Mass_Units <PDynaflector>.force in x Force_in_X_Direction <PDynaflector>.force in y Force_in_Y_Direction

Integer

default: 0

--

radio button number;

Float

default: 0.0

--

animatable; float;

Float

default: 0.0

--

animatable; float;

310

Chapter 1

Whats New in 3ds max 4 MAXScript

<PDynaflector>.force in z Force_in_Z_Direction <PDynaflector>.apply at x Apply_at_X_location <PDynaflector>.apply at y Apply_at_Y_location <PDynaflector>.apply at z Apply_at_Z_location <PDynaflector>.number Number_of_Particles

Float

default: 0.0

--

animatable; float;

Float

default: 0.0

--

animatable; float;

Float

default: 0.0

--

animatable; float;

Float

default: 0.0

--

animatable; float;

Integer

default: 0

--

animatable; integer;

<PDynaflector>.friction Float Controller Scaling: (1 : 100.0) <PDynaflector>.quality Collision_Quality <PDynaflector>.collider Collision_Quality Integer

default: 0.0

--

animatable; percentage;

default: 20

--

animatable; integer;

UndefinedClass

default: undefined

--

max object;

Plane_Angle - superclass: helper

Plane_Angle - superclass: helper; super-superclass:node - 6:0 - classID: #(635524970, 561654288) Constructor:
Plane_Angle ...

Properties:
<Plane_Angle>.Origin Point3 <Plane_Angle>.NormalVec Point3 <Plane_Angle>.UpVec Point3 <Plane_Angle>.Angle Float Controller Scaling: (1 : 57.2958) default: default: default: default: [0,0,0] [0,0,1] [0,1,0] 0.0 --- point3 -- point3; Normal_Vector -- point3; Up_Vector animatable; angle;

The angle of the manipulator, from 0.0 to 360.0 (both values are perpendicular in the Y axis of the viewport where you created the manipulator, unless you have rotated the manipulator object). Default=0.0.
<Plane_Angle>.Distance Float default: 0.0 -float

The length of the manipulator, in 3ds max units. Default=the distance of mouse drag when the manipulator was created.
<Plane_Angle>.Size Float default: 1.0 -float

The size of the manipulators handle, in 3ds max units. Default=1.0.

PlaneAngleManip - superclass: helper

311

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

PlaneAngleManip - superclass: helper

PlaneAngleManip - superclass: helper; super-superclass:node - 6:0 - classID: #(635524970, 561654288) Constructor:
PlaneAngleManip ...

Properties:
<PlaneAngleManip>.Origin Point3 <PlaneAngleManip>.NormalVec Point3 Normal_Vector <PlaneAngleManip>.UpVec Point3 <PlaneAngleManip>.Angle Float Controller Scaling: (1 : 57.2958) default: [0,0,0] default: [0,0,1] default: [0,1,0] default: 0.0 ---point3 point3;

-- point3; Up_Vector animatable; angle;

The angle of the manipulator, from 0.0 to 360.0 (both values are perpendicular in the Y axis of the viewport where you created the manipulator, unless you have rotated the manipulator object). Default=0.0.
<PlaneAngleManip>.Distance Float default: 0.0 -float

The length of the manipulator, in 3ds max units. Default=the distance of mouse drag when the manipulator was created.
<PlaneAngleManip>.Size Float default: 1.0 -float

The size of the manipulators handle, in 3ds max units. Default=1.0.

312

Chapter 1

Whats New in 3ds max 4 MAXScript

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

Point3List - superclass: Point3Controller

Point3List - superclass: Point3Controller; super-superclass:MAXWrapper - 1:1 - classID: #(1263210497, 0) Constructor:
Point3List ...

Properties:
<Point3List>.available Point3 default: [0,0,0] -- animatable; point3; Controller Scaling: ([1,1,1] : [0,0,0]); WeirdScaled ([0,0,0])

See Also
Point3List interfaces: (p. 479)

Point3Reactor - superclass: Point3Controller

Point3Reactor - superclass: Point3Controller; super-superclass:MAXWrapper - 0:0 - classID: #(419957000, 996243513)

See Also
Point3Reactor interfaces: (p. 481)

Point3Spring - superclass: Point3Controller

313

Point3Spring - superclass: Point3Controller

Point3Spring - superclass: Point3Controller; super-superclass:MAXWrapper - 4:4 - classID: #(327754098, 1754751609) Constructor:
Point3Spring ...

Properties:
<Point3Spring>.position <Point3Spring>.x_effect Point3 Float default: [0,0,0] default: 100.0 -animatable; point3

These settings let you control the percentage of the effect on the individual world axes. Default=100. Range=0 to 200.
<Point3Spring>.y_effect Float default: 100.0

These settings let you control the percentage of the effect on the individual world axes. Default=100. Range=0 to 200.
<Point3Spring>.z_effect Float default: 100.0

These settings let you control the percentage of the effect on the individual world axes. Default=100. Range=0 to 200.

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

314

Chapter 1

Whats New in 3ds max 4 MAXScript

Point_Cache - superclass: modifier

Point_Cache - superclass: modifier; super-superclass:MAXWrapper - 7:0 - classID: #(567311073, 1221790700) Constructor:
Point_Cache ...

Properties:
<Point_Cache>.time <Point_Cache>.start_time Float Float default: 0.0 default: 0.0 --float float

The frame number at which the cached animation starts playing back. Using decimal fractions lets you start at a sub-frame setting when using a Frame:Ticks time display. Default=0.0. Sets the first frame for recording the vertex animation.
<Point_Cache>.end_time <Point_Cache>.samples <Point_Cache>.cache_file Float Integer UndefinedClass default: 100.0 -float

Sets the last frame for recording the vertex animation.

default: 1 -- integer default: undefined -- string

Loads a vertex animation from a cache file on disk into the Point Cache modifier. If number of vertices in the cache file does not match the number of vertices in the object, a warning appears, but no error occurs.
<Point_Cache>.relativeOffset Relative_Offset BooleanClass default: false -boolean;

Makes the Strength setting available. This enables offsetting the animated vertex positions relative to their positions as recorded. Default=off. Note: When you turn on Use Relative Offsets and play back a cached animation with the modifiers turned on, the cached vertex positions are calculated relative to their positions as calculated by the modifiers. For example, if you record a Bend animation to a cache file, and then play it back with both Use Relative Offsets and the Bend modifier turned on and Strength=1.0, all vertex positions are doubled, resulting in exaggerated motion.
<Point_Cache>.strength Float default: 1.0 -animatable; float

Affects the motion relative to the original animation. Available only when Use Relative Offsets is turned on. Default=1.0. Range=-10.0 to 10.0. At 1.0, the animation plays back the same as recorded. With strengths between 0 and 1, the animation is relatively restrained. At strengths greater than 1, the animation is exaggerated. With negative Strength settings, the motion is reversed.

See Also
Point Cache Modifier (p. 26) Point_Cache interfaces: (p. 484) Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315) Point_CacheSpacewarpModifier interfaces: (p. 485)

Point_CacheSpacewarpModifier - superclass: SpacewarpModifier

315

Point_CacheSpacewarpModifier - superclass: SpacewarpModifier

Point_CacheSpacewarpModifier - superclass: SpacewarpModifier; super-superclass:MAXWrapper 7:0 - classID: #(567311073, 1221790701) Constructor:
Point_CacheSpacewarpModifier ...

Properties:
<Point_CacheSpacewarpModifier>.time float <Point_CacheSpacewarpModifier>.start_time float Float Float default: 0.0 default: 0.0 ---

The frame number at which the cached animation starts playing back. Using decimal fractions lets you start at a sub-frame setting when using a Frame:Ticks time display. Default=0.0. Sets the first frame for recording the vertex animation.
<Point_CacheSpacewarpModifier>.end_time float <Point_CacheSpacewarpModifier>.samples integer <Point_CacheSpacewarpModifier>.cache_file undefined -- string Float default: 100.0 --

Sets the last frame for recording the vertex animation.

Integer default: 1 --

UndefinedClass default:

Loads a vertex animation from a cache file on disk into the Point Cache modifier. If number of vertices in the cache file does not match the number of vertices in the object, a warning appears, but no error occurs.
<Point_CacheSpacewarpModifier>.relativeOffset BooleanClass boolean; Relative_Offset default: false --

Makes the Strength setting available. This enables offsetting the animated vertex positions relative to their positions as recorded. Default=off. Note: When you turn on Use Relative Offsets and play back a cached animation with the modifiers turned on, the cached vertex positions are calculated relative to their positions as calculated by the modifiers. For example, if you record a Bend animation to a cache file, and then play it back with both Use Relative Offsets and the Bend modifier turned on and Strength=1.0, all vertex positions are doubled, resulting in exaggerated motion.
<Point_CacheSpacewarpModifier>.strength animatable; float Float default: 1.0 --

Affects the motion relative to the original animation. Available only when Use Relative Offsets is turned on. Default=1.0. Range=-10.0 to 10.0. At 1.0, the animation plays back the same as recorded. With strengths between 0 and 1, the animation is relatively restrained. At strengths greater than 1, the animation is exaggerated. With negative Strength settings, the motion is reversed.

316

Chapter 1

Whats New in 3ds max 4 MAXScript

See Also
Point Cache Modifier (p. 26) Point_Cache interfaces: (p. 484) Point_Cache - superclass: modifier (p. 314) Point_CacheSpacewarpModifier interfaces: (p. 485)

PointCache - superclass: modifier

PointCache - superclass: modifier; super-superclass:MAXWrapper - 7:0 - classID: #(567311073, 1221790700) Constructor:
PointCache ...

Properties:
<PointCache>.time <PointCache>.start_time Float Float default: 0.0 default: 0.0 --float float

The frame number at which the cached animation starts playing back. Using decimal fractions lets you start at a sub-frame setting when using a Frame:Ticks time display. Default=0.0. Sets the first frame for recording the vertex animation.
<PointCache>.end_time <PointCache>.samples <PointCache>.cache_file Float default: 100.0 -float

Sets the last frame for recording the vertex animation.

Integer default: 1 -- integer UndefinedClass default: undefined -- string

Loads a vertex animation from a cache file on disk into the Point Cache modifier. If number of vertices in the cache file does not match the number of vertices in the object, a warning appears, but no error occurs.
<PointCache>.relativeOffset BooleanClass Relative_Offset default: false -boolean;

Makes the Strength setting available. This enables offsetting the animated vertex positions relative to their positions as recorded. Default=off. Note: When you turn on Use Relative Offsets and play back a cached animation with the modifiers turned on, the cached vertex positions are calculated relative to their positions as calculated by the modifiers. For example, if you record a Bend animation to a cache file, and then play it back with both Use Relative Offsets and the Bend modifier turned on and Strength=1.0, all vertex positions are doubled, resulting in exaggerated motion.

PointCacheWSM - superclass: SpacewarpModifier

317

<PointCache>.strength

Float

default: 1.0

--

animatable; float

Affects the motion relative to the original animation. Available only when Use Relative Offsets is turned on. Default=1.0. Range=-10.0 to 10.0. At 1.0, the animation plays back the same as recorded. With strengths between 0 and 1, the animation is relatively restrained. At strengths greater than 1, the animation is exaggerated. With negative Strength settings, the motion is reversed.

See Also
Point Cache Modifier (p. 26) Point_Cache interfaces: (p. 484) Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315) Point_CacheSpacewarpModifier interfaces: (p. 485)

PointCacheWSM - superclass: SpacewarpModifier

PointCacheWSM - superclass: SpacewarpModifier; super-superclass:MAXWrapper - 7:0 - classID: #(567311073, 1221790701) Constructor:
PointCacheWSM ...

Properties:
<PointCacheWSM>.time <PointCacheWSM>.start_time Float Float default: 0.0 default: 0.0 --float float

The frame number at which the cached animation starts playing back. Using decimal fractions lets you start at a sub-frame setting when using a Frame:Ticks time display. Default=0.0. Sets the first frame for recording the vertex animation.
<PointCacheWSM>.end_time <PointCacheWSM>.samples <PointCacheWSM>.cache_file Float default: 100.0 -float

Sets the last frame for recording the vertex animation.

Integer default: 1 -- integer UndefinedClass default: undefined -- string

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

318

Chapter 1

Whats New in 3ds max 4 MAXScript

<PointCacheWSM>.relativeOffset BooleanClass Relative_Offset

default: false

--

boolean;

Makes the Strength setting available. This enables offsetting the animated vertex positions relative to their positions as recorded. Default=off. Note: When you turn on Use Relative Offsets and play back a cached animation with the modifiers turned on, the cached vertex positions are calculated relative to their positions as calculated by the modifiers. For example, if you record a Bend animation to a cache file, and then play it back with both Use Relative Offsets and the Bend modifier turned on and Strength=1.0, all vertex positions are doubled, resulting in exaggerated motion.
<PointCacheWSM>.strength Float default: 1.0 -animatable; float

Affects the motion relative to the original animation. Available only when Use Relative Offsets is turned on. Default=1.0. Range=-10.0 to 10.0. At 1.0, the animation plays back the same as recorded. With strengths between 0 and 1, the animation is relatively restrained. At strengths greater than 1, the animation is exaggerated. With negative Strength settings, the motion is reversed.

See Also
Point Cache Modifier (p. 26) Point_Cache interfaces: (p. 484) Point_Cache - superclass: modifier (p. 314) Point_CacheSpacewarpModifier interfaces: (p. 485)

PointHelperObj - superclass: helper

PointHelperObj - superclass: helper; super-superclass:node - 7:0 - classID: #(8211, 0) Constructor:
PointHelperObj ...

Properties:
<PointHelperObj>.size animatable; float Float default: 20.0 --

Sets the size for the point object. Use this to minimize the point object, or increase its size to aid in locating it. Default=20.
<PointHelperObj>.centermarker BooleanClass animatable; boolean; Center_Marker <PointHelperObj>.axistripod animatable; boolean; Axis_Tripod BooleanClass default: false --

Displays a small X marker at the center of the point object.

default: false --

Displays a tripod axis indicating the position and orientation of the point object. The axis remains visible when the point object is no longer selected.

Poly_Select - superclass: modifier

319

<PointHelperObj>.cross animatable; boolean

BooleanClass

default: true

--

Displays an axis-aligned cross.

<PointHelperObj>.box animatable; boolean BooleanClass default: false --

Displays a small box at the center of the point object.

<PointHelperObj>.constantscreensize BooleanClass animatable; boolean; Constant_Screen_Size <PointHelperObj>.drawontop animatable; boolean; Draw_On_Top BooleanClass default: false --

Keeps the size of the point object constant, regardless of how much you zoom in or out.
default: false --

Displays the point object on top of all other objects in the scene.

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

Poly_Select - superclass: modifier

Poly_Select - superclass: modifier; super-superclass:MAXWrapper - 7:0 - classID: #(2095390827, 823661829) Constructor:
Poly_Select ...

Properties:
<Poly_Select>.useSoftSelection boolean; Use_Soft_Selection BooleanClass default: false --

Affects the action of Move, Rotate, and Scale functions within editable object or edit modifier, and the action of deformation modifiers applied to the object if they are operating on a sub-object selection. When on, 3ds max applies a spline curve deformation to the unselected sub-objects surrounding the selection that you transform. To take effect, this check box must be on before moving the selection. You can also use the keyboard shortcut CTRL+S to toggle Use Soft Selection (while the Plug-In Keyboard Shortcut Toggle button is turned on).
<Poly_Select>.softselUseEdgeDistance boolean; Use_Edge_Distance <Poly_Select>.softselEdgeDist animatable; integer; Edge_Distance BooleanClass Integer default: false default: 1 ---

This spinner setting limits the region affected by the number of edges between the selection and the affected vertices. The affected region is measured in terms of edge-distance space, along the surface, rather than real space.

320

Chapter 1

Whats New in 3ds max 4 MAXScript

<Poly_Select>.softselAffectBackfacing boolean; Affect_Backfacing

BooleanClass

default: false

--

When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the normals of faces to which theyre attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence. Turn off Affect Backfacing when you want to pull faces of a thin object, such as a thin box, but dont want to affect faces on the other side of the object. You can also use the keyboard shortcut CTRL+F to toggle Affect Backfacing (while the PlugIn Keyboard Shortcut Toggle button is turned on).
<Poly_Select>.softselFalloff animatable; world units; Falloff Float default: 20.0 --

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry. Default=20. Note: At the Vertex sub-object level, the region specified by the Falloff setting is depicted graphically in the viewports as a vertex-color gradient from the Sub-selection color (normally red) to the Vertex Ticks color (normally blue). In addition, this gradient is updated in real time as you change the Falloff setting.
<Poly_Select>.softselPinch animatable; float; Pinch Float default: 0.0 --

Raises and lowers the top point of the curve along the vertical axis. Sets the relative pointedness of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis. Default=0.
<Poly_Select>.softselBubble animatable; float; Bubble Float default: 0.0 --

Expands and contracts the curve along the vertical axis. Sets the relative fullness of the region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble move the bottom of the curve below the surface, creating a valley around the base of the region. Default=0.

Position_Constraint - superclass: PositionController

Position_Constraint - superclass: PositionController; super-superclass:MAXWrapper - 1:0 - classID: #(8217, 0) Constructor:
Position_Constraint ...

Properties:
<Position_Constraint>.relative BooleanClass default: false -boolean

PositionList - superclass: PositionController

321

See Also
Position_Constraint interfaces: (p. 488)

PositionList - superclass: PositionController

PositionList - superclass: PositionController; super-superclass:MAXWrapper - 1:1 - classID: #(1263210498, 0) Constructor:
PositionList ...

Properties:
<PositionList>.available Point3 default: [0,0,0] -animatable; point3

See Also
PositionList interfaces: (p. 494)

PositionReactor - superclass: PositionController

PositionReactor - superclass: PositionController; super-superclass:MAXWrapper - 0:0 - classID: #(2059782884, -1874176333)

See Also
PositionReactor interfaces: (p. 496)

PositionSpring - superclass: PositionController

PositionSpring - superclass: PositionController; super-superclass:MAXWrapper - 8:1 - classID: #(2036956458, -222780984) Constructor:
PositionSpring ...

Properties:
<PositionSpring>.effectHow number; Abs_Rel <PositionSpring>.forceNode Force_Nodes; SubAnim <PositionSpring>.steps <PositionSpring>.x_effect float Integer ArrayParameter Integer Float default: 1 default: #() default: 2 -default: 100.0 --radio button node array; integer -- animatable;

These settings let you control the percentage of the effect on the individual world axes. Default=100. Range=0 to 200.

322

Chapter 1

Whats New in 3ds max 4 MAXScript

<PositionSpring>.y_effect float

Float

default: 100.0

--

animatable;

These settings let you control the percentage of the effect on the individual world axes. Default=100. Range=0 to 200.
<PositionSpring>.z_effect float Float default: 100.0 -animatable;

These settings let you control the percentage of the effect on the individual world axes. Default=100. Range=0 to 200.See Also
<PositionSpring>.start <PositionSpring>.position point3 Integer Point3 default: 0 -- integer; Start_Frame default: [0,0,0] -- animatable;

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

PSpawnflector - superclass: SpacewarpObject

PSpawnflector - superclass: SpacewarpObject; super-superclass:node - 22:0 - classID: #(1318347405, 1313044340) Constructor:
PSpawnflector ...

Properties:
<PSpawnflector>.time on Integer default: 0 -- animatable; integer; Time_On <PSpawnflector>.time off Integer default: 16000 -animatable; integer; Time_Off <PSpawnflector>.affects Float default: 10000.0 -animatable; percentage; Reflects; Controller Scaling: (1 : 100.0) <PSpawnflector>.bounce Float default: 1.0 -- animatable; float <PSpawnflector>.bouncevar Float default: 0.0 -- animatable; percentage; Bounce_Variation; Controller Scaling: (1 : 100.0) <PSpawnflector>.chaos Float default: 0.0 -- animatable; percentage; Controller Scaling: (1 : 100.0)

Reflection - superclass: MAXObject

323

<PSpawnflector>.inheritVelocity Float default: 1.0 -- animatable; float; Velocity_Inheritance <PSpawnflector>.refracts Float default: 100.0 -animatable; percentage; Controller Scaling: (1 : 100.0) <PSpawnflector>.deceleration Float default: 1.0 -- animatable; float <PSpawnflector>.decel var Float default: 0.0 -- animatable; percentage; Deceleration_Variation; Controller Scaling: (1 : 100.0) <PSpawnflector>.refraction Float default: 50.0 -animatable; percentage; Distortion; Controller Scaling: (1 : 100.0) <PSpawnflector>.refraction var Float default: 0.0 -- animatable; percentage; Distortion_Variation; Controller Scaling: (1 : 100.0) <PSpawnflector>.diffusion Float default: 0.0 -- animatable; percentage; Controller Scaling: (1 : 100.0) <PSpawnflector>.diffusion var Float default: 0.0 -- animatable; percentage; Diffusion_Variation; Controller Scaling: (1 : 100.0) <PSpawnflector>.width Float default: 0.0 -- animatable; float <PSpawnflector>.height Float default: 0.0 -- animatable; float <PSpawnflector>.spawn Float default: 100.0 -animatable; percentage; Spawn_Percentage; Controller Scaling: (1 : 100.0) <PSpawnflector>.pass velocity Float default: 1.0 -- animatable; float; Pass_Velocity <PSpawnflector>.passvel var Float default: 0.0 -- animatable; percentage; Pass_Velocity_Variation; Controller Scaling: (1 : 100.0) <PSpawnflector>.friction Float default: 0.0 -- animatable; percentage; Controller Scaling: (1 : 100.0) <PSpawnflector>.quality Integer default: 20 -- animatable; integer; Collision_Quality <PSpawnflector>.collider UndefinedClass default: undefined -- max object; Collision_Quality

Reflection - superclass: MAXObject

Reflection - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(6, 0) Constructor:
Reflection ...

Properties:
<Reflection>.enabled <Reflection>.filterOn FilteringOn BooleanClass BooleanClass default: true default: true --boolean boolean;

Shows whether the element is enabled.

Shows whether the active antialiasing filter is enabled for the element.

324

Chapter 1

Whats New in 3ds max 4 MAXScript

<Reflection>.elementName

String

default: Reflection

--

string

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<Reflection>.bitmap UndefinedClass default: undefined -bitmap

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored_Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self_Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

reflectionRenderElement - superclass: MAXObject

reflectionRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(6, 0) Constructor:
reflectionRenderElement ...

Properties:
<reflectionRenderElement>.enabled boolean BooleanClass default: true --

Shows whether the element is enabled.

reflectionRenderElement - superclass: MAXObject

325

<reflectionRenderElement>.filterOn boolean; FilteringOn <reflectionRenderElement>.elementName Reflection -- string

BooleanClass

default: true

--

Shows whether the active antialiasing filter is enabled for the element.
String default:

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<reflectionRenderElement>.bitmap - bitmap UndefinedClass default: undefined -

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored_Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self_Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

326

Chapter 1

Whats New in 3ds max 4 MAXScript

Refraction - superclass: MAXObject

Refraction - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(7, 0) Constructor:
Refraction ...

Properties:
<Refraction>.enabled <Refraction>.filterOn FilteringOn <Refraction>.elementName BooleanClass BooleanClass default: true default: true --boolean boolean;

Shows whether the element is enabled.

Shows whether the active antialiasing filter is enabled for the element.
String default: Refraction -string

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<Refraction>.bitmap UndefinedClass default: undefined -bitmap

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored_Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) refractionRenderElement - superclass: MAXObject (p. 327) Self_Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

refractionRenderElement - superclass: MAXObject

327

refractionRenderElement - superclass: MAXObject

refractionRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(7, 0) Constructor:
refractionRenderElement ...

Properties:
<refractionRenderElement>.enabled boolean BooleanClass default: true --

Shows whether the element is enabled.

<refractionRenderElement>.filterOn boolean; FilteringOn <refractionRenderElement>.elementName Refraction -- string BooleanClass default: true --

Shows whether the active antialiasing filter is enabled for the element.
String default:

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<refractionRenderElement>.bitmap - bitmap UndefinedClass default: undefined -

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored_Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) Self_Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332)

328

Chapter 1

Whats New in 3ds max 4 MAXScript

Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

RingWave - superclass: GeometryClass

RingWave - superclass: GeometryClass; super-superclass:node - 26:0 - classID: #(686038884, 306926354)

RotationList - superclass: RotationController

RotationList - superclass: RotationController; super-superclass:MAXWrapper - 1:1 - classID: #(1263210499, 0) Constructor:
RotationList ...

Properties:
<RotationList>.available Quat default: (quat 0 0 0 1) -animatable; quat

See Also
RotationList interfaces: (p. 510)

RotationReactor - superclass: RotationController

RotationReactor - superclass: RotationController; super-superclass:MAXWrapper - 0:0 - classID: #(713503979, 1475640742)

See Also
RotationReactor interfaces: (p. 512)

ScaleList - superclass: ScaleController

ScaleList - superclass: ScaleController; super-superclass:MAXWrapper - 1:1 - classID: #(1263210500, 0) Constructor:
ScaleList ...

Properties:
<ScaleList>.available Point3 default: [0,0,0] -animatable; point3

See Also
ScaleList interfaces: (p. 517)

ScaleReactor - superclass: ScaleController

329

ScaleReactor - superclass: ScaleController

ScaleReactor - superclass: ScaleController; super-superclass:MAXWrapper - 0:0 - classID: #(331629852, 751514504)

See Also
ScaleReactor interfaces: (p. 519)

SDynaflector - superclass: SpacewarpObject

SDynaflector - superclass: SpacewarpObject; super-superclass:node - 19:0 - classID: #(1147744028, 332006682) Constructor:
...

Properties:
<SDynaflector>.time on Time_On <SDynaflector>.time off Time_Off Integer default: 0 -animatable; integer;

Integer

default: 16000

--

animatable; integer;

<SDynaflector>.affects Float default: 10000.0 Reflects; Controller Scaling: (1 : 100.0) <SDynaflector>.bounce Float default: 1.0 --

--

animatable; percentage;

animatable; float -animatable; percentage;

<SDynaflector>.bouncevar Float default: 0.0 Bounce_Variation; Controller Scaling: (1 : 100.0) <SDynaflector>.chaos Float Controller Scaling: (1 : 100.0) <SDynaflector>.inheritVelocity Velocity_Inheritance <SDynaflector>.radius <SDynaflector>.mass Particle_Mass Float Float default: 0.0 --

animatable; percentage;

Float

default: 1.0

--

animatable; float;

default: 0.0 default: 1.0 --

--

animatable; float animatable; float;

<SDynaflector>.mass units Particle_Mass_Units <SDynaflector>.force in x Force_in_X_Direction

Integer

default: 0

--

radio button number;

Float

default: 0.0

--

animatable; float;

330

Chapter 1

Whats New in 3ds max 4 MAXScript

<SDynaflector>.force in y Force_in_Y_Direction <SDynaflector>.force in z Force_in_Z_Direction <SDynaflector>.apply at x Apply_at_X_location <SDynaflector>.apply at y Apply_at_Y_location <SDynaflector>.apply at z Apply_at_Z_location <SDynaflector>.number Number_of_Particles

Float

default: 0.0

--

animatable; float;

Float

default: 0.0

--

animatable; float;

Float

default: 0.0

--

animatable; float;

Float

default: 0.0

--

animatable; float;

Float

default: 0.0

--

animatable; float;

Integer

default: 0

--

animatable; integer;

<SDynaflector>.friction Float Controller Scaling: (1 : 100.0) <SDynaflector>.collider Friction

default: 0.0

--

animatable; percentage;

UndefinedClass

default: undefined

--

max object;

section - superclass: shape

section - superclass: shape; super-superclass:node - 13:0 - classID: #(549004141, 1725569194) Constructor:
section ...

Properties:
<section>.angle <section>.renderable <section>.mapCoords <section>.thickness <section>.sides <section>.viewport_thickness <section>.viewport_sides <section>.viewport_angle <section>.DisplayRenderMesh <section>.UseViewportSettings <section>.DisplayRenderSettings Float BooleanClass BooleanClass Float Float Float Integer Float BooleanClass BooleanClass BooleanClass default: default: default: default: default: default: default: default: default: default: default: 0.0 -- float false -- boolean false -- boolean 1.0 -- float 12.0 -- integer 1.0 -- float 12 -- integer 0.0 -- float false -- boolean false -- boolean true -- boolean

Notes: Setting to false wont take if <shape>.useViewportSettings or <shape>.displayRenderMesh is false. This matches the behavior in the UI where the Viewport option is disabled in this case.

Self_Illumination - superclass: MAXObject

331

Self_Illumination - superclass: MAXObject

Self_Illumination - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(5, 0) Constructor:
Self_Illumination ...

Properties:
<Self_Illumination>.enabled <Self_Illumination>.filterOn FilteringOn <Self_Illumination>.elementName Illumination -- string BooleanClass BooleanClass default: true default: true --boolean boolean;

Shows whether the element is enabled.

Shows whether the active antialiasing filter is enabled for the element.
String default: Self-

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<Self_Illumination>.bitmap bitmap UndefinedClass default: undefined --

See Also
LOOKS THE SAME AS emissionRenderElement - superclass: MAXObject (p. 285) Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored_Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) ShadowRenderElement - superclass: MAXObject (p. 332)

332

Chapter 1

Whats New in 3ds max 4 MAXScript

Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

ShadowRenderElement - superclass: MAXObject

ShadowRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(8, 0) Constructor:
ShadowRenderElement ...

Properties:
<ShadowRenderElement>.enabled boolean BooleanClass default: true --

Shows whether the element is enabled.

<ShadowRenderElement>.filterOn boolean; FilteringOn <ShadowRenderElement>.elementName string BooleanClass default: true --

Shows whether the active antialiasing filter is enabled for the element.
String default: Shadow --

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<ShadowRenderElement>.bitmap bitmap UndefinedClass default: undefined --

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored_Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326)

sliderManipulator - superclass: helper

333

refractionRenderElement - superclass: MAXObject (p. 327) Self_Illumination - superclass: MAXObject (p. 331) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)

sliderManipulator - superclass: helper

sliderManipulator - superclass: helper; super-superclass:node - 10:0 - classID: #(1205540079, 1318803856) Constructor:
sliderManipulator ...

Properties:
<sliderManipulator>.value <sliderManipulator>.minVal <sliderManipulator>.maxVal Float Float Float default: 0.0 default: 0.0 default: 100.0 ---animatable; float animatable; float animatable; float

The value of the slider, based on the position of the slidable triangle. Default=0.0. The minimum possible value of the slider. Default=0.0. The maximum possible value of the slider. Default=100.0. When the minimum is 0.0 and the maximum is 100.0, the slider Value can represent a percentage.
<sliderManipulator>.xPos Float default: 0.0 -float

The sliders X location in the active viewport. Default=Viewport X location you clicked when you created the slider.
<sliderManipulator>.yPos Float default: 0.0 -float

The sliders Y location in the active viewport. Default=Viewport Y location you clicked when you created the slider.
<sliderManipulator>.width <sliderManipulator>.hide Float default: 100.0 --float boolean

The sliders width, in 3ds max units. Default=100.0.

BooleanClass default: false

When on, hides all of the slider except for the label and the move and show/hide components. Default=off.
<sliderManipulator>.sldName String default: ---string boolean float

The slider label that appears in viewports. Default=none.

<sliderManipulator>.snapToggle BooleanClass default: true <sliderManipulator>.snapVal Float default: 0.01

When on, the slider snaps to incremental values. When off, Default=on. The increment used by the slider when Snap is on. Default=0.01.

334

Chapter 1

Whats New in 3ds max 4 MAXScript

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

Specular - superclass: MAXObject

Specular - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(2, 0) Constructor:
Specular ...

Properties:
<Specular>.enabled <Specular>.filterOn FilteringOn <Specular>.elementName BooleanClass BooleanClass default: true default: true --boolean boolean;

Shows whether the element is enabled.

Shows whether the active antialiasing filter is enabled for the element.
String default: Specular -string

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<Specular>.bitmap UndefinedClass default: undefined -bitmap

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265)

specularRenderElement - superclass: MAXObject

335

BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored_Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self_Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) specularRenderElement - superclass: MAXObject (p. 335)

specularRenderElement - superclass: MAXObject

specularRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(2, 0) Constructor:
specularRenderElement ...

Properties:
<specularRenderElement>.enabled boolean BooleanClass default: true --

Shows whether the element is enabled.

<specularRenderElement>.filterOn boolean; FilteringOn <specularRenderElement>.elementName string BooleanClass default: true --

Shows whether the active antialiasing filter is enabled for the element.
String default: Specular --

Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected.
<specularRenderElement>.bitmap bitmap UndefinedClass default: undefined --

336

Chapter 1

Whats New in 3ds max 4 MAXScript

See Also
Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored_Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self_Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement_superclass_MAXObject

SpringPoint3Controller - superclass: Point3Controller

SpringPoint3Controller - superclass: Point3Controller; super-superclass:MAXWrapper - 4:4 - classID: #(327754098, 1754751609) Constructor:
SpringPoint3Controller ...

Properties:
<SpringPoint3Controller>.position point3 <SpringPoint3Controller>.x_effect Point3 Float default: [0,0,0] default: 100.0 -animatable;

These settings let you control the percentage of the effect on the individual world axes. Default=100. Range=0 to 200.
<SpringPoint3Controller>.y_effect Float default: 100.0

These settings let you control the percentage of the effect on the individual world axes. Default=100. Range=0 to 200.

SpringPositionController - superclass: PositionController

337

<SpringPoint3Controller>.z_effect

Float

default: 100.0

These settings let you control the percentage of the effect on the individual world axes. Default=100. Range=0 to 200.See Also

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

SpringPositionController - superclass: PositionController

SpringPositionController - superclass: PositionController; super-superclass:MAXWrapper - 8:1 classID: #(2036956458, -222780984) Constructor:
SpringPositionController ...

Properties:
<SpringPositionController>.effectHow button number; Abs_Rel <SpringPositionController>.forceNode array; Force_Nodes; SubAnim <SpringPositionController>.steps <SpringPositionController>.x_effect animatable; float Integer ArrayParameter Integer Float default: 1 default: #() default: 2 -default: 100.0 --radio node integer --

These settings let you control the percentage of the effect on the individual world axes. Default=100. Range=0 to 200.
<SpringPositionController>.y_effect animatable; float Float default: 100.0 --

These settings let you control the percentage of the effect on the individual world axes. Default=100. Range=0 to 200.
<SpringPositionController>.z_effect animatable; float Float default: 100.0 --

These settings let you control the percentage of the effect on the individual world axes. Default=100. Range=0 to 200.See Also

338

Chapter 1

Whats New in 3ds max 4 MAXScript

<SpringPositionController>.start Start_Frame <SpringPositionController>.position animatable; point3

Integer Point3

default: 0

--

integer; --

default: [0,0,0]

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

SSpawnflector - superclass: SpacewarpObject

SSpawnflector - superclass: SpacewarpObject; super-superclass:node - 20:0 - classID: #(1700857802, 522734191) Constructor:
SSpawnflector ...

Properties:
<SSpawnflector>.time on Time_On <SSpawnflector>.time off integer; Time_Off Integer default: 0 -animatable; integer;

Integer

default: 16000

--

animatable;

<SSpawnflector>.affects Float default: 10000.0 Reflects; Controller Scaling: (1 : 100.0) <SSpawnflector>.bounce Float default: 1.0 --

--

animatable; percentage;

animatable; float -animatable; percentage;

<SSpawnflector>.bouncevar Float default: 0.0 Bounce_Variation; Controller Scaling: (1 : 100.0) <SSpawnflector>.chaos Float Controller Scaling: (1 : 100.0) <SSpawnflector>.inheritVelocity Velocity_Inheritance default: 0.0 --

animatable; percentage;

Float

default: 1.0

--

animatable; float;

transform_script - superclass: Matrix3Controller

339

<SSpawnflector>.refracts Float Controller Scaling: (1 : 100.0) <SSpawnflector>.deceleration Float

default: 100.0

--

animatable; percentage;

default: 1.0

--

animatable; float

<SSpawnflector>.decel var Float default: 0.0 -- animatable; percentage; Deceleration_Variation; Controller Scaling: (1 : 100.0) <SSpawnflector>.refSraction Float default: 50.0 percentage; Distortion; Controller Scaling: (1 : 100.0) -animatable;

<SSpawnflector>.refraction var Float default: 0.0 -- animatable; percentage; Distortion_Variation; Controller Scaling: (1 : 100.0) <SSpawnflector>.diffusion Float Controller Scaling: (1 : 100.0) default: 0.0 -animatable; percentage;

<SSpawnflector>.diffusion var Float default: 0.0 -- animatable; percentage; Diffusion_Variation; Controller Scaling: (1 : 100.0) <SSpawnflector>.radius Float default: 0.0 --animatable; float animatable; percentage;

<SSpawnflector>.spawn Float default: 100.0 Spawn_Percentage; Controller Scaling: (1 : 100.0) <SSpawnflector>.pass velocity Pass_Velocity Float

default: 1.0

--

animatable; float;

<SSpawnflector>.passvel var Float default: 0.0 -- animatable; percentage; Pass_Velocity_Variation; Controller Scaling: (1 : 100.0) <SSpawnflector>.friction Float Controller Scaling: (1 : 100.0) <SSpawnflector>.collider object; Friction default: 0.0 -animatable; percentage;

UndefinedClass

default: undefined

--

max

transform_script - superclass: Matrix3Controller

transform_script - superclass: Matrix3Controller; super-superclass:MAXWrapper - 1:0 - classID: #(2136360284, 468085864) The Transform Script controller contains all of the information contained in a Position/Rotation/ Scale (PRS) controller in one scripted matrix value. Instead of having three separate tracks for position, rotation, and scale, all three values can be simultaneously accessed from one script controller dialog. Because the transform values are defined by a script, they are easier to animate. The value of the controller script must be a matrix3 value. A matrix3 value is a 4x3 3D transformation matrix. For more information, see the Matrix3 Values topic in the MAXScript reference.

340

Chapter 1

Whats New in 3ds max 4 MAXScript

The software interprets the text you type into the Script text box as the body of a MAXScript block expression. You can type as many expressions as you want on as many lines as you want, and they are evaluated in turn. The value of the last expression is taken as the controller value. This must yield a matrix3 value for Transform Script controllers. Since the text is inside a block expression, you can declare local variables which are visible only within the script and are temporary for one evaluation. You can also declare or access global variables that are shared with all other scripts in MAXScript and hold their values from one evaluation to the next. A controller is always evaluated by the software with respect to a specific animation time. This might be the current time slider or incrementing frame time if an animation is playing, or a rendering is under way. In the case of Script controllers, the time being evaluated is used to establish an automatic at time context around the controller script, so any properties you access (outside of other explicit at time expressions) yield the correct values for the current controller evaluation time. This means you dont have to do anything special in your scripts to work at the correct time. You can access the evaluation time, with the standard MAXScript variable, current Time. You can also reference scene property values at other times by using at time expressions in your scripts, as in regular MAXScript programming. Constructor:
transform_script ...

Properties:
<transform_script>.script String default: (matrix3 1)

See Also
Script Controllers (p. 1329)

Turn_to_Mesh - superclass: modifier

Turn_to_Mesh - superclass: modifier; super-superclass:MAXWrapper - 4:0 - classID: #(1549488375, 1614380193) Constructor:
Turn_to_Mesh ...

Properties:
<Turn_to_Mesh>.useInvisibleEdges BooleanClass animatable; boolean; Use_Invisible_Edges default: true --

When on, uses invisible edges to represent polygons. When off, produces a completely triangulated mesh with all visible edges. Default=on.

Turn_to_Mesh - superclass: modifier

341

<Turn_to_Mesh>.selectionConversion Selection_Conversion <Turn_to_Mesh>.useSoftSelection Use_Soft_Selection

Integer

default: 0

--

integer; -boolean;

BooleanClass

default: true

Affects the action of sub-object Move, Rotate, and Scale functions. When these are on, 3D Studio MAX applies a spline curve deformation to unselected vertices surrounding the transformed selected sub-object. This provides a magnet-like effect, with a sphere of influence around the transformation. Use this when you want to preserve the soft selection from beneath. For example, if Use Soft Selection is on when you select vertices on an editable poly, and you apply Turn To Mesh with Include Soft Selection on, then the same soft selection will apply to the mesh vertices. Default=on. For more information, see Soft Selection Rollout. Important: Be aware that when Include Soft Selection is on, bound vertices can turn to meshes.
<Turn_to_Mesh>.selectionLevel Selection_Level Integer default: 0 -integer;

From Pipeline: Uses the equivalent of whatever the input object uses. (Patch level becomes face level, and so on.). For example, if you create a box, convert it to an editable patch in patch mode and apply a Turn To Mesh modifier to it, 3ds max passes a sub-object selection in patch mode up the stack. The Turn To Mesh modifier takes the sub-object patch selection into account and selects the mesh faces that derive from the patch selection. Object: Uses object as the selection level for passing up the rest of the stack. Edge: Uses edge as the sub-object selection level for passing up the rest of the stack. Vertex: Uses vertex as the sub-object selection level for passing up the rest of the stack. Face: Uses face as the sub-object selection level for passing up the rest of the stack.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

342

Chapter 1

Whats New in 3ds max 4 MAXScript

Turn_to_Patch - superclass: modifier

Turn_to_Patch - superclass: modifier; super-superclass:MAXWrapper - 4:0 - classID: #(1011577041, 590161861) Constructor:
Turn_to_Patch ...

Properties:
<Turn_to_Patch>.quadsToQuads BooleanClass animatable; boolean; Quads_to_Quad_Patches default: true --

Turns quad faces in meshes or polymeshes into quad patches. Note: When you turn this option off, 3ds max triangulates quads when the Turn To Patch modifier is applied to a patch object.
<Turn_to_Patch>.selectionConversion Selection_Conversion <Turn_to_Patch>.useSoftSelection Use_Soft_Selection Integer Integer default: 0 default: 1 --integer; integer;

Affects the action of sub-object Move, Rotate, and Scale functions. When these are on, 3D Studio MAX applies a spline curve deformation to unselected vertices surrounding the transformed selected sub-object. This provides a magnet-like effect, with a sphere of influence around the transformation. Use this when you want to preserve the soft selection from beneath. For example, if Use Soft Selection is on when you select vertices on an editable poly, and you apply Turn To Mesh with Include Soft Selection on, then the same soft selection will apply to the mesh vertices. Default=on. For more information, see Soft Selection Rollout. Important: Be aware that when Include Soft Selection is on, bound vertices can turn to meshes.
<Turn_to_Patch>.selectionLevel Selection_Level Integer default: 0 -integer;

From Pipeline: Uses the equivalent of whatever the input object uses. (Patch level becomes face level, and so on.). For example, if you create a box, convert it to an editable mesh in face mode and apply a Turn To Patch modifier to it, 3ds max passes a sub-object selection in face mode up the stack. The Turn To Patch modifier takes the sub-object face selection into account and selects the patches that derive from the face selection. Object: Uses object as the selection level for passing up the rest of the stack. Edge: Uses edge as the sub-object selection level for passing up the rest of the stack. Vertex: Uses vertex as the sub-object selection level for passing up the rest of the stack. Face: Uses face as the sub-object selection level for passing up the rest of the stack.

Turn_to_Poly - superclass: modifier

343

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Turn_to_Poly - superclass: modifier

Turn_to_Poly - superclass: modifier; super-superclass:MAXWrapper - 9:0 - classID: #(793333328, 1547135298) Constructor:
Turn_to_Poly ...

Properties:
<Turn_to_Poly>.keepConvex animatable; boolean; Keep_Convex BooleanClass default: false --

Does not join across edges if the resulting polygon would not be convex. Convex means that you can connect any two points in the polygon with a line that doesnt go outside the polygon. A polygon is not convex if you can draw a line between vertices and that line lays outside of the polygon. Problems that can occur with non-convex polygons include the fact that changes in the geometry of the input object can result in a different topology for the Turn To Poly result. For instance, in a box, if you drag one of the top corners across the middle of the top face, the box becomes non-convex. Turn To Poly would then see this as two triangles instead of one quad, and the number of points in the result would change.
<Turn_to_Poly>.limitPolySize BooleanClass animatable; boolean; Limit_Polygon_Size default: false --

Limits the number of sides to a polygon so that the surface is better defined. For example, you might want to produce a polymesh of triangles and quads, or one composed of all triangles, rather than joining together more than two triangles into pentagons, hexagons, and so on.
<Turn_to_Poly>.maxPolySize integer; Max_Polygon_Size Integer default: 4 -animatable;

The maximum number of sides to a polygon.

<Turn_to_Poly>.requirePlanar BooleanClass animatable; boolean; Require_Planar_Polygons default: false --

Creates polygons composed of flat planes. Does not join faces together across an edge if the edge has a sharper angle than the threshold listed.
<Turn_to_Poly>.planarThresh Float default: 15.0 -animatable; angle; Planar_Threshold; Controller Scaling: (1 : 57.2958)

Controls the threshold of the angle between polygonal planes.

<Turn_to_Poly>.removeMidEdgeVertices Remove_Mid_Edge_Vertices BooleanClass default: true -boolean;

344

Chapter 1

Whats New in 3ds max 4 MAXScript

<Turn_to_Poly>.selectionConversion Selection_Conversion <Turn_to_Poly>.useSoftSelection Use_Soft_Selection

Integer BooleanClass

default: 0 default: true

--

integer; -boolean;

Affects the action of sub-object Move, Rotate, and Scale functions. When these are on, 3ds max applies a spline curve deformation to unselected vertices surrounding the transformed selected sub-object. This provides a magnet-like effect, with a sphere of influence around the transformation. Use this when you want to preserve the soft selection from beneath. For example, if Use Soft Selection is on when you select vertices on an editable mesh, and you apply Turn To Poly with Include Soft Selection on, then the same soft selection will apply to the polymesh vertices. Default=on. Important: Be aware that when Include Soft Selection is on, bound vertices can turn to meshes. For more information, see Soft Selection Rollout
<Turn_to_Poly>.selectionLevel Selection_Level Integer default: 0 -integer;

These options set the sub-object selection level for passing up the rest of the stack. From Pipeline: Uses the equivalent of whatever the input object uses. (Patch level becomes face level, and so on.). For example, if you create a box, convert it to an editable mesh in face mode and apply a Turn To Poly modifier to it, 3ds max passes a sub-object selection in face mode up the stack. The Turn To Poly modifier takes the sub-object face selection into account and selects the polygons that derive from the face selection. Object: Uses object as the selection level for passing up the rest of the stack. Edge: Uses edge as the sub-object selection level for passing up the rest of the stack. Vertex: Uses vertex as the sub-object selection level for passing up the rest of the stack. Face: Uses face as the sub-object selection level for passing up the rest of the stack.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

UDynaDeflector - superclass: SpacewarpObject

345

UDynaDeflector - superclass: SpacewarpObject

UDynaDeflector - superclass: SpacewarpObject; super-superclass:node - 19:0 - classID: #(1750561194, 1736524989) Constructor:
...

Properties:
<UDynaDeflector>.time on Time_On <UDynaDeflector>.time off integer; Time_Off Integer default: 0 -animatable; integer;

Integer

default: 1600000

--

animatable;

<UDynaDeflector>.affects Float default: 10000.0 Reflects; Controller Scaling: (1 : 100.0) <UDynaDeflector>.bounce Float default: 1.0 --

--

animatable; percentage;

animatable; float -animatable; percentage;

<UDynaDeflector>.bouncevar Float default: 0.0 Bounce_Variation; Controller Scaling: (1 : 100.0) <UDynaDeflector>.chaos Float Controller Scaling: (1 : 100.0) <UDynaDeflector>.friction Float Controller Scaling: (1 : 100.0) <UDynaDeflector>.inheritVelocity Velocity_Inheritance <UDynaDeflector>.radius <UDynaDeflector>.mass Particle_Mass Float Float default: 0.0 --

animatable; percentage;

default: 0.0

--

animatable; percentage;

Float

default: 1.0

--

animatable; float;

default: 0.0 default: 1.0

---

animatable; float; Icon_Size animatable; float;

<UDynaDeflector>.mass units Particle_Mass_Units <UDynaDeflector>.force in x Force_in_X_Direction <UDynaDeflector>.force in y Force_in_Y_Direction <UDynaDeflector>.force in z Force_in_Z_Direction

Integer

default: 0

--

radio button number;

Float

default: 0.0

--

animatable; float;

Float

default: 0.0

--

animatable; float;

Float

default: 0.0

--

animatable; float;

346

Chapter 1

Whats New in 3ds max 4 MAXScript

<UDynaDeflector>.apply at x Apply_at_X_location <UDynaDeflector>.apply at y Apply_at_Y_location <UDynaDeflector>.apply at z Apply_at_Z_location <UDynaDeflector>.number Number_of_Particles <UDynaDeflector>.collider Friction

Float

default: 0.0

--

animatable; float;

Float

default: 0.0

--

animatable; float;

Float

default: 0.0

--

animatable; float;

Integer

default: 20

--

animatable; integer;

UndefinedClass

default: undefined

--

max object;

USpawnDeflector - superclass: SpacewarpObject

USpawnDeflector - superclass: SpacewarpObject; super-superclass:node - 20:0 - classID: #(436029718, 1434415577) Constructor:
...

Properties:
<USpawnDeflector>.time on Time_On <USpawnDeflector>.time off integer; Time_Off Integer default: 0 -animatable; integer;

Integer

default: 16000

--

animatable;

<USpawnDeflector>.affects Float default: 10000.0 percentage; Reflects; Controller Scaling: (1 : 100.0) <USpawnDeflector>.bounce Float default: 1.0 --

--

animatable;

animatable; float

<USpawnDeflector>.bouncevar Float default: 0.0 -- animatable; percentage; Bounce_Variation; Controller Scaling: (1 : 100.0) <USpawnDeflector>.chaos Float Controller Scaling: (1 : 100.0) <USpawnDeflector>.friction Float Controller Scaling: (1 : 100.0) <USpawnDeflector>.inheritVelocity float; Velocity_Inheritance default: 0.0 -animatable; percentage;

default: 0.0

--

animatable; percentage;

Float

default: 1.0

--

animatable;

<USpawnDeflector>.refracts Float default: 100.0 percentage; Controller Scaling: (1 : 100.0)

--

animatable;

UVWUnwrap - superclass: modifier

347

<USpawnDeflector>.deceleration

Float

default: 1.0

--

animatable; float

<USpawnDeflector>.decel var Float default: 0.0 -- animatable; percentage; Deceleration_Variation; Controller Scaling: (1 : 100.0) <USpawnDeflector>.refraction Float default: 50.0 percentage; Distortion; Controller Scaling: (1 : 100.0) -animatable;

<USpawnDeflector>.refraction var Float default: 0.0 -percentage; Distortion_Variation; Controller Scaling: (1 : 100.0) <USpawnDeflector>.diffusion Float default: 0.0 percentage; Controller Scaling: (1 : 100.0) --

animatable;

animatable;

<USpawnDeflector>.diffusion var Float default: 0.0 -percentage; Diffusion_Variation; Controller Scaling: (1 : 100.0) <USpawnDeflector>.radius Icon_Size Float default: 0.0 --

animatable;

animatable; float;

<USpawnDeflector>.spawn Float default: 100.0 Spawn_Percentage; Controller Scaling: (1 : 100.0) <USpawnDeflector>.pass velocity float; Pass_Velocity Float

--

animatable; percentage;

default: 1.0

--

animatable;

<USpawnDeflector>.passvel var Float default: 0.0 -- animatable; percentage; Pass_Velocity_Variation; Controller Scaling: (1 : 100.0) <USpawnDeflector>.collider object; Friction UndefinedClass default: undefined -max

UVWUnwrap - superclass: modifier

UVWUnwrap - superclass: modifier; super-superclass:MAXWrapper - 0:0 - classID: #(48180794, 1924812319) UVWUnwrap interfaces: (p. 568)

Vortex - superclass: SpacewarpObject

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

348

Chapter 1

Whats New in 3ds max 4 MAXScript

Constructor:
Vortex ...

Properties:
<Vortex>.time on <Vortex>.time off integer; Time_Off <Vortex>.axialstrength Axial_Drop_Strength <Vortex>.axialrange float; Axial_Range Integer Integer default: 0 -integer; Time_On -animatable;

The frame numbers at which the space warp becomes active and becomes inactive.
default: 16000

The frame numbers at which the space warp becomes active and becomes inactive.
Float default: 0.1 -animatable; float;

Specifies how quickly particles move in the direction of the drop axis.
Float default: 100.0 -animatable;

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; Axial_Falloff Float default: 1000.0 -animatable;

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 -percentage; Axial_Damping; Controller Scaling: (1 : 100.0) animatable;

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 Orbital_Speed_Strength <Vortex>.rotationrange float; Orbital_Range Float default: 0.5 -animatable; float;

Specifies how quickly the particles rotate.

Float default: 100.0 -animatable;

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; Orbital_Falloff Float default: 1000.0 -animatable;

Specifies the distance beyond the Orbital Range within which Orbital Damping is applied. Orbital Damping is strongest at the Range distance, decreases linearly out to the limit of the Orbital Falloff, and has no effect beyond that. Takes effect only when Unlimited Range is turned off.

Vortex - superclass: SpacewarpObject

349

<Vortex>.rotationdamping Float default: 5.0 -percentage; Orbital_Damping; Controller Scaling: (1 : 100.0)

animatable;

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 Radial_Pull_Strength <Vortex>.radialrange float; Radial_Range Float default: 0.5 -animatable; float;

Specifies the distance from the drop axis at which the particles rotate.
Float default: 100.0 -animatable;

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; Radial_Falloff Float default: 1000.0 -animatable;

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 -percentage; Radial_Damping; Controller Scaling: (1 : 100.0) animatable;

Controls the degree to which Radial Pull is restrained per frame. Default=5.0. Range=0 to 100.
<Vortex>.taperstrength float; Taper_Length Float default: 100.0 -animatable;

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 Taper_Curve Float default: 1.0 -animatable; float;

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 <Vortex>.rangeless Unlimited_Range Integer BooleanClass default: 0 default: true -radio button number -boolean;

Determines whether particles rotate clockwise or counterclockwise.

When on, Vortex exerts full damping strength over an unlimited range. When off, the Range and Falloff settings take effect.
<Vortex>.iconsize Float default: 10.0 -float; Icon_Size

Specifies the size of the icon. Example:

Vortex time on:0 time off:16000 axialstrength:0.1 axialrange:100 axialfalloff:1000 axialdamping:5 rotationstrength:0.5 rotationrange:100 rotationfalloff:1000 rotationdamping:5 radialstrength:0.5 radialrange:100 radialfalloff:1000 radialdamping:5 taperstrength:100 tapershape:1 direction:0 rangeless:on pos:[32.5437,-58.2321,0] isSelected:on iconSize:25.8103

350

Chapter 1

Whats New in 3ds max 4 MAXScript

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

Z_Depth - superclass: MAXObject

Z_Depth - superclass: MAXObject; super-superclass:Value - 6:0 - classID: #(12, 0) Constructor:
Z_Depth ...

Properties:
<Z_Depth>.enabled <Z_Depth>.filterOn BooleanClass BooleanClass default: true default: true --boolean boolean; FilteringOn

Shows whether the element is enabled. When on, applies the active antialiasing filter to the rendered element. When off, the rendered element does not use the antialiasing filter. Default=on. The Filter Enabled column of the elements list shows whether or not the filter is enabled for an element. You choose the antialiasing filter in the Anti-Aliasing group of the MAX Default Scanline A-Buffer rollout. Disabling antialiasing can improve rendering time, although the rendered element that results might appear jagged.
<Z_Depth>.elementName String default: Z Depth -string

Shows the name of the element. You can change the default name of elements, in the Selected Element Parameters group. To select an element, click its name in the list. Use CTRL+click to select additional elements, or SHIFT+click to select a contiguous group of additional elements.
<Z_Depth>.bitmap <Z_Depth>.zMin UndefinedClass Float default: undefined default: 100.0 --- bitmap float; Z_Min

The minimum distance to include in the Z-depth rendering. This is a value in 3ds max units. Default=0.0 (cannot be less than zero).
<Z_Depth>.zMax Float default: 300.0 -float; Z_Max

The maximum distance to include in the Z-depth rendering. This is a value in 3ds max units. Default=100.0.

ZRenderElement - superclass: MAXObject

351

ZRenderElement - superclass: MAXObject

ZRenderElement - superclass: MAXObject; super-superclass:Value - 6:0 - classID: #(12, 0) Constructor:
ZRenderElement ...

Properties:
<ZRenderElement>.enabled <ZRenderElement>.filterOn FilteringOn BooleanClass BooleanClass default: true default: true --boolean boolean;

Shows whether the element is enabled.

When on, applies the active antialiasing filter to the rendered element. When off, the rendered element does not use the antialiasing filter. Default=on. The Filter Enabled column of the elements list shows whether or not the filter is enabled for an element. You choose the antialiasing filter in the Anti-Aliasing group of the MAX Default Scanline A-Buffer rollout. Disabling antialiasing can improve rendering time, although the rendered element that results might appear jagged.
<ZRenderElement>.elementName String default: Z Depth -string

Shows the name of the element. You can change the default name of elements, in the Selected Element Parameters group. To select an element, click its name in the list. Use CTRL+click to select additional elements, or SHIFT+click to select a contiguous group of additional elements.
<ZRenderElement>.bitmap <ZRenderElement>.zMin UndefinedClass Float default: undefined default: 100.0 --- bitmap float; Z_Min

The minimum distance to include in the Z-depth rendering. This is a value in 3ds max units. Default=0.0 (cannot be less than zero).
<ZRenderElement>.zMax Float default: 300.0 -float; Z_Max

The maximum distance to include in the Z-depth rendering. This is a value in 3ds max units. Default=100.0.

352

Chapter 1

Whats New in 3ds max 4 MAXScript

version 4 MAXScript Interfaces Core Interfaces

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

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

Interface: actionMan

353

Core Interface Pages

Interface: actionMan
Action Manager (p. 9) All Action Items are macro recorded when executed. This includes main menus items, CUI buttons, keyboard shortcuts and quad menu items. Prototype:
<boolean>executeAction <integer>tableId <string>persistentId

Parameters:
<integer>tableId <string>persistentId

Return Value: True if successful and false otherwise. Prototype:

<boolean>loadKeyboardFile <string>file

Parameters:
<string>file

Return Value: True if successful and false otherwise. Prototype:

<boolean>saveKeyboardFile <string>file

Parameters:
<string>file

Return Value: True if successful and false otherwise. Prototype:

<string>getKeyboardFile()

Return Value: True if successful and false otherwise.

See Also
Action Manager (p. 9) The Macro Recorder (p. l) Defining Macro Scripts (p. 1521) The MAXScript Listener Window (p. xxxvi)

354

Chapter 1

Whats New in 3ds max 4 MAXScript

Turning On the Listener Log (p. xli) Listener Commands (p. xxxviii)

Interface: BoneSys
Bone Creation (p. 25) Interface: BoneSys Methods: Prototype:
<node>createBone <point3>startPos <point3>endPos <point3>zAxis

Parameters:
<point3>startPos

The location of the new bone as point3

<point3>endPos

The direction (X axis) of the bone and the bone length as point3
<point3>zAxis

The direction of the Z axis for the new bone node as point3 Return Value: It returns the new bone node that was created. Note: If the Z axis is not perpendicular to the X axis, the Z axis will be made perpendicular. To create a bone chain, call createBone repeatedly with the startPosition set to the value of the previous endPosition. Note that newly created bones are not linked to any parent. So to create a bone chain, the script would also need to link each newly created bone segment to the previous.

See Also
Bones : System (p. 991) Core Interfaces (p. 70) Node Common Properties, Operators, and Methods (p. 820) Bone Creation (p. 25) Bone : Helper (p. 978) Skin : Modifier (p. 1157) Access to the new node bone properties and methods (p. 23) Bones_SystemBones_System

Interface: browserMgr

355

Interface: browserMgr
This represents the interface to the Browser Manager. Methods: Prototype:
<Interface>newBrowser <string>rootURL <boolean>showDirectory <boolean>showContent <boolean>showToolbar <boolean>showMenu

Remarks:
This method will create and open a new browser window.

Parameters:
<string>rootURL

The string containing the URL.

<boolean>showDirectory

TRUE to show as a directory, otherwise FALSE.

<boolean>showContent

TRUE to show the content window, otherwise FALSE.

<boolean>showToolbar

TRUE to show the browser toolbar, otherwise FALSE.

<boolean>showMenu

TRUE to show the browser menu, otherwise FALSE. Return Value: An interface to a new browsermgr. Prototype:
<integer>numBrowsers()

Return Value: This method will return the current number of browsers. Prototype:
<Interface>getBrowser <integer>index

Remarks: This method allows you to obtain a pointer to a specific browser. Parameters:
<integer>index

Return Value: An interface to the ith browser.

356

Chapter 1

Whats New in 3ds max 4 MAXScript

See Also
Asset Browser enhancements (p. 22) iDrop - drag and drop (p. 62) Zip-file Script Packages (p. 122)

Interface: cmdPanel
Customize The Order of Rollup Pages (p. 185) Methods: Prototype:
<integer>GetRollupThreshold()

Return Value: Returns how many pixels of a rollout should be scrollable in the command panel before the rollout is shifted into a separate command panel column. This option is only applicable when there are multiple columns displayed in the command panel. Prototype:
<void>SetRollupThreshold <integer>threshold

Remarks: Parameters:
<integer>threshold

See Also
Rollout User-Interface Controls (p. 1481) Rollout User-Interface Controls Types (p. 1484) Rollout User-Interface Controls Common Properties (p. 1481) Rollout User-Interface Controls Common Layout Parameters (p. 1483) Customize The Order of Rollup Pages (p. 185) Visual MAXScript (p. 117)

Interface: colorMan
Color Manager (p. 35) This is an interface to the Color Manager. Within MAX, using the Customize pull down menu/ Customize User Interface choice/Colors tab, a user is able to alter the colors used for various UI elements. They can change the saturation, value and transparency of elements, and load and save color schemes. Prototype:
<boolean>useStandardWindowsColors()

Interface: colorMan

357

Return Value: Returns true if the standard windows colors are used and false if custom colors are used. Prototype:
<void>setUseStandardWindowsColors <boolean>onOff

Remarks: Sets whether standard windows colors are used or not. This allows the developer to tell the system to use standard windows colors, instead of the custom colors. Parameters:
<boolean>onOff

Pass true to use the standard windows color and false to use the custom colors. Prototype:
<boolean>registerColor <string>color <string>name <string>category <point3 by value>defaultColor

Remarks: This registers a new color with the system. This adds a color to the color manager database that is then accessible from the color customization UI. Parameters:
<string>color

The ID of the color to register. Example: #myNewColor

<string>name

The name for the color. Example: My Own Color

<string>category

The category for the color. If the name passed matches one of the existing MAX categories the color will be placed in there, otherwise a new one will be created. Example: Fun Gaming Colors
<point3 by value>defaultColor

The default value for the color. This is the value that the color will be reset to when a MAX user presses Reset in the color customization dialog. Example: [1,0,0] Return Value: Returns false if the color is already registered; otherwise true. Prototype:
<boolean>loadColorFile <string>file

Remarks: This method will load the specified color file from the current UI directory. Parameters:
<string>file

The filename of the color file to load.

358

Chapter 1

Whats New in 3ds max 4 MAXScript

Return Value: TRUE if the load was successful, otherwise FALSE. Prototype:
<boolean>saveColorFile <string>file

Remarks: This method will save the specified color file from the current UI directory. Parameters:
<string>file

The filename of the color file to save. Return Value: TRUE if the save process was successful, otherwise FALSE. Prototype:
<string>getColorFile()

Return Value: This method returns the file name of the current color file. Prototype:
<boolean>setColor <string>color <point3 by value>colorValue

Remarks: Sets the color value of the previously registered color whose ID is passed. Parameters:
<string>color

Specifies which color to set.

<point3 by value>colorValue

The color value to set. Predefined colors include:

#background #text #activeCommand #hilight #shadow #window other windows #activeCaption #toolTipBackground #toolTipText #hilightText #windowText windows #itemHilight #subObjectColor StackView #3dDarkShadow -----------The The The The The The background for all controls and buttons text for all controls and buttons color command mode buttons turn when pressed hilight color for 3d controls shadow color for 3d controls background color for edit boxes, list boxes and

The The The The

background for viewport tool tips text color for viewport tool tips hilight color in the stack view drop-down list color used in edit boxes, list boxes and other

--- The color used to hilight sub-object levels in -- the dark shadow color on 3d controls

Interface: colorMan

359

#3dLight -- the light color on 3d controls #appWorkspace -#trackbarBg -- trackbar background #trackbarBgSel -- trackbar background for selected keys #trackbarText -- trackbar text #trackbarTicks -- trackbar ticks #trackbarKeys -- trackbar keys #trackbarSelKeys -- track bar selected keys #trackbarCursor -- track bar cursor #pressedButton -- background color for pressed buttons, like the transform constraints #timeSliderBg -- The background for the time slider bar. #viewportBorder -- The viewport border color #activeViewportBorder -- The active viewport border color #rollupTitleFace -- Rollout title background #rollupTitleText -- rollout title text #rollupTitleHilight-- rollout title 3d highlight #rollupTitleShadow -- rollout title 3d shadow #selectionRubberBand -- the selection marquee color #stackViewSelection -- the color of a selected item in stack view

Return Value: Returns true if the color was set and false if the id passed could not be found. Prototype:
<point3 by value>getColor <string>color

Remarks: Returns the color value of the color whose ID is passed. Parameters:
<string>color

Specifies which color to get. Return Value: The color is returned or black (RGB(0,0,0)) if the Color passed was not found. Prototype:
<string>getName <string>color

Parameters:
<string>color

The ID of the color. Return Value: Returns the name of the color whose ID is passed.

360

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<string>getCategory <string>color

Parameters:
<string>color

The ID of the color. Return Value: Returns the category string of the color whose ID is passed. Prototype:
<float>getIconColorScale <enum>type <enum>which

type enums: {#disabledIcon|#enabledIcon} which enums: {#saturationScale|#valueScale|#alphaScale} Parameters:

<enum>type

One of the following values:

#disabledIcon

The disabled icons.

#enabledIcon

The enabled icons.

<enum>which

The icon color scale. One of the following values:

#saturationScale

The saturation scale.

#valueScale

The value scale.

#alphaScale

The alpha scale. Return Value: Returns a floating point value (in the range 0.0f to 1.0f) that is one of the scale factors applied to the specified icon type. These scale values used to do image processing on the icons at start-up time. Prototype:
<void>setIconColorScale <enum>type <enum>which <float>value

type enums: {#disabledIcon|#enabledIcon} which enums: {#saturationScale|#valueScale|#alphaScale} Remarks: Sets the specified scale factor for the icon type passed. The color manager maintains the values for the MAX icon image processing system. Developers can set values to scale the saturation, value and transparency for enabled and disabled icon images using this method.

Interface: colorMan

361

Parameters:
<enum>type

The icon type. One of the following values:

#disabledIcon

The disabled icons.

#enabledIcon

The enabled icons.

<enum>which

The icon color scale. One of the following values:

#saturationScale

The saturation scale.

#valueScale

The value scale.

#alphaScale

The alpha scale.

<float>value

The value runs from 0.0 to 100.0. Prototype:

<boolean>getIconColorInvert <enum>type

type enums: {#disabledIcon|#enabledIcon} Parameters:

<enum>type

The icon type. One of the following values:

#disabledIcon

The disabled icons.

#enabledIcon

The enabled icons. Return Value: Returns true if the invert flag is set for the specified icon type and false if not set. Prototype:
<void>setIconColorInvert <enum>type <boolean>value

type enums: {#disabledIcon|#enabledIcon} Remarks: Sets the invert flag for the specified icon type to on or off. Parameters:
<enum>type

The icon type. One of the following values:

#disabledIcon

The disabled icons.

362

Chapter 1

Whats New in 3ds max 4 MAXScript

#enabledIcon

The enabled icons.

<boolean>value

Pass true for inverted; false for not inverted. Prototype:

<string>getFileName()

Remarks: Returns the file name of the currently loaded color file. Prototype:
<point3 by value>getDefaultColor <string>color

Parameters:
<string>color

The ID of the color. Return Value: Returns the default color for the specified ID. The default color is the value passed as defaultValue in registerColor, regardless if a SetColor() has been done subsequently. This is used by the UI when the user presses Reset to reset a color to its default value. Prototype:
<void>repaintUI <enum>type

type enums: {#repaintAll|#repaintTrackBar|#repaintTimeBar} Remarks: This method allows you to issue a repaint of the user interface. Parameters:
RepaintType type

The type of repaint you wish to issue; #repaintAll, #repaintTrackBar, #repaintTimeBar.

See Also
In The MAXSDK Help File: Class IColorManager

Interface: dragAndDrop
iDrop - drag and drop (p. 62) The Drag and Drop system is managed through a Core Function Published interface. It provides control over the DnD system, manages handler registration and exposes some useful utility methods for downloading URLs, simulating drops, etc.

Interface: dragAndDrop

363

Prototype:
<void>globalEnableDragAndDrop <boolean>onOff

Remarks: This method allows you to globally enable or disable the DnD interface. Parameters:
<boolean>onOff

TRUE to enable, FALSE to disable. Prototype:

<boolean>isEnabled()

Return Value: This method returns TRUE if the global DnD interface is enabled, otherwise FALSE. Prototype:
<boolean>enableDragAndDrop <HWND>window <boolean>onOff

Remarks: This method allows you to enable DnD for a given window (and its children). If no custom DragAndDropHandler is supplied, a default one is used that will accept dropped scene files for opening and scripts for running. Parameters:
<HWND>window A handle to the window you wish to enable or disable DnD for. <boolean>onOff TRUE to enable, FALSE to disable.

Return Value: True if successful and false otherwise. Prototype:

<boolean>dropPackage <HWND>window <&point>mousePoint <&string array>files

Remarks: This method allows the simulation of a package of files into a window at a given point. A package of files, specified as a list of URL strings is the common form of DropType data from iDrop sources and files dragged from the Windows desktop. The entire package is downloaded, as needed, but only the first file in the list is actually dropped into MAX. The other files in the package are presumed to be support files, such as texmaps or xref sources, for the main drop file. After the drop, the URL strings in the URLTab are converted to fully-specified path names to local file copies, if any had to be downloaded from the web. Parameters:
<HWND>window

A handle to the window. If this is set to NULL, the default MAX window is used.
<&point>mousePoint

The point at which to drop.

364

Chapter 1

Whats New in 3ds max 4 MAXScript

<&string array>files

A reference to the local copies of the URL strings. Return Value: TRUE if the drop was successful, otherwise FALSE. Prototype:
<boolean>downloadPackage <&string array>files <string>directory

Remarks: This method serves as a utility function that can be used to download a package of URLs to the specified directory. If the hwnd argument is supplied, any progress or other messages are centered over that window. Parameters:
<&string array>files

A reference to the local copies of the URL strings.

<string>directory

The directory path string to download to. Return Value: True if successful and false otherwise. Prototype:
<string>getDownloadDirectory()

Return Value: This method returns the fully-specified path to the directory in which package drops are downloaded. Prototype:
<boolean>DownloadUrlToDisk <string>url <string>fileName <integer>flags

Remarks: This method allows you to download the file referenced by the URL to disk. Parameters:
<string>url

The URL string of the file to download.

<string>fileName

The filename string of the URL to store on disk.

<integer>flags

Return Value: True if successful and false otherwise. Prototype:

<node>ImportContextNode()

Return Value: Returns a pointer to the import context node.

Interface: HDIKSys

365

See Also
Zip-file Script Packages (p. 122) iDrop - drag and drop (p. 62)

Interface: HDIKSys
Interface: HDIKSys Methods: Prototype:
<void>ikChain <node>startJoint <node>endJoint <boolean>createEndEffector

Parameters:
<node>startJoint <node>endJoint <boolean>createEndEffector

Prototype:
<boolean>RemoveChain <node>chainNode

Remarks: Calling this method on the master controller causes all slave controllers in the chain to be replaced with default transform controllers (PRS). This method will support undo if it is enabled but will not turn undo on. This method does not cause viewports to be redrawn. Parameters:
<node>chainNode

See Also
HD IK controller chains can be assigned to existing hierarchies (p. 73)

Interface: IKSys
Interface: IKSys Methods: Prototype:
<node>ikChain <node>startJoint <node>endJoint <string>solver

Remarks: Where startJoint is the first node in the new chain (ancestor), endJoint is the last node in the chain (decendent) and assignEE is a boolean parameter: when TRUE, a position end effector is crated at the endJoint. Parameters:
<node>startJoint <node>endJoint <string>solver

366

Chapter 1

Whats New in 3ds max 4 MAXScript

Interface: manip
Scripted Manipulators (p. 97) Properties:
.msXYPlane : Interface : Read .msXZPlane : Interface : Read .msYZPlane : Interface : Read

Prototype:
<mesh>makeSphere <point3 by value>pos <float>radius <integer>segments

Parameters:
<point3 by value>pos <float>radius

Specifies the radius of the sphere.

<integer>segments

Sets the number of polygonal divisions for the sphere. Return Value: This returns a mesh sphere with the given position, radius, and segments. Prototype:
<mesh>makeTorus <point3 by value>pos <float>radius <float>radius2 <integer>segs <integer>sides

Parameters:
<point3 by value>pos <float>radius

Sets the distance from the center of the torus to the center of the cross-sectional circle. This is the radius of the torus ring.
<float>radius2

Sets the radius of the cross-sectional circle. The default is 10 units. This value is replaced each time you create a torus.
<integer>segs

Sets the number of radial divisions around the torus. By reducing this number, you can create polygonal rings instead of circular ones.
<integer>sides

Sets the number of sides on the cross-sectional circle of the torus. By reducing this number, you can create prism-like cross sections instead of circular ones. Return Value: Create a torus mesh with the given values. Prototype:
<mesh>makeBox <point3 by value>pos <float>l <float>w <float>h <integer>lsegs <integer>wsegs <integer>hsegs

Interface: manip

367

Parameters:
<point3 by value>pos <float>l

Sets the length, width, and height of the Box object. These fields also act as readouts while you drag the sides of the box. Default=0,0,0.
<float>w

Sets the length, width, and height of the Box object. These fields also act as readouts while you drag the sides of the box. Default=0,0,0.
<float>h

Sets the length, width, and height of the Box object. These fields also act as readouts while you drag the sides of the box. Default=0,0,0.
<integer>lsegs

Sets the number of divisions along each axis of the object. Can be set before or after creation. By default, each side of the box is a single segment. When you reset these values, the new values become the default during a session. Default=1,1,1. Tip: Increase the Segments settings to give objects extra resolution for being affected by modifiers. For example, if youre going to bend a box on the Z axis, you might want to set its Height Segments parameter to 4 or more.
<integer>wsegs

Sets the number of divisions along each axis of the object. Can be set before or after creation. By default, each side of the box is a single segment. When you reset these values, the new values become the default during a session. Default=1,1,1. Tip: Increase the Segments settings to give objects extra resolution for being affected by modifiers. For example, if youre going to bend a box on the Z axis, you might want to set its Height Segments parameter to 4 or more.
<integer>hsegs

Sets the number of divisions along each axis of the object. Can be set before or after creation. By default, each side of the box is a single segment. When you reset these values, the new values become the default during a session. Default=1,1,1. Tip: Increase the Segments settings to give objects extra resolution for being affected by modifiers. For example, if youre going to bend a box on the Z axis, you might want to set its Height Segments parameter to 4 or more. Return Value: Creates a box mesh with the given parameters. Prototype:
<Interface>makePlaneFromPts <point3 by value>p1 <point3 by value>p2 <point3 by value>p3

Parameters:
<point3 by value>p1 <point3 by value>p2 <point3 by value>p3

368

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<Interface>makePlaneFromNormal <point3 by value>normal <point3 by value>point

Parameters:
<point3 by value>normal <point3 by value>point

Return Value: Creates a Plane object with the given normal that passes through the given point. Prototype:
<Interface>makeGizmoShape()

Prototype:
<Interface>makeCircle <point3 by value>center <float>radius <integer>segments

Parameters:
<point3 by value>center <float>radius <integer>segments

Interface: maxOps
maxOps (p. 87) Properties:
.productVersion : enum : Read productVersion enums: {#productVersionDevel|#productVersionTrial|#productVersionOrdinary|#productVersion Edu|#productVersionNFR} .licenseBehavior : enum : Read licenseBehavior enums: {#licenseBehaviorPermanent|#licenseBehaviorExtendable|#licenseBehaviorNonextendabl e} .licenseDaysLeft : integer : Read .trackbar : Interface : Read

Methods: Prototype:
<boolean>canImportBitmap <string>fileName

Parameters:
<string>fileName

Return Value: True if successful and false otherwise. Prototype:

<void>displayActiveCameraViewWithMultiPassEffect()

Remarks: displayActiveCameraViewWithMultiPassEffect - no automatic redraw after invoked

Interface: maxOps

369

Prototype:
<void>setActiveViewportTransparencyDisplay <integer>transparencyLevel

Parameters:
<integer>transparencyLevel

Prototype:
<boolean>loadCUIFile <string>fileName

Parameters:
<string>fileName

Return Value: True if successful and false otherwise. Prototype:

<boolean>isFeatureLicensed <integer>featureNumber

Parameters:
<integer>featureNumber

Return Value: True if successful and false otherwise. Prototype:

<Interface>GetCurRenderElementMgr()

Return Value: gets the current render element manager. Prototype:

<Interface>GetRenderElementMgr <enum>

Parameters:
{#Production|#Draft}

Return Value: Gets a specific render element manager. Prototype:

<void>CollapseNode <node>node <boolean>noWarning

Remarks: Parameters:
<node>node <boolean>noWarning

Prototype:
<boolean>CollapseNodeTo <node>node <index>modIndex <boolean>noWarning

Parameters:
<node>node <index>modIndex <boolean>noWarning

370

Chapter 1

Whats New in 3ds max 4 MAXScript

Return Value: True if successful and false otherwise. Prototype:

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

Parameters:
<&node array>nodes <&point3>offset expandHierarchy:<boolean> expandHierarchy default value: false cloneType:<enum> cloneType enums: {#copy|#instance|#reference} cloneType default value: #copy actualNodeList:<node array> actualNodeList default value: #() newNodes:<node array> newNodes default value: #()

Return Value: True if successful and false otherwise. Prototype:

<boolean>setSelectionType <boolean>auto <enum>method

Parameters:
<boolean>auto method enums: {#window|#crossing|#leftToRight|#rightToLeft}

Return Value: True if successful and false otherwise. Prototype:

<maxObject>getNodeByHandle <DWORD>handle

Parameters:
<DWORD>handle

Return Value: Return a node associated with a given handle. Prototype:

<Interface>getTrackBar()

Return Value: The interface to a trackbar is returned.

Interface: medit

371

Interface: medit
Interface available for Texmap and Mtl Interface_medit. Prototype:
<maxObject>GetCurMtl()

Return Value: This method returns a material base pointer for the current material. Prototype:
<void>SetActiveMtlSlot <index>slot <boolean>forceUpdate

Parameters:
<index>slot

The material slot index.

<boolean>forceUpdate

Set this to TRUE to update the slot contents. Remarks: This method allows you to set the active material slot. Prototype:
<index>GetActiveMtlSlot()

Return Value: This method returns the index of the active material slot. Prototype:
<void>PutMtlToMtlEditor <maxObject>mtl <index>slot

Parameters:
<maxObject>mtl

The material you want to put.

<index>slot

The index of the material slot you wish to put the material into. Remarks: This method allows you to put the specified material to the specified material editor slot. Prototype:
<maxObject>GetTopMtlSlot <index>slot

Parameters:
<index>slot

The index of the material slot for which you wish to obtain the material. Return Value: This method returns a pointer to the material base from the specified slot. Prototype:
<boolean>OkMtlForScene <material>mtl

372

Chapter 1

Whats New in 3ds max 4 MAXScript

Parameters:
<material>mtl

The pointer to the material. Return Value: Before assigning material to scene, call this to avoid duplicate names. Prototype:
<void>UpdateMtlEditorBrackets()

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

See Also
Material Editor Access (p. 165) BitmapTex Reload and viewImage (p. 164)

Interface: menuMan
Prototype:
<boolean>loadMenuFile <string>file

Remarks: This method allows you to load a menu file from disk and automatically update the UI accordingly. Parameters:
<string>file

The path and filename of the menu file to load. Return Value: TRUE if the menu file was loaded, otherwise FALSE. Prototype:
<boolean>saveMenuFile <string>file

Remarks: This method allows you to save a menu file to disk. Parameters:
<string>file

The path and filename of the menu file to save. Return Value: TRUE if the menu file was saved, otherwise FALSE.

Interface: menuMan

373

Prototype:
<string>getMenuFile()

Return Value: This method returns the file name of the currently loaded and active menu file. Prototype:
<void>updateMenuBar()

Remarks: This method can be called to update MAX main menu bar after adding sub-menus or menu items. Prototype:
<boolean>registerMenuContext <integer>contextId

Remarks: To add items to MAXs main menu, the plug-in should check the return value of RegisterMenuContext(), and if it is true, that means that this is the first time it has been registered, and the plug-in can then create new menus, add items to MAXs main menu and Quad menus. Prototype:
<Interface>findMenu <string>menuName

Remarks: This method will return a pointer to a menu based on its name. Parameters:
<string>menuName

The name of the menu to return. Return Value: A pointer to the menu or NULL if the menu wasnt found. Prototype:
<Interface>findQuadMenu <string>menuName

Remarks: This method will return a pointer to a quad menu based on its name. Parameters:
<string>menuName

The name of the menu to return. Return Value: A pointer to the quad menu or NULL if the menu wasnt found. Prototype:
<boolean>unRegisterMenu <Interface>menu

Remarks: This method allows you to remove a menu form the mananger.

374

Chapter 1

Whats New in 3ds max 4 MAXScript

Parameters:
<Interface>menu

Points to the menu to unregister. Return Value: FALSE if the menu was not registered, TRUE if successfully unregistered. Prototype:
<boolean>unRegisterQuadMenu <Interface>quadMenu

Parameters:
<Interface>quadMenu

Remarks: This is like unregisterMenu but for quad menus. Prototype:

<Interface>createMenu <string>name

Parameters:
<string>name

Return Value: This creates a new, empty menu with the given name. Prototype:
<Interface>createQuadMenu <string>name <string>quad1Name <string>quad2Name <string>quad3Name <string>quad4Name

Parameters:
<string>name <string>quad1Name <string>quad2Name <string>quad3Name <string>quad4Name

Remarks: This creates a new, empty quad menu. It contains, 4 empty menus, one for each quad. Prototype:
<Interface>createSubMenuItem <string>name <Interface>subMenu

Parameters:
<string>name <Interface>subMenu

Remarks: This creates a new sub-menu item that can be added to a menu. It uses the given name and it displays the given sub-menu. Prototype:
<Interface>createSeparatorItem()

Interface: menuMan

375

Return Value: This creates a new menu separator that can be added to a menu. Prototype:
<Interface>createActionItem <string>macroScriptName <string>macroScriptCategory

Parameters:
<string>macroScriptName <string>macroScriptCategory

Return Value: This creates a new menu item that can be added to a menu. The item is an action that executes the macro script with the given name and category. This returns undefined if there is no macroScript with the given name and category. Prototype:
<boolean>setViewportRightClickMenu <enum>which <Interface>menu

which enums: {#nonePressed|#shiftPressed|#altPressed|#controlPressed|#shiftAndAltPressed|#shiftAndControlPres sed|#controlAndAltPressed|#shiftAndAltAndControlPressed} Remarks: This method allows you to set the viewport right-click menu to the specified quad menu. Parameters:
<enum>which

See the List of Right-Click Contexts above.

<Interface>menu

A pointer to the quad menu you wish to set. Return Value: TRUE if it was set successfully. Prototype:
<Interface>getViewportRightClickMenu <enum>which

which enums: {#nonePressed|#shiftPressed|#altPressed|#controlPressed|#shiftAndAltPressed|#shiftAndControlPres sed|#controlAndAltPressed|#shiftAndAltAndControlPressed} Parameters:

<enum>which

See the List of Right-Click Contexts.. Return Value: This method returns a pointer to the current viewport right-click quad menu. Prototype:
<Interface>getMainMenuBar()

376

Chapter 1

Whats New in 3ds max 4 MAXScript

Return Value: This method returns a pointer to the main menu bar. Prototype:
<boolean>setMainMenuBar <Interface>menu

Remarks: This method allows you to set the main menu bar. Parameters:
<Interface>menu

A pointer to the menu you wish to set as the main menu bar. Return Value: TRUE if it was set successfully. Prototype:
<bool>getShowAllQuads <Interface>quadMenu

Remarks: This method checks if the Show All Quads flag is set for a specific QuadMenu. Parameters:
<Interface>quadMenu

A pointer to the QuadMenu you wish to check the flag for. Return Value: This method will return TRUE if the flag is set or FALSE if the flag is not set. Prototype:
<void>setShowAllQuads <Interface>quadMenu <bool>value

Remarks: This method sets the Show All Quads flag for a specific QuadMenu. Parameters:
<Interface>quadMenu

A pointer to the QuadMenu you wish to set the flag for.

<bool>value

TRUE to set the flag to on, FALSE to set the flag off. Prototype:
<string>getQuadMenuName <Interface>quadMenu

Parameters:
<Interface>quadMenu

A pointer to the QuadMenu for which you wish to retrieve the name. Return Value: This method returns the name given to a specific QuadMenu as a string.

Interface: menuMan

377

Prototype:
<void>setQuadMenuName <Interface>quadMenu <string>name

Remarks: This method allows you to set the name of a specific QuadMenu. Parameters:
<Interface>quadMenu

A pointer to the QuadMenu for which you wish to set the name.
<string>name

The string containing the name for the QuadMenu. Prototype:

<integer>numMenus()

Return Value: Returns the total number of menus in registered with the menu manager. Prototype:
<Interface>getMenu <index>index

Parameters:
<index>index

Return Value: Retrieves the indexth menu in the menu manager. This is a 1-based index. Prototype:
<integer>numQuadMenus()

Return Value: Returns the total number of quad menus registered with the menu manager. Prototype:
<Interface>getQuadMenu <index>index

Parameters:
<index>index

Return Value: Retrieves the indexth quad menu in the menu manager. This is a 1-based index.

See Also
In The MAXSDK Help File Class ImenuManager

See Also
Menu Manager (p. 75) Interface: quadMenuSettings (p. 414)

378

Chapter 1

Whats New in 3ds max 4 MAXScript

Interface: msZip
Prototype:
<boolean>fileInPackage <string>fileName <&TSTR>extractDir

Remarks: extractDir is In parameter This method will unload and run a zip package and return the extract_dir. Parameters:
<string>fileName

The file name of the ZIP script package.

<&TSTR>extractDir

The directory in which the files were extracted. Return Value: TRUE if the zip package was run, otherwise FALSE. Prototype:
<boolean>unloadPackage <string>fileName <&TSTR>extractDir <&TSTR>dropFile

Remarks: extractDir is In parameter dropFile is In parameter This method will unload the package while ignoring any drop or run commands and return the extract_dir and any primary drop file. If the primary dropFile is a *.ds, compile it in context of the package and return the MacroEntry in dropScript. Parameters:
<string>fileName

The file name of the ZIP script package.

<&TSTR>extractDir

The directory in which the files were extracted.

<&TSTR>dropFile

The primary drop file. Return Value: TRUE if the package was unloaded, otherwise FALSE.

See Also
Interface: dragAndDrop (p. 362) Zip-file Script Packages (p. 122) iDrop - drag and drop (p. 62)

Interface: NetRender

379

Interface: NetRender
Methods: Prototype:
<Interface>GetManager()

Remarks: In order to access network rendering through the scripter, you need to create a manager instance. The syntax is the following:
netrender.getmanager()

Working with the manager

The following methods can be used to query and or control the manager. Prototype:
<netManager>.setCallback #progress | #message | #update | #managerdown | #queuecontrol | #querycontrol <somefunction>

Remarks: Used to listen to the manager for certain event types that occur during a network render. For each event type, you can call a single function that you define. Each of the 6 callback types is one type of event, and you can install a callback for any of these event or none. You must define the function to take a different number of arguements depending on the event type. Requires 2 arguments, they can be:
#progress myprogess

Called anytime a download/upload is underway, including anytime you fetch information about jobs or servers. Requires a function defined with 2 integer parameters, Total and Current. Total is the total amount to transfer, and Current is the amount tranferred so far. Example:
fn myprogress total current = -- NOTE: two integer parameters format Progress: completed % out of %\n current total m.setcallback #progress myprogress -- sets the #progress callback to use myprogress() #message mymessage

Called when the manager has a text message for the user. Requires a function defined with 1 string parameter which is the message text.

380

Chapter 1

Whats New in 3ds max 4 MAXScript

Example:
fn myNetMessage msg =-- NOTE: one string parameter format Message: %\n msg m.setcallback #message mymessage -- sets the #message callback to use mymessage() #update myupdate

Called when something has changed, like a job started or finished. Lets you know when you need to make GetUpdate calls, or other refreshing. Requires a function defined with no parameters. Example:
fn myUpdate = job.GetUpdate()--example of what you might do m.setcallback #update myupdate -- sets the #update callback to use myupdate() #managerdown mymanagerdown

Called when the manager shuts down. Requires a function defined with no parameters. Example:
fn myManagerDown = format Manager is dead\n m.setcallback mymanagerdown mymanagerdown() #queuecontrol myqueuecontrol

-- sets the #managerdown callback to use

Called whenever queue control changes. Requires a function defined with no parameters. Example:
fn myQueueControl = format Queue control has changed\n m.setcallback #QueueControl myQueueControl--install the QueueControl callback #querycontrol myquerycontrol

Called when you have Queue Control, and another computer wants it, either via the QueueManager, or with the script function <netManager>.QueryControl(). If you want to keep control, set the value <netManager>.WantControl to true, otherwise set it to false. The function must take one arguement, which is the name of the machine requesting control. See the function <netManager>.QueueControl() for more information.

Working with the manager

381

Example:
fn myQueryControl clientName = (--NOTE: one string parameter format The computer % wants queue control clientName m.wantControl = true-- use this to keep queue control m.wantControl = false-- use this to release queue control ) m.setcallback #QueryControl myQueryControl--install the QueryControl callback

Prototype:
<netManager>.GetCallback <#progress | #message | #update | #managerdown | #queuecontrol | #querycontrol>

Remarks: Returns the name of the function used for that particular callback. Returns an empty array if no callback is assigned. Requires 1 argument, can be:
#progress

Called anytime a download/upload is underway, including anytime you fetch information about jobs or servers
#message

Called when the manager has a text message for the user
#update

Called when something has changed, like a job started or finished. Lets you know when you need to make GetUpdate calls, or other refreshing
#managerdown

Called when the manager dies

#queuecontrol

Called whenever queue control changes

#querycontrol

Called when you have Queue Control, and another computer wants it Prototype:
<netManager>.connect #manual <manager name>|<manager IP address> [port:<integer>] or <netManager>.connect #automatic <subnet mask> [port:<integer>]

Remarks: Establishes a connection to the manager, allowing access to job states, server states, editing job settings, etc .It takes 2 arguments and a 3rd optional argument. You can either connect to a manager manually by specifying the manager name or ip address of the manager as a string, or automatically by specifying the subnet mask and optional port number, eg:
m.connect #manual manager -- connects to manager of name manager -- connects to manager of IP 192.168.0.1

or:
m.connect #manual 192.168.0.1

or:

382

Chapter 1

Whats New in 3ds max 4 MAXScript

m.connect #automatic 255.255.255.0 port:1234 -- automatically connects to manager on subnet 255.255.255.0 at port 1234

in either case, you can specify the optional port number should the manager be using a non default port number. Will return true if connection was succesful. Prototype:
<netManager>.Disconnect()

Remarks: Disconnects the connection established with <netManager>.connect. Prototype:

<netManager>.Kill()

Remarks: Shutsdown the manager. You must have queue control to do this. Prototype:
<netManager>.QueryControl #wait | #dontwait

Parameters: requires either #wait or #dontWait. The function works as follows: Nobody has queue controlSomeone has Queue Control
#dontWaitreturns TRUEreturns FALSE #waitreturns TRUEprompts the current queue controller

Remarks: In the last case, the queue controller gets the QueryControl callback, and must indicate if they want control. If that user indicates they want to keep control, then the function returns FALSE, if they will give up control (or the 10 second timeout expires), it returns TRUE. Note that the QueueManager gives a prompt for the user to indicate what they want; in the scripter, you just get the callback and have to use the wantControl value. Note: Please refer to callback, #queuecontrol myqueuecontrol, found above in <netManager>.setCallback. Prototype:
<netManager>.GetControl()

Remarks: Takes control of the queue. Returns true if control was taken. From that moment on, jobs can be submitted, edited, reprioritized, servers can be removed, until queue control is relinquished. Note: The current queue controller does not get its QueryControl callback triggered. Instead, they just lose the queue control (unless they also have the queue locked lock). You should always precede a call to GetControl() with a call to QueryControl(true), to be sure if its OK to do this.

Working with the manager

383

Prototype:
<netManager>.Lock <true | false>

Remarks: Locks out others from getting queue control; and if they call QueryControl, it will automatically return false. For example, suppose you got control of the queue through the scripter using getcontrol(), someone else who has the queuemanager up in readonly mode can request queuecontrol. Setting lock to true, will disallow anyone else to take control until you until you disconnect from the manager, or until you reset the lock to false. Note that the QueueManager always calls QueryControl to check if it can grab the queue. Prototype:
<netManager>.SetUpdates <true | false>

Remarks: This functions usage resemebles the Lock() function, in that a boolean value is passed, and you must already have queue control. Setting updates to false will freeze the manager so that it refuses any changes to the queue. It does not affect the callbacks. Fewer Update callbacks will be received, since the job queue is not updating. Use this function when submitting large numbers of changes, and when you want all the changes to take effect at the same time. This will occur when setUpdates is called with a true value. Prototype:
<netManager>.checkoutputvisibility <path>

Takes 1 argument, a pathname defined as a string, ie c:\\temp. Remarks: It verifies that the path exists, returns The system cannot find the path specified. (0x3) if the path doesnt exist. Note: Note that the manager checks this output path relative to itself, not to your local machine. Thus if you pass C:\\ and you have not shared you C drive, it will return OK (because the manager checks its own C drive). Thus you should use a network name when calling this function, like \\\\mymachine\\share\\. Also, if the parameter does not end in \\, the functions assumes youre naming a file (not a directory) and checks whether this file could be created. Always include the \\ at the end if youre checking whether a directory is accessible.

Properties:
The following properties can be used to get information or set certain properties of the manager. Prototype:
<netManager>.connected

Remarks: Returns true if connected to the manager.

384

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<netManager>.netStatus

Remarks: Returns the status of the manager. Various information about the manager can be gathered through netstatus,see netstatus topic. Prototype:
<netManager>.wantControl

Remarks: If you have QueueControl, and other computers call QueryControl, this indicates whether you want to maintain control, or relinquish it; their call to QueryControl will return whatever you have set for WantControl Prototype:
<netManager>.haveControl

Remarks: True, if you currently have QueueControl. Prototype:

<netManager>.numJobs

Remarks: Returns the number of jobs in the queue. Prototype:

<netManager>.numServers

Remarks: Returns the number of servers. Prototype:

<netManager>.numGroups

Remarks: Returns the number of groups.

Working with jobs

Various functions and properties can be used to access jobs. You can use the GetJobs() function to retrieve an array of all jobs in the queue. The jobs can be filtered in various ways to return an array based on the filter. Note: Do not call GetJobs() or GetServers() very often, because these are VERY heavyweight methods.

Working with jobs

385

Prototype:
<netManager>.getjobs [filter:#suspended | #complete | #waiting | #started | #error | #name | #handle | #index] [key:<name> | <handle> | <index>]

The latter three filter types require a corresponding key arguement. If used without a filter, returns an array of all jobs in queue. If no jobs are in the queue, an empty array will be returned.
filter:#suspended

Returns an array of all suspended jobs. Returns an empty array #() if no jobs are suspended
filter:#complete

Returns an array of all completed jobs. Returns an empty array #() if no jobs are complete.
filter:#waiting

Returns an array of jobs that are waiting to be rendered or are being rendered. Will return an empty array #() if no jobs are waiting.
filter:#started returns an array of jobs that are actually started and being rendered. filter:#complete

Returns an array of all completed jobs. Returns an empty array #() if no jobs are complete
filter:#error

Returns an array of all jobs experiencing an error. Returns an empty array #() if no jobs have errors
filter:#name

Pass a name as the Key argument; Returns an array of all jobs with the given name. Returns an empty array #() if the no jobs have that name
filter:#handle

Pass a handle as the Key argument; the job with that handle will be returned (as an array with one element). Returns an empty array #() if the no job has that handle
filter:#index

Pass an integer as the Key argument; the job at that index in the queue will be returned (as an array with one element). Returns an empty array #() if the no job exists at that index Example:
manager.GetControl() --get queue control manager.SetUpdates false --the queue is now frozen jobs = manager.GetJobs() manager.SetUpdates true --the queue is unfrozen

Note: The GetJobs() function could return incorrect results if the Queue is changed while the job information is downloading. SetUpdates is used to guarantee that GetJobs operates without error.

386

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<netManager>.SetJobOrder <array>

Remarks: Changes the order of the jobs in the queue. The array must contain the same jobs that are contained in the array from .getjobs(), although they can be in different order. You must also have queuecontrol, use .getcontrol() function to take control before setting the job order. Prototype:
<netManager>.NewJob file:<filename>

Example:
job.newJob file:file.max --submitting a file job.newJob() --submitting the current scene

Remarks: Creates a new job instance. It requires a valid max file name, ie a max file that exists somewhere on the hard drive or the network. Returns a job definition if the file exists, undefined if the file cant be found. Note: Jobs can not have maps included, and render element data will not be available for submitted job but render elements will process correctly. These problems are resent when submitting a job from a file, but not when submitting the current scene. Prototype:
<job>.GetUpdate()

Remarks: Updates the information about the selected job. Remember this involves a network interaction, so its a heavyweight operation Prototype:
<job>.SendUpdate()

Remarks: Updates the job in the queue with new job settings. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control. Remember this involves a network interaction, so its a heavyweightoperation Prototype:
<job>.Submit() Servers:<array>

Remarks: Submits a new job to be rendered to the queue. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control. if no servers are provided, then all servers will be assigned to the job. Prototype:
<job>.Suspend()

Working with jobs

387

Remarks: Suspends the selected job. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control. Prototype:
<job>.Resume()

Remarks: Will cause the job to resume where it left off when it was suspended. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control. Prototype:
<job>.Restart()

Remarks: Will restart the job from the beginning. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control. Prototype:
<job>.Delete()

Remarks: Will delete the job from the queue. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control. Prototype:
<job>.AssignServer <server>

Remarks: Assigns a selected server to the job. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control. Prototype:
<job>.SuspendServer <server>

Remarks: Removes a server from the selected job. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control. Prototype:
<job>.GetServerInfo <integer>

Remarks: Gets information about a particular server assigned to the job. Requires a server number, 1 based. Prototype:
<job>.GetRenderElement <index>

388

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: Returns information as a data structure about the nth element in the. The <element> structure is defined below. Returns undefined if no element at the index number, eg: el = jobs[1].getrenderelement 1 -- retrieves the 1st element in the 1st job in the queue. With this you can find out if the element is enabled, if filtering is enabled, if atmosphere is applied, if shadows are applied, the element name and the element output filename. The following are the properties that are valid for an element. Prototype:
<element>.enabled

Remarks: Returns true if the element is enabled. Can also set its state. Prototype:
<element>.filterEnabled

Remarks: Returns true if filtering is enabled. Can also set its state. Prototype:
<element>.atmosphereApplied

Remarks: Returns true if atmosphere is applied. READ-ONLY Prototype:

<element>.shadowsApplied

Remarks: Returns true if shadows are applied. READ-ONLY Prototype:

<element>.name

Remarks: Returns the elements name. Name can be changed. Prototype:

<element>.output

Remarks: Returns the elements output file name. Output name and path can be changed, however, changing the filetype will change the extension of the image but not the actual file type, eg: the current output returned is \\ej4sf\frames\foo_diffuse.tga, changing the extension to .bmp will just result in the tga file having a .bmp extension instead of the .tga extension. Prototype:
<job>.SetRenderElement <index> <element>

Working with jobs

389

Remarks: Sets the selected render element to the new values assigned to the element. In order for the change to take effect in the job, you need to do a <job>.sendupdate() to update the job itself in the queue. Prototype:
<job>.GetCameras()

Remarks: Returns an array of cameras in the scene. An empty array #() is returned if no cameras are in the scene. Prototype:
<job>.GetLog() start:x numLines:y

Remarks: Returns the log for the job as text. The start and numLines parameters are optional. If you pass no parameters, you get the entire log. If you only pass start, you get every line starting from the given line. If you pass only numLines, then start is assumed to be 0. Prototype:
<job>.GetFrameInfo <integer>

Remarks: Returns information, as a data structure, about the nth frame. The index is 1 based. The <frame> structure is defined below. Example:
fr = getframeinfo 4 -- Returns info about the 4th frame. Read-only

Prototype:
<frame>.state

Remarks: Returns the state of the frame. The state can be #waiting, #assigned or #complete. Prototype:
<frame>.index

Remarks: Returns the actual frame number. Read-only Prototype:

<frame>.serverhandle

Remarks: Returns the serverhandle. Should return undefined when frame hasnt been rendered yet. Read-only Prototype:
<frame>.servername

390

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: Returns the name of the server that is assigned to that frame. Should return undefined if the frame isnt assigned yet. Read-only Prototype:
<frame>.elapsedtime

Remarks: Returns the time it took for the frame to render. Should return undefined if the frame isnt assigned yet. Read-only Prototype:
<job>.GetServerStatusText <server>

Remarks: Returns any messages from the chosen server assigned to the job. Will return an empty string if no messages from the server. Read-only Prototype:
<job>.numServers

Remarks: Returns the number of servers assigned to the job. Read-only Prototype:
<job>.state

Remarks: Returns the state of the job. This can be #complete, #suspended, #busy or #waiting. Read-only Prototype:
<job>.serverPID

Remarks: This function gives low-level information that is intended for internal-use-only. Prototype:
<job>.handle

Remarks: Returns the jobs handle. Read-only Many of the following values are read-write, but changes you make to these values will not register with the manager until you call <job>.SendUpdate(). Note that SendUpdate requires queue control (obtained via <NetManager>.getControl) Prototype:
<job>.name

Remarks: Returns the name of the job. The name can be changed

Working with jobs

391

Prototype:
<job>.filesize

Remarks: Returns the jobs file size Prototype:

<job>.filesizeExtracted

Remarks: Returns the jobs extracted file size. Read-only Prototype:

<job>.timeSubmitted

Remarks: Returns the time at which the job was submitted as a string. Prototype:
<job>.timeStarted

Remarks: Returns the time at which the job was started as a string. Returns undefined if job hasnt started. Read-only Prototype:
<job>.timeFinished

Remarks: Returns the time at which the job was finished as a sting. Returns undefined if job hasnt finished. Read-only Prototype:
<job>.notifications

Remarks: Returns true if notifications are on. Can be changed Prototype:

<job>.notifyFailure

Remarks: Returns true if notified of failures. Can be changed Prototype:

<job>.notifyProgress

Remarks: Returns true if notified of progress. Can be changed Prototype:

<job>.notifyCompletion

392

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: Returns true if notified of progress is on. Can be changed Prototype:

<job>.notifyFrameInterval

Remarks: Returns an interval at which notifications occur. Can be changed Prototype:

<job>.fromFrame

Remarks: Returns the rendering start frame. Can be changed Prototype:

<job>.toFrame

Remarks: Returns the rendering end frame. Can be changed Prototype:

<job>.nthFrame

Remarks: Returns the rendering frame interval. Can be changed Prototype:

<job>.outputWidth

Remarks: Returns the width of the rendered frame. Can be changed Prototype:
<job>.outputHeight

Remarks: Returns the height of the rendered frame. Can be changed Prototype:
<job>.numFramesComplete

Remarks: The number of completed frames for the job. Read-only Prototype:
<job>.priority

Remarks: Returns the job priority.

Working with jobs

393

Prototype:
<job>.videoPost

Remarks: Returns true if there is a video post sequence. Read-only Prototype:

<job>.nonconcurrentDriver

Remarks: Returns true if the output cannot be rendered one frame at a time (like .MOV). Read-only Prototype:
<job>.includeMaps

Remarks: Returns true if the job was submitted with include maps on. Can be changed Prototype:
<job>.uninterruptibleDriver

Remarks: Returns true if the render cant be resumed if it was interrupted or suspended. For an.AVI, you cannot render half the file, then finish it later. You need to render the whole thing without interruption. Read-only Prototype:
<job>.skipRenderedFrames

Remarks: Returns true if skip rendered frames was set to on when job was submitted. Can be changed Prototype:
<job>.useAllServers

Remarks: Returns true if use all servers was set to on when job was submitted. Can be changed Prototype:
<job>.suspended

Remarks: Returns true if the job is suspended. Read-only. To suspend the job use <job>.suspend() Prototype:
<job>.finished

Remarks: Returns true if the job is finished. Read-only Prototype:

<job>.ignoreShare

394

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: Returns true if the job was submitted with ignore share on. Can be changed Prototype:
<job>.skipOutputTest

Remarks: Returns true if the job was submitted with skip output test on. Can be changed Prototype:
<job>.nonSeqFrames

Remarks: Returns true if the job was submitted to render non sequential frames. Can be changed Prototype:
<job>.combustionJob

Remarks: Returns false if the job is a max job. Read-only Prototype:

<job>.uncompressedFile

Remarks: Returns false if the job file is compressed. Read-only Prototype:

<job>.gammaCorrection

Remarks: Returns true if the job was submitted with gamma correction on. Can be changed. Prototype:
<job>.gammaValueIn

Remarks: Returns a float value of the incomming gamma value. Can be changed. Prototype:
<job>.gammaValueOut

Remarks: Returns a float value of the outgoing gamma value. Can be changed. Prototype:
<job>.renderPixelAspect

Remarks: Returns a float value of the render pixel aspect ratio. Can be changed.

Working with jobs

395

Prototype:
<job>.renderCamera

Remarks: Returns a string with the name of the camera view being rendered. Will return an empty string if view being rendered is an non camera view, ie perspective, front, user, etc Can be changed. Use <job>.getcameras() function to get a list of valid cameras in the scene to change to. Prototype:
<job>.renderElements

Remarks: Returns true if a job was submitted with the render elements active. Note that this will return true even there arent any elements to be rendered. Can be changed. Prototype:
<job>.numSceneObjects

Remarks: Returns the number of objects in the scene as an integer. Read-only Prototype:
<job>.numSceneFaces

Remarks: Returns the number of faces in the scene as an integer. Read-only Prototype:
<job>.numSceneLights

Remarks: Returns the number of lights in the scene as an integer. Read-only Prototype:
<job>.sceneStartTime

Remarks: Returns the scene start time in frames, so if your scene is set to use MM:SS:Ticks, this will still return a value in frames. Prototype:
<job>.sceneEndTime

Remarks: Returns the scene end time in frames. Prototype:

<job>.videoColorCheck

Remarks: Returns true if the job was submitted with videocolorcheck on. Can be changed.

396

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<job>.force2Sided

Remarks: Returns true if the job was submitted with force 2 sided on. Can be changed. Prototype:
<job>.renderHiddenObjects

Remarks: Returns true if the job was submitted with render hidden objects on. Can be changed. Prototype:
<job>.renderAtmosphericEffects

Remarks: Returns true if the job was submitted with render render atmospheric effects on. Can be changed. Prototype:
<job>.superBlack

Remarks: Returns true if the job was submitted with superblack on. Can be changed. Prototype:
<job>.serialNumbering

Remarks: Returns true if nth serial numbering is on this property is accesible through the preferences \ rendering dialog. Prototype:
<job>.ditherPaletted

Returns true if Dither Paletted was enabled when the job was submitted. Can be changed. Prototype:
<job>.ditherTrueColor

Remarks: Returns true if Dither True Color was enabled when the job was submitted. Can be changed. Prototype:
<job>.renderFields

Remarks: Returns true if Render Fields was enabled when the job was submitted. Can be changed. Prototype:
<job>.renderDisplacements

Remarks: Returns true if displacements was enabled when the job was submitted. Can be changed.

Working with jobs

397

Prototype:
<job>.renderEffects

Remarks: Returns true if render effects was enabled when the job was submitted. Can be changed. Prototype:
<job>.fieldOrder

Remarks: Returns either #odd or #even depending on what the field order was set to when job was submitted. Can be changed. Prototype:
<job>.numRenderElements

Remarks: Returns the number of render elements in the scene. Read-only. Prototype:
<job>.userName

Remarks: Returns the name of the user, as a string, that submitted the job. Note that if a job is submitted through the scripter using <job>.submit(), and the max file was last saved by another user on a different computer, the username will be that of the other user. Read-only Prototype:
<job>.computerName

Remarks: Returns the name of the computer, as a string, that the job was submitted from. Note that if a job is submitted through the scripter using <job>.submit(), and the max file was last saved by another user on a different computer, the computername will be that of the computer on which the max file was last saved. Read-only Prototype:
<job>.managerShare

Remarks: Returns the shared folder as a string where all jobs are stored on the manager. Prototype:
<job>.frames

Remarks: Returns a string of frames to render, ie 1,3,5-12. Can be changed. Prototype:

<job>.frameOutputName

398

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: Returns the name and path of the output file. Can be changed Prototype:
<job>.frameOutputGamma

Remarks: Returns the output gamma of the rendered frames. Prototype:

<job>.frameOutputDevice

Remarks: Returns the device name if a device is specified at render time. Prototype:
<job>.numFrames

Remarks: Returns the total number of frames for the particular job

Working with servers

Various functions and properties can be used to access rendering servers. You can use the getservers() function to retrieve an array of all servers managed by the manager. The servers can be filtered in various ways to return an array based on the filter. Note: Do not to call GetJobs() or GetServers() very often, because these are VERY heavyweight methods. Prototype:
<netManager>.GetServers [filter:#idle | #busy | #absent | #suspended | #error | #group | #job | #handle | #index] [key:<string> | <integer> | <job> ]

Remarks: If used without a filter, GetServers() will return an array of all servers managed by the manager. If there are no servers, the function will return an empty array.
filter:#idle

Returns an array of all idle servers

filter:#busy

Returns an array of all servers busy rendering a job

filter:#absent

Returns an array of all servers that are absent, ie that were connected to the manager at one point but that are either down or the server service or serverapp is not running on it.
filter:#suspended

Returns an array of all suspended servers

Working with servers

399

filter:#error

Returns an array of all servers experiencing an error

filter:#group

Returns an array of servers in a group. Requires that the key option is used, the key can be a group name as a string or a group number as an integer (1 based). An empty array is returned if no groups are defined.
filter:#job

Returns an array of servers that are assigned to the specified job. Requires that the key option be used, the key must be a job definition.
filter:#handle

Returns the server with a given handle (as an array with one item). Requires that the key option be used, the key must be a server handle.
filter:#index

Returns the server at a given index in the server list (as an array with one item). Requires that the key option be used, the key must be an integer (the index).
server = m.getservers()

Prototype:
<server>.GetUpdate()

Remarks: Gets an update on the state of the server. Returns Ok if succesful. Prototype:
<server>.SendUpdate()

Remarks: Updates the server with new settings. Must have queuecontrol. Prototype:
<server>.Delete()

Remarks: Deletes the server from the manager. Must have queuecontrol. Prototype:
<server>.ResetPerformance()

Remarks: Resets the performance metric to 0.0. Must have queuecontrol and must do <server>.sendupdate() to update the server. Prototype:
<server>.netStatus

Remarks: Netstatus Prototype:

<server>.handle

400

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: Returns the servers handle. Read-only Prototype:

<server>.state

Remarks: Returns the state of the server, this can be #idle, #absent, #busy Prototype:
<server>.name

Remarks: Returns the name of the server. Read-only Prototype:

<server>.totalFrames

Remarks: Returns the total number of frames rendered by the server. Read-only Prototype:
<server>.totalTime

Remarks: Returns the total time that the server has been up. The value returned is in hours. Prototype:
<server>.performance

Remarks: Returns the performance index of the server. Read-only Prototype:

<server>.AttendedPriority

Remarks: Returns the priority, as an integer, of the server when the user is logged in.
0 = high priority, 1 = low priority, 2 = idle. Can be changed.

Prototype:
<server>.UnattendedPriority

Working with groups

401

Remarks: Returns the priority level, as an integer, of the server when the system is logged out.
0 = high priority, 1 = low priority, 2 = idle.

Note that this is only valid if running serversvc and the user is not logged in on the system. If running serversvc and a user is logged in on the system then the attendedpriority values are in effect. Can be changed Prototype:
<server>.schedule

Remarks: Returns an array of 7 bitarrays. Each bitarray is a day, each bit is an hour, each bit within that bit array means that the server is available at that hour. A bit array of #{1, 3..5, 15..24} means that the server is available from 12 midnight to 1am, from 3am to 5am and from 3pm to midnight. Prototype:
<server>.jobHandle

Remarks: Returns the handle ot the job it is working on. Will return a value of 0 if no job is being worked on by that server. Prototype:
<server>.jobFrameIndex

Remarks: Returns the frame index of the job that the server is working on. Prototype:
<server>.jobFrameTimeStarted

Remarks: Returns the time at which the frame being rendered was started.

Working with groups

Prototype:
<netManager>.SizeofGroup <index>

Remarks: Returns the number of servers in the nth group. Prototype:

<netManager>.GetGroupName<index>

Remarks: Returns the name of the nth group.

402

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<netManager>.CreateGroup <array> <string>

Remarks: Creates a named group of servers. It takes 2 arguments: an array of servers and a string to define the group name. Prototype:
<netManager>.DeleteGroup <string>

Remarks: Deletes a named group. Takes a string as an argument.

Netstatus
Both manager and servers have a netstatus property. All properties are Read-only.
system = m.netstatus

Prototype:
<system>.SpaceOnDisk <index>

Remarks: Returns the amount of space in megs on a specified disk. The index is 1 based. Disks 1 and 2 are the a: and b: drives. Prototype:
<system>.numDroppedPackets

Remarks: Returns the number of dropped packets. Prototype:

<system>.numBad

Remarks: Returns the number of bad packets. Prototype:

<system>.numTCPRequests

Remarks: Returns the number of TCP requests Prototype:

<system>.numUDPRequests

Remarks: Returns the number of UDP packets Prototype:

<system>.bootTime

Netstatus

403

Remarks: Returns the time at which the system was started. Prototype:
<system>.memorySize

Remarks: Returns the amount of memory of the system. Prototype:

<system>.numProcessors

Remarks: Returns the number of processors in system machine Prototype:

<system>.platformID

Remarks: Returns an integer, a value of 1 indicates win95, a value of 2 indicates WinNT Prototype: <system>.majorVersion Remarks: Returns an integer. When the platformID indicates a WinNT system, a value of 5 or higher here indicates Win2k. Prototype: <system>.minorVersion Remarks: Returns an integer. Win98 is indicated by a minor build greater than 0 for win95 Prototype: <system>.buildNumber Remarks: Returns the build number, this only applies to winnt and win2k. Not supported under win95, win98 or win ME. Prototype: <system>.CSDVersion Remarks: Returns the service pack number of the OS as a string. Prototype: <system>.username

404

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: Returns the login name of the user logged in on the computer or the login name used by the service. Prototype: <system>.tempDir Remarks: Returns the tempdir for the system. Prototype:
<system>.computerName

Remarks: Returns the name of the computer. Prototype:

<system>.workdisk

Remarks: Returns the disk where max is setup. Prototype:

<system>.Disks

Remarks: Returns a bitarray of which disks exist (1=A, 2=B, 3=C etc.) Prototype:
<system>.mac

Remarks: Returns the MAC address of the systems network card. If the computer is a network server, this is its handle.

Examples:
-- ESTABLISHING A CONNECTION -m = netrender.getmanager()--get a NetManager instance --start this session m.connect #manual nimbus -- OR m.connect #manual nimbus port:1234--specifying a port number -- QUEUE CONTROL ---Get QueueControl using GetControl(); --there is no way to release control, but if wantControl==false --then control will be relinquished to the next client --that requests it if( m.QueryControl #wait ) do --only take control if you have permission m.getcontrol() --takes queue control m.wantControl=true--if another client does QueryControl(), they will get a return value of false m.Lock true--this completely prevents others from getting queue control

Examples:

405

m.Lock false--others can now get control -- SUBMITTING JOBS -job = m.newjob file:c:\\share\\test.max job.suspended = true--jobs can be submitted as suspended job.state--should be unsubmitted job.includeMaps = true --turn on Include Maps srv_list = m.getservers() --get the server list to assign to the job job.submit servers:srv_list --specify which servers to use for the job -- job.submit() --this uses all servers for the job -- GETTING JOBS & SERVER OBJECTS -m.SetUpdates false--lock the queue, to make sure nothing changes while you download info j = m.getjobs filter:#suspended--an array of NetJob objects; filters are optinal s = m.getservers filter:#idle--an array of NetServer objects; filters are optinal --see below for other filters... there are many m.SetUpdates true--be sure to unlock the queue! -- WORKING WITH GROUPS -m.creategroup s myGroup--takes an array of NetServers and a name num_groups = m.numGroups--total number of groups size_group1 = m.SizeofGroup 1--number of servers in the first group g = m.getservers filter:#group key:1 --an array of the servers for group 1 g = m.getservers filter:#group key:myGroup--an array of the servers for group myGroup g_name = m.GetGroupName 1--the name of the first group m.deletegroup g_name--delete a group -- WORKING WITH JOBS -job = j[1]--pull a job out of the list jHandle = job.handle--the jobs ID p = job.priority--jobs priority if job.nonSeqFrames==TRUE then frames = job.frames--one of those 1,3,5-12 frame lists else frames = (job.fromFrame as string) + - + (job.toFrame as string) --now frames is 0-100 if 0 and 100 are the start/end frames cameraArray = job.GetCameras()--an array of the camera names l = job.GetLog--the entire log, as text l = job.GetLog start:4 numLines:2 --gets the 4th and 5th entries of the log statText = job.GetServerStatusText s[1] --text about a server, regarding this job num_workers = job.numServers--number of servers on this job job.frameOutputName = d:\\blah.bmp--change the output name isDevice = job.frameOutputDevice--true if the output is to a device, false otherwise share = job.managerShare--the manager share for this job job.filesize--size of the MAZ file for the job job.filesizeextracted--extracted sisze of the MAZ file for the job -- WORKING WITH SERVERS -srv = s[1]--pull a server out of the list sHandle = srv.Handle--the servers ID sName = srv.name--the servers machine name speed = srv.performance--servers performance index

406

Chapter 1

Whats New in 3ds max 4 MAXScript

srv.ResetPerformance()--reset the index timeUsed = srv.totalTime--total time spent rendering sjHandle = srv.jobHandle--the handle of the servers current job, 0 if none sjFrameIndex = srv.jobFrameIndex--the index of the frame the server is rendering --PRACTICAL EXAMPLE; get info about the frame being rendered sjHandle = srv.jobHandle sjIndex = srv.jobFrameIndex sJobs = m.getJobs filter:job key:sjHandle--should be an array with one entry frameInfo = (sJobs[1].getFrameInfo sjIndex)--get info about the current frame frameTime = frameInfo.elapsedTime -- UPDATES FROM MANAGER ---Jobs and Servers support GetUpdate and SendUpdate functions, -- for synchronizing with the manager job.status--should be busy job.Suspend() job.status--still says busy (status value is stale) job.GetUpdate()--download the latest news job.status--now says suspended s[1].GetUpdate()--servers also have Get/SendUpdate -- CALLBACKS --- These are used to listen for messages from the manager, -- They are functions you can define, that will get called when -- the manager has something to say -- There are 6 possible callbacks -- NOTE: you can name these functions anything you want, but they must have correct paramters --NETPROGRESS CALLBACK; Called anytime a download/upload is underway, -- including anytime you fetch information about jobs or servers fn myNetProgress total current =--NOTE: two integer parameters format Progress: completed % out of %\n current total --NETMESSAGE CALLBACK; Called when the manager has a text message for the user fn myNetMessage msg =--NOTE: one string parameter format Message: %\n msg --UPDATE CALLBACK; Called when something has changed, like a job started or finished -- Lets you know when you need to make GetUpdate calls, or other refreshing fn myUpdate = job.GetUpdate()--example of what you might do --MANAGERDOWN CALLBACK; Called when the manager dies fn myManagerDown = format Manager is dead\n --QUEUECONTROL CALLBACK; Called whenever queue control changes fn myQueueControl = format Queue control has changed\n --QUERYCONTROL CALLBACK; Called when you have Queue Control, and another computer wants it fn myQueryControl clientName = (--NOTE: one string parameter format The computer % wants queue control clientName m.wantControl = true-- use this to keep queue control

Examples:

407

m.wantControl = false-- use this to release queue control ) --INSTALLING THE CALLBACKS; after you define the functions, you must give them to the -- manager as follows --NOTE: only one callback of each type is allowed (e.g., you cant have two Update callbacks) m.setcallback #Progress myNetProgress--install the Progress callback m.setcallback #MessagemyNetMessage --install the Message callback m.setcallback #UpdatemyUpdate--install the Update callback m.setcallback #ManagerDown myManagerDown --install the ManagerDown callback m.setcallback #QueueControl myQueueControl --install the QueueControl callback m.setcallback #QueryControl myQueryControl --install the QueryControl callback -- NETSTATUS OBJECTS ---Read-only information about a computer on the network stat = s[1].netStatus--get network info about server 1 stat.boottime--make a query stat.Disks-d = stat.workDisk--which is the disk for net-rendering work? stat.SpaceOnDisk d--megabytes of free space on the workdisk stat.memorySize--computers memory in bytes (note: 1 meg = 1048576 bytes) s[1].GetUpdate()--this refreshes the netStatus object stat = m.netStatus--manager also has a NetStatus --NOTE: Manager has no GetUpdate(), you must fetch the NetStatus again to see any changes --To print out the operating system on the machine... --Win95 has a platformID of 1; WinNT has a platformID of 2 --Win2K is indicated by a majorBuild of 5 or more for WinNT --Win98 is indicated by a minorBuild greater than 0 for Win95. --Also, build number and the CSDVersion string are not supported by Win95/98 format Windows %.%, Build %, %\n \ stat.majorVersion stat.minorVersion stat.buildNumber stat.CSDVersion -- JOBFRAME OBJECTS -num_frames = job.numFrames() frame = job.getFrameInfo 1 --get info about the 1st frame elapsed_time = frame.ElapsedTime --amount of time frame has been rendering num_rendElems = job.numRenderElements()--number of render elements for render if num_rendElems>0 do ( rendElem = job.GetRenderElement 1--pass the index of the element rendElem.enabled = false--turn off the rend element job.SetRenderElement 1 rendElem--update the job with the new changes job.SendUpdate()--upload the changes ) -- JOBSERVER OBJECTS ---Read-only information about a server, in relation to a particular job j_num_servers = j[1].numServers--how many servers does the job have? js = j[1].GetServerInfo 1--info about the jobs first server sh = js.serverHandle--whats the servers handle? sn = js.serverName--whats the servers name? isWorker = js.active--whether this server participates in this job js_state = js.state--is the server busy with the job? has an error? etc

408

Chapter 1

Whats New in 3ds max 4 MAXScript

--Print out some stats format rendering frame %, completed %, total time % hours\n \ js.currentFrame js.numFramesComplete js.elapsedTime --ways to get more info about this server... jSrv = m.GetServers filter:#handle key:sh--get the actual server object statText = j[1].GetServerStatusText jSrv[1]--text info from the server about this job -- RENDERELEMENT OBJECTS ---Information about particular render elements for a job n = j[1].numRenderElements--how many render elements for this job? re = j[1].GetRenderElement 1--get the first one re.enabled = false--disable it re.filterEnabled = false--disable filtering re.name = newName--change its name useShadows = re.shadowsApplied--are shadows applied? (read-only) useShadows = re.atmosphereApplied--are atmospherics applied (read-only) re.output = C:\\share\\rendElem1.bmp--change its output path & name j[1].SetRenderElement 1 re--update the job with the new changes j[1].SendUpdate--upload the changes -- WEEKLY SCHEDULES --- a servers weekly schedule is an array of seven BitArrays; -- Each bitArray is a day, each bit is an hour sched = s[1].schedule sched[1][11] = false--sunday 11am, the server will not work sched[1][12] = false -- same for sunday noon s[1].attendedPriority = 60--set the priorities for the servers schedule s[1].unattendedPriority = 10 s[1].schedule = sched--set the new schedule s[1].schedule --printout to prove the change worked s[1].SendUpdate()--upload the changes to this server --NOTE: a Schedule is just a BitArray and has no GetUpdate, --you must fetch it again from the server to see any changes -- MISCELANEOUS FUNCTIONS -jobList = #( j[3], j[1], j[2] )--make an array of some jobs m.SetJobOrder jobList--rearrange the jobs; e.g. j[3] is now the first in the queue mName = (m.netStatus).computerName --the machine name of the manager -- JOB & SERVER FILTERS -jobServers = m.getservers filter:#Job key:j[1] groupServers = m.getservers filter:#group key:Clouds -- ENDING THE SEESION -m.wantControl=true--other clients can now get QueueControl m.disconnect()--end this session -- m.kill()--brings down the manager, (would need queue control)

Interface: NullInterface

409

Interface: NullInterface
Interface: NullInterface Note: Intentionally blank.

Interface: objXRefs
Interface: objXRefs Methods: Prototype:
<maxObject>addNewXRefObject <filename>fname <string>objname <boolean>proxy

Parameters:
<filename>fname <string>objname <boolean>proxy

Prototype:
<integer>getNumXRefObjects <filename>fname

Parameters:
<filename>fname

Prototype:
<maxObject>getXRefObject <filename>fname <index>index

Parameters:
<filename>fname <index>index

Prototype:
<integer>getNumFiles()

Prototype:
<filename>getFileName <index>index

Parameters:
<index>index

Prototype:
<boolean>reloadFile <filename>fname

Parameters:
<filename>fname

Return Value: True if successful and false otherwise. Prototype:

<boolean>isFileUnresolved <filename>fname

410

Chapter 1

Whats New in 3ds max 4 MAXScript

Parameters:
<filename>fname

Return Value: True if successful and false otherwise. Prototype:

<boolean>isFileDisabled <filename>fname

Parameters:
<filename>fname

Return Value: True if successful and false otherwise.

See Also
XRefObject : Node (p. 1037) XRefScene Values (p. 1038) XRef Files (p. 1643)

Interface: paramWire
Parameter Wiring (p. 85) This class represents the interface that provides general access to the parameter wiring functions. Prototype:
<void>start()

Remarks: This method will launch the parameter wiring UI mode on the currently selected object. Only works if there is a single object selected in the viewport. It will move the cursor to the pivot point of the node. Example: It might be used in a macroScript like this:
macroScript paramWire category:Tools buttonText:Wire Parameters tooltip:Start Param Wiring Icon:#(MAXScript,1) ( on execute do paramWire.start() on isEnabled return selection.count == 1 )

Prototype:
<void>openEditor()

Interface: paramWire

411

Remarks: This method will open up the parameter wiring dialog on the selected objects with no track selected in either tree view. Prototype:
<void>editParams <value>leftParam <value>rightParam

Remarks: Opens the parameter wiring editor dialog on the parameters specified. The parameter is specified as a SubAnim in MAXScript, via the index [] operator on a MAX object. Parameters:
<value>leftParam

The sub-animatable of the left-hand reference target.

<value>rightParam

The sub-animatable of the right-hand reference target. Note: The subanim index operator can also take number indexes. Prototype:
<void>editParam <value>param

Remarks: Opens the parameter wiring editor dialog on the parameter specified. The parameter is specified as a SubAnim in MAXScript, via the index [] operator on a MAX object. Parameters:
<value>param

The sub-animatable of the left-hand reference target. Example:

-- The radius parameter in a sphere node paramWire.editParam $sphere01.baseObject[#radius] -- The angle parameter in a bend modifier would be paramWire.editParam $foo.bend[#angle] -- The position parameter in node would be paramWire.editParam $foo[#transform][#position], etc.

Prototype:
<void>editControllers <control>leftController <control>rightController

Remarks: Opens the parameter wiring editor dialog on the two given existing wire controllers. Parameters:
<control>leftController

A pointer to the controller for the left-hand wire.

<control>rightController

A pointer to the controller for the right-hand wire.

412

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<void>editController <control>controller

Remarks: Opens the parameter wiring editor dialog on the given existing wire controller. Parameters:
<control>controller

A pointer to the controller being edited. Example:

paramWire.editController $foo.radius.controller

Prototype:
<bool>connect <value>fromParam <value>toParam <string>toExpr

Remarks: This method allows you to set up a one-way parameter wire from the fromParam subAnim to the toParam subAnim, using the toExpr as the expression for the controlled parameter. Parameters:
<value>fromParam

The sub-animatable to wire from.

<value>toParam

The sub-animatable to wire to.

<string>toExpr

A string containing the expression on the to wire. Return Value: TRUE if the connection can be made, otherwise FALSE. Example:
paramWire.connect $foo.baseObject[#radius] $baz.bend[#angle] radius / 2

Prototype:
<bool>connect2Way <value>leftParam <value>rightParam <string>leftExpr <string>rightExpr

Remarks: This method allows you to set up a two-way parameter wire between the leftParam parameter and the rightParam parameter, with the given expression strings. Parameters:
<value>leftParam

The sub-animatable of the left-hand reference target.

<value>rightParam

The sub-animatable of the right-hand reference target.

Interface: paramWire

413

<string>leftExpr

A string containing the expression for the left-hand target.

<string>rightExpr

A string containing the expression for the right-hand target. Return Value: TRUE if the connection can be made, otherwise FALSE. Example:
paramWire.connect2Way $foo.baseObject[#radius] $baz.bend[#angle] \ angle / 2 radius * 2

Prototype:
<bool>disconnect <control>controller

Remarks: This method allows you to disconnect a one-way wireController from its current parameter, replacing it with either the wires existing animation track or a default controller for the parameter. Parameters:
<control>controller

A pointer to the wire controller you wish to disconnect. Return Value: TRUE if the disconnect was successful, otherwise FALSE. Prototype:
<bool>disconnect2Way <control>leftController <control>rightController

Remarks: This method allows you to disconnect a two-way wire between leftcontroller and rightController. If this is the last two-way wire for either controller, replace it with either the the wires existing animation track or a default controller for the parameter. Parameters:
<control>leftController

A pointer to the first wire controller you wish to disconnect.

<control>rightController

A pointer to the second wire controller you wish to disconnect. Return Value: TRUE if the disconnect was successful, otherwise FALSE.

See Also
In The MAXSDK Help File Class IParamWireMgr

414

Chapter 1

Whats New in 3ds max 4 MAXScript

Interface: pluginManager
Interface: pluginManager Properties:
.visible : boolean : Read|Write

Remarks:
Show and hide the plug-in manager.

Methods:
<void>loadClass <class>class

Remarks: Will ensure that the given class is loaded, in the event that it is a deferred loading class, and so any MAXScript methods or Function Published interfaces it publishes will be available. Parameters:
<class>class

Example:
plug-inManager.loadClass Flex

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

See Also
Interface: pluginManager (p. 414) Plugin_Manager interfaces: (p. 473)

Interface: quadMenuSettings
This represents an interface for quad menu settings. Note: PickObject() does not pick objects when launched from a Quad Menu. It will hang and refuses to pick any object. Hit escape for emergency exit. PickObject works correctly from a shortcut and toolbar. Prototype:
<void>ResetDefaults()

Remarks: This method will reset the menu settings to their defaults. Prototype:
<void>SetBorderSize <integer>borderSize

Interface: quadMenuSettings

415

Remarks: This method allows you to set the menu border size. Parameters:
<integer>borderSize

The border size in pixels. Prototype:

<integer>GetBorderSize()

Return Value: This method returns the menu border size. Prototype:
<void>SetHorizontalMarginInPoints <integer>horizontalMarginInPoints

Remarks: This method allows you to set the menus horizontal margin size. Parameters:
<integer>horizontalMarginInPoints

The horizontal margin size in points. Prototype:

<integer>GetHorizontalMarginInPoints()

Return Value: This method returns the menus horizontal margin size (in points). Prototype:
<void>SetVerticalMarginInPoints <integer>verticalMarginInPoints

Remarks: This method allows you to set the menus vertical margin size. Parameters:
<integer>verticalMarginInPoints

The vertical margin size in points. Prototype:

<integer>GetVerticalMarginInPoints()

Return Value: This method returns the menus vertical margin size (in points). Prototype:
<void>SetItemFontFace <string>szItemFontFace

Remarks: This method allows you to set the menu items font typeface.

416

Chapter 1

Whats New in 3ds max 4 MAXScript

Parameters:
<string>szItemFontFace

A string containing the typeface name. Prototype:

<string>GetItemFontFace()

Return Value: This method returns the name of the menu items font typeface. Prototype:
<void>SetTitleFontFace <string>szTitleFontFace

Remarks: This method allows you to set the menu titles font typeface. Parameters:
<string>szTitleFontFace

A string containing the typeface name. Prototype:

<string>GetTitleFontFace()

Return Value: This method returns the name of the menu titles font typeface. Prototype:
<void>SetItemFontSize <integer>itemFontSize

Remarks: This method allows you to set the menu items font size. Parameters:
<integer>itemFontSize

The size of the font, in points. Prototype:

<integer>GetItemFontSize()

Return Value: This method returns the menu items font size, in points. Prototype:
<void>SetTitleFontSize <integer>titleFontSize

Remarks: This method allows you to set the menu titles font size. Parameters:
<integer>titleFontSize

The size of the font, in points.

Interface: quadMenuSettings

417

Prototype:
<integer>GetTitleFontSize()

Return Value: This method returns the menu titles font size, in points. Prototype:
<void>SetUseUniformItemHeight <boolean>useUniformItemHeight

Remarks: This method allows you to set the status of a menu items uniform height flag. Parameters:
<boolean>useUniformItemHeight

TRUE to set the uniform height flag ON, FALSE to set it to OFF. Prototype:
<boolean>GetUseUniformItemHeight()

Return Value: This method returns TRUE or FALSE if the menu items uniform height flag is set or not set, respectively. Prototype:
<void>SetOpacity <float>opacity

Remarks: This method allows you to set the menus opacity value. Parameters:
<float>opacity

The opacity value, ranging from 0.0 1.0 where 1 is opaque. Prototype:
<float>GetOpacity()

Return Value: This method returns the menus opacity value. Prototype:
<void>SetDisplayMethod <integer>displayMethod

Remarks: This method allows you to set a menus display method. Parameters:
<integer>displayMethod

The display method which is one of the following:

0 - displays the menu with transparency, if opacity is < 1. 1 - stretch animate the menu by making it grow in size from its center with transparency, if opacity is < 1. 2 - fade in from invisible to whatever opacity is set to.

418

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<integer>GetDisplayMethod()

Return Value: This method returns the menus display method, which is either of the following; DM_NORMAL, DM_STRETCH, DM_FADE, DM_NUM_METHODS Prototype:
<void>SetAnimatedSteps <integer>animatedSteps

Remarks: This method allows you to set the menus number of animated steps for the growing effect. Parameters:
<integer>animatedSteps

The number of steps. Prototype:

<integer>GetAnimatedSteps()

Return Value: This method returns the menus number of animated steps used for the growing effect. Prototype:
<void>SetAnimatedStepTime <integer>animatedStepTime

Remarks: This method allows you to set the menus animated step time. Parameters:
<integer>animatedStepTime

The animated step time, in milliseconds. Prototype:

<integer>GetAnimatedStepTime()

Return Value: This method returns the menus animated step time, in milliseconds. Prototype:
<void>SetSubMenuPauseTime <integer>subMenuPauseTime

Remarks: This method allows you to set the delay before a submenu is displayed. Parameters:
<integer>subMenuPauseTime

The delay, in milliseconds. Prototype:

<integer>GetSubMenuPauseTime()

Interface: quadMenuSettings

419

Return Value: This method returns the delay before a submenu is displayed, in milliseconds. Prototype:
<void>SetUseLastExecutedItem <boolean>useLastSelectedItem

Remarks: This method allows you to set the last executed item flag which determines whether to use the menus last executed item when the user clicks on the menus titlebar. Parameters:
<boolean>useLastSelectedItem

Prototype:
<boolean>GetUseLastExecutedItem()

Return Value: This method returns whether the last executed item flag is set (TRUE) or not set (FALSE). The flag determines whether to use the menus last executed item when the user clicks on the menus titlebar. Prototype:
<void>SetRepositionWhenClipped <boolean>repositionWhenClipped

Remarks: This method allows you to set the flag which controls and determines whether the menu is repositioned when near the edge of the screen. Parameters:
<boolean>repositionWhenClipped

TRUE to turn repositioning ON, FALSE to turn it OFF. Prototype:

<integer>GetRepositionWhenClipped()

Remarks: This method returns the status of the flag which controls and determines whether the menu is repositioned when near the edge of the screen. Return Value: TRUE if the flag is ON, otherwise FALSE. Prototype:
<void>SetRemoveRedundantSeparators <boolean>removeRedundantSeparators

Remarks: This method allows you to set the flag which controls and determines whether the menu should remove redundant separators. Parameters:
<boolean>removeRedundantSeparators

TRUE to turn the flag ON, FALSE to turn it OFF.

420

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<integer>GetRemoveRedundantSeparators()

Remarks: This method returns the status of the flag which controls and determines whether the menu should remove redundant separators. Return Value: TRUE if the flag is ON, otherwise FALSE. Prototype:
<void>SetFirstQuadDisplayed <integer>firstQuadDisplayed

Remarks: This method allows you to set the first quad which will be displayed when a quad menu pops up. Parameters:
<integer>firstQuadDisplayed

The quad index, one of the following; QUAD_ONE, QUAD_TWO, QUAD_THREE, or QUAD_FOUR. Prototype:
<integer>GetFirstQuadDisplayed()

Remarks: This method returns the index of the first quad which will be displayed. Return Value: The quad index, one of the following; QUAD_ONE, QUAD_TWO, QUAD_THREE, or QUAD_FOUR. Prototype:
<void>SetUseUniformQuadWidth <boolean>useUniformQuadWidth

Remarks: This method allows you to set whether the quad menu has a uniform width. Parameters:
<boolean>useUniformQuadWidth

TRUE to set the uniform width, FALSE to set it to non-uniform. Prototype:

<boolean>GetUseUniformQuadWidth()

Return Value: This method returns the status of the uniform width flag for the quad menu. TRUE if the quad menu has been set to use uniform width, otherwise FALSE. Prototype:
<void>SetMirrorQuad <boolean>mirrorQuad

Remarks: This method allows you to set whether the quad menus are mirrored left to right.

Interface: quadMenuSettings

421

Parameters:
<boolean>mirrorQuad

TRUE to mirror the menus, otherwise FALSE. Prototype:

<integer>GetMirrorQuad()

Return Value: This method returns TRUE if the quad menu is mirrored left to right, otherwise FALSE. Prototype:
<void>SetMoveCursorOnReposition <boolean>moveCursorOnReposition

Remarks: This method allows you to set whether the cursor moves when the quad menu is repositioned because of clipping the edge of the screen. Parameters:
<boolean>moveCursorOnReposition

TRUE to move the cursor, otherwise FALSE. Prototype:

<boolean>GetMoveCursorOnReposition()

Return Value: This method returns TRUE if the cursor moves when the quad menu is repositioned because of clipping the edge of the screen, otherwise FALSE. Prototype:
<void>SetReturnCursorAfterReposition <boolean>returnCursorAfterReposition

Remarks: This method allows you to set whether the cursor is moved the opposite distance that it was automatically moved when the quad menu is repositioned because of clipping the edge of the screen. Parameters:
<boolean>returnCursorAfterReposition

TRUE to set the flag, otherwise FALSE. Prototype:

<boolean>GetReturnCursorAfterReposition()

Return Value: This method returns TRUE if the cursor is moved the opposite distance that it was automatically moved when the quad menu is repositioned because of clipping the edge of the screen, otherwise FALSE. Prototype:
<void>SetInitialCursorLocInBox_0to1 <float>initialCursorLocX <float>initialCursorLocY

422

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method allows you to set the initial location of the cursor in the center quad box. Parameters:
<float>initialCursorLocX <float>initialCursorLocY

The location of the cursor, as a ratio of the box size, between 0.0 and 1.0. Prototype:
<float>GetInitialCursorLocXInBox_0to1()

Return Value: This method returns the initial x location of the cursor in the center quad box, as a ratio of the box size, between 0.0 and 1.0. Prototype:
<float>GetInitialCursorLocYInBox_0to1()

Return Value: This method returns the initial y location of the cursor in the center quad box, as a ratio of the box size, between 0.0 and 1.0. Prototype:
<void>SetTitleBarBackgroundColor <integer>quad <&RGBA color>color

Remarks: This method allows you to set the title bar background color for a specific quad. color is In parameter Parameters:
<integer>quad

The quad (numbered 1 through 4).

<&RGBA color>color

The color to set. Prototype:

<&RGBA color>GetTitleBarBackgroundColor <integer>quad

Parameters:
<integer>quad

The quad (numbered 1 through 4). Return Value: This method returns the title bar background color of a specific quad. This method returns the color as a Color. Prototype:
<void>SetTitleBarTextColor <integer>quad <&RGBA color>color

Interface: quadMenuSettings

423

Remarks: This method allows you to set the title bar text color for a specific quad. color is In parameter Parameters:
<integer>quad

The quad (numbered 1 through 4).

<&RGBA color>color

The color to set. Prototype:

<&RGBA color>GetTitleBarTextColor <integer>quad

Parameters:
<integer>quad

The quad (numbered 1 through 4). Return Value: This method returns the title bar text color of a specific quad. This method returns the color as a Color Prototype:
<void>SetItemBackgroundColor <integer>quad <&RGBA color>color

Remarks: This method allows you to set the item background color for a specific quad. color is In parameter Parameters:
<integer>quad

The quad (numbered 1 through 4).

<&RGBA color>color

The color to set. Prototype:

<&RGBA color>GetItemBackgroundColor <integer>quad

Parameters:
<integer>quad

The quad (numbered 1 through 4). Return Value: This method returns the item background color of a specific quad. This method returns the color as a Color. Prototype:
<void>SetItemTextColor <integer>quad <&RGBA color>color

424

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method allows you to set the item text color for a specific quad. color is In parameter Parameters:
<integer>quad

The quad (numbered 1 through 4).

<&RGBA color>color

The color to set. Prototype:

<&RGBA color>GetItemTextColor <integer>quad

Parameters:
<integer>quad

The quad (numbered 1 through 4). Return Value: This method returns the item text color of a specific quad. This method returns the color as a Color. Prototype:
<void>SetLastExecutedItemTextColor <integer>quad <&RGBA color>color

Remarks: This method allows you to set the last executed item text color for a specific quad. color is In parameter Parameters:
<integer>quad

The quad (numbered 1 through 4).

<&RGBA color>color

The color to set. Prototype:

<&RGBA color>GetLastExecutedItemTextColor <integer>quad

Parameters:
<integer>quad

The quad (numbered 1 through 4). Return Value: This method returns the last executed item text color of a specific quad. This method returns the color as a Color. Prototype:
<void>SetHighlightedItemBackgroundColor <integer>quad <&RGBA color>color

Remarks: This method allows you to set the highlighted item background color for a specific quad. Color is In parameter.

Interface: quadMenuSettings

425

Parameters:
<integer>quad

The quad (numbered 1 through 4).

<&RGBA color>color

The color to set. Prototype:

<&RGBA color>GetHighlightedItemBackgroundColor <integer>quad

Parameters:
<integer>quad

The quad (numbered 1 through 4). Return Value: This method returns the highlighted item background color of a specific quad. This method returns the color as a Color. Prototype:
<void>SetHighlightedItemTextColor <integer>quad <&RGBA color>color

Remarks: This method allows you to set the highlighted item text color for a specific quad. color is In parameter Parameters:
<integer>quad

The quad (numbered 1 through 4).

<&RGBA color>color

The color to set. Prototype:

<&RGBA color>GetHighlightedItemTextColor <integer>quad

Parameters:
<integer>quad

The quad (numbered 1 through 4). Return Value: This method returns the highlighted item text color of a specific quad. This method returns the color as a Color. Prototype:
<void>SetBorderColor <integer>quad <&RGBA color>color

Remarks: This method allows you to set the border color for a specific quad. color is In parameter

426

Chapter 1

Whats New in 3ds max 4 MAXScript

Parameters:
<integer>quad

The quad (numbered 1 through 4).

<&RGBA color>color

The color to set. Prototype:

<&RGBA color>GetBorderColor <integer>quad

Parameters:
<integer>quad

The quad (numbered 1 through 4). Return Value: This method returns the border color of a specific quad. This method returns the color as a Color. Prototype:
<void>SetDisabledShadowColor <integer>quad <&RGBA color>color

Remarks: This method allows you to set the disabled shadow color for a specific quad. color is In parameter Parameters:
<integer>quad

The quad (numbered 1 through 4).

<&RGBA color>color

The color to set. Prototype:

<&RGBA color>GetDisabledShadowColor <integer>quad

Parameters:
<integer>quad

The quad (numbered 1 through 4). Return Value: This method returns the disabled shadow color of a specific quad. This method returns the color as a Color. Prototype:
<void>SetDisabledHighlightColor <integer>quad <&RGBA color>color

Interface: rollup

427

Remarks: This method allows you to set the disabled highlight color for a specific quad. color is In parameter Parameters:
<integer>quad

The quad (numbered 1 through 4).

<&RGBA color>color

The color to set. Prototype:

<&RGBA color>GetDisabledHighlightColor <integer>quad

Parameters:
<integer>quad

The quad (numbered 1 through 4). Return Value: This method returns the disabled highlight color of a specific quad. This method returns the color as a Color.

See Also
In The MAXSDK Help File Class IMenuSettings

See Also
Menu Manager (p. 75) Interface: menuMan (p. 372)

Interface: rollup
Interface: rollup Note: Intentionally blank.

Interface: SceneExposureControl
Interface: SceneExposureControl Properties:
.exposureControl : maxObject : Read|Write|Validated by

428

Chapter 1

Whats New in 3ds max 4 MAXScript

Interface: SceneRadiosity
Interface: SceneRadiosity Properties:
.radiosity : maxObject : Read|Write|Validated by

Methods: Prototype:
<void>showPanel()

Remarks: The radiosity panel is disabled from the scriptor when there are no radiosity plugins registered. In this case the SceneRadiosity.showPanel() function published method doesnt do anything. Prototype:
<void>closePanel()

Prototype:
<void>minimizePanel()

Interface: timeSlider
This represents the interface for the time slider.

Methods:
Prototype:
<void>setVisible <boolean>visible

Remarks: This method allows you to set the visibility flags of the time slider. This Setting is sticky across sessions and will be stored in the ini file. Parameters:
<boolean>visible

TRUE to set the time slider visible, otherwise FALSE. Prototype:

<boolean>isVisible()

Return Value: This method returns TRUE if the time slider is visible, otherwise FALSE.

See Also
In The MAXSDK Help File Class ITimeSlider

Interface: trackviews

429

Interface: trackviews
Interface: trackviews Properties:
.currentTrackView : Interface : Read .lastUsedTrackViewName : string : Read

Methods: Prototype:
<Interface>getTrackView <fpvalue>name or index

Parameters:
<fpvalue>name or index

Return Value: This method will get a trackview based on its index or name. Prototype:
<Interface by value array>getAllOpenTrackViews()

Return Value: Returns an array of trackviews. Prototype:

<integer>numTrackViews()

Return Value: Returns the number of trackviews. Prototype:

<boolean>open <fpvalue>name or index

Parameters:
<fpvalue>name or index

Return Value: Open a trackview based on its index or name. Prototype:

<boolean>close <fpvalue>name or index

Parameters:
<fpvalue>name or index

Return Value: Close a trackview based on its index or name. Prototype:

<void>delete <fpvalue>name or index

430

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: Parameters:
<fpvalue>name or index

Prototype:
<string>getTrackViewName <index>index

Parameters:
<index>index

Return Value: Returns the name of the trackview window based on the index. Prototype:
<boolean>zoomSelected <TSTR>name

Parameters:
<TSTR>name

Return Value: Zooms to the selected objects track Prototype:

<boolean>zoomOn <TSTR>name <maxObject>object <index>subNum

Parameters:
<TSTR>name <maxObject>object <index>subNum

Return Value: True if successful and false otherwise. Prototype:

<boolean>setFilter()

Remarks: setFilter has variable number of arguments Return Value: True if successful and false otherwise. Prototype:
<boolean>clearFilter()

Remarks: clearFilter has variable number of arguments Return Value: True if successful and false otherwise. Prototype:
<fpvalue by value>pickTrackDlg()

Interface: trackviews

431

Remarks: pickTrackDlg has variable number of arguments Return Value: This method brings up the Track View Pick dialog and returns a TrackViewPick value when the user selects a track and clicks Ok, or undefined if the user clicks Cancel. If the optional argument #multiple is passed, multiple tracks can be picked in the dialog and an array of TrackViewPick values is returned instead of single value. Prototype:
<boolean>isOpen <fpvalue>name or index

Parameters:
<fpvalue>name or index

Return Value: Returns a boolean value indicating if the specified trackview is open. Prototype:
<boolean>openLastUsedTrackView()

Return Value: Opens the current trackview if it has been closed. Prototype:
<boolean>isCurrent <fpvalue>name or index

Parameters:
<fpvalue>name or index

Return Value: Returns a boolean value indicating if the trackview is the last one used or not. Prototype:
<boolean>setCurrent <fpvalue>name or index

Parameters:
<fpvalue>name or index

Return Value: Sets the specified trackview to be the current one. Returns true if successful.

See Also
Track View Pick Dialog (p. 1617)

432

Chapter 1

Whats New in 3ds max 4 MAXScript

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

Interface: trackviews

433

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

434

Chapter 1

Whats New in 3ds max 4 MAXScript

Rotation Wire (p. 508) Scale Wire (p. 515)

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

Other Interface Pages

bitmapTex interfaces:
bitmapTex interfaces: Interface: bitmapTex Methods: Prototype:
<void>reload()

Remarks: Reloads the bitmap file using the same name and path. You dont need to use the file browser to reload the bitmap after youve updated it in your paint program. Clicking reload for any instance of the map updates the map in all sample slots and in the scene. Prototype:
<void>viewImage()

Remarks: Displays a Virtual Frame Buffer that shows the bitmap surrounded by a region outline. The region outline has handles at its sides and corners. When cropping is on, dragging the handles changes the size of the crop area. You can also drag within the region area to move it. The VFB editing window has U/V and W/H (width/height) spinners on its toolbar. Use these to adjust the location and size the image or crop area. When Place is turned on, dragging the region area handles changes the scale of the bitmap (hold down CTRL to preserve the bitmaps aspect ratio), and dragging the image changes its location within the tile area. When Crop is turned on, the UV or XY button at the right of the virtual frame buffer toolbar lets you switch between using UV or XY coordinates in the toolbar spinners. Also, you can zoom out by pressing SHIFT+Z and zoom in by pressing Z.

Block_Control interfaces:

435

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

Block_Control interfaces:
Interface: list Properties:
.count : integer : Read .active : index : Read|Write

Methods: Prototype:
<integer>getCount()

Remarks: This method returns the number of items that appear in the List controllers list box. Prototype:
<void>setActive <index>listIndex

Remarks: This method allows you to sets the indexed item in the list active so its parameters appear in the motion panel, and any input is directed to the indexed sub controller. Parameters:
<index>listIndex

The index of the item to set as the active item. Prototype:

<integer>getActive()

Remarks: This method returns the index of the currently active item. Prototype:
<void>delete <index>listIndex

436

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method allows you to delete the indexed sub controller from the list. Parameters:
<index>listIndex

The index of the item to delete from the list. Prototype:

<void>cut <index>listIndex

Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later. Parameters:
<index>listIndex

The index of the item you wish to cut. Prototype:

<void>paste <index>listIndex

Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters:
<index>listIndex

The index of the slot to paste into. Prototype:

<TSTR by value>getName <index>listIndex

Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesnt exist. Parameters:
<index>listIndex

The index of the item for which to get the name. Prototype:
<void>setName <index>listIndex <string>name

Remarks: This method allows you to set the name of an indexed item. Parameters:
<index>listIndex

The index of the item.

<string>name

The name to set it to.

BMP interfaces:

437

See Also
In the MAXSDK Help File Class IListControl

BMP interfaces:
This represents the interface for the Bitmap IO BMP format. Interface: ibmpio Methods: Prototype:
<enum>getType() getType enums: {#noType|#paletted|#true24}

Return Value: This method returns the format type, which is one of the enum types. Note: #noType is equivalent to #true24 Prototype:
<void>setType <enum>type type enums: {#noType|#paletted|#true24}

Remarks: This method allows you to set the format type. Parameters:

<enum>type
The type, which is one of the enum types. Note: #noType is equivalent to #true24

See Also
In The MAXSDK Help File Class IBitmapIO_Bmp

438

Chapter 1

Whats New in 3ds max 4 MAXScript

Flex interfaces:
Flex interfaces: Interface: flexOps Methods: Prototype:
<void>paint()

Prototype:
<void>setReference()

Prototype:
<void>reset()

Prototype:
<void>addForce <node>force

Parameters: <node>force Prototype:

<void>removeForce <integer>force

Parameters:
<integer>force

Prototype:
<integer>numberVertices()

Prototype:
<void>selectVertices <bitArray>sel <boolean>update

Parameters:
<bitArray>sel <boolean>update

Prototype:
<bitArray>getSelectedVertices()

Prototype:
<float>getVertexWeight <integer>index

Parameters:
<integer>index

Prototype:
<void>setVertexWeight <int array>indices <float array>values

Parameters:
<int array>indices <float array>values

Prototype:
<void>setEdgeList <bitArray>sel <boolean>update

Flex interfaces:

439

Parameters:
<bitArray>sel <boolean>update

Prototype:
<bitArray>getEdgeList()

Prototype:
<void>addSpringFromSelection <integer>flag <boolean>addDuplicates

Parameters:
<integer>flag <boolean>addDuplicates

Prototype:
<void>addSpring <integer>indexA <integer>indexB <integer>flag <boolean>addDuplicates

Parameters:
<integer>indexA <integer>indexB <integer>flag <boolean>addDuplicates

Prototype:
<void>removeAllSprings()

Prototype:
<void>addSpringButton()

Prototype:
<void>removeSpringButton()

Prototype:
<void>optionsButton()

Prototype:
<void>createSimpleSoftButton()

Prototype:
<void>removeSpringByEnd <integer>a

Parameters:
<integer>a

Prototype:
<void>removeSpringByEnds <integer>a <integer>b

Parameters:
<integer>a <integer>b

440

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<void>removeSpringByIndex <integer>index

Parameters:
<integer>index

Prototype:
<integer>numberSprings()

Prototype:
<integer>getSpringGroup <integer>index

Parameters:
<integer>index

Prototype:
<void>setSpringGroup <integer>index <integer>group

Parameters:
<integer>index <integer>group

Prototype:
<float>getSpringLength <integer>index

Parameters:
<integer>index

Prototype:
<void>setSpringLength <integer>index <float>length

Parameters:
<integer>index <float>length

Prototype:
<integer>getIndex <integer>a <integer>b

Parameters:
<integer>a <integer>b

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

float_list interfaces:

441

float_list interfaces:
float_list interfaces: This class represents the interface to the list controller. Interface: list Properties:
.count : integer : Read .active : index : Read|Write

Methods: Prototype:
<integer>getCount()

Remarks: This method returns the number of items that appear in the List controllers list box. Prototype:
<void>setActive <index>listIndex

Remarks: This method allows you to sets the indexed item in the list active so its parameters appear in the motion panel, and any input is directed to the indexed sub controller. Parameters:
<index>listIndex

The index of the item to set as the active item. Prototype:

<integer>getActive()

Remarks: This method returns the index of the currently active item. Prototype:
<void>delete <index>listIndex

Remarks: This method allows you to delete the indexed sub controller from the list. Parameters:
<index>listIndex

The index of the item to delete from the list. Prototype:

<void>cut <index>listIndex

Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

442

Chapter 1

Whats New in 3ds max 4 MAXScript

Parameters:
<index>listIndex

The index of the item you wish to cut. Prototype:

<void>paste <index>listIndex

Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters:
<index>listIndex

The index of the slot to paste into. Prototype:

<TSTR by value>getName <index>listIndex

Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesnt exist. Parameters:
<index>listIndex

The index of the item for which to get the name. Prototype:
<void>setName <index>listIndex <string>name

Remarks: This method allows you to set the name of an indexed item. Parameters:
<index>listIndex

The index of the item.

<string>name

The name to set it to.

See Also
In the MAXSDK Help File Class IListControl

Float Reactor interfaces:

443

Float Reactor interfaces:

Float Reactor interfaces: Interface: reactions Properties:
.editStateMode : boolean : Read|Write

This property sets or gets the state of the Edit Reaction State toggle.
.useCurve : boolean : Read|Write

Specifies whether or not to use the curve. Methods: Prototype:

<void>reactTo <maxObject>object

Parameters:
<maxObject>object

The object to react to. This can either be a controller or a node. The default influence value depends on the time the reaction was created. Remarks: This is a time variant function so it will use the MAXScript time context instead of requiring a Time value as an argument. Prototype:
<boolean>create name:<string> name default value: scriptCreated

Create a new reaction and give it a name. The default influence value depends on the time the reaction was created. Remarks: This is a time variant function. It will also use the name supplied if there is one, but a name is not necessary. Return Value: True if successful and false otherwise. Note: All index parameters below are 1-based. Prototype:
<boolean>delete <index>index

Parameters:
<index>index

Return Value: Returns true is successful and false otherwise.

444

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<integer>getCount()

Return Value: Returns the reaction count. Prototype:

<void>select <index>index

Parameters:
<index>index

Prototype:
<index>getSelected()

Return Value: Prototype:

<boolean>setStateToCurrent <index>index

Parameters:
<index>index

Remarks: This is a Time Variant function. Sets the reaction state to the current state at the given MAXScript time. Return Value: Returns true is successful and false otherwise. Prototype:
<boolean>setFloatState <index>index <float>state

Parameters:
<index>index <float>state

Remarks: Set the reaction state to the value passed in. The function you use depends on the type of reactor controller it is. Return Value: Returns true is successful and false otherwise. Prototype:
<boolean>setVectorState <index>index <point3>state

Parameters:
<index>index <point3>state

Remarks: Set the reaction state to the value passed in. The function you use depends on the type of reactor controller it is.

Float Reactor interfaces:

445

Return Value: Returns true is successful and false otherwise. Prototype:

<boolean>setRotationState <index>index <quat>state

Parameters:
<index>index <quat>state

Remarks: Set the reaction state to the value passed in. The function you use depends on the type of reactor controller it is. Return Value: Returns true is successful and false otherwise. Prototype:
<boolean>setValueToCurrent <index>index

Parameters:
<index>index

Remarks: This is a Time Variant function. Sets the reaction value to value of the ReactTo object at the given MAXScript time. Return Value: Returns true is successful and false otherwise. Prototype:
<boolean>setValueAsFloat <index>index <float>value

Parameters:
<index>index <float>value

Remarks: Set the reaction value to the value passed in. The function you use depends on the type of object or controller you are reacting to. See getType() below. Return Value: Returns true is successful and false otherwise. Prototype:
<boolean>setValueAsVector <index>index <point3>value

Parameters:
<index>index <point3>value

446

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: Set the reaction value to the value passed in. The function you use depends on the type of object or controller you are reacting to. See getType() below. Return Value: Returns true is successful and false otherwise. Prototype:
<boolean>setValueAsQuat <index>index <quat>value

Parameters:
<index>index <quat>value

Remarks: Set the reaction value to the value passed in. The function you use depends on the type of object or controller you are reacting to. See getType() below. Return Value: Returns true is successful and false otherwise. Prototype:
<boolean>setInfluence <index>index <float>influence

Parameters:
<index>index <float>influence

Remarks: Sets the influence for the specified reaction. Return Value: Returns true is successful and false otherwise. Prototype:
<boolean>setStrength <index>index <float>strength

Parameters:
<index>index <float>strength

Remarks: Sets the strength for the specified reaction. Return Value: Returns true is successful and false otherwise. Prototype:
<boolean>setFalloff <index>index <float>influence

Parameters:
<index>index <float>influence

Float Reactor interfaces:

447

Remarks: Sets the falloff for the specified reaction. Return Value: Prototype:
<void>setName <index>index <string>name

Parameters:
<index>index <string>name

Remarks: Set the name of the reaction specified by the index. Prototype:
<string>getName <index>index

Parameters:
<index>index

Return Value: Returns the reaction name. Prototype:

<float>getInfluence <index>index

Parameters:
<index>index

Return Value: Returns the reaction influence. Prototype:

<float>getStrength <index>index

Parameters:
<index>index

Return Value: Returns the reaction strength. Prototype:

<float>getFalloff <index>index

Parameters:
<index>index

Return Value: Returns the reaction falloff. Prototype:

<enum>getType() getType enums: { #floatReaction | #positionalReaction | #rotationalReaction | #scaleReaction }

448

Chapter 1

Whats New in 3ds max 4 MAXScript

Return Value: The type of object you are reacting to. Prototype:
<fpvalue by value>getState <index>index

Parameters:
<index>index

Return Value: Returns the reaction state. This value can be either a Point3, a Quat, or a float depending on the type of reactor controller this is. Prototype:
<fpvalue by value>getValue <index>index

Parameters:
<index>index

Return Value: Returns the reaction value. This value can be either a Point3, a Quat, or a float depending on the type of reactor controller this is.

Float_Wire interfaces:
This represents the interface for individual wire controllers. Interface: wireController Properties:
.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).
.isMaster : boolean : Read

This property will return TRUE if the wire is a master predicate, otherwise it will return FALSE.
.isSlave : boolean : Read

This method will return TRUE if the wire is a slave predicate, otherwise it will return FALSE.
.isTwoWay : boolean : Read

This method will return TRUE if the wire is a two-way predicate, otherwise it will return FALSE.
.slaveAnimation : control : Read|Write

This method returns a pointer to the slave animation controller. This method allows you to set the slave animation controller. Prototype:
<maxObject>getWireParent <index>index

Float_Wire interfaces:

449

Parameters:
<index>index

The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype:
<integer>getWireSubnum <index>index

Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters:
<index>index

The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype:
<control>getCoController <index>index

Parameters:
<index>index

The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype:
<string>getExprText <index>index

Parameters:
<index>index

The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype:
<void>setExprText <index>index <string>text

Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters:
<index>index

The index of the parameter

<string>text

The expression you wish to set.

450

Chapter 1

Whats New in 3ds max 4 MAXScript

See Also
In The MAXSDK Help File Class IBaseWireControl

FloatList interfaces:
This class represents the interface to the list controller. Properties:
.count : integer : Read .active : index : Read|Write

Methods: Prototype:
<integer>getCount()

Remarks: This method returns the number of items that appear in the List controllers list box. Prototype:
<void>setActive <index>listIndex

Remarks: This method allows you to sets the indexed item in the list active so its parameters appear in the motion panel, and any input is directed to the indexed sub controller. Parameters:
<index>listIndex

The index of the item to set as the active item. Prototype:

<integer>getActive()

Remarks: This method returns the index of the currently active item. Prototype:
<void>delete <index>listIndex

Remarks: This method allows you to delete the indexed sub controller from the list. Parameters:
<index>listIndex

The index of the item to delete from the list. Prototype:

<void>cut <index>listIndex

FloatList interfaces:

451

Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later. Parameters:
<index>listIndex

The index of the item you wish to cut. Prototype:

<void>paste <index>listIndex

Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters:
<index>listIndex

The index of the slot to paste into. Prototype:

<TSTR by value>getName <index>listIndex

Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesnt exist. Parameters:
<index>listIndex

The index of the item for which to get the name. Prototype:
<void>setName <index>listIndex <string>name

Remarks: This method allows you to set the name of an indexed item. Parameters:
<index>listIndex

The index of the item.

<string>name

The name to set it to.

See Also
In the MAXSDK Help File Class IListControl

452

Chapter 1

Whats New in 3ds max 4 MAXScript

FloatReactor interfaces:
FloatReactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: <void>reactTo <maxObject>object <boolean>create name:<string> name default value: scriptCreated} <boolean>delete <index>index <integer>getCount() <void>select <index>index <index>getSelected() <boolean>setStateToCurrent <index>index <boolean>setFloatState <index>index <float>state <boolean>setVectorState <index>index <point3>state <boolean>setRotationState <index>index <quat>state <boolean>setValueToCurrent <index>index <boolean>setValueAsFloat <index>index <float>value <boolean>setValueAsVector <index>index <point3>value <boolean>setValueAsQuat <index>index <quat>value <boolean>setInfluence <index>index <float>influence <boolean>setStrength <index>index <float>strength <boolean>setFalloff <index>index <float>influence <void>setName <index>index <string>name <string>getName <index>index <float>getInfluence <index>index <float>getStrength <index>index <float>getFalloff <index>index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} <fpvalue by value>getState <index>index <fpvalue by value>getValue <index>index Actions:

HSDS_Modifier interfaces:

453

HSDS_Modifier interfaces:
HSDS_Modifier interfaces: Interface: hsdsOps Properties: methods: <void>subdivide() <void>deletePolygon() <void>hide() <void>showAll() <void>createNamedSelection <string>name <void>activateNamedSelection <string>name <void>addDetail <float>length <float>angle <void>removeDetail <float>length <float>angle Actions:

HSDSObject interfaces:
HSDSObject interfaces: Interface: hsdsOps Properties: methods: <void>subdivide() <void>deletePolygon() <void>hide() <void>showAll() <void>createNamedSelection <string>name <void>activateNamedSelection <string>name <void>addDetail <float>length <float>angle <void>removeDetail <float>length <float>angle Actions:

IKChainControl interfaces:
IKChainControl interfaces: Interface: Action Properties: methods: <float>snap() -- Action Interface <float>ikSnap() -- Action Interface <float>fkSnap() -- Action Interface Actions: Category: IK_Chain_Actions; Action: IK_Chain_Snap_Action; Shortcut: -- none defined -Category: IK_Chain_Actions; Action: IK_Chain_IK_Snap; Shortcut: -- none defined -Category: IK_Chain_Actions; Action: IK_Chain_FK_Snap; Shortcut: -- none defined

454

Chapter 1

Whats New in 3ds max 4 MAXScript

imageMotionBlur interfaces:
imageMotionBlur interfaces: Interface: ImageMotionBlur Properties: methods: Actions:

JPEG interfaces:
This represents the interface for the Bitmap IO JPG format. Interface: ijpegio Methods: Prototype:
<integer>getQuality()

Return Value: This method returns the quality level of the output image. Prototype:
<void>setQuality <integer>quality

Remarks: This method allows you to set the quality level of the output image. Parameters: <integer>quality The quality level. Prototype:
<integer>getSmoothing()

Return Value: This method returns the smoothing level of the output image. Prototype:
<void>setSmoothing <integer>smoothing

Remarks: This method allows you set the smoothing level of the output image. Parameters: <integer>smoothing The smoothing level.

Link interfaces:

455

See Also
In The MAXSDK Help File Class IBitmapIO_Jpeg

Link interfaces:
Link interfaces: Interface: constraints Properties: methods: <node>getTarget <index>index <boolean>setTarget <node>target <index>index <float>getFrameNo <index>index <time>time <boolean>setFrameNo <integer>frameNo <index>index <time>time <integer>getNumTargets() <boolean>appendTarget <node>target <time>time <void>DeleteTarget <integer>targetNumber Actions:

Link_Constraint interfaces:
Link_Constraint interfaces: Interface: constraints Methods: <node>getTarget <index>index <boolean>setTarget <node>target <index>index <float>getFrameNo <index>index <time>time <boolean>setFrameNo <integer>frameNo <index>index <time>time <integer>getNumTargets() <boolean>appendTarget <node>target <time>time <void>DeleteTarget <integer>targetNumber

LookAt_Constraint interfaces:
This class is an interface to the LookAt Constraint rotation controller. Interface: constraints Methods: Prototype:
<node>getTarget <index>index

Parameters:
<index>index

The node number in the Look-At target list to be obtained.

456

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method will return a pointer to a node of one of the Look-At nodes that the Look-At constraint controller targets, specified by targetNumber. Prototype:
<boolean>setTarget <node>target <index>index

Parameters:
<node>target

Points to the node to follow.

<index>index

The node number in the Look-At target list to be set. Remarks: Sets one of the Look-At nodes that the Look-At constraint controller targets, specified by targetNumber. If targetNumber is greater than the number of targets in the current list, it returns a FALSE. In this case use the function AppendTarget. Return Value: TRUE if success; FALSE otherwise. Prototype:
<float>getWeight <index>index <time>time

Parameters:
<index>index

The node number in the Look-At target list whose weight is to be obtained.
<time>time

The time at which the weight is to be obtained. The weights are animatable. Remarks: Gets the weight of one of the Look-At nodes that the Look-At constraint controller targets, specified by targetNumber, and time t. Prototype:
<boolean>setWeight <float>weight <index>index <time>time

Parameters:
<float>weight

The weight to set.

<index>index

The node number in the Look-At target list whose weight is to be set.
<time>time

The time at which the weight is to be set. The weights are animatable.

LookAt_Constraint interfaces:

457

Remarks: Sets the weight of one of the Look-At nodes that the Look-At constraint controller follows, specified by targetNumber, and time t. Return Value: TRUE if there is more than one Look-At targets in the list and you are trying to set weight, FALSE otherwise. Prototype:
<integer>getNumTargets()

Remarks: Returns the number of nodes in the list of nodes to look at. Prototype:
<void>appendWeightedTarget <node>target <float>weight

Parameters:
<node>target

The node that is to be appended to the current Look-At target list.

<float>weight

This is the weight that is to be assigned to the newly appended Look-At target. The default weight is 50.0. Remarks: Appends the current Look-At target list by one and appends the current Look-At target weightlist by one. Prototype:
<boolean>appendTarget <node>target

Parameters:
<node>target

The node that is to be appended to the current Look-At target list. Remarks: Appends the current Look-At target list by one and appends the current Look-At target weightlist by one. Prototype:
<boolean>getRelative()

Remarks: Gets the relative/absolute mode corresponding to the Keep Initial Offset checkbox in the UI. Prototype:
<boolean>getUpnodeWorld()

458

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: Returns TRUE if the World checkbox is on; FALSE if off. Prototype:
<boolean>getStoUpAxisFlip()

Remarks: Returns TRUE if the selected axis flip checkbox is on; FALSE if off. Prototype:
<boolean>getTargetAxisFlip()

Remarks: Returns TRUE if the source axis flip checkbox is on; FALSE if off. Prototype:
<boolean>getSetOrient()

Remarks: Returns TRUE if the orientation flag is set, FALSE if off. Prototype:
<boolean>getTargetAxis()

Remarks: Gets the selection corresponding to the Select LookAt Axis button in the UI. Obtains which of the source axes is required to coincide with the target axis. Return Value: (0) if the target axis coincides with the x axis of the source object. (1) if the target axis coincides with the y axis of the source object. (2) if the target axis coincides with the z axis of the source object. Prototype:
<boolean>getUpNodeAxis()

Remarks: Gets the selection corresponding to the Source/Upnode Alignment: Aligned to UpNode Axis: radiobutton in the UI. Obtains which of the upnode axes is required to align with a specified source axis. Return Value: (0) if the upnode x axis coincides with a specified source object. (1) if the upnode y axis coincides with a specified source object. (2) if the upnode z axis coincides with a specified source object. Prototype:
<boolean>getStoUPAxis()

Remarks: Gets the selection corresponding to the Source/Upnode Alignment: Aligned to UpNode Axis: radiobutton in the UI. Obtains which of the source axes is required to align with a specified upnode axis.

LookAt_Constraint interfaces:

459

Return Value: (0) if the source x axis coincides with a specified upnode axis. (1) if the source y axis coincides with a specified upnode axis. (2) if the source z axis coincides with a specified upnode axis. Prototype:
<void>setRelative <boolean>rel

Parameters:
<boolean>rel

TRUE to set the relative flag, otherwise FALSE. Remarks: This method allows you to set the relative flag. Prototype:
<void>setUpnodeWorld <boolean>upnode

Parameters:
<boolean>upnode

TRUE to set the world flag, otherwise false. Remarks: This method allows you to set the World flag. Prototype:
<void>setTargetAxisFlip <boolean>staxflip

Parameters:
<boolean>staxflip

TRUE to set the source flip axis flag, otherwise FALSE. Remarks: This method allows you to set the source flip axis flag. Prototype:
<void>setStoUPAxisFlip <boolean>ssuaflip

Parameters:
<boolean>ssuaflip

TRUE to set the selected axis flip flag, otherwise FALSE. Remarks: This method allows you to set the selected axis flip flag. Prototype:
<void>setSetOrient <boolean>ssorient

460

Chapter 1

Whats New in 3ds max 4 MAXScript

Parameters:
<boolean>ssorient

TRUE to set the orientation flag, otherwise FALSE. Remarks: This method allows you to set the orientation flag. Prototype:
<void>setResetOrient()

Remarks: Resets to zero the amount of orientation offset, effected through the Set Orientation feature. Prototype:
<void>setTargetAxis <integer>staxis

Parameters:
<integer>staxis

(0) if TargetAxis coincides with the X axis of the source object. (1) if TargetAxis coincides with the Y axis of the source object. (2) if TargetAxis coincides with the Z axis of the source object Remarks: Sets the selection corresponding to the Set Orientation button in the UI. Specifies which of the source axes is required to coincide with the target axis. Prototype:
<void>setUpNodeAxis <integer>sunaxis

Parameters:
<integer>sunaxis

(0) if the upnode X axis coincides with a specified source axis. (1) if the upnode Y axis coincides with a specified source axis. (2) if the upnode Z axis coincides with a specified source axis. Remarks: Sets the selection corresponding to the Source/Upnode Alignment: Aligned to UpNode Axis: radiobutton in the UI. Specifies which of the upnode axes is required to align with a specified source axis. Prototype:
<void>setStoUPAxis <integer>ssuaxis

Parameters:
<integer>ssuaxis

(0) if the source X axis coincides with a specified upnode axis. (1) if the source Y axis coincides with a specified upnode axis. (2) if the source Z axis coincides with a specified upnode axis.

LookAt_Constraint interfaces:

461

Remarks: Sets the selection corresponding to the Source/Upnode Alignment: Aligned to UpNode Axis: radiobutton in the UI. Specifies which of the source axes is required to align with a specified upnode axis. Prototype:
<boolean>GetVLisAbs()

Remarks: Gets the ViewLine relative/absolute mode corresponding to the Keep ViewLine Length Absolute checkbox in the UI. When Viewline Length is absolute, the ViewLine Length spinner sets the length of the ViewLine. A negative length implies that starting from the source object the line travels opposite to the direction of the target object. The source/target distance has no effect on the ViewLine length in this mode. If the Keep ViewLine Length Absolute checkbox is unchecked, the ViewLine length is determined from the spinner value, which is interpreted as a percentage of the source/target distance. Return Value: TRUE if the ViewLine length is absolute, FALSE otherwise. Prototype:
<void>SetVLisAbs <boolean>rel

Parameters:
<boolean>rel

TRUE if Keep ViewLine Length Absolute is active (checked), FALSE otherwise. Remarks: Sets the relative/absolute mode corresponding to the Keep ViewLine Length Absolute checkbox in the UI. Prototype:
<void>deleteTarget <integer>targetNumber

Parameters:
<integer>targetNumber

The zero based node number in the list of nodes the controller looks at. Remarks: This method allows you to delete a specified target.

See Also
In The MAXSDK Help File Class ILookAtConstRotation

462

Chapter 1

Whats New in 3ds max 4 MAXScript

Motion_Blur interfaces:
Motion_Blur interfaces: Interface: ImageMotionBlur Properties: methods: Actions:

Orientation_Constraint interfaces:
Orientation_Constraint interfaces: Interface: constraints Properties: methods: <node>getTarget <index>index <boolean>setTarget <node>target <index>index <float>getWeight <index>index <time>time <boolean>setWeight <float>weight <index>index <time>time <integer>getNumTargets() <integer>getlw() <void>appendWeightedTarget <node>target <float>weight <void>deleteNode <integer>targetNumber Actions:

path interfaces:
path interfaces: This class represents the interface to the Path Position Controller. Interface: constraints Methods:
<integer>getNumTargets()

Remarks: Returns the number of nodes in the path list. Prototype:

<node>getTarget <index>index

Remarks: Gets one of the path nodes that the path controller follows, specified by targetNumber. Parameters:
<index>index

The node number in the path list to be obtained. Prototype:

<boolean>setTarget <node>target <index>index

path interfaces:

463

Prototype:
<float>getWeight <index>index <time>time

Remarks: Gets the weight of one of the path nodes that the path controller follows, specified by targetNumber, and time t. If the targetNumber is not relevant then 0.0f is returned. Parameters:
<index>index

The node number in the path list whose weight is to be obtained.

<time>time

Prototype:
<boolean>setWeight <float>weight <index>index <time>time

Remarks: Sets the weight of one of the path nodes that the path controller follows, specified by targetNumber. Parameters:
<float>weight

The weight to assign.

<index>index

The node number in the path list whose weight is to be set.

<time>time

Return Value: TRUE if there is more than one path in the list and you are trying to set weight, FALSE otherwise. Prototype:
<void>appendWeightedTarget <node>target <float>weight

Remarks: Appends the current path list by one and appends the current weight list by one. Parameters:
<node>target

The node that is to be appended to the current path list.

<float>weight

The weight to be assigned to the newly appended path. Prototype:

<void>setFollow <boolean>isSetFollow

Remarks: This method allows you to set the follow flag. Parameters:
<boolean>isSetFollow

TRUE for on, FALSE for off.

464

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<boolean>getFollow()

Remarks: This method returns the state of the follow flag. TRUE if on; FALSE if off. Prototype:
<void>setBankAmount <float>bankAmount

Remarks: Sets the bank amount parameter. Bank and tracking are scaled in the UI. Parameters:
<float>bankAmount

The bank amount. Prototype:

<float>getBankAmount()

Remarks: Returns the bank amount setting. See the remarks in SetBankAmount() above. Prototype:
<void>SetBank <boolean>isSetBank

Remarks: Sets the bank parameter to on or off. Parameters:

<boolean>isSetBank

TRUE for on; FALSE for off. Prototype:

<boolean>getBank()

Remarks: Returns the on/off state of the bank parameter. TRUE if on; FALSE if off. Prototype:
<void>setTracking <float>tracking

Remarks: Sets the smoothness parameter. Parameters:

<float>tracking

The smoothness setting. Prototype:

<float>getTracking()

path interfaces:

465

Remarks: Returns the smoothness setting. See remarks in SetTracking() above. Prototype:
<void>setAllowFlip <boolean>allowFlip

Remarks: Sets the state of the Allow Upside Down parameter. Parameters:
<boolean>allowFlip

TRUE for on; FALSE for off. Prototype:

<boolean>getAllowFlip()

Remarks: Returns the state of the Allow Upside Down parameter. Return Value: TRUE for on; FALSE for off. Prototype:
<void>setConstVel <boolean>constVel

Remarks: Sets the state of the Constant Velocity parameter. Parameters:

<boolean>constVel

TRUE for on; FALSE for off. Prototype:

<boolean>getConstVel()

Remarks: Returns the state of the Constant Velocity parameter. Return Value: TRUE for on; FALSE for off. Prototype:
<void>setFlip <boolean>Flip

Remarks: Sets the state of the Flip parameter. Parameters:

<boolean>Flip

TRUE for on; FALSE for off.

466

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<boolean>getFlip()

Remarks: Returns the state of the Flip parameter. Return Value: TRUE for on; FALSE for off. Prototype:
<void>setAxis <integer>isSetFollow

Remarks: Set the state of the axis parameter. Parameters:

<integer>isSetFollow

The axis setting. One of the following values: 0: X axis. 1: Y axis. 2: Z axis. Prototype:
<integer>getAxis()

Remarks: Returns the axis setting. Return Value: One of the following values: 0: X axis. 1: Y axis. 2: Z axis. Prototype:
<void>setLoop <boolean>Loop

Remarks: This method allows you to set the state of the loop flag. Parameters:
<boolean>Loop

TRUE for on; FALSE for off. Prototype:

<boolean>getLoop()

Remarks: Returns the state of the loop flag.

path interfaces:

467

Return Value: TRUE for on; FALSE for off. Prototype:

<void>setRelative <boolean>relative

Remarks: This method allows you to set the state of the relative/absolute flag. Parameters:
<boolean>relative

TRUE to set to relative; FALSE to set to absolute. Prototype:

<boolean>getRelative()

Remarks: Returns the state of the relative/absolute flag. Return Value: TRUE if relative is on; FALSE is off (i.e. absolute). Prototype:
<void>deleteTarget <integer>targetNumber

Remarks: This method allows you to delete a specified target. Parameters:

<integer>targetNumber

The node number in the orientation target list to delete. Return Value: TRUE if successful, otherwise FALSE.

See Also
In The MAXSDK Help File Class IPathPosition

468

Chapter 1

Whats New in 3ds max 4 MAXScript

Path_Constraint interfaces:
Path_Constraint interfaces: This class represents the interface to the Path Position Controller. Interface: constraints Properties: Methods: Prototype:
<integer>getNumTargets()

Prototype:
<node>getTarget <index>index

Parameters:
<index>index

The node number in the path list to be obtained. Return Value: Gets one of the path nodes that the path controller follows, specified by targetNumber. Prototype:
<boolean>setTarget <node>target <index>index

Prototype:
<float>getWeight <index>index <time>time

Parameters:
<index>index

The node number in the path list whose weight is to be obtained.

<time>time

Return Value: Gets the weight of one of the path nodes that the path controller follows, specified by targetNumber, and time t. If the targetNumber is not relevant then 0.0f is returned. Prototype:
<boolean>setWeight <float>weight <index>index <time>time

Remarks: Sets the weight of one of the path nodes that the path controller follows, specified by targetNumber. Parameters:
<index>index

The node number in the path list whose weight is to be set.

<float>weight

The weight to assign.

<time>time

Path_Constraint interfaces:

469

Return Value: TRUE if there is more than one path in the list and you are trying to set weight, FALSE otherwise. Prototype:
<void>appendWeightedTarget <node>target <float>weight

Remarks: Appends the current path list by one and appends the current weight list by one. Parameters:
<node>target

The node that is to be appended to the current path list.

<float>weight

The weight to be assigned to the newly appended path. Default: 50.0 Prototype:
<void>setFollow <boolean>isSetFollow

Remarks: This method allows you to set the follow flag. Parameters:
<boolean>isSetFollow

TRUE for on, FALSE for off. Prototype:

<boolean>getFollow()

Return Value: This method returns the state of the follow flag. TRUE if on; FALSE if off. Prototype:
<void>setBankAmount <float>bankAmount

Remarks: Sets the bank amount parameter. Bank and tracking are scaled in the UI. The bank values are scaled in the user interface. The following macros may be used to convert to and from the UI values. Parameters:
<float>bankAmount

The bank amount. Prototype:

<float>getBankAmount()

Return Value: Returns the bank amount setting. See the remarks in SetBankAmount() above.

470

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<void>SetBank <boolean>isSetBank

Remarks: Sets the bank parameter to on or off. Parameters:

<boolean>isSetBank

TRUE for on; FALSE for off. Prototype:

<boolean>getBank()

Return Value: Returns the on/off state of the bank parameter. TRUE if on; FALSE if off. Prototype:
<void>setTracking <float>tracking

Remarks: Sets the smoothness parameter. The smoothing (tracking) values are scaled in the user interface. The following macros may be used to convert to and from the UI values. Parameters:
<float>tracking

The smoothness setting. Prototype:

<float>getTracking()

Return Value: Returns the smoothness setting. See remarks in SetTracking() above. Prototype:
<void>setAllowFlip <boolean>allowFlip

Remarks: Sets the state of the Allow Upside Down parameter. Parameters:
<boolean>allowFlip

TRUE for on; FALSE for off. Prototype:

<boolean>getAllowFlip()

Remarks: Returns the state of the Allow Upside Down parameter. Return Value: TRUE for on; FALSE for off.

Path_Constraint interfaces:

471

Prototype:
<void>setConstVel <boolean>constVel

Remarks: Sets the state of the Constant Velocity parameter. Parameters:

<boolean>constVel

TRUE for on; FALSE for off. Prototype:

<boolean>getConstVel()

Remarks: Returns the state of the Constant Velocity parameter. Return Value: TRUE for on; FALSE for off. Prototype:
<void>setFlip <boolean>Flip

Remarks: Sets the state of the Flip parameter. Parameters:

<boolean>Flip

TRUE for on; FALSE for off. Prototype:

<boolean>getFlip()

Remarks: Returns the state of the Flip parameter. Return Value: TRUE for on; FALSE for off. Prototype:
<void>setAxis <integer>isSetFollow

Remarks: Set the state of the axis parameter. Parameters:

<integer>isSetFollow

The axis setting. One of the following values: 0: X axis. 1: Y axis. 2: Z axis.

472

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<integer>getAxis()

Remarks: Returns the axis setting. Return Value: One of the following values: 0: X axis. 1: Y axis. 2: Z axis. Prototype:
<void>setLoop <boolean>Loop

Remarks: This method allows you to set the state of the loop flag. Parameters:
<boolean>Loop

TRUE for on; FALSE for off. Prototype:

<boolean>getLoop()

Remarks: Returns the state of the loop flag. Return Value: TRUE for on; FALSE for off. Prototype:
<void>setRelative <boolean>relative

Remarks: This method allows you to set the state of the relative/absolute flag. Parameters:
<boolean>relative

TRUE to set to relative; FALSE to set to absolute. Prototype:

<boolean>getRelative()

Remarks: Returns the state of the relative/absolute flag. Return Value: TRUE if relative is on; FALSE is off (i.e. absolute).

Plugin_Manager interfaces:

473

Prototype:
<void>deleteTarget <integer>targetNumber

Remarks: This method allows you to delete a specified target. Parameters:

<integer>targetNumber

The node number in the orientation target list to delete. Return Value: TRUE if successful, otherwise FALSE.

See Also In The MAXSDK Help File

Class IPathPosition

Plugin_Manager interfaces:
Plugin_Manager interfaces: Interface: PluginMgrAction Methods: Prototypes:
<float>show() -- Action Interface

Actions: Category: Plugin_Manager; Action: Plugin_Manager; Shortcut: -- none defined

See Also
Plug-In Manager (p. 86) Interface: pluginManager (p. 414)

Portable_Network_Graphics interfaces:
This represents the interface for the Bitmap IO PNG format. Interface: ipngio Methods: Prototype:
<enum>getType() getType enums: {#paletted|#true24|#true48|#gray8|#gray16}

Return Value: This method returns the bitmap type, which is one of the following; BMM_PALETTED, BMM_TRUE_24, BMM_TRUE_48, BMM_GRAY_8, or BMM_GRAY_16.

474

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<void>setType <enum>type {#paletted|#true24|#true48|#gray8|#gray16} type enums:

Parameters:
<enum>type

One of the following; BMM_PALETTED, BMM_TRUE_24, BMM_TRUE_48, BMM_GRAY_8, or BMM_GRAY_16. Remarks: This method allows you to set the bitmap type. Prototype:
<boolean>getAlpha()

Return Value: This method returns TRUE if the alpha flag is set, otherwise FALSE. Prototype:
<void>setAlpha <boolean>useAlpha

Parameters:
<boolean>useAlpha

TRUE to set the alpha flag, otherwise FALSE. Remarks: This method allows you to set the alpha flag. Prototype:
<boolean>getInterlaced()

Return Value: This method returns TRUE if the interlaced flag is set, otherwise FALSE. Prototype:
<void>setInterlaced <boolean>Interlaced

Parameters:
<boolean>Interlaced

TRUE to set the interlaced flag, otherwise FALSE. Remarks: This method allows you to set the interlaced flag.

See Also
In The MAXSDK Help File Class IBitmapIO_Png

point3_list interfaces:

475

point3_list interfaces:
This class represents the interface to the list controller. Interface: list Properties:
.count : integer : Read .active : index : Read|Write

Methods: Prototype:
<integer>getCount()

Remarks: This method returns the number of items that appear in the List controllers list box. Prototype:
<void>setActive <index>listIndex

Parameters:
<index>listIndex

The index of the item to set as the active item. Remarks: This method allows you to sets the indexed item in the list active so its parameters appear in the motion panel, and any input is directed to the indexed sub controller. Prototype:
<integer>getActive()

Remarks: This method returns the index of the currently active item. Prototype:
<void>delete <index>listIndex

Parameters:
<index>listIndex

The index of the item to delete from the list. Remarks: This method allows you to delete the indexed sub controller from the list. Prototype:
<void>cut <index>listIndex

Parameters:
<index>listIndex

The index of the item you wish to cut.

476

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later. Prototype:
<void>paste <index>listIndex

Parameters:
<index>listIndex

The index of the slot to paste into. Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Prototype:
<TSTR by value>getName <index>listIndex

Parameters:
<index>listIndex

The index of the item for which to get the name. Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Prototype:
<void>setName <index>listIndex <string>name

Parameters:
<index>listIndex

The index of the item.

<string>name

The name to set it to. Remarks: This method allows you to set the name of an indexed item.

See Also
In the MAXSDK Help File Class IListControl

Point3_Reactor interfaces:

477

Point3_Reactor interfaces:
Point3_Reactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: <void>reactTo <maxObject>object <boolean>create name:<string> name default value: scriptCreated} <boolean>delete <index>index <integer>getCount() <void>select <index>index <index>getSelected() <boolean>setStateToCurrent <index>index <boolean>setFloatState <index>index <float>state <boolean>setVectorState <index>index <point3>state <boolean>setRotationState <index>index <quat>state <boolean>setValueToCurrent <index>index <boolean>setValueAsFloat <index>index <float>value <boolean>setValueAsVector <index>index <point3>value <boolean>setValueAsQuat <index>index <quat>value <boolean>setInfluence <index>index <float>influence <boolean>setStrength <index>index <float>strength <boolean>setFalloff <index>index <float>influence <void>setName <index>index <string>name <string>getName <index>index <float>getInfluence <index>index <float>getStrength <index>index <float>getFalloff <index>index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} <fpvalue by value>getState <index>index <fpvalue by value>getValue <index>index Actions:

Point3_Wire interfaces:
Interface: wireController Properties:
.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).
.isMaster : boolean : Read

This property will return TRUE if the wire is a master predicate, otherwise it will return FALSE.

478

Chapter 1

Whats New in 3ds max 4 MAXScript

.isSlave : boolean : Read

This method will return TRUE if the wire is a slave predicate, otherwise it will return FALSE.
.isTwoWay : boolean : Read

This method will return TRUE if the wire is a two-way predicate, otherwise it will return FALSE.
.slaveAnimation : control : Read|Write

This method returns a pointer to the slave animation controller. This method allows you to set the slave animation controller. Prototype:
<maxObject>getWireParent <index>index

Parameters:
<index>index

The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype:
<integer>getWireSubnum <index>index

Parameters:
<index>index

The index of the subanim. Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype:
<control>getCoController <index>index

Parameters:
<index>index

The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype:
<string>getExprText <index>index

Parameters:
<index>index

The index of the parameter.

Point3List interfaces:

479

Return Value: This method returns the expression string of the i-th wire parameter. Prototype:
<void>setExprText <index>index <string>text

Parameters:
<index>index

The index of the parameter

<string>text

The expression you wish to set. Remarks: This method allows you to set the expression string of the i-th wire parameter.

See Also
In The MAXSDK Help File Class IBaseWireControl

Point3List interfaces:
Point3List interfaces: This class represents the interface to the list controller. Interface: list Properties:
.count : integer : Read .active : index : Read|Write

Methods: Prototype:
<integer>getCount()

Remarks: This method returns the number of items that appear in the List controllers list box. Prototype:
<void>setActive <index>listIndex

Remarks: This method allows you to sets the indexed item in the list active so its parameters appear in the motion panel, and any input is directed to the indexed sub controller. Parameters:
<index>listIndex

The index of the item to set as the active item.

480

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<integer>getActive()

Remarks: This method returns the index of the currently active item. Prototype:
<void>delete <index>listIndex

Remarks: This method allows you to delete the indexed sub controller from the list. Parameters:
<index>listIndex

The index of the item to delete from the list. Prototype:

<void>cut <index>listIndex

Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later. Parameters:
<index>listIndex

The index of the item you wish to cut. Prototype:

<void>paste <index>listIndex

Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters:
<index>listIndex

The index of the slot to paste into. Prototype:

<TSTR by value>getName <index>listIndex

Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesnt exist. Parameters:
<index>listIndex

The index of the item for which to get the name. Prototype:
<void>setName <index>listIndex <string>name

Point3Reactor interfaces:

481

Remarks: This method allows you to set the name of an indexed item. Parameters:
<index>listIndex

The index of the item.

<string>name

The name to set it to.

See Also
In the MAXSDK Help File Class IListControl

Point3Reactor interfaces:
Point3Reactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: <void>reactTo <maxObject>object <boolean>create name:<string> name default value: scriptCreated} <boolean>delete <index>index <integer>getCount() <void>select <index>index <index>getSelected() <boolean>setStateToCurrent <index>index <boolean>setFloatState <index>index <float>state <boolean>setVectorState <index>index <point3>state <boolean>setRotationState <index>index <quat>state <boolean>setValueToCurrent <index>index <boolean>setValueAsFloat <index>index <float>value <boolean>setValueAsVector <index>index <point3>value <boolean>setValueAsQuat <index>index <quat>value <boolean>setInfluence <index>index <float>influence <boolean>setStrength <index>index <float>strength <boolean>setFalloff <index>index <float>influence <void>setName <index>index <string>name <string>getName <index>index <float>getInfluence <index>index <float>getStrength <index>index <float>getFalloff <index>index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} <fpvalue by value>getState <index>index

482

Chapter 1

Whats New in 3ds max 4 MAXScript

<fpvalue by value>getValue <index>index Actions:

Point3Spring interfaces:
Interface: Spring Properties: Methods: Prototype:
<float>getMass()

Return Value: Returns the mass. Prototype:

<void>setMass <float>mass

Parameters:
<float>mass

Remarks: Sets the mass. The mass of the object to which the Spring controller is applied. Increasing the mass causes the bouncing spring motion to become more exaggerated. Prototype:
<float>getDrag()

Return Value: Returns the drag. Prototype:

<void>setDrag <float>drag

Parameters:
<float>drag

Remarks: Sets the drag. Acts as air friction on the spring motion. A low Drag setting results in a greater bouncing effect, while a high Drag results in subdued bouncing. Default=1. Range=0 to 10. Prototype:
<float>getTension <index>springIndex

Parameters:
<index>springIndex

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

Point3Spring interfaces:

483

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

Parameters:
<index>springIndex <float>tension

Remarks: Sets the tension for the spring corresponding to the index. The stiffness of the virtual spring between the controlled object and the highlighted spring object(s). Prototype:
<float>getDampening <index>springIndex

Parameters:
<index>springIndex

Return Value: Gets the dampening for the spring corresponding to the index. Prototype:
<void>setDampening <index>springIndex <float>dampening

Parameters:
<index>springIndex <float>dampening

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

Parameters:
<node>node

Remarks: Adds the node to the spring list. Return Value: Returns true if successful, false otherwise Prototype:
<integer>getSpringCount()

484

Chapter 1

Whats New in 3ds max 4 MAXScript

Return Value: Returns the number of springs in the spring system. Prototype:
<void>removeSpringByIndex <index>springIndex

Parameters:
<index>springIndex

Remarks: Removes the spring corresponding to the index. Prototype:

<void>removeSpring <node>node

Parameters:
<node>node

Remarks: Removes the spring if the node is in the spring list.

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

Point_Cache interfaces:
This represents the interface to the PointCache Modifier. Interface: pointCache Methods: Prototype:
<void>record()

Remarks: This method will press the Record button in the rollup interface.

Point_CacheSpacewarpModifier interfaces:

485

Prototype:
<void>setCache()

Remarks: This method will press the Set Cache button in the rollup interface. Prototype:
<void>enableMods()

Remarks: This method will press the Enable Modifiers Below button in the rollup interface. Prototype:
<void>disableMods()

Remarks: This method will press the Disable Modifiers Below button in the rollup interface.

See Also In The MAXSDK Help File

Class IpointCache

See Also
Point Cache Modifier (p. 26) Point_Cache - superclass: modifier (p. 314) Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315) Point_CacheSpacewarpModifier interfaces: (p. 485)

Point_CacheSpacewarpModifier interfaces:
This represents the interface to the PointCache Modifier. Interface: pointCacheWSM Methods: Prototype:
<void>record()

Remarks: This method will press the Record button in the rollup interface. Prototype:
<void>setCache()

Remarks: This method will press the Set Cache button in the rollup interface. Prototype:
<void>enableMods()

486

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method will press the Enable Modifiers Below button in the rollup interface. Prototype:
<void>disableMods()

Remarks: This method will press the Disable Modifiers Below button in the rollup interface.

See Also In The MAXSDK Help File

Class IPointCacheWSM

See Also
Point Cache Modifier (p. 26) Point_Cache interfaces: (p. 484) Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315) Point_CacheSpacewarpModifier_interfaces_

PointCache interfaces:
This represents the interface to the PointCache Modifier. Interface: pointCache Methods: Prototype:
<void>record()

Remarks: This method will press the Record button in the rollup interface. Prototype:
<void>setCache()

Remarks: This method will press the Set Cache button in the rollup interface. Prototype:
<void>enableMods()

Remarks: This method will press the Enable Modifiers Below button in the rollup interface. Prototype:
<void>disableMods()

Remarks: This method will press the Disable Modifiers Below button in the rollup interface.

PointCacheWSM interfaces:

487

See Also
In The MAXSDK Help File Class IpointCache

See Also
Point Cache Modifier (p. 26) Point_Cache - superclass: modifier (p. 314) Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315) Point_CacheSpacewarpModifier interfaces: (p. 485)

PointCacheWSM interfaces:
This represents the interface to the PointCache Modifier. Interface: pointCacheWSM Methods: Prototype:
<void>record()

Remarks: This method will press the Record button in the rollup interface. Prototype:
<void>setCache()

Remarks: This method will press the Set Cache button in the rollup interface. Prototype:
<void>enableMods()

Remarks: This method will press the Enable Modifiers Below button in the rollup interface. Prototype:
<void>disableMods()

Remarks: This method will press the Disable Modifiers Below button in the rollup interface.

See Also
In The MAXSDK Help File Class IPointCacheWSM

488

Chapter 1

Whats New in 3ds max 4 MAXScript

See Also
Point Cache Modifier (p. 26) Point_Cache - superclass: modifier (p. 314) Point_Cache interfaces: (p. 484) Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315) Point_CacheSpacewarpModifier_interfaces_

Position_Constraint interfaces:
Position_Constraint interfaces: This class represents the interface to the Position Constraint. Interface: constraints Methods: Prototype:
<integer>getNumTargets()

Remarks: Returns the number of target nodes in the position target list. Prototype:
<node>getTarget <index>index

Remarks: Gets one of the position nodes that the position constraint controller targets, specified by targetNumber. Parameters:
<index>index

The node number in the position target list to be obtained. Prototype:

<boolean>setTarget <node>target <index>index

Prototype:
<float>getWeight <index> index <time>time

Remarks: Gets the weight of one of the position nodes that the position constraint controller targets, specified by targetNumber, and time t. Parameters:
<index>index

The node number in the position target list to set.

<time>time

Position_Constraint interfaces:

489

Return Value: Returns the position target weight if the targetNumber is relevant, 0.0f otherwise. Prototype:
<boolean>setWeight <float>weight <index> index <time>time

Remarks: Sets the weight of one of the position nodes that the position constraint controller follows, specified by targetNumber, and time t. Parameters:
<index>index

The node number in the position target list whose weight is to be set.
<float>weight

The weight to set.

<time>time

Return Value: TRUE if there is more than one position target in the list and you are trying to set weight, FALSE otherwise. Prototype:
<boolean>appendTarget <node>target <float>weight

Remarks: Appends the current position target list by one and appends. Parameters:
<node>target

The node that is to be appended to the current position target list.

<float>weight

This is the weight that is to be assigned to the newly appended position target. The default weight is 50.0. Prototype:
<void>deleteTarget <integer>targetNumber

Remarks: This method allows you to delete a specified target. Parameters:

<integer>targetNumber

The node number in the position target list to delete. Return Value: TRUE if successful, otherwise FALSE.

490

Chapter 1

Whats New in 3ds max 4 MAXScript

See Also
In The MAXSDK Help File Class IPosConstPosition

position_list interfaces:
This class represents the interface to the list controller. Interface: list Properties:
.count : integer : Read .active : index : Read|Write

Methods: Prototype:
<integer>getCount()

Remarks: This method returns the number of items that appear in the List controllers list box. Prototype:
<void>setActive <index>listIndex

Remarks: This method allows you to sets the indexed item in the list active so its parameters appear in the motion panel, and any input is directed to the indexed sub controller. Parameters:
<index>listIndex

The index of the item to set as the active item. Prototype:

<integer>getActive()

Remarks: This method returns the index of the currently active item. Prototype:
<void>delete <index>listIndex

Parameters:
<index>listIndex

The index of the item to delete from the list. Remarks: This method allows you to delete the indexed sub controller from the list. Prototype:
<void>cut <index>listIndex

position_list interfaces:

491

Parameters:
<index>listIndex

The index of the item you wish to cut. Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later. Prototype:
<void>paste <index>listIndex

Parameters:
<index>listIndex

The index of the slot to paste into. Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Prototype:
<TSTR by value>getName <index>listIndex

Parameters:
<index>listIndex

The index of the item for which to get the name. Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesnt exist. Prototype:
<void>setName <index>listIndex <string>name

Parameters:
<index>listIndex

The index of the item.

<string>name

The name to set it to. Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesnt exist.

See Also
In the MAXSDK Help File Class IListControl

492

Chapter 1

Whats New in 3ds max 4 MAXScript

Position_Reactor interfaces:
Position_Reactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: <void>reactTo <maxObject>object <boolean>create name:<string> name default value: scriptCreated} <boolean>delete <index>index <integer>getCount() <void>select <index>index <index>getSelected() <boolean>setStateToCurrent <index>index <boolean>setFloatState <index>index <float>state <boolean>setVectorState <index>index <point3>state <boolean>setRotationState <index>index <quat>state <boolean>setValueToCurrent <index>index <boolean>setValueAsFloat <index>index <float>value <boolean>setValueAsVector <index>index <point3>value <boolean>setValueAsQuat <index>index <quat>value <boolean>setInfluence <index>index <float>influence <boolean>setStrength <index>index <float>strength <boolean>setFalloff <index>index <float>influence <void>setName <index>index <string>name <string>getName <index>index <float>getInfluence <index>index <float>getStrength <index>index <float>getFalloff <index>index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} <fpvalue by value>getState <index>index <fpvalue by value>getValue <index>index Actions:

Position_Wire interfaces:
This represents the interface for individual wire controllers. Interface: wireController Properties:
.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).

Position_Wire interfaces:

493

.isMaster : boolean : Read

This property will return TRUE if the wire is a master predicate, otherwise it will return FALSE.
.isSlave : boolean : Read

This method will return TRUE if the wire is a slave predicate, otherwise it will return FALSE.
.isTwoWay : boolean : Read

This method will return TRUE if the wire is a two-way predicate, otherwise it will return FALSE.
.slaveAnimation : control : Read|Write

This method returns a pointer to the slave animation controller. This method allows you to set the slave animation controller. Prototype:
<maxObject>getWireParent <index>index

Parameters:
<index>index

The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype:
<integer>getWireSubnum <index>index

Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters:
<index>index

The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype:
<control>getCoController <index>index

Parameters:
<index>index

The index of the controller. Return Value: This method returns a pointer to the i-th CoController.

494

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<string>getExprText <index>index

Parameters:
<index>index

The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype:
<void>setExprText <index>index <string>text

Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters:
<index>index

The index of the parameter

<string>text

The expression you wish to set.

See Also
In The MAXSDK Help File Class IBaseWireControl

PositionList interfaces:
This class represents the interface to the list controller. Interface: list Properties:
.count : integer : Read .active : index : Read|Write

Methods: Prototype:
<integer>getCount()

Remarks: This method returns the number of items that appear in the List controllers list box. Prototype:
<void>setActive <index>listIndex

Remarks: This method allows you to sets the indexed item in the list active so its parameters appear in the motion panel, and any input is directed to the indexed sub controller.

PositionList interfaces:

495

Parameters:
<index>listIndex

The index of the item to set as the active item. Prototype:

<integer>getActive()

Remarks: This method returns the index of the currently active item. Prototype:
<void>delete <index>listIndex

Remarks: This method allows you to delete the indexed sub controller from the list. Parameters:
<index>listIndex

The index of the item to delete from the list. Prototype:

<void>cut <index>listIndex

Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later. Parameters:
<index>listIndex

The index of the item you wish to cut. Prototype:

<void>paste <index>listIndex

Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters:
<index>listIndex

The index of the slot to paste into. Prototype:

<TSTR by value>getName <index>listIndex

Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesnt exist. Parameters:
<index>listIndex

The index of the item for which to get the name.

496

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<void>setName <index>listIndex <string>name

Remarks: This method allows you to set the name of an indexed item. Parameters:
<index>listIndex

The index of the item.

<string>name

The name to set it to.

See Also
In the MAXSDK Help File Class IListControl

PositionReactor interfaces:
PositionReactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: <void>reactTo <maxObject>object <boolean>create name:<string> name default value: scriptCreated} <boolean>delete <index>index <integer>getCount() <void>select <index>index <index>getSelected() <boolean>setStateToCurrent <index>index <boolean>setFloatState <index>index <float>state <boolean>setVectorState <index>index <point3>state <boolean>setRotationState <index>index <quat>state <boolean>setValueToCurrent <index>index <boolean>setValueAsFloat <index>index <float>value <boolean>setValueAsVector <index>index <point3>value <boolean>setValueAsQuat <index>index <quat>value <boolean>setInfluence <index>index <float>influence <boolean>setStrength <index>index <float>strength <boolean>setFalloff <index>index <float>influence <void>setName <index>index <string>name <string>getName <index>index <float>getInfluence <index>index <float>getStrength <index>index <float>getFalloff <index>index <enum>getType()

PositionSpring interfaces:

497

getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} <fpvalue by value>getState <index>index <fpvalue by value>getValue <index>index Actions:

PositionSpring interfaces:
Interface: Spring Properties: Methods: Prototype:
<float>getMass()

Return Value: Returns the mass. Prototype:

<void>setMass <float>mass

Parameters:
<float>mass

Remarks: Sets the mass. The mass of the object to which the Spring controller is applied. Increasing the mass causes the bouncing spring motion to become more exaggerated. Prototype:
<float>getDrag()

Return Value: Returns the drag. Prototype:

<void>setDrag <float>drag

Parameters:
<float>drag

Remarks: Sets the drag. Acts as air friction on the spring motion. A low Drag setting results in a greater bouncing effect, while a high Drag results in subdued bouncing. Default=1. Range=0 to 10. Prototype:
<float>getTension <index>springIndex

Parameters:
<index>springIndex

498

Chapter 1

Whats New in 3ds max 4 MAXScript

Return Value: Gets the tension for the spring corresponding to the index. Prototype:
<void>setTension <index>springIndex <float>tension

Parameters:
<index>springIndex <float>tension

Remarks: Sets the tension for the spring corresponding to the index. The stiffness of the virtual spring between the controlled object and the highlighted spring object(s). Prototype:
<float>getDampening <index>springIndex

Parameters:
<index>springIndex

Return Value: Gets the dampening for the spring corresponding to the index. Prototype:
<void>setDampening <index>springIndex <float>dampening

Parameters:
<index>springIndex <float>dampening

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

Parameters:
<node>node

Remarks: Adds the node to the spring list. Return Value: Returns true if successful, false otherwise

PositionSpring interfaces:

499

Prototype:
<integer>getSpringCount()

Return Value: Returns the number of springs in the spring system. Prototype:
<void>removeSpringByIndex <index>springIndex

Parameters:
<index>springIndex

Remarks: Removes the spring corresponding to the index. Prototype:

<void>removeSpring <node>node

Parameters:
<node>node

Remarks: Removes the spring if the node is in the spring list.

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

500

Chapter 1

Whats New in 3ds max 4 MAXScript

radiusManip interfaces:
Interface: Manip Properties:
.mouseState : enum : Read mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods: Prototype:
<void>clearGizmos()

Remarks: This must be called at the beginning of the updateGizmos handler in order to clear the current gizmo cache. Prototype:
<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<mesh>mesh <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this is to create an instance of a primitive and get the mesh from it. The flags can be 0, or one or more of these values. If you want more than one flag to apply, then you add the values together. Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<Interface>gizmo <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

radiusManip interfaces:

501

gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.
gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a shape object. The gizmoShape can be created using functions from the manip package, described below. The flags can be 0, or one or more of these values. If you want more than one flag to apply, then you add the values together. Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor marker enums: {#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond |#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

Parameters:
<enum>marker <point3 by value>position

The position is a point in 3d space, or 2d screen space.

<integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.

502

Chapter 1

Whats New in 3ds max 4 MAXScript

gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: The position is a point in 3d space, or 2d screen space. Prototype:

<void>addGizmoText <string>text <point3 by value>position <integer> flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the mouse. It is used for display purposes only. Prototype:
<ray by value>getLocalViewRay <point2 by value> m

Parameters:
<point2 by value>m

Return Value: This function takes a mouse position and returns the ray that passes through that mouse position in the direction of the view. It is returned in the local coordinates of the node that owns the manipulator target. Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip

Remarks: Parameters:
<time>t <&TSTR>toolTip

RenderElementMgr interfaces:

503

RenderElementMgr interfaces:
Interface: RenderElementMgr Prototype:
<boolean>AddRenderElement <maxObject>element

Parameters:
<maxObject>element

Remarks: Adds a specific element. Return Value: Returns TRUE if Successful, FALSE otherwise Prototype:
<boolean>RemoveRenderElement <maxObject>element

Parameters:
<maxObject>element

Remarks: Removes a specific element. Return Value: Returns true is successful and false otherwise. Prototype:
<void>RemoveAllRenderElements()

Remarks: Removes all elements in the list. Prototype:

<integer>NumRenderElements()

Return Value: Returns number of elements in list Prototype:

<maxObject>GetRenderElement <integer>index

Parameters:
<integer>index

Return Value: Returns a specific element, index is 0 based. Prototype:

<void>SetElementsActive <boolean>active

Parameters:
<boolean>active

504

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: Sets a boolean indicating elements are active, ie. will be created during a render. Prototype:
<boolean>GetElementsActive()

Return Value: Gets a boolean indicating elements are active, ie. will be created during a render. Prototype:
<void>SetDisplayElements <boolean>display

Parameters:
<boolean>display

Remarks: Sets boolean indicating elements will be displayed after they are created. Prototype:
<boolean>GetDisplayElements()

Return Value: Gets boolean indicating elements will be displayed after they are created. Prototype:
<void>SetCombustionOutputEnabled <boolean>enabled

Parameters:
<boolean>enabled

Remarks: Enables or disables output to combustion .cws file. Prototype:

<boolean>GetCombustionOutputEnabled()

Return Value: Gets boolean indicating enabled output to combustion .cws file. Prototype:
<void>SetCombustionOutputPath <string>pathname

Parameters:
<string>pathname

Remarks: Sets the filename of the .cws file. Prototype:

<string>GetCombustionOutputPath()

Return Value: Gets the filename of the .cws file.

rotation_list interfaces:

505

Example:
-- set a list of render elements. elementlist = #(specular,diffuse,self_illumination,reflection,refraction,shadowrenderelement,atm osphere,blend,z_depth,alpha,colored_shadow,backgroundrenderelement) re = maxOps.GetCurRenderElementMgr() -- get the current render element manager re.removeallrenderelements() -- remove all renderelements re.numrenderelements() -- get number of render elements prod = maxOps.GetRenderElementMgr #Production draft = maxOps.GetRenderElementMgr #Draft prod.numrenderelements() draft.numrenderelements() -- adds all renderelements to be rendered. for n in elementlist do ( re.addrenderelement (n elementname:(foo_ + (n as string))) format \nAdded % renderelement n ) rendoutputfilename = c:\\test.tga rendsavefile = true setsilentmode true -- used to avoid error message when checking the filename of element -- get all render elements set and return name of render element and output filename for n = 0 to (prod.numrenderelements()- 1) do ( el = re.getrenderelement n format \nGetting % render element el.elementname format \nRender element outputfilename: % el.bitmap.filename --el.filename )

See Also
maxOps (p. 87)

rotation_list interfaces:
This represents the interface to the list controller. Interface: list Properties:
.count : integer : Read .active : index : Read|Write

Methods: Prototype:
<integer>getCount()

506

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method returns the number of items that appear in the List controllers list box. Prototype:
<void>setActive <index>listIndex

Remarks: This method allows you to sets the indexed item in the list active so its parameters appear in the motion panel, and any input is directed to the indexed sub controller. Parameters:
<index>listIndex

The index of the item to set as the active item. Prototype:

<integer>getActive()

Remarks: This method returns the index of the currently active item. Prototype:
<void>delete <index>listIndex

Remarks: This method allows you to delete the indexed sub controller from the list. Parameters:
<index>listIndex

The index of the item to delete from the list. Prototype:

<void>cut <index>listIndex

Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later. Parameters:
<index>listIndex

The index of the item you wish to cut. Prototype:

<void>paste <index>listIndex

Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters:
<index>listIndex

The index of the slot to paste into.

Rotation_Reactor interfaces:

507

Prototype:
<TSTR by value>getName <index>listIndex

Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesnt exist. Parameters:
<index>listIndex

The index of the item for which to get the name. Prototype:
<void>setName <index>listIndex <string>name

Remarks: This method allows you to set the name of an indexed item. Parameters:
<index>listIndex

The index of the item.

<string>name

The name to set it to.

See Also
In the MAXSDK Help File Class IListControl

Rotation_Reactor interfaces:
Rotation_Reactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write Methods: <void>reactTo <maxObject>object <boolean>create name:<string> name default value: scriptCreated} <boolean>delete <index>index <integer>getCount() <void>select <index>index <index>getSelected() <boolean>setStateToCurrent <index>index <boolean>setFloatState <index>index <float>state <boolean>setVectorState <index>index <point3>state <boolean>setRotationState <index>index <quat>state <boolean>setValueToCurrent <index>index <boolean>setValueAsFloat <index>index <float>value <boolean>setValueAsVector <index>index <point3>value

508

Chapter 1

Whats New in 3ds max 4 MAXScript

<boolean>setValueAsQuat <index>index <quat>value <boolean>setInfluence <index>index <float>influence <boolean>setStrength <index>index <float>strength <boolean>setFalloff <index>index <float>influence <void>setName <index>index <string>name <string>getName <index>index <float>getInfluence <index>index <float>getStrength <index>index <float>getFalloff <index>index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} <fpvalue by value>getState <index>index <fpvalue by value>getValue <index>index Actions:

Rotation_Wire interfaces:
This represents the interface for individual wire controllers. Interface: wireController Properties:
.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).
.isMaster : boolean : Read

This property will return TRUE if the wire is a master predicate, otherwise it will return FALSE.
.isSlave : boolean : Read

This method will return TRUE if the wire is a slave predicate, otherwise it will return FALSE.
.isTwoWay : boolean : Read

This method will return TRUE if the wire is a two-way predicate, otherwise it will return FALSE.
.slaveAnimation : control : Read|Write

This method returns a pointer to the slave animation controller. This method allows you to set the slave animation controller. Prototype:
<maxObject>getWireParent <index>index

Parameters:
<index>index

The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent.

Rotation_Wire interfaces:

509

Prototype:
<integer>getWireSubnum <index>index

Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters:
<index>index

The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype:
<control>getCoController <index>index

Parameters:
<index>index

The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype:
<string>getExprText <index>index

Parameters:
<index>index

The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype:
<void>setExprText <index>index <string>text

Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters:
<index>index

The index of the parameter

<string>text

The expression you wish to set.

See Also
In The MAXSDK Help File Class IBaseWireControl

510

Chapter 1

Whats New in 3ds max 4 MAXScript

RotationList interfaces:
This class represents the interface to the list controller. Interface: list Properties:
.count : integer : Read .active : index : Read|Write

Methods: Prototype:
<integer>getCount()

Remarks: This method returns the number of items that appear in the List controllers list box. Prototype:
<void>setActive <index>listIndex

Remarks: This method allows you to sets the indexed item in the list active so its parameters appear in the motion panel, and any input is directed to the indexed sub controller. Parameters:
<index>listIndex

The index of the item to set as the active item. Prototype:

<integer>getActive()

Remarks: This method returns the index of the currently active item. Prototype:
<void>delete <index>listIndex

Remarks: This method allows you to delete the indexed sub controller from the list. Parameters:
<index>listIndex

The index of the item to delete from the list. Prototype:

<void>cut <index>listIndex

Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

RotationList interfaces:

511

Parameters:
<index>listIndex

The index of the item you wish to cut. Prototype:

<void>paste <index>listIndex

Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters:
<index>listIndex

The index of the slot to paste into. Prototype:

<TSTR by value>getName <index>listIndex

Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesnt exist. Parameters:
<index>listIndex

The index of the item for which to get the name. Prototype:
<void>setName <index>listIndex <string>name

Remarks: This method allows you to set the name of an indexed item. Parameters:
<index>listIndex

The index of the item.

<string>name

The name to set it to.

See Also
In the MAXSDK Help File Class IListControl

512

Chapter 1

Whats New in 3ds max 4 MAXScript

RotationReactor interfaces:
RotationReactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: <void>reactTo <maxObject>object <boolean>create name:<string> name default value: scriptCreated} <boolean>delete <index>index <integer>getCount() <void>select <index>index <index>getSelected() <boolean>setStateToCurrent <index>index <boolean>setFloatState <index>index <float>state <boolean>setVectorState <index>index <point3>state <boolean>setRotationState <index>index <quat>state <boolean>setValueToCurrent <index>index <boolean>setValueAsFloat <index>index <float>value <boolean>setValueAsVector <index>index <point3>value <boolean>setValueAsQuat <index>index <quat>value <boolean>setInfluence <index>index <float>influence <boolean>setStrength <index>index <float>strength <boolean>setFalloff <index>index <float>influence <void>setName <index>index <string>name <string>getName <index>index <float>getInfluence <index>index <float>getStrength <index>index <float>getFalloff <index>index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} <fpvalue by value>getState <index>index <fpvalue by value>getValue <index>index Actions:

scale_list interfaces:

513

scale_list interfaces:
This class represents the interface to the list controller. Interface: list Properties:
.count : integer : Read .active : index : Read|Write

Methods: Prototype:
<integer>getCount()

Remarks: This method returns the number of items that appear in the List controllers list box. Prototype:
<void>setActive <index>listIndex

Remarks: This method allows you to sets the indexed item in the list active so its parameters appear in the motion panel, and any input is directed to the indexed sub controller. Parameters:
<index>listIndex

The index of the item to set as the active item. Prototype:

<integer>getActive()

Remarks: This method returns the index of the currently active item. Prototype:
<void>delete <index>listIndex

Remarks: This method allows you to delete the indexed sub controller from the list. Parameters:
<index>listIndex

The index of the item to delete from the list. Prototype:

<void>cut <index>listIndex

Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.

514

Chapter 1

Whats New in 3ds max 4 MAXScript

Parameters:
<index>listIndex

The index of the item you wish to cut. Prototype:

<void>paste <index>listIndex

Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters:
<index>listIndex

The index of the slot to paste into. Prototype:

<TSTR by value>getName <index>listIndex

Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesnt exist. Parameters:
<index>listIndex

The index of the item for which to get the name. Prototype:
<void>setName <index>listIndex <string>name

Remarks: This method allows you to set the name of an indexed item. Parameters:
<index>listIndex

The index of the item.

<string>name

The name to set it to.

See Also
In the MAXSDK Help File Class IListControl

Scale_Reactor interfaces:

515

Scale_Reactor interfaces:
Scale_Reactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: <void>reactTo <maxObject>object <boolean>create name:<string> name default value: scriptCreated} <boolean>delete <index>index <integer>getCount() <void>select <index>index <index>getSelected() <boolean>setStateToCurrent <index>index <boolean>setFloatState <index>index <float>state <boolean>setVectorState <index>index <point3>state <boolean>setRotationState <index>index <quat>state <boolean>setValueToCurrent <index>index <boolean>setValueAsFloat <index>index <float>value <boolean>setValueAsVector <index>index <point3>value <boolean>setValueAsQuat <index>index <quat>value <boolean>setInfluence <index>index <float>influence <boolean>setStrength <index>index <float>strength <boolean>setFalloff <index>index <float>influence <void>setName <index>index <string>name <string>getName <index>index <float>getInfluence <index>index <float>getStrength <index>index <float>getFalloff <index>index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} <fpvalue by value>getState <index>index <fpvalue by value>getValue <index>index Actions:

Scale_Wire interfaces:
This represents the interface for individual wire controllers. Interface: wireController Properties:
.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).

516

Chapter 1

Whats New in 3ds max 4 MAXScript

.isMaster : boolean : Read

This property will return TRUE if the wire is a master predicate, otherwise it will return FALSE.
.isSlave : boolean : Read

This method will return TRUE if the wire is a slave predicate, otherwise it will return FALSE.
.isTwoWay : boolean : Read

This method will return TRUE if the wire is a two-way predicate, otherwise it will return FALSE.
.slaveAnimation : control : Read|Write

This method returns a pointer to the slave animation controller. This method allows you to set the slave animation controller. Prototype:
<maxObject>getWireParent <index>index

Parameters:
<index>index

The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype:
<integer>getWireSubnum <index>index

Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters:
<index>index

The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype:
<control>getCoController <index>index

Parameters:
<index>index

The index of the controller. Return Value: This method returns a pointer to the i-th CoController.

ScaleList interfaces:

517

Prototype:
<string>getExprText <index>index

Parameters:
<index>index

The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype:
<void>setExprText <index>index <string>text

Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters:
<index>index

The index of the parameter

<string>text

The expression you wish to set.

See Also
In The MAXSDK Help File Class IBaseWireControl

ScaleList interfaces:
This class represents the interface to the list controller. Interface: list Properties:
.count : integer : Read .active : index : Read|Write

Methods: Prototype:
<integer>getCount()

Remarks: This method returns the number of items that appear in the List controllers list box. Prototype:
<void>setActive <index>listIndex

Remarks: This method allows you to sets the indexed item in the list active so its parameters appear in the motion panel, and any input is directed to the indexed sub controller.

518

Chapter 1

Whats New in 3ds max 4 MAXScript

Parameters:
<index>listIndex

The index of the item to set as the active item. Prototype:

<integer>getActive()

Remarks: This method returns the index of the currently active item. Prototype:
<void>delete <index>listIndex

Remarks: This method allows you to delete the indexed sub controller from the list. Parameters:
<index>listIndex

The index of the item to delete from the list. Prototype:

<void>cut <index>listIndex

Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later. Parameters:
<index>listIndex

The index of the item you wish to cut. Prototype:

<void>paste <index>listIndex

Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters:
<index>listIndex

The index of the slot to paste into. Prototype:

<TSTR by value>getName <index>listIndex

Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesnt exist. Parameters:
<index>listIndex

The index of the item for which to get the name.

ScaleReactor interfaces:

519

Prototype:
<void>setName <index>listIndex <string>name

Remarks: This method allows you to set the name of an indexed item. Parameters:
<index>listIndex

The index of the item.

<string>name

The name to set it to.

See Also
In the MAXSDK Help File Class IListControl

ScaleReactor interfaces:
ScaleReactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: <void>reactTo <maxObject>object <boolean>create name:<string> name default value: scriptCreated} <boolean>delete <index>index <integer>getCount() <void>select <index>index <index>getSelected() <boolean>setStateToCurrent <index>index <boolean>setFloatState <index>index <float>state <boolean>setVectorState <index>index <point3>state <boolean>setRotationState <index>index <quat>state <boolean>setValueToCurrent <index>index <boolean>setValueAsFloat <index>index <float>value <boolean>setValueAsVector <index>index <point3>value <boolean>setValueAsQuat <index>index <quat>value <boolean>setInfluence <index>index <float>influence <boolean>setStrength <index>index <float>strength <boolean>setFalloff <index>index <float>influence <void>setName <index>index <string>name <string>getName <index>index <float>getInfluence <index>index <float>getStrength <index>index <float>getFalloff <index>index <enum>getType()

520

Chapter 1

Whats New in 3ds max 4 MAXScript

getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} <fpvalue by value>getState <index>index <fpvalue by value>getValue <index>index Actions:

sliderManipulator interfaces:
Interface: Manip Scripted Manipulators (p. 97) Properties:
.mouseState : enum : Read mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods: Prototype:
<void>clearGizmos()

Remarks: This must be called at the beginning of the updateGizmos handler in order to clear the current gizmo cache. Prototype:
<void>addGizmoMesh <mesh>mesh <integer>flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<mesh>mesh <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this is to create an instance of a primitive and get the mesh from it. The flags can be 0, or one or more of these value. If you want more than one flag to apply, then you add the values together.

sliderManipulator interfaces:

521

Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<Interface>gizmo <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.
gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a shape object. The gizmoShape can be created using functions from the manip package, described below. Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor marker enums: {#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond |#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

Parameters:
<enum>marker <point3 by value>position

The position is a point in 3d space, or 2d screen space.

<integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.

522

Chapter 1

Whats New in 3ds max 4 MAXScript

gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.
gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by addGizmoShape. Prototype:
<void>addGizmoText <string>text <point3 by value>position <integer> flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the mouse. It is used for display purposes only. Prototype:
<ray by value>getLocalViewRay <point2 by value> m

Parameters:
<point2 by value>m

Return Value: This function takes a mouse position and returns the ray that passes through that mouse position in the direction of the view. It is returned in the local coordinates of the node that owns the manipulator target. Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip

Remarks: Parameters:
<time>t <&TSTR>toolTip

SpringPoint3Controller interfaces:

523

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

SpringPoint3Controller interfaces:
Interface: Spring Properties: Methods: Prototype:
<float>getMass()

Return Value: Returns the mass. Prototype:

<void>setMass <float>mass

Parameters:
<float>mass

Remarks: Sets the mass. The mass of the object to which the Spring controller is applied. Increasing the mass causes the bouncing spring motion to become more exaggerated. Prototype:
<float>getDrag()

Return Value: Returns the drag.

524

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<void>setDrag <float>drag

Parameters:
<float>drag

Remarks: Sets the drag. Acts as air friction on the spring motion. A low Drag setting results in a greater bouncing effect, while a high Drag results in subdued bouncing. Default=1. Range=0 to 10. Prototype:
<float>getTension <index>springIndex

Parameters:
<index>springIndex

Return Value: Gets the tension for the spring corresponding to the index. Prototype:
<void>setTension <index>springIndex <float>tension

Parameters:
<index>springIndex <float>tension

Remarks: Sets the tension for the spring corresponding to the index. The stiffness of the virtual spring between the controlled object and the highlighted spring object(s). Prototype:
<float>getDampening <index>springIndex

Parameters:
<index>springIndex

Return Value: Gets the dampening for the spring corresponding to the index. Prototype:
<void>setDampening <index>springIndex <float>dampening

Parameters:
<index>springIndex <float>dampening

Remarks: Sets the dampening for the spring corresponding to the index. : Acts as a multiplier of an internal factor that determines how quickly the object comes to rest. With the Self Influence spring,

SpringPoint3Controller interfaces:

525

changing Dampening has the same effect as changing Drag. With other springs, Dampening affects only the movement caused by that spring. Internally, the dampening value is proportional to the tension, so as you increase the tension and make the solution more stiff, the dampening is increased to maintain system stability. Prototype:
<boolean>addSpring <node>node

Parameters:
<node>node

Remarks: Adds the node to the spring list. Return Value: Returns true if successful, false otherwise Prototype:
<integer>getSpringCount()

Return Value: Returns the number of springs in the spring system. Prototype:
<void>removeSpringByIndex <index>springIndex

Parameters:
<index>springIndex

Remarks: Removes the spring corresponding to the index. Prototype:

<void>removeSpring <node>node

Parameters:
<node>node

Remarks: Removes the spring if the node is in the spring list.

See Also
PositionSpring interfaces: (p. 497) Point3Spring interfaces: (p. 482) SpringPoint3Controller interfaces: (p. 523) SpringPoint3Controller - superclass: Point3Controller (p. 336) SpringPositionController interfaces: (p. 526)

526

Chapter 1

Whats New in 3ds max 4 MAXScript

SpringPositionController - superclass: PositionController (p. 337) Flex : Modifier (p. 1128) Flex interfaces: (p. 438) flexOps const StructDef (p. 235)

SpringPositionController interfaces:
Interface: Spring Properties: Methods: Prototype:
<float>getMass()

Return Value: Returns the mass. Prototype:

<void>setMass <float>mass

Parameters:
<float>mass

Remarks: Sets the mass. The mass of the object to which the Spring controller is applied. Increasing the mass causes the bouncing spring motion to become more exaggerated. Prototype:
<float>getDrag()

Return Value: Returns the drag. Prototype:

<void>setDrag <float>drag

Parameters:
<float>drag

Remarks: Sets the drag. Acts as air friction on the spring motion. A low Drag setting results in a greater bouncing effect, while a high Drag results in subdued bouncing. Default=1. Range=0 to 10. Prototype:
<float>getTension <index>springIndex

SpringPositionController interfaces:

527

Parameters:
<index>springIndex

Return Value: Gets the tension for the spring corresponding to the index. Prototype:
<void>setTension <index>springIndex <float>tension

Parameters:
<index>springIndex <float>tension

Remarks: Sets the tension for the spring corresponding to the index. The stiffness of the virtual spring between the controlled object and the highlighted spring object(s). Prototype:
<float>getDampening <index>springIndex

Parameters:
<index>springIndex

Return Value: Gets the dampening for the spring corresponding to the index. Prototype:
<void>setDampening <index>springIndex <float>dampening

Parameters:
<index>springIndex <float>dampening

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

Parameters:
<node>node

Remarks: Adds the node to the spring list.

528

Chapter 1

Whats New in 3ds max 4 MAXScript

Return Value: Returns true if successful, false otherwise Prototype:

<integer>getSpringCount()

Return Value: Returns the number of springs in the spring system. Prototype:
<void>removeSpringByIndex <index>springIndex

Parameters:
<index>springIndex

Remarks: Removes the spring corresponding to the index. Prototype:

<void>removeSpring <node>node

Parameters:
<node>node

Remarks: Removes the spring if the node is in the spring list.

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

Targa interfaces:

529

Targa interfaces:
This class represents the interface for the Bitmap IO TGA format. Interface: itgaio Methods: Prototype:
<integer>getColorDepth()

Return Value: This method returns the color depth, which would be 16, 24, or 32. Prototype:
<void>setColorDepth <integer>colorDepth

Remarks: This method allows you to set the color depth. Parameters:
<integer>colorDepth

The color depth, being either 16, 24, or 32. Prototype:

<boolean>getCompressed()

Return Value: This method returns TRUE if the compression flag is set, otherwise FALSE. Prototype:
<void>setCompressed <boolean>compression

Remarks: This method allows you to set the compression flag. Parameters:
<boolean>compression

TRUE to set the compression flag, otherwise FALSE. Prototype:

<boolean>getAlphaSplit()

Return Value: This method returns TRUE if the alpha split flag is set, otherwise FALSE. Prototype:
<void>setAlphaSplit <boolean>alphaSplit

Remarks: This method allows you to set the alpha split flag.

530

Chapter 1

Whats New in 3ds max 4 MAXScript

Parameters:
<boolean>alphaSplit

TRUE to set the alpha split flag, otherwise FALSE. Prototype:

<boolean>getPreMultAlpha()

Return Value: This method returns TRUE if the premultiplied alpha flag is set, otherwise FALSE. Prototype:
<void>setPreMultAlpha <boolean>preMultAlpha

Remarks: This method allows you to set the premultiplied alpha flag. Parameters:
<boolean>preMultAlpha

TRUE to set the premultiplied alpha flag, otherwise FALSE.

See Also
In The MAXSDK Help File Class IBitmapIO_Tga

Unwrap_UVW interfaces:
This class represents the interface to the UVW Unwrap Modifier. Interface: unwrap Methods: Prototype:
<void>planarMap()

Remarks: This method will press the Planar Map button in the rollup interface. Prototype:
<void>save()

Remarks: This method will press the Save button in the rollup interface. Prototype:
<void>load()

Remarks: This method will press the Load button in the rollup interface.

Unwrap_UVW interfaces:

531

Prototype:
<void>reset()

Remarks: This method will press the Reset button in the rollup interface. Prototype:
<void>edit()

Remarks: This method will press the Edit button in the rollup interface. Prototype:
<void>setMapChannel <integer> mapChannel

Remarks: This method will set the Map Channel field value in the rollup. Parameters:
<integer>mapChannel

The Map Channel you want to set to. Prototype:

<integer>getMapChannel()

Return Value: This method will return the Map Channel field in the rollup. Prototype:
<void>setProjectionType <integer>mapChannel

Parameters:
<integer>mapChannel

The mapping type:

1 2 3 4 for for for for X aligned Y aligned Z aligned normal aligned.

Remarks: This method will set the mapping type. Prototype:

<integer>getProjectionType()

Return Value: This method will return the mapping type; 1 for X aligned, 2 for Y aligned, 3 for Z aligned, 4 for normal aligned. Prototype:
<void>setVC <boolean>vertexColor

532

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method will set the Vertex Color Channel radio button in the rollup interface. Parameters:
<boolean>vertexColor

TRUE to enable; FALSE to disable. Prototype:

<boolean>getVC()

Return Value: This method returns the current state of the Vertex Color Channel radio button in the rollup interface. Prototype:
<void>move()

Remarks: This method will press the Move button in the edit floater. Prototype:
<void>moveh()

Remarks: This method will press the Move Horizontal button in the edit floater. Prototype:
<void>movev()

Remarks: This method will press the Move Vertical button in the edit floater. Prototype:
<void>rotate()

Remarks: This method will press the Rotate button in the edit floater. Prototype:
<void>scale()

Remarks: This method will press the Scale button in the edit floater. Prototype:
<void>scaleh()

Remarks: This method will press the Scale Horizontal button in the edit floater. Prototype:
<void>scalev()

Unwrap_UVW interfaces:

533

Remarks: This method will press the Scale Vertical button in the edit floater. Prototype:
<void>mirrorH()

Remarks: This method will press the Mirror Horizontal button in the edit floater. Prototype:
<void>mirrorV()

Remarks: This method will press the Mirror Vertical button in the edit floater. Prototype:
<void>expandSelection()

Remarks: This method will press the Expand Selection button in the edit floater. Prototype:
<void>contractSelection()

Remarks: This method will press the Contract Selection button in the edit floater. Prototype:
<void>setFalloffType <integer>falloffType

Remarks: This method will set the Falloff type. Parameters:

<integer>falloffType

The falloff type; 1 for linear, 2 for sinual, 3 for fast, and 4 for slow. Prototype:
<integer>getFalloffType()

Return Value: This method will return the falloff type; 1 for linear, 2 for sinual, 3 for fast, and 4 for slow. Prototype:
<void>setFalloffSpace <integer>falloffSpace

534

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method will set the space you want the falloff to be computed in. Parameters:
<integer>falloffSpace

The falloff space; 1 for XY, the local space of the object, 2 for UV, the UVW space of the object. Prototype:
<integer>getFalloffSpace()

Return Value: This method will return the falloff space; 1 for XY, the local space of the object, 2 for UV, the UVW space of the object. Prototype:
<void>setFalloffDist <float>falloffDist

Remarks: This method will set the falloff distance in the edit floater. Parameters:
<float>falloffDist

The falloff distance. Prototype:

<float>getFalloffDist()

Return Value: This method will return the falloff distance. Prototype:
<void>breakSelected()

Remarks: This method will press the Break Selected button in the edit floater. Prototype:
<void>weld()

Remarks: This method will press the Target Weld button in the edit floater. Prototype:
<void>weldSelected()

Remarks: This method will press the Weld Selected button in the edit floater. Prototype:
<void>updateMap()

Unwrap_UVW interfaces:

535

Remarks: This method will press the Update Map button in the edit floater. Prototype:
<void>DisplayMap <boolean>displayMap

Remarks: This method sets the state of the Display Map button in the edit floater Parameters:
<boolean>displayMap

TRUE to toggle the Display Map button on; FALSE to toggle it off. Prototype:
<boolean>IsMapDisplayed()

Return Value: This method returns the state of the Display Map button in the edit floater. TRUE if its on; FALSE if its off. Prototype:
<void>setUVSpace <integer>UVSpace

Remarks: This method sets the space that you want to view the texture vertices in. Parameters:
<integer>UVSpace

The texture space; 1 for UV, 2 for VW, 3 for UW. Prototype:
<integer>getUVSpace()

Return Value: This method returns the space that the texture vertices are viewed in; 1 for UV, 2 for VW, 3 for UW. Prototype:
<void>options()

Remarks: This method will press the Options button in the edit floater. Prototype:
<void>lock()

Remarks: This method will toggle the Lock Selected Vertices button in the edit floater. Prototype:
<void>hide()

536

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method will press the Hide button in the edit floater. Prototype:
<void>unhide()

Remarks: This method will press the Unhide button in the edit floater. Prototype:
<void>freeze()

Remarks: This method will press the Freeze button in the edit floater. Prototype:
<void>unfreeze()

Remarks: This method will press the Unfreeze button in the edit floater. Prototype:
<void>filterselected()

Remarks: This method will press the Filter Selected Faces button in the edit floater. Prototype:
<void>pan()

Remarks: This method will press the Pan button in the edit floater. Prototype:
<void>zoom()

Remarks: This method will press the Zoom button in the edit floater. Prototype:
<void>zoomRegion()

Remarks: This method will press the Zoom Region button in the edit floater. Prototype:
<void>fit()

Remarks: This method will press the Fit button in the edit floater.

Unwrap_UVW interfaces:

537

Prototype:
<void>fitselected()

Remarks: This method will press the Fit Selected button in the edit floater. Prototype:
<void>snap()

Remarks: This method will press the Snap button in the edit floater. Prototype:
<integer>getCurrentMap()

Return Value: This method returns the index into the map drop down list of the current map in the view of the edit floater. Prototype:
<void>setCurrentMap <integer>map

Remarks: This method sets the currently displayed map to the specified map index. Parameters:
<integer>map

The index of the map in the drop down list to display. Prototype:
<integer>numberMaps()

Return Value: This method returns the number of maps in the map drop down list. Prototype:
<point3>getLineColor()

Return Value: This method returns the color of the lines used to connect the texture vertices edges as a Point3 pointer. Prototype:
<void>setLineColor <point3>color

Remarks: This method sets the line color of the texture vertices. Parameters:
<point3>color

The color as a Point3.

538

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<point3>getSelectionColor()

Return Value: This method returns the texture vertices selection color as Point3. Prototype:
<void>setSelectionColor <point3>color

Remarks: This method sets the color of selected texture vertices. Parameters:
<point3>color

The color as a Point3. Prototype:

<integer>getRenderWidth()

Return Value: This method returns the width of the bitmap used to render 2d/3d textures to and if the Use Bitmap Resolution bitmaps is not set the width used to render bitmap. Prototype:
<void>setRenderWidth <integer>width

Remarks: This method sets the width of the bitmap used to render to for display. Parameters:
<integer>width

The width in pixels. Prototype:

<integer>getRenderHeight()

Return Value: This method returns the height of the bitmap used to render 2d/3d textures to and if the Use Bitmap Resolution bitmaps is not set the height used to render bitmap. Prototype:
<void>setRenderHeight <integer>height

Remarks: This method sets the width of the bitmap used to render to for display. Parameters:
<integer>height

The height in pixels. Prototype:

<boolean>getUseBitmapRes()

Unwrap_UVW interfaces:

539

Return Value: This method returns the state of the Use Bitmap Resolution, if false the bitmaps are rendered using the RenderWidth/Height values. Prototype:
<void>setUseBitmapRes <boolean>useRes

Remarks: This method sets the state of the Use Bitmap Resolution value. If it is false the bitmaps are rendered using the RenderWidth/Height values. Parameters:
<boolean>useRes

TRUE to toggle on; FALSE to toggle off. Prototype:

<float>getWeldThreshold()

Return Value: This method returns the weld threshold. Prototype:

<void>setWeldThreshold <float>height

Remarks: This method sets the threshold values for welds. Parameters:
<float>height

The welding threshold/ Prototype:

<boolean>getConstantUpdate()

Return Value: This method returns the state of the Constant Update value which when set true forces the veiwport to be updated on every move, otherwise it is just updated on mouse up. Prototype:
<void>setConstantUpdate <boolean>update

Remarks: This method Sets the state of the Constant Update value which when set true forces the viewport to be updated on every move, otherwise it is just updated on mouse up. Parameters:
<boolean>update

TRUE to toggle on; FALSE to toggle off. Prototype:

<boolean>getShowSelectedVertices()

540

Chapter 1

Whats New in 3ds max 4 MAXScript

Return Value: This method returns whether the selected texture vertices are also displayed in the view port. Prototype:
<void>setShowSelectedVertices <boolean>show

Remarks: This method sets whether the selected texture vertices are also displayed in the view port. Parameters:
<boolean>show

TRUE to toggle on; FALSE to toggle off. Prototype:

<boolean>getMidPixelSnap()

Return Value: This method returns whether the mid pixels snap is used, if it is false the snap is set to the bottom right corner of the pixel, else it snaps to the center of the pixel. Prototype:
<void>setMidPixelSnap <boolean>snap

Remarks: This method sets whether the mid pixels snap is used, if it is false the snap is set to the bottom right corner of the pixel, else it snaps to the center of the pixel. Parameters:
<boolean>snap

TRUE to toggle on; FALSE to toggle off. Prototype:

<integer>getMatID()

Return Value: This method returns the current material id index filter. Prototype:
<void>setMatID <integer>matid

Remarks: This method sets the material drop list to the index supplied. Parameters:
<integer>matid

The material ID index to set. Prototype:

<integer>numberMatIDs()

Return Value: This method returns the number of material ids in the material id filter drop down.

Unwrap_UVW interfaces:

541

Prototype:
<bitArray>getSelectedVertices()

Return Value: This method returns the current selected texture vertices in the edit floater as a bit array. Prototype:
<void>selectVertices <bitArray>selection

Remarks: This method selects texture vertices in the edit floater dialog. Parameters:
<bitArray>selection

The selection set as a bit array. Prototype:

<boolean>isVertexSelected <integer>index

Parameters:
<integer>index

The index of the vertex to check. Return Value: This method returns whether a texture vertex is selected. Prototype:
<void>MoveSelectedVertices <point3>offset

Remarks: This method moves the selected texture vertices by the offset. Parameters:
<point3>offset

The offset by which you want to move the vertices. Prototype:

<void>RotateSelectedVerticesCenter <float>angle

Remarks: This method rotates the selected vertices around their center point. Parameters:
<float>angle

The angle in radians that you want to rotate the selection by. Prototype:
<void>RotateSelectedVertices <float>angle <point3>axis

542

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method rotates the selected vertices around a specified point. Parameters:
<float>angle

The angle in radians that you want to rotate the selection by.
<point3>axis

The axis that you want to rotate the selected vertices by. This is in the space of the window. Prototype:
<void>ScaleSelectedVerticesCenter <float>scale <integer>dir

Remarks: This method scales the selected points around their center. Parameters:
<float>scale

The amount that you want to scale by

<integer>dir

The direction; 1 for uniform scaling, 2 for X, and 3 for Y. Prototype:

<void>ScaleSelectedVertices <float>scale <integer>dir <point3>axis

Remarks: This method scales the selected points around a specified point. Parameters:
<float>scale

The amount that you want to scale by

<integer>dir

The direction; 1 for uniform scaling, 2 for X, and 3 for Y.

<point3>axis

The axis that you want to scale the selected vertices by. This is in the space of the window. Prototype:
<point3>GetVertexPosition <time>time <integer>index

Parameters:
<time>time

The time at which you want to get the vertex.

<integer>index

The index of the vertex. Return Value: This method returns the position of the vertex.

Unwrap_UVW interfaces:

543

Prototype:
<integer>numberVertices()

Return Value: This method returns the number of texture vertices Prototype:
<void>moveX <float>p

Remarks: This method sets the selected vertices x values in absolute coordinates. Parameters:
<float>p

The absolute position along the x axis Prototype:

<void>moveY <float>p

Remarks: This method sets the selected vertices y values in absolute coordinates. Parameters:
<float>p

The absolute position along the y axis Prototype:

<void>moveZ <float>p

Remarks: This method sets the selected vertices z values in absolute coordinates. Parameters:
<float>p

The absolute position along the s axis Prototype:

<bitArray>getSelectedPolygons()

Return Value: This method returns the selected polygons in the view port as a bit array. Prototype:
<void>selectPolygons <bitArray>selection

Remarks: This method selects the polygons in the view ports. Parameters:
<bitArray>selection

The polygons you wish to select.

544

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<boolean>isPolygonSelected <integer>index

Parameters:
<integer>index

The index of the polygon to check. Return Value: This method returns whether a polygon is selected or not. Prototype:
<integer>numberPolygons()

Return Value: This method returns the number of polygons in the object. Prototype:
<void>detachEdgeVertices()

Remarks: This method detaches any vertex that is not completely surrounded by selected vertices. This is similar to a polygon selection detach except it uses the vertex selection to determine what is detached. Prototype:
<void>flipHorizontal()

Remarks: This method will press the Flip Horizontal button in the edit floater. Prototype:
<void>flipVertical()

Remarks: This method will press the Flip Vertical button in the edit floater. Prototype:
<boolean>getLockAspect()

Remarks: This method returns whether the edit window aspect ratio is locked or not, if the aspect ratio is not locked the image will try stretch to fit the aspect ratio of the window. Return Value: TRUE if locked; FALSE if unlocked. Prototype:
<void>setLockAspect <boolean>aspect

Unwrap_UVW interfaces:

545

Remarks: This method sets the Lock Aspect Ratio value Parameters:
<boolean>aspect

TRUE to lock; FALSE to unlock. Prototype:

<float>getMapScale()

Return Value: This method returns the scaling factor when the user applies a planar map. The smaller the value the more planar map is scaled down. Prototype:
<void>setMapScale <float>scale

Remarks: This method sets the scaling factor when the user applies a planar map. The smaller the value the more planar map is scaled down Parameters:
<float>scale

The scaling factor for planar map. Prototype:

<void>getSelectionFromFace()

Remarks: This method takes the current polygon selection and uses it to select the texture vertices that are associated with it. Prototype:
<void>forceUpdate <boolean>update

Remarks: This method sets a flag to determines how Unwrap will behave when a topology change occurs. If update is TRUE the mapping gets reset, otherwise unwrap skips mapping the object if it has a different topology. It is sometimes useful to turn this off if you have MeshSmooth or other topology changing modifiers below Unwrap that have different topologies when rendering. Parameters:
<boolean>update

This determines whether the mapping is reset on topology change. TRUE to update, otherwise FALSE. Prototype:
<void>zoomToGizmo <boolean>all

546

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method zooms the selected or all the viewports to zoom to the current planar map gizmo. Parameters:
<boolean>all

This determines whether the active or all the viewports get zoomed. TRUE to zoom all viewports, FALSE to view the active viewport. Prototype:
<void>setVertexPosition <time>time <integer>index <point3>pos

Remarks: This method sets the position of a UVW vertex at a specific time. Parameters:
<time>time

The time at what you want to set the position.

<integer>index

The index of the vertex.

<point3>pos

The position of the vertex in UVW space. Prototype:

<void>markAsDead <integer>index

Remarks: This method marks a vertex that it is dead, and no longer in use. Vertices are not actually deleted they are just marked and recycled when needed. That means when a vertex is added vertices marked as dead will be the first ones checked. If there are no dead vertices, the vertex is appended to the end of the list. Using this function carefully since marking a vertex as dead that is actually in use will cause strange results. Parameters:
<integer>index

The index of the vertex to mark as dead. Prototype:

<integer>numberPointsInFace <integer>index

Parameters:
<integer>index

The index of the face to inspect. Return Value: This method retrieves the numbers of vertices that a face contains. A face can contain 3 to N number of points depending on what type of topology Unwrap is working on. For Tri Meshes this is always 3, for patches this can be 3 or 4, and for polygons this can be 3 or greater. Unwrap abstracts all three object types into one generic format.

Unwrap_UVW interfaces:

547

Prototype:
<integer>getVertexIndexFromFace <integer>faceIndex <integer>ithVertex

Parameters:
<integer>faceIndex

The index of the face to inspect.

<integer>ithVertex

The I-th vertex of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains. Prototype:
<integer>getHandleIndexFromFace <integer>faceIndex <integer>ithVertex

Parameters:
<integer>faceIndex <integer>ithVertex

The index of the face to inspect.

<integer>ithVertex

The I-th handle of that you want to retrieve. This value should range from 1 to the number of vertices*2 that the face contains. Return Value: This method retrieves the index of a handle, from a face. A face contains 0 to N number of handles. So to retrieve a particular handle index, you give it the face index and the I-th handle that you want to inspect. So if you wanted to look at the 3 handle on face 1 you would call GetHandleIndexFromFace(1,3). This only applies for patch meshes. Prototype:
<integer>getInteriorIndexFromFace <integer>faceIndex <integer>ithVertex

Parameters:
<integer>faceIndex

The index of the face to inspect.

<integer>ithVertex

The I-th interior handle of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains. Return Value: This method retrieves the index of a interior handle, from a face. A face contains 0 to N number of interior handles. So to retrieve a particular interior handle index, you give it the face index and the I-th interior handle that you want to inspect. So if you wanted to look at the 3 interior handle on face 1 you would call GetInteriorIndexFromFace(1,3). This only applies for patch meshes.

548

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<integer>getVertexGeomIndexFromFace <integer>faceIndex <integer>ithVertex

Parameters:
<integer>faceIndex

The index of the face to inspect.

<integer>ithVertex

The I-th vertex of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains. Return Value: This method retrieves the index of a geometric vertex, from a face. This the vertex that is attached to the mesh and not the texture faces. A face contains 0 to N number of vertices. So to retrieve a particular vertex index, you give it the face index and the I-th vertex that you want to inspect. So if you wanted to look at the 3 vertex on face 1 you would call GetVertexGeomIndexFromFace(1,3). Prototype:
<integer>getHandleGeomIndexFromFace <integer>faceIndex <integer>ithVertex

Parameters:
<integer>faceIndex

The index of the face to inspect.

<integer>ithVertex

The I-th handle of that you want to retrieve. This value should range from 1 to the number of vertices*2 that the face contains. Return Value: This method retrieves the index of a geometric handle from a patch. This the handle that is attached to the patch and not the texture faces. A face contains 0 to N number of handle. So to retrieve a particular handle index, you give it the face index and the I-th handle that you want to inspect. So if you wanted to look at the 3 handle on face 1 you would call GetHandleGeomIndexFromFace(1,3). Prototype:
<integer>getInteriorGeomIndexFromFace <integer>faceIndex <integer>ithVertex

Parameters:
<integer>faceIndex

The index of the face to inspect.

<integer>ithVertex

The I-th interior handle of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains. Return Value: This method retrieves the index of a geometric interior handle from a patch. This the interior handle that is attached to the patch and not the texture faces. A face contains 0 to N number of interior handle. So to retrieve a particular interior handle index, you give it the face index and the I-th

Unwrap_UVW interfaces:

549

interior handle that you want to inspect. So if you wanted to look at the 3 interior handle on face 1 you would call GetInteriorGeomIndexFromFace(1,3). Prototype:
<void>setFaceVertex <point3>pos <integer>faceIndex <integer>ithVertex <boolean> sel

Remarks: This method allows you to manipulate the position of vertex attached to a face. Basically it detaches the vertex if multiple faces share that vertex and then moves it to the position specified. So if you want to move the 3rd vertex of face 1 to .5,.5,.0 you would do setFaceVertex [.5 .5 .0] 1 3. If you dont want the vertex broken use SetVertexSPosition. Parameters:
<point3>pos

The position that you want to move a vertex to.

<integer>faceIndex

The index of the face that you wish to work on.

<integer>ithVertex

The ith vertex of the face that you want to change

<boolean>sel

Whether or not to select the vertex after it is recreated Prototype:

<void>setFaceHandle <point3>pos <integer>faceIndex <integer>ithVertex <boolean> sel

Remarks: This method is identical to SetFaceVertex except works on patch handles. Parameters:
<point3>pos

The position that you want to move a vertex to.

<integer>faceIndex

The index of the face that you wish to work on.

<integer>ithVertex

The ith vertex of the face that you want to change

<boolean>sel

Whether or not to select the vertex after it is recreated Prototype:

<void>setFaceInterior <point3>pos <integer>faceIndex <integer>ithVertex <boolean>sel

Remarks: This method is identical to SetFaceVertex except works on patch interior handles. Parameters:
<point3>pos

The position that you want to move a vertex to.

550

Chapter 1

Whats New in 3ds max 4 MAXScript

<integer>faceIndex

The index of the face that you wish to work on.

<integer>ithVertex

The ith vertex of the face that you want to change

<boolean>sel

Whether or not to select the vertex after it is recreated Prototype:

<void>setFaceVertexIndex <integer>faceIndex <integer>ithVertex <integer>vertexIndex

Remarks: This method allows you to set the index of the ith vertex of a face. Parameters:
<integer>faceIndex

The index of the face that you wish to work on.

<integer>ithVertex

The ith vertex of the face that you want to manipulate.

<integer>vertexIndex

The index into the vertex list that you want to set to Prototype:
<void>setFaceHandleIndex <integer>faceIndex <integer>ithVertex <integer>vertexIndex

Remarks: This method is identical to setFaceVertexIndex but works on handles for patches. Parameters:
<integer>faceIndex

The index of the face that you wish to work on.

<integer>ithVertex

The ith vertex of the face that you want to manipulate.

<integer>vertexIndex

The index into the vertex list that you want to set to Prototype:
<void>setFaceInteriorIndex <integer>faceIndex <integer>ithVertex <integer>vertexIndex

Remarks: This method is identical to setFaceVertexIndex but works on interior handles for patches. Parameters:
<integer>faceIndex

The index of the face that you wish to work on.

<integer>ithVertex

The ith vertex of the face that you want to manipulate.

uvwMappingHeightManip interfaces:

551

<integer>vertexIndex

The index into the vertex list that you want to set to Prototype:
<void>updateView()

Remarks: This method forces the viewport and dialog to update. Prototype:
<void>getFaceSelectionFromStack()

Remarks: This method looks at the current face selection in the stack, and copies it to the unwrap face selection. The reason this is useful is that if some one creates a new selection modifier Unwrap can use it. An example would be if you applied to Unwrap to a whole editable mesh, then you went back into the editable mesh, selected some faces by smoothing group, then turned off the face subobject selection. If you went back to Unwrap you could get this selection by calling getFaceSelectionFromStack.

See Also
In The MAXSDK Help File Class IUnwrapMod

uvwMappingHeightManip interfaces:
Interface: Manip Properties:
.mouseState : enum : Read mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods: Prototype:
<void>clearGizmos()

Remarks: This must be called at the beginning of the updateGizmos handler in order to clear the current gizmo cache.

552

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<void>addGizmoMesh <mesh> mesh <integer>flags <point3 by value> unselColor <point3 by value>selColor

Parameters:
<mesh>mesh <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this is to create an instance of a primitive and get the mesh from it. The flags can be 0, or one or more of these values. If you want more than one flag to apply, then you add the values together. Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<Interface>gizmo <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.
gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

uvwMappingHeightManip interfaces:

553

Remarks: This creates a gizmo from a shape object. The gizmoShape can be created using functions from the manip package, described below. The flags can take on the same value as for addGizmoMesh, with two new values supported: Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor marker enums: {#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond |#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

Parameters:
<enum>marker <point3 by value>position

The position is a point in 3d space, or 2d screen space.

<integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.
gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by addGizmoShape.

554

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<void>addGizmoText <string> text <point3 by value>position <integer> flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the mouse. It is used for display purposes only. Prototype:
<ray by value>getLocalViewRay <point2 by value>m

Parameters:
<point2 by value>m

Return Value: This function takes a mouse position and returns the ray that passes through that mouse position in the direction of the view. It is returned in the local coordinates of the node that owns the manipulator target. Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip

Remarks: Parameters:
<time>t <&TSTR>toolTip

toolTip is In parameter

See Also
Scripted Manipulators (p. 97) Interface: manip (p. 366) radiusManip interfaces: (p. 500) ConeAngleManip - superclass: helper (p. 277) PlaneAngleManip - superclass: helper (p. 311) Scripted Plug-ins (p. 1538) sliderManipulator - superclass: helper (p. 333) sliderManipulator interfaces: (p. 520) uvwMappingHeightManip interfaces: (p. 551)

uvwMappingLengthManip interfaces:

555

uvwMappingLengthManip interfaces: (p. 555) uvwMappingUTileManip interfaces: (p. 558) uvwMappingVTileManip interfaces: (p. 562) uvwMappingWidthManip interfaces: (p. 565)

uvwMappingLengthManip interfaces:
Interface: Manip Properties:
.mouseState : enum : Read mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods: Prototype:
<void>clearGizmos()

Remarks: This must be called at the beginning of the updateGizmos handler in order to clear the current gizmo cache. Prototype:
<void>addGizmoMesh <mesh> mesh <integer>flags <point3 by value> unselColor <point3 by value>selColor

Parameters:
<mesh>mesh <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this is to create an instance of a primitive and get the mesh from it. The flags can be 0, or one or more of these value. If you want more than one flag to apply, then you add the values together.

556

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<Interface>gizmo <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.
gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a shape object. The gizmoShape can be created using functions from the manip package, described below. The flags can take on the same value as for addGizmoMesh, with two new values supported: Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor marker enums: {#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond |#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

Parameters:
<enum>marker <point3 by value>position

The position is a point in 3d space, or 2d screen space.

<integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

uvwMappingLengthManip interfaces:

557

gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.
gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by addGizmoShape. Prototype:
<void>addGizmoText <string> text <point3 by value>position <integer> flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the mouse. It is used for display purposes only. Prototype:
<ray by value>getLocalViewRay <point2 by value>m

Parameters:
<point2 by value>m

Return Value: This function takes a mouse position and returns the ray that passes through that mouse position in the direction of the view. It is returned in the local coordinates of the node that owns the manipulator target. Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip

Remarks: Parameters:
<time>t <&TSTR>toolTip

558

Chapter 1

Whats New in 3ds max 4 MAXScript

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

uvwMappingUTileManip interfaces:
Interface: Manip Properties:
.mouseState : enum : Read mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods: Prototype:
<void>clearGizmos()

Remarks: This must be called at the beginning of the updateGizmos handler in order to clear the current gizmo cache. Prototype:
<void>addGizmoMesh <mesh> mesh <integer>flags <point3 by value> unselColor <point3 by value>selColor

Parameters:
<mesh>mesh <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

uvwMappingUTileManip interfaces:

559

gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this is to create an instance of a primitive and get the mesh from it. The flags can be 0, or one or more of these values. If you want more than one flag to apply, then you add the values together. Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<Interface>gizmo <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.
gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a shape object. The gizmoShape can be created using functions from the manip package, described below.

560

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor marker enums: {#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond |#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

Parameters:
<enum>marker <point3 by value>position

selColor The position is a point in 3d space, or 2d screen space.

<integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.
gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: The creates a gizmo using a marker. Prototype:

<void>addGizmoText <string> text <point3 by value>position <integer> flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the mouse. It is used for display purposes only.

uvwMappingUTileManip interfaces:

561

Prototype:
<ray by value>getLocalViewRay <point2 by value>m

Parameters:
<point2 by value>m

Return Value: This function takes a mouse position and returns the ray that passes through that mouse position in the direction of the view. It is returned in the local coordinates of the node that owns the manipulator target. Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip

Remarks: Parameters:
<time>t <&TSTR>toolTip

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

562

Chapter 1

Whats New in 3ds max 4 MAXScript

uvwMappingVTileManip interfaces:
Interface: Manip Properties:
.mouseState : enum : Read mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods: Prototype:
<void>clearGizmos()

Remarks: This must be called at the beginning of the updateGizmos handler in order to clear the current gizmo cache. Prototype:
<void>addGizmoMesh <mesh> mesh <integer>flags <point3 by value> unselColor <point3 by value>selColor

Parameters:
<mesh>mesh <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this is to create an instance of a primitive and get the mesh from it. The flags can be 0, or one or more of these values. If you want more than one flag to apply, then you add the values together. Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<Interface>gizmo <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.

uvwMappingVTileManip interfaces:

563

gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.
gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a shape object. The gizmoShape can be created using functions from the manip package, described below. The flags can take on the same value as for addGizmoMesh, with two new values supported: Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor marker enums: {#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond |#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

Parameters:
<enum>marker <point3 by value>position

The position is a point in 3d space, or 2d screen space.

<integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.

564

Chapter 1

Whats New in 3ds max 4 MAXScript

gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: The creates a gizmo using a marker. Prototype:

<void>addGizmoText <string> text <point3 by value>position <integer> flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the mouse. It is used for display purposes only. Prototype:
<ray by value>getLocalViewRay <point2 by value>m

Parameters:
<point2 by value>m

Return Value: This function takes a mouse position and returns the ray that passes through that mouse position in the direction of the view. It is returned in the local coordinates of the node that owns the manipulator target. Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip

Remarks: Parameters:
<time>t <&TSTR>toolTip

uvwMappingWidthManip interfaces:

565

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

uvwMappingWidthManip interfaces:
Interface: Manip Properties:
.mouseState : enum : Read mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}

Methods: Prototype:
<void>clearGizmos()

Remarks: This must be called at the beginning of the updateGizmos handler in order to clear the current gizmo cache. Prototype:
<void>addGizmoMesh <mesh> mesh <integer>flags <point3 by value> unselColor <point3 by value>selColor

Parameters:
<mesh>mesh <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.

566

Chapter 1

Whats New in 3ds max 4 MAXScript

gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this is to create an instance of a primitive and get the mesh from it. The flags can be 0, or one or more of these value. If you want more than one flag to apply, then you add the values together. Prototype:
<void>addGizmoShape <Interface>gizmo <integer>flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<Interface>gizmo <integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.
gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo from a shape object. The gizmoShape can be created using functions from the manip package, described below. Prototype:
<void>addGizmoMarker <enum>marker <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor marker enums: {#point|#hollowBox|#plusSign|#asterisk|#xMarker|#bigBox|#circle|#triangle|#diamond |#smallHollowBox|#smallCircle|#smallTriangle|#smallDiamond|#dot|#smallDot}

uvwMappingWidthManip interfaces:

567

Parameters:
<enum>marker <point3 by value>position

The position is a point in 3d space, or 2d screen space.

<integer>flags gizmoDontDisplay

Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
gizmoDontHitTest

Tells the system to not hit-test the gizmo. It will be displayed, but not hit-tested.
gizmoActiveViewportOnly

Tells the system to only display and hit-test this gizmo in the active viewport.
gizmoUseScreenSpace

This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the Z coordinate is ignored.
gizmoUseRelativeScreenSpace

This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport.
<point3 by value>unselColor <point3 by value>selColor

Remarks: The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by addGizmoShape. Prototype:
<void>addGizmoText <string> text <point3 by value>position <integer> flags <point3 by value>unselColor <point3 by value>selColor

Parameters:
<string>text <point3 by value>position <integer>flags <point3 by value>unselColor <point3 by value>selColor

Remarks: This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the mouse. It is used for display purposes only. Prototype:
<ray by value>getLocalViewRay <point2 by value>m

Parameters:
<point2 by value>m

568

Chapter 1

Whats New in 3ds max 4 MAXScript

Return Value: This function takes a mouse position and returns the ray that passes through that mouse position in the direction of the view. It is returned in the local coordinates of the node that owns the manipulator target. Prototype:
<void>updateGizmos <time>t <&TSTR>toolTip

Remarks: Parameters:
<time>t <&TSTR>toolTip

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

UVWUnwrap interfaces:
See Also
Unwrap_UVW interfaces: (p. 530)

Float_Wire interfaces:

569

Float_Wire interfaces:
This represents the interface for individual wire controllers. Interface: wireController Properties:
.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).
.isMaster : boolean : Read

This property will return TRUE if the wire is a master predicate, otherwise it will return FALSE.
.isSlave : boolean : Read

This method will return TRUE if the wire is a slave predicate, otherwise it will return FALSE.
.isTwoWay : boolean : Read

This method will return TRUE if the wire is a two-way predicate, otherwise it will return FALSE.
.slaveAnimation : control : Read|Write

This method returns a pointer to the slave animation controller. This method allows you to set the slave animation controller. Prototype:
<maxObject>getWireParent <index>index

Parameters:
<index>index

The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype:
<integer>getWireSubnum <index>index

Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters:
<index>index

The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable.

570

Chapter 1

Whats New in 3ds max 4 MAXScript

Prototype:
<control>getCoController <index>index

Parameters:
<index>index

The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype:
<string>getExprText <index>index

Parameters:
<index>index

The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype:
<void>setExprText <index>index <string>text

Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters:
<index>index

The index of the parameter

<string>text

The expression you wish to set.

See Also
In The MAXSDK Help File Class IBaseWireControl

Point3_Wire interfaces:
Interface: wireController Properties:
.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).
.isMaster : boolean : Read

This property will return TRUE if the wire is a master predicate, otherwise it will return FALSE.

Point3_Wire interfaces:

571

.isSlave : boolean : Read

This method will return TRUE if the wire is a slave predicate, otherwise it will return FALSE.
.isTwoWay : boolean : Read

This method will return TRUE if the wire is a two-way predicate, otherwise it will return FALSE.
.slaveAnimation : control : Read|Write

This method returns a pointer to the slave animation controller. This method allows you to set the slave animation controller. Prototype:
<maxObject>getWireParent <index>index

Parameters:
<index>index

The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype:
<integer>getWireSubnum <index>index

Parameters:
<index>index

The index of the subanim. Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype:
<control>getCoController <index>index

Parameters:
<index>index

The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype:
<string>getExprText <index>index

Parameters:
<index>index

The index of the parameter.

572

Chapter 1

Whats New in 3ds max 4 MAXScript

Return Value: This method returns the expression string of the i-th wire parameter. Prototype:
<void>setExprText <index>index <string>text

Parameters:
<index>index

The index of the parameter

<string>text

The expression you wish to set. Remarks: This method allows you to set the expression string of the i-th wire parameter.

See Also
In The MAXSDK Help File Class IBaseWireControl

Rotation_Wire interfaces:
This represents the interface for individual wire controllers. Interface: wireController Properties:
.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).
.isMaster : boolean : Read

This property will return TRUE if the wire is a master predicate, otherwise it will return FALSE.
.isSlave : boolean : Read

This method will return TRUE if the wire is a slave predicate, otherwise it will return FALSE.
.isTwoWay : boolean : Read

This method will return TRUE if the wire is a two-way predicate, otherwise it will return FALSE.
.slaveAnimation : control : Read|Write

This method returns a pointer to the slave animation controller. This method allows you to set the slave animation controller.

Rotation_Wire interfaces:

573

Prototype:
<maxObject>getWireParent <index>index

Parameters:
<index>index

The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype:
<integer>getWireSubnum <index>index

Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters:
<index>index

The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype:
<control>getCoController <index>index

Parameters:
<index>index

The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype:
<string>getExprText <index>index

Parameters:
<index>index

The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype:
<void>setExprText <index>index <string>text

574

Chapter 1

Whats New in 3ds max 4 MAXScript

Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters:
<index>index

The index of the parameter

<string>text

The expression you wish to set.

See Also
In The MAXSDK Help File Class IBaseWireControl

Scale_Wire interfaces:
This represents the interface for individual wire controllers. Interface: wireController Properties:
.numWires : integer : Read

This property returns the number of wires out of this controller (i.e. the number of dependent params).
.isMaster : boolean : Read

This property will return TRUE if the wire is a master predicate, otherwise it will return FALSE.
.isSlave : boolean : Read

This method will return TRUE if the wire is a slave predicate, otherwise it will return FALSE.
.isTwoWay : boolean : Read

This method will return TRUE if the wire is a two-way predicate, otherwise it will return FALSE.
.slaveAnimation : control : Read|Write

This method returns a pointer to the slave animation controller. This method allows you to set the slave animation controller. Prototype:
<maxObject>getWireParent <index>index

Parameters:
<index>index

The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent.

Scale_Wire interfaces:

575

Prototype:
<integer>getWireSubnum <index>index

Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters:
<index>index

The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype:
<control>getCoController <index>index

Parameters:
<index>index

The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype:
<string>getExprText <index>index

Parameters:
<index>index

The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype:
<void>setExprText <index>index <string>text

Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters:
<index>index

The index of the parameter

<string>text

The expression you wish to set.

See Also
In The MAXSDK Help File Class IBaseWireControl

576

Chapter 1

Whats New in 3ds max 4 MAXScript

Chapter 2:

Learning MAXScript

Welcome to Learning MAXScript. This introductory reference helps you get started using MAXScript, the scripting language that is built into 3ds max . Learning MAXScript can be used as an introductory reference. However, it is most useful if read straight through as a tutorial. You can follow the examples in this reference by using drag-and-drop or copy-and-paste to bring the code from this document into the MAXScript Listener. You can also type in your own text and start experimenting with MAXScript as you learn it.

Getting Started
Accessing MAXScript (p. 579) Source Code Layout (p. 580) Entering Information into MAXScript (p. 582) Assigning Variables (p. 585) Mathematical Operations in MAXScript (p. 588)

Working with 3ds max Objects

Drawing a Box with MAXScript (p. 591) Modifying the Box (p. 593) Applying Standard Transformations (p. 598) More Box Transformations (p. 603)

Creating Your Own Scripts

Controlling Program Flow in Scripts (p. 607) Defining Custom Functions (p. 614) Structure Definitions (p. 618) 3ds max Commands in MAXScript (p. 620)

578

Chapter 2

Learning MAXScript

Where to Go From Here

Saving your Commands in a Script File (p. 621) Loading and Running Your Script File (p. 621) Loading Other Scripts (p. 623) Learning MAXScript by Walking Through a Script (p. 623) Learning MAXScript with the Macro Recorder (p. 624)

Some Advanced Topics Include:

Action Manager (p. 9) ActiveX Controls in MAXScript Rollouts (p. 10) Asset Browser enhancements (p. 22) Curve Control (p. 170) Customize The Order of Rollup Pages (p. 185) General Event Callback Mechanism (p. 29) iDrop - drag and drop (p. 62) Interfaces (p. 67) Menu Manager (p. 75) Network Render Interface (p. 82) Parameter Wiring (p. 85) Quad Menu (p. 90) Scripted Custom Attributes (p. 45) Scripted Manipulators (p. 97) Visual MAXScript (p. 117) Zip-file Script Packages (p. 122)

Accessing MAXScript

579

Accessing MAXScript
MAXScript is the built-in scripting language for 3ds max (version 2.0 or higher.) Because of this, you can use MAXScript only when 3ds max is running. There are several ways to access MAXScript from within 3ds max. The easiest way is to select MAXScript Listener from the MAXScript menu. The other way to start MAXScript is as follows: 1. On the Command panel, choose Utility, and click MAXScript. The MAXScript rollout appears:

2.

Click Open Listener. The MAXScript Listener window appears with its Welcome message:

580

Chapter 2

Learning MAXScript

The MAXScript Listener window is an interactive interpreter for the MAXScript language and works similarly to a DOS command prompt window. Enter MAXScript commands in this window, and press ENTER to execute them immediately. Only one instance of the MAXScript Listener window can be open at a time. The Listener is a resizable, modeless window. You can switch between it and the software as you work. If you close the Listener window and then reopen it, any text that was in the window before it was closed reappears. The Listener is divided into two panes. The top (pink) pane is the Macro Recorder pane; the bottom (white) pane is the output pane. The Macro Recorder plane is hidden when the Listener is opened; drag the splitter bar down to open it. When the Macro Recorder is enabled, every recordable command is displayed in the Macro Recorder pane. The output of results from scripts is displayed in the output pane. The output of code executed in the Macro Recorder pane is always directed to the output pane to prevent cluttering the recordings. Both panes allow you to cut-and-paste, drag-and-drop, edit, select, and execute code. You can resize the panes by dragging on the split bar between them. The left end of the status bar contains a resizable Mini Listener.

If the Mini Listener is not visible, drag on the vertical split bar at the left edge of the status panel to reveal this feature. The Mini Listener panes act as single-line sliding windows for the current line in corresponding Listener panes. The Mini Listener panes always show what you are typing or where the cursor is placed in the Listener panes. Conversely, anything you enter into a Mini Listener pane is entered into the corresponding Listener pane at the current cursor position. To install Listener into a viewport: 1. 2. 3. Right-click the viewport label. Choose Extended. Choose MAXScript Listener.

Source Code Layout

The layout rules for MAXScript code are unlike those of most programming languages. MAXScript gives you the advantage of freeform languages, such as C and C++, without the need for extensive punctuation. MAXScript lets you break statements and expressions across lines wherever you want. The line break can be in the middle of an expression. MAXScript reads your code until the end of each line and determines whether it has a complete expression. If it does not, it continues to read subsequent lines until it finds the rest of the expression.

Source Code Layout

581

Take as an example the following line:

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

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

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

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

Whenever MAXScript encounters a \ as the last character on a line (except for spaces, tabs, or comments), it continues to read the next line as though the break were not present. Line continuations can be useful for breaking up long or complex lines of code, making them easier to read. MAXScript also lets you combine multiple statements and expressions in a single line. The statements or expressions are separated with a ;, for example:

582

Chapter 2

Learning MAXScript

Sometimes it is useful to enter comments within your script to provide guidance or context. You can enter comments in MAXScript by preceding your comment with a double-hyphen (--). As soon as MAXScript reaches the double-hyphen, it stops evaluating the rest of that line. For example:

Entering Information into MAXScript

There are several different types of information that you will typically want to enter into the MAXScript Listener window. These include numeric values, strings, and arrays. Information is generally entered into MAXScript by typing a value or expression and pressing ENTER. However, each type of information must be entered in a slightly different way.

Entering Numbers in MAXScript

MAXScript distinguishes between two types of numbers: integers and floats. An integer is a whole number, such as 0, 1, 2, 10, 527. Floats are floating-point numbers and contain decimal points, such as 2.5, 72.0, and 0.33. When MAXScript performs numerical operations, the result is generally the same number-type as the arguments in the operation. For example: 3 + 4 will return 7, while 3.0 + 4.0 will return 7.0.

Entering Information into MAXScript

583

When MAXScript performs operations involving both float and integer-type numbers however, it treats the integer as a float number. For example: 3 + 4.0 will return 7.0.

Entering Strings in MAXScript

MAXScript is an expression-based language. All of its constructs yield a value. Strings are MAXScript constructs, and they are entered inside quotation marks. The command output for a string, meaning the value a string yields in MAXScript, is the string itself. With the MAXScript Listener window open, say hello to MAXScript: 1. At the prompt, type Hello and press ENTER. MAXScript answers with undefined. This is called command output, which always appears in blue. The reason for this specific output is that MAXScript doesnt know the word Hello. It is not defined in the language and therefore MAXScript cannot determine what to do with it.

584

Chapter 2

Learning MAXScript

2.

Write the word Hello again, this time with quotation marks, and press ENTER. The command output is now Hello. It seems that MAXScript knows the string Hello because it answers with a friendly Hello. Actually, it merely knows that you entered a string, and the command output for strings is always the value of the string you entered.

Entering Arrays in MAXScript

You can use an array to group several elements into one collection. An array is an ordered collection of values. In MAXScript, each element in the array can contain any type of value, and all of the elements can be accessed individually. An array can be expressed in two forms. The first is:
#()

This is the most basic type of array: an empty one. It is important to note that all arrays must be defined with the pound character (#) and a pair of parentheses.

Assigning Variables

585

#( <expr> , <expr> )

This form of the array is appropriate when you would like to define one or more of the initial elements within the array. Each value of <expr> can be a number, an expression (e.g., sin pi, 6.2^3), or a string (e.g., hello). Elements do not have to be the same type of information, and there is no limit on the number of elements you can have in an array.

Assigning Variables
In the previous lesson, you entered the string Hello in MAXScript, and MAXScript displayed the same string as its command output. When you enter other strings, MAXScript displays them and forgets about the previous ones. To make MAXScript remember the value of a string, assign it to a variable. The general syntax for assigning a variable in MAXScript is:
variable_name = variable_value

A variable_name starts with an alphabetic character or _ (underscore), followed by any number of alphanumeric characters. The variable_value can be a string, a number, or any other expression.

586

Chapter 2

Learning MAXScript

To assign a string to a variable: 1. At the Listener prompt, enter the following command:
mystring = This is my string.

MAXScript returns the value of the string variable:

2.

You can now refer to this string variable by entering the variables name. Enter mystring. MAXScript again returns the value of the string variable:

This is faster than entering the string again. MAXScript remembers this string for as long as your MAXScript session is open, or until you change the variables value.

Assigning Variables

587

To assign a new value to an existing variable: 1. Enter mystring = This is not your string. MAXScript now displays the new value of mystring:

2.

When you refer to mystring now, MAXScript uses the new value. Enter mystring. MAXScript now displays the new variable value:

Notice that MAXScript doesnt distinguish between lowercase and uppercase variable names because MAXScript names are not case-sensitive.

588

Chapter 2

Learning MAXScript

Mathematical Operations in MAXScript

Besides strings, you can enter other types of data into MAXScript. MAXScript not only recognizes numeric characters as numbers, it can also perform mathematical operations with them. As with strings, if you just enter a number by itself, MAXScript echoes it back to you; it evaluates the number and displays its value. Mathematical operations are more interesting.

Basic Mathematical Operations

MAXScript has many built-in functions that let you use MAXScript as a calculator. Enter 36.5 * 2, for example, to see what a certain dimension needs to be if you want to double it.

MAXScript returns the result of the calculation. This is useful for quick calculations where loading an external calculator program doesnt seem worth the trouble. MAXScript also recognizes several mathematical constants. Enter pi.

MAXScript knows the value of pi and returns it.

Mathematical Operations in MAXScript

589

You can use this value in more complex operations. For example, if you want to know the volume of a sphere with a 2.5-inch radius, multiply the cube of the radius by pi, then multiply by 4 and divide by 3. Enter 4/3 * pi * 2.5^3 .

Operations with Strings

You can also perform some simple mathematical operations with strings. For example, if you have defined a=MAXScript and b= is fun!, entering a+b returns MAXScript is fun!

For more string operations, see the String Values (p. 722) topic in the MAXScript reference.

Additional Mathematical Operations

MAXScript is able to perform many mathematical operations, including most trigonometric functions (sin, cosh, atan) and transcendental functions (exp, log, sqrt). This topic introduces two of the most useful operations: random numbers and incrementing. For a complete list of the operations supported by MAXScript, see the Number Values (p. 717) topic in the MAXScript reference.

590

Chapter 2

Learning MAXScript

Creating Random Numbers

One very useful mathematical operation in MAXScript is the random number function. It returns a pseudo-random number selected inclusively between two user-specified arguments. For example:
random 1 100

returns a random integer between 1 and 100. The return value type (Float or Integer) is the same as the type of the first argument in the function, therefore if you enter:
random 1.0 100

MAXScript returns a random float between 1 and 100.

Note: For reasons beyond the scope of this tutorial, the random command will generate the same random numbers each time a script is run. This happens if you restart the software and run the script, but not if you run the script over and over. If you want the values created by the random function to change each time you start the software, you can use the seed command:
seed <number>

where <number> is any float or integer. Each time you change the seed value, MAXScript generates new random numbers.

Drawing a Box with MAXScript

591

Incrementing
Another useful mathematical operation that MAXScript provides is incrementing. This is a shorthand form of assignment that can be used to modify a value in place, as shown in the following long form examples:
x = x + 1

There are assignment operators corresponding to the four math operations (+,-,*, and /) that apply the operation to the assignments destination with the result. Their syntax is:
<destination> <destination> <destination> <destination> += -= *= /= <expr> <expr> <expr> <expr> ----add <expr> to destination subtract <expr> from destination multiply destination by <expr> divide destination by <expr>

Using this shorthand form of assignment, the previous example can be written as:
x += 1

Drawing a Box with MAXScript

In the previous lessons you have seen some of MAXScripts useful capabilities; however, nothing that is visible in the interface. MAXScript is also useful for working with regular objects, such as boxes or cylinders. You can draw a box in MAXScript just by entering the box() command:
box()

This creates a box with the default parameters. It is generally better practice to assign an object to a variable, so you can later refer to it by name and manipulate it using that name:
mybox = box()

When you use MAXScript to create an object without specifying any parameters, it is important to use empty parentheses, (). This tells MAXScript to use the default parameters for the object. If you want to specify any of the parameters during creation, such as the size or location of the object, you do not need parentheses. For example:
mybox = box length:20 width:20 height:20

592

Chapter 2

Learning MAXScript

MAXScript returns the box object name and the position of the box:

This example creates a box, and supplies three parameters: the length, width, and height of the box. The parameter names are followed by a colon and then by the value for that parameter. You can enter all parameters, without any punctuation between them. MAXScript returns the following statement:
$Box:Box01 @ [0.000000, 0.000000, 0.000000].

The first part of the statement is called a pathname. A pathname in MAXScript is similar to a pathname in Windows, such as c:\3dsmax\examples\file.max, which represents a path through a hierarchy of directories pointing to a particular file. In MAXScript, a similar path concept is used. However paths in MAXScript end up pointing to objects, not files. Pathnames in MAXScript always begin with the $ character. For more information on Pathnames, see the Pathname Literals (p. 662) topic in the MAXScript reference. The second part of the statement is the object name: Box01, in this case. This name appears in the Select Object dialog when you use the Select by Name toolbar button in 3ds max. It is not the name of your box variable, which is mybox. This variable is merely a placeholder that points to the object, Box01. The values inside the brackets represent the x, y, and z coordinates of the center of the box.

Modifying the Box

593

MAXScript also draws the box in the viewports, as shown in this perspective viewport:

Notice that you can use Undo (as you can with most MAXScript creation and modification commands) to remove the box from the scene.

Modifying the Box

In the previous lesson, you created a box by assigning it to a named variable. Because you used a variable for the box, you can now access all of the boxs properties easily. The variable name mybox is the handle to your box. To access the properties of the handle, append a . (period), and then the property name. For example, mybox.height can be read as the height of mybox. All 3ds max objects have creation parameters such as width, length, and height for boxes, or radius for circles. These objects also have transformation properties, such as scale, rotation, or position, and general properties like name, wireColor, etc. To change any of these properties, you can set the property to a new value.

594

Chapter 2

Learning MAXScript

To change the object name of the box: If you dont like the default object name Box01, you can change the name property of the box: Enter mybox.name = BlueBox in the Listener window and the software renames the box. You can see the new name in the Name edit box when you go to the Modify panel:

To change the color of the box: The software assigns the color of objects randomly at creation time. Therefore, the color of your box is not necessarily blue. In this case, BlueBox wouldnt be an appropriate name for your box. However, you can change the color of your box to match the name: Enter mybox.wireColor = blue and watch the box in your viewports turn blue. You may have to select the box again to reflect the new color in the color swatch next to the object name in the Modify panel. The color blue is a predefined color constant in MAXScript and its RGB value is defined as (0,0,255). The other predefined color variables are red, green, white, black, orange, yellow, and brown. Instead of using a predefined color, you can assign a color with different RGB values, such as:
mybox.wireColor = (color 255 0 255)

Notice the special syntax for entering specific color values. The example shown would change the box to magenta. If you entered this command, click Undo to change the box back to blue.

For more information on colors, see the Color Values (p. 729) topic in the MAXScript reference. To change the position of the box: You can change the position of the box by changing the boxs position property. You refer to the position property for this example box with mybox.pos. The position is expressed as the X, Y, Z coordinate. For example [0,-75,0]. Bring the box forward by entering mybox.pos = [0,-75,0] and watch the box jump forward in the perspective view:

Modifying the Box

595

Click

Undo to move the box back to the origin.

To change the size of the box: To make the box bigger, you can use the scale property of the box: Enter mybox.scale = [1.5,1.5,1.5] to see the box resized to 1.5 times its original size. The scale property requires a scaling factor for each of the X, Y, and Z axes, or, in this case, the width, length and height of the box. You dont have to use the same value for each axis unless you want to resize the box uniformly.

596

Chapter 2

Learning MAXScript

If you want to change the scale to affect only the height and the width, but not the length, use the following example:
mybox.scale = [1,3,2]

When you scale your original [20,20,20] box by any factor, the boxs parameters are still 20 for width, 20 for length, and 20 for height. You can see this when you open the Modify panel. The box parameters are not changed by the scale transformation:

Modifying the Box

597

Although altering the height and width properties of the box achieves the same result, visually, the above scale modification is not equivalent to using the following two commands:
mybox.height = 40 mybox.width = 60 -- 2 times the original 20 units -- 3 times the original 20 units

The reason for this is that changing the height property of the box changes the creation parameter of the boxs height. Using the scale property to transform the height of the box does not. Again, the effect of using either method is visually the same, but when you want to maintain the original creation parameters of an object, so that you can alter them even after a number of different transformations, you must use the scale property to manipulate the size of the box, not the individual creation properties.

If you entered the last two commands, click height and width.

Undo twice to change the box back to its original

To find out which other box parameters you can change: The Parameters rollout shows all the creation parameters for a box. You can change them using the spinners in the rollout. If you want to change the value of the length, width, and height segments, or the setting of the mapping coordinates in MAXScript, you need to know the syntax for these parameters. In order to find the syntax for all of the parameter settings, there are two different inspector functions. The first of these is showclass(). Enter showclass box.* MAXScript shows all the box parameters that are equivalent to the ones you see in the Parameters rollout, including which object class the box object belongs to, and the data type that each parameter requires:

598

Chapter 2

Learning MAXScript

Notice that you can use the * character as a wildcard to see all box parameters. If you had entered showClass box*.*, MAXScript would have listed the Box and the BoxGizmo classes. The other inspector function is showProperties(). To learn more about these functions, search for the Class and Object Inspector Functions and Properties topic in the MAXScript Reference.

Applying Standard Transformations

Now that you know how to create and modify the basic properties of a box, you need to learn how to apply the standard transformations (move, scale, and rotate) to it. It is possible to designate position, size, and orientation when the box is created; however, you can also carry out these operations after you have created your object, just as you would in 3ds max . To move the box: Moving an object in MAXScript is very simple:
move name_obj [<x,y,z>]

where name_obj is the name of the object you want to move and <x,y,z> is the amount you want it to move. It is important to note that you are not moving the object to <x,y,z>, but by the amounts <x,y,z>. Therefore, if you apply the move function more than once, the object continues to move. This is also true for the scale and rotate transforms. This is in contrast to setting a property of an object. If you set the object position, scale, and rotation properties several times, the object wont change, assuming that you assign the same value each time.

Applying Standard Transformations

599

For example:
mybox.pos = [10,0,0] mybox.pos = [10,0,0] mybox.pos = [10,0,0]

will only change the position of your box after the first line is executed. The second and third lines do not affect the position of your box, as they do not change the position of the box.

If you entered the above commands, click original position. On the other hand, entering:
move mybox [10,0,0] move mybox [10,0,0] move mybox [10,0,0]

Undo three times to move the box back to its

will move your box 30 units along the X-axis.

600

Chapter 2

Learning MAXScript

If you entered the above commands, click original position.

Undo three times to move the box back to its

Applying Standard Transformations

601

To scale the box: Scaling is performed in a similar manner:

scale name_obj [<x,y,z]

where name_obj is the name of the object and <x,y,z> is a 3D coordinate that corresponds to the amount you would like to scale the object along the X, Y, and Z-axis, respectively. Again, the scale transformation is different from the scale object property. Setting the objects scale property (name_obj.scale = ) repeatedly with the same values will only scale the object the first time, but applying the scale transformation repeatedly will continue to scale the object. To rotate the box: The rotate transformation is not as simple as the move and rotate transforms. In fact, there are three ways to rotate an object in MAXScript: Euler Angles Quaternions Angleaxis

This introduction will only consider Euler Angles. If you would like further information on any of these transformations, see the MAXScript reference. To apply a rotation transform in MAXScript, you must first define the rotation as a sort of rotation object, and then apply the rotation object to the object you want to rotate. The rotation object is defined in the following way:
rot_obj = eulerangles x y z

where rot_obj can be any name and x, y, and z represent the amount you want to rotate your object (in degrees) around the X, Y, and Z-axes, respectively. For example:
rot_box = eulerangles 0 30 0

creates an object called rot_box, which will rotate an object around the Y-axis by 30 degrees. This rotation can be applied to your box in the following way:
rotate mybox rot_box

602

Chapter 2

Learning MAXScript

In fact, this rotation could be applied to any object by writing the same line as above and replacing mybox with the name of the object you want to rotate.

If you entered the above commands, click If you designate angles for more than one axis:
rot_box2 = eulerangles 30 45 60

Undo to move the box back to its original position.

The rotation is applied to an object, with the X-axis rotation occurring first, followed by the Y-axis rotation, and then the Z-axis rotation. Note: Moving, scaling, or rotating objects, or setting transform-related properties within a coordinate system, will operate in relation to the current reference coordinate system (i.e., Local, World, Screen), which is displayed in the main 3ds max toolbar. If you want to perform these transformations in another coordinate system, see the Coordsys (p. 685) topic in the MAXScript reference.

More Box Transformations

603

More Box Transformations

Additional property transformations
The following lines prepare our box for more complex transformations. They change the number of box segments on all sides, and put a check mark into the Generate Mapping Coords. box in the Parameters rollout: Enter the following four lines of code:
mybox.lengthsegs = 10 mybox.widthsegs = 10 mybox.heightsegs = 10 mybox.mapCoords = true

MAXScript has changed the appropriate settings in the Parameters rollout:

Any time you change a property of a 3ds max object, MAXScript immediately reflects the change in the scene and in the user interface. You can also create modifiers and add them to an object. To create a modifier: Creating a modifier is pretty simple. You use the addModifier command and specify the name of the modifier you want to use and its appropriate parameters. For example, to create a Twist modifier set at 30 degrees and apply it to your box, you would enter
addModifier mybox (twist angle:30)

604

Chapter 2

Learning MAXScript

The box in your Perspective viewport is now twisted and the interface shows the new Twist modifier in the modifier stack display, together with its parameters:

More Box Transformations

605

To change a modifier: Changing a modifier is similar to changing a creation parameter. Again, because you used a variable name for your object, and you added a modifier to that object variable, you now have easy access to the new modifier properties of your object. To change the angle of the twist modifier to 60 degrees, enter
mybox.twist.angle = 60

606

Chapter 2

Learning MAXScript

The twist of your box is now more pronounced and the Angle parameter of the Twist modifier displays the new value:

From here on, you can add and change other modifiers as you like. The syntax is the same for all modifiers. To find out the names of other modifiers, search for the Modifier : MAXWrapper topic in the MAXScript Reference.

If you entered the above commands, click original state.

Undo twice to bring the box back to its

Controlling Program Flow in Scripts

607

To animate your box: MAXScript has several syntax forms that mirror the main UI tools, such as the Animate button, the time slider, and the active coordinate system. In the following example, you turn on the Animate button, set the slider to several different values, and adjust the properties of your box, just as you would do using the softwares UI:
animate on ( at time 0 (mybox.pos = [-100, 0, 0]; mybox.scale = [1, 1, 0.25]) at time 100 (mybox.pos = [100, 0, 0]; mybox.scale = [1, 1, 3]) )

Drag the slider around, and you will see that MAXScript has animated the box, and placed keyframes at 0 and 100. When you use MAXScript to animate objects, the actual Animate button in the UI does not come on, nor does the time slider move; these things happen within MAXScript. In this example, the time was given as a simple number. If no unit is specified, MAXScript interprets this as a frame number. You can also use one of the various time literals in the following manner:
2.5s 20f 4800t 1m3s5f 1:15.5 -----2.5 seconds 20 frames 4800 ticks = 1 sec 1 min, 3 seconds, 5 frames SMPTE: 1 min, 15 seconds, 5 frames

Note: All times are automatically converted to frames.

Controlling Program Flow in Scripts

Now that you have explored the beginnings of object creation and manipulation, the next step is programming. MAXScript is a programming language at heart, and two of the most important concepts necessary for mastering MAXScript are conditional statements and loops. At this point, real script writing comes into play. From the Utilities command panel, click on the New Script button. This opens a new MAXScript editor window where you can create, save, and open scripts. In the MAXScript editor window, commands are not automatically executed. In order to execute the entire script, use Evaluate All from the File Menu, or press CTRL+E. You can also execute scripts several lines at a time by highlighting the lines you want to execute and pressing SHIFT+ENTER, or ENTER on the numeric keypad.

608

Chapter 2

Learning MAXScript

Conditional Statements
Conditional statements simply tell MAXScript to perform a specified command if a certain condition is met. For example:
if mybox.height == 10 then mybox.width = 20

This changes the width of your box to 20 if its height is equal to 10. You may have taken note of the double equal sign used in the statement above. This is discussed at the end of this topic. This if...then... statement can be expanded to include an else statement. For example:
if mybox.height == 10 then mybox.width = 20 else mybox.width = 10

This statement tells MAXScript to change the width of your box to 20 if its height is 10, otherwise change the width to 10. The if, then, and else portions of the statement can all be on separate lines:
if b.height == 10 then b.width = 20 else b.width = 10

If you are entering these commands into the Listener window, you may notice that the commands are not executed line by line, as is typical of the Listener. This is because the Listener recognizes that the if statement requires a then statement to be complete. In fact, the Listener does not execute the statement after the then statement, because it does not know if you intend to include an else statement. For this reason, the Listener does not execute an if...then... statement until you have either entered a then statement or after the next line you type, following the if...then... statement. The double equal sign in the last statement, ==, tells MAXScript to compare two values. The single = sign always signifies assignment. This is common in many standard programming languages, such as C++. There are several different conditional parameters used in MAXScript. They are listed here: == equal to != not equal to > greater than >= greater than or equal to < less than <= less than or equal to Note: Any time MAXScript evaluates a conditional expression, the result is either true or false. MAXScript temporarily stores the value of this result. In an if...then statement, MAXScript uses this result to determine the path to follow in the statement. If the result of the if statement is true, MAXScript will evaluate the then expression. If the result is false, MAXScript will evaluate the else expression, assuming one is specified; otherwise, it will cease evaluating the conditional statement. In some scripts, you might see the words on and off used in place of true and false, respectively. These words are interchangeable and they mean the same thing to MAXScript.

Controlling Program Flow in Scripts

609

Loops
Loops are repetitive operations that tell MAXScript to repeat the execution of a collection of commands. Loops are useful for working with large groups of objects, as you can make changes to many objects with one set of commands. For example, if you wanted to make 50 boxes, you could use a loop to execute the create command 50 times, rather than creating the boxes with 50 separate commands. Loops are also useful for changing the properties of multiple objects. There are several different types of loop. The first to be considered are for and while loops.

For Loops
The for loop iterates through a range of numbers, time values, or a sequenced collection of values, such as an array or object set. Use a for loop to copy the box:
for i = 1 to 5 do ( box_copy = copy mybox box_copy.pos = [i * 50, 0, 0] )

610

Chapter 2

Learning MAXScript

Everything inside of the parentheses makes up a block. All loop statements must be created as a block. This statement executes five times. Each time, a new box is created. A for statement starts with the word for. Next, you must define how many times the statement will repeat. In this case, you have used the variable i to control the loop. The line, for i = 1 to 5 tells MAXScript to set the variable i to the value 1, execute the contents of the loop statement, then set the variable i to 2, execute the loop contents, and so on. The variable i is called the index for the loop. Each time the loop executes, the index is incremented by 1 automatically, without requiring any user input. Each repetition of the loop is called an iteration. To make MAXScript increment the index by a value other than 1, insert by x after the index statement, where x is the amount to increment the index. For example, the following statement will set the index to 1, then 3, then 5:
for i = 1 to 5 by 2 do ( box_copy = copy mybox box_copy.pos = [i * 50, 0, 0] )

Controlling Program Flow in Scripts

611

The do keyword tells MAXScript to execute the following block or statement each time the loop repeats. Note that in some loops you might see the word in in place of the equal sign, =. These both mean the same thing in for loops, and can be used interchangeably. Note how the index was used within the loop statement to set the position of each new box. This is a useful way to work with multiple object creation. For loops can also be used to build arrays and/or access values within an array. In the following example, you use a for loop to build an array called arr:

Remember that because MAXScript is an expression-based language, you are able to use expressions in variable assignment, as seen above in the assignment of the for loop expression to the variable, arr. Note the collect statement in the for loop above. This tells MAXScript to collect the results of each iteration in an array, rather than just calculate them. In this case, you only asked MAXScript to collect the value of the index; however, you can collect iterations of any expression.

612

Chapter 2

Learning MAXScript

Finally, for loops can also perform iterations with the contents of an array. In the following example, you use a for loop to access the values of the array you created in the previous example:

The print command is a MAXScript function that displays the specified variable in the Listener window. In this example you used in instead of an equal sign; however, they are still both acceptable, even when accessing values within an array. Note: You can also access the number of elements in an array with the .count property. For example, the previous example could have been written:
for i = 1 to arr.count do print i

This will return the same result.

While and Do Loops

While and Do loops are used to repeatedly execute an expression until a test expression evaluates as false. The while and do loop are simple variants of one another. The syntax is:
do <expr> while <expr> -- do loop while <expr> do <expr> -- while loop

The following example will return the value of a variable, incrementing the variable by 1 with each iteration.
x=10 while x>0 do print (x-=1)

Controlling Program Flow in Scripts

613

Returns:
9 8 7 6 5 4 3 2 1 0 0

MAXScript automatically returns the final value of the loop to the Listener. In this example, MAXScript is also instructed to return the value at each iteration of the loop; therefore, the final value is returned twice. Both loops repeat the do<expr> as long as the while<expr> evaluates to the value true. The do form evaluates the do<expr> at least at least once, before evaluating the text expression at the end of the loop. The while form evaluates the test expression at the start of the loop, and might not loop at all. Both forms return, as their value, the result of the do<expr> from the last successful loop iteration. The while form returns the value undefined if the test expression immediately returns false. For example:
x=10 do print (x-=1) while x>10 Returns: 9 undefined

However,
x=10 while x>10 do print (x-=1) Returns: Undefined

614

Chapter 2

Learning MAXScript

Defining Custom Functions

MAXScripts built-in functions are very powerful. They provide access to objects, allowing you to read and set their properties. However, scripting in 3ds max normally entails going beyond simple object creation. Fortunately, MAXScript allows you to make your own functions, giving you the ability to streamline and customize your work.

Local and Global Variables

In MAXScript, there are two classes of variables that you can create: local and global variables. When a variable is global, it means that the variable can be used anywhere in the program. The only place you cannot use a global variable is before you have defined it. For example, the following lines will produce an error:
sphere radius:rad global rad = 10

The variable rad does not exist until it has been defined. The following is an acceptable form of the previous lines:
global rad = 10 sphere radius:rad

Now that rad has been defined, MAXScript was able to use it in the definition of a sphere. In fact, since rad is a global variable, it can be used throughout the rest of the script. There are several global variables that can be used without defining them first. They are the system global variables, which have already been created and assigned to a default value. Most of these variables can be reassigned to different values. For more information on the system global variables, see the 3ds max System Globals (p. 630) topic in the MAXScript reference. Unlike global variables, local variables can be used only within the block in which they are defined. A block is a grouping of MAXScript code, such as the statements within loops and conditional statements. Here is an example of a for loop:
for i = 1 to 3 do ( local rad = 10 s = sphere() s.pos.x = i * 10 s.radius = rad )

Local variables can only exist within a block. For this reason, they must be created in a block. If you try to define a local variable from the top level of MAXScript, you will receive an error message. In the previous example, you defined a local variable named rad. This variable is active only within the parentheses inside the for loop; if you attempt to use the variable rad elsewhere, you will get an error. Although rad is initialized to a specific value, this is not necessary. When you define variables using a local or global identifier, you can do so without assigning an initial value. The name of the variable will be recognized. However, the software will not know the type of the variable (name,

Defining Custom Functions

615

number, color, etc.). MAXScript automatically assigns the variable a special value of undefined. The first time you assign something to the variable, it will become defined by the data type that you have assigned it to. In practice, it is always best to define variables with an initial value. It is important to note that rad is not the only local variable in the previous example. The variable s is also a local variable, and cannot be accessed outside of the parentheses. It is not necessary to declare every variable with a global or local statement. You learned previously that you can implicitly create a variable by simply assigning a value to it. If you do not make the global or local distinction upon your variable, MAXScript will create the appropriate association, depending on where the variable is defined in the script. For example if you create a variable inside a block, MAXScript automatically treats it as a local variable. On the other hand, any variable created at the top level of MAXScript (outside of all blocks) is always a global variable. As mentioned previously, MAXScript does not allow for the creation of local variables outside of a block. These concepts are presented in the following example:
for i = 1 to 5 ( global rad = 10 cyl_height = 25 c = cylinder() c.radius = rad c.height = cyl_height c.pos.x = i * 25 ) s = sphere radius:rad

In this example, four variables are created: rad, cyl_height, c, and s. Because they were implicitly created within a block, c and cyl_height are both local variables. The other two variables are both global; s, because it was created outside of a block, and rad, because it was declared as a global variable. For this reason, you can use rad again to define the sphere, s.

616

Chapter 2

Learning MAXScript

Defining Custom Functions

In MAXScript, you can use functions to perform almost any of the softwares operations. Start with a simple function definition that subtracts two variables:

MAXScript returns subtract() to let you know that it has defined the function, subtract. The definition contains the keyword function (you can also use the word fn in place of function), followed by the name of the function (subtract), followed by the list of variables (x and y). The equal sign signifies the start of the body of the function. The body is the series of statements that the function executes. Even if there is only one statement, the body of the function must be in parentheses. Note: Any variables created in the body of a function are local variables unless otherwise specified. Once a function has been defined, it can be used anywhere throughout the script. Therefore, it is useful to place function definitions at the beginning of your scripts. In order to use a function, you simply enter the function name and the values for its variables:

Defining Custom Functions

617

This example uses what are known as positional arguments. When you call the function, you must supply both arguments, and you must supply them in the proper order for the function to execute properly. The second type of arguments you can use are keyword arguments. This is what is used for all of the object constructors in MAXScript. The function definition is the same, with the exception of declaring the keyword arguments, or default values for the variables in a function. The following example determines whether a number is positive, negative, or equal to zero:
function sign val:0 = ( if val == 0 then messagebox (Equal to 0) else if val > 0 then messagebox (Greater than 0) else messagebox (Less than 0) )

The messagebox command causes a message box to pop up on the screen, displaying the argument in the parentheses that follow the command. In this example, a parameter called val has been declared in the function definition. The value after the colon is the parameters default value. When the function definition contains parameters like this, they are optional in the function call. If you enter sign(), without specifying any parameters in the function call, MAXScript uses the default value:

The Equal to 0 message box appears, since the default value for val (0) will be used. However, if you do define val:
sign val:-5

the Less than 0 message appears. You can include as many keyword arguments in a function as you need, and they can be entered in any order when calling the function. This is useful when you consider functions such as object-creation functions, where the new object might have 20 or 30

618

Chapter 2

Learning MAXScript

parameters associated with it. If you wanted to use positional argument functions to create the same objects, you would have to provide all of these parameters, in the right order, each time you wanted to call the function. It is also possible to use both positional and keyword arguments in the same function call. In this case, you must use positional arguments first, followed by the keyword arguments:
function mycube side position:[0, 0, 0] = ( box length:side width:side height:side pos:position )

This function requires you to enter the size of the cube, but the position is optional.

Structure Definitions
In addition to custom functions, you can also create custom compound values in MAXScript using structure definitions. Structure definitions are a flexible data type, built of simpler data types. They let you define the layout of a new structured type of value that you can then create and work with in your code. The syntax for a structure definition is:
Struct <struct_name> ( <member> , <member> )

where each <member> can be one of:

<name> [ = <expr> ] name and optional initial value <function_definition>

Create a new structure, called person:

Struct person (name, height, age, sex)

Structure Definitions

619

Now create an instance of this structure using the person constructor:

Bill = person name:Bill height:72 age:34 sex:#male

This stores an instance of the person structure in the variable Bill. Member name is initialized to the string value Bill, height to the integer value 72, age to the integer value 34, and sex to the name value #male. Create another instance:
Joe = person name:Joseph sex:#male

In this example, another person is created. However, this person does not have initialized values for the height and age members. Since you did not provide these members with an optional default value in our structure definition, they will default to a value of undefined.

Structure definitions are a good alternative to arrays when you have a fixed, small number of components. The code for these types of values is easier to work with since you can reference property names rather than index numbers in arrays.

620

Chapter 2

Learning MAXScript

3ds max Commands in MAXScript

In addition to controlling modeling and animation, MAXScript scripts can invoke 3ds max menu and toolbar commands. You do this using the max keyword. For example:
max file open max unhide all max quick render

The keyword max is followed by one or more words that describe the command. The available commands can be displayed by using the ? character in a partial max command. For example:
max time ? -- shows all the time-related commands max sel ? -- shows all the commands with sel in them as a substring max ? -- shows all the commands (there are a lot)

Below is a partial list of the available commands to give you an idea of the type of 3ds max commands you can perform with MAXScript. For a complete list, see the 3ds max Commands (p. 1630) topic in the MAXScript reference.
3ds max Command Name max ? max delete max file new max file open max file save max move max properties max quick render max redo max reset file max rotate max select max select all max time end max time start max undo max unfreeze all max unhide all max vpt front max zoomext sel Command Description Displays all max commands in the Listener Deletes selected objects or sub-objects Displays the new file dialog Displays the open file dialog Activates File/Save Activates Select and Move mode Displays the Object Properties Dialog Performs a quick render Performs a redo operation Activates File/Reset Activates Select And Rotate mode Activates select mode Selects all objects Sets the time slider to the end frame (Go to End) Sets the time slider to the start frame (Go to Start) Performs an undo operation Unfreezes all objects Unhides all objects Sets the active viewport to Front Activates Zoom Extents Selected

Saving your Commands in a Script File

621

Saving your Commands in a Script File

So far, you have entered your commands into the Listener window. If you had to stop at some point, and couldnt finish some code in one session, you would have to start all over, entering the commands you already used in the previous session. MAXScript allows you to store your commands in an external file that you can load and run. The general procedure for storing commands in a script file is to click the New Script button in the MAXScript rollout, and type commands in the Script Editor window that opens. Because you have already entered a lot of commands in the Listener window, you can copy them from that window into the Script Editor window. To copy tutorial commands from the Listener into the script editor window: 1. 2. 3. 4. 5. Click the New Script button in the MAXScript rollout on the Display panel. The Script Editor window appears with the title Untitled - MAXScript. Position the Script Editor window side-by-side or below the Listener window so that you can copy and paste text between the two windows. In the Listener window, select the black command line from the Drawing a Box with MAXScript (p. 591) topic (mybox = box length:20 width:20 height:20) Press CTRL+C on your keyboard to copy the text to the Clipboard. Click the Script Editor window to place the cursor in it, and press CTRL+V on your keyboard to paste the command into the Script Editor window. Tip: You can also drag selected text from the Listener and drop it in the Script Editor, or vice versa. Choose File > Save in the Choose File Name for Save dialog, navigate to your \Scripts directory. Name your script file box_draw.ms and click Save. Your script file is saved and the script editor window title changes to box_draw.ms MAXScript. You have now saved your first script file. MAXScript uses the .ms extension for script files. It is good general practice to save all of your script files into the scripts directory.

6.

Loading and Running your Script File

You can open a script file for editing, or you can include it in another script to run automatically when that script runs. To run the script you just saved: 1. 2. Reset 3ds max. Go to the Utilities panel, turn on MAXScript, and in the MAXScript rollout, click the Run Script button. The Choose Editor File dialog appears.

622

Chapter 2

Learning MAXScript

3.

Select the box_draw.ms file, and click Open. MAXScript immediately carries out the command that is contained in the script file and places a box in the scene.

To open a script file for editing: If you want to edit your script later to add more commands to it, you need to open it: 1. 2. In the MAXScript rollout, click the Open Script button Select the script you want to edit and click Open. The Script Editor window opens, showing the text of your script. You can now edit your commands or add new ones, as you would edit any other text file. Save the script file to keep your changes. To evaluate the commands in your script: If you enter any commands in the Script Editor window manually (not by copying and pasting from the Listener window), you can test the validity of all commands: 1. 2. If your Listener window isnt open, click the Open Listener button in the MAXScript rollout. In the Script Editor window, choose File > Evaluate All. MAXScript evaluates the commands in your script file. It sends any feedback to the Listener window. It also sends each valid command to the user interface as if you had run the script. If your script contains any syntax errors, MAXScript reports those in the Listener window in red. To include your script in another script: If you want to write a script for each tutorial (for example one for drawing a box, one for modifying the box, and another one for transforming it), you could then use those three scripts in another one that contains all the box operations. Assuming you had created the scripts box_draw.ms, box_mod.ms, and box_trans.ms, you could then include them in a new script, box_all.ms. The text for box_all.ms would be as follows:
include box_draw.ms include box_mod.ms include box_trans.ms

To reset 3ds max before running scripts: If you want to start with a new scene before running any scripts, you need to reset the software: 1. 2. 3. Choose File > Reset. Answer the Yes-No prompt to either save or discard the changes to your scene. Open and run the script you want. Note that resetting the software closes all MAXScript windows so that you cant copy any more commands from the Listener window. You can always copy commands from the help file, as described below.

Loading Other Scripts

623

To copy commands from the help file: You can copy commands from the tutorial help file: 1. 2. 3. In the Help window, highlight the command you want to copy. Right-click the highlighted text and select Copy from the pop-up menu. In the Script Editor window, choose the Edit > Paste menu to paste the command into the current script file, or press CTRL+V on your keyboard.

Loading Other Scripts

The software comes with many scripts pre-installed in the scripts directory. Or, you might find MAXScript files on the World Wide Web that other MAXScript users have posted. To load any of those script files isnt different from loading your own scripts: To load a script: If you want to study a script before running it, open it first: 1. 2. In the MAXScript rollout, click the Open Script button. Select the script you want to study and click Open. The Script Editor window opens. It shows the text of the script you selected. You can now read the commands and see if you get an understanding of what the script might do when you run it. To run a script: 1. 2. In the MAXScript rollout, click the Run Script button. The Choose Editor File dialog appears. Select the script file you want to run, and click Open. MAXScript immediately carries out the commands that are contained in the script file.

Learning MAXScript by Walking Through a Script

You can learn a lot about MAXScript by just using several different script files. The best method to learn MAXScript commands and command syntax is to step through a script and watch the responses in the Listener window and in the user interface. You can walk through a script by loading a script into the Script Editor window and executing one command line or a command block at a time: To step through a script: 1. 2. Open a script into the Script Editor window. Place the cursor into the first command line and press ENTER on the number pad of your keyboard. The Number Pad <ENTER> key is a shortcut for executing the current command line or the selected block of code.

624

Chapter 2

Learning MAXScript

MAXScript executes the current command line and reflects the outcome in the Listener window and, if appropriate, in the user interface. 3. Move the cursor to the next command line or select the next block of code from the script. Press the number pad ENTER key again, and so on.

From here on, step through other scripts and take note of the effects. Most of the script files included with 3ds max are very well commented and include a description about the scripts purpose. For more information about using script files, see the Running Scripts (p. xlix) topic in the MAXScript Reference.

Learning MAXScript with the Macro Recorder

Another useful tool for learning MAXScript is the Macro Recorder. If you want to learn how to perform a task in MAXScript, you can use the Macro Recorder to get started. The Macro Recorder captures many of the actions performed by the user, and generates the MAXScript commands that correspond to those actions. The Macro Recorder output is displayed in the top pane of the MAXScript Listener window. This pane has a pink background. The Macro Recorder has several filtering options that control what types of user actions are recorded, whether the generated script commands contain explicit object references or are selection-relative, and whether the generated MAXScript commands contain explicit or relative transforms and coordinates. These options can be set using the Macro Recorder menu in the Listener window. Many user actions generate Macro Recorder output, but not all of them. In general, most of the buttons on the Menu Bar, toolbars, Status Bar, Create panel, and Modify panel generate Macro Recorder output. If the button invokes a secondary dialog, changing setting or performing actions in the secondary dialog typically will not generate Macro Recorder output. In the Create and Modify panels, Macro Recorder output is generated if MAXScript can create the object or modifier. This makes the Macro Recorder a useful too for learning MAXScript, as you can perform tasks in the UI and simultaneously see how to perform these same tasks with MAXScript. For further documentation on the Macro Recorder, see the Macro Recorder (p. l) topic in the MAXScript reference.

The Scripts Included with 3ds max

You can open each script in the scripts directory and study what each script does by stepping through them. The script files are ASCII files that you can open with any ASCII editor for viewing or printing. Most script files are very well commented and include a description of the scripts purpose. Of particular interest is demo.ms, which you can step through to explore various aspects of MAXScripts capabilities.

Chapter 3:

Reserved Keywords, Symbols, Punctuation and Variables

As with any computer language, MAXScript features a number of lexical tokens, corresponding to the words and numbers and punctuation that are the building blocks of English. Tokens fall into several categories: Reserved keywords that typically introduce clauses in the language, such as if, for, and function. Punctuation marks and symbols that separate or group clauses or specify math operators, etc. Reserved global variables containing 3ds max system global variables and MAXScript predefined global variables.

The following list of topics contains information about the above types of tokens and their syntax: Language Reserved Keywords (p. 625) Punctuation and Symbols (p. 627) Reserved Global Variables (p. 628)

Language Reserved Keywords

Keywords begin or separate portions of MAXScript commands. For example, one form of the if expression is:
if <expr> then <expr> [ else <expr> ]

In order for MAXScript to easily identify the various portions of the if expression, the words if, then and else are reserved keywords and can not be used as variable names or identifiers. So, for example, you cannot declare a variable or function called if. The following table lists all MAXScript reserved keywords. Click a reserved keyword to go to a description of its usage. In some cases, a keyword may have more additional meanings, depending on its context. This information is also summarized in the MAXScript Grammar (p. 1681) topic.

626

Chapter 3

Reserved Keywords, Symbols, Punctuation and Variables

Reserved Keywords
about and animate as at by case catch collect continue coordsys do else exitv fn for from function global if in local macroscript mapped max not of off on or parameters persistent plugin rcmenu return rollout Creating_Functions Scope_of_Variables If_Expression For_Loop Scope_of_Variables Defining_Macro_Scripts Creating_Functions MAX_Commands Logical_Expressions Case_Expression Predefined_Globals Rollout_Clauses Logical_Expressions Scripted_Plugin_Clauses Persistent_Global_Variables Scripted_Plugins Scripted_Right_Click_Menus The_Return_Expression Utility_Clauses about Logical_Expressions animate value_common_properties_operators_and_methods at_time For_Loop Case_Expression Try_Expression For_Loop Skipping_Loop_Iterations coordsys While_and_Do_Loops If_Expression Loop_Exit Creating_Functions For_Loop

Punctuation and Symbols

627

set struct then throw to tool try undo utility when where while with

Sticky_Contexts Structure_Definition If_Expression Try_Expression For_Loop Scripted_Mouse_Tools Try_Expression undo Scripted_Utilities Change_Handlers_and_When_Constructs For_Loop While_and_Do_Loops Loop_Exit

The from keyword is reserved, but not currently used.

Punctuation and Symbols

The following table shows all MAXScript punctuation marks and symbols. Their meanings are described in the definitions of the various language constructs that use them and also in the MAXScript Grammar (p. 1681) topic. Some of these punctuation marks and symbols offer more information. Click a linked punctuation mark or symbol to go to a description of its usage. In some cases, a keyword may have more additional meanings, depending on its context.
( ) + * / ^ += -= *= /= -= ; <eol> Block_Expressions Block_Expressions Math_Expressions Math_Expressions Math_Expressions Math_Expressions Math_Expressions Math_Assignment Math_Assignment Math_Assignment Math_Assignment Source_Code_Layout_and_Continuation_Lines Math_Assignment Source_Code_Layout_and_Continuation_Lines

628

Chapter 3

Reserved Keywords, Symbols, Punctuation and Variables

, [ ] : & . { } # == != < > >= <= ? $ ... .. \ BitArray_Values BitArray_Values Array_Values Logical_Expressions Logical_Expressions Logical_Expressions Logical_Expressions Logical_Expressions Logical_Expressions Using_the_?_Symbol Pathname_Literals Pathname_Literals BitArray_Values Source_Code_Layout_and_Continuation_Lines 2D_and_3D_Point_Literals 2D_and_3D_Point_Literals Function_Calls Names

Reserved Global Variables

Reserved global variables are variables to which MAXScript automatically assigns values. The MAXScript reserved global variables fall in 3 categories: predefined globals (such as red and pi); 3ds max system globals which give you access to state information in the 3ds max system (such as currentFrame); and MAXScript system globals which give you access to the MAXScript system state. Unlike language reserved keywords, you can re-use these variable names as local variables, with values that you specify. However, it is highly recommended that you do not re-use reserved global variable names as such usage can be highly confusing.

See Also
Predefined Globals (p. 629) 3ds max System Globals (p. 630) MAXScript System Globals (p. 640) Variables Assignment and Scope (p. 643)

Predefined Globals

629

Predefined Globals
The predefined global variables contain special values that are frequently used in scripts. These variables are read-only.
true, false

Boolean values. Can be used for testing the results of comparisons and for state tests.
on, off

Synonyms for true and false, sometimes easier to read in state accesses.
pi, e

Float values that contain the standard mathematical constants values. They are equivalent to 3.1415926535 and 2.718281828, respectively.
red, green, blue, white, black, orange, yellow, brown, gray

A predefined set of useful Color values.

x_axis, y_axis, z_axis

Point3 values that define normal vectors for the 3 major axes. They are equivalent to [1, 0, 0], [0, 1, 0], and [0, 0, 1], respectively.
ok

A void value returned by some functions or expressions that dont have a meaningful value to return.
undefined

The initial value of all variables and array elements. MAXScript generates an error if you try to perform any operation on the undefined value, except for checking to see if some value is equal to it or not:
if a == undefined then print oh, oh if b != undefined then print whew! unsupplied

The initial value of all function keyword arguments. Keyword arguments are optional arguments to functions. If a keyword argument is not supplied by the function caller and the function definition does not specify a default value, MAXScript initializes the keyword argument to unsupplied. You can test for this value to see whether a caller has supplied a particular keyword. For more details, see the Function Calls (p. 675) topic.
dontcollect

This value is used in for loops to signal that the value is not to be collected. See the For Loop (p. 694) topic for details.

630

Chapter 3

Reserved Keywords, Symbols, Punctuation and Variables

3ds max System Globals

The 3ds max system global variables give you access to state information in the 3ds max system. Except where noted as read-only, you can both access and assign to the global variables.
activeGrid

Contains the currently active grid. If the home grid is active, returns the value undefined. You can assign a grid node object to this variable to make it the currently active grid. See Viewport Grids (p. 1587).
ambientColor

Lets you get and set a Color value that defines the global rendering environment (Rendering > Environment) ambient lighting color. See Working with 3ds max Atmospherics (p. 1345).
ambientColorController

Lets you get and set a Controller value that defines the global rendering environment (Rendering > Environment) ambient lighting color controller. See Working with 3ds max Atmospherics (p. 1345).
animationRange

Lets you get and set an Interval value that defines the start and end of the current active animation range. This variable contains the corresponding values set in the Time Configuration dialog. See Time Configuration Dialog (p. 1616).
animButtonEnabled

A Boolean value that specifies whether the user can change the state of the Animate button. If set to false, the user can not change the Animate button state. If set to true, the user can change the Animate button state. A script can change the state of the Animate button using animButtonState regardless of the animButtonEnabled value. See Time Control (p. 1580).
animButtonState

Lets you to get and set the state of the Animate button. A Boolean value - true if Animate is on, false if Animate is off. See Time Control (p. 1580).
autoBackup.enabled

Get/set whether auto backup is enabled as a <boolean>.

autoBackup.time

Get/set the time in minutes between auto backup as a <float>. If the specified value is < 0.01 (the UI limit), the time is set to 0.01.
backgroundColor

Lets you get and set a Color value that defines the global rendering environment (Rendering > Environment) background color. See Working with 3ds max Atmospherics (p. 1345).
backgroundColorController

Lets you get and set a Controller value that defines the global rendering environment (Rendering > Environment) background color controller. See Working with 3ds max Atmospherics (p. 1345).

3ds max System Globals

631

backgroundImageFileName

Lets you get and set a String value that defines the viewport background image bitmap file name. This variable contains the corresponding bitmap file name set in the Viewport Background dialog. See Viewport Background Images (p. 1586).
cui.commandPanelOpen

Lets you get and set whether the command panel is displayed. A Boolean value - true if the command panel is displayed, false if not displayed. See Command Panels (p. 1571).
currentMaterialLibrary

Contains a virtual array of materials and root level maps corresponding to the currently opened material library. You can get library materials via array indexing and iterate over them in a for loop. The array can be indexed by number, or by name or string to select by material name. This variable is read-only. See MaterialLibrary Values (p. 795).
displayGamma fileInGamma fileOutGamma

Lets you get and set Float values that define the gamma preference settings. They contain the corresponding values set in the Gamma tab of the Preferences dialog. You could use these global variables to establish gamma for a MAXScript-created bitmap, for example:
b = bitmap 320 240 gamma:displayGamma render camera:c to:b

This would cause the rendered bitmap to display using the current displays gamma setting if used as a rollout bitmap or button image.
displaySafeFrames

Lets you get and set whether Show Safe Frames is on for the active viewport. A Boolean value - true if Show Safe Frames is on, false if off.
environmentMap

Lets you get and set a TextureMap value that defines the global rendering environment (Rendering > Environment) environment map. See Working with 3ds max Atmospherics (p. 1345).
flyOffTime

Lets you get and set an Integer value that defines the time in milliseconds the user must hold down on a flyout before the flyout is activated. This variable contains the corresponding value set in the General tab of the Preferences dialog.
frameRate

Lets you get and set an Integer value that defines the current scene frame rate in framesper-second. This variable contains the corresponding value set in the Time Configuration dialog. See Time Configuration Dialog (p. 1616).
globalTracks

Contains a MAXTVNode value that defines the top-level Global Tracks node in Track View. This variable is read-only. See Track View Nodes (p. 1382).

632

Chapter 3

Reserved Keywords, Symbols, Punctuation and Variables

hardwareLockID

Contains an Integer value that defines the 3ds max hardware lock ID. This variable is read-only.
hotspotAngleSeparation

Contains a Float value that defines the Hot Spot/FallOff Angle Separation value. This variable contains the corresponding value set in the Rendering tab of the Preferences dialog. This variable is read-only.
keyboard.shiftPressed keyboard.controlPressed keyboard.altPressed

These variables access the current state of the keyboard shift keys and return true or false depending on the pressed state of the key at the time the variable is read and are read-only variables.
lightTintColor

Lets you get and set a Color value that defines the global rendering environment (Rendering > Environment) Global Lighting Tint color. See Working with 3ds max Atmospherics (p. 1345).
lightTintColorController

Lets you get and set a Controller value that defines the global rendering environment (Rendering > Environment) Global Lighting Tint color controller. See Working with 3ds max Atmospherics (p. 1345).
lightLevel

Lets you get and set a Float value that defines the global rendering environment (Rendering > Environment) Global Lighting Tint Level. See Working with 3ds max Atmospherics (p. 1345).
lightLevelController

Lets you get and set a Controller value that defines the global rendering environment (Rendering > Environment) Global Lighting Tint Level controller. See Working with 3ds max Atmospherics (p. 1345).
listener

Read only system global - listener edit window <WindowStream> value

localTime

Contains a String value that defines the current local date and time. This variable is readonly. An example of the value stored in localtime is:
s = localTime 4/14/97 10:24:57 AM

The format of this string is controlled by the date format selected in the main Windows Regional Settings control panel.
logsystem.quietmode

Lets you get and set whether error logging quiet mode is enabled. A Boolean value set to true when you do not want error messages from the renderer to bring up dialog boxes. If set to false, error messages from the renderer will bring up dialog boxes. 3ds max sets the

3ds max System Globals

633

corresponding internal variable to true during network rendering to suppress error messages such as the Missing Maps and Missing Map Coordinates dialogs. If this variable is set to true and the renderer generates an error message, the renderer will exit. After setting quiet mode, do not forget to clear it when you are done, since the user will not see any error messages from the renderer while quiet mode is enabled.
macroRecorder

Read only system global - macro recorder edit window <WindowStream> value
maxFileName

Contains a String value that defines the file name for the currently open scene. This variable is read-only.
maxFilePath

Contains a String value that defines the directory path for the currently open scene. This variable is read-only.
meditMaterials

Contains a virtual array of materials and root level maps corresponding to the slots in the material editor. You can access material editor materials and root level maps via array indexing and iterate over them in a for loop. The array can be indexed by number to specify slot number or name or string to select by material and root level map name. For example:
$foo.material = meditMaterials[1] meditMaterials[foo mat].diffuse = red for m in meditMaterials do print m.diffuseMap meditMaterials[1]=standard() print meditMaterials.count -- number of slots

This variable is read-only, but the elements (the materials in the slots) are assignable. See MaterialLibrary Values (p. 795). See the Material Editor (p. 1606) topic for methods for assigning materials and maps to the material editor slots.
numEffects

Contains an Integer value that defines the number of current render effects defined in the Rendering > Effects dialog list. This variable is read-only. See RenderEffect (p. 1347).
numAtmospherics

Contains an Integer value that defines the number of atmospheric events, as shown in Rendering > Environment. This variable is read-only. See Working with 3ds max Atmospherics (p. 1345).
numSubObjectLevels

Lets you get the number of sub-object levels supported by the object or modifier currently selected in the modifier stack. If the Modify panel is not open or no objects are selected, the global contains the value undefined. See the Modify Panel (p. 1572) topic.
playActiveOnly

Lets you get and set whether to playback the active viewport only. This variable contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Active Viewport Only is on, false if off. See Time Configuration Dialog (p. 1616).

634

Chapter 3

Reserved Keywords, Symbols, Punctuation and Variables

preferences.constantReferenceSystem

Lets you get and set whether to use the same coordinate system for the Move, Rotate, and Scale tools in the 3ds max toolbar. A Boolean value - true if Constant is on, false if off. This variable matches the Constant check box in the General page of Customize > Preferences.
preferences.flyOffTime

Lets you get and set an Integer value that defines the time in milliseconds the user must hold down on a flyout before the flyout is activated. This variable contains the corresponding value set in the General page of Customize > Preferences.
preferences.maximumGBufferLayers

Lets you get and set an Integer value that specifies the maximum number of g-buffer layers generated during a render.
preferences.spinnerWrap

Lets you get and set a Boolean value that defines whether cursor wrapping is limited to an area close to the spinner when you drag to adjust spinner value. This variable contains the corresponding value set in the General page of Customize > Preferences.
preferences.useLargeVertexDots

Lets you get and set whether to use small or large dots when representing vertices as dots. A Boolean value set to true if you when using dots to represent vertices and a large size is desired. The value of this variable only has effect when UseVertexDots is set to true. This variable contains the corresponding value set in the Viewports page of Customize > Preferences.
preferences.useTransformGizmos

Lets you get and set whether to use the Transform Gizmos. A Boolean value - true if on, false if off. This variable contains the corresponding value set in the Viewports page of Customize > Preferences.
preferences.useVertexDots

Lets you get and set whether to represent vertices as dots. A Boolean value set to true when you want to use dots as the representation of the vertices in a mesh. If set to false, ticks will be used. This variable contains the corresponding value set in the Viewports page of Customize > Preferences.
realTimePlayback

Lets you get and set whether to playback in real time mode. This variable contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Real Time is on, false if off. See Time Configuration Dialog (p. 1616).
renderer

Lets you switch between the draft and production renderers and test which one is active. A Name value that accepts and contains the values #draft or #production, for example:
if renderer == #draft then ... renderer = #production render camera:c ...

See Controlling the Renderer (p. 1664) and Render Scene Dialog (p. 1611).

3ds max System Globals

635

renderDisplacements

Lets you get and set whether to perform displacement mapping during a render. A Boolean value - true if displacement mapping is to be performed, false if not.
renderEffects

Lets you get and set whether to perform Render Effects after a scene render. A Boolean value - true if Render Effects are to be performed, false if not.
renderHeight

Lets you get and set an Integer value that defines the output size height for the active renderer. This variable contains the corresponding value set in the Render Scene dialog. See Render Scene Dialog (p. 1611).
renderPixelAspect

Lets you get and set an Integer value that defines the output pixel aspect for the active renderer. This variable contains the corresponding value set in the Render Scene dialog.
renderWidth

Lets you get and set an Integer value that defines the output size width for the active renderer. This variable contains the corresponding value set in the Render Scene dialog. See Render Scene Dialog (p. 1611).
rendOutputFilename

Lets you get and set a String value that defines the output file name for the active renderer. This variable contains the corresponding value set in the Render Scene dialog. If this global variable is set to the Save File check box in the Render Scene dialog is unchecked.
rootNode

Contains a Node value that defines the root node of the scene. The root node does not physically exist in the scene, rather it is a special node that is the parent node of all nodes that are not linked to another node. The scene can be enumerated by accessing the children property of the root node. A run-time error is generated if you try to perform other node operations on the root node.
sceneMaterials

Contains a virtual array of materials and root level maps corresponding to the materials and root level maps present in the scene. You can get scene materials and root level maps via array indexing and iterate over them in a for loop. The array can be indexed by number, or by name or string to select by material or root level map name. This variable is read-only. See MaterialLibrary Values (p. 795).
scriptsPath

Contains a String value that defines the full directory path to the current Scripts directory. This variable is read-only.

636

Chapter 3

Reserved Keywords, Symbols, Punctuation and Variables

selectionSets

Contains a virtual array of all the current named node selection sets in the Named Selection Set drop-down list on the 3ds max toolbar. You can get named selection sets via array indexing and iterate over them in a for loop. The array can be indexed by number, or by name or string to select by named selection sets. You can change, add and delete Named Selection Sets by using the standard array methods on the selectionSets array. See the SelectionSetArray Values (p. 783) topic.
showEndResult

Lets you get and set the state of the Show End Result Toggle icon in the Modify panel. A Boolean Value true if Show End Result is on, false if off. See the Modify Panel (p. 1572) topic.
skipRenderedFrames

Lets you get and set whether to skip rendered frames during a render. A Boolean Value true if rendered frames are to be skipped, false if not.
sliderTime

Lets you get and set a Time value that defines the time associated with the 3ds max time slider. See Time Control (p. 1580).
snapMode.active

Lets you get and set a Boolean value defining the Snap toggle state - on (true) or off (false). This global variable is not available in 3ds max. See Status Bar Buttons (p. 1579).
snapMode.type

Lets you get and set a Name value defining whether 2D (#2D), 2.5D (#2_5D), or 3D (#3D) is the current snap type. This global variable is not available in 3ds max. See Status Bar Buttons (p. 1579).
subObjectLevel

Lets you get and set the sub-object level in the Modify panel if it is open. An Integer value of zero or greater up to the number of sub-object levels supported by the currently open modifier, typically in the order shown in the Sub-Object drop-down list. A subObjectLevel of 0 means sub-object mode is off. If the Modify panel is not open or sub-object level setting not permitted in the current modifier, the global contains the value undefined. Use the numSubObjectLevels global variable to access the maximum valid subObjectlevel value. See the Modify Panel (p. 1572) topic. For example:
b=box() em=edit_mesh() addModifier $box01 em max modify mode select $box01 print subObjectLevel subObjectLevel = 2 sysInfo.DesktopSize -------create a box create an Edit Mesh modifier add edit mesh mod open mod panel select object box01 print the current subobject level set sub-object level to Edge

A read only variable to get the desktop size in pixels as a <point2> value.
sysInfo.DesktopBPP

A read only variable to get the desktop color depth in bits per pixel as an <integer> value.

3ds max System Globals

637

sysInfo.MAXPriority

Get/set the 3ds max process priority as a <name> value. Valid priority values are #high, #normal, and #low
ticksPerFrame

Contains an Integer value defining the system time resolution. This variable is read-only.
timeConfiguration.playActiveOnly

Lets you get and set whether to playback the active viewport only. This variable contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Active Viewport Only is on, false if off. See Time Configuration Dialog (p. 1616).
timeConfiguration.realTimePlayback

Lets you get and set whether to playback in real time mode. This variable contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Real Time is on, false if off. See Time Configuration Dialog (p. 1616).
timeConfiguration.useTrackBar

Lets you get and set the state of the Time Configuration dialog Key Steps/Use TrackBar check box. A Boolean value true if checked, false if not. See Time Configuration Dialog (p. 1616).
trackbar.filter

Lets get and set the filter specifying which types of keys to show in the Trackbar. A Name value - the valid values are: #all, #TMOnly, #currentTM, #object, and #mat.
trackbar.visible

Lets you get and set whether the trackbar is visible. A Boolean value - true if the trackbar is visible, false if invisible
trackViewNodes

Contains a MAXTVNode value that defines top-level World node in Track View. This variable is read-only. See Track View Nodes (p. 1382).
units.DisplayType

Get/set the current unit display type as a <name>. Valid unit display types are:
#Generic #Metric #US #custom units.MetricType

Get/set the current metric unit display type as a <name>. Valid metric unit display types are:
#Millimeters #Centimeters #Meters #Kilometers

638

Chapter 3

Reserved Keywords, Symbols, Punctuation and Variables

units.USType

Get/set the current US standard unit display type as a <name>. Valid US standard unit display types are:
#Frac_In #Dec_In #Frac_Ft #Dec_Ft #Ft_Frac_In #Ft_Dec_In units.USFrac

Get/set the current US fraction display type as a <name>. Valid US fraction display types are:
#Frac_1_1 #Frac_1_2 #Frac_1_4 #Frac_1_8 #Frac_1_10 #Frac_1_16 #Frac_1_32 #Frac_1_64 #Frac_1_100 units.CustomName

Get/set the current custom unit name as a <string>

units.CustomValue

Get/set the current custom unit value as a <float>

units.CustomUnit

Get/set the current custom unit type as a <name>. Valid custom unit display types are:
units.SystemScale

Get/set the current system unit scale value as a <float>. This is the value shown in Preference Settings, General tab, System Unit Scale group.
units.SystemType

Get/set the current system unit scale type as a <name>. This is the unit shown in Preference Settings, General tab, System Unit Scale group. Valid system unit scale types are:
#Inches #Feet #Miles #Millimeters #Centimeters #Meters #Kilometers

3ds max System Globals

639

useEnvironmentMap

Lets you get and set the global rendering environment (Rendering > Environment) Use Map value. A Boolean value true if Use Map is on, false if off. See Working with 3ds max Atmospherics (p. 1345).
videoPostTracks

Contains a MAXTVNode value that defines the top-level Video Post Track View node. This variable is read-only. See Track View Nodes (p. 1382). This variable contains the value undefined in 3D Studio VIZ.
viewport.activeViewport

Lets you get and set the index of the active viewport. See Accessing Active Viewport Info, Type, and Transforms (p. 1581).
viewport.numViews

Contains the number of viewports in the current viewport layout. This variable is read-only. See Accessing Active Viewport Info, Type, and Transforms (p. 1581). The following 3ds max system global variables are specific to 3ds maxs default scanline A-Buffer renderer. These variables return undefined if the current renderer is not 3ds maxs default scanline A-Buffer renderer.
scanlineRender.antiAliasFilter

Lets you get and set the anti-aliasing filter. For a list of all of the anti-aliasing filters you can say:
showClass *:filter*

For example:
scanlineRender.antiAliasFilter = quadratic()

The anti-aliasing filters and their parameters are described in the 3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters (p. 1614) topic.
scanlineRender.antiAliasFilterSize

Contains a float value that defines the anti-aliasing filter size.

scanlineRender.enablePixelSampler

Lets you enables and disables global super sampling. A Boolean value - true if Disable all Samplers is off, false if on.

640

Chapter 3

Reserved Keywords, Symbols, Punctuation and Variables

MAXScript System Globals

These globals give access to the MAXScript system state. You can access and assign to them as noted.
currentTime

Contains a Time value that defines the current evaluation time in frames as set by the at time context expression currently in force. This is useful in functions that need to do time-relative computations that may be called from code that sets working animation time. If there is no at time context in force, currentTime contains the current user interface slider time, unless a render is in progress. If a render is being performed, currentTime contains the frame being rendered. This variable is read-only.
editorFont

Lets you get and set a String value that defines the font name for script Editor windows. Setting this variable effects all currently open and future script Editor and MAXScript Listener windows. This variable contains the corresponding value set in the MAXScript page of Customize > Preferences.
editorFontSize

Lets you get and set an Integer value defining the font point size for script Editor. Setting this variable effects all currently open and future script Editor and MAXScript Listener windows. This variable contains the corresponding value set in the MAXScript page of Customize > Preferences.
editorTabWidth

Lets you get and set an Integer value defining the tab width (in characters) for script Editor windows. Setting this variable effects all currently open and future script Editor windows. This variable contains the corresponding value set in the MAXScript page of Customize > Preferences.
escapeEnable

Lets you get and set a Boolean value defining whether ESC key interrupt detection is on or off. Setting enableEscape to false turns ESC key interrupt detection off, setting it to true turns it on again. This variable is useful when used in conjunction with a Progress Bar. You can set enableEscape to false when you dont want the user to be able to interrupt a script running a long computation and you have set up a progress bar with its own Cancel button. See Progress Bar Display (p. 1578).
heapFree

Contains an Integer value defining the current amount of free memory in the MAXScript heap. This value will vary constantly depending on where MAXScript is in its collection regime. This variable is read-only.

MAXScript System Globals

641

heapSize

Lets you get and set an Integer value defining the size of the heap currently allocated to MAXScript. MAXScript carves its own working memory (called a heap) out of the memory that 3ds max has allocated. You can add to this heap at any time by assigning the new size to this system variable, as in:
heapSize += 1000000 -- another meg please

See also the Memory Allocation and Garbage Collection (p. 655) topic.
inputTextColor

Lets you get and set a Color value defining the color of typed input text in Listener.
messageTextColor

Lets you get and set a Color value defining the color of error message text in Listener.
outputTextColor

Lets you get and set a Color value defining the color of output text in Listener.
options.oldPrintStyles

The printed form of all basic data value types, except for BigArray, are directly readable by the readValue() and readExpr() functions, making it simpler to read back in values printed to a file by MAXScript. If the pre-3ds max 4 print forms are required for compatibility with existing scripts, you can set this variable to true.
stackLimit

The stack is region of reserved memory in which MAXScript temporarily stores status data such as procedure and function call return addresses, passed parameters, and local variables. This defaults to 1Mb, but you may have certain scripts that contain recursive algorithms that will exceed this limit and so generate a runtime error. You can assign to the stackLimit variable to increase the stack size available.
stackLimit *= 2 ? -- double the stack

A special variable that is used only in the context of the MAXScript Listener. This variable contains the result of the last expression evaluated in the Listener. For more details, see the Using the ? Symbol (p. xli) topic.

642

Chapter 3

Reserved Keywords, Symbols, Punctuation and Variables

Chapter 4:

Variables - Assignment and Scope

A variable is a user-defined container to which you can assign a value, and then later retrieve the value. A variable is identified by its name, and anywhere the variable name is referenced, the value stored in that variable is used. In this section, the various attributes and considerations associated with variables are described.

See also
Variable Assignment (p. 643) Scope of Variables (p. 646) Persistent Global Variables (p. 651) Type-Free Variables (p. 653) Reference Assignment (p. 653) Memory Allocation and Garbage Collection (p. 655) Manual Garbage Collection (p. 656)

Variable Assignment
The syntax for general assignment, <assignment>, is:
<destination> = <expr>

where <destination> can be one of:

<var_name> <property> <array_index>

Each of these destination type is described below. MAXScript provides a swap() method that takes two valid assignment destinations as arguments and swaps their values. Its syntax is:
swap <destination> <destination>

644

Chapter 4

Variables - Assignment and Scope

Assignment to Variables A variable is identified with a MAXScript <var_name>, as described in the Names (p. 657) topic. If <destination> is a var_name, it identifies the variable to be assigned a value, as shown in the following examples:
x y z z = = = = 2 + 2 * 3 [1, 2, 3] + pos #(1, 2, foo, bar) #oops ----assign to variable x assign to variable y assign to variable z oops, changed my mind

Assignment to Accessors If <destination> is a <property> or an <array_index>, the assignment is to an accessor. Accessors are constructs used to access the components in compound values, such as arrays and 3D points. There are two kinds of accessors corresponding to the two kinds of compound values in MAXScript: The component values are arranged in an indexable sequence, as in arrays or strings. The compound value contains a fixed set of named components, as with 3D points and time intervals.

All 3ds max objects, such as boxes, spheres, bend modifiers, or bitmap textures are treated as compound values in this sense. All their parameters, such as height and angle, or map file name, are accessed as named components. In MAXScript, these named components are referred to as properties. For more information, see the Properties, Methods, Operators, and Literals (p. lxiv) topic. Accessors have one of two forms, an <array_index>:
<operand> [ <expr> ] -- an indexed element

or a <property>:
<operand>.<var_name> -- a named property property var_name of value in operand

Examples of assignment to accessors are:

$box01.pos = baseObj.pos + (baseObj.radius*[0,0,1])

Set the position property of object box01 based on the position and radius properties of the object whose value is stored in variable baseObj.
z[2] = d.rotation as eulerangles

Convert the rotation property value of the value stored in variable d to an eulerAngles class value, and store this value in element 2 of the array stored in variable z. Because MAXScript is an origin 1 language, all sequencable collections in MAXScript start at index position 1. This is an important convention to remember when using the indexing operator. The syntax definitions allow you to use any <operand> before the . or []. Because accessors are themselves operands, this definition is recursive, which means you can string accessors together to query nested arrays or properties:
my_things[i][j] my_objects[i].target.position.x

Variable Assignment

645

Accessors are evaluated left-to-right. The first example evaluates the ith element of my_things, which is presumably a nested array or an array of strings, before yielding the jth element of that element. The second example retrieves an object from an array of my_objects, then its target, then the position of the target (a 3D point), and finally the x coordinate of that point. An <operand> can also be a block-expression, allowing you to compute the target object to be accessed. For example:
(instance myNode).pos=myNode.parent.pos

Create an instance of the node whose value is stored in variable myNode, and set its position to the position of the myNodes parent object.
(find_table foo)[n - 2] = fred

Call function find_table with a parameter value of foo. The return value from the function is presumably an array. Set element n-2 of this array to the value fred. The named properties defined for the MAXScript values and classes are documented with the value and class descriptions. Order of Evaluation In an assignment, <expr> is evaluated before <destination>, as can be seen in the following example: Script:
a=#() -- create an empty array to play with a[(print in <destination>;1)]=(print in <expr>;10)

Output:
#() in <expr> in <destination> 10 ----result output output result line from from line 1 <expr> side of assignment <destination> side of assignment 2

Assignment in MAXScript is itself an expression and yields the value just assigned. Therefore, you can use assignments inside other expressions or cascade assignments, as in:
x = y = z = 0 #(1, 2, a = [0,0,1], 4)

646

Chapter 4

Variables - Assignment and Scope

Scope of Variables
Variables have an attribute called scope, which determines where in MAXScript code a variable can be accessed. MAXScript has two kinds of variable scope, global and local. Global variables are visible in all running MAXScript code and hold their values until you exit 3ds max. Local variables are directly visible to code only in the lexical scope currently in effect, and hold their values only as long as the current scope is active. Once a scope is no longer active, you can no longer access the contents of a variable local to that scope. This is similar to how most modern programming languages implement variables. The conditions under which MAXScript creates a new scope are described next. MAXScript provides language constructs used to explicitly declare and initialize both global and local variables. The syntax for variable declaration, <variable_decls>, is as follows:
( local | global ) <decl> { , <decl> }

where <decl> is defined as:

<var_name> [ = <expr> ] -- name and optional initial value

Examples:
global baz global foo=10, initialized=false local x = 1, y = 2, z = sqrt(123.7) -- initialized to undefined -- initialized globals -- continued on several lines

As mentioned above, local variables hold their values as long as that scope is active. In nested scopes, this is usually a very short period it starts when a function or loop or block expression runs and ends when it exits. Each time the scope is entered at runtime, a new set of locals is created and then retired when the scope is exited. In certain situations, however, the top-level scope can remains active for extended periods and so the locals declared at that top-level hold their values for that extended period. In particular, top-level locals declared in scripted rollouts, utilities, plug-ins, script controllers and Macro Scripts hold their values for as long as the rollout, utility, plug-in, or Macro Script exists. Typically, they remain in existence until you redefine them, so for example when you define a Macro Script and run it for the first time, the top-level scope is created and remains active over any number of subsequent executions unless you redefine the Macro Script. At this point, the existing top-level scope is retired and a fresh one (along with its top-level locals) is created when you next execute the Macro Script. This lets you use top-level locals in these constructs as a kind of private global; the values they hold remain in place over many executions but only code in that construct can see the variable and so it does not conflict with other globals. Note that in scripted plug-ins, a separate copy of the top-level local scope is created for each instance of the plugin and this scope remains active while that instance remains in existence up until the end of the current 3ds max session.

Scope of Variables

647

Note: In 3ds max R2.x , the optional initialization value is applied to global variables only if the declaration creates a new variable. So, for example, if you ran the following script twice, the value of x in the second line would be 10 for the first execution, and 20 for the second execution. In 3ds max R3, the optional initialization value is always applied to global variables.
global x = 10 print x x=20

If you want to make the global variable initialization conditional in 3ds max R3, use a construct similar to:
global foo; if foo == undefined do foo = 23

If you do not explicitly declare a variable, and the variable name does not exist at a higher scope, MAXScript will create the variable the first time you use it and initialize it to hold the special value undefined. You are not required to explicitly declare a variable, or initialize its value, before you can use it. Variable names not explicitly declared by one of the previous statements are called implicitly declared variables. The scope of implicitly declared variables is the MAXScript scope context currently in effect when the variable is first used. The initial MAXScript scope context is global, and new scope contexts are opened for the following: Top-level open parentheses in a script file or in the Listener Start of a function body Start of a for loop body Start of a utility, rollout, right-click menu, Macro Script, or tool definition Start of a rollout, utility, right-click menu, Macro Script, or tool event handler Start of a when body

Within these new scopes, newly referenced variables will be implicitly declared as local variables. Scope contexts are nested, with the scope of a variable explicitly or implicitly declared at one scope context level extending to all scope contexts below that level. Take for example the following script: Script:
a=10 ( b=20 for i = 1 to 5 do ( j=random i a k=random i b print (j*a+k*b) ) a=a+b ) print a print k -- scope context: global -- new scope context: level 1 -- new scope context: level 2

-- end of scope context: level 2 -- end of scope context: level 1 -- back to global scope context

In this script, variable a is first used in the global scope context, and its scope includes scope contexts global, level 1, and level 2. Variable b is first used in scope context level 1, so it is implicitly declared as a local variable and its scope includes scope contexts level 1 and 2. Variables i and j are first used

648

Chapter 4

Variables - Assignment and Scope

in scope context level 2, and their scope is only scope context level 2. The scope of variable k varies depending on whether this script has been run before. The first time the script is run, variable k is first defined at line 5, and its scope is scope context level 2. In line 11, variable k is used again. Because the variable k defined at line 5 is no longer in scope, a new variable k is defined whose scope is global. The second time you run the script, at line 5 MAXScript detects variable k already exists and uses it. So the first time you run the script line 11 will print undefined, and the second time you run the script line 11 will print the last value calculated at line 5. Note: The scope of the variable used as a for loop counter (variable i in the above script) is a special case. The for loop counter variables scope is always the scope context created for the for loop. This is true even if the for loop counter variables name has already been implicitly or explicitly declared at a higher scope context level. When you explicitly declare a local variable, you can reuse the same name as a variable at a higher scope context level. If you do this, the newly declared local variable hides the outer variables with the same name. Any reference to that variable name later in the local variables scope refers to the new local variable. At the end of the local variables scope, the next outer variable becomes visible again. This visibility scheme is called lexical scoping. An example of lexical scoping is shown in the following script. Script:
-- explicit declaration of foo and x, -- scope is global y = 10 -- implicit declaration of y, -- scope is global format context level global: foo= %\n foo if x > y then ( -- top-level open parentheses - new -- scope is created local baz = foo + 1 -- uses the global foo local foo = y - 1 -- declares 1st local foo, hides global foo format context level 1: foo= %\n foo b=box() -- b implicitly declared as local b.pos.x = foo -- uses 1st local foo if (foo > 0) then ( local a local foo = y - x -- a nested 2nd local foo, hides 1st local format context level 2: foo= %\n foo a = sin foo -- uses 2nd local foo format a= %\n a ) -- leave scope b.pos.y = foo - 1.5 -- back to 1st local foo format context level 1: foo= %\n foo ) -- leave scope -- b, baz and foo no longer in scope format context level global: foo= %\n foo -- back to global foo global foo = 23, x = 20

Scope of Variables

649

Output:
20 10 context level OK context level context level a= -0.173648 context level OK context level OK --global - foo= 23 --1: foo= 9 -2: foo= -10 --1: foo= -10 --global: foo= 23 --result result output result output output output output result output result of line 1 of line 3 from line 5 of line 5 from line 11 from line 18 from line 20 from line 23 of if expression lines 6 to 24 from line 26 of line 26

This might seem a strange way of over-using a single variable name, but in large programs, these scoping rules can be useful. For example, you may add a new user-interface item and its handlers to a utility script. By explicitly declaring the variables used in the handlers as local, you ensure these variables are independent of any preexisting variables with the same names in the remainder of the script. When writing scripts, it is good programming practice to explicitly declare your local and global variables. Implicit declaration is provided as a short-hand, typically used when working in the Listener interactively or developing short scripts. When developing extended scripts, explicitly declaring variables can reduce errors and improve readability of the code. It is also recommend that you declare as local all variables unless you really want them to be global variables. There are several reasons for this practice: All the variable names used in the block or function will be together, which makes it easier to find the variable names and helps prevent using incorrect names in the script. If more than one script is executed at the same time (for example, you are running a scripted utility and have a scripted controller in the scene) and both scripts use the same global variable name, the two scripts can interfere with one another. This can cause apparently random failures of one or both scripts. You are sure you are using the correct variable in the event that a variable with the same name has already been declared at a higher scope, and you wont inadvertently change the higherlevel variables value. Values of variables explicitly defined as local are displayed in error call stack trace-backs. In 3ds max R2.5, if a 3ds max class, a MAXScript method, or a MAXScript read-only global variable has the same name as an implicitly declared local variable, a MAXScript runtime error will be generated if an assignment to that variable name occurs. Since the variable name already existed with a global scope, an implicitly declared local variable was not created. Since one or more new 3ds max classes will be created by any third party plug-ins the user has loaded, you were not be able to tell ahead of time if a variable name was a global variable name. In 3ds max R3, if the MAXScript compiler detects that the first reference to such a variable is an assignment, it will implicitly declare a local variable, rather than leaving it as a reference to a read-only system global. For example, executing the following expression in 3ds max R2.5 would result in a value of Box, since Box is a 3ds max object class. In 3ds R3, MAXScript detects

650

Chapter 4

Variables - Assignment and Scope

that the first use of variable box is an assignment and creates an implicitly declared local variable box. The result of this expression in 3ds max R3 is the value undefined.
(if false do box=10;box)

In the following script, an error was introduced by using undefined variable k in line 7. In the output, the error call stack trace-back shows the value for variable b in function afunc and in the block-expression calling afunc. Script:
fn afunc = ( local b b = box() for i in 1 to 10 do for j in 1 to 10 do instance b pos:[i*20,j*30,30*sin(k*36)] ) -( global c=10 local b b=hello afunc() )

Output:
afunc() -- Error occurred in j loop -- Frame: -k: undefined -j: 1 -called in i loop -- Frame: -i: 1 -called in afunc() -- Frame: -b: $Box:Box102 @ [0.000000,0.000000,0.000000] -called in <block>() -- Frame: -b: hello -- No * function for undefined OK

If the same script is run with lines 3 and 12 removed, the following output is generated. Because function afunc and the block-expression are in different MAXScript scope contexts, variable b is implicitly declared as local in each and contain different values. However, because they were implicitly defined, they are not included in the error call stack trace-back.

Persistent Global Variables

651

Output:
afunc() -- Error occurred in j loop -- Frame: -k: undefined -j: 1 -called in i loop -- Frame: -i: 1 -called in afunc() -- Frame: -- No * function for undefined OK

See also
Type-Free Variables (p. 653) Reference Assignment (p. 653) Visibility of Locals, Functions, Structures and User-Interface Items in Rollout Code (p. 1478) Accessing Locals and Other Items in a Rollout from External Code (p. 1480)

Persistent Global Variables

MAXScript supports a limited form of persistent global variables. You declare a particular global to be persistent and the value it contains is always saved to and restored from scene files as they are opened and closed. Therefore, you can keep direct references to objects in the scene in variables and those references will persist across scene save and reload. You declare a global variable as persistent by prefacing its declaration with the reserved word persistent. For example:
persistent global foo, baz, bar

declares the variables foo, baz, and bar to be persistent. From then on, the values in foo, baz, and bar at the time of a scene save are stored in the .max scene file. When that file is reopened, the values in foo, baz, and bar are restored, with an implicit declaration as persistent globals if they are not so already declared. The current limitation with persistent global variables is that only certain kinds of value are storable in a scene file, and only those types of values are saved and restored across scene saves and loads. The supported value classes are: Integer, Float, String, Color, Time, Interval, Array, Point3, Ray, Quat, AngleAxis, EulerAngles, Matrix3, Point2, Undefined, OK, Boolean, and all the MAXWrapper classes (nodes, modifiers, controllers, materials, and so on). All other types of values restore as the value undefined. In the case of Array, only those values in the array that are in the previous list are correctly saved and restored; others appear as undefined in the restored array. Persistent globals are removed when a File > Reset, File > New, or File > Open is performed, so persistent globals added to one file do not stick around and become part of every other file opened

652

Chapter 4

Variables - Assignment and Scope

and saved. If needed, you can install persistent globals in each new file in a #filePreSave callback. See the General Event Callback Mechanism (p. 29) topic for more information. The following methods are used to show and delete persistent globals variables:
persistents.show()

Displays a list of persistent globals and their value.

persistents.remove <var_name>

Removes the named persistent global from the persistent global pool. The variable remains as a global variable and retains its value.
persistents.removeAll()

Removes all persistent globals from the persistent global pool. The variables remain as global variables and retain their value. Script:
a=Hello world persistent global a persistent global b=box() persistents.show() persistents.remove #a persistents.removeall() a b

Output:
Hello world OK $Box:Box02 @ [0.000000,0.000000,0.000000] a: Hello world b: $Box:Box02 @ [0.000000,0.000000,0.000000] OK OK OK Hello world $Box:Box02 @ [0.000000,0.000000,0.000000]

Note: If a persistent global contains a MAXWrapper value, but the class instance is not in the scene, that value is not stored/restored on a file save/load. Example:
-- persistents - node only persistent global global_array = #() global_array[1] = b= box() global_array[2] = bm= bend() global_array[3] = sm= standard() global_array[4] = fog() global_array[5] = area() global_array[6] = bezier_float() global_array[7] = br= bricks() global_array[8] = lookat()

Type-Free Variables

653

global_array[9] = blur() global_array[10] = MapScaler() --b.material=sm --addmodifier b bm --sm.diffusemap=br persistents.show() max hold max fetch persistents.show()

Remarks: Only the box is in the array after running this script. If the commented lines are run, the material, modifier, and map are also in the array. MAXScript does not do a full reference-tree dump when it outputs its persistent variables, it just outputs RefIDs for MAX objects and so depends on them being dumped as references by the main file save code.

Type-Free Variables
Variables can hold any type of value, and the value type they hold can change from assignment to assignment. For example, you can store a point3 value, then a float value, and then an array to the same variable. The variables in MAXScript are known as type-free variables, unlike variables in C or Java, which can only hold values of a particular declared type. This freedom makes scripting simpler and more exploratory. As well as being type-free, variables in MAXScript are also type-safe. This means you cannot perform the wrong operation on a value in a variable, as shown in the following example, where MAXScript prints an error message following the invalid operation:
x = $Box01.position -x = foo -x = x + 2 -Error: Unable to convert a point3 value a string value try to add a number to a string 2 to type String

Reference Assignment
MAXScript uses a type of assignment called reference assignment. When you create a value, for example by writing a literal, the memory for that value is allocated and a pointer or reference to the value is placed into the variable rather than the value itself. If you assign that variables value to another variable, the reference to that values memory is placed in the new variable. The same applies to assigning a variables value to an array element or passing it as a function call argument; in all cases the reference is assigned or passed. When you assign a new value to a variable or when a variable goes out of scope, the reference that the variable contained is dropped. When your program has dropped all references to a values memory, that memory becomes eligible for reclamation. This is in contrast to value assignment in which a copy of the whole values memory is made and assigned. Value assignment has one advantage over reference assignment, namely that every time a variable or an array element is re-assigned, the old values memory space can be immediately

654

Chapter 4

Variables - Assignment and Scope

reclaimed because the old value is unique and nothing else can be referring to it. With reference assignment, the system cannot reclaim the original values memory space, because other variables may still point to the same value. Some scripting languages use a copy-based approach, such as HyperCards HyperTalk, but its inefficiency as well as some value sharing problems make it inappropriate for MAXScript. This creates the task of reclaiming memory in MAXScript. Programming languages such as C or Pascal require that the programmer explicitly reclaim a values memory when it is no longer needed, and this is one of the most difficult parts of programming in those languages. Recent variants like Java and some advanced languages like Lisp and Smalltalk provide automatic memory reclamation. MAXScript also provides this and it is described in the Memory Allocation and Garbage Collection (p. 655) topic. If you assign a variables value to another variable, the reference to that values memory is placed in the new variable. Thus, both variables are actually referencing the exact same value. If you assign a new value to one of the variables, that variable will contain a reference to the new value, and the other variable will contain a reference to the old value. Normally this is the desired behavior, as you dont want both variables to reference the new value. However, a complication occurs if a compound value, like a point3 or array, is referenced by more than one variable, and you assign a new value to a component of the compound value. When you assign a value to a component of a compound value, a new compound value is not created. Therefore any variables that reference the compound value will still point to the same value, and will see the changed component value. Examples of this behavior are shown in the following script: Script:
( a=hello world b=a format a=%; b=%\n a b b=thanks for the fish format a=%; b=%\n a b b=a a[1]=J format a=%; b=%\n a b a=b=[10,20,30] format a=%; b=%\n a b a.x=-100 format a=%; b=%\n a b ) ------------create a string value, put reference in a put strings reference in b and print their values create a string value, put reference in b print values they are different put strings reference from a in b change a component value print values they are the same assign a point3 value reference to a and b and print their values change a component value print values they are the same

Output:
a=hello world; b=hello world a=hello world; b=thanks for the fish a=Jello world; b=Jello world a=[10,20,30]; b=[10,20,30] a=[-100,20,30]; b=[-100,20,30] OK

Memory Allocation and Garbage Collection

655

In some cases, this behavior is the desired behavior, and in other cases it is not. For those cases where it is not the desired behavior, a copy method is defined for most value types that will create a separate copy of a value. In some cases, such as arrays and structures, the value itself may contain compound values. The copy made is what is called a shallow copy - only a copy of the upper-level value itself (that is, the array) is created. Copies arent made of compound values in the value (that is, the elements of the array).

Memory Allocation and Garbage Collection

MAXScript allocates its own working memory in addition to any memory 3ds max allocates as it works. The default working memory size setting for MAXScript is 5.5 MB, and the memory is virtual and pageable like all 3ds max memory. The default allocation accommodates most tasks, but you can increase it by incrementing the MAXScript system global variable heapSize:
heapSize += 2000000 -- another 2 MB, for a total of 7.5 MB

You can add this statement to your startup script if you always need extra memory allocated for MAXScript tasks or you can set the default size in the MAXScript tab in the 3ds max Preferences dialog. Increasing the MAXScript heap reduces memory address space for other 3ds max tasks. Adjust the default memory setting only after you receive Out of memory error messages from MAXScript, or when garbage collection pauses occur frequently. You can increase the MAXScript heap as many times as you need during a 3ds max session, but you cannot reduce it. Restart 3ds max to reset the MAXScript memory heap to the default setting. MAXScript uses a memory management scheme called automatic garbage collection. This means you dont have to explicitly reclaim any memory that a value takes up when you no longer need it. When you assign a new value to a variable or when a local variables block exits, the reference that the variable contained is dropped. When your program has dropped all references to a values memory, that memory becomes eligible for reclamation. Some values, such as arrays, have internal references to other values. In an array, each element contains a reference to another value. When you assign a new value to an array element, the elements old reference is dropped. If you remove all references to the array itself, all the references in the elements of that array are implicitly dropped. The same applies to component values, such as in user structures and most 3ds max objects. MAXScript reclaims memory in a garbage collection pass through memory when MAXScript runs out of memory. This simple approach can result in a short pause because the entire MAXScript memory is scanned for garbage. Some languages use background collectors that work continuously; others use advanced schemes that minimize the scanning. Later versions of MAXScript might adopt one or more of these techniques. The advantage of garbage collection is you can create as many values as you need, and MAXScript cleans up the ones you no longer use.

656

Chapter 4

Variables - Assignment and Scope

Manual Garbage Collection

The function gc() invokes the garbage collector. Normally, the collector runs automatically when available memory runs low, so you dont normally need to call it explicitly. However, in some situations, it is useful to be able to force a collect to ensure a pause due to garbage collection will be delayed as long as possible. You can also invoke the collector to cause any unreferenced open files to be closed. In some situations, a file can be left open if a runtime error occurs while it is still open. If the file object was being held in a local variable at this point, it may not be possible to get at it from the Listener to force a close. Any subsequent attempts to open it may result in an already open error from the operating system. Running the collector will cause the file object to be reclaimed and this forces any open file associated with it to be closed.
gc()

This function returns the number of bytes free in the MAXScript heap after collection. Note that the collector may take many seconds to run if the heap is full of many small reclaimable objects.

Chapter 5:

Names, Literal Constants, and Expressions

Names
Names are used in MAXScript to identify variables, functions, parameters, properties, and so on. Names start with an alphabetic character or _ (underscore), and can contain any number of alphanumeric characters or _. Examples of valid names are:
foo bar123 this_is_a_very_long_identifier _heresOneWithStudlyCaps

The following names are not valid:

1object pressed? a big number seven(7) First character not an alphabetic character ? is not a valid alphanumeric character spaces not allowed in names ( and ) are not valid alphanumeric characters

In contrast to most general purpose programming languages, MAXScript names are not casesensitive. For example, the names in the following list refer to the same variable in MAXScript:
BitMapTexture bitmaptexture BITMAPtexture

In syntax descriptions, name identifiers are specified as:

<var_name>

An example of a syntax where a name identifier is specified is:

for <var_name> ( in | = ) <sequence> ( do | collect ) <expr>

In this example, <var_name> specifies the for loop variable.

658

Chapter 5

Names, Literal Constants, and Expressions

A name in a program is always interpreted as the name of a variable or parameter and it effectively stands for the current value of that variable or parameter in any expression in which it is used. For example, consider the following script:
i=10 j=i+5 print j

In this script, i and j are variable names. In the first line, the value 10 is assigned to variable i. In the second line, the value 5 is added to the value stored in variable i, and then the result is stored in variable j. In the third line, the value 15 is printed, which is the value stored in variable j. MAXScript also allows you to work directly with names as values at runtime, as you can with numbers and strings. To write a name value in MAXScript, you preface the name with a #:
#<var_name>

In syntax descriptions, name values are specified as:

<name>

Name values are primarily used for symbolic parameters in function calls, and many of the built-in functions use them as such. The allowed values specified for symbolic parameters are defined by the function, and are documented with the function. As an example, consider the setBeforeORT() function. Its syntax is:
setBeforeORT <controller> <ORT_type_name>

Sets the Out-of-Range (ORT) type for the controller for the time before the first key. The <ORT_type_name> must be one of the following name values:
#constant #cycle #loop #pingPong #linear #relativeRepeat

An example usage of this function is:

setBeforeORT $box01.position.controller #pingPong

Name values can also be used as an index in certain Collections (p. 773). For example, the index for a ModifierArray (p. 794) can be an integer, name, or string:
$loft01.modifiers[#Optimize] -- access modifier on object loft01 called Optimize

See also
Name Values (p. 727)

659

Quoted Names Names set in single quotes allow you to write names that contain illegal identifier characters, such as spaces and other punctuation. They are primarily intended for specifying 3ds max object classes and properties that have special characters in their names. The form is:
<any_char_except_quote> #<any_char_except_quote> <any_char_except_quote>: -- for an identifier or property name -- for a name literal -- for a keyword parameter label

Examples:
snow starttime(start):5 b.lifetime(life) $box01.modifiers[#FFD 4x4x4]

Spaces in Names Because of the large amount of names in 3ds max that include spaces, the underscore character (_) can be used instead of a space in a name. The following is equivalent to the last line of the above example:
$box01.modifiers[#FFD_4x4x4]

Literal Constants
MAXScript has many built-in data types: numbers, strings, names, arrays, vectors, and matrices, as well as special data types which store the 3ds max objects such as geometry objects, splines, materials, modifiers, etc. Some data types have special literal constant forms, where the literal constant is a value that is keyed directly into your program where it is needed. The syntax of the literal constant specifies both its value and data type. In MAXScript, the assignment of a literal constant might look like this:
b=50

In this line, b is the variable name, and 50 is the literal constant of type integer assigned to b. 50 is a literal constant because you cannot assign a value to 50, and its value cannot be changed.

See also
Number Literals (p. 660) String Literals (p. 660) Time Literals (p. 662) Pathname Literals (p. 662) 2D and 3D Point Literals (p. 665) Array Literals (p. 666)

660

Chapter 5

Names, Literal Constants, and Expressions

Number Literals
MAXScript uses two types of numbers: single precision floating point 32 bit signed integers

These number types correspond to the two number types (Integer and Float) used internally in 3ds max. The syntax for numbers is:
[-]{<digit>}[.{<digit>}[(e | E)[+ | -]{<digit>}+] 0x{<hex_digit>}+ -- decimal number -- hexadecimal number

Examples:
123 123.45 -0.00345 1.0e-6 0x0E .1

See also
Number Values (p. 717)

String Literals
String literals in MAXScript are one or more characters enclosed in double quotes:
3ds max October 5th, 1996

String literals can contain any character except another plain double quote. You can include a double quote in a string literal, as well as some useful control characters, by using a \ (backslash) escape character sequence. The valid escape sequences are:
\ \n \r \t \* \? \\ \% \x{d} ---------a double quote character a newline character a carriage return character a TAB character an asterisk character a question mark character a single \ character a percent character a hexadecimal character

String Literals

661

Example:
print foo should be quoted like this: \foo\ and a new line: \n

would output:
foo should be quoted like this: foo and a new line:

A \ character that does not preface one of the specified characters is left as a single backslash. You can break a string literal into several lines and the line breaks will stay in the string. For example:
Twas brillig and the slithy tobes did gyre and gimbol in the wabe or something like that...

Non-Printing Characters in Strings You can specify non-printing characters in string literals using the \x hexadecimal escape sequence convention from C/C++. The form is:
\x{<hex_digit>}+ -- <hex_digit> is a hexadecimal digit (0-9,a-f)

Example:
str = Copyright \xa9 1997, FrabWorks, Inc

would insert a copyright sign . Hexadecimal a9 is the code for that symbol. Running the following script displays in Listener the characters associated with each hexadecimal code: Script:
char=0123456789abcdef for i=1 to char.count do for j=1 to char.count do ( s=execute(\\\x+char[i]+char[j]+\) format %% %\n char[i] char[j] s )

File Path Name Strings File path name strings use the backslash character to separate a parent directory from its subdirectory. The backslash is used as an escape character, therefore file path names specified in a string should use the escape character sequence for a single \ character, i.e., \\. An example is:
scene_path = g:\\3dsmax25\\scenes -- specifies file path g:\3dsmax25\scenes

For strings that are used as file names or paths, the / character can be used instead of the \\. MAXScript internally interprets the / character as a \ character when used in a file path name string. An example is:
scene_path = g:/3dsmax25/scenes -- specifies file path g:\3dsmax25\scenes

See also
String Values (p. 722)

662

Chapter 5

Names, Literal Constants, and Expressions

Time Literals
Time is a basic data type in MAXScript. Its semantics are based on animation time in 3ds max, where you can express time in frames, ticks or normalized time. In 3ds max, time is stored with a resolution of 4800 ticks per second. The format for a time literal is one of:
[-]{<decimal_number>[m | s | f | t]}+ [-]{<digit>}:{<digit>}[.{<digit>}] [-]<decimal_number>n -- minutes/sec/frames/ticks -- SMPTE mins:secs.frame -- active segment normalized time

In the first form, the {...}+ indicates one or more repetitions, so you can string together minutes/ seconds/frames/ticks. If you do this, they must be in the specific minutes/seconds/frames/ticks order. The normalized time form is always relative to the current active animation time segment. Examples:
2.5s 1m15s 2m30s5f2t 125f 18.25f 1f20t 2:10.0 0:0.29 0.45n ---------2.5 seconds 1 minute 15 seconds 2 minutes 30 seconds 5 frames 2 ticks 125 frames 18.25 frames 1 frame 20 ticks 2 minutes 10 seconds 0 frames (SMPTE) 29 frames (SMPTE) 0.45 normalized time (fraction of active segment)

See also
Time Values (p. 751)

Pathname Literals
Names (p. 657) identify entities such as variables and parameters inside the running MAXScript program. If you want to identify objects by name in the 3ds max scene, you use a pathname. Pathnames can name a single object in the scene, specify a particular object using a path through the object hierarchy, or name sets of objects using pattern matching. The full syntax for a pathname literal is:
<path_name> <path> <levels> <level> <level_name> ::= ::= ::= ::= ::= $<path> | $ [ <objectset> ] [ / ] [ <levels> ] <level_name> <level> { / <level> } <level_name> ... { <alphanumeric > | _ | * | ? | \ } { <alphanumeric > | _ | * | ? | \ }

The root of a <path> can be an <objectset>, which limits the pathname searching to the object set you specify. ObjectSets are described in the ObjectSet Values (p. 781) topic.

Pathname Literals

663

Examples:
$box01 $torso/left_up_arm/left_low_arm $*box* $torso/* $helpers/d* --------object named box01 hierarchy path name all objects with box in the name all the direct children of $torso all helper objects whose name starts with d

All objects in a 3ds max scene are arranged in a hierarchy as presented in Track View. This is both an important organizing scheme in 3ds max, and it suggests a MAXScript naming scheme for objects based on the path to an object through the hierarchy. It is also very similar to path names in an operating systems directory structure. For example,
$dummy/head/neck

names the scene object neck whose parent is object head, which has the top-level parent object dummy. This pathname helps you identify a specific object in a 3ds max scene, even if several objects have the same name. If head is unique in the scene, MAXScript lets you use the shorthand $head to refer to it regardless of its hierarchy position. Even if the object is not uniquely named you can use the shorthand form, but it is undetermined which of the same-named objects you will get. Pathnames also provide a powerful way to refer to several objects at once, such as all the children of a certain parent, or all the objects with names containing the string foot. For this, you can use wild-card patterns, as you can with operating system shell file naming schemes. For example,
$dummy/*

names all the immediate children of dummy. The * character is used as a wild card. Or,
$neck*

finds all the objects, whose names start with the string neck, anywhere in the hierarchy. You can use wild cards anywhere in a pathname. For example,
$*foot*

finds all the objects with foot anywhere in their names. The * wild-card character effectively matches any number other characters. You can also use the ? wild-card character to match exactly one dont care character. This is, the ? wild-card character will match any single character. For example,
$box0?

finds all the objects that begin with box0 and have exactly one character after the 0 in their names. Wild-card characters can also be used for specifying parent levels in a hierarchy. For example,
$dummy/*/*

names all the children of all the children of $dummy.

664

Chapter 5

Names, Literal Constants, and Expressions

If you want to find an object and all the children of the object at any nested level, you use the special ellipsis level name ..., as in:
$dummy/.../box*

This refers to $dummy and all the box* children at any level below $dummy. The ... indicates to search the entire hierarchy below the level of the ellipsis. MAXScript lets you omit the / when using ... because it is unambiguous:
$dummy...box*

Or, in another common example,

$dummy...*

names $dummy and all the children of $dummy at any level. If you use a wild card in an object pathname MAXScript will manipulate all matching objects at one time. For example,
hide $*foot*

hides all objects whose names contain foot. You can also perform automatic collection mapping, where a property for each matching object is set. For example,
$*box*.position += [10, 10, 0]

adds [10,10,0] to the positions of all scene objects whose names contain box. For more information, see the Collections (p. 773) topic. You can use a shorthand form for specifying the currently selected object or objects with the pathname syntax. A lone $ character refers to either the currently selected object if a single object is selected, the current selection set as an ObjectSet if more than one object is selected, or undefined if no objects are selected. This is a useful shorthand for use in the Listener when working on selections. For example:
$.pos = [0,0,0] hide $ rotate $ 35 z_axis

Inside a script, it is better to use the selection ObjectSet rather than $. selection always contains an ObjectSet regardless of the number of selected objects. Where hide $ will generate an error if no objects are selected (because $ contains the value undefined), hide selection will not generate an error. Due to the way that 3ds max internally processes notification signals, the $ form of accessing selected objects is not recommended in a select change handler. To access the selected objects, you should use the selection ObjectSet. This is because $ relies on information that has not yet been set in the selection processing whereas selection uses a different method of accessing selections and the information it uses has been set up.

See also
Spaces and Other Special Characters in Pathnames (p. 665) ObjectSet Values (p. 781) Collections (p. 773)

Spaces and Other Special Characters in Pathnames

665

Spaces and Other Special Characters in Pathnames

3ds max lets you use any characters you want in object names, including spaces and other MAXScript punctuation. You can write pathnames that contain these characters by putting the name in single quotes, for example:
$a silly name!!

These quotes do not hide wild-card characters, so if you happen to have an object in your scene with a * in its name, you have to escape the * character in the pathname with a backslash:
$what the \*

See the String Literals (p. 660) topic for other escape character sequences. Because of the large number of names in 3ds max that include spaces, the underscore character (_) can be used instead of a space in a name. For example, the following two lines are equivalent:
bodyPart=$Bip01 L UpperArm bodyPart=$Bip01_L_UpperArm

2D and 3D Point Literals

Coordinates are used extensively in MAXScript programming. They support a large range of operations as described in the Point2 Values (p. 736) and Point3 Values (p. 731) topics. You can write point literals using the following forms: 2D
[ <expr>, <expr> ]

3D
[ <expr>, <expr>, <expr> ]

where <expr> evaluates to an Integer or Float value. Examples:

[320, 240] [10, 20, 30] -- 2D point -- 3D point

Expressions in a literal are evaluated when the literal is built. The following script and results show the value stored in a Point3 when expressions are used in the literal: Script:
a=10 b=45 [10, 20, 30] [sin a, 2 * b, a^2 + b^2]

-- can contain expressions

666

Chapter 5

Names, Literal Constants, and Expressions

Output:
10.0 45 [10,20,30] [0.173648,90,2125] ----result result result result of of of of line line line line 1 2 3 4

See also
Point2 Values (p. 736) Point3 Values (p. 731)

Array Literals
An array in MAXScript is an ordered collection of values. Each element in the array can contain any type of value, and you can index and iterate an array. You can write array literals directly in a program or build the collection with the array functions provided in MAXScript. For details, see the Array Values (p. 776) topic. Array literals can be expressed in two forms:
#( <expr> { , <expr> } ) #() -- empty array

Examples:
#(1, 2, 3) #() #(1,foo,#(1.2, -4,#fred),[1,2,3]) -- this one has a nested array

Expressions in an array literal are evaluated when the literal is built. The following script and results show the values stored in an array when expressions are used in the literal: Script:
a=10 x=45 #(1, sin x, a * 2.3)

-- can contain expressions

Output:
10.0 45 #(1, 0.707107, 23.0)

Array Literals

667

Expressions
MAXScript is an expression-based language. Every construct in the language is an expression and yields a result; this includes constructs that other languages consider statements. The simplified syntax of the language allows you to build very expressive code. Anywhere you can write an <expr> expression, you can write any construct in MAXScript. A good example of this is the if construct. In statement-based languages, there is usually one syntax for if statements and another for conditional expressions. In MAXScript, a single syntax is used for both cases. For example, the following two lines of code are both valid, and their meaning should be obvious:
if a > b then print c else print d x = if a > b then c else d

You can also write the following line, containing a nested if expression and a nested assignment, which itself is an expression:
x = if (if a > b then c else d) < e then f else (g = 23)

Another example is the block-expression, denoted <block_expr>. It contains a series of <expr> expressions enclosed in parentheses:
( print a print b if a > b then print the big a )

Each expression in the block is separated by a line break. You can also write several expressions on one line using a ; (semicolon) to separate them:
(print a; print b; if a > b then print the big a)

Block-expressions are themselves <expr> expressions. They evaluate their component expressions in sequence and yield as their value the value of the last expression in the block. To create classic block-structured statements, you might write:
if a > b then ( print c x = sqrt (c) ) else ( print d x = sin (e) )

or, use a nested block-expression to compute a comparison operand:

if a > (y = sin b; sqrt(y * z)) then print c

668

Chapter 5

Names, Literal Constants, and Expressions

At its simplest, a MAXScript program is made up of <expr> expressions. An <expr> is defined as any of the following:
<simple_expr> <variable_decls> <assignment> <context_expr> <if_expr> <while_loop> <do_loop> <for_loop> <loop_exit> <case_expr> <try_expr> <function_def> <function_return> <struct_def> <max_command> <utility_def> <rollout_def> <tool_def> <rcmenu_def> <plugin_def>

This list of expressions constitute the main constructs in MAXScript.

See also
Simple Expressions (p. 669) Context Expressions (p. 681) Controlling Program Flow (p. 691) Creating Functions (p. 699) Structure Definition (p. 707) Literal Constants (p. 659) Variables Assignment and Scope (p. 643) 3ds max Commands (p. 1630) Scripted Utilities (p. 1463) Utility Clauses (p. 1466) Scripted Mouse Tools (p. 1531) Scripted Right-Click Menus (p. 1514) Scripted Plug-ins (p. 1538)

Array Literals

669

Simple Expressions
Simple expressions in MAXScript, denoted as <simple_expr>, correspond to the constructs normally considered expressions in math and conventional programming languages, as in the following examples:
a + b * c sin x

The expressions are generally comprised of operands (a, b, c, and x), that are acted on by operators (+ and *) or given as parameters to functions (sin). Simple expressions are divided into the following groups:

See also
Operands (p. 669) Math Expressions (p. 670) Comparison Expressions (p. 673) Logical Expressions (p. 674) Function Calls (p. 675) Block-Expressions (p. 679)

Operands
Operands, denoted as <operand> in the syntax definitions, are the references to values that surround operators or are passed as parameters to a function. Prime examples are Literal Constants (p. 659) and variable names. Operands are divided into two groups, Factors and Accessors. Factors Factors, denoted as <factor> in the syntax definitions, are references to values, where the entire value is acted on. A factor can be a Literal Constants (p. 659), a Reserved Global Variable (p. 628), a variable name, or an expression. The unary minus applies the math negate operator to its operand.
-<operand> -- unary minus

The unary minus is only applicable to factors that evaluate to a number. Examples:
-0.75 sin (-a*pi)

670

Chapter 5

Names, Literal Constants, and Expressions

Accessors Accessors are constructs that let you access the components in compound values, such as arrays and 3D points. There are two kinds of accessors corresponding to the two kinds of compound values in MAXScript: The component values are arranged in an indexable sequence, as in arrays or strings. The compound value contains a fixed set of named components, as with 3D points and time intervals.

All 3ds max objects, such as boxes, spheres, bend modifiers, or bitmap textures are treated as compound values in this sense. All of their parameters, such as height and angle, or map file name, are accessed as named components. In MAXScript, these named components are referred to as properties. Accessors have one of two forms, an <array_index>:
<operand> [ <expr> ] -- an indexed element

or a <property>:
<operand>.<var_name> -- a named property

Examples:
maps[i] selection[n+1] position.x bend.angle

Math Expressions
The math expressions in MAXScript correspond to the common operator expressions in mathematics, such as add, subtract, multiply, divide, and so on. The <math_expr> constructs in MAXScript are:
<math_operand> + <math_operand> -- standard arithmetic addition <math_operand> - <math_operand> -- standard arithmetic subtraction <math_operand> * <math_operand> -- standard arithmetic -- multiplication <math_operand> / <math_operand> -- standard arithmetic division <math_operand> ^ <math_operand> -- exponential, raise to the power <math_operand> as <class> -- conversion between types

where <math_operand> can be one of:

<operand> <function_call> <math_expr>

Note that a math operand can be another nested math expression. This is another instance of a recursive syntax definition which lets you create arbitrary sequences of operands and operators.

Math Assignment

671

Note also that the math unary minus is not defined here, it is one of the <operand> types described in the Operands (p. 669) topic. Examples:
42 2 + 2 2 * a - sin x / b (a + b) * -c 2 ^ n (n + 1) as string

-- using a function call

-- converts result to a string value

The conversion operator, as, works between selected sets of source and destination value types. Only certain kinds of values can be converted into certain other kinds of values. These allowed conversions are defined for each type of value, and are documented with the value type descriptions.

See also
Math Assignment (p. 671) Precedence and Association Rules (p. 672) Polymorphism (p. 672)

Math Assignment
MAXScript provides the C language shorthand form of assignment that can be used to modify a value in place, as shown in the following long-form examples:
x = x + 1 $obj.pos = $obj.pos * scale -- increment x by one -- multiply $obj.pos by scale

Corresponding to the four math operations (+, -, *, and /) are assignment operators that apply the operation to the assignments destination and update the destination with the result. Their syntax is:
<destination> <destination> <destination> <destination> += -= *= /= <expr> <expr> <expr> <expr> ----add <expr> to destination subtract <expr> from destination multiply destination by <expr> divide destination by <expr>

Using the shorthand form of assignment, the previous examples can be written as:
x += 1 $obj.pos *= scale -- increment x by one -- multiply $obj.pos by scale

672

Chapter 5

Names, Literal Constants, and Expressions

Precedence and Association Rules

As in mathematics, a sequence of operands and operators is evaluated according to a set of precedence and association rules. The following table shows sample expressions and their order of evaluation:
Expression a + b * c a + b - c a ^ b ^ c Order of evaluation a + (b * c) (a + b) - c a ^ (b ^ c) -- exponentiation, raise to the power

The evaluation order in the previous table follows standard precedence rules, where * and / operations are evaluated before + and - operations, and where + and - operations associate to the left (that is, operands on the left are evaluated before operands on the right) and exponentiation operations associate to the right (that is, operands on the right are evaluated before operands on the left). These precedence rules define the ordering of evaluation in all expressions in MAXScript, unless parenthesizing is used to force a different order. Expressions in parenthesis are evaluated before the surrounding operands are applied. The following list shows the precedence order for math expressions starting with the highest precedence:
<operand> <function_call> as ^ -- right associative * and / -- left associative + and -- left associative

See also
Function Precedence (p. 677)

Polymorphism
As in mathematical expressions, MAXScript operators are polymorphic. This term means a single operator can be used to operate on a number of different types of values and performs the appropriate action for each type of value. For example, a + operator between two integers performs integer arithmetic, between two floats it performs real arithmetic, and between two matrices it performs a matrix addition. MAXScript allows certain non-mathematical types to use certain math operators. For example, you can concatenate two strings with the + operator:
twas brillig + and the slithy tobes x.name += sequence_number as string

Polymorphism

673

In some cases, you can mix operand types and MAXScript converts them appropriately. For example, adding a float to an integer results in a float. Multiplying a 3D point by a float results in a scalar vector product, and so on. Internally in MAXScript the allowable operators and the actions performed by the operators are defined for each type of value. The allowable operators and their actions are documented with the value type descriptions.

See also
Inheritance and Polymorphism (p. lxiii)

Comparison Expressions
Using comparison expressions you can compare values of comparable types. The result is always one of the two Boolean values, true or false. The various forms of <compare_expr> are as follows:
<compare_operand> <compare_operand> <compare_operand> <compare_operand> <compare_operand> <compare_operand> == <compare_operand> != <compare_operand> > <compare_operand> < <compare_operand> >= <compare_operand> <= <compare_operand> -- equal -- not equal -- greater than -- less than -- greater than or equal -- less than or equal

where <compare_operand> can be one of:

<math_expr> <operand> <function_call>

Examples:
a > b sin x == 0.0 a + b <= n - 1

Comparison operations have lower precedence than math operations. In the previous examples, the sin function call and the + and - operations are performed before the comparisons. As with math expressions, the comparison operators work on all appropriate types. Equal == and not-equal != operate on all types, and the relative comparisons work between comparable types. The allowable comparison operators are documented with the value type descriptions.

674

Chapter 5

Names, Literal Constants, and Expressions

Logical Expressions
Logical expressions combine the results of Boolean expressions, such as comparisons, to construct complex conditional expressions. The forms of a <logical_expr> are as follows:
--<logical_operand> and <logical_operand> --[ not ] <logical_operand> -<logical_operand> or <logical_operand> true if either operand is true true if both operands are true true if operand is false

where <logical_operand> is one of the following:

<operand> <compare_expr> <function_call> <logical_expr>

Logical operators only operate on Boolean values, so each <logical_operand> must evaluate to true or false. Examples:
a > 0 and a < n + 1 not x and y a and b or c and d and not e

As with math expressions, <logical_expr> is a recursive definition, meaning a logical operand can be another logical expression. You can have arbitrary sequences containing and, or, and not, and the order of evaluation is defined by the following precedence ordering (in decreasing order of precedence):
not and or -- right associative -- left associative -- left associative

This means that in an unparenthesised logical expression, not is evaluated before and which is evaluated before or. Logical operators have a lower precedence than comparison operators, math, and function calls. Therefore, these operations are always evaluated before logical operators, which follows convention. The previous examples would be evaluated in the following order:
(a > 0) and (a < (n + 1)) (not x) and y (a and b) or ((c and d) and (not e))

See also
Short-Circuiting Logical Expressions (p. 675)

Short-Circuiting Logical Expressions

675

Short-Circuiting Logical Expressions

Following the convention in most other programming languages, logical expressions in MAXScript are short-circuiting or non-strict. This means only enough of the sub-expression is evaluated to determine the overall result: If the first operand is false in an and expression, the result must be false, therefore, the second operand is not evaluated. If the first operand is true in an or expression, the result must be true, therefore, the second operand is not evaluated.

This saves execution time and enables useful shorthand notation. For example, if you want to calculate sin a if the value of variable a isnt undefined, you can use the following example:
if a != undefined and sin a > 0 then ...

In a strict language, the sin a evaluation of an undefined operand results in an error, and you would need to break up the expression into two if statements:
if a != undefined then if sin a > 0 then ...

Function Calls
A function call expression passes an optional list of arguments to a MAXScript or user-defined function, and the value returned by the function is the function call expressions result. A <function_call> has one of the following forms:
<operand> { <argument> }+ <operand> () -- one or more arguments -- no arguments

in which, <argument> is one of the following:

<operand> <name>: <operand> -- keyword argument

Examples:
sin a tan2 x y print (n + 1) to:debug fns[i] $box01 move object1 [10,20,x * 3]

-- get function out of array fns

This syntax is unlike most programming languages which typically use parenthesized lists of comma-separated arguments. This syntax was chosen for MAXScript for the following reasons: It is simpler and easier to use, particularly if a function has many optional keyword arguments. The language is used in a command-line window within 3ds max. Therefore this form is similar to other command or shell languages that users might be already know.

676

Chapter 5

Names, Literal Constants, and Expressions

All 3ds max objects, including geometric objects, splines, materials, and so on are created using function calls. The name of the object creation function is the objects class name. For example:
standard() bend angle:45 box height:20 width:40 -- create a standard material -- create a bend modifier -- create a box

See also
Positional and Keyword Arguments (p. 676) Function Precedence (p. 677) Code Layout (p. 678) Special Notes about Function Calls (p. 678) Creating Functions (p. 699)

Positional and Keyword Arguments

A function can take two kinds of arguments: Positional Arguments: If you call a function that takes positional arguments, you must specify those arguments first and in the correct order. Positional arguments correspond to the function arguments in most programming languagesthey are required and have a fixed number and order. Keyword Arguments: You write keyword arguments as a keyword:value pair, and they can appear in any order after the positional arguments. Functions can use some or all of their keyword arguments as optional arguments. If you call a function and dont supply optional keyword arguments, they will have either the default value supplied by the called function, or the special value unsupplied when first referenced in the called function.

Optional keyword arguments are useful in command languages where commands can have many options. They are particularly useful within 3ds max where most functions have numerous optional keyword arguments. For example, all scene object creation functions take optional keyword arguments for their creation parameters. As there are sometimes more than 100 arguments to these functions, using positional arguments would simply be unworkable. As an example of positional arguments, the syntax for the print function is:
print <value> [ to: <file> ]

<value> is a positional argument, and is required. to: <file> is an optional keyword argument, where to is the argument keyword and <file> is the argument value. If the to argument value is unsupplied, MAXScript outputs <value> to Listener. Otherwise, MAXScript outputs <value> to the file specified by <file>.

Function Precedence

677

As another example, you can create a sphere object in the 3ds max scene with no arguments:
sphere()

Or, you could specify just one argument:

sphere radius:23

Or, you can specify more optional arguments:

sphere segs:20 smooth:on radius:15 hemisphere:0.5 mapcoords:on

For those keyword arguments not specified when creating 3ds max objects, default values are used. The default value used for each keyword argument is shown in the descriptions of the object classes.

Function Precedence
A <function_call> has a lower precedence than an <operand>, but it has a higher precedence than all the math, comparison, and logical operations. This means you have to be careful about correctly parenthesizing function arguments. For example:
sin x + 1

is evaluated as:
(sin x) + 1

In general, you have to put arguments that are expressions inside parentheses, as in:
sin (x + 1) atan2 (y - 1) (z - 1)

This rule has one exception, the unary minus. It is recognized as one type of <operand> you dont have to parenthesize. For example:
sin -x

is interpreted as:
sin (-x)

678

Chapter 5

Names, Literal Constants, and Expressions

Code Layout
The end-of-line layout rules, as described in the Source Code Layout and Continuation Lines (p. lvii) topic, mean an end-of-line indicates the end of a function call if the line ends at the end of a complete argument. You cannot simply break up a function call with many arguments into several lines, because each line becomes a separate expression, almost certainly causing an error. Use the \ continuation character in this situation:
foo = standardMaterial twosided:on shininess:34 diffuseMap:baz opacityMap:bar bumpMap:boo \ \ \

Special Notes About Function Calls

Functions in MAXScript are just another value that can be stored in variables and arrays, and passed to other functions as arguments. Such functions are sometimes called higher-order functions. All built-in functions, and functions that MAXScript defines based on the 3ds max object classes, are values stored in system global variables of the same name as the function. When you define a scripted function, the function value is placed in a variable with the same name as the function. You can use the value in these variables and work with them as you would with other values, such as storing them in an array or passing them as arguments. Because the function name is a variable that simply yields the function itself, functions that take no arguments need to be called in a special way. For example, if you want to call a function get_current_target that takes no arguments, you can not simply write:
t = get_current_target

This stores the get_current_target function value in variable t, rather than storing the result of executing function get_current_target. Instead, you must use the () nullary call operator:
t = get_current_target()

The function to be called is defined as an <operand> in the syntax for function calls. This means that it can be an expression that is evaluated to get the function to call. For example:
(if a > b then sin else cos) x handlers[x] $box01 [1,1,1] -- conditional function choice -- get the function out of an array

Special Notes About Function Calls

679

Block-Expressions
Block-expressions are the basic constructors for structured code. They allow you to group a sequence of expressions and evaluate them in sequence as though they were a single expression. The syntax for <block_expr> is:
( <expr> { (; | <eol>) <expr> } )

That is, a parenthesized sequence of expressions with each <expr> separated by either a line break or a ; semicolon. MAXScript also allows empty block-expressions, (). This is useful when incrementally building code in order to place an empty expression in a path to be filled in later. When evaluated, empty expressions yield the value undefined. Examples:
( d = centre.x^2 - (p.x^2 + p.y^2) newz = if d > 0 then sqrt d else p.z print newz ) if x < y then (print x; print y; u += 10; print u)

You can use a mixture of line breaks or semicolons:

( print x; print y u += 10 print u; print z )

Because a block-expression is an <operand>, you can insert a block-expression anywhere you can put an <operand>. This is unlike most languages which limit where you can put blocks of code to only a few places. Further, because all constructs are expressions in MAXScript, a block-expression yields a value defined to be the last <expr> in the block. This allows you to use a nested sequence of expressions to compute an operand for some operation:
$box.pos.z = ( d = x^2 - y^2 if d > 0 then sqrt d else z )

Here, the result of the block-expression is the result of the final if expression, which is then assigned to $box.pos.z. Because the item in parentheses can be any <expr>, you can turn any construct in MAXScript into an operand by putting it in parentheses. This allows you to write the following example, in which the operand to be indexed is the conditional result of an if expression:
(if a > b then c else d)[n + 1]

680

Chapter 5

Names, Literal Constants, and Expressions

As described in the Scope of Variables (p. 646) topic, top-level open parentheses in a script file or in the Listener create a new variable scope. Any block-expressions with the top-level block-expression do not create a new variable scope, even if the variable is explicitly declared as local in the inner block-expression. A variables scope extends into any block-expressions within the variables scope. If you declare a variable as local in a scope, the newly declared local variable hides any outer variables with the same name. Any reference to that variable name later in the local variables scope refers to the new local variable. At the end of the local variables scope, the next outer variable becomes visible again. This is shown in the following script: Script:
a=1 ( local a=2 ( local a=3 ) print a ) a

Output:
1 3 3 1 ----result output result result of of of of line 1 line 7 block-expression lines 2 to 8 line 9

Any variable names used in a block-expression which have not been created at a higher scope level are implicitly declared as local in the present scope. This can result in unexpected execution results for scripts that are not set up correctly. For example, consider the following script:
(b=bend();addmodifier Objs b) -- create bend modifier and apply to objects b.angle=10

The first time you execute this script, the following error message is generated:
-- Unknown property: angle in undefined

If you execute the script again, it works properly. The reason is there are actually two variables with the name b one is local to the block-expression and contains the bend modifier value, and the other is global and has the value undefined. During the second execution, global b exists, so the block-expression does not implicitly declare a new variable b, rather it uses the global variable b. When writing scripts, it is also a good programming practice to explicitly declare as local all variables unless you really want them to be global variables. There are several reasons for this practice: All the variable names used in the block or function will be together, which makes it easier to find the variable names and helps prevent using incorrect names in the script. If more than one script is executing at the same time (for example, you are running a scripted utility and have a scripted controller in the scene) and both scripts use the same global variable

Special Notes About Function Calls

681

name, the two scripts can interfere with one another. This can cause apparently random failures of one or both scripts. You are sure you are using the correct variable in the event that a variable with the same name has already been declared at a higher scope, and you wont inadvertently change the higherlevel variables value. Values of variables explicitly defined as local are displayed in error call stack trace-backs. In 3ds max R2.5, if a 3ds max class, a MAXScript method, or a MAXScript read-only global variable has the same name as an implicitly declared local variable, a MAXScript runtime error will be generated if an assignment to that variable name occurs. Since the variable name already existed with a global scope, an implicitly declared local variable was not created. Since one or more new 3ds max classes will be created by any third party plug-ins the user has loaded, you were not be able to tell ahead of time if a variable name was a global variable name. In 3ds max 4, if the MAXScript compiler detects that the first reference to such a variable is an assignment, it will implicitly declare a local variable, rather than leaving it as a reference to a read-only system global. For example, executing the following expression in 3ds max R2.5 would result in a value of Box, since Box is a 3ds max object class. In 3ds max 4, MAXScript detects that the first use of variable box is an assignment and creates an implicitly declared local variable box. The result of this expression in 3ds max 4 is the value undefined.
(if false do box=10;box)

Context Expressions
Context expressions are the parts of the MAXScript syntax that are most specifically designed for use with 3ds max. Context expressions are mirrors of some of the most important abstractions in the 3ds max user interface - the animate button, the time-line slider, the working coordinate system, and so on. Context expressions make it as easy to create animation and perform geometry manipulation in MAXScript as these tools do in the user interface. The basic idea for this is a prefix is supplied that sets up a context for the evaluation of its expression. For example:
animate on ( move $box01 [20, 0, 0] rotate $box02 45 x_axis )

682

Chapter 5

Names, Literal Constants, and Expressions

This effectively turns on the animate button for the duration of its block-expression. The move and rotate will automatically generate keyframes, just as would happen if you turned the animate button on in the 3ds max user interface and moved objects around. Another kind of context expression has a prefix for setting the current animation time, as though you had moved the time slider. If we mix the two forms together, like this:
animate on ( at time 0 $box01.position = [-100, 0, 0] at time 100 $box01.position = [100, 0, 0] )

you can see how to do keyframe animation in MAXScript. The full syntax for <context_expr> is:
<context> { , <context> } <expr>

where <context> is one of:

[ with ] animate <boolean> at level <node> in <node> at time <time> [ in ] coordsys <coordsys> about <center_spec> [ with ] undo <boolean>

Examples:
-- randomly jiggle each object in the selection around + or - 20 units in coordsys local selection.pos = random [-20,20,20] [20,20,20] -- rotate all the boxes 30 degrees about the y_axis of $foo about $foo rotate $box* 30 y_axis -- generate a keyframed animation of $foo randomly chasing $baz animate on for t in 0 to 100 by 5 do at time t $foo.pos = $baz.pos + random [-10,-10,-10] [10,10,10]

The individual context expressions are described in the following topics: animate (p. 683) at level, in (p. 684) at time (p. 685) coordsys (p. 685) about (p. 686) undo (p. 687)

animate

683

See also
Cascading Contexts (p. 688) Nested Contexts (p. 688) Sticky Contexts (p. 689)

animate
The [ with ] animate <boolean_expr> context corresponds to setting the Animate button in the 3ds max user interface. Placing an expression, operation, or block-expression within an animate on context causes keyframes to be generated whenever an animatable property of a 3ds max object is changed, regardless of the actual state of the Animate button. Likewise, placing an expression within an animate off context prevents keyframes from being generated whenever an animatable property of a 3ds max object is changed. Expressions that change an animatable property of a 3ds max object, and are not within an animate context, will generate keyframes only if the Animate button is on. Setting the animate context on or off does not affect the state of the Animate button. The state of the Animate button can be queried and set using the animButtonState global variable. The user can be prevented from changing the state of the Animate button using the animButtonEnabled global variable. Examples:
loadheight=obj.pos.z -- lift object, no key generated animate off obj.pos.z=loadheight+LiftHeight -- Create key at time tStart to keep object lifted until that time. -- If tStart != 0, a key will also automatically be created at frame 0. -- Then create a key at time tEnd to drop the object with animate on ( at time tStart obj.pos.z=loadheight+LiftHeight at time tEnd obj.pos.z=loadheight )

684

Chapter 5

Names, Literal Constants, and Expressions

at level, in
The at level <node> and in <node> contexts set the specified node to be the effective root for any pathnames specified, or scene objects created, in the context. These contexts automatically prefix the specified node to any pathnames in the context. They also set the specified node to be the parent for any scene objects created in the context. To be able to use pathnames within level contexts to name objects anywhere in the scene, you can override the current working level by using a rooted pathname. A rooted pathname has an extra / before the first-level name and indicates start at the actual root of the object tree. For example:
scale $/baz/* [1,1,2]

operates on the object baz in the actual top level, not just as a child of the current working level. You can also use this rooted pathname form to force a pathname to only consider top-level objects when you name a single object. For example:
$foo

looks throughout the whole scene, at all levels for an object named foo, but,
$/foo

will only look for a top-level object named foo. Examples:

in $mannequin01...LClav...hand $mannequin01.spine.LClav.arm.hand ( rotate $thumb1 15 y_axis rotate $finger11 10 y_axis PalmCenter=$finger21.parent.pos PalmCenter+=(LHandPos-$finger21.pos)/2. dummy name:palmLink pos:PalmCenter -- set context to hand ----------rotate hands child thumb rotate hands child first finger get hands position calculate center of palm create a dummy there, dummy is a child of the hand

) in $dummy ( sphere name:ear1 pos:[10,10,10]

-- create automatically as -- children of $dummy

sphere name:ear2 pos:[-10,10,10] scale $foo/* [1,1,2] -- look for foo as a child -- of $dummy )

at time

685

at time
The at time <time> context corresponds to the 3ds max time slider. Any animatable property references will yield their interpolated values for the specified time. If the Animate button is on, or the script is also in an animate on context, keyframes are generated at the specified time when an animatable property of a 3ds max object is changed. Setting an at time context does not affect the 3ds max time slider. The time associated with the time slider can be queried and set using the sliderTime global variable. Examples:
-- generate a keyframed animation of $foo randomly chasing $baz animate on for t in 0 to 100 by 5 do at time t $foo.pos = $baz.pos + random [-10,-10,-10] [10,10,10]

coordsys
The [ in ] coordsys <coordsys_spec> context corresponds to the current reference coordinate system list in the main 3ds max toolbar. Prefixing an expression, operation, or block-expression with a coordsys context causes 3D coordinate operations to be interpreted in the specified coordinate system. Moving, scaling, or rotating objects, or setting transform-related properties within a coordsys context operate in relation to the given coordsys. Accessing coordinate properties such as position, center, rotation axis, and so on, within a coordsys context causes those values to be delivered relative to the given coordsys. The following forms are supported:
[ in ] coordsys world

use the world space coordinate system

[ in ] coordsys local

use the objects local coordinate system

[ in ] coordsys parent

use the objects parents coordinate system

[ in ] coordsys grid

use the active grids coordinate system

[ in ] coordsys screen

use the currently active viewports coordinate system

[ in ] coordsys <node>

use the specified nodes local coordinate system - this is equivalent to the pick coordinate system capability in the 3ds max user interface
[ in ] coordsys <matrix3>

use the coordinate system specified by the given 3D matrix

686

Chapter 5

Names, Literal Constants, and Expressions

Examples:
-- randomly jiggle each object in the selection around +/- 20 units in coordsys local selection.pos = random [-20,20,20] [20,20,20] -- rotate objects in parents coordinate system in coordsys parent rotate selection (EulerAngles 0 0 90)

about
The about <center_spec> context is the MAXScript equivalent of the rotate/scale transform center list on the main 3ds max toolbar. It defines the center point about which any scale or rotation operation is performed within its context. Note that, like the center list in 3ds max, this sets only the center point for the operation, not the axis. The axis is taken from the current working coordinate system set using the coordsys context expression:
about selection

rotates/scales about the center of the current selection

about pivot

rotates/scales about each objects pivot point

about coordsys

rotates/scales about the center of the current working coordinate system set using the coordsys context expression
about <node>

rotates/scales about the pivot point of the given object

about <matrix3>

rotates/scales about the center of the coordinate system specified by the given 3D matrix
about <point3>

rotates/scales about the given point with coordinate system and axes taken from the current working coordinate system. Examples:
-- rotate all the boxes 30 degrees about the y_axis of $foo about $foo rotate $box* 30 y_axis -- rotate each planet 45 degrees around its parent in coordsys parent about coordsys rotate $planets* 45 z_axis

undo

687

undo
The undo <boolean> context provides control over whether scripted scene changes will be undoable. By default, the operations performed in MAXScript are undoable. This means that scene-modifying commands typed in the Listener are undoable by default. Making this a context-controlled activity allows you to decide when the undo overhead is to be taken. Example:
undo on ( delete $box* delete $sphere* clearUndoBuffer() )

The undoable operations appear as items labeled MAXScript in the 3ds max Undo menu. It is important to note that the granularity of the undoable operations is at the level of entire undo clauses. In the previous example, one entry is added to the Undo stack containing both deletes as a single operation. Choosing undo for this entry in the Undo menu causes both deletes to be undone. Therefore, you can control the granularity of an undo by choosing the appropriate undo block expression groupings. You can invoke an undo from MAXScript with the max command:
max undo

When you script very large scene changes, you should consider turning undo off as it is quite easy to fill up the Undo stack and consume substantial amounts of memory. Disabling undo can improve performance in this situation. If the actions your script performs could interfere with entries already in the Undo stack, you should explicitly clear the Undo stack before enabling undo. An entry in the Undo stack generally expects the scene to be in the state it was when the entry was placed in the Undo stack. If you interrupt the storing of Undo stack entries, and modify the scene in an incompatible way (such as deleting an object that an entry assumes is still around), a 3ds max crash is likely if you then try to perform an undo. Using the following functions you can control the undo and scene save states in 3ds max:
clearUndoBuffer()

empties the Undo stack, both providing a way to reset the undo state and another way to control the save-changes requester.
setSaveRequired <boolean>

lets you set the 3ds max system dirty flag. If this flag is set or there are entries in the Undo stack, you are asked if you want to save the scene file on a File > New or File > Reset.
getSaveRequired()

returns true if the 3ds max system dirty flag is set to true or if the Undo buffer is not empty. If the Undo buffer if not empty, this function will still return true, even if you just called setSaveRequired false.

688

Chapter 5

Names, Literal Constants, and Expressions

Normally, if there are entries in the Undo stack when the scene is closed, 3ds max will prompt with a save-changes requester. In some cases, where you are controlling undo in MAXScript, you may want to force the need for a save-changes prompt.

Cascading Contexts
You can cascade a set of context prefixes, optionally separated by commas, onto one subject expression, effectively applying all the contexts (in order) to the subject expression. For example:
animate on, at time (t+1), with undo off, coordsys local ( ... )

All the context forms are true expressions, yielding the value of their subject expression, so:
pos0 = at time 35 $box01.position pos1 = at time 75 $box01.position

assigns the box01 position at times 35 and 75 to variables pos0 and pos1. This is particularly useful with the at time context, as you can very easily do across-time computations. The operand to an at time context can be any valid time value (numbers are taken as frames for convenience), including sub-frame times down to the tick level. The animation system in 3ds max will interpolate animated parameters at these fine levels so you can easily do sub-frame simulation computations.

Nested Contexts
All context expressions remember the prior setting of the context when they are set, and restore the original setting when the expression completes. Therefore, you can nest context clauses in any way you want, including contexts of the same type to override an outer setting. Example:
with animate on, ( move ... rotate ... animate off ( move ... rotate ... ) scale ... ... ) at time t -- all these place keys -- turn off animate for a bit -- working maneuvers, these dont effect animation -- animate on is restored here -- place keys again

Sticky Contexts

689

Further, all the contexts are dynamically scoped . Any code inside a context expression, any functions that code calls, and functions they call down to any level, are executed in the current prevailing context. So, a function can move an object and place keyframes at a certain time when called from one client and do no keyframing when called from another client, depending on how the callers have set up the contexts. Of course, the called function can explicitly set its own contexts if it wants to, overriding those that may have been set up by the caller.

Sticky Contexts
You can force the settings of contexts such as coordsys, animate, time, and so on, to be sticky. The settings will stay active for any code execution that follows, up until the point you change them or override them with a context prefix for an expression. This is particularly useful when working in the Listener, allowing you to set a context and then perform several interactive operations in that context without prefixing each with the desired context construct. Establishing a sticky context is accomplished with the set construct:
set <context>

where <context> is one of the MAXScript context prefixes: animate, time, in, coordsys, about, level, or undo. Example:
set animate on set time 30f move $foo [80,0,0] scale $baz [1,1,3] $bar.bend.angle += 23 ... set animate off set time off

This turns animate on and sets the current time to frame 30 after which any number of interactive operations can be performed that will generate animation at frame 30. The modes are then returned to default. As shown in this example, certain the MAXScript contexts permit syntactic variants to make the set construct read clearly. In particular, these are:
set time <value> | off set level <node> -- variant of at time <time> -- variant of at level <node>

The time context can be set to off, signifying the current value of the 3ds max time slider is to be used. All the set constructs are expressions that yield the context setting that was in force at the time the new context was set. This allows you to simulate the standard nested forms of these constructs by storing the old context in a variable and using that to restore the context later. For example:
oc = set coordsys parent rotate $foo (quat 30 z_axis) ... set coordsys oc -- remember old coordsys

-- restore it

690

Chapter 5

Names, Literal Constants, and Expressions

You can also force several of the contexts back to their default states by specifying #default as their parameter. The set constructs for which you can specify #default are: animate, in, coordsys, and level. When using the set undo on construct to enable the undoing of scripted changes in the Listener, undo granularity is a top-level expression. Every time you evaluate an expression or sequence of selected expressions with the ENTER or Number-Pad ENTER key, a single entry is added to the Undo stack.

Chapter 6:

Controlling Program Flow

MAXScript has several <expr> expression forms used to explicitly control the flow of execution. They are:
<if_expr> <case_expr> <do_loop> <while_loop> <for_loop> <loop_exit> <try_expr>

These expression forms correspond to the standard control constructs found in many programming languages. Each is described in its own topic: If Expression (p. 692) Case Expression (p. 693) While and Do Loops (p. 694) For Loop (p. 694) Loop Exit (p. 697) Try Expression (p. 697) Additionally, there are several constructs for implicitly controlling program flow. The when construct is used for scripting general change handlers, so you can write scripts that respond to user operations such as object moves, vertex edits, object deletions, name changes, and so on. Callback mechanisms are used to have a function called when certain specific events occur. See the Change Handlers and When Constructs (p. 1650) topic for more information. The on construct is used when scripting rollouts or tools or plugins, so the script can respond to events, often user-generated, in those constructs. See the Utility and Rollout Properties, Methods, and Event Handlers (p. 1474) topic for more information.

692

Chapter 6

Controlling Program Flow

If Expression
The if expression is used to conditionally execute an expression based on the result of a boolean test expression. The syntax for an <if_expr> is one of:
if <expr> then <expr> [else <expr> ] if <expr> do <expr>

Examples:
if a > b do (print d; print e) a = (if d == 0 then 0 else a / d)

The first <expr> is a test expression that must evaluate to true or false, such as a comparison or logical expression. If the result is true, the then or do <expr> is evaluated and its value is returned as the result of the <if_expr>. If the result is false, the optional else <expr> is evaluated and its value is returned as the result of the <if_expr>. If there is no else or the do form is used, the <if_expr> returns the value undefined. The do form is provided particularly for use during interactive sessions in the MAXScript Listener. When you enter expressions for immediate evaluation into the Listener, MAXScript determines if your expression is complete and then evaluates it. If you use the optional else form in the Listener and you want to omit the else <expr>, MAXScript continues to wait and see if you enter an else <expr>. The line break after the then <expr> is legal and does not cause MAXScript to evaluate the current line right away. As an example, if the following script is entered in Listener, the first line will not evaluate until you enter the second line:
if match x y then print x print hello

When you use the optional else form inside a block or another expression, MAXScript can determine from the code that follows it if you omitted the optional else. Use the do form for if statements without an else as top-level commands in the Listener:
if match x y do print x

As described in the Expressions (p. 667) topic, anywhere you can write an <expr> expression, you can write any construct in MAXScript. In statement-based languages, there is usually one syntax for if statements and a separate one for conditional expressions. In MAXScript, a single syntax is used for both cases. For example, the following two lines of code are both valid, and their meaning should be obvious:
if a > b then print c else print d x = if a > b then c else d

You can also write the following line, containing a nested if expression and a nested assignment, which is itself an expression:
x = if (if a > b then c else d) < e then f else (g = 23)

Case Expression

693

Case Expression
The case expression is used to select an expression to be evaluated from a set of labeled expressions based on a test value compared against the labels. Only the first expression whose label matches the test expression is evaluated. All labels must be comparable to the test expression. Labeled expressions can be block-expressions, so you can use the case expression as a case statement, choosing between blocks of code to execute. The syntax for <case_expr> is:
case [ <expr> ] of ( <cases> )

where <expr> is the test expression and <cases> is a sequence of labeled expressions:
<factor>: <expr> default: <expr>

Examples:
new_obj = case copy_type.state of ( 2: copy $foo 3: instance $foo default: reference $foo )

A special label, default, can be optionally used to tag the expression that will be evaluated if no other labels match the test expression. If the default label is not used, and no label matches the test expression, the case expression returns a value of undefined. The labels are <factors> - elements such as number literals, name literals, string literals, variables, or block-expressions. When a case expression is evaluated, the test expression is evaluated once, then each label expression is evaluated in order until one is found that compares equally to the test expression value. The expression it labels is then evaluated and this becomes the result of the case expression. No further labels are evaluated or tested. The test expression is optional. If it is not supplied, the labels are expected to be Boolean values or expressions, and the first label evaluated as true determines the chosen case. In this variant, it is common to use expressions as labels, so be sure to parenthesize them. For example:
case of ( (a > b): (b < c): (c <= d*3): default: )

print a is big print b is little ... ...

694

Chapter 6

Controlling Program Flow

While and Do Loops

while and do loops are used to repeatedly execute an expression until a test expression evaluates as false. The while loop and do loop are simple variants of one another. The syntax is:
do <expr> while <expr> while <expr> do <expr>

Both loops repeat the do <expr> as long as the while <expr> evaluates to the value true. The do form evaluates the do <expr> at least once, evaluating the test expression at the end of each loop. The while form evaluates the test expression at the start of each loop and may not loop at all. Both forms return as their value the result of the do <expr> from the last successful loop iteration. The while form will return the value undefined if the test expression immediately returns false. Examples:
while x > 0 do ( print x x -= 1 ) while not eof f do print (read_value f) do ( exchanged=false for i=1 to imax do ( j=i+gap if (compare array[j] array[i]) do (swap array[j] array[i]; exchanged=true) ) ) while exchanged

See also
Skipping Loop Iterations (p. 696) Loop Exit (p. 697)

For Loop
The for loop iterates through a range of numbers, time values, or a sequenced collection of values, such as an array or object set. The syntax for the for loop is:
for <var_name> ( in | = ) <sequence> ( do | collect ) <expr>

where <var_name> is the name of the loop index variable that holds the loop value, and <sequence> is the source of values for the loop. The <sequence> can be one of the following:
<expr> to <expr> [ by <expr> ] [where <expr> ] <expr> [ where <expr> ]

For Loop

695

Examples:
for i = 1 to 10 do print i -- sequence numbers for item in table1 do x = x + item.height -- sequence an array for t in 0f to 100f by 5f do ... -- sequence time (given as -- frames, here) bigones = for obj in $box* -- you can sequence pathnames! where obj.height > 100 collect obj -- collect the big boxes into -- an array

The first <sequence> form is the standard number loop, the first <expr> value is the start value, the to <expr> value is the limit value and the optional by <expr> value is the loop value increment. The allowable value types are integer, float and time. If the by value isnt given it defaults to 1. The second form of <sequence> takes a sequencable collection, such as an array (p. 666) or ObjectSet (p. 781), and iterates through all its values, assigning successive elements in the collection to the loop value each time through the loop. MAXScript contains several sequence collections, including PathName values (p. 780), the current selection set, the children of a node, and the stack of modifiers on an object. See also the Collections (p. 773) topic for caveats when using a collection in a for loop. Each <sequence> source form takes an optional where <expr> which must evaluate to true or false. The where expression is evaluated at the beginning of each loop and only executes the loop body for that loop value if the where expression is true. The do <expr> form simply evaluates the body expression once for each value in the sequence. The loop variable is visible to the code in the body expression as though it was declared locally and initialized to the successive loop values each time. When the do <expr> form of a for loop is used as an expression, its return value is always OK. The collect <expr> form gathers the expression values from the loop iterations and stores them in an array, which is then yielded as the value of the overall for loop. This, for example, is a good way to gather procedural selections of objects from a scene. If the where expression is used with the collect form of the for loop, only the values from those iterations for which the where expression is true are collected. This can be used to collect a filtered sub-set of the iterated values. You can also achieve this collection filtering in a for loop that does not use a where expression by yielding the special value dontCollect for those iterations that should not be added to the collection. As described in the Scope of Variables (p. 646) topic, a for loop creates a new scope context. The for loop index variables scope is always the extent of the for loop, even if another variable of the same name already exists. Once the for loop exits, the for loop index variable is no longer accessible. The scope of any variables created in a for loop is always the extent of the for loop. This is shown in the following example:

696

Chapter 6

Controlling Program Flow

Script:
obj=$box01 avg_pos=[0,0,0] offset_pos=[100,100,0] for obj in $* do

( pos=obj.pos-offset_pos

avg_pos += pos ) avg_pos /= $*.count

-----------

new for loop index variable obj created even though a variable named obj already exists, scope is for loop new variable pos created, scope is for loop offset_pos already exists outside for loop, its value will be used avg_pos already exists outside for loop, its value will be used for loop index since variable obj goes out of scope

See also
Skipping Loop Iterations (p. 696) Loop Exit (p. 697)

Skipping Loop Iterations

MAXScript provides a continue construct that allows you to jump to the end of a for, do, or while loop body <expr> and resume with the next loop iteration. Its syntax is:
continue

Examples:
for i=1 to 8 do (if i == 5 do continue; print i) -- prints 1..4, 6..8 while not eof f do ( local line=readline f if line[1] == - do continue line1=parser1 line processobjs line1 ) -----read until reach end of file read in a line if comment, skip to next line call function parser1 call function processobjs

If a continue is executed in a for ... collect loop, the expression result for that loop iteration is not collected in the array of body values. Example:
for i=1 to 8 collect (if i == 5 do continue; i) -- returns #(1, 2, 3, 4, 6, 7, 8)

Loop Exit

697

Loop Exit
MAXScript provides an exit construct for breaking out of for, do, and while loops prematurely, even though the loop test expression is still true. This is often useful to simplify the loop test expression, and still use error or other complex termination tests in the body <expr> of the loop. Its syntax is:
exit [with <expr> ]

Example:
while x < y do ( local delta = x - y if delta <= 0 then exit $foo.pos.x = compute_x (foo / delta) x += 0.1 )

-- time to bail

The optional with <expr> lets you specify what the overall value of the loop expression should be if the loop exits prematurely. If you dont specify an exit value, the loop returns the value undefined upon exit. Exiting a for ... do loop using a with <expr> results in a value of OK. Exiting a for ... collect loop using a with <expr> results in the array of body values collected up to the point of exit.

Try Expression
MAXScript provides simple exception-handling with the try expression, a simplified form of the C++ exception-handling scheme. The try expression lets you bracket a piece of code and catch any runtime errors. This allows you to respond appropriately or take corrective action, rather than let MAXScript halt the execution of your script and print an error message. The syntax for the try expression is:
try <protected_expr> catch <on_err_expr>

The <protected_expr> is executed and any errors that occur are trapped and the <on_err_expr> is executed. If the <protected_expr> is a block-expression, the blockexpression stops executing at the point of the error. If there are no errors in the protected expression, the <on_err_expr> is not executed. This is a very simple error-trapping scheme, but limited heavily by the fact that you cannot get at any error codes or information about the error that occurred.

698

Chapter 6

Controlling Program Flow

Example:
f = openFile foo.dat try while not eof f do read_some_data f catch ( messageBox bad data in foo.dat results = undefined ) close f

In this example, any errors in reading or processing the data in the read_some_data() function are trapped, then a Message box is displayed and some clean-up is done. This is a good example of a use for the simple error-trapping. There is also an associated function, throw(), which can be used to generate your own runtime error and pass on an error you caught when doing some interim clean-up, or do a non-local jump. It has the form:
throw <error_message_string> [ <value> ] throw()

If you have no intervening catches in your script, calling throw() with error message arguments will cause a runtime error to be signaled and MAXScript will report the error message using its standard error reporting. The optional second argument can be any value you want printed with the error message, perhaps the object involved in the error. This second argument can not be specified if the throw is in the body of a catch() and will generate a compile error if present. If the try/catch is within another try expression, calling throw() will cause the catch expression associated with the outer try expression to be executed. If you have no intervening catches in your script, calling throw() will cause MAXScript to continue running the script from just after the topmost set of parenthesis surrounding the try/catch, or will stop the currently running script if there are no parenthesis surrounding the try/catch. If you want to catch an error, perhaps to do some clean-up processing, and then pass the error on to outer handlers or MAXScript for error reporting, you can call throw() with no arguments. This throws the current error again and must only be done inside a catch expression. For example: Script:
try ( i=10 try ( i.x=1 ) catch ( print Bad Error try (i.pos=[0,0,0]) catch (throw())

-- will generate a run-time error ----error message printed will also generate a run-time error throw() will cause outer catch to execute

) ) catch (print Really Bad Error Occurred) -- error message printed

Chapter 7:

Creating Functions

Functions are defined in MAXScript using the function definition expression. The syntax for <function_def> is:
[mapped] (function | fn) <name> { <parameter> } = <expr>

in which <name> is the name of the function. The optional sequence of <parameter>s can be one of:
<name> <name>: [ <operand> ] -- keyword parameter with -- optional default value

and the <expr> after the = (equal sign) is the body of the function. The function <name> is actually used to name a variable into which a value representing the function is placed. When you call a function by using its name, you are accessing its definition in a variable of that name. The scope of the function name variable is the current MAXScript scope. The parameters for a function are either positional or keyword. Positional parameters are defined with a simple <name> and must be placed before any keyword parameters. Keyword parameters have a : (colon) after the name and an optional default value. The caller of the function can optionally supply keyword arguments in any order. Those not supplied will be set to the default value given, or the special value unsupplied if a default value is not given. Using the mapped prefix on a function definition marks this function to be automatically mapped over collections. This means the function will be automatically called repeatedly on the elements of a collection if the collection is given as the first argument to the function. This allows you to define scripted functions that behave in a similar manner to the mapped built-in functions, such as copy, delete, move, and so on, which can be applied to an object set, path name pattern, or array. See the Collections (p. 773) topic for more information.

700

Chapter 7

Creating Functions

Examples:
function add a b = a + b fn factorial n = if n <= 0 then 1 else n * factorial(n - 1) mapped function rand_color x = x.wireColor = random (color 0 0 0) (color 255 255 255) fn starfield count extent:[200,200,200] pos:[0,0,0] = ( local f = pos - extent / 2, t = pos + extent / 2 for i = 1 to count do sphere name:star \ radius:(random 0.1 2.0) \ position:(random f t) \ segs:4 smooth:false )

A scripted function returns as its value the value of the body <expr>. If the body is a blockexpression, the function evaluates to the value of the last expression in the block. A function can be called recursively (that is, the function can call itself), as is the factorial function in the previous examples. If you need to locate the source of a scripted function, you can use the showSource() function. It displays a script Editor containing the source file in which the function was defined and positioned at the functions definition. The form is:
showSource <fn>

This is useful for browsing definitions if you are working on many scripted functions, that were perhaps defined in several script files loaded with fileIn() or Run Script in the MAXScript utility.

See also
Function Variables (p. 701) Function Parameters (p. 702) The Return Expression (p. 705) Special Notes about Function Calls (p. 678)

Function Variables

701

Function Variables
When you define a function, the following events occur: The function definition is evaluated, creating a function value. The function <name> is used to declare a new variable with that name. The function value is placed into that variable. The function value is returned as the result of the function definition expression.

Because the function itself is a value stored in a variable, you not only can call the function through the function name variable. By simply referring the functions variable you can also assign the function value to another variable, store it in an array, or pass it as an argument to another function. Example:
-- some 3D surface functions fn saddle x y = sin x * sin y fn sombrero x y = cos (x^2 + y^2) / print (saddle 1 1) -surface_functions[1] = saddle -surface_functions[2] = sombrero z = (surface_functions[i]) 10 10 --build_math_mesh sombrero ---

(1 + (x^2 + y^2)) try one out store the functions in an array call one of them from within the array pass one in to a higher-order function

The scope of a function variable is the current MAXScript scope context. The variables used inside a function have a local scope, unless the variable was already defined at a higher scope or is declared as global in the function. An exception to this is the function parameter variables, which always have a local scope. When writing scripts, it is good programming practice to explicitly declare your local and global variables. Implicit declaration is provided as a short-hand, typically used when working in the Listener interactively or developing short scripts. When developing extended scripts, explicitly declaring variables can reduce errors and improve readability of the code. It is also recommend that you declare as local all variables unless you really want them to be global variables. The reasons for this are described in the Scope of Variables (p. 646) topic. If a function variable is assigned to another variable, a reference to the function value is stored in that variable. Thus while a function variable may no longer be in scope, the function itself still is if the variable it is assigned to has a scope that extends outside the current MAXScript scope context.

702

Chapter 7

Creating Functions

Examples:
fn funcA which = ( if which == 1 then fn saddle x y = sin x * sin y else fn sombrero x y = cos (x^2 + y^2) / (1 + (x^2 + y^2)) ) myfunc=funcA 2 z=myfunc 10 10

In the above example, the scope of variables saddle and sombrero is local to funcA, and the variables are out of scope outside the function. The return value of funcA is either the function value saddle() or sombrero(), and is assigned to variable myfunc. As also can be seen in this example, you can define a function within any expression.

See also
Scope of Variables (p. 646) Function Calls (p. 675)

Function Parameters
The parameters to a function are implicitly declared as local variables at the head of the function body, and are initialized with the arguments given by the caller. The parameters have a scope that extends to the end of the function body <expr>. They can be assigned to and hidden by nested local variables with the same name, as can other local variables. Keyword parameters can be given default values in the function definition, implicitly making them optional to the caller. If the caller does not supply one of the keyword arguments, it is initialized to the default value upon function entry. The default values are specified after the : (colon). If a keyword parameter is defined with no default value and is not supplied by the caller, it is initialized to the special value unsupplied. You can check for this value in the body of your function and handle missing required keyword argument errors accordingly. Example:
fn foo a b: c: d: = ( if c == unsupplied then print Wheres the c: argument?? ... )

As described in the Reference Assignment (p. 653) topic, MAXScript uses an assignment called reference assignment. In a function, each parameter variable contains a reference to the value passed to the function by the caller. Assigning to a parameter variable places a new reference in the parameter variable, and has no effect on the variable values in the caller - it is an entirely local action. An exception to this is if the parameter value is a compound value such as an 3D Point, string, or array, and you assign a new value to one of the components of the compound value. In this case, the

Function Parameters

703

variables reference does not change, and the changed compound value will still be referenced by the variable in the caller. While in some cases you may want a function to return multiple values, it typically is not a good practice to do this by assigning to the components of a parameter variable compound value. To manipulate a compound value passed as a parameter, a compound value needs to be created in the caller and passed to the function, which can give results as shown in this example: Script:
fn getXYZset val = ( val.x=random -100 100 val.y=random 100 100 val.z=random val.x val.y ) ( v1=[0,0,0] v4=v1 getXYZSet v1 format v1= %; v4= %\n v1 v4 getXYZSet v4 format v1= %; v4= %\n v1 v4 )

Output:
getXYZset() v1= [-84,100,78.1224]; v4= [-84,100,78.1224] v1= [10,100,18.6575]; v4= [10,100,18.6575] OK ----result output output result lines 1 to 5 line 10 line 12 lines 6 to 12

Note that it appears the value for both variables v1 and v4 are set in the calls to getXYZset, even though only one variable is being passed. The reason for this is in line 8 variable v4 is initialized to the value of v1. What actually occurs is that in line 7 a reference to a Point3 value of [0,0,0] is created, and this reference is stored in v1. In line 8, that same reference is retrieved from v1 and assigned to v4. Rather than storing two different values, both v1 and v4 reference the same value. When you set the components of the compound value in getXYZset, the reference to the Point3 value is not being changed, and both variables still reference that value.

704

Chapter 7

Creating Functions

The proper way to return multiple values from a function is to have the return value of the function be an array or a structure. For example: Script:
fn readDataFile filename = ( f=openfile filename data=#() avg=0 nVals=0 while not eof f do ( val = readvalue f append data val avg += val nVals += 1 ) close f #(data,(avg/nVals)) ) result=readDataFile c:\\datafiles\\run1.dat data=result[1] avg=result[2]

Normally, if you are writing a function that is operating on a compound value which is passed as a parameter, you should make a copy of the value. This prevents the value in the caller from inadvertently being changed. For example: Script:
fn uppercase instring = ( local upper, lower, outstring upper=ABCDEFGHIJKLMNOPQRSTUVWXYZ lower=abcdefghijklmnopqrstuvwxyz outstring=copy instring -- operate on copy of instring for i=1 to outstring.count do ( j=findString lower outstring[i] if j != undefined do outstring[i]=upper[j] ) return outstring )

The Return Expression

705

The Return Expression

As with the loop constructs, you can break out of a function body block-expression prematurely in MAXScript, and return a result without evaluating the remaining portion of the block. For this purpose, you use the return expression:
return <expr>

If a return expression is evaluated in the course of running a function body, the function exits immediately and yields the value given in the return <expr>. Note that it is unnecessary and somewhat inefficient to place a return expression at the end of a function body to return an expression value. Instead, simply place the result expression at the end of a function body. If a return <expr> is used in a mapped function and a collection is passed as the first argument to the function, the value returned will be OK rather than <expr>. As a special case, you can exit a script controllers script using a return <expr>. Example:
fn find_root twod_fn = ( local root, last_root while true do ( ... if abs(root - last_root) < epsilon then return root ... ) )

706

Chapter 7

Creating Functions

Chapter 8:

Structure Definition

You can create your own compound values in MAXScript using structure definitions. Structure definitions let you define the layout of new classes of values that you can then create and work with in your code. The syntax for a structure definition is:
struct <struct_name> ( <member> { , <member> } )

where each <member> can be one of:

<name> [ = <expr> ] <function_def> -- name and optional initial value

Example:
struct person (name, height, age, sex)

defines a new person class. You create values of this class using the person constructor:
bill = person name:Bill height:72 age:34 sex:#male

creates an instance of the person class, storing the instance in variable bill. Member name is initialized to the string value Bill, height to the integer value 72, age to the integer value 34, and sex to the name value #male.
joe = person name:Joseph sex:#male

creates an instance of the person class, storing the instance in variable joe. Member name is initialized to the string value Joseph and sex to the name value #male. Since the height and age members are not assigned values, and do not have optional initial values supplied in the structure definition, they default to a value of undefined. You access structured values using the standard property accessing syntax in MAXScript:
bill.age -> 34 joe.age -> undefined joe.age = bill.age - 4

Structure definitions are useful as an alternative to arrays when you have a fixed, usually small number of independent components and the code to work with them is much clearer when they can be referenced by property name, rather than by index number.

708

Chapter 8

Structure Definition

As with function definitions, a structure definition actually creates a value to represent the definition and stores it in a variable of the same name as the structure. You can therefore store the structure definitions in other compound objects or pass them as function arguments The classOf() function returns this structure definition value when applied to these values, so you can use it to test the definition of structure instances at runtime. For example:
classOf bill -> person

The struct value constructors are just like function calls and take positional argument initializers as well as keyword initializers. The elements of the new struct are filled-in in order from any positional arguments and then by name from any keyword arguments. For example, given the following struct definition,
struct foo (name, age, height, hair=brown)

you can create instances, in several ways:

f1 = foo bill 23 72 f2 = foo age:45 name:sam f3 = foo mary hair:red -- fills in name, age, height in order -- random named initializers -- first name, then keywords

There is one method associated with struct values:

copy <struct>

Creates a copy of the structure. The copy made is what is called a shallow copy - only a copy of the upper-level value itself (that is, the struct value) is created. Copies arent made of compound values stored in the structure, rather the same compound value is stored in both struct values. This can be seen in the following example, where changing a component value of a compound value in a copy of a struct value also changes value in the original struct value: Script:
struct test (pos1, pos2) testval = test [1,2,3] [4,5,6] testval_copy=copy testval testval_copy.pos1.x=10 testval ------define a structure create struct value copy the struct value change component value of a compound value in the copy look at original struct value

Output:
#Struct:test( pos1:<data>, pos2:<data>) #test(pos1:[1,2,3], pos2:[4,5,6]) #test(pos1:[1,2,3], pos2:[4,5,6]) 10 #test(pos1:[10,2,3], pos2:[4,5,6]) -- result line 1

-----

result result result result

line line line line

2 3 4 6

Defining Local Functions in Structures

709

Defining Local Functions in Structures

You can define local functions in structures, providing a convenient mechanism for packaging a set of related functions and avoiding possible name conflicts when many global functions are defined, possibly by several separate scripts. For example:
struct foo ( a, b, c, fn baz n = sqrt (n + 1), fn bar x y = print (x ^ 2 + y ^ 2) )

This defines a structure definition foo with 3 elements named a, b, and c, and two local functions, bar and baz. You can access these functions as properties of either the structure definition value itself or an instance of the foo structure:
p = foo.baz q foo.bar x y f = foo 2 3 4 f.bar x y -- access as property of the structure definition value

-- access as property of the structure instance

Local functions declared in a structure definition can make references to the member data variables defined in the structure, such that when that member function in some instance of the structure is called, the references access the members of that instance. This allows you to initialize and maintain data structures for the structure functions within the structure itself. An example of including functions that use members of the structure is shown in the following script. Script:
struct RandVals ( RndVals=#(), ptr, seedVal, fn generateRV num fromVal toVal = ( if seedVal != undefined do seed seedVal RndVals=for i=1 to num collect random fromVal toVal ptr=1 RndVals ), fn deleteRv = ( RndVals=#() ptr=undefined undefined ), fn getNextRV = ( if Nvals == 0 do return undefined val=RndVals[ptr] ptr += 1 if ptr > RndVals.count do ptr=1 val ), fn sortRV = (sort RndVals),

710

Chapter 8

Structure Definition

fn setSeed val = (SeedVal = val), fn setPointer val = ( if val > 0 and val <= RndVals.count then (ptr=val;true) else false ) ) MyRandomVals= RandVals() MyRandomVals.setSeed 12345 MyRandomVals.generateRV 10 0 100 MyRandomVals.getNextRV() MyRandomVals.sortRV() MyRandomVals.setPointer 1 MyRandomVals.getNextRV() MyRandomVals.deleteRv()

Output:
#Struct:RandVals( -- result of struct def lines 1 to 29 generateRV:<fn>, sortRV:<fn>, RndVals:<data>, deleteRv:<fn>, getNextRV:<fn>, seedVal:<data>, setSeed:<fn>, setPointer:<fn>, ptr:<data>) #RandVals(RndVals:#(), ptr:undefined, seedVal:undefined) -- result line 30 12345 -- result line 31 #(23, 59, 79, 68, 17, 72, 84, 16, 89, 72) -- result line 32 23 -- result line 33 #(16, 17, 23, 59, 68, 72, 72, 79, 84, 89) -- result line 34 true -- result line 35 16 -- result line 36 undefined -- result line 37

In this script, the structure has 3 data members and 6 function members. Note the references to the structure data members in the generateRV() function. In line 30, an instance of the RndVals structure is created and stored in variable MyRandomVals. In line 31, the setSeed() function in the structure instance is called, which initializes the random seed variable by storing the specified value in data member seedVal in the structure instance. In line 32, the generateRV() function in the structure instance is called, which initializes the random number using the seed value specified by setSeed(), sets up and stores an array of random numbers in data member RndVals, updates data member ptr, and then returns the random number array. Local functions defined in structures are not stored in every instance of the structure. The local function is stored once in the structure definition and references to them in the instances refer to their definitions in the structure definition.

Structure Inherited Methods

711

Structure Inherited Methods

All structures inherit from the Value (p. 713) class and so structure instances implement the Value methods print(), format(), classOf(), superClassOf(), isKindOf(), ==, and !=. The copy() method is the only method not inherited from Value that structures implement. It yields a top-level copy of the structure you call it on, meaning that you get a new, separate structure instance containing the same element values as the original and then you can modify that copy independently. The element values are not themselves copies, so for example, if one of the elements was an array, the copy would reference that same array, not a copy of that array.

712

Chapter 8

Structure Definition

Chapter 9:

Values

The Value class is the root class for all MAXScript classes. It supplies methods and operators that any class can use. As described in the Properties, Methods, Operators, and Literals (p. lxiv) topic, each class can specify external interfaces for the class. These external interfaces are broken up into the following categories: Literals: Any literal form for objects of the class. Constructors: The various ways you can create objects of the class. Properties: Accessible parameters for objects of the class. Operators: Defines the math and other symbolic operators that are defined on values in the class. Methods: Defines all the functions you can call for objects of the class.

In the description of each class in MAXScript, each of these external interfaces are documented. In the syntax forms given for methods, operators, and properties, the types of argument or property values are specified using the <type_name> convention, in which type_name describes the type of value that is allowable for that argument or property. You can, of course, use an arbitrary expression for these values, as long as it evaluates to a value of the right type. For example, <boolean> means either the true or false Boolean values. Also indicated for function calls are those that are automatically mapped over collections. This means that the function will be automatically called repeatedly on the elements of a collection if the collection is given as the first argument to the function. See the Collections (p. 773) topic for more information.

714

Chapter 9

Values

Value Common Properties, Operators, and Methods

Operators:
<value> == <value>

compare if equal
<value> != <value>

compare if not equal

<value> as <class>

Converts the value to an instance of given class. See the description for each class for valid conversions. All values can be converted to class String, which yields a string with the printed representation of the value. Methods:
print <value> [ to:<stream> ] [#noMap] -- mappable

where <stream> is
( <filestream> | <stringstream> | <windowstream> )

Prints single value to Listener or optional filestream (p. 763), stringstream (p. 766), or windowstream (p. 767), followed by a line break. If the argument value is a Collection (p. 773), and #noMap is not specified, each value in the collection is printed out on a separate line. If #noMap is specified, the collection value is printed out on a single line. The printed form of all basic data value types, except for BigArray, are directly readable by the readValue() and readExpr() functions, making it simpler to read back in values printed to a file by MAXScript. If the pre-3ds max R3 print forms are required for compatibility with existing scripts, you can set the system global variable options.oldPrintStyles to true.
format <format_string> { <value> } [ to:<stream> ]

Prints one or more values to Listener or optional filestream, stringstream, or windowstream, using the format string as a template. The format string is a string that can contain plain text to print interspersed with the % (percent) metacharacter. Each occurrence of a % is replaced by the printed representation of the successive argument values following the format string. For example:
format name:%, pos:%\n obj.name obj.pos

generates something like:

name: box01, pos: [0, 150.0, 0.5]

format does not automatically append a line break to the output stream, so you can build up a line from several format calls and generally control layout better. An explicit \n newline escape character sequence is needed to place a line break in the output stream. Other escape character sequences are documented in the String Literals (p. 660) topic.

Value Common Properties, Operators, and Methods

715

classOf <value>

Returns the values class. Each type of value has its own class. If the value is a Node value, classOf() returns the class of the world state object (the state of the node at the top of its stack). See the Node : MAXWrapper (p. 820) topic for more information. Note: To avoid a conflict between a user class value in global variable named rollout and MAXScript reserved word rollout which always introduces a rollout definition the class variable name for a rollout is RolloutClass. So, for a rollout foo youd now say if classOf foo == RolloutClass.
superClassOf <value>

Returns the values superclass. A values superclass is the class from which the values class was derived.
isKindOf <value> <class>

Returns true if value has given class or inherits from class.

isStructDef <value>

Returns true if the value is a structure definition

isStruct <value>

Returns true if the value is a structure instance

isController <value>

Returns true if the value is a controller

getHashValue <value> <Integer oldHaskValue>

If the value is one of the supported value types, returns an integer hash value that is a factor of the value and oldHaskValue. If the value type is not supported, returns a value of undefined. The supported value types are: Float Integer String BitArray Point3 Ray Quat AngAxis EulerAngles Matrix3 Point2 Color Arrays containing any of the above value types

716

Chapter 9

Values

Working with Values

Print and Format: The print() and format() functions are straightforward. The format function is used when any formatting of the output is desired, or if you want to print multiple values on a line. When printing a value using either of these functions, a string representation of the value is printed. This is not the object name for those objects with names (for example a 3ds max object or material). In the following example, variable b contains a reference to a 3ds max Box object that has a material applied: Script:
print print print print b b.name b.material b.material.name

Output:
$Box:Box01 @ [-74.353745,0.000001,-19.931978] Box01 Material #1:Standard Material #1

The printed results above also reflect the result of a <value> as string operation, that is the result is a string representation of the object rather than the object name. classOf, superClassOf, and isKindOf The following table shows the hierarchy of classes and superclasses for a variable that contains a reference to a 3ds max Box object (i.e., b=box()).
ClassOf b box GeometryClass Node MAXWrapper Value Box GeometryClass Node MAXWrapper Value Value SuperClassOf Node MAXWrapper Value Value Value and isKindOf GeometryClass

The isKindOf() and classOf() functions are useful for filtering objects from a set. For example, either of the following will collect all objects of class box into variable allBoxes:
allBoxes=for obj in $* where (isKindOf obj box) do collect obj allBoxes=#() for obj in $* do (if classOf obj == box then append allBoxes obj)

Number Values

717

One of the named parameters to the interactive node selection functions is filter, which allows you to specify a function that returns a value of true if an object can be selected. The classOf, superClassOf, and isKindOf functions are frequently used in these functions. For example, the following function limits the choices to shape objects:
fn shape_filt obj = isKindOf obj Shape

For an example of such a usage, see the Pickbutton (p. 1504) topic.

Basic Data Values

Number Values (p. 717) String Values (p. 722) Name Values (p. 727) BooleanClass Values (p. 728) Color Values (p. 729) Point3 Values (p. 731) Point2 Values (p. 736) Ray Values (p. 737) Quat Values (p. 738) AngleAxis Values (p. 741) EulerAngles Values (p. 742) Matrix3 Values (p. 744) BigMatrix Values (p. 748) Box2 Values (p. 750) BitArray Values (p. 791) ArrayParameter Values (p. 770)

Number Values
Integer : Number Float : Number The Number class provides standard arithmetic capabilities to MAXScript. The two Number types, Integer and Float, can be freely intermixed and MAXScript will convert as necessary. They both support all the following operators and methods. Also see the Number Literals (p. 660) topic. Literals:
[-]{<digit>}[.{<digit>}[(e | E)[+ | -]{<digit>}+] 0x{<hex_digit>}+ -- decimal number -- hexadecimal number

718

Chapter 9

Values

Example Literals:
123 123.45 -0.00345 1.0e-6 0x0E 0xFFE0 .1

Operators:
<number> <number> <number> <number> + * / <number> <number> <number> <number>

Standard arithmetic operations. If both numbers are integers, the result is a non-rounded integer. If one or both numbers are floats, both arguments are widened to floats and the result is a float.
<number> ^ <number>

Raise the first number to the power given by the second number. If the first number is an integer, the result is a rounded integer.
- <number>

unary minus
<number> <number> <number> <number> <number> <number> == <number> != <number> > <number> < <number> >= <number> <= <number>

Standard number comparison operations.

<number> as <class>

Converts the number to an instance of the given class. Allowed classes are:
Float Integer String Time (number taken as frames)

Methods:
copy <number>

Creates a new copy of the number value. This method exists primarily to support copying arrays.
abs <number>

Returns the absolute value of the number. The result is the same type as the argument.
mod <number1> <number2>

Modulo arithmetic, the remainder when number1 is divided by number2. The result is always a float.

Number Values

719

ceil <number>

Returns the nearest whole number greater than or equal to number. The result is always a float.
floor <number>

Returns the nearest whole number less than or equal to number. The result is always a float.
acos <number> asin <number> atan <number> atan2 <number> <number> cos <number> cosh <number> sin <number> sinh <number> tan <number> tanh <number>

Standard trigonometric functions. Angles are represented in degrees. The result is always a float.
exp <number> log <number> log10 <number> pow <number> <number> sqrt <number>

Standard transcendental functions. The result is always a float.

random <number> <number>

Returns a pseudo random number inclusively between the two arguments. Return value type is the type of the first argument.
seed <number>

Reseeds the random number generator using the specified value.

degToRad <number>

Returns the conversion of the number from degrees to radians. The result is always a float.
radToDeg <number>

Returns the conversion of the number from radians to degrees. The result is always a float.
bit.and <integer1> <integer2>

Returns the <integer> result of AND-ing the bits in integer1 and integer2
bit.or <integer1> <integer2>

Returns the <integer> result of OR-ing the bits in integer1 and integer2
bit.xor <integer1> <integer2>

Returns the <integer> result of XOR-ing the bits in integer1 and integer2
bit.not <integer1>

Returns the <integer> result of flipping the bits in integer1

720

Chapter 9

Values

bit.shift <integer1> <integer2>

Returns the <integer> result of shifting the bits in integer1 by integer2 places. If integer2 is positive, the bits are shifted to the left, if negative, to the right. The highest order bit is not carried when shifting to the left (unsigned shift operation).
bit.set <integer1> <integer2> <boolean>

Returns an <integer> result where bit integer2 of integer1 is set to the specified boolean value. Bit 1 is the lowest order (least significant) bit.
bit.flip <integer1> <integer2>

Returns an <integer> result where bit integer2 of integer1 is flipped. Bit 1 is the lowest order (least significant) bit.
bit.get <integer1> <integer2>

Returns the <boolean> state of the integer2 bit of integer1. Bit 1 is the lowest order (least significant) bit.
bit.intAsChar <integer>

Returns a <string> result of length 1 containing the character corresponding to the integer value. Only the lowest order 8-bits (16-bits for localized versions of 3ds max) of the integer areused.
bit.charAsInt <string>

Returns the <integer> value corresponding to the first character of the string.
bit.intAsHex <integer>

Returns a <string> value containing the hex representation of the integer. Notes: The range of valid Integers in MAXScript is -2,147,483,648 to 2,147,483,647. If you perform calculations that result in integers outside of this range, you will get integer overflow errors that are not detected by MAXScript. You must take care in designing your code to prevent or detect this overflow yourself. The result of an overflow is typically a large number of the wrong sign. Dividing an integer by 0 will result in a MAXScript system exception. A Float in MAXScript has an absolute value range of is 1.18E-38 to 3.40E38, with a precision of one part in 1.0E7. If you perform calculations that result in floats with an absolute value less than this range, the result will be stored as 0.0. If you perform calculations that result in floats with an absolute value larger than this range, the result will be stored as a special value that represents infinity, 1.#INF. Adding, subtracting, or multiplying a number by 1.#INF results in a value of 1.#INF. Dividing a number by 1.#INF results in a value of 0.0. Dividing 0.0 by 0.0 or 1.#INF by 1.#INF, multiplying 1.#INF by 0, or 1.#INF from 1.#INF results in a special value that represents an indeterminate number, -1.#IND. Adding, subtracting, multiplying, or dividing a number by 1.#IND results in a value of -1.#IND.

Number Values

721

When you display or print a Float, MAXScript prints the value to the 6th significant digit. The following table shows examples of values stored to a MAXScript variable, the value as stored, and the value as displayed.
Input Value 1.23456789 1.1 1.01 1.001 1.0001 1.00001 1.000001 1.0000001 1.00000001 100017.911 1.23456788 1.10000002 1.00999999 1.00100004 1.00010001 1.00001001 1.00000095 1.00000011 1.00000000 100017.914 Stored Value 1.23457 1.1 1.01 1.001 1.0001 1.00001 1.0 1.0 1.0 100018.0 Displayed Value

Examples: The following script shows the use of various literals, constructors, properties, operators, and methods of the Number class. Script:
-- numbers test bed i=10 -j=20 i/j -i=i as float -i/j -i += 1 -if i < j do i=2.^3 -mod j i -cos 30.0 -sqrt j -seed 12345 -for k=1 to 5 do print assign integers to variables integer divide, result is integer convert i to a float float divide, result is float increment i by 1 if i is less than j, set i to 2 to the 3rd power return remainder of j divided by i return cosine of 30 degrees return square root of j seed the random number generator (random i j) -- print out 3 random numbers

722

Chapter 9

Values

Output:
10 20 0 10.0 0.5 11.0 8.0 4.0 0.866025 4.47214 OK 10.7775 15.0183 17.4467 16.1027 10.1344 OK ------------result result result result result result result result result result result output of line 2 of line 3 of line 4 (10/20) of line 5 of line 6 (10./20) of line 7 of line 8 (2.^3) of line 9 of line 10 of line 11 (sqrt 20) of line 12 from line 13 (random 8. 20)

-- result of line 13

String Values
The String class defines the characteristics of character strings. The character strings can be of any length. Literal:
<characters>

See the String Literals (p. 660) topic for a description of String literals. Constructors:
<value> as string

Converts any value into its string representation. Properties:

<string>.count : Integer, read-only

The number of characters in the string. Operators:

<string> + <string>

Returns a new string that is the concatenation of the two strings.

<string> <string> <string> <string> <string> <string> == <string> != <string> > <string> < <string> >= <string> <= <string>

Standard lexical string comparisons (case sensitive). To perform a case insensitive comparison, first convert the strings to Name values.
<string>[<index_number>]

Returns indexed character as a single-character string, index starts at 1.

String Values

723

<string>[<index_number>] = <single_character_string>

Sets indexed character to character given.

<string> as <class>

Converts the string to an instance of the given class. You can convert a string into a Name value using the as operator, for example:
Foo as name -- returns #foo

You can also convert strings to numbers using the as operator. For example:
123.4 as float -- returns 123.4

You can use any of the Number classes as a target class - Number, Float, or Integer. If you use Number, the appropriate class will be used depending on the syntax of the number in the string. You can convert a string to a StringStream value using the as operator. For example:
$box01 as stringstream -- returns the string as a stringstream

Converting a string to a StringStream value allows you to read through a string using the MAXScripts text file I/O operations. See the StringStream Values (p. 766) topic for a description of StringStreams. Methods:
copy <string>

Creates a new copy of the string value. For example:

newstr = copy oldstr

The new value contains a copy of the text contents of the copied string, and is independent of the copied string.
execute <string>

Compiles and evaluates the contents of the string as a MAXScript expression and returns the result of the evaluation. For example:
execute 2 + 2 -- yields the value 4

str = $foo.ffd_2x2x2.control_point_ + n as string + = [1,1,1] execute str

The result of an execute() call is the result of the last expression in the string argument.

724

Chapter 9

Values

You can use execute() as a temporary work-around to the current limitation in naming scene objects - there is currently no way to name an object using a computed name. For example:
obj = execute ($foo/ + child_name)

would retrieve the child of $foo named in the variable child_name. Heres a more complex example:
side = left finger = 2 limb = arm obj = execute ($torso/ + limb + / + side + /finger/ + finger as string)

The scope of variables used in the evaluated string is global and not the scope in effect when the execute() method is executed. So if you call execute() within a function, scripted utility, or anywhere where the scope is not global, you will need to explicitly specify the scope of any variables used in the string that is executed. In the following example, the scope of variable posObj is local to utility myUtil, so the string needs to specify the variables name as being in myUtils scope:
Utility myUtil My Utility ( ... local posObj ... fn test obj = ( local i, j, thisCont ... thisCont=execute (myUtil.posObj.+j+pos.controller) ... )

In general, you cannot access locals from outside of an object, except for top-level locals in rollouts, utilities, tools and plug-ins (because they are semi-permanent and are stored with these objects). Function parameters and locals are dynamic and stack-based and not accessible as properties of the function definition. For more information on variable scope, see the Scope of Variables (p. 646) and Accessing Locals and Other Items in a Rollout from External Code (p. 1480) topics.
GetTextExtent <string>

Returns a Point2 value containing the size of the string in pixels if it was displayed in a command panel.
findString <string> <search_string>

Returns the index of search_string in string or undefined if not found. For example:
findString Thanks for all the fish! all -- returns 12

String Values

725

filterString <string> <token_string>

Parses string based on token_string and returns an array of strings. filterString splits the input string into substrings based on the characters given in token_string, and returns each substring as a member of the array. The token_string is simply a list of splitter characters - when the string is scanned, any occurrence of any of the tokens is regarded as the start of a substring. This function is useful for file import/export scripts, or for any type of manual parsing. For example:
filterString MAX Script, is-dead-funky , -

would return
#(MAX,Script,is,dead,funky) replace <string> <from_integer> <length_integer> <new_string>

Returns a new string where the substring in string starting at index from_integer, and of length length_integer, is replaced with the new_string. new_string can be any length. The sum of from_integer and length_integer must be less than the length of string. An example usage is:
s=1234567890 s1=replace s 5 3 inserted string -- returns 1234inserted string890

substring <string> <from_integer> <length_integer>

Returns a new string consisting of the substring in string starting at index from_integer, and of length length_integer. If the sum of from_integer and length_integer is greater than the length of string, a shorter string is returned containing as many characters as are available in the source. If a negative value is specified for length_integer, the remainder of the string starting from from_integer is returned. For example:
s = Balerofon ss = substring s 5 3 ss = substring s 5 -1 ss = substring s 5 100 -- returns rof -- returns rofon -- returns rofon

matchPattern <string> pattern:<pattern_string> \ [ ignoreCase:<boolean> ]

Returns true if string is matched by the wild card pattern_string, false otherwise. The comparison is case-insensitive unless ignoreCase:false is specified. For example:
s=text1 matchPattern matchPattern matchPattern matchPattern s s s s pattern:text? pattern:T* pattern:T* ignoreCase:false pattern:s* ----returns returns returns returns true true false false

Examples: The following script shows the use of various literals, constructors, properties, operators, and methods of the String class.

726

Chapter 9

Values

Script:
-- strings test bed fn uppercase instring = -- beginning of function definition ( local upper, lower, outstring -- declare variables as local upper=ABCDEFGHIJKLMNOPQRSTUVWXYZ -- set variables to literals lower=abcdefghijklmnopqrstuvwxyz --- create an unique copy of the string referenced by instring, and store -- reference to unique copy in outstring outstring=copy instring --- increment from 1 to number of character in string for i=1 to outstring.count do --- see if the single character at index i in outstring is present in string lower -- If so, j equals position in string lower. If not, j equals undefined ( j=findString lower outstring[i] --- if character was found in lower, replace with corresponding character in upper if (j != undefined) do outstring[i]=upper[j] ) outstring -- value of outstring will be returned as function result )-- end of fn uppercase -s1=AbCdEfGh -- set variable to literal s2=uppercase s1 -- call function uppercase, passing s1 as parameter if s1 == s2 do print strings s2 and s3 are the same -- compare strings if s1 != s2 do print strings s1 and s2 are different -theObject=sphere -- set variable to literal theRadius= (random 10. 100.) as string -- convert number to string -- concatenate strings and execute string myObject=execute (theObject + radius: + theRadius)

Output:
uppercase() AbCdEfGh ABCDEFGH undefined strings s1 and s2 are different strings s1 and s2 are different sphere 75.4091 $Sphere:Sphere01 @ [0.0,0.0,0.0] -----------result to function definition result of line 24 result of line 25 result of line 26 - strings not equal, and no else expression in if expression output from line 27 result of line 27 result of line 29 result of line 30 result of line 32. Execute function created a sphere object

Name Values

727

Name Values
The Name class defines the characteristics of names. Names are primarily used as parameters in function calls to signify one of a set of options. Literal:
#<var_name>

See the Names (p. 657) topic for a description of Name literals. Constructors:
<string> as name

Converts a String value into a name Operators:

<name> <name> <name> <name> <name> <name> == <name> != <name> < <name> > <name> <= <name> >= <name>

Comparison of names is caseless alphabetic. Among other things, this allows arrays of names to be sorted using the array sort function. Examples: The following script shows the use of various literals, constructors, and operators of the Name class. Script:
-- name test bed name1=#Hello name2=HELLO as name if name1 == name2 do print names are equal box_props=getpropnames box sort box_props -----set variable to name literal convert string to name compare the names get the properties of box class sort the property names

Output:
#Hello -- result of line 2 #Hello -- result of line 3 names are equal -- output from line 4 names are equal -- result of line 4 -- following are the results of lines 5 and 6 #(#height, #length, #lengthsegs, #width, #widthsegs, #mapCoords, #heightsegs) #(#height, #heightsegs, #length, #lengthsegs, #mapCoords, #width, #widthsegs)

728

Chapter 9

Values

BooleanClass Values
The BooleanClass class defines the characteristics of values that can only have one of two states. Literals:
true false on off

-- equivalent to true -- equivalent to false

Operators:
not <boolean>

true if boolean=false, false if boolean=true

<boolean> and <boolean>

true if both boolean values are true

<boolean> or <boolean>

true if either boolean value is true Notes: The boolean and and or evaluations are non-strict. This means that only the first boolean may be evaluated to determine the overall result: If the first operand is false in an and expression, the result must be false, therefore, the second operand is not evaluated. If the first operand is true in an or expression, the result must be true, therefore, the second operand is not evaluated.

This saves execution time and enables useful shorthand notation. For example, if you want to calculate sin a if the value of variable a isnt undefined, you could use the example below:
if a != undefined and sin a > 0 then ..

Examples: The following script shows the use of various literals and operators of the BooleanClass class. Script:
-- boolean test bed bool1=true -- set variables to boolean literals bool2=on if bool1 and bool2 do print booleans are equal -- compare the booleans -- define an exclusive or function - returns true if only one of the -- inputs is true fn xor b1 b2 = (not (b1 and b2)) and (b1 or b2) xor false false -- evaluate 4 combinations of inputs to xor xor false true xor true false xor true true

Color Values

729

Output:
true true booleans are equal booleans are equal xor() false true true false ---------result of line 2 result of line 3 output from line 4 result of line 4 function definition result of line 8 result of line 9 result of line 10 result of line 11

Color Values
All the places that colors turn up in MAXScript (such as wireColor, light color, etc.) are represented by instances of the Color class. You can also use Point3 values as color specifiers. Literals:
red green blue white black orange yellow brown gray

predefined MAXScript globals Constructors:

color <r> <g> <b> [ <a> ]

r,g,b and optional alpha are float values in the range 0 to 255
<point3> as color

interprets x as r, y as g, z as b Properties:
<color>.red or .r <color>.green or .g <color>.blue or .b <color>.alpha or .a : : : : Float Float Float Float

color component properties

<color>.hue or .h <color>.saturation or .s <color>.value or .v : Float : Float : Float

derived properties

730

Chapter 9

Values

Operators:
<color> == <color> <color> != <color> <color> <color> <color> <color> + * / <color_or_number> <color_or_number> <color_or_number> <color_or_number>

Channel-by-channel math operations. Numbers operate on r,g,b,a channels equally.

- <color>

unary minus Methods:

copy <color>

Creates a new copy of the color value. For example:

newClr = copy oldClr

The new value contains a copy of the input color value, and is independent of the input color value.
random <from_color> <to_color>

Returns a random color between the given colors. The alpha component of the result will always be 255.
composite <color1> <color2>

Composites color1 over color2 through color1s alpha. This function is equivalent to:
color1 + color2*((255. - color1.alpha)/255.)

-- 3D Noise Functions
noise3 <color> noise4 <color> <phase_float> turbulence <color> <frequency_float> fractalNoise <color> <H_float> <lacunarity_float> <octaves_float>

See the Point3 Values (p. 731) topic for a description of the noise functions. Notes: The component values of a Color value (r, g, b, and a) are normally in the range 0.0 to 255.0. However values outside this range are permissible. When color values outside the normal range are used in 3ds max, 3ds max clamps the values to the range of 0.0 to 255.0. Examples: The following script shows the use of various literals, constructors, properties, operators, and methods of the Color class.

Point3 Values

731

Script:
-- color test bed magenta=color 255 255 0 255 aqua = [0, 255, 255] as color aqua.v /= 2. aqua aqua.alpha=128 aqua lightGray=white/4 composite aqua lightGray random black white -- create colors using constructors -- reduce strength of aqua color -- set aqua to 50% opacity ----create light gray color by dividing each component of white by 4 composite light gray over aqua generate a random color

Output:
(color 255 255 0) (color 127.5 (color 128 (color (color (color (color -- result of line 2. Note that if -- alpha=255 it is not displayed 0 255 255) -- result of line 3 -- result of line 4 - value property of aqua 0 127.5 127.5) -- result of line 5 - color of aqua -- result of line 6 - alpha property of aqua 0 127.5 127.5,128) -- result of line 7 - color of aqua 63.75 63.75 63.75) -- result of line 8 - each component divided by 4 31.75 159.25 159.25 159.75) -- result of line 10 170.944 109.543 74.1957) -- result of line 11

Point3 Values
The Point3 class defines the characteristics of points in 3D space. These values are also known as 3D vectors, and contain 3 component floating point numbers. All the coordinates passed to and from 3ds max are in these values. See also 2D and 3D Point Literals (p. 665). Literals:
[ <expr>, <expr>, <expr> ]

Example Literals:
[x, y, z] [10, 10, 10] [sin x, cos y, tan z] x_axis y_axis z_axis

-- equivalent to [1,0,0] -- equivalent to [0,1,0] -- equivalent to [0,0,1]

Constructors:
point3 <x> <y> <z> <color> as point3

732

Chapter 9

Values

Properties:
<point3>.x <point3>.y <point3>.z : Float -- the x coordinate : Float -- the y coordinate : Float -- the z coordinate

Operators:
<point3> == <point3> <point3> != <point3> <point3> <point3> <point3> <point3> + * / <point3_or_number> <point3_or_number> <point3_or_number> <point3_or_number>

Standard vector arithmetic. If the second operand is a number, the operation is performed on each component of the value.
<point3> * <matrix3>

Transforms point3 into the coordinate system specified by matrix3.

<point3> * <quat>

rotates point3
- <point3>

unary minus Methods:

copy <point3>

Creates a new copy of the point3 value. For example:

newPos = copy oldPos

The new value contains a copy of the input point3 value, and is independent of the input point3 value.
length <point3>

Returns the length of the vector.

dot <point3> <point3>

Returns the vector dot product.

cross <point3> <point3>

Returns the vector cross product.

normalize <point3>

Returns the point3 value normalized such that the vector length equals 1.
distance <point3> <point3>

Returns the distance between the points - length of (point 2 point 1).
random <point3> <point3>

Generates a pseudo-random point between the given points.

arbAxis <point3>

Returns a Matrix3 value representing an arbitrary axis system using point3 as the up direction.

Point3 Values

733

matrixFromNormal <point3>

Returns a Matrix3 value with the normal specified by the given point as the Z axis. The translation portion of the Matrix3 value will be [0,0,0]. The components of the scale portion are the inverse of the values required to normalize the point3 value. For example,
MatrixFromNormal [0,0,1] MatrixFromNormal [0,1,1]

will return
(matrix3 [1,0,0], [0,1,0], [0,0,1], [0,0,0]) (matrix3 [0,-0.707107,0.707107] [1.41421,0,0] [0,1,1] [0,0,0])

-- 3D Noise Functions
noise3 <point3>

A floating point noise function over 3D space, implemented by a pseudo-random tricubic spline. The return value is in the range -1.0 to +1.0. Given the same point3 value, the noise3() function always returns the same value.
noise4 <point3> <phase_float>

The same function as noise3 in which the phase can be varied using the second parameter. The return value is in the range -1.0 to +1.0.
turbulence <point3> <frequency_float>

This is a simple fractal-loop turbulence built on top of the noise3 function. The second parameter controls the frequency of the turbulence. The return value is in the range 0.0 to +1.0.
fractalNoise <point3> <H_float> <lacunarity_float> <octaves_float>

This is a fractal function of 3D space implemented using fractional Brownian motion. The function is homogeneous and isotropic. It returns a float. The parameters are as follows: point3 - The point in space at which the noise is computed. H_float - The fractal increment parameter in the range [0,1]. When H_float is 1 the function is relatively smooth; as H_float goes to 0, the function approaches white noise. lacunarity_float - The gap between successive frequencies, best set at 2.0. octaves_float - The number of frequencies in the function. All the noise functions are based on code and algorithms in the book Texturing and Modeling: A Procedural Approach, Musgrave, Peachey, Perlin and Worley. Academic Press, ISBN: 0-12-228760-6.

734

Chapter 9

Values

Examples: The following script shows the use of various literals, constructors, properties, operators, and methods of the Point3 class. The following script was written as a test bed for the noise functions. This script displays a 2 dimensional slice of the noise function output as a bitmap. By changing the noise parameters in lines 4 through 10, and specifying which noise function to evaluate in line 12, you can see the effects of changes in the parameters and using different noise functions. Script:
-- noise functions test bed b_width=320 -- specify size of bitmap b_height=320 size=10. -- total distance covered by each row and column z=0. -- z coordinate of 2D slice phase=0.5 -- noise4 parameter frequency=10. -- turbulence parameter fract_interval=.5 -- fractalNoise parameters lacunarity=2. octaves=5 -whichfunc=1 -- 1 = noise3; 2 = noise4; 3 = turbulence; 4 = fractalNoise -b=bitmap b_width b_height -- create the bitmap for h=0 to (b_height-1) do -- step through each row of the bitmap ( h_norm=(h as float/(b_height-1))*size -- calculate y coordinate row = for w=0 to (b_width-1) collect -- collect row of pixel colors ( w_norm=(w as float/(b_width-1))*size -- calculate x coordinate noise_val = case whichfunc of -- store result of selected function ( 1: noise3 [w_norm, h_norm , z] 2: noise4 [w_norm, h_norm , z] phase 3: turbulence [w_norm, h_norm , z] frequency 4: fractalNoise [w_norm, h_norm , z] fract_interval lacunarity octaves ) noise_val = 0.5*(1.+noise_val) -- convert output range to 0. to 1. white*noise_val -- and multiply by color white ) setpixels b [0,h] row -- store row of pixels in bitmap ) display b -- display bitmap in VFB

Point3 Values

735

Output: The following figures show the bitmap generated by the above script for each noise function type.

noise3

noise4

turbulence

736

Chapter 9

Values

fractalNoise

Point2 Values
The Point2 class defines the characteristics of points in 2D space. This class is a 2D version of Point3 and is used in utility rollout positioning parameters and for accessing Bitmap values, etc. See also 2D and 3D Point Literals (p. 665). Literals:
[ <expr>, <expr> ]

Example Literals:
[x, y] [10, 20] [sin x, cos x]

Constructors:
point2 <x> <y> <point3> as point2 -- x and y are numbers -- created from the x and y components of the point3

Properties:
<point2>.x <point2>.y : Float : Float

Operators:
<point2> == <point2> <point2> != <point2> <point2> <point2> <point2> <point2> + * / <point2_or_number> <point2_or_number> <point2_or_number> <point2_or_number>

Standard vector arithmetic. If the second operand is a number it does scalar arithmetic on vector.
- <point2>

unary minus

Ray Values

737

Methods:
copy <point2>

Creates a new copy of the point2 value. For example:

newPoint = copy oldPoint

The new value contains a copy of the input point2 value, and is independent of the input point2 value.
random <point2> <point2>

Generates a pseudo-random point between the given points.

length <point2>

Returns the length of the vector.

distance <point2> <point2>

Returns the distance between the points - length of (point 2 point 1).
normalize <point2>

Returns the point2 value normalized such that the vector length equals 1.

Ray Values
The Ray class defines the characteristics of a ray in 3D space. A ray has two Point3 components, one defining a start position and the other a direction vector for the ray. Constructors:
ray <pos_point3> <dir_point3>

Returns a new ray with given position and direction vector.

<node> as ray

Takes a scene object that has a target, such as a tape measure or a target camera and returns a ray from the object to the target. Returns undefined if the object has no target. Properties:
<ray>.pos <ray>.position <ray>.dir : Float : Float : Point3 -- pos and position are synonyms -- unit normalized direction vector

Methods:
copy <ray>

Creates a new copy of the ray value. For example:

newRay = copy oldRay

The new value contains a copy of the input ray value, and is independent of the input ray value.

738

Chapter 9

Values

Quat Values
The Quat class provides a compact representation for orientation in three space and provides methods to perform Quaternion algebra. Quaternions are used to store object rotations in 3ds max. A quaternion is made up of four terms: a real scalar part which specifies the amount of rotation and an imaginary vector part which defines the axis of rotation. If the quaternion is normalized, the scalar term equals the cosine of half the angle of rotation, the vector term is the axis of rotation, and the magnitude of the vector term equals the sine of half the angle of rotation. Interpolation between two key frame orientations is much easier using quaternions and produces smooth and natural motion. Unlike Euler angles, no numerical integration is necessary; quaternions provide an analytic result (no approximations). Rotations in MAXScript follow the right-hand-rule, namely positive angles rotate counter-clockwise about positive axes, consistent with the convention in the 3ds max UI. Constructors:
quat <x_float> <y_float> <z_float> <w_float>

The x, y, z values make up the vector portion. w is the angle of rotation about the vector.
quat <degrees_float> <axis_point3> <angleaxis> as quat <eulerangle> as quat <matrix3> as quat -- extracts the rotation component as a quat

Properties:
<quat>.w <quat>.x <quat>.y <quat>.z <quat>.angle <quat>.axis : : : : Float Float Float Float

quaternion complex components as Floats

: Float : Point3

derived properties - an angle in degrees and a rotation axis Operators:

<quat> + <quat> <quat> * <quat> / - <quat> <quat> <quat> <quat_or_number> <number>

Quaternion algebra
<quat> * <matrix3>

Quaternion algebra using rotation portion of the matrix3

<quat> == <quat> <quat> != <quat> <quat> as <class>

quats can convert to Matrix3s, Angleaxiss, Eulerangles

Quat Values

739

Methods:
copy <quat>

Creates a new copy of the quat value. For example:

newQuat = copy oldQuat

The new value contains a copy of the input quat value, and is independent of the input quat value.
isIdentity <quat>

Returns true if the quaternion is equal to the identity quaternion (x=y=z=0.0; w=1.0).
normalize <quat>

Returns a normalized quat, dividing each term of the input quat by a scale factor such that the resulting sum of the squares of all parts equals unity.
inverse <quat>

Returns the inverse of the quaternion (1/q).

conjugate <quat>

Returns the conjugate of a quaternion.

logN <quat>

Returns the natural logarithm of UNIT quaternion.

exp <quat>

Returns the exponentiated quaternion (where q.w=0).

slerp <start_quat> <end_quat> <number>

Returns a spherical linear interpolation of UNIT quaternions. As number goes from 0 to 1, the returned value goes from start_quat to end_quat.
LnDif <p_quat> <q_quat>

Returns the log difference of two quaternions as:

logN ((inverse p_quat)*q_quat) qCompA <prev_quat> <now_quat> <next_quat>

Compute a, the term used in Boehm-type interpolation:

a = now_quat * exp(-(1 / 4)*(logN((inverse now_quat)*next_quat)+ logN((inverse now_quat)*prev_quat))) squad <p_quat> <a_quat> <b_quat> <q_quat> <number> slerp (slerp p_quat q_quat number) \ (slerp a_quat b_quat number) \ (2*(1-number)*number) qorthog <quat> <axis_point3>

Returns quat rotated by 180 degrees (quaternion space metric) about the specified axis axis_point3.
transform <quat> <matrix3>

Returns the transformation of the specified quaternion by the specified matrix.

740

Chapter 9

Values

squadrev <angle_number> <axis_point3> <start_quat> \ <start_tangent_quat> <end_tangent_quat> \ <end_quat> <number>

Returns quaternion interpolation for angles > 2PI where angle_number is angle of rotation, and axis_point3 is axis of rotation. As number goes from 0 to 1, the returned value goes from start_quat to end_quat.
random <quat> <quat>

Returns a random rotation between the two quats, using Slerp. Related Methods:
quatToEuler <quat> order:<eulertype_integer> eulerToQuat <eulerAngle> order:<eulertype_integer>

Convert between quat and euler angle values. The optional order parameter specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:
1 2 3 4 5 6 7 8 9 XYZ XZY YZX YXZ ZXY ZYX XYX YZY ZXZ \

getEulerQuatAngleRatio <quat1> <quat2> <eulerAngles1> <eulerAngles2> \ [angle:<eulertype_integer>]

When converting a series of quat values to eulerAngles values, it is possible for sign flips to occur in the eulerAngles values. This is due to the fact that one single quat value can be expressed through many different eulerAngles values. This flip can be detected by based on the eulerAngles/quat ratio. The eulerAngles/quat ratio is the relation of the angle difference in eulerAngles space to the angle difference in quat space. If this ratio is bigger than PI the rotation between the two quat to eulerAngles conversions. This method returns the eulerAngles/quat angle ratio between the two quat to eulerAngles conversions as a float value. The actual detection of the flip is dependent on the amount of rotation in between conversions. The smaller the amount of rotation, the more accurate the detection is. The parameters to this method are: quat1 and quat2 are the previous and current rotation values. eulerAngles1 and eulerAngles2 are the previous and current converted rotation angles.

AngleAxis Values

741

The optional eulertype_integer parameter specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:
1 2 3 4 5 6 7 8 9 XYZ XZY YZX YXZ ZXY ZYX XYX YZY ZXZ

AngleAxis Values
The AngleAxis class provides a representation for orientation in 3D space using an angle in degrees and a rotation axis. This class is similar to a quaternion, except that a normalized quaternion only represents -PI to +PI rotation. Angles can be greater than 360 and so specify multiple revolutions, unlike quaternions. Rotations follow the right-hand-rule. Constructors:
angleaxis <degrees_float> <axis_point3> <quat> as angleaxis <eulerangle> as angleaxis <matrix3> as angleaxis

extracts the rotation component as an angleaxis Operators:

<angleaxis> == <angleaxis> <angleaxis> != <angleaxis> <angleaxis> as <class>

AngleAxis can convert to Matrix3s, Quats, Eulerangles Properties:

<angleaxis>.angle <angleaxis>.axis <angleaxis>.numrevs : Float : Point3 : Integer

Methods:
copy <angleaxis>

Creates a new copy of the angleaxis value. For example:

newAngleAxis = copy oldAngleAxis

The new value contains a copy of the input angleaxis value, and is independent of the input angleaxis value.
random <angleaxis> <angleaxis>

Random rotation in degrees, but uses quat Slerp, so loses multiple revolution angles.

742

Chapter 9

Values

EulerAngles Values
The EulerAngles class provides a representation for orientation in 3D space using rotation angles in degrees about each axis. Angles can be greater than 360 and so specify multiple revolutions. Rotations follow the right-hand-rule. Constructors:
eulerAngles <x_degrees> <y_degrees> <z_degrees> <quat> as eulerAngles <angleAxis> as eulerAngles <matrix3> as eulerAngles

Extracts the rotation component as an eulerAngles. Operators:

<eulerAngles> == <eulerAngles> <eulerAngles> != <eulerAngles> <eulerAngles> as <class>

eulerAngles can convert to Matrix3, Quat, angleAxis values Properties:

<eulerAngles>.x <eulerAngles>.y <eulerAngles>.z : Float : Float : Float

Rotation about each primary axis in float degrees Methods:

copy <eulerAngles>

Creates a new copy of the eulerAngles value. For example:

newEulerAngles = copy oldEulerAngles

The new value contains a copy of the input eulerAngles value, and is independent of the input eulerAngles value.
random <eulerAngles> <eulerAngles>

Random rotation between the eulerAngles, but uses quat Slerp, so loses multiple revolution angles.

EulerAngles Values

743

quatToEuler <quat> order:<eulertype_integer> eulerToQuat <eulerAngle> order:<eulertype_integer>

Convert between quat and euler angle values. The optional order parameter specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:
1 2 3 4 5 6 7 8 9 XYZ XZY YZX YXZ ZXY ZYX XYX YZY ZXZ \

getEulerQuatAngleRatio <quat1> <quat2> <eulerAngles1> <eulerAngles2> \ [angle:<eulertype_integer>]

When converting a series of quat values to eulerAngles values, it is possible for sign flips to occur in the eulerAngles values. This is due to the fact that one single quat value can be expressed through many different eulerAngles values. This flip can be detected by based on the eulerAngles/quat ratio. The eulerAngles/quat ratio is the relation of the angle difference in eulerAngles space to the angle difference in quat space. If this ratio is bigger than PI the rotation between the two quat to eulerAngles conversions. This method returns the eulerAngles/quat angle ratio between the two quat to eulerAngles conversions as a float value. The actual detection of the flip is dependent on the amount of rotation in between conversions. The smaller the amount of rotation, the more accurate the detection is. The parameters to this method are: quat1 and quat2 are the previous and current rotation values. eulerAngles1 and eulerAngles2 are the previous and current converted rotation angles. The optional eulertype_integer specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:
1 2 3 4 5 6 7 8 9 XYZ XZY YZX YXZ ZXY ZYX XYX YZY ZXZ

744

Chapter 9

Values

getEulerMatAngleRatio <matrix3_1> <matrix3_2> <eulerAngles1> <eulerAngles2> \ [angle:<eulertype_integer>]

This method parallels the getEulerQuatAngleRatio() method. This method is identical to getEulerQuatAngleRatio() with the exception that matrix3 values are passed rather than quat values.

Matrix3 Values
The Matrix3 class implements a 4x3 3D transformation matrix object. The transform matrix is a 3D homogeneous matrix typically used to hold object coordinate systems and transformations. Constructors:
matrix3 <row1_point3> <row2_point3> <row3_point3> <row4_point3>

matrix from row vectors

matrix3 0

zero matrix
matrix3 1

identity matrix
<quat> as matrix3 <angleaxis> as matrix3 <eulerangles> as matrix3

rotation matrices
rotateXMatrix <number> rotateYMatrix <number> rotateZMatrix <number> -- all angles in degrees

rotation matrices
transMatrix <point3>

translation matrix
scaleMatrix <point3>

scale matrix
rotateYPRMatrix <yaw_number> <pitch_number> <roll_number>

Returns a Matrix3 value for use as a rotation transformation by specifying yaw, pitch and roll angles. All angles are in degrees.
matrixFromNormal <point3>

Returns a Matrix3 value with the normal specified by the given point as the Z axis. The translation portion of the Matrix3 value will be [0,0,0]. The components of the scale portion are the inverse of the values required to normalize the point3 value. For example,
MatrixFromNormal [0,0,1] MatrixFromNormal [0,1,1]

will return
(matrix3 [1,0,0], [0,1,0], [0,0,1], [0,0,0]) (matrix3 [0,-0.707107,0.707107] [1.41421,0,0] [0,1,1] [0,0,0])

Matrix3 Values

745

Operators:
<matrix3> <matrix3> <matrix3> <matrix3> + <matrix3> - <matrix3> * <matrix3> as <class>

Matrix3s can convert to Quats, AngleAxis, EulerAngles using the matrixs rotation component Properties:
<matrix3>.row1 <matrix3>.row2 <matrix3>.row3 <matrix3>.row4 <matrix3>.translation <matrix3>.rotationpart <matrix3>.translationpart <matrix3>.scalerotationpart <matrix3>.scalepart <matrix3>.determinantsign : : : : : : : : : Point3 Point3 Point3 Point3 Point3 Quat, read-only Point3, read-only Quat, read-only Point3, read-only

read/write access to rows. Row4 is the translation.

access to various transforms, with the remaining transforms zero-ed out.

: Integer, read-only

returns sign of the matrixs determinant Methods:

copy <matrix3>

Creates a new copy of the matrix3 value. For example:

newMatrix3 = copy oldMatrix3

The new value contains a copy of the input matrix3 value, and is independent of the input matrix3 value.
isIdentity <matrix3>

Returns true if the matrix is equal to the identity matrix.

inverse <matrix3>

Returns the inverse of the matrix.

xformMat <transform_matrix3> <space_matrix3>

Returns the transform matrix transformed into a particular space. For example, say you have a rotation you want to apply, but you want to perform the rotation in another coordinate system. To do this, you typically transform into the space of the coordinate system, then apply the transformation, and then transform out of that coordinate system. This method transformats matrix transform_matrix3 into the space of matrix space_matrix3. The resulting matrix3 value is calculated as space_matrix3 * transform_matrix3 * inverse(space_matrix3).

746

Chapter 9

Values

identity <matrix3>

-- mapped function

Sets the input matrix or matrices to the identity matrix. If the parameter is a single matrix, this function returns an identity matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 values are replaced with the identity matrix.
zero <matrix3> -- mapped function

Sets the input matrix or matrices to the zero matrix. If the parameter is a single matrix, this function returns an zero matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 values are replaced with the zero matrix.
orthogonalize <matrix3> -- mapped function

Sets the input matrix or matrices to the an unbiased orthogonalization of the matrix. An orthogonal matrix has an axis system where each axis is 90 degrees from the others (its not skewed). If the parameter is a single matrix, this function returns the orthogonalized matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the orthogonalized matrix value(s).
translate <matrix3> <point3> -- mapped function

Applies an incremental translation transformation to the input matrix or matrices. This is equivalent to multiplying on the RIGHT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).
rotateX <matrix3> <number> rotateY <matrix3> <number> rotateZ <matrix3> <number> rotate <matrix3> <quat> -- mapped functions -- all angles in degrees

Applies an incremental rotation transformation to the input matrix or matrices. This is equivalent to multiplying on the RIGHT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).
scale <matrix3> <point3> [ <boolean> ] -- mapped function

Applies an incremental scale transformation to the input matrix or matrices. This is equivalent to multiplying on the RIGHT by the transform. If <boolean> is true, the translation component is scaled. If <boolean> is false the translation component is unaffected. When 3ds max was originally written there was a bug in the code for this method where the translation portion of the matrix was not being scaled. This meant that when a matrix was scaled the bottom row was not scaled. Thus it would always scale about the local origin of the object, but it would scale the world axes. When this bug was discovered, dependencies existed in the code upon this bug. Thus it could not simply be fixed because it would break the existing code that depended upon it working the incorrect way. To correct this boolean parameter was added. If it is set to true, the translation component will be scaled correctly. If not specified, the boolean defaults to

Matrix3 Values

747

false, and the code behaves the old way. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).
preTranslate <matrix3> <point3> -- mapped function

Applies an incremental translation transformation to the input matrix or matrices. This is equivalent to multiplying on the LEFT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).
preRotateX <matrix3> <number> preRotateY <matrix3> <number> preRotateZ <matrix3> <number> preRotate <matrix3> <quat> -- mapped functions -- all angles in degrees

Applies an incremental rotation transformation to the input matrix or matrices. This is equivalent to multiplying on the LEFT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).
preScale <matrix3> <point3> [ <boolean> ] -- mapped function

Applies an incremental scale transformation to the input matrix or matrices. This is equivalent to multiplying on the LEFT by the transform. If <boolean> is true, the translation component is scaled. If <boolean> is false the translation component is unaffected. If not specified, the boolean defaults to false. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s). Related Methods:
getEulerMatAngleRatio <matrix3_1> <matrix3_2> <eulerAngles1> <eulerAngles2> \ [angle:<eulertype_integer>] \

When converting a series of matrix3 values to eulerAngles values, it is possible for sign flips to occur in the eulerAngles values. This is due to the fact that one single matrix3 value can be expressed through many different eulerAngles values. This flip can be detected by based on the eulerAngles/matrix3 ratio. The eulerAngles/matrix3 ratio is the relation of the angle difference in eulerAngles space to the angle difference in matrix3 space. If this ratio is bigger than PI the rotation between the two matrix3 to eulerAngles conversions. This method returns the eulerAngles/matrix3 Angle ratio between the two matrix3 to eulerAngles conversions as a float value. The actual detection of the flip is dependent on the amount of rotation in between conversions. The smaller the amount of rotation, the more accurate the detection is. The parameters to this method are:

748

Chapter 9

Values

matrix3_1 and matrix3_2 are the previous and current transform matrix values. eulerAngles1 and eulerAngles2 are the previous and current converted rotation angles. The optional eulertype_integer specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:
1 2 3 4 5 6 7 8 9 XYZ XZY YZX YXZ ZXY ZYX XYX YZY ZXZ

BigMatrix Values, BigMatrixRowArray Values

The BigMatrix class implements an MxN matrix for situations and calculations where the usual 4x3 Matrix3 class is not adequate. The BigMatrixRowArray class implements an N element vector. Each row in a BigMatrix value is a BigMatrixRowArray value. Only Float values can be stored in the elements of a BigMatrixRowArray. Constructors:
BigMatrix <rows> <columns>

Properties:
<BigMatrix>.rows <BigMatrix>.columns : Integer, read-only : Integer, read-only

Operators:
<BigMatrix> + <BigMatrix> -- both BigMatrix values must have same size <BigMatrix>[<int_row>] -- returns BigMatrixRowArray of indexed row <BigMatrixRowArray>[<int_column>] -- returns float value of indexed column <BigMatrixRowArray>[<int_column>] = <float_value> -- sets value in the indexed column

Because accessors are themselves operands, these definitions are recursive, which means that you can string accessors together:
<BigMatrix>[<int_row>][<int_column>] -- returns float value of indexed row and column <BigMatrix>[<int_row>][<int_column>] = <float_value> -- sets value in the matrix

Methods:
invert <BigMatrix>

Inverts the matrix in place, i.e., the input BigMatrix itself is modified. The return value is also the inverted matrix. Note that this method only works if this matrix is square, i.e. if m = n.

BigMatrix Values, BigMatrixRowArray Values

749

transpose <BigMatrix>

Returns the transpose of <BigMatrix>, i.e. result BigMatrix[i][j] = BigMatrix[j][i].

clear <BigMatrix>

Frees all the elements and sets the matrix size to be 0x0
setSize <BigMatrix> <rows> <columns>

Deletes the current elements and sets the size of the matrix to rows x columns.
identity <BigMatrix> -- mapped function

If the number of rows and columns are equal, this method sets the matrix to the identity (diagonal elements = 1, all other elements = 0). If the number of rows and columns are not equal, it does nothing. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input BigMatrix value(s) are set to the identity. Notes: A BigMatrix object is a compound object, similar to an array of arrays. All of the BigMatrix methods operate directly on the components of the input BigMatrix. As described in the Reference Assignment (p. 653) topic, this can cause complications to occur if a BigMatrix object referenced by more than one variable. If you assign a new value to an element of the matrix, or use any of the BigMatrix methods, the same object is still referenced by the variables. This can be seen in the following example. Script:
bm1=bigmatrix 2 2 for i=1 to 2 do for j=1 to 2 do bm1[i][j]=random 0 10 bm2=bm1 invert bm1 bm2

Output:
#BigMatrix( [0.00,0.00], [0.00,0.00] ) OK #BigMatrix( [4.00,6.00], [4.00,9.00] ) #BigMatrix( [0.75,-0.50], [-0.33,0.33] ) #BigMatrix( [0.75,-0.50], [-0.33,0.33] ) -- result of line 1, contents of bm1

-- result of line 2 -- result of line 3, contents of bm2

-- result of line 4, contents of bm1

-- result of line 5, contents of bm2

750

Chapter 9

Values

Box2 Values
The Box2 class describes a 2D rectangular region using integer coordinates. The Box2 class provides methods that return individual coordinates of the box, scale and translate it, retrieve its center, modify its size, and determine if points are inside the box. Box2 values are primarily used in the viewport graphics methods described in the Viewport Drawing Methods (p. 1592) topic. Constructors:
Box2 <x_integer> <y_integer> <w_integer> <h_integer>

Constructs a Box2 with the upper left corner at [x,y] with width w and height h.
Box2 <upperleft_point2> <lowerRight_point2>

Constructs a Box2 object from the specified corners. Properties:

<Box2>.x <Box2>.y <Box2>.w <Box2>.h <Box2>.left <Box2>.right <Box2>.top <Box2>.bottom <Box2>.center : : : : : : : : : Integer Integer Integer Integer Integer, alias of x property Integer Integer, alias of y property Integer Point2, read-only

The right property is calculated as right = x + w 1. The bottom property is calculated as bottom = y + h 1. Setting the right or bottom property will normally change the w and h properties, respectively. However, if right is set less than left, the right and left values will be swapped, and then the new value will be used as the left value. Likewise, if bottom is set less than top, the bottom and top values will be swapped, and then the new value will be used as the top value. Operators:
<Box2> == <Box2> <Box2> != <Box2>

Standard comparison operators. Two Box2 values are equal if all of their component values are equal. Methods:
scale <Box2> <float>

Scales the coordinates of the box about the center of the box.
translate <Box2> <point2>

Translates the coordinates of the box by the distance specified.

contains <Box2> <point2>

Determines if the point2 value is contained within the Box2. Returns true if the point is inside the Box2 or on the Box2 edge; otherwise false.
rectify <Box2>

Adjusts the coordinates of the box such that top < bottom and left < right.

Time Values

751

empty <Box2>

Sets the Box2 to a special empty value.

isEmpty <Box2>

Returns true if the Box2 contains the special empty value, false otherwise.

Time Data Values

The Time data value types are: Time Values (p. 751) Interval Values (p. 752)

Time Values
The Time class implements animation time in MAXScript. Time values reflect the properties of animation time in 3ds max. Resolution is in ticks, with 4800 ticks per second. You can work with time as ticks, frames, h.m.s, or normalized time. You can intermix numbers and time values in time computations defined below. The rule is that numbers are always interpreted as frame counts, with floating point numbers specifying fractional frames. The numbers are always converted to tick-based time values internally and so have an ultimate resolution of 4800 ticks per second. You can do time arithmetic and comparisons using numbers as well as time values and convert between time and (frame) numbers using the as operator. See also Time Literals (p. 662). Literals:
[-]{<decimal_number>[m | s | f | t]}+ [-]{<digit>}:{<digit>}[.{<digit>}] [-]<decimal_number>n -- minutes/sec/frames/ticks -- SMPTE mins:secs.frame -- active segment normalized time

Example Literals:
2.5s 1m15s 2m30s5f2t 125f 17.25f 1f20t 2:10.0 0:0.29 --------2.5 seconds 1 minute 15 seconds 2 minutes 30 seconds 5 frames 2 ticks 125 frames 17.25 frames 1 frame 20 ticks 2 minutes 10 seconds 0 frames (SMPTE) 29 frames (SMPTE)

Constructor:
normTime <float> -- time from normal fraction

Properties:
<time>.ticks <time>.frame <time>.normalized : Time as ticks : Time as frames : Time as normalized fraction of active segment

752

Chapter 9

Values

Operators:
<time> + <time> - <time> <time> * <time> / <time> <time> <time> <time> <time> <time> <time> <time> <time> <number> <number>

scale time
== <time> != <time> > <time> >= <time> < <time> <= <time> as <class>

You can coerce a time to a Number - you get the time in ticks. Methods:
random <time> <time> abs <time>

Examples:
sliderTime = 30 t2 = n as time if currentTime == 45 then ...

Some of the examples above refer to system global variables. See the 3ds max System Globals (p. 630) topic for more details.

Interval Values
An Interval class represents an interval of time. It has two time value components, start and end. The time values can be numbers or Times, numbers being interpreted as frame counts. Constructor:
interval <start_time> <end_time>

Properties:
<interval>.start <interval>.end : Time : Time

Undefined Value

753

Examples:
t = animationRange.start + 5 orig_anim_range=animationRange -- store original animation range animationRange=interval 0 100000 -- set real long animation range -- assign script controller, controllers range is the current -- animation range ControlObj.scale.controller=scale_script() -- assign a script to the controller ControlObj.scale.controller.script = controlscript -- reset animationRange back to original value animationRange=orig_anim_range

Some of the examples above refer to system global variables. See the 3ds max System Globals (p. 630) topic for more details.

Special Data Values

Undefined Value (p. 753) Ok Value (p. 754) Unsupplied Value (p. 754) DontCollect Value (p. 754)

Undefined Value
The Undefined class implements the value used in uninitialized variables and array members. There is one distinguished instance of the Undefined class in the reserved system variable undefined. Constructor:
undefined

Examples:
-- check to see if MyLight has a target if MyLight.target != undefined then -- distance from light to target dist=distance MyLight.pos MyLight.target.pos else -- distance from light to [0,0,0] dist=length MyLight.pos -- set CH_Hand1 to undefined so can test later to see if deleted deleteChangeHandler CH_Hand1; CH_Hand1=undefined

754

Chapter 9

Values

Ok Value
The Ok class implements the void value returned by some functions and expressions that dont have a meaningful value to return. There is one distinguished instance of the OK class in the reserved system variable OK.

Unsupplied Value
The Unsupplied class implements the value used to initialize unsupplied keyword parameters to functions. There is one distinguished instance of the Unsupplied class in the reserved system variable unsupplied. You can test to see whether a caller has supplied an optional keyword argument by comparing it with unsupplied. Constructor:
unsupplied

Examples:
fn walk_tree obj parent: = ( if parent == unsupplied then ... else ... ... )

DontCollect Value
The dontCollect value is used in for loops to signal that the value is not to be collected. See For Loop (p. 694) for details. dontCollect is a separate distinguished instance of the Undefined class, and so will fail in the way the undefined value does if used in computations. Constructor:
dontCollect

Examples:
-- collect all spheres with radius less than 5 little_spheres = for i in $* collect if classOf i == sphere and i.radius < 5 then i else dontCollect

DontCollect Value

755

Bitmap Values
The Bitmap class provides storage of and low-level access to 3ds max bitmaps. Bitmaps can be temporary objects that are resident only in memory, or they can be associated with a file on disk. Those bitmaps associated with files have a non-null .fileName property and are either load-only or save-only, but not both (this is with respect to file I/O; all bitmaps in memory can have their pixels modified by the setPixel() functions). You make load-only bitmaps with the openBitmap() and selectBitmap() functions. You make temporary or save-only bitmaps with the bitmap() constructor, or with the render(), copy(), or getChannelAsMask() functions. To make them savable, they must have a valid file name, supplied either on the constructor with a fileName: parameter or by setting the .fileName property. Constructors:
bitmap <width <height> [ [ [ [ [ filename:<filename_string> ] numframes:<integer> ] color:<color> ] gamma:<float> ] pixelAspect:<float> ] \ \ \ \

Creates an empty bitmap. The bitmap value returned is a savable bitmap. The filename: parameter allows you to set the name of the file the bitmap will be saved to using the save method. Specifying an existing bitmap file name does not load the contents of the bitmap file into the bitmap value. The numframes: parameter allows you to create a multi-frame bitmap. The color: parameter allows you to set the initial color of all pixels in the bitmap. For example:
b = bitmap 320 240 color:white

The gamma: parameter allows you to set the gamma for the newly created bitmap. For example:
b = bitmap 320 240 gamma:1.9 render camera:c to:b

The pixelAspect: parameter allows you to set the pixel aspect for the newly created bitmap. Note that it is not possible to change the gamma or pixel aspect of a bitmap once created, though you can copy one bitmap into a newly created one that has a different gamma or pixel aspect to achieve this effect.
openBitMap <filename_string>

Returns a bitmap value containing the contents of the specified bitmap file. If the specified bitmap file does not exist, a runtime error is generated. The bitmap value returned is a load-only bitmap.

756

Chapter 9

Values

selectBitMap [ caption:<open_dialog_title_string> ]

This method displays a Image Input selection browser for the user to select a bitmap file. Returns a bitmap value containing the contents of the selected bitmap file, or the value undefined if the user presses Cancel in the browser. The bitmap value returned is a load-only bitmap.
copy <bitmap>

Copies an existing bitmap, creating an unique instance of the bitmap. If the source bitmap is load-only, the bitmap value returned is a temporary bitmap value, with a null filename and just one frame. If the source is a multi-frame file, it snaps the current frame into the new copy, which becomes frame 0. Properties:
<bitmap>.filename <bitmap>.palette : String : Array

Lets you get or set the file name associated with the bitmap. Yields an array of 256 colors (a bug in the current 3ds max SDK prevents working with paletted files of other than 256 entries). Take care accessing this array with colors indexes retrieved by the getIndexedPixels() function described below, because these indexes are 0-based and MAXScript array indexes are 1-based. Yields undefined if the bitmap is not paletted. Currently you cannot create a paletted bitmap in MAXScript, however you can read and write to a pre-existing paletted bitmap.
<bitmap>.frame : Integer

Get and set the current frame number in a multi-frame file. Setting this property is permitted only on load-only bitmaps. The frame number is 0-based for inherently multiframe files, such as .avi and .mov.
<bitmap>.numframes <bitmap>.height <bitmap>.width <bitmap>.gamma <bitmap>.aspect : Integer : Integer, read-only : Integer, read-only : Float, read-only : Float, read-only

The number of frames in a multi-frame file, yields 1 for a single image file. Returns bitmaps height in pixels. Returns bitmaps width in pixels. Returns bitmaps gamma value. Returns the bitmaps pixel aspect. Note that this is the aspect of the pixel, not the aspect of the bitmap image. Methods:
display <bitmap>

Opens a virtual frame buffer (VFB) displaying the image. Changes to the bitmap are not automatically displayed to the VFB. To update the VFB, you need to call this function again. Setting the frame property does cause the VFB to update. Each bitmap has its own VFB, i.e., if you display two different bitmaps, two VFBs will be displayed.

DontCollect Value

757

unDisplay <bitmap>

Close the VFB associated with the bitmap if open.

save <bitmap> [frame:<integer>]

Saves current state of the bitmap. Make sure the file name has been set first. When saving multi-frame image files, the effect of the frame: keyword parameter is different depending on the type of output file. Inherently multi-frame files, such as .avi and .mov, ignore the frame: parameter and always write to the next output file frame in sequence on each save(); you cannot randomly write frames or rewrite frames already saved. Saving image sequences (such as .bmp, jpg, .tga) requires supplying the frame: parameter and causes the frame number to be appended to the output file name for each frame saved. This effectively generates a sequence of image files suitable for building an IFL. The output file remains open until you call close on the bitmap. The save() function can only be called on a savable bitmap. You will get a runtime error if you attempt to save a bitmap opened with openBitmap() or selectBitmap().
close <bitmap>

Closes the bitmap file associated with the bitmap if it is open for output. A bitmap file is opened for output when you call save on the bitmap value the first time. If a VFB associated with the bitmap is open, it will be closed. This function also frees all memory allocated by the bitmap, including the internal pixel frame buffer. If you are generating many bitmaps, say in a rendering loop, you can use the close() function to free these often large amounts of memory, that wont otherwise be released until the next garbage collection.
copy <source_bitmap> <dest_bitmap>

Copies the source bitmap to the destination bitmap. If the size of the two bitmaps is different, the image will be scaled to fit the destination bitmap.
gotoFrame <bitmap> <frame>

Position multi-frame file (avi, flc, etc.) to frame frame. This method is permitted only on load-only bitmaps. The frame number is 0-based for inherently multi-frame files, such as .avi and .mov. Updates VFB if open.
getPixels <bitmap> <coord_point2> <num_pixels>

Retrieve a sequence of pixels from a row in the bitmap as an array of color values. The coord_point2 argument specifies the starting pixel coordinate with [0,0] at the top-lefthand pixel. The .x component of the Point2 coordinate is the column, and the .y component is the row. The sequence must come from one row only; you cannot retrieve a sequence of pixels that spans multiple rows. Using any out of-bounds coordinates or retrieving over row boundaries will fail and yield an empty array.
setPixels <bitmap> <coord_point2> <color_value_array>

Sets the sequence of pixels in a row in the bitmap starting at the Point2 coordinate to the values in the given array. The .x component of the Point2 coordinate is the column, and the .y component is the row. The number of pixels to set is taken from the size of the array. As with getPixels(), you cannot set pixel sequences across a row boundary.

758

Chapter 9

Values

getIndexedPixels <bitmap> <coord_point2> <num_pixels>

Retrieve a row of pixels as an array of palette index numbers. The coord_point2 argument specifies the starting pixel coordinate with 0,0 at the top-left-hand pixel. The index numbers are origin 0. Note that this is in keeping with indexed color conventions but not MAXScripts. Take care accessing any retrieved palette array using these numbers because the retrieved palette is returned as a MAXScript array and these arrays use 1-based indexes. You cannot get pixels sequences that cross row boundaries.
setIndexedPixels <bitmap> <coord_point2> <number_array>

Sets the row of pixels starting at the Point2 coordinate to the color indexes in the given array. The number of pixels to set is taken from the size of the array. The color indexes are zero-based. You cannot set pixels sequences that cross row boundaries.
getChannel <bitmap> <coord_point2> <chan_name>

Retrieves the g-buffer channel data for the named channel for the pixel specified by 2D coordinate. The chan_name argument specifies the channel identifier, chosen from the following:
#zDepth #matID #objectID #UVCoords #normal #unClamped #coverage #node #shaderColor #shaderTransparency #velocity #weight

If the bitmap contains the requested channel, the returned value is always an array of values, one for each layer present in the channel at that pixel, ordered from front to back. If the bitmap does not contain the requested channel, the function returns the value undefined. Typically, you get bitmaps containing channels by opening .rla files or using the MAXScript render() function with the channels: parameter supplied. You will get multiple values in the array if the front objects have any transparency. For example:
getChannel bm [x,y] #zDepth

might return:
#(-354.413, -354.467, -355.271, -1e+030)

indicating there is a front surface with non-zero transparency at depth -354.413, another at -354.467 and a final one at -355.271. The 1e+30 value represents the background image plane. You could retrieve the #node channel (if it was generated) to get the actual scene objects at those depths, eg:
getChannel bm [x,y] #node

DontCollect Value

759

might return:
#($Sphere:Sphere02 @ [-4.7,24.3,0.0], $Sphere:Sphere02 @ [4.7,24.3,0.0],$Sphere:Sphere01 @ [-8.3,56.2,5.7])

The type of values returned in the array depend of the channel, as follows:
#zDepth #matID #objectID #UVCoords #normal #unClamped #coverage #node #shaderColor #shaderTransparency #velocity #weight : : : : : : : : : : : : <float> <integer> <integer> <point2> <point3> <color> <float> <node> <color> <color> <point2> <color>

See the 3ds max Software Development Kit Help file for information on the data stored in the g-buffer channels.
getChannelAsMask <bitmap> <chan_name> [to:<bitmap>] [fileName:filename_string] [pixelAspect:<float>] [gamma:<float>] [layer:<integer>] [invert:<boolean>] [node:<node> | objectID:<integer> | matID:<integer>] [velocity:#angle | #magnitude] | [angle:<float>] \ \ \ \

Builds and returns a separate 8-bit gray-level bitmap, suitable for use as a mask in materials, maps, effects, and so on. This bitmap corresponds roughly to the display you see in the visual frame buffer if you select a g-buffer channel to view. In addition, you can cause this mask to be masked itself to a selected node, object ID or material ID. The parameters are as follows:
<bitmap>

The source bitmap containing the source g-buffer channel data.

<chan_name>

The channel from which to generate a mask. The chan_name values are as described for the getChannel() method. Note that the mask is a single 8 bit value while the channel may be a complex value of some kind. In each case, a mapping to 8 bits is performed. Unless noted differently below, this mapping is the same mapping as in used by 3ds max to generate monochrome images in the Virtual Frame Buffer.
to:<bitmap>

Specifies an existing bitmap to write the mask into. Its width and height must match the source bitmap.
fileName:filename_string

Specifies the file name associated with the generated bitmap.

gamma:<float>

Specifies the generated bitmaps gamma value.

760

Chapter 9

Values

pixelAspect:<float>

Specifies the generated bitmaps pixel aspect. Note that this is the aspect of the pixel, not the aspect of the bitmap image.
layer: <integer>

Specifies the channel layer of the source bitmap to extract data from. Defaults to 1.
invert:<boolean>

If true, inverts the generated bitmap. Defaults to false.

node:<node> objectID:<integer> matID:<integer>

Specifies a sub-mask. If one of these parameters is supplied, the generated mask is clipped to contain data only in pixels where the given node, objectID or materialID is visible. To use this sub-masking, you must ensure the #node, #objectID or #matID channel is present in the source bitmap. Further, if the #coverage channel is present in the source bitmap, the sub-mask is anti-aliased by the coverage data.
velocity:#angle | #magnitude angle:<float>

These parameters can only be specified if the selected channel is #velocity. The default velocity parameter value is #magnitude. These parameters control the generated bitmap as follows:
velocity:#angle

Generated bitmap pixel values are proportional to angle of pixel movement direction, with an angle of direction of 0 degrees (horizontal to the right) mapping to a luminance value of 0, 180 degrees mapping to a luminance value of 127, and 360 degrees mapping to a luminance value of 255.
velocity:#magnitude

Generated bitmap pixel values are proportional to velocity magnitude. High velocities are darker than low velocities.
angle:<float>

Generated bitmap pixel values are proportional to movement direction deviation from the given angle, with a luminance value of 255 at the exact angle and falling off to a luminance value of 0 at 10 degrees from the specified angle. The specified angle is relative to 0 being horizontal to the right. Related Methods:
setSilentMode <boolean>

Sets Silent mode on or off. If Silent mode is off, any errors occurring during bitmap input or output will result in an error message dialog being displayed by the 3ds max bitmap I/O routines. If Silent mode is on, error message dialogs are not displayed. Returns a boolean signifying the prior Silent mode state. The Silent mode state is an internal 3ds max state, and other 3ds max plug-ins can turn this state on or off. It is recommended that if you use this method that you turn the state on or off saving the return value, perform the bitmap input or output, and then restore the state to its original value.

DontCollect Value

761

silentMode()

Returns a boolean signifying the Silent mode state.

selectSaveBitMap [ caption:<open_dialog_title_string> ]

Displays a 3ds max bitmap save dialog and returns the fully-specified file path name as a string. Returns undefined if the user cancels out of the bitmap save dialog.
freeSceneBitmaps()

Frees up all the memory used by the image file bitmap caches. This is useful if memory is fragmented with a lot of different bitmaps and you want to have just the ones currently active reloaded.
getBitmapOpenFileName caption:<title> filename:<seed_filename_string> getBitmapSaveFileName caption:<title> filename:<seed_filename_string>

Displays the bitmap file selection dialog. Both functions return a fully-specified file path name or undefined if the user cancels out. If an existing file name is selected using the getBitmapSaveFileName() function, a File Exists/Confirm Overwrite dialog will be displayed. Note: The getBitmapOpenFileName() function does not require that an existing file name be selected - i.e., a file name is returned if the user types a file name that does not exist. If necessary, you should check the file name that is returned to ensure the file exists. Notes: When you open a bitmap file, an entire frame is loaded into memory. When you are finished processing a bitmap, it is a good idea to either call close() on the bitmap or assign the value undefined to the variable storing the bitmap value, and then manually run garbage collection (gc()), so that its memory can be released. Another technique for conserving memory when using the render() or getChannelAsMask() functions repeatedly is to use the to:<bitmap> keyword argument which allows those functions to overwrite an existing bitmaps pixel image with the new rendering or mask. There currently is no access to the properties associated with the bitmap output plug-ins. This means that you cannot set the codec used for .avi files, nor the setup parameters for .rla and .tga files. The properties used are the properties that were last used when saving that file type in 3ds max . Examples: The following script shows how to properly create and save a multi-frame image file.

762

Chapter 9

Values

Script:
theTeapot=teapot() animate on at time 10 \ rotate theTeapot 180 z_axis cam=targetcamera pos:[200,0,100] \ target:theTeapot renderFrames=#{1,3,5..12} b=bitmap 160 120 filename:c:\\t.avi for i = 1 to renderFrames.count do ( if renderFrames[i] then ( at time i render 160 120 camera:cam to:b save b ) ) close b -----------------something to render set animate and time context rotate the teapot camera pointed at teapot specify frames to render create a new bitmap loop though renderFrames if supposed to render frame... set time context render to bitmap frame save each frame as you advance if you save AFTER the loop, just the last frame is saved. close the output file. This will also get rid of the reference to the bitmap value and free its memory.

Output:
$Teapot:Teapot01 @ [0,0,0] OK $Target_Camera:Camera01 @ [200,0,100] #{1, 3, 5..12} BitMap:c:\t.avi OK OK -------result result result result result result result of of of of of of of line 1 lines 2 and 3 lines 4 and 5 line 6 line 7 for loop, lines 8 to 15 line 16

The following script reads a bitmap file, and outputs a script to Listener that implements a function that will recreate the same bitmap. This function can then be copied into your script. This is useful for building button images in MAXScript, so that you dont need to distribute bitmap files along with your script. Script:
( b=selectbitmap() -- open image file browser bname=bitmap_+(getfilenamefile b.filename) -- build name from filename w=b.width -- get properties of bitmap h=b.height format ----------\nfn load_% = (\n bname -- start defining function format local %=bitmap % %\n bname w h -- create bitmap in function -- write out a function that unpacks an integer into a pixel color format fn unpack val = for p in val collect (r=p/256^2; g=p/256-r*256; b=mod p 256; color r g b)\n for r=0 to h-1 do -- for each row in the bitmap -- have function write the column of pixels to the bitmap ( format setpixels % [0,%] (unpack #( bname r pixels=getpixels b [0,r] w -- read in the column of pixels for c=1 to w do -- loop through each pixel

FileStream Values

763

p=pixels[c] -- get the pixel -- pack the pixel into an integer and write it out format % (((p.r as integer)*256+(p.g as integer))*256+(p.b as integer)) if c != w then -- if not at end of data format , -- write a comma else format ))\n -- else close out the line

) ) format return %\n bname format )\n----------\n )

-- function returns the bitmap -- finish off function definition

Output:
---------fn load_bitmap_convert = ( local bitmap_convert=bitmap 4 4 fn unpack val = for p in val collect (r=p/256^2; g=p/256-r*256; b=mod p 256; color r g b) setpixels bitmap_convert [0,0] (unpack #(12632256, 12632256, 12632256, 12632256)) setpixels bitmap_convert [0,1] (unpack #(255, 255, 255, 255)) setpixels bitmap_convert [0,2] (unpack #(255, 255, 255, 255)) setpixels bitmap_convert [0,3] (unpack #(255, 12632256, 12632256, 12632256)) return bitmap_convert ) ----------

Also see the example in the Point3 Values (p. 731) topic for another usage of class Bitmap.

Stream Values
Stream values are used to format and hold character data. You can read and write character data to Stream values. The types of Stream values are: FileStream Values (p. 763) StringStream Values (p. 766) WindowStream Values (p. 767)

FileStream Values
A FileStream class implements text file input and output in MAXScript. A FileStream value represents an open text file in MAXScript. Text file I/O is performed by calling functions on the FileStream value. Constructors:
createFile <filename_string>

creates a new file and returns a <filestream> value. If the specified file cannot be created, the value undefined is returned.

764

Chapter 9

Values

openFile <filename_string> [ mode:<mode_string> ]

opens an existing file and returns a <filestream> value. If the specified file does not exist, the value undefined is returned. The optional mode_string can be a to mean open an existing file for append output, or r to mean open file read-only.
openEncryptedFile <filename> <key>

opens the encrypted file using the given integer key and returns a FileStream value that you can then do read calls on, exactly as you can on FileStreams returned from the openFile() function. See the Encrypted Files (p. 1647) topic for details on encrypted files. Methods:
readLine <filestream>

read next line, return as string

readChar <filestream>

read next char, return as string

readChars <filestream> <char_count>

reads the specified number of characters and returns them in a string.

readDelimitedString <filestream> <string>

takes a delimiter character (as a string) and reads in characters until the delimiter is found (or end-of-file is reached) and returns the characters in a string.
skipToString <filestream> <string>

takes a character string and scans forward in the file until it finds an occurrence of the string and positions the file just after that string. If the string is not found, the function returns the value undefined.
skipToNextLine <filestream>

positions the input file at the beginning of the next line

filePos <filestream>

retrieve the current offset into the file

seek <filestream> <integer>

position the file at the given offset so that subsequent I/O will start there.
eof <filestream>

return true if there is no more data in the file, false otherwise.

flush <filestream>

ensure all output to file is on disk, flushes the memory buffers.

close <filestream>

flushes the memory buffers and closes the file For the following methods, see the description of the execute() method in the String Values (p. 722) topic for information on the scope of variables used in the evaluated expressions.
readValue <filestream>

read and evaluate the next MAXScript <operand> from the file
readExpr <filestream>

read and evaluate the next MAXScript <expr> from the file

FileStream Values

765

execute <filestream>

read and evaluate all the expressions left in the file. The differences between the above methods can be seen in the following example. In this example, a stringstream value is created that contains a string containing two expressions random 0. 1. and random red blue. The readValue, readExpr, and execute methods are then used with the stringstream as the argument. Script:
s=stringstream random 0. 1.;random red blue readvalue s -- read and evaluate the first value readvalue s -- read and evaluate the second value seek s 0 -- position at beginning of stringstream readexpr s -- read and evaluate the first expression readexpr s -- read and evaluate the second expression seek s 0 -- position at beginning of stringstream execute s -- evaluate all expressions

Output:
StringStream:random 0. 1.;random red blue -- result random() -- result line 2 (evaluated 0.0 -- result line 3 (evaluated OK -- result line 4 0.448042 -- result line 5 (evaluated (color 86.476 0 163.24) -- result line 6 (evaluated OK -- result line 7 (color 30.2417 0 143.636) -- result line 7 (evaluated -returns result of line 1 random) 0.) random 0. 1.) random red blue) all expressions, last expression)

Associated Methods:
print <value> to: <filestream> format <fmt_string> { <value> } to: <filestream>

See the Value Common Properties, Operators, and Methods (p. 714) topic for a description of these methods.

See also
External File Methods (p. 1645) File Name Parsing (p. 1644) Standard Open and Save File Dialogs (p. 1643)

766

Chapter 9

Values

StringStream Values
The StringStream class allows you to construct and parse strings using all the text file I/O functions. For example, you can set up a StringStream and build it up by performing prints and formats to it, just as you would to a text file. Conversely, you can convert a String into a StringStream and then work through it using functions like readLine(), readValue(), skipToString(), etc. Since Strings are easily converted to and from StringStreams, this is often a convenient way to work on large, complex strings. The StringStream class can be used in conjunction with the AppData accessing functions for storing and retrieving large and complex amounts of script-generated data permanently within a 3ds max scene file. Constructors:
stringStream <initial_string> <string> as stringStream

convert existing String to StringStream. See also the String Literals (p. 660) and String Values (p. 722) topics. Operators:
<stringstream> as string

convert StringStream to a String Methods:

copy <stringstream>

create a separate copy of the StringStream Associated Methods:

print <value> to:<stringstream> format <fmt_string> {values} to:<stringstream>

The print() and format() functions provide a way to build up a StringStream a piece at a time. As with text file output, each call to print or format appends to existing text, the StringStream dynamically grows as needed. Note that you can reposition output streaming using the seek() function documented below. The following functions are identical to the text file input functions available for text FileStream values. See the FileStream Values (p. 763) class documentation for details. When called on StringStream instances, they read progressively through the string extracting successive values and lines and characters, etc.
readValue <stringstream> readExpr <stringstream> readLine <stringstream> readChar <stringstream> readChars <stringstream> <number> readDelimitedString <stringstream> <string> skipToString <stringstream> <string> skipToNextLine <stringstream> execute <stringstream>

WindowStream Values

767

filePos <stringstream> seek <stringstream> <pos> eof <stringstream> close <stringstream> flush <stringstream>

The close() and flush() functions are provided for consistency with file I/O but are not necessary for StringStreams and do nothing if called.

WindowStream Values
The WindowStream class allows you to output strings to a script Editor window. This is useful for directing output to a separate window for ease of inspection, editing, or later saving to a file. Constructors:
newScript()

Opens an empty script Editor window and returns a WindowStream value. Associated Methods:
print <value> to:<windowstream> format <fmt_string> {values} to:<windowstream>

Output to a WindowStream is inserted at the current cursor position in that window. Notes: When using the format() function with a WindowStream, a new line in the Editor window is not displayed until an end-of-line character (\n)is output. Examples:
debug = newScript() ... print $foo to:debug ... format name is %\n obj.name to:debug

MAXKey Values
Certain controllers (keyframeable controllers) store their animation values as keys. As seen by MAXScript, keys are stored in a MAXKeyArray. The MAXKeyArray for a keyframeable controller is accessed via the .keys property of the controller. For more information on MAXKeyArrays, see the MAXKeyArray Values (p. 793) topic.

See also
MAXKey Common Properties, Operators, and Methods (p. 768) Working with MAXKey Values (p. 769)

768

Chapter 9

Values

MAXKey Common Properties, Operators, and Methods

Constructor:
addNewKey <controller> <time> [ #select ] [ #interpolate ]

Adds a new key to the controller track at the time specified. The new key is also selected in the track view if the #select optional argument is specified. The value for the new key is taken from the previous key, unless the #interpolate argument is specified in which case the value is the interpolated controller value at that time.
getKey <controller> <index_integer>

Returns the indexed key as a MAXKey instance.

<key_array>[<index_integer>]

where <key_array> is:

<controller>.keys <node>.<animatable_property>.keys

Properties: For keys associated with all keyframeable controller types, the following properties are accessible:
<key>.time <key>.selected access. Time Boolean -- time value or number (interpreted as frames) -- specifies whether the key is selected. Read/write

The .time property is read-only for the keys for some controllers, and read/write for the keys of other controllers. The controller type description specifies whether the .time property is read-only or read/write. For controllers where the key .time property is read/write, the following properties are also available:
<key>.value varies -- class determined by its containing controller

Methods:
copy <key>

Creates a copy of the key value. This copy is not independent of the original key, as a key value always references a key in a controller. This method exists primarily to support copying of arrays. The keys on Bzier, TCB, and Barycentric Morph controllers have additional properties and methods. See the Bezier Controller Keys (p. 1310), TCB Controller Keys (p. 1335), and Barycentric Morph Controller Keys (p. 1308) topics for details.

See also
MAXKeyArray Values (p. 793) Controller Common Properties, Operators, and Methods (p. 1289) Value Common Properties, Operators, and Methods (p. 714)

Working with MAXKey Values

769

Working with MAXKey Values

Changing the .time property of a key may cause it to go out of time order relative to the other keys in the controller. You must call the sortKeys() function on the controller or associated MAXKeyArray once all key time manipulations of this kind is complete so that animation will perform correctly. The class of a keys value property is determined by the controller it is in, for example, a linear_float key has a float .value, a tcb_rotation key has a quaternion .value, etc. The properties are all settable and support the math-assignment operators and nested-property access. Here are some examples:
$foo.pos.keys[2].time += 20f -- change time of single key $foo.pos.keys.time += 20f -- change time of all keys $box1.uvw_map.center.keys[2].value.x += 20 for k in $baz.bend.angle.keys do k.value *= 1.1

In some cases, the actual value stored in a key is not the value shown in the command panels, shown in Track View, the value returned by the .value property of the key, or the value returned when accessing the property to which the keys controller is assigned. Instead, a scaling factor is applied to the keys value before the value is made visible. For example, percentages are normally displayed with a range of 0-100, rotation angles are in degrees, colors are [0-255,0-255,0-255]. The unscaled key values for percentages are normally in a range of 0-1, rotation angles in radians, and colors are [0-1,0-1,0-1]. In the description of properties for each class, the scaling factor, if any, is identified for each property. Take for example the following properties for the PArray class:
<PArray>.X_Spin_Vector <PArray>.Spin_Time_Variation <PArray>.Spin_Phase <PArray>.viewPercent Float Float Float Float default: default: default: default: 1.0 0.0 0.0 10.0 ----animatable animatable, percentage animatable, angle percentage

The .X_Spin_Vector property does not apply any scaling to its controller keys. The .Spin_Time_Variation property applies percentage scaling to its controller keys (displayed as percentage, stored as fraction). The .Spin_Phase property applies angle scaling to its controller keys (displayed as degrees, stored as radians). The .viewPercent property is stored internally with a percentage scaling factor, but since this property is not animatable, this scaling it invisible to MAXScript. Normally this scaling is not of concern when programming in MAXScript, but there are two cases where it must be taken into account. The first is when using script controllers, and is described in the Script Controllers (p. 1329) topic.

770

Chapter 9

Values

The second case is when one controller is applied as the controller for two or more properties. The scaling is an attribute of the animatable property, not the controller, so in (the admittedly rare) situations in which a controller is shared by several animatables that have different scaling, unexpected results will occur if you do not take into account the scaling factor. An example of this is shown in the following script, where the same controller is shared between three differently scaled properties. Script:
obj=PArray() cont=bezier_float() obj.X_Spin_Vector.controller=cont obj.Spin_Time_Variation.controller=cont obj.Spin_Phase.controller=cont obj.X_Spin_Vector=1 obj.X_Spin_Vector -- no scaling obj.Spin_Time_Variation -- percentage obj.Spin_Phase -- angle

Output:
$PArray:PArray03 @ [0,0,0] Controller:Bezier_Float Controller:Bezier_Float Controller:Bezier_Float Controller:Bezier_Float 1 1.0 100.0 57.2958 degrees ---------result result result result result result result result result line line line line line line line line line 1 2 3 4 5 6 7, unscaled 8, percentage scaled, 1 = 100% 9, angle scaled, 1 radian = 57.2958

If you do assign the same controller to properties with different scaling factors, you should take care to access the .value property through the correct animatable property - this provides a scaling context for the access operation.

ArrayParameter Values
Certain plug-ins in 3ds max store parameter data in a form that is accessible by MAXScript as ArrayParameters. As such, you can access the parameter data by index and iterate over the parameter data. Constructors:
<MAXWrapper>.parameter

Where the parameter contains an ArrayParameter. Properties:

<ArrayParameter>.count

Returns the number of values in the ArrayParameter. Read-only in most cases, with exceptions noted in the MAXWrapper object description where an adjustable ArrayParameter is used.

Working with MAXKey Values

771

Operators:
<ArrayParameter>[<integer>]

Returns element of ArrayParameter. Indexes start at 1.

<ArrayParameter>[<integer>] = <value>

Sets element of ArrayParameter to value. Notes: Each ArrayParameter can only contain data of a certain type (for example, Float), or a controller that matches that data type. The showProperties() function indicates these array parameters as <type> array, for example, int array, texmap array, etc. A plug-in can also define parameter names which point to specific entries in one of its ArrayParameters. For example, mapAmounts is a property of Standard materials containing an ArrayParameter. Each element in this ArrayParameter contains the map amount for one of the map channels. For easier access in a script, the Standard .ambientMapAmount property is provided as an alias for mapAmounts[1] (along with aliases for all the other common maps). You can access the controller for the ambientMapAmount alias either via the .controller property on the alias or on the .mapAmounts[1] property. For example, either:
$foo.material.ambientMapAmount.controller

or
$foo.material.mapAmounts[1].controller

will get the controller on the ambient map amount material property. Examples: The following script shows the use of showProperties() to show the data type for elements of ArrayParameters, access to ArrayParameter elements, and a case of a plug-in defining parameter names which point to a specific entry in one of its ArrayParameters. Script:
m=CompositeMaterial() showproperties m m.amount m.amount[1] *= .5 m=standard() showproperties m m.ambientMapAmount=13 m.mapAmounts[1] --------create a Composite material show the properties for the material show value of parameter amount reduce the value for one element create a Standard material show its properties set the value for one element via its alias and show the element was changed

772

Chapter 9

Values

Output:
compositematerial:Composite -- result line 1 .materialList (Material : material array -- output line 2 .mixType (Composite Type) : int array -- ArrayParameter elements are integer .mapEnables (Map Enable) : bool array -- ArrayParameter elements are boolean .amount : float array -- ArrayParameter elements are float OK -- result line 2 #(100, 100, 100, 100, 100, 100, 100, 100, 100, 100) -- result line 3 50.0 -- result line 4 Standardmaterial:Standard -- result line 5 .mapEnables (Map Enables) : bool array -- pruned output line 6 .maps : texmap array .mapAmounts (Map Amounts) : percent array .ambientMap (alias for maps[0]) .ambientMapAmount (alias for mapAmounts[0]) .ambientMapEnable (alias for mapEnables[0]) .bumpMap (alias for maps[8]) .bumpMapAmount (alias for mapAmounts[8]) .bumpMapEnable (alias for mapEnables[8]) 13 -- result line 7 13.0 -- result line 8

Chapter 10:

Collections

Many of the values you work with in MAXScript are sequenced collections, notably arrays, wild-card pathname selections, and the built-in object sets. In the manner of most operating system shell command languages, MAXScript will automatically apply appropriate operations to each of the members in these target collections. Examples:
hide $lights/key* $box*.position = [0,0,0] delete dead_objects obj.pos.keys.intangent=#fast lights.value *= 0.8 ------hide all the key lights in the scene recenter all boxes delete all the objects in the array dead_objects set in tangent to fast for all objs position keys turn down all the lights 20%

MAXScript determines whether to perform a mapped operation by looking at the first argument to a function or the target in a property assignment to see if it is a sequenced collection. In the case of a function call, it also looks to see if the function is of the appropriate kind, evaluates all the other argument expressions once only. MAXScript then calls the function on each of the members of the first argument collection passing along the other evaluated arguments. In the case of a property assignment, it evaluates the right-hand-expression once only and assigns the value to the named property of each of the elements in the target value collection. This means that every element in the collection must be a valid target for the function or have the named property in question. If MAXScript comes across an inappropriate target it will report an error and stop the automatic operation. Except for certain common properties, MAXScript currently only allows automatic collection mapping of property assignment one level deep. For example, the following will perform collection mapping across the objects ObjectSet:
objects.pos = [0,0,0] -- move all objects to world center

774

Chapter 10

Collections

If the last level specified is one of the following component names, the automatic collection mapping is performed on the preceeding property:
.angle .b .blue .axis .controller .g .green .isAnimated .keys .r .red .track .x .x_rotation .y .y_rotation .z .z_rotation

For example:
objects.pos.z = 0.0 -- move all objects to world XY plane

This behavior of calling a function on all the elements of a collection is known as mapping in computer science. In the description of each collection type, you will find those kinds of sequenced collections that can be mapped over identified as mappable. In the descriptions of the various functions and operators throughout this document, those that act on each element in a collection are labeled mapped. In general, the functions that are mapped are those that have some side-effect on the value they take, such as moves, and deletes and hides. Others, like the test function isHidden(), are not mapped because it would be pointless. All mapped functions defined by MAXScript, such as copy(), delete(), or move(), take an optional last argument, #noMap. This causes the functions not to be mapped when called on collection arguments such as arrays. When used with copy() on arrays in particular, this will return a top-level copy of the array itself and not perform an individual copy() on each element of the array. You can make your own mapped scripted functions by preceding the function definition with the reserved word mapped, for example:
mapped function rand_color x = (x.wireColor = random black white)

This causes such functions to be automatically called repeatedly on the elements of a collection if a collection is given as the first argument to the function. The #noMap argument is not applicable to user-written functions.

775

As described in the For Loop (p. 694) topic, a for loop can be set up to iterate through a collection set assigning successive elements in the collection to the loop value each time through the loop. For loops can also be set up to return an array collection set as its result. Examples:
for item in table1 do x = x + item.height -- sequence an array bigones = for obj in $box* -- you can sequence pathnames! where obj.height > 100 collect obj -- collect the big boxes -- into an array

When iterating through a collection set using a for loop, or when passing a collection to a mapped function, care must be taken not to reorder or remove elements in the collection set within the for loop or function. Take for an example a script that is supposed to convert all of the selected splines into NURBS curves. Two scripts that do not execute properly are:
for obj in selection do ( convertToNURBSCurve obj) convertToNURBSCurve selection

The reason neither of these lines execute properly is that the convertToNURBSCurve() function clears the current selection. So only the first spline is passed to convertToNURBSCurve() and converted. Since convertToNURBSCurve() is a built-in function, there is no way to modify this behavior. To get around this problem, you need to first snapshot the selection collection set as an array using the as operator, or use the getCurrentSelection() function, which returns the current selection set as an array. Two scripts that execute properly are:
for obj in (selection as array) do ( convertToNURBSCurve obj) convertToNURBSCurve (getCurrentSelection())

Collection Types
Array Values (p. 776) PathName Values (p. 780) ObjectSet Values (p. 781) SelectionSet Values (p. 785) SelectionSetArray Values (p. 783) NodeChildrenArray Values (p. 785) VertexSelection Values (p. 786) FaceSelection Values (p. 788) EdgeSelection Values (p. 790)

776

Chapter 10

Collections

KeyArray Values (p. 793) MAXNoteKeyArray Values (p. 794) ModifierArray Values (p. 794) MaterialLibrary Values (p. 795) NURBSSet Values (p. 797)

Array Values
An array is a variable length indexable sequence of values. The values in an array can be of any type. Array values are mappable. Literals:
#(<value>, <value>, ...) #() -- an empty array

See also Array Literals (p. 666). Constructors:

<collection> as array

Convert collection to an array. Properties:

<array>.count : Integer, read-only

Returns number of elements in array. Operators:

<array>[<integer>]

Returns element of array. Indexes start at 1.

<array>[<integer>] = <value>

Sets element of array to value, growing array as necessary.

<array> + <collection>

Like join except a completely new array is constructed containing all the elements of the first and second operands For example:
a = #(1,2,3,4) join a #(5,6,7,8) (cameras as array) + lights props = getPropNames Node join props getPropNames (classOf $foo) join props getPropNames $foo $dynamicOnly sort props

Array Values

777

Methods:
append <array> <value>

Append value to array, growing it as necessary.

copy <array> [#noMap] -- mapped

Creates a copy of all the elements in the array. Returns a value of OK. If #noMap is specified, the copy made is what is called a shallow copy - only a copy of the upper-level value itself (that is, the array value) is created. Copies arent made of values stored in the array, rather a reference to the same value is stored in both array values.
deleteItem <array> <number>

Delete element indexed by number from array, shrinking it in size by 1.

join <array> <collection>

Appends all the elements of the second argument to the array (first) argument.
sort <array>

Sorts the elements of the array into ascending order. All the elements must be comparable.
findItem <array> <value>

Does a MAXScript == comparison between elements in the array and the target object and then returns the index of the first occurrence of the given value in the array or zero if the value is not in the array. Values such as Point3s and Strings match if they have the same contents.
insertItem <value> <array> <integer>

Inserts the value at the specified index in the array, growing the array if necessary
qsort <array> <function> [start:<integer>] [end:<integer>] [user-defined key args passed to function]

Sorts the array using the specified function for element-by-element comparison. The comparison function must take 2 values as arguments, and return a number < 0 if the first value is less than thesecond value, 0 if the values are equivalent, and a number > 0 if the first value is greater than the second value. The entire array is sorted unless a start or end value is specified. For example, the following script generates 10 random positions, and then sorts the positions based on their distance from [0,0,0]:
positions=for i=1 to 10 collect (random [0,0,0] [100,100,0]) qsort positions (fn distFrom0 v1 v2 = (length v1)-(length v2))

778

Chapter 10

Collections

All key arguments are now passed to the comparison function. This allows you to do things like an indexed sort:
fn compareFN v1 v2 valArray: = (local v1i = valArray[v1] local v2i = valArray[v2] (length v1i)-(length v2i) ) positions=for i=1 to 10 collect (random [0,0,0] [100,100,0]) indexArray = for i = 1 to positions.count collect i qsort indexArray compareFN valArray:positions for i = 1 to positions.count do print positions[indexArray[i]] amin ( <array> | {value} )

Returns minimum value of items in the array or of the argument values. If the array size is zero orno arguments are specified, the value undefined is returned. Examples:
myMin1 = amin #(5,1,4,2,8) myMin2 = amin 5 1 4 2 8 amax ( <array> | {value} )

Returns maximum value of items in the array or of the argument values. If the array size is zero orno arguments are specified, the value undefined is returned. Notes: As described in the Reference Assignment (p. 653) topic, the elements in an array are stored by reference rather than by value. When you operate directly on array elements, and the reference to the array is stored in more than one place, unexpected results may occur. An example of this is shown in the following script. Script:
RandomSets=#() -- create array RandomSet=#() -- create array for i=1 to 3 do -- loop i ( for j=1 to 3 do -- for each i loop j RandomSet[j]=random 1 100 -- set array element to random value print RandomSet #nomap -- print array of random values RandomSets[i]=RandomSet -- store random value array in array ) print RandomSets -- print array of arrays of random values

Output:
#() #() #(33, 47, 31) #(4, 52, 39) #(52, 36, 23) OK #(52, 36, 23) #(52, 36, 23) #(52, 36, 23) OK -------result of line 1 result of line 2 output from line 6, i=1 output from line 6, i=2 output from line 6, i=3 result of for loop, lines 3 to 8 3 lines of output from line 7

-- result of line 9

Array Values

779

As can be seen in the output lines 7 to 9, all the elements of array RandomSets contain the same values, which is not the result as expected from the output shown on lines 3 to 5. The reason the same values are stored in each element of RandomSets is only one array value is actually ever created for RandomSet (in line 2), and line 5 of the script is only changing the elements of that array value. Thus each element of RandomSets is actually pointing at the exact same value. The easiest fix for the above script is to move line 2 into the for i loop expression, thereby creating a new array value which will then be stored in RandomSets. Script:
RandomSets=#() for i=1 to 3 do ( RandomSet=#() -- create a new array value for RandomSet for j=1 to 3 do RandomSet[j]=random 1 100 print RandomSet #nomap RandomSets[i]=RandomSet ) print RandomSets

Output:
#() #(89, #(87, #(74, OK #(89, #(87, #(74, OK 27, 88) 87, 10) 27, 64) 27, 88) 87, 10) 27, 64)

You can convert object sets and wild-card pathnames to arrays using the as operator. This has the effect of taking a snapshot into the array of the current objects in the set or those matched by the pathname, so that you can then later work on that collection of objects without worrying if the set or match has changed. This is similar to named selection sets in the 3ds max user interface, and can be used, for example, to keep track of selections as you work interactively with MAXScript. If the user deletes from the scene any of the objects in the array, you will get an error if you try to map operations over the array. Examples:
sel1 = selection as array boxes_at_load = $box* as array snap_children = $torso...* as array original_cameras = cameras as array

780

Chapter 10

Collections

PathName Values
PathNames provide the mechanism for naming objects in the 3ds max scene. See also the Pathname Literals (p. 662) topic. Pathname values are mappable. Example Literals:
$box01 $torso/left_upper_arm/left_lower_arm $*box* $torso/* $torso...*

Properties:
<pathname>.center <pathname>.max <pathname>.min <pathname>.count : Point3, read-only : Point3, read-only : Point3, read-only : Integer, read-only

Returns center of bounding box of all objects in pathname. Returns maximum corner of bounding box. Returns minimum corner of bounding box. Returns number of objects in set. This property is only valid for wild-carded pathnames, i.e., a pathname that could contain more than one scene object. Operators:
<pathname>[<integer>] <pathname> as array -- accesses member of collection. Indexes start at 1. -- converts pathname collection to an array

Associated Methods:
isDeleted <MAXWrapper_object>

This function yields the result true if the object has been deleted and false if it still exists in the scene. Using the function only makes sense in situations where references to 3ds max objects are held in variables or arrays or passed as parameters and you want to determine whether the object has been deleted from the scene. Performing an operation on a deleted 3ds max object referenced in a variable or array otherwise generates an exception. Any kind of 3ds max object can be tested in this way, scene objects, modifiers, controllers, materials, etc. For example:
myBoxes = $box* as array -- store list of all boxes in array myBoxes ... -- <one or more objects in the selection are deleted -- by the user or other scripts> ... for obj in myBoxes where not isDeleted obj do move obj [10,0,0]

ObjectSet Values

781

Notes: The order of sequencing is consistent in a stable scene but somewhat arbitrary - it depends on how 3ds max stores its object hierarchy internally which is affected mostly by order of additions and deletions to and from the scene. MAXScript lets you set up a working level in the 3ds max scene hierarchy that affects pathnames and coordinate systems and object creation. You do this with a <level_expr>, one of the many context expressions that are described in the Context Expressions (p. 681) topic. Examples:
a = $*feet*[i] -- retrieves the ith object in the *feet*s

-- tell me what things inside dummy have a non-identity scale for obj in $dummy...* where obj.scale != [1,1,1] do format % has non-identity scale: %\n obj.name obj.scale -- place $foos pivot point at the max corner of the set of box* objects. $foo.pivot = $box*.max in $dummy ( sphere name:ear1 pos:[10,10,10] -- create as children of $dummy sphere name:ear2 pos:[-10,10,10] scale $foo/* [1,1,2] -- looks for foo as a child of $dummy )

ObjectSet Values
ObjectSets represent the main scene object categories in 3ds max. The constructors below are all reserved system variables. ObjectSet values are mappable. Constructors:
objects geometry lights cameras helpers shapes systems spacewarps selection -- all the objects -- the standard 3ds max categories...

-- the current selection

Properties:
<objectset>.center <objectset>.max : Point3, read-only : Point3, read-only

Returns center of bounding box of all objects in set. Returns maximum corner of bounding box.

782

Chapter 10

Collections

<objectset>.min <objectset>.count

: Point3, read-only : Integer, read-only

Returns minimum corner of bounding box. Returns number of objects in set. Operators:
<objectset>[<integer>] <objectset> as array -- accesses member of collection. Indexes start at 1. -- converts objectset collection to an array

Associated Methods:
clearSelection()

Clears current scene node selection.

deselect <PathName>

Deselects given node(s). For example:

deselect $box*

deselects all items whose names start with box.

select <PathName>

Deselects any current selection first, then selects the node(s) you specified.
selectMore <PathName>

Adds the specified node(s) to the current selection.

getCurrentSelection()

Returns the current selection as an array. This is equivalent to selection as array, but can be significantly faster if there are very large numbers of objects in the scene. Notes: ObjectSets are actually special types of value that denote their sets, stored in reserved system variables of the same name, so you can assign them to other variables and pass them around as function arguments, etc. When storing an ObjectSet to a variable, the ObjectSet value is stored rather than the objects in the ObjectSet. To store the objects currently in the ObjectSet to a variable, first convert the ObjectSet to an array using the as operator. You can use ObjectSets as the root of a pathname, like this:
$helpers/d*

which limits the pathname searching to the object set youve specified. So, in the above example, it will name only helper objects that start with d. The order of sequencing is consistent in a stable scene but somewhat arbitrary - it depends on how 3ds max stores its object hierarchy internally which is effected mostly by order of additions and deletions to and from the scene.

SelectionSetArray Values

783

The lights and cameras object sets include the target objects, if any, for the lights and cameras. If you want to change a property value for all the lights or cameras, you will need process each object in the ObjectSet individually, testing to make sure it is a light or camera. For example, to increase the multiplier property value for all lights, you would say:
for obj in lights do if iskindof obj light do obj.multiplier *= 1.3

Examples:
s = selection[1] -- grab the first object in the -- current selection move camera[2] [x, y, z + 10] -- move the second camera -- select everything within a 100 units of $foo for o in objects where distance o $foo < 100 do selectmore o

SelectionSetArray Values
The SelectionSetArray class has only one instance, selectionSets, which is an array of all the named selection sets in the current scene. The named selection sets correspond to the selection sets in the Named Selection Set drop-down list on the 3ds max toolbar. Also see the SelectionSet Values (p. 785) topic. SelectionSet values are mappable. Constructors:
selectionSets

Properties:
<selectionsetarray>.count : Integer, read-only

Returns number of named selection sets. Operators:

<selectionsetarray>[<set_name>]

Accesses member of collection by named selection set name. set_name can be either a String or Name value.
<selectionsetarray>[<set_index_integer>]

Accesses member of collection by index number. Indexes start at 1.

<selectionsetarray>[<set_name>] = <node_array>

Create or replace named selection set with name set_name, which can be either a String or Name value. node_array must be an array of nodes. Methods:
deleteItem <selectionsetarray> <set_name>

Delete the named selection set with name set_name, which can be either a String or Name value.

784

Chapter 10

Collections

Associated Methods:
getNumNamedSelSets()

Returns number of named selection sets as an integer.

getNamedSelSetName <set_index_integer>

Returns name of the indexed named selection set as a string. <set_index_integer> is 1 based.
getNamedSelSetItemCount <set_index_integer>

Returns name of the indexed named selection set as a string. <set_index_integer> is 1 based.
getNamedSelSetItem <set_index_integer> <node_index_integer>

Returns indexed node in the indexed named selection set as a node. <set_index_integer> and <node_index_integer> are 1 based. Examples: You access an individual selection set by indexing the selectionSets array with its name or index:
set1 = selectionSets[my set 1]

You can then use that set just as you would use any other object set in MAXScript, such as selection, objects, lights, etc. For example,
move set1 [10,0,0]

moves all the objects in the set across 10 in x. You can use strings or MAXScript names (starting with #) interchangeably as indexes for the selectionSets array, or you can use an integer as an index if you want to loop over all the sets, for example:
selectionSets[#set2].wireColor = red for i in 1 to selectionSets.count do saveNodes selectionSets[i] (set + i as string + .max)

You can change, add and delete new Name Selection Sets by using the standard array methods on the selectionSets array:
selectionSets[new set] = selection selectionSets[old spheres] = $sphere* -- snap the current selection -- all the current objects named -- sphere*

selectionSets[#foo] = #(obj1, obj2, obj3) deleteItem selectionSets old set -- delete the set named old set

SelectionSet Values

785

SelectionSet Values
A SelectionSet represents the named scene node selection sets in the Named Selection Sets drop-down list in the 3ds max toolbar. Also see the SelectionSetArray Values (p. 783) topic. SelectionSet values are mappable. Constructors:
selectionSets[<set_name>] selectionSets[<index>] -- set by string or name value -- set by order in drop-down list

Operators:
<selectionset>[<integer>] -- retrieve nth object in set

Properties:
<selectionset>.center <selectionset>.max <selectionset>.min <selectionset>.count : Point3, read-only : Point3, read-only : Point3, read-only : Integer, read-only

Returns center of bounding box of all objects in set. Returns maximum corner of bounding box. Returns minimum corner of bounding box. Returns number of objects in set. Notes: Unlike ObjectSet, you cannot use SelectionSet as the root of a pathname. The order of sequencing is consistent in a stable scene but somewhat arbitrary - it depends on how 3ds max stores its object hierarchy internally which is effected mostly by order of additions and deletions to and from the scene.

NodeChildrenArray Values
A NodeChildrenArray represents the direct children of a scene node as a virtual array. As such, you can iterate over the children, apply mapped functions to them and obtain certain properties such as count and bounding box info. Also see the General Node Properties (p. 836) topic. NodeChildrenArray values are mappable. Constructors:
<node>.children

Properties:
<nodechildrenarray>.center <nodechildrenarray>.max : Point3, read-only : Point3, read-only

Returns center of bounding box of children. Returns maximum corner of bounding box.

786

Chapter 10

Collections

<nodechildrenarray>.min <nodechildrenarray>.count

: Point3, read-only : Integer, read-only

Returns minimum corner of bounding box. Returns number of objects in set. Operators:
<nodechildrenarray>[<integer>] -- retrieve nth child

Methods:
append <nodechildrenarray> <node>

Makes the specified node a child of the node NodeChildrenArray was constructed from.
deleteItem <nodechildrenarray> <node>

Removes specified node as a child of the node NodeChildrenArray was constructed from. Notes: Unlike ObjectSets, you cannot use NodeChildrenArray as the root of a pathname. The order of sequencing is consistent in a stable scene but somewhat arbitrary - it depends on how 3ds max stores its object hierarchy internally which is effected mostly by order of additions and deletions to and from the scene.

VertexSelection Values
A VertexSelection represents a set of vertices for a scene mesh node as a virtual array. As such, you can access a vertex by index, iterate over the vertices, and apply mapped functions to the vertices. See also Editable_Mesh (p. 1041). The VertexSelection array is dynamic, i.e., its contents will change as the vertices or selected vertices of the mesh node change. VertexSelection values are mappable. Constructors:
<mesh>.selectedVerts -- the currently selected vertices of the mesh object <mesh>.verts -- all of the vertices of the mesh object, read-only

Properties:
<vertexselection>.count <vertexselection>.selSetNames : Integer, read-only : Array of names, read-only

Returns the number of vertices in the VertexSelection array. Returns an array of names of the current vertex-level named selection sets for the object the VertexSelection is associated with. The following properties are present for singleton selections (of the form $foo.verts[n]):
<vertexselection>.index $foo.selectedVerts[2].index : Integer, read-only

Returns the index of the selected element in the mesh, e.g., returns the vertex index of the 2nd vertex in the current selection.

VertexSelection Values

787

<vertexselection>.pos

: Point3

Returns or sets the position of the selected element in the mesh, e.g.,
$foo.verts[i].pos = $baz.verts[j].pos + [10,0,0]

Note that iterating over a selection yields singleton selections in the loop body:
sv = for i in $foo.selectedVerts collect i.index

sv contains selected vertices as array Operators:

<mesh>.selectedVerts = (<array> | <bitarray>)

Selects the specified vertices.

<vertexselection>[<integer>]

Retrieves the indexed vertex as a singleton VertexSelection. Index starts at 1

<vertexselection>[<integer>] = <point3>

Sets the position of the indexed vertex.

<vertexselection>[(<integer_array> | <bitarray>)]

Retrieves the indexed vertices as a VertexSelection. Index starts at 1.

<vertexselection>[(<#name> | <string>)]

Retrieves the vertex-level named selection set, where the name of the named selection set can be specified as a name or string value.
<vertexselection>[(<#name> | <string>)] = (<vertexselection> | <integer_array> | <bitarray>)

Sets the vertex-level named selection set to the specified vertices. The name of the named selection set can be specified as a name or string value, and the vertices can be specified as an array, bitArray, or a VertexSelection from the same object. Methods:
move <vertexselection> <point3>

Moves the vertices in the VertexSelection.

select <vertexselection>

Selects the vertices in the VertexSelection.

deselect <vertexselection>

Deselects the vertices in the VertexSelection.

delete <vertexselection>

Deletes the vertices in the VertexSelection.

append <vertexselection> (<vertexselection> | <integer>)

Appends the vertex or vertices to the VertexSelection.

findItem <vertexselection> (<vertexselection[<integer>] | <integer>)

Returns the selection index of the matching item or 0 if not found. The item is selection index or singleton VertexSelection.

788

Chapter 10

Collections

Examples:
-- move vertices in mouth named selection set move $foo.verts[#mouth] [0,0,10] -- select vertices in front verts set select $baz.verts[front verts] -- set baz named selection set to given vertices $foo.verts[#baz] = #(1,3,4,5,10) -- set cursel set to current selection $baz.verts[#cursel] = $baz.selectedVerts -- all the names of the vertex-level named selection sets for object $foo $foo.verts.selSetNames -- print out all vertex-level named selection sets for n in $.verts.selSetNames do print $.verts[n]

FaceSelection Values
A FaceSelection represents a set of faces for a scene mesh node as a virtual array. As such, you can access a face by index, iterate over the faces, and apply mapped functions to the faces. See also Editable_Mesh (p. 1041). The FaceSelection array is dynamic, i.e., its contents will change as the faces or selected faces of the mesh node change. FaceSelection values are mappable. Constructors:
<mesh>.selectedFaces <mesh>.Faces -- the currently selected faces of the mesh object -- all of the faces of the mesh object, read-only

Properties:
<faceselection>.count <faceselection>.selSetNames : Integer, read-only : Array of names, read-only

Returns the number of faces in the FaceSelection array. Returns an array of names of the current face-level named selection sets for the object the FaceSelection is associated with. The following property is present for singleton selections (of the form $foo.faces[n]):
<faceselection>.index $foo.selectedFaces[2].index : Integer, read-only

Returns the index of the selected element in the mesh, e.g., returns the face index of the 2nd face in the current selection. Note that iterating over a selection yields singleton selections in the loop body:
sf = for i in $foo.selectedFaces collect i.index

sf contains selected faces as array Operators:

<mesh>.selectedFaces = (<array> | <bitarray>)

Selects the specified faces.

<faceselection>[<integer>]

Retrieves the indexed face as a singleton FaceSelection. Index starts at 1.

FaceSelection Values

789

<faceselection>[<integer>] = <point3>

Sets the vertices of the indexed face to the vertex indices specified in the point3 value.
<faceselection>[(<integer_array> | <bitarray>)]

Retrieves the indexed faces as a FaceSelection. Index starts at 1.

<faceselection>[(<#name> | <string>)]

Retrieves the face-level named selection set, where the name of the named selection set can be specified as a name or string value.
<faceselection>[(<#name> | <string>)] = (<faceselection> | <integer_array> | <bitarray>)

Sets the face-level named selection set to the specified faces. The name of the named selection set can be specified as a name or string value, and the faces can be specified as an array, bitArray, or a FaceSelection from the same object. Methods:
move <faceselection> <point3>

Moves the faces in the FaceSelection.

select <faceselection>

Selects the faces in the FaceSelection.

deselect <faceselection>

Deselects the faces in the FaceSelection.

delete <faceselection>

Deletes the faces in the FaceSelection.

append <faceselection> (<faceselection> | <integer>)

Appends the face(s) to the FaceSelection.

findItem <faceselection> (<faceselection[<integer>] | <integer>)

Returns the selection index of the matching item or 0 if not found. The item is selection index or singleton FaceSelection. Examples:
-- move faces in mouth named selection set move $foo.faces[#mouth] [0,0,10] -- select faces in front faces set select $baz.faces[front faces] -- set baz named selection set to given faces $foo.faces[#baz] = #(1,3,4,5,10) -- set cursel set to current selection $baz.faces[#cursel] = $baz.selectedFaces -- all the names of the face-level named selection sets for object $foo $foo.faces.selSetNames -- print out all face-level named selection sets for n in $.faces.selSetNames do print $.faces[n]

790

Chapter 10

Collections

EdgeSelection Values
An EdgeSelection represents a set of edges for a scene mesh node as a virtual array. As such, you can access an edge by index, iterate over the edges, and apply mapped functions to the edges. See also Editable_Mesh (p. 1041). The EdgeSelection array is dynamic, i.e., its contents will change as the edges or selected edges of the mesh node change. EdgeSelection values are mappable. Constructors:
<mesh>.selectedEdges <mesh>.Edges -- the currently selected edges of the mesh object -- all of the edges of the mesh object, read-only

Properties:
<edgeselection>.count <edgeselection>.selSetNames : Integer, read-only : Array of names, read-only

Returns the number of edges in the edge array. Returns an array of names of the current edge-level named selection sets for the object the EdgeSelection is associated with. The following property is present for singleton selections (of the form $foo.edges[n]):
<edgeselection>.index $foo.selectedEdges[2].index : Integer, read-only

Returns the index of the selected element in the mesh, e.g., returns the edge index of the 2nd edge in the current selection. Note that iterating over a selection yields singleton selections in the loop body:
se = for i in $foo.selectedVerts collect i.index

se contains selected edges as array Operators:

<mesh>.selectedEdges = (<array> | <bitarray>)

Selects the specified edges.

<edgeselection>[<integer>]

Retrieves the indexed edge as a singleton EdgeSelection. Index starts at 1

<edgeselection>[(<integer_array> | <bitarray>)]

Retrieves the indexed edges as a EdgeSelection. Index starts at 1.

<edgeselection>[(<#name> | <string>)]

Retrieves the edge-level named selection set, where the name of the named selection set can be specified as a name or string value.
<edgeselection>[(<#name> | <string>)] = (<faceselection> | <integer_array> | <bitarray>)

Sets the edge-level named selection set to the specified edges. The name of the named selection set can be specified as a name or string value, and the edges can be specified as an array, bitArray, or a EdgeSelection from the same object.

BitArray Values

791

Methods:
move <edgeselection> <point3>

Moves the edges in the EdgeSelection.

select <edgeselection>

Selects the edges in the EdgeSelection.

deselect <edgeselection>

Deselects the edges in the EdgeSelection.

delete <edgeselection>

Deletes the edges in the EdgeSelection.

append <edgeselection> (<edgeselection> | <integer>)

Appends the edge(s) to the EdgeSelection.

findItem <edgeselection> (<edgeselection[<integer>] | <integer>)

Returns the selection index of the matching item or 0 if not found. The item is selection index or singleton EdgeSelection. Examples:
-- move edges in mouth named selection set move $foo.edges[#mouth] [0,0,10] -- select edges in front edges set select $baz.edges[front edges] -- set baz named selection set to given edges $foo.edges[#baz] = #(1,3,4,5,10) -- set cursel set to current selection $baz.edges[#cursel] = $baz.selectedEdges -- all the names of the edge-level named selection sets for object $foo $foo.edges.selSetNames -- print out all edge-level named selection sets for n in $.edges.selSetNames do print $.edges[n]

BitArray Values
The MAXScript BitArray class provides direct access to 3ds maxs SDK BitArray class. The SDK BitArray is used throughout 3ds max to compactly encode selections as a string of bits. Literals:
#{ <selection> } -- these are curly-brackets

where <selection> is a comma-separated list of the following:

<integer> <integer> .. <integer> -- integers must be > 0

For example, #{1, 5, 10..200, 302} says that the bits 1, 5, 10 to 200, and 302 are turned on. When used in connection with selections in 3ds max (such as vertex or face or control vertex) the on bits imply the elements or sub-objects with those indexes are selected.

792

Chapter 10

Collections

Properties:
<bitarray>.count : Integer, read-only

Returns the largest possible index held in the BitArray at that point in time. This value is independent of whether any particular indexes are selected or not. BitArrays grow dynamically as needed to accommodate the indexes used on it, just as with arrays. Operators:
<bitarray>[<integer>] <bitarray>[<integer>] = <boolean> <bitarray> + <bitarray> <bitarray> - <bitarray> -<bitarray> -----yields true if selected, else false sets or clears indexed bit union (OR operation) difference invert the bitarray

Methods:
append <bitarray> <integer>

Adds index to bitarray, growing bitarray if necessary.

join <bitarray> <bitarray>

Union (OR operation) of the two bitarrays.

findItem <bitarray> <integer>

Yields index <integer> if selected, 0 otherwise.

deleteItem <bitarray> <integer>

Clears the index selection.

copy <bitarray>

Creates an independent copy of the bitarray. Notes: BitArrays can be used interchangeable with ordinary #(...) arrays (p. 776) of index numbers where ever a selection array is applicable, such as in mesh sub-object selections, for example:
$foo.verts[#{20..1023}] -- selects all vertices between 20 and 1023

You can sequence over BitArrays with a for-loop, which yields a sequence of index numbers corresponding to the currently selected items.
for i in #{2..200} do print i -- print the numbers between 2 & 200

You can perform an AND operation between two BitArrays by inverting the difference between them. For example:
a=#{1..5} b=#{3..10} c=-(a-b) -- result in c is #{3..5}

MAXKeyArray Values

793

MAXKeyArray Values
A MAXKeyArray represents all the keyframe keys in a 3ds max controller track. See also the MAXKey Values (p. 767), Working with MAXKey Values (p. 769), and Controller Common Properties, Operators, and Methods (p. 1289) topics. MAXKeyArray values are mappable. Constructors:
<node>.<animatable_property>.keys

The key array can be accessed using the keys property on an animated 3ds max object property. Examples:
$foo.position.keys $foo.twist.angle.keys

If the 3ds max object parameter is not yet animated (i.e., no controller has been assigned to the parameter), a value of undefined is returned.
<controller>.keys

The key array can be accessed using the keys property on a controller. Examples:
$foo.position.controller.keys $foo[3][1].keys

Properties:
<key_array>.count : Integer, read-only

Returns the number of keys in the key array. Operators:

<key_array>[<index_integer>]

Returns a MAXKey (p. 767) value representing the indexed key in the key array. Indexes start at 1. Methods:
append <key_array> <key>

Appends key to key array.

deleteItem <key_array> <index_integer>

Deletes the indexed key. Key indexes are 1-based.

addNewKey <key_array> <time> [ #select ]

Adds a new key to the key array at the time specified. The value for the new key is the interpolated controller value at the specified time. The new key is also selected if the #select optional argument is specified. The value for the new key is the interpolated controller value at that time. addNewKey() will not add a key if a key already exists at the specified time. The return value in this case is the key located at the specified time.
deleteKeys <key_array> [ #allKeys ] [ #selection ]

Deletes keys from the controller according to the optional symbolic argument supplied. #allKeys (default): deletes all keys in the controller. #selection: deletes the currently selected keys

794

Chapter 10

Collections

deleteKey <key_array> <index_integer>

Deletes the indexed key. Key indexes are 1-based.

moveKeys <key_array> <time> [ #selection ]

Moves all keys by the time given. If #selection is specified, move the current selection otherwise move all keys.
sortKeys <key_array>

Re-sorts keys according to their times. Some MAXKey operations can result in out of order keys and this function must be called to correctly order keys. Notes: All of the above methods may re-sequence keys in the key array and so cause existing keys to take on different indexes, because key array indexes are time positional. Take care when inserting and deleting keys into arrays that have individual keys in variables and other containers -- MAXKey values are defined internally in terms of this index and so may point to different keys if you re-arrange the keys in a controller. MAXKeyArrays also support mapped property assignment on their contents in the same way that pathname and array collections do on their contents. So, for example:
$box01.pos.keys.time += 10f

bumps all key times by 10 frames, and,

$cyl23.bend.angle.keys.value *= 1.2

scales all the bend angle key values up by 1.2. Example:

keys = $box01.bend.angle.keys for t in 0f to 100f by 10f do addNewKey keys t

MAXNoteKeyArray Values
A MAXNoteKeyArray represents all the note keys in a 3ds max note track. This value is described in Note Track Access (p. 816). MAXNoteKeyArray values are mappable.

ModifierArray Values
A ModifierArray represents the modifiers present on a scene node as an array. As such, you can access a modifier by index, iterate over the modifiers, and apply mapped functions to the modifiers. See also Modifiers (p. 1095). ModifierArray values are mappable. Constructors:
<node>.modifiers

Properties:
<modifierarray>.count : Integer, read-only

Returns the number of modifiers in the modifier array.

MaterialLibrary Values

795

Operators:
<modifierarray>[<integer>]

Retrieves indexed modifier. Index is 1-based with 1 being the modifier on the top of the modifier stack.
<modifierarray>[( <name> | <string> )]

Retrieves named modifier using modifier name as string or name.

MaterialLibrary Values
A MaterialLibrary contains a table of materials as an array. The 3ds max system global variables currentMaterialLibrary and sceneMaterials contain MaterialLibrary instances. System global variable meditMaterials strictly speaking is not a MaterialLibrary value, rather it is a virtual array of the materials in the Material Editor sample slots. In most cases, meditMaterials can be considered a MaterialLibrary value, with the exception that you can assign a material or textureMap value to a meditMaterials element. MaterialLibrary values are mappable. Constructors:
currentMaterialLibrary -- system global sceneMaterials -- system global, the materials in the scene meditMaterials -- system global, the materials in material editor materialLibrary { <material> }

Creates a temporary material library. You can add materials to this library with the append function, but there is currently no way to save it or make it the current library. Properties:
<mat_lib>.count : Integer, read-only

Returns the number of materials in the library. Operators:

<mat_lib>[ <integer> | <name> | <string> ]

Retrieves a material from the material library. Material libraries can be indexed just like arrays with an integer index, or by using the material name as a Name or String value.
<mat_lib>[ <integer> | <name> | <string> ] = ( <material> | <textureMap> )

Assigns the specified material or textureMap to the material library. Material libraries can be indexed just like arrays with an integer index, or by using the material name as a Name or String value. If the material library is indexed by an index value, and the index value is larger than the size of the material library, a runtime error is generated. If the material library is indexed by a material name, and the material name is not already present in the material library, the material or textureMap is appended to the material library.
meditMaterials[<slot_index_integer>]

Returns the material or textureMap in the indexed material editor slot. Valid <slot_index_integer> values are 1 through 24.

796

Chapter 10

Collections

meditMaterials[<slot_index_integer>] = ( <material> | <textureMap> )

Assigns the specified material or textureMap to the indexed material editor slot. Valid <slot_index_integer> values are 1 through 24. For example:
meditMaterials[3]= standard()

Methods:
append <mat_lib> <material>

Append the specified material to the material library. This method is not applicable to the meditMaterials material library.
deleteItem <mat_lib> ( <integer> | <name> | <string> )

Delete the specified material from the material library. The material can be specified as the indexed material in the material library, as a String, or as a Name. This method is not applicable to the meditMaterials material library.
findItem <mat_lib> <material>

Returns the index of the material in the material library or zero if the material is not in the material library. Associated Methods:
getMeditMaterial <slot_index_integer>

Returns the top level material or textureMap in the specified material editor slot. Valid <slot_index_integer> values are 1 through 24. For example:
foo = getMeditMaterial 3 setMeditMaterial <slot_index> ( <material> | <textureMap> )

Complements the getMeditMaterial function allowing you to place a material or textureMap into the numbered material editor slot.
loadDefaultMatLib()

Loads the default 3ds max material library file.

loadMaterialLibrary <filename_string>

Loads the named 3ds max material library file, which becomes the current material library. If the file name does not have a fully specified directory path, the function searches through all the currently configured bitmap paths. Returns true if the loads succeeds, false if it fails.
saveMaterialLibrary <filename_string>

Saves the current material library into the named file. Returns true if the save succeeds, false if it fails.
fileOpenMatLib()

This method displays the File Open dialog and allows the user to select a material library to load. Note: If the Material/Map Browser is open when fileOpenMatLib() is called, the Material/Map Browser display is not updated.
fileSaveAsMatLib()

Displays the standard Save File As dialog to allow the user to save the current material library.

NURBSSet Values

797

fileSaveMatLib()

If the current material library has been saved previously (has been named) this method saves the material library to the same file. Otherwise it displays the standard Save File As dialog to allow the user to save the current material library.
getMatLibFileName()

Returns the current material library file name as a String value. Examples: You can use the standard array indexing accessors to get and set materials in the library. MaterialLibraries also allow you to use name and string literals as indexes to get at materials in them by name:
$foo.material = currentMaterialLibrary[Rough Gold] for m in sceneMaterials do print m.name append currentMaterialLibrary $baz.material

NURBSSet Values
A NURBSSet is used rto create NURBS objects, or retrieve data from existing NURBS objects. The NURBSSet acts as a container for the various NURBSObject derived entities (points, curves, surfaces) used to make up the set. This value is described in NURBSSet : Value (p. 1450). NURBSSet values are mappable.

798

Chapter 10

Collections

Chapter 11:

3ds max Objects

Identifying and Accessing MAXScript Classes and Properties

The largest set of classes and functions in MAXScript are those that provide access to the elements in the 3ds max application and in your scene. This section has several topics that discuss the use of these 3ds max-specific classes and functions. One important family of classes is the MAXWrapper Value (p. 808) class that give you access to the scene objects, lights, cameras, modifiers, controllers, materials, etc., in 3ds max scenes. The topics in this section are: Class and Object Inspector Functions (p. 799) Dynamic Properties (p. 805) Indexed Access to Animatable Properties (p. 806) Third-Party Plug-In Classes (p. 808)

Class and Object Inspector Functions

MAXScript provides a number of built-in functions that display information about the classes that are accessible in your particular 3ds max installation. These functions are useful as an online reference for the core 3ds max classes and provide the only way of determining what properties in Third-Party plug-in classes (p. 808) are accessible. apropos: The apropos() function is used to search for and print out information about global variables by name pattern and class of contents. This function has the form:
apropos <pattern_string> [ to:<stream> ]

The <pattern_string> argument is a string containing a wild-card pattern for matching against global variables. The pattern form is:
<variable_name_pattern_string[:class_name_pattern_string]>

800

Chapter 11

3ds max Objects

that is, a global variable name pattern optionally followed by a : and a class name pattern. If the optional class name pattern is given, it restricts the printout to globals containing values of the specified classes. The apropos() function assumes a wild-card * at the start and end of each pattern, implying a contains pattern match. The pattern strings can contain name characters and *s and ?s. The output consists of the global variable name, a tag in () indicating if the variable is a system or const (unchangeable) variable and the class of the value currently in it, followed by a printed representation of that value. Examples:
apropos apropos apropos apropos apropos light -- any variables with light in the variable name :float -- any variables containing float values to:f -- dump all variables to the stream f controller:super -- the list of controller superclasses foo:control -- any variables whose name contains foo -- and that contain controller classes

Heres a fragment of the first examples output:

lights (const ObjectSet): $lights lightLevel (system Float): 1.0 Sunlight (const MAXClass): Sunlight Directionallight (const MAXClass): Directionallight lightLevelController (system Control): Controller:Bezier_Float light (const MAXSuperClass): light NewLight (const Primitive): NewLight() lightTintColor (system Color): (color 255 255 255) Volume_Light (const MAXClass): Volume_Light lightTintColorController (system Control): Controller:Bezier_Color gw.getMaxLights (Primitive): getMaxLights() gw.setLight (Primitive): setLight()

showClass: The showClass() function prints information about a specified 3ds max class or classes. It has the following form:
showClass <pattern_string> [ to:<stream> ]

where <pattern_string> is a string containing a wild-card pattern to match against 3ds max class names, superclass names and property names, and the optional to:<stream> keyword argument specifies a Stream Value (p. 763) to output the display to. The pattern string has this form:
<class_name>[ :<superclass_name> ][ .<property_name> ]

Class and Object Inspector Functions

801

Examples:
showClass path* showClass noise.* showClass showClass showClass showClass -- all 3ds max classes starting path -- all the accessible properties on the -- Noise texture map *:mod* -- all the modifier classes *.*rad* -- all the classes with a property name -- containing rad *.* to:f -- everything, out to a file *:*controller* -- all the classes that have -- controller in their superclass -- name

In the output from the last example, the controllers include 3ds maxs core controllers and any 3rd-party plug-in controllers. In some cases, embedded controllers for some complex plug-ins may be visible in the showClass() listing (such as for character studio and HyperMatter). You should not attempt to create and use these controllers individually, this may result in system exceptions. If you leave out the superclass pattern (the : part), it matches all superclasses. If you leave out the property pattern (the . part), you only get class names printed. Note: This function only displays matching MAXWrapper classes (nodes, modifiers, materials, etc.), not the foundation classes in MAXScript (float, integer, array, point3, etc.). The following shows examples of the output of showClass(): Script:
showclass box* showclass box.* -- show all classes whose name starts with box -- show all properties for class box

Output:
Box : GeometryClass {10,0} BoxGizmo : helper {3bc31904,67d74ec9} OK Box : GeometryClass {10,0} .height : float .length : float .lengthsegs : integer .width : float .widthsegs : integer .mapCoords : boolean .heightsegs : integer OK -- start of output from line 1 -- result returned from line 1 -- start of output from line 2

-- result returned from line 2

showProperties: The showProperties() function is used to display the properties for a specific object that is an instance of one of the MAXWrapper classes. It can be used in place of showClass() in situations where you have an actual object in hand. Unlike showClass(), it can display the dynamic properties (p. 805) that may appear in individual objects as you work on them in the scene, such as the subcontrollers in a list controller or the animated control points in an FFD modifier.

802

Chapter 11

3ds max Objects

The showProperties() function has the form:

showProperties <maxwrapper_object> [ <property_pattern> ] [ to:<stream> ]

where <maxwrapper_object> is the 3ds max entity to be inspected, the optional <property_pattern> is a wild-card pattern that names the properties to be inspected, and the optional to:<stream> keyword argument specifies a Stream Value (p. 763) to output the display to. If the property name pattern is not supplied, all properties are listed. Examples:
showProperties $foo.bend object foo -- show properties of the bend modifier on

ffdmod = $baz.FFD_box__4x4x4 -- point to the FFD modifier on object baz showProperties ffdmod disp* to:log -- show properties starting with disp in the -- FFD modifier showProperties $foo.pos.controller controller -- sub controllers in a position list

Note: When the 3ds max entity specified is a node (for example $box01), this function only displays the properties of base object. It does not show the properties of the transform controllers, modifiers, or materials applied to the object. To display the properties for one of these objects, that object must be specified as the 3ds max entity as shown in the above examples. The following shows examples of the output of showProperties: Script:
b=box() ffd_mod=ffdBox() addmodifier b ffd_mod showproperties b showproperties ffd_mod -----create a box create a ffdBox modifier apply ffdBox modifier to the box show all properties for the box show all properties for the ffdBox modifier

Output:
$Box:Box07 @ [0.0000,0.0000,0.0000] -- result from line 1 FFD_box__4x4x4:FFD(box) 4x4x4 -- result from line 2 OK -- result from line 3 .height : float -- start of output from line 4 .length : float .lengthsegs : integer .width : float .widthsegs : integer .mapCoords : boolean .heightsegs : integer OK -- result from line 4 .dispLattice (Lattice) : boolean -- start of output from line 5 .dispSource (Source Volume) : boolean .deformType (<unknown>) : integer .falloff : float

Class and Object Inspector Functions

803

.tension : float .continuity : float .inPoints (Inside Points) : boolean .outPoints (Outside Points) : boolean .offset : float .lattice_transform : transform OK -- result from line 5

getPropNames: The getPropNames() function is similar to showProperties(), except it returns the property names for a specific object as an array. Unlike showProperties(), you can specify whether to return only the names of dynamic properties (p. 805) of the object. The getPropNames function has the form:
getPropNames <maxwrapper_obj> [ #dynamicOnly ]

The getPropNames() function returns an array of the property names accessible on the object. For example, if a FFD(Box) modifier with animated control points is applied to a sphere,
getPropNames $sphere01.FFD(box) 4x4x4

could yield:
#(#dispLattice, #dispSource, #deformType, #falloff, #tension, #continuity, #inPoints, #outPoints, #offset, #Lattice_Transform, #Control_Point_49, #Control_Point_50, #Control_Point_51, #Control_Point_52, #Control_Point_53)

Note: When the 3ds max entity specified is a node (for example $box01), this function only returns the properties of base object. It does not return the properties of the transform controllers, modifiers, or materials applied to the object. To return the properties for one of these objects, that object must be specified as the 3ds max entity as shown in the above examples. If you call getPropNames() on MAXWrapper classes such as Box, Line, or Bend, it will return the properties common to all instances of that class. If you call getPropNames() on a 3ds max entity, it will return the properties currently defined for that entity. If you add the optional keyword #dynamicOnly to the getPropNames() call for an entity, it returns the dynamic properties unique to that instance. For example,
getPropNames $sphere01.FFD(box) 4x4x4 #dynamicOnly

could yield:
#(#Lattice_Transform, #Control_Point_49, #Control_Point_50, #Control_Point_51, #Control_Point_52, #Control_Point_53)

Note that the property names for the lattice transform and control points which was returned by the previous example is not returned when #dynamicOnly is specified. These properties are unique to the specific FFD modifier.

804

Chapter 11

3ds max Objects

As a special case, you can also call getPropNames() on the superclass Node to get the list of properties common to all scene nodes such as .position, .name, or .wireColor. For example:
getPropNames node

getProperty and setProperty: The getProperty() and setProperty() functions allow you to access and set properties using computed property names: These form for each of these functions are:
getProperty <obj> <property_name> setProperty <obj> <property_name> <value>

The property name can be either a name, for example #length, or a string, for example length, so you can construct property names with string operations. Examples:
getProperty foo #x -- equiv. to foo.x setProperty $foo radius 23 -- equiv. to $foo.radius = 23 getProperty $foo.ffd_2x2x2 (control_point_ + n as string)

The getPropNames() function can be used in conjunction with the getProperty() function to implement object dumping tools that can iterate over all the properties of an arbitrary object and output them as required. For example,
for p in getPropNames $foo do format % = %\n p (getProperty $foo p)

Similar functions for accessing and setting the values of property-assigned controllers are:
getPropertyController <value> <string_or_name> setPropertyController <value> <string_or_name> <controller>

Get and set the controller assigned to the named property of the value. If no controller has been assigned to the property, a value of undefined is returned. SubAnims and ParamBlocks: 3ds max stores all of properties for objects in structures called subAnims. In some cases, a subAnim will contain nested subAnims. An example of this can be seen with the Standard material. If you apply a Standard material to an 3ds max object, and then expand the objects tracks in Track View to display the material, you will see three Track View nodes - Parameters, Maps, and Shader. Each of these nodes is a subAnim defined in the Standard materials class. Expanding the tracks for these three nodes, you will see various properties listed. These properties are defined in each of the nested subAnims in a structure called a ParamBlock. MAXScript automatically finds animatable properties in all ParamBlocks associated with an object. To access these properties, you use the same nesting as shown in Track View when referencing those properties in MAXScript. For example, you would access the Ambient Color property in a Standard material in MAXScript as:
$box01.material.shader.diffuse_color

Dynamic Properties

805

For more information about accessing animatable properties in MAXScript, see also Indexed Access to Animatable Properties in 3ds max Objects (p. 806). The properties accessible on the various kinds of values is documented for each class. Many of the foundation classes in MAXScript (such as point3, color, etc.) support a special kind of nestedproperty assignment which allows sub-properties on object properties, such as the .x, .y, and .z coordinates in a nodes .position property, to be individually and directly set. See the Nested Object Properties (p. 815) topic for details.

Dynamic Properties
In addition to the properties listed in the reference, MAXScript provides access to the dynamic properties in 3ds max entities, those properties that are specific to an individual object and depend on the operations youve performed on that object in the 3ds max scene. These includes such things as animatable modifier sub-objects like gizmos and FFD control points and sub-controllers like those in a List controller or P/R/S Transform or Path controller. These correspond to the many animatable parameters and sub-objects that you see in the Track View for an object; if you can see them in the Track View they will be visible as either static or dynamic properties in the MAXScript value that corresponds to that object. The property name you specify is matched against the sub-animatable name (as it would be seen in the Track View or sub-object drop-down) using the standard MAXScript conventions of mapping spaces to _ underscores and ignoring case when dealing with 3ds max class and property names. You can also simply leave out the spaces in any dynamic property names. Example:
p = $foo.bend.center $baz.taper.gizmo.rotation = quat 30 z_axis $foo.pos.controller.bezier_position = [10,0,0]

Because these properties are dynamic and may change as controllers are replaced and sub-objects become animated, they may vary from object to object and so are not reported in the properties section of the showClass() function output. Instead, you can use the built-in function showProperties() which will display the accessible properties on a 3ds max entity including the currently visible dynamic properties. Both functions are described in the Class and Object Inspector Functions (p. 799) topic.

806

Chapter 11

3ds max Objects

Indexed Access to Animatable Properties in 3ds max Objects

As an alternative to using named property accesses, you can access in an object any animatable property that is visible as a track in Track View by indexing the 3ds max object value as though it were an array. This simplifies such tasks as iterating over all the animatable properties in an object and accessing sub-controllers that dont have unique names, such as within list controllers. Properties:
<maxwrapper_object>.numSubs : Integer, read-only

Yields the number of accessible sub-animatables, or tracks, in an object. This is the number of immediate children subAnims, and may include as yet invisible tracks in the track view, such as visibility tracks on a node or yet-to-be animated vertices in an FFD. This property operates on any MAXWrapper subclass. Methods:
getSubAnimName <maxwrapper_object> <index> getSubAnimNames <maxwrapper_object>

Provides access to the Track View names of subAnims. The getSubAnimName() function takes a subAnim index and returns a Name instance. The getSubAnimNames() function returns an array of names in subAnim index order.
getSubAnim <maxwrapper_object> <index>

Returns the indexed subAnim. See the index operator below. Operators:
<maxwrapper_object>[<index_number>]

Returns the indexed subAnim. You can apply the index operator, [<index_number>], to any MAXWrapper object (nodes, modifiers, controllers, materials, etc.) to access a numbered subAnim. For example:
for i in 1 to $foo.numSubs do print $foo[i] -- iterate them $bar.position.controller[3] -- third subAnim in a position list controller ffd_mod[i].value -- position of ith FFD control point

You cannot set subAnims with the index operator, this is a read-only access. -- SubAnim Class MAXScript defines a SubAnim class, instances of which provide a general representation for subanimatables. Whenever you use the index operator on a 3ds max object, it returns a SubAnim instance. For example:
$box01[3] -> SubAnim:Transform

The third subAnim in a node is typically the transform track. Properties:

<subAnim>.value : Value

The current value of the track subAnim, equivalent to <controller>.value. Returns undefined if no appropriate value exists or the track has not yet been assigned a

Indexed Access to Animatable Properties in 3ds max Objects

807

controller. The .value property yields the value at the current MAXScript time. You can assign to this value to set the tracks value at that time.
<subAnim>.controller : Controller

The controller for the track SubAnim. Returns undefined if a controller has not yet been assigned or if the SubAnim is not animatable. You can assign a new controller to a track by assigning to the .controller property of its subAnim.
<subAnim>.keys : KeyArray, read-only

Yields the key array for that track or undefined if not keyable or a controller has not yet been assigned. This property is read-only.
<subAnim>.isAnimated <subAnim>.object : Boolean, read-only : MAXWrapper, read-only

Yields true if there is an animated controller present. This property is read-only. Yields the subAnim object, or undefined if not assigned. This property is read-only. The .object property may return any kind of MAXWrapper object, depending on what the parent object decides to put there. For example, <node>[1].object is the visibility controller or undefined if not yet assigned, <node>[2].object contains the bindings of any space warps bound to the node, or undefined if none have been bound, <node>[3].object is the transform controller, <node>[4].object is the nodes object, either the modified object if there are modifiers present or the base object if not, <node>[5].object is the material assigned to the node or undefined if no material has been assigned, and <node>[6].object is the Image Motion Blur Multiplier controller or undefined if not yet assigned,. For example:
b = box() b[4].object <subAnim>.numSubs -- returns a reference to the Box base object : Integer, read-only

The number of immediate subAnim children. If you attempt to access subAnim properties, such as .value, .numSubs, .category, etc., on certain subAnims that had yet to be assigned controllers, such as scene node visibility tracks, these properties return null values such as 0, or undefined, as appropriate. Methods:
getSubAnim <subAnim> <index>

Returns the indexed subAnim. See the index operator below. Operators:
<subAnim>[<index_number>]

Returns the indexed subAnim. You can work down through nested subAnims (nested tracks) by indexing into subAnims themselves. For example,
$box01[3][2]

yields the rotation track subAnim since <node>[3] is always the transform track and the second track in it is always the rotation track. Indexing a SubAnim always yields another SubAnim. For those familiar with SubAnims in the 3ds max SDK, it should be noted that

808

Chapter 11

3ds max Objects

MAXScript SubAnims descend automatically through hidden subAnim levels, reflecting the structure seen in Track View. Note that you can get at the base objects Track View parameters by indexing into the base object:
b=box() getSubAnimNames b[4] -- returns #(#length, #width, #height, ...) b[4][2].value -- returns current width value i = 3 b[4][i].controller = float_list() -- assign height controller

Third-Party Plug-In Classes

The MAXWrapper Value (p. 808) classes are the core 3ds max classes that are supported directly within MAXScript. Many of the kinds of 3ds max objects you will work with are provided through 3rd-party plug-ins for 3ds max, they are not built directly in to MAXScript. For these classes, an automatic plug-in detector scans for plug-ins that MAXScript doesnt internally know about and attempts to provide MAXScript access to them. This includes new core classes in new releases of 3ds max that MAXScript doesnt internally know about, and 3rd-party plug-ins (such as HyperMatter, Sand Blaster, Surface Tools, etc.). Not all parameters and properties of the detected plug-ins are accessible. In general, the detector will only find animatable parameters on these plugins, and in some cases none at all, if the plug-in uses non-standard parameter coding. You can use the class and object inspector functions (p. 799) in MAXScript to browse through the 3ds max core and 3rd-party classes accessible in MAXScript.

MAXWrapper : Value
The MAXWrapper class is the superclass of all classes in MAXScript that represent 3ds max objects, such as scene nodes, modifiers, materials, etc. MAXWrapper values contain references to the associated 3ds max objects that allow it keep track of the object. This allows MAXScript to know when a 3ds max object is transformed, deleted by the user, or its properties are changed. The properties, operators, and methods that are common to all classes derived directly from the MAXWrapper class are described in the MAXWrapper Common Properties, Operators, and Methods (p. 809) topic. The following classes are derived directly from the MAXWrapper class. Other classes are derived from these classes, and inherit the properties and methods defined for the MAXWrapper class.

MAXWrapper Common Properties, Operators, and Methods

809

See also
Node (p. 820) Modifier and SpacewarpModifier (p. 1095) Material (p. 1203) Atmospheric (p. 1337) Controllers (p. 1300) Render Effect (p. 1347)

MAXWrapper Common Properties, Operators, and Methods

The following properties and methods are applicable to any value that is derived from MAXWrapper. Properties: The following MAXWrapper value and class properties give you access to the plug-in category, such as Standard Primitives, Extended Primitives, or Particle Systems:
<MAXWrapperobject>.category <maxclass>.category <maxsuperclass>.categories Name, read-only Name, read-only Array, read-only

The category property returns a Name value containing the category. You can use it on either a 3ds max object class, such as Line, Box, or Fog, or on an instance of any 3ds max object class. For scene nodes, the category usually corresponds to one of the names in the drop down list in the Create panel. These are the categories such as #Standard_Primitives, #Compound_Objects, and #Particles_Only. For modifiers, the category determines which group the modifier appears in the Configure Button Sets/Modifiers list. These are the categories such as #MAX_STANDARD, #MAX_EDIT, and #MAX_SURFACE. For textures, the category determines which group the texture appears in the Material/Map Browser. These are the categories such as #2D (2D maps), #3D (3D maps), and #COMP (Compositors). The categories property can be used on any of the 3ds max object superclasses, such as Shape, GeometryClass, Helper, SpacewarpObject, TextureMap, or Modifier, to get a list of the available categories for that superclass, returned as an array of Names. For example:
$line01.category Gengon.category Shape.categories -- returns #Splines -- returns #Extended_Primitives -- returns #(#Shape, #Splines, #NURBS_Curves)

810

Chapter 11

3ds max Objects

<MAXWrapperobject>.classID <maxclass>.classID

The classID property retrieves the internal 3ds max Class ID of the MAXWrapper classes and objects. The value returned is an array containing two numbers, PartA and PartB of the 3ds max internal class ID. For a MAXWrapper object, the value returned is the Class ID of the class the object is an instance of. For example,
Box.classID b=box() b.classID -- returns #(16, 0)

-- returns #(16, 0)

The combination of the PartA and PartB numbers is guaranteed to be unique for each class.
<MAXWrapperObject>.superClassID <maxclass>.superClassID

Retrieves the 3ds max superclass ID of the MAXWrapper classes and objects. Methods:
copy <MAXWrapper_object>

The copy() function is implemented by all the 3ds max objects available in MAXScript, such as scene objects, controllers, modifiers, materials, etc. You can use this function to make a clone of the source object, for example in situations where you want individual copies or you want to make a shared object unique. For example:
addModifier $foo $baz.bend

will cause foo to share the bend modifier on baz, whereas:

addModifier $foo (copy $baz.bend)

will give foo a separate clone of the bend modifier on baz. Any changes to the bend modifier on foo will not affect baz and vice versa. In the next example, we set up several objects all sharing a single rotation controller:
c = bezier_rotation() $foo.rotation.controller = c $baz.rotation.controller = c $bar.rotation.controller = c

To later make one of the controllers unique, you could do this:

$baz.rotation.controller = copy $baz.rotation.controller

When the MAXWrapper object is not a scene node, the copy is only created in MAXScript memory. When the MAXWrapper object is a scene node, a new scene node is created which is visible and accessible by the user in the 3ds max viewports.

MAXWrapper Common Properties, Operators, and Methods

811

exprForMAXObject <MAXWrapper_object>

Returns a string containing a MAXScript expression that will name the specified MAXWrapper object using property access and indexes as needed. For example, if you have in variable m a bend modifier on a scene object named foo, then:
exprForMAXObject m

would yield the string:

$foo.bend

This method is an exposure of an internal method that macro recorder uses, and its output will vary depending on the macro recorder options.
b=box() --> $Box:Box02 @ [0.000000,0.000000,0.000000] c=b.pos.controller --> Controller:Bezier_Position exprformaxobject c --> $Box02.pos.controller bm=bend() --> Bend:Bend addmodifier b bm --> OK exprformaxobject bm --> $Box02.modifiers[#Bend]

Here, changing the macro recorder options from Explicit scene object names to Selection-relative scene object names, yeilds:
exprformaxobject bm --> $.modifiers[#Bend] createInstance <maxclass> [keyarg1:v] [keyarg2:v] ...

This method is used to directly create the base objects that you see in a Node (or any other object). The main use for this is to create temporary geometry base objects from which meshes will be extracted to help create the meshes for scripted geometry primitive plug-ins. The optional <keyargs> are the same base-object keyword arguments as can be supplied for the class constructor. These are typically the parameters of the base object. For example:
b = createInstance Box length:10 height:40 width:20

creates an instance of a Box. This box will not appear in the 3ds max viewports, as it is not a node. It only contains the geometry associated with the Box object. You can get at the mesh representation of these instanced objects with the mesh property, which yields a TriMesh value.
replaceInstances <old_MAXWrapper> <new_MAXWrapper>

Replaces all instances of the old MAXWrapper with the new MAXWrapper. Old and new MAXWrapper must have the same superclass. Minimal error checking, use with extreme caution.

812

Chapter 11

3ds max Objects

-- Dependencies An important internal mechanism in 3ds max defines the dependency relationship between 3ds max objects. For example, a material depends on its various maps, a path controller depends on its percent controller, a scene node depends on its base object, etc. The following method returns the MAXWrapper objects that depend on a specified MAXWrapper object.
refs.dependents <MAXWrapper_object>

Returns an array of the other 3ds max MAXWrapper objects depend on the specified MAXWrapper object. The specified MAXWrapper object can be any MAXWrapper object, such as a scene node, controller, material, modifier, etc. For example:
refs.dependents $foo.material.diffuseMap

could return:
#(Material_#3, Material_#2, Map_#2:Noise, Material_#1)

which shows that the diffuseMap in $foo is referenced in material #1, material #2, material #3, and noise TextureMap #2. Example: The following example shows several objects being created, and sets up controllers on the objects which depend on other objects. Script:
theSphere=sphere () -- create a sphere theCone=cone radius1:0 radius2:20 -- create a cone theHelix=helix height:100 pos:[100,100,0] -- create a helix theCone.target=theSphere -- assign theSphere as target of theCone -- a lookat controller is automatically -- assigned to theCone -- assign path controller to theSphere, path to follow is the helix theSphere.position.controller=path path:theHelix refs.dependents theSphere -- show dependents of the sphere refs.dependents theCone -- show dependents of the cone refs.dependents theHelix -- show dependents of the helix

Output:
$Sphere:Sphere02 @ [0,0,0] -- result line 1 $Cone:Cone02 @ [0,0,0] -- result line 2 $Helix:Helix02 @ [100,100,0] -- result line 3 $Sphere:Sphere02 @ [0,0,0] -- result line 4 Controller:Path -- result line 8 #(Controller:Look_At, $Cone:Cone02 @ [0,0,0]) -- result line 9 #() -- result line 10 -- following is output of line 11 #(Controller:Path, Controller:Position_Rotation_Scale, $Sphere:Sphere02 @ [0,0,0], Controller:Look_At, $Cone:Cone02 @ [0,0,0])

Access to MAXWrapper AppData

813

See also
Access to MAXWrapper AppData (p. 813) Nested Object Controller Functions (p. 814) Nested Object Properties (p. 815) Note Track Access (p. 816)

Access to MAXWrapper AppData

The AppData access methods give a simple form of access to the AppData capability in the 3ds max SDK. The AppData mechanism provides a way for plug-ins to attach arbitrary data to any 3ds max object in a scene, such as nodes, materials, modifiers, controllers, etc., that is permanently stored with that object in the 3ds max scene file. The following methods are used to read and store AppData for a MAXWrapper object:
setAppData <MAXWrapper_object> <integer_ID> <string>

Sets the AppData item of the given ID number on the given 3ds max object to the <string> value. This creates a new item if needed or replaces the string contents if an item of that ID already exists.
getAppData <MAXWrapper_object> <integer_ID>

Returns the AppData item string of the given ID number from the given 3ds max object. Returns the value undefined if the IDd item is not present.
deleteAppData <MAXWrapper_object> <integer_ID>

Deletes the AppData item if the given ID number from the given 3ds max object.
clearAllAppData <MAXWrapper_object>

Clears out all MAXScript-related AppData items from the given MAXWrapper object. You can add as many AppData strings as you like to an object--you assign them each an integer identification number when they are first added and access them later using those IDs. AppData strings can be attached to any MAXWrapper subclass instance, including scene nodes, modifiers, controllers, materials, atmospherics, etc. Note that the AppData is stored in the scene file only if its object is in the scene--if, for example, you create a material in MAXScript and do not assign it to any object or the material editor, it will not be saved in the scene file nor will its AppData. If you want to associate certain AppData strings with the scene as a whole, it is recommended that you create a hidden dummy node with a unique name and attach the scene AppData to that node.

814

Chapter 11

3ds max Objects

AppData in its full generality allows the C++ plug-in developer to store arbitrary binary data with an object. This is not directly possible with MAXScript, so the approach taken is to store and retrieve AppData text strings that can be built-up or parsed into complex MAXScript objects using a StringStream Value (p. 766). For example, to store some numbers in an array on a scene node, you might do the following:
ss = StringStream for v in data_values do print v to:ss setAppData $foo 1 ss

and read them back after the scene has been saved and reloaded as follows:
ss = StringStream (getAppData $foo 1) data_values = #() while not eof ss do append data_values (readValue ss)

Nested Object Controller Functions

Certain time and keyframe functions on controllers can be called on any 3ds max object or collection of 3ds max objects. If called in this way, they apply recursively to all the nested controllers within that object and on any on sub-objects and sub-controllers within those objects. In this way, they work in a manner similar to the object-level tracks in the 3ds max Track View that allow you to manipulate keys and time for all the sub-objects and sub-controllers within them. The time and controller functions that work this way are:
deleteTime reverseTime scaleTime insertTime setTimeRange addNewKey deleteKeys selectKeys deselectKeys moveKeys sortKeys reduceKeys addEaseCurve deleteEaseCurve setBeforeORT setAfterORT enableORTs

The above functions can be called on any 3ds max object collection (such as a wild-card pathname or object set or array of objects ) and will recursively apply to all animation within those objects. For more information see Time and Key Functions on Object Hierarchies (p. 1299) and Controller Time Functions (p. 1292).

Nested Object Properties

815

Examples:
insertTime $box01.xform 0f 10f

-- all keys after 0f in all controllers in the XForm modifier are moved by 10f
insertTime $box01 0f 10f

-- all keys after 0f in box01 are moved (transform, creation, modifiers)

selectKeys $box02.xform.gizmo.rotation.controller 0f 100f

-- selects keys in 0-100f. If controller is Euler, will select x, y and z keys

deleteTime $box* 10f 10f

-- delete 10f at frame 10 in all keys in all objects named $box* (works with -- any pathname or array of objects)
insertTime $box03.children 0f 10f

-- inserts time in all controllers of all children of $box03

reduceKeys $box01.modifiers

-- applies key reductions to all controllers in all modifiers in $box01 (leaves -- transform and creation parameters alone)

Nested Object Properties

Several of the properties on 3ds max objects contain values that are themselves compound, for example <node>.pos yields a Point3, which itself contains x, y and z properties. MAXScript provides a mechanism that lets you modify these nested properties on MAXWrapper objects in place such that assignment to them will affect that nested property on the 3ds max object. This mechanism depends on the nested property being accessed in one, cascaded property access. For example:
$foo.pos.x += 23 $baz.rotation.angle *= 2 -- move the node 23 units in x -- double the rotation

If you first get the intermediate value into some variable and then set the property on that value, the change will not be reflected in the original object, the connection is only maintained within a single cascaded property access. For example:
p = $foo.pos p.x += 23 -- get foos position as a detached point3 -- set the x prop of that point, it doesnt know -- about foo anymore, foos pos is not changed

In this case, you would have to explicitly re-assign the free-standing point to $foos position to affect $foo:
$foo.pos = p -- set foos new position

In general, any property on a MAXWrapper object that is itself a foundation compound value such as a Point3 or Quat will yield a free-standing value when simply accessed and supports object subproperty assignment in cascaded property assignment.

816

Chapter 11

3ds max Objects

Note Track Access

All MAXWrapper objects can have one or more note tracks assigned to them. These note tracks are visible in Track View as children of the MAXWrapper object. Note tracks provide a way for plug-ins to attach data to any 3ds max object in a scene, such as nodes, materials, modifiers, controllers, etc., that is permanently stored with that object in the 3ds max scene file. This data is stored in note keys, and a note track can contain any number of note keys. The structure of note tracks is similar to the structure of key-able animation controllers. A note track is an instance of the class, and has a property called keys. The value returned by accessing the keys property is a MAXNoteKeyArray. The MAXNoteKeyArray contains the note keys. The keys themselves are accessed as if the MAXNoteKeyArray was an array.

See also
Notetrack Values (p. 816) MAXNoteKeyArray Values (p. 817) MAXNoteKey Values (p. 818) Working with Note Tracks (p. 818)

Notetrack Values
The following methods are related to creating, adding, deleting Note tracks. See the MAXNoteKeyArray Values (p. 817) and MAXNoteKey Values (p. 818) topics for information on accessing the contents of Note tracks. Constructor:
notetrack <name_string>

Creates a new, empty note track with the specified name. The name is only used to differentiate different note tracks in MAXScript but is not visible in 3ds max. Properties:
<noteTrack>.keys <noteTrack>.name MAXNoteKeyArray String

Methods:
getNoteKeyTime <notetrack> <index>

Returns the time of indexed note key.

getNoteKeyIndex < notetrack > <time>

Returns the index of the note key at the specified time. Associated Methods:
addNoteTrack <MAXWrapper_object> <NoteTrack>

Adds a new note track to the MAXWrapper object.

deleteNoteTrack <MAXWrapper_object> <NoteTrack>

Deletes specified note track from the MAXWrapper object.

MAXNoteKeyArray Values

817

hasNoteTracks <MAXWrapper_object>

Deletes specified note track from the MAXWrapper object.

numNoteTracks <MAXWrapper_object>

Returns the number of note tracks applied to the MAXWrapper object as an integer.
getNoteTrack <MAXWrapper_object> <index_integer>

Returns the indexed note track applied to the MAXWrapper object. Index is 1-based.

MAXNoteKeyArray Values
A MAXNoteKeyArray represents all the note keys in a 3ds max note track. See also MAXNoteKey Values (p. 818) and Notetrack Values (p. 816). MAXNoteKeyArray values are mappable. Constructors:
<NoteTrack>.keys

The note key array can be constructed by accessing the keys property on the note track. Example:
nt=getNoteTrack $foo.position.controller 1 -- get first note track on controller ntk=nt.keys -- note key array for note track

Properties:
<NoteKeyArray>.count : Integer, read-only

returns the number of objects in set Operators:

<NoteKeyArray>[<index_integer>] at 1. -- accesses member of collection. Indexes start

Methods:
addNewNoteKey <NoteKeyArray> <time>

Adds a new note key to the note key array at the time specified. The value for the new note key is a null string. Returns the note key added.
deleteNoteKeys <NoteKeyArray> ( #allKeys | #selection )

Deletes note keys from the note key array according to the optional symbolic argument supplied. #allKeys: deletes all keys in the note key array. #selection: deletes the currently selected note keys
deleteNoteKey <NoteKeyArray> <index_integer>

Deletes the indexed note key. Key indexes are 1-based.

sortNoteKeys <NoteKeyArray>

Re-sorts note keys according to their times. Some MAXNoteKey operations can result in out of order note keys and this function must be called to correctly order note keys.

818

Chapter 11

3ds max Objects

Associated Methods:
getNoteKeyTime <notetrack> <index>

Returns the time of indexed note key.

getKeyIndex < notetrack > <time>

Returns the index of the note key at the specified time.

MAXNoteKey Values
Note tracks store their notes as MAXNoteKeys. As seen by MAXScript, note keys are stored in a MAXNoteKeyArray. The MAXNoteKeyArray for a note track is accessed via the keys property of the note track. For more information on MAXNoteKeyArrays, see the MAXNoteKey Values (p. 818) topic. Constructor:
addNewNoteKey <MAXNoteKeyArray> <time> [ #select ]

Adds a new note key to the note track at the time specified. The new note key is also selected in the track view if the #select optional argument is specified. The value for the new note key is a null string.
<MAXNoteKeyArray>[<index_integer>]

Properties:
<MAXNoteKey>.time <MAXNoteKey>.selected write access. <MAXNoteKey>.value Time Boolean String -- time value or number (interpreted as frames) -- specifies whether the key is selected. Read/ -- string contained in the note key

Working with Note Tracks

Changing the time property of a note key may cause it to go out of time order relative to the other keys in the controller. You must call the sortKeys() function on the controller or associated MAXNoteKeyArray once all key time manipulations of this kind is complete so that animation will perform correctly. Example: Script:
s = sphere() -ntp1 = NoteTrack PosNT1 ntp2 = NoteTrack PosNT2 addNoteTrack s.pos.controller ntp1 controller addNoteTrack s.pos.controller ntp2 controller numNoteTracks s.pos.controller controller -- create a sphere -- create a note track -- create another note track -- apply first note track to spheres pos -- apply second note track to spheres pos -- check number of note tracks on pos

Working with Note Tracks

819

hasNoteTracks s.pos.controller -- test to see if pos controller has note tracks -addNewNoteKey ntp1.keys 20 #select -- add key to first note track, and select the key addNewNoteKey ntp1.keys 40 -- add another key to first note track -n = getNoteTrack s.pos.controller 1 -- retrieve first note track on the pos controller nk=n.keys -- retrieve an instance of the note track key array -nk[2].value = Yo Whats Up -- set value for second note key nk[2].time = 10 -- change the time for second note key. Now first key nk[1].selected = true -- select the first note key sortNoteKeys nk -- changed the time of the note keys, so resort nk.count -- check number of keys nk -- display the note keys --- To delete the note tracks and note keys deleteNoteKey nk 1 -- delete first note key deleteNoteKeys n.keys #allKeys -- delete all the note keys deleteNoteTrack s.pos.controller ntp1 -- remove note track from pos controller deleteNoteTrack s.pos.controller ntp2 -- remove note track from pos controller

Output:
$Sphere:Sphere02 @ [0.0,0.0,0.0] Notetrack:PosNT1 Notetrack:PosNT2 OK OK 2 true #Note key(1 @ 20f) #Note key(2 @ 40f) Notetrack: #keys(20f, 40f) Yo Whats Up 10 true OK 2 #keys(10f, 20f) OK OK OK OK ---------------------result result result result result result result result result result result result result result result result result result result result result line line line line line line line line line line line line line line line line line line line line line 1 3 4 5 6 7 8 10 11 13 14 16 17 18 19 20 21 24 25 26 27

820

Chapter 11

3ds max Objects

Node : MAXWrapper
Nodes represent 3ds max scene objects such as geometry, cameras, shapes, etc. Each kind of 3ds max scene object is represented by a class that inherits from Node. The classes derived directly from the Node class are described in the Node Subclasses (p. 849) topic. Other classes are derived from these classes, and inherit the properties and methods defined for the Node class. The properties, operators, and methods that are common to all classes derived directly from the Node class are described in the Node Common Properties, Operators, and Methods (p. 820) topic. The Node class is derived from the MAXWrapper class, and inherits the properties and methods defined for that class. These properties and methods are described in the MAXWrapper Common Properties, Operators, and Methods (p. 809) topic.

Node Common Properties, Operators, and Methods

The following properties and methods are applicable to any value that is derived from Node. Constructors:
<non_wild_card_pathname>

identifies a unique node in the scene

<objectset>[<integer>] <wild_card_pathname>[<integer>]

nth scene object in collection

<node_constructor> [ [ [ [ [ [ [ [ [ location [ [ [ name: <string> ] prefix: <string> ] material: <material> ] target: <node> ] pos: <point3> ] position: <point3> ] rotation: <quat> ] scale: <point3> ] pivot: <point3> ] \ \ \ \ \ \ \ \ \

------

default synonym default default default

[0,0,0] for pos 0 rotation 100% scale normal node pivot

transform: <matrix3> ] \ -- default identity isSelected: <boolean> ] \ -- default false dir: <point3> ] -- set local z direction

The position and rotation values are relative to the current active grid if coordsys grid is the current working coordinate system. A <node_constructor> is one of the scene node classes listed in Node Subclasses (p. 849), such as box, sphere, quadPatch, splineShape, etc. For example:
b = box name:foo position:[10,10,10] height:20

Working with Note Tracks

821

All of the node constructors can take the above optional keyword arguments, along with any of general node properties or any of the properties for the particular node class as keyword arguments. The name keyword can be used to specify the name for the created node. 3ds max allows the same name to be used for more than one node. The prefix keyword can be used in place of the name keyword argument to specify the start of the node name from which 3ds max will generate a unique name by adding a series of digits, as it does when creating objects interactively. For example:
for i in 1 to 100 do sphere prefix:baz

creates 100 spheres, giving each a unique name beginning with baz, such as $baz01, $baz02, $baz03, etc. The material keyword can be used to apply the specified material to the created node. The target keyword can be used to automatically apply a LookAt controller to the nodes transform track, and set the specified node as the LookAt target. The transformation arguments, pos, scale, rotation, and pivot, are applied to the new object in the order they are specified in the constructor call, so you can control transform order. The pos, scale, and rotation arguments are mutually exclusive with the transform argument which can be used as an alternative way to set the nodes complete transform matrix in one go. Note: Exercise care if you specify the target keyword. When you specify a target object, 3ds max stores with the target object the last object it was assigned as a target of. If you delete the target object, the behavior of 3ds max is to also delete the object looking at it. If the target object is a targetobject class object, deleting an object looking at it will also delete the target object, even if another object is also looking at it. Properties: See the General Node Properties (p. 836) and Node Transform Properties (p. 841) topics for details about the properties accessible on scene nodes. Methods: Most node methods are automatically mapped over node collections.
IsValidNode <var>

Returns true if <var> is a node value, and the node has not been deleted. Otherwise, it returns false.
move <node> <point3> scale <node> <point3> rotate <node> <angle> <axis_point3> rotate <node> <quat> rotate <node> <eulerangles> -----mapped mapped mapped mapped mapped

-- angle in degrees

all the transform operations operate in the current working coordinate system. See Context Expressions (p. 681).

822

Chapter 11

3ds max Objects

copy <node> reference <node> instance <node>

-- mapped -- mapped -- mapped

All the clone operations can take any of the standard node creation optional keyword arguments which are applied after the node has been copied. These functions clone all the original nodes transform controllers and keys and the visibility controller and its keys if a visibility track has been assigned.
snapshot <node> -- mapped

This function provides functionality similar to the SnapShot tool in 3ds max. It generates a new node that contains a copy of the world-state mesh of the source <node> at the time that the snapshot is made. Any existing modifiers are collapsed out of the new node and the mesh snapshot accounts for any space warps currently applied. As with the clone methods (copy, reference and instance,) you can add any of the standard node creation keyword arguments, such as pos:, name:, etc. The following example achieves an animation-based snapshot similar to the SnapShot tool in 3ds max:
for t in 0 to 100 do at time t snapshot $foo delete <node> -- mapped -- mapped -- mapped

Deletes the specified node(s).

instanceReplace <dest_node> <src_node> referenceReplace <dest_node> <src_node>

Lets you turn existing nodes into instances and references to other nodes. You can use these, for example, to replace the geometry of one node with another, perhaps for implementing custom level-of-detail tools. The <dest_node> is turned into an instance or reference to the <src_node>. As a new instance, existing geometry and modifiers are removed and replaced by the <src_node>s, but all the node-related properties are kept, such as material, transform, visibility, name, etc. As a new reference, the base object for the <dest_node> becomes the world-state of the <src_node>, such that any changes to the src_node will affect the <dest_node>, but changes to the <dest_node> are local to it. It is possible to develop a custom scripted version of the File/Replace function with these functions and the mergeMAXFile() function by temporarily changing the name of a node in the current scene, merging in that named node from another, making the first node an instance of the newly merged node with instanceReplace(), deleting the newly merged node and renaming the old node back again. Both these functions are collection mapped, so you can make a selection of objects all instance or reference the same object, for example:
instanceReplace $foo* $baz

makes all the foo* objects be instances of bazs geometry and modifier stack.
attachObjects <node1> <node2> [ move:<boolean> ]

Makes <node2> a child of <node1>. Resets the current location of <node2> to the location of <node1> unless move:false is specified.

Working with Note Tracks

823

getTMController <node>

Returns the transform controller for the node.

bindSpaceWarp <node> <spacewarp_node>

Binds the scene node to the space warp object scene node. Space warp bindings show up in the modifier stack and can be accessed like any other modifier. Use the deleteModifier() function to unbind objects from space warps. See the Modifier and SpacewarpModifier (p. 1095) topic for more information about working with the modifier stack.
getPolygonCount <node>

Returns a 2 element array containing the current number of faces for the node in the first element, and the current number of vertices for the node in the second element. The number of faces and vertices returned are the number that would be present if the node was converted to a mesh object.
isShapeObject <node>

Returns true if the node is a shape object, false otherwise

numSurfaces <node>

Returns the number of parametric surfaces in the object. At the current time, Loft objects are the only objects where more than one surface is present (ie. loft of a donut).
isSurfaceUVClosed <node> <surface_index_integer>

Returns a 2 element array indicating if the parametric surface is closed in the U and V dimensions (ie. a torus is closed in both U and V). Note that not all objects have this method implemented, and will return a default value of #(true, true).
getTransformAxis <node> <index>

Returns the transform axis of the indexed axis system of the node as a <matrix3> value. Normally a node justhas 1 transform axis. In some cases (like being in the Local Reference Coordinate System, in object SO mode, and having multiple SO selected), multiple transform axes exist. If index > the number of transform axis, the transform for the first transform axis is returned. The transform returned by this method can be used in an in coordsys context and an about context to move, rotate, or scale an object about the current 3ds max UI Reference Coordinate System and Center.

824

Chapter 11

3ds max Objects

For example:
fn axisRotate obj rotation = (local axis local objA = if classof obj == objectSet or classof obj == array then obj else #(obj) if getCoordCenter() != #local then (axis = getTransformAxis objA[1] 0 for obj1 in objA do in coordsys axis about axis rotate obj1 rotation ) else (for obj1 in objA do (axis = getTransformAxis obj1 0 in coordsys axis about axis rotate obj1 rotation ) ) ) invalidateTM <node>

Invalidates the nodes transformation matrix cache.

invalidateTreeTM <node>

Invalidates the nodes transformation matrix cach and notify the nodes subtree that the transformation matrix has changed. The following MAXScript function can be used to force an update of an object whose transform is partially controlled by a scripted controller (such as a script controller on the position track):
mapped fn TMInvalidate obj = (at time (currenttime-1) obj.transform nodeInvalRect obj invalidateTreeTM obj redrawViews() ) invalidateWS <node>

Invalidates the nodes world space cache.

getNodeByName <string> exact:<boolean>

Returns first <node> with the specified name. String case is insensitive unless exact:true. Default is exact:false
snapshotAsMesh <node>

Returns world state of node as a <mesh> value.

Working with Note Tracks

825

getInheritanceFlags <node> setInheritanceFlags <node> (#all | #none | <bitarray>) keepPos:<boolean>

Get and set the inheritance flags for the specified node as an <bitarray>. If a bit is on, the corresponding inheritance is turned on. The order of the bits is: #{POS_X,POS_Y,POS_Z,ROT_X,ROT_Y,ROT_Z,SCALE_X,SCALE_Y,SCALE_Z} If keepPos:false is specified, the node may move when an inheritance is turned on or off.
getTransformLockFlags <node> setTransformLockFlags <node> (#all | #none | <bitarray>)

Get and set the transform lock flags for the specified node as an <bitarray>. If a bit is on, the corresponding transform lock is turned on. The order of the bits is: #{POS_X,POS_Y,POS_Z,ROT_X,ROT_Y,ROT_Z,SCALE_X,SCALE_Y,SCALE_Z} -- Render-Related Methods
getInheritVisibility <node>

Returns true if the node inherits the visibility of its parent object (if any), false if not.
setInheritVisibility <node> <boolean>

Sets whether the node inherits the visibility of its parent object (if any). If <boolean> is true, node inherits visibility. If <boolean> is false the node does not inherit visibility.
getVisController <node>

Returns an instance of the nodes visibility controller. Returns undefined if the node does not have a visibility track.
getImageBlurMultController <node>

Returns the nodes Image Motion Blur Multiplier controller. Returns undefined if not Image Motion Blur Multiplier controller has been assigned to the node.
setImageBlurMultiplier <node> <time> <number>

Sets the nodes Image Motion Blur Multiplier value at the specified time to the specified value
setImageBlurMultController <node> <controller>

Sets the nodes Image Motion Blur Multiplier controller to the specified controller
setMotBlur <node> <integer>

Sets which type of motion blur to use for node. If <integer> = 1, None. If <integer> = 2, Object Motion Blur. If <integer> = 3, Image Motion Blur.
setRenderable <node> <boolean>

Sets whether the node is renderable. If <boolean> is true, node is renderable. If <boolean> is false the node is not renderable.
getRenderID <node>

Returns the RenderID of the node. A value of 65535 is returned if the scene has not yet been rendered, or the node is not renderable. The RenderIDs of the nodes are output to the NODE_RENDER_ID g-buffer channel by the renderer.
setRenderID <node> <integer>

Sets the RenderID of the node to the specified value. This value is not sticky - it is not saved with the scene, and it will be replaced by the renderer when the next render occurs.

826

Chapter 11

3ds max Objects

-- Group-Related Methods
group <node> [ name:<string> ] [ prefix:<string> ] \ [ select:<boolean> ] -- mapped

Makes a group of the given nodes and returns the group node. You can optionally specify the group name or group name prefix. Not specifying a name or specifying a group name prefix ensures that the group name assigned is unique. Specifying select:true selects the group after it is made. For example:
group $box* name:boxes

makes a group of all box*s named boxes.

group selection

groups current selection.

ungroup <group_head_node> -- mapped

Ungroups one level of a group node. For example:

ungroup $group01

ungroups group $group01

explodeGroup <group_head_node> -- mapped

Ungroups all levels in a group node.

isGroupHead <node>

Returns true if node is group head, false otherwise.

isGroupMember <node>

Returns true if node is in a group, false otherwise.

isOpenGroupMember <node>

Returns true if <node> is a member of a group, and that group is open.

isOpenGroupHead <node>

Returns true if <node> is the head of a group, and that group is open.
setGroupOpen <group_head_node> <boolean>

Sets whether the group is set as open or closed. If <boolean> is true, the group is set as open. If <boolean> is false the group is closed.

Working with Note Tracks

827

*** Use the following methods with care. You can place nodes in states that are impossible to accomplish using the 3ds max user interface. ***
setGroupMember <node> <boolean>

Sets whether the node is a group member or not. If <boolean> is true, node is set as a group member. If <boolean> is false, and the node is a group member, the node is set as not being a group member and is unlinked from the group head. Note: If you set a node to be a group member using this method, you need to set the node to be a child of a group head. Otherwise, the node name is not shown in the Select By Name dialog. For example:
setGroupHead $dummy01 true append $group03.children $dummy01 setGroupHead <node> <boolean>

Sets whether the node is flagged as a group head or not. If <boolean> is true, node is flagged as a group head. If <boolean> is false, the node is set as not being a group head. Note: If you flag a node as a group head using this method, the nodes mesh will not be displayed in the viewports, and its properties will not be shown in the Modify panel. If you flag a group head node as not being a group head using this method, you will not be able to Open or Explode the group via the Group menu command. Example:
-- create a set of spheres, group them, and test group head and member of group mySpheres=for i=1 to 5 collect sphere pos:(random [-100,-100,0] [100,100,0]) group MySpheres name:MyGroup isGroupHead $MyGroup -- returns true isGroupMember $sphere01 -- returns true -- check to see if group is open. Open group and test member of group isOpenGroupHead $MyGroup -- returns false setGroupHeadOpen $MyGroup true isOpenGroupMember $sphere01 -- returns false -- create a new set of spheres, append the group to the set, and then group them all NewSpheres=for i=1 to 3 collect sphere pos:(random [-100,-100,0] [100,100,0]) append NewSpheres $MyGroup group NewSpheres name:BiggerGroup -- open the group head, test member of group, and then close the groups. setGroupHeadOpen $BiggerGroup true isOpenGroupMember $MyGroup setGroupHeadOpen $MyGroup false setGroupHeadOpen $BiggerGroup false

828

Chapter 11

3ds max Objects

-- Node Viewport State Methods

hide <node> unhide <node> freeze <node> unfreeze <node> flagForeground <node> <boolean> -----mapped mapped mapped mapped mapped

Controls the disposition of scene nodes in the viewport foreground/background planes, so you can influence interactive performance on a node. Nodes placed in the foreground plane are redrawn individually and so interactive changes to them through spinners in scripted rollout panels are much faster. The boolean argument puts the scene node(s) into the foreground plane if true, or into the background plane if false. You should be judicious in putting nodes in the foreground plane, because putting too many objects in the foreground plane reduces the foreground planes effectiveness. Remember to unflag objects when you dont need to interactively control them any more.
getTrajectoryOn <node>

Returns true if Trajectory is shown for the node, false otherwise.

setTrajectoryOn <node> <boolean>

Sets whether Trajectory is shown for the node. If <boolean> is true, Trajectory is shown. If <boolean> is false, Trajectory is not shown.
isBoneOnly <node>

Returns true if the nodes showLinksOnly property is true.

getCVertMode <node>

Returns true if node is displayed using vertex colors in shaded viewports, false otherwise.
setCVertMode <node> <boolean>

Sets whether to display the effect of assigned vertex colors for the node in shaded viewports. If <boolean> is true, node is displayed using vertex colors. If <boolean> is false, node is displayed using the material or wireframe color.
getShadeCVerts <node>

Returns true if the vertex color display for the node is shaded in the viewports, false otherwise.
setShadeCVerts <node> <boolean>

Sets whether the vertex color display for the node is shaded in the viewports. When true, the colors are unshaded and appear in their pure RGB values. When false, the colors appear like any other assigned color in the viewports.

Working with Note Tracks

829

-- Node Selection Methods

clearSelection() clearNodeSelection [ redraw:<boolean> ]

Deselects all currently selected scene nodes. Scene is redrawn unless redraw:false is specified.
deselect <node> -- mapped

Deselects the given node(s). For example:

deselect $box*

deselects all items whose names start with box.

deselectNode <node>

Deselects a single node

select <node> selectMore <node> -- mapped -- mapped

Deselects any currently selected objects and then selects the node(s) you specified. Adds the node(s) to the set of selected objects. If you want to build a set of selected objects from scratch in a loop, you can use clearSelection() to clear the selection before entering the loop, and use selectMore() in the loop to add objects to the set of selected objects. -- Modifier Stack Related Methods
validModifier [ <node> | <objectset> | <group> ] <modifier>

Tests whether a particular modifier may be added the given <node> or to all of the objects in the objectset or group. Returns true if so, false if not. The validModifier() method operates exactly as does the Modify panel in determining modifier applicability. Any modifier that takes a deformable object will return true for all scene objects except Helpers. This corresponds to the Modify panels behavior of allowing modifiers such as Bend, Taper, etc. to be applied to lights and cameras, space warp objects, etc., as well as geometry types like box, sphere, etc., but not helpers such as dummys or bones. The validModifier() method will return true if an empty <objectset> is specified, or if a <group> is specified and the modifier is valid for all members of the group. In these cases, applying the modifier using the addModifier() method will fail, because the <objectset> is empty in the first case, or because the modifier cannot be applied to the dummy object that is the parent object of the objects in the group. You will need to test for these conditions in your script, or use the modPanel.addModToSelection() method described in the Modify Panel (p. 1572) topic.
addModifier <node> <modifier> [before:index] -- mapped

Applies the modifier to all instances of the node(s) to which the function is applied. The optional before: keyword argument can be used to insert the modifier into the nodes modifier stack just before the indexed modifier, counting from the top of the stack. The added modifier will apply to any appropriate active sub-object selection in the node only if

830

Chapter 11

3ds max Objects

the node is currently selected and open in the Modify panel at the desired sub-object level. You can use the 3ds max System global variable, subObjectLevel to test and set the level for the object currently open in the Modify panel. For example:
max modify mode select $box01 subObjectLevel = 3 addModifier $box01 (ffd_2x2x2()) ----open mod panel select box01 into mod panel subobject level to Face add FFD mod to those faces

If <node> is a collection, an instance of the modifier is placed on each of the nodes in the collection. Unlike interactively applying a modifier to a selection, the position and size of each modifier instances gizmo corresponds to position and size of the node the modifier instance is applied to. To apply a modifier to a collection in the same manner that 3ds max applies modifiers, use the modPanel.addModToSelection() method described in the Modify Panel (p. 1572) topic. Also see the Modifier and SpacewarpModifier (p. 1095) topic for more details.
deleteModifier <node> <modifier_or_index> -- mapped

Lets you delete modifiers from the modifier stack. Takes either a modifier value which is present on the <node> stack, or an index specifying the index of the modifier to delete, counting from the top of the stack.
collapseStack <node> -- mapped

Collapses the modifiers out of a stack, leaving a resultant editable mesh as the base object of the node(s). If there are no modifiers in the stack when this is called, no action is taken. If you want to force an object to be an editable mesh, use the function convertToMesh(). -- Node Modifier Transform Context Methods
getModContextTM <node> <modifier>

Returns a Matrix3 value giving the modifiers context transform for the local coordinates used in modifier sub-object gizmos. Accessing the transform properties of a modifier subobject such as a gizmo or a center in MAXScript yields values that are relative to that modifiers context transform, equivalent to the values shown in track view for those properties. If the modifier is not operating on a sub-object selection, such as a face or vertex selection, or if the modifier was interactively applied to an object selection, this context TM is the local coordinate space of the object itself. However, if the modifier is operating on either an object selection set or a sub-object selection, the context transform gives the position and orientation of that selection, and so you can use the getModContextTM() function to get the world-space transform properties of any of its sub-objects.

Working with Note Tracks

831

getModContextBBoxMin <node> <modifier> getModContextBBoxMax <node> <modifier>

These functions complement the getModContextTM() function and can be used to derive the world-space coordinates of the bounding box of the modifier context. This can be used, for example, to determine the bounds of a modifier operating on a sub-selection or the bounds of an FFD lattice. This is particularly useful for scripting FFD control point placement, since these control points live in a 0-to-1 lattice space--the mod context bounding box gives the world space bounds of this lattice space allowing you to compute scaled lattice space coordinates from world coordinates. The functions return Point3 values for the minimum and maximum extents of the bounding box. See the Modifier Sub-Object Transform Properties (p. 1099) topic for examples of using the above methods. -- Node Conversion Methods
convertToMesh <node> -- mapped

This function converts appropriate scene object types into Editable Meshes. It is similar to collapseStack() in that it will remove all modifiers present, but unlike collapseStack() it will always replace the base object with an editable mesh version, even if there are no modifiers present. convertToMesh() can be applied to any object that an Edit Mesh modifier can work on, such as geometry and shapes, but not helpers, space warps, lights, etc. If the object cannot be converted, the function returns undefined.
convertToSplineShape <node> -- mapped

Converts the given scene node to a SplineShape object. If the object cannot be converted (typically, if it is not a shape), the function returns undefined. Any modifiers present will be collapsed. The collapseStack() function can also be used as can the collapse button in the modifier stack dialog in 3ds max; both generate a SplineShape, but will only do so if there is at least one modifier present.
canConvertTo <node> <class>

Allows you to test whether a given node is convertible into a given class. Returns true or false. For example:
if canConvertTo $foo NURBSSurface then ...

The kinds of classes you can convert objects to are the generic editable forms including Mesh, SplineShape, NURBSCurve, NURBSSurface, etc.
convertTo <node> <class> -- mapped

This function is a general form of the existing specific conversion functions such as convertToMesh(), convertToSplineShape(), etc. For example, convertToSplineShape() can be written:
convertTo $circle01 SplineShape

If the conversion is not supported, the function returns the value undefined.

832

Chapter 11

3ds max Objects

convertToNURBSSurface <node> convertToNURBSCurve <node>

-- mapped -- mapped

These functions work on those primitive geometry and shape classes that support conversion to NURBS (such as boxes, spheres, circles, lines, etc.). If an object does not support conversion, the function returns undefined. -- Node Utility Methods
isDeleted <MAXWrapper_object>

This function yields the result true if the object has been deleted and false if it still exists in the scene. Using the function only makes sense in situations where references to 3ds max objects are held in variables or arrays or passed as parameters and you want to determine whether the object has been deleted from the scene. Performing an operation on a deleted 3ds max object referenced in a variable or array otherwise generates an exception. Any kind of 3ds max object can be tested in this way, scene objects, modifiers, controllers, materials, etc. For example:
sel = selection as array -- snapshot selection ... -- <one or more objects in the selection are deleted, -- by the user or other scripts> ... for obj in sel where not isDeleted obj do move obj [10,0,0] distance <node> <node>

Computes the distance between the pivot points of the two specified nodes.
intersectRay <node> <ray>

Computes the closest intersection of the ray and the surface of the given node. Returns another Ray which defines the position of intersection in 3D space and the surface normal direction vector at that point. The intersection test respects the face normals of the node, i.e. if a faces normal points away from the rays source, an intersection test is not performed on that face. intersectRay() works if the world state of the node (the state of the node at the top of the nodes stack) has a surface, such as an editable mesh, a Standard, Extended, or Compound Primitive, or a Patch or NURBS surface object. Splines and NURBS curves do not have a surface. Returns undefined if the ray doesnt intersect the node, the faces it does intersect point away from the rays position, or the node does not have a surface.

Working with Note Tracks

833

intersectRayEx <node> <ray>

Takes a ray and computes the closest intersection to the surface of the given node. It returns an array with the following three elements. 1.A Ray defining the position of intersection in 3-space and the surface normal direction vector at the point. 2.The index of the face the ray intersects with 3.The barycentric coordinates of the face that was hit. This method only works if the world state of the node is a mesh, either because it started as an editable mesh or because it has modifiers applied that convert the node to a mesh. Unlike intersectRay(), this method will not work if the node is a Standard or Extended Primitive - the nodes stack must evaluate to a mesh. The intersection test respects the face normals of the node, i.e. if a faces normal points away from the rays source, an intersection test is not performed on that face. Returns undefined if the ray doesnt intersect the node, the faces it does intersect point away from the rays position, or the node isnt a mesh. Barycentric coordinates are the coordinates relative to the triangular face. The barycentric coordinates of a point p relative to a triangle describe that point as a weighted sum of the vertices of the triangle. If the barycentric coordinates are b0, b1, and b2, then:
p = b0*p0 + b1*p1 + b2*p2;

where p0, p1, and p2 are the positions of the vertices of the triangle. The Point3 returned by this method has the barycentric coordinate stored in its three component values. The coordinate is relative to the triangular face that was intersected. Barycentric coordinates can also be used to interpolate any quantity whose value is known at the vertices of the triangle. Following is an example of finding the UV coordinates at the intersection point: Script:
s = sphere material:(standardMaterial diffuseMap:(checker())) showTextureMap s.material s.material.diffuseMap on --- Add a normal modifier to make the sphere into a mesh addModifier s (normalModifier()) r = ray [-100,5,0] (s.center-[-100,5,0]) --- Get the Intersection details arr = (intersectRayEx s r) --- Create a dummy at the point of intersection dummy pos:(arr[1]).pos --- Get the texture face tf = getTVFace s arr[2] --- Get the UVW verts of the face tv1 = getTVert s tf.x

834

Chapter 11

3ds max Objects

tv2 = getTVert s tf.y tv3 = getTVert s tf.z --- Calculate the texture vertices at point of intersection from -- the barycentric coordinates tv = tv1*arr[3].x + tv2*arr[3].y + tv3*arr[3].z --- Delete the modifier deleteModifier s 1 intersects <node> <node>

Returns true if the bounding boxes of the two specified nodes overlap, or false if they do not overlap.
printStack <node>

Prints a representation of the current modifier stack for the given node. -- Node User Properties
getUserProp <node> <key_string>

Retrieves the nodes user property with the given key as a string. <key_string> is either a String or a Name value. If the key does not exist, a value of undefined is returned.
setUserProp <node> <key_string> <value>

Sets the nodes user property with the given key to the given value.
getUserPropBuffer <node>

Retrieves the entire user property buffer as a string containing all the user property settings. This is effectively the contents of the User Defined Properties box in the 3ds max Object Properties dialog.
setUserPropBuffer <node> <string>

Sets the user property buffer to the given string. See the Node User-Defined Properties and Methods (p. 848) topic for more information on these methods. -- Inverse Kinematics Properties The following methods get and set the nodes IK values as seen in the Hierarchy panel, Object Parameters rollout.
getRotTaskWeight <node>

Returns the rotation binding weight for the node.

setRotTaskWeight <node> <float>

Sets the rotation binding weight for the node.

getPosTaskWeight <node>

Returns the position binding weight for the node.

setPosTaskWeight <node> <float>

Sets the position binding weight for the node.

getTaskAxisState <node> <pos_or_rot_integer> <axis_integer>

Returns true or false to indicate if the specified axis is turned on for position or rotation binding. If an axis is turned off, the specified axis is no longer influenced by the follow

Working with Note Tracks

835

object or the IK Controller Position end effector. <pos_or_rot_integer> sets whether the method returns the position state or the rotation state: 0 specifies position; 1 specifies rotation. <axis_integer> sets the axis to check: 0 specifies X, 1 specifies Y, 2 specifies Z.
setTaskAxisState <node> <pos_or_rot_integer> <axis_integer> <boolean>

Sets the axis state for position or rotation binding to the specified boolean value. See getTaskAxisState() for a description of the parameters.
mirrorIKConstraints <node> <axis_integer> <pos_or_rot_integer>

Mirrors the specified IK constraints on the specified nodes transform controller about the specified axis. <axis_integer> specifies the axis of reflection: 0 for X, 1 for Y, 2 for Z. <pos_or_rot_integer> specifies which type of constraints are being mirrored: 0 for position, 1 for rotation.
nodeIKParamsChanged <node>

Call this method when one of the node level IK parameters has been changed.
OKToBindToNode <ik_node> <node>

Returns true if the <ik_node> can be bound to the <node> as a follow object, false otherwise. If the <ik_node> is not part of an IK system, this method always returns true. This method tests <node> to see if its transform is in any way already dependent on the IK system, and returns false if it is. Miscellaneous Methods:
classOf <node>

Returns the class of the world state of the node (the state of the node at the top of its stack). If no modifiers are applied to the base object, the class returned is the class of the base object. If modifiers are applied to the base object, the class returned is the class of the node as it exits the last modifier. For example, if you apply a Bend modifier to a Box, the Bend modifier converts the incoming Box primitive to a mesh, and the class returned by classOf is Editable_Mesh. You can get the class of the base object in all cases by using classOf <node>.baseObject.
isPointSelected <node> <point_index>

Returns true if the specified point is selected, false if not. The definition of a point varies depending on the object type. For meshes, it is the mesh vertex. For a spline, it is the knot. For NURBS objects, it is the vertex or control point.
pointSelection <node> <point_index>

Returns a floating point weighted point selection if the object supports soft selections. Most object types just return 1.0 if the point is selected and 0.0 if not. Only NURBS and Editable Mesh objects currently support weighted point selection.
nodeInvalRect <node>

Invalidates the rectangle in the viewports that the node is occupying. Rectangles flagged as invalid will be update on the next screen redraw.
stopCreating <node>

This method stops the creation of the current object, if any. This method is primarily used to ensure that a NURBS objects is fully created, which it until the creation is stopped. This method will also deactivated any activated object create buttons in the Create panel.

836

Chapter 11

3ds max Objects

Associated Methods:
uniqueName <prefix>

Generates a unique scene node name from a prefix string by adding a series of digits, in the same manner the 3ds max does as you create objects in the scene. This name is only guaranteed to be unique until the next scene node creation. For example:
$foo.name = uniqueName foo

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) General Node Properties (p. 836) Node Transform Properties (p. 841) Node User-Defined Properties and Methods (p. 848) Nested Object Properties (p. 815) Class and Object Inspector Functions (p. 799) Dynamic Properties (p. 805) Node Subclasses (p. 849) NURBS Node Properties and Methods (p. 1397)

General Node Properties

All the properties listed here are accessible on any node subclass. Unless otherwise noted, these properties can not be animated.
<node>.name <node>.baseObject String A subclass of Node default: varies default: varies -- read-only

Get or set the scene objects name. Retrieve the base object in a scene node. This has relevance in nodes that have modifiers present that change the node type as it is processed up the stack. For example, a line with an extrude modifier starts out as a Shape and turns into an Editable Mesh at the top of the stack, its so-called world state. The baseObject property gives you access to the base object in the modifier stack. Because the classOf() function on scene node objects returns the class of the world state object (the top of the stack), you can use the baseObject property to determine the class of the original object used to create the node. This property is read-only.
<node>.material Material default: undefined

Get or set the objects material.

General Node Properties

837

<node>.parent

Node

default: undefined

Get or set the parent of the object. If the object is a top-level object, accessing the parent property will return undefined. For example,
foo_mom = $foo.parent $foo.parent = $baz

Setting the this property has the effect of detaching <node> from its original parent and attaching it as a child of the specified node. You can detach an object and make it a top-level object by assigning undefined to the parent property:
$foo.parent = undefined <node>.children NodeChildrenArray default: undefined

This yields a special array subclass, NodeChildrenArray. See the NodeChildrenArray Values (p. 785) topic. A NodeChildrenArray can be accessed using normal MAXScript array indexing and can be sequenced over in a for loop or with collection-mapped functions, for example:
c = $foo.children[i] move $foo.children [10,10,10] for c in $baz.children do print c

You can get the number of children via the count property:
num_children = $foo.children.count

You cannot directly set a child by indexing into NodeChildrenArray, but you can append new children using the append() function and delete children using the deleteItem() function:
$foo.children[$foo.children.count+1]=$baz append $foo.children $baz deleteItem $foo.children $baz -- does not work -- works -- removes $baz as child

The ordering of child indexes corresponds to the ordering shown in the 3ds max hierarchy view, which is the order in which the children were added to the parent.
<node>.mesh TriMesh

For scene nodes or base objects that are Editable Mesh objects, or are convertable to Editable Mesh objects, this property yields a TriMesh containing a copy of the source objects mesh after any modifiers have been applied, but before any space warps have been applied. This property is read-only unless the scene node or base object is an Editable Mesh object, in which case the specified TriMesh replaces the base object. See the Editable_Mesh : GeometryClass and TriMesh : Value (p. 1041) topic for more information on TriMesh and Editable Mesh.

838

Chapter 11

3ds max Objects

-- Target/LookAt Related Properties

<node>.isTarget Boolean default: false

Returns true if then node is the target of another objects LookAt controller, false if it is not. If the object is the automatically created target object of a lights or cameras LookAt controller, and you set this property to false, you can delete the target object without causing the light or target to be deleted.
<node>.lookAt Node default: undefined

Get a node that is looking at <node>, or set a node to look at <node>. This is the converse of the <node>.target property. If <node> is not the target of some objects LookAt controller, the value undefined is returned. If <node> is the target of more than one object, only one such object is returned. If this property is used to set <node> as the target of another object, a LookAt controller is automatically assigned to that object.
<node>.target Node default: undefined

Get or set the target node for <node>s LookAt controller. Returns undefined if there is no target or the node does not have a LookAt controller. If this property is used to set an object as the target of <node>, a LookAt controller is automatically assigned to <node>. Exercise care if you assign a node to the target property. When you specify a target object, 3ds max stores with the target object the last object it was assigned as a target of. If you delete the target object, the behavior of 3ds max is to also delete the object looking at it. If the target object is a targetobject class object, deleting an object looking at it will also delete the target object, even if another object is also looking at it.
<node>.targetDistance Float default: undefined

Get or set the distance from the node to its target. Returns undefined if <node> does not have a target. Setting this property moves the target along the object-to-target vector to the distance specified. For example,
$spot01.targetDistance $cam2.targetDistance = 100

-- Viewport Related Properties

<node>.isSelected <node>.isHidden Boolean Boolean default: false default: false

Get or set whether the node is selected. Get or set whether the node is flagged as hidden in the viewports. A node may be hidden even if this property is false. If the nodes category is marked as hidden in the Hide by Category rollout in the Display panel, or if the node is flagged as frozen and Hide Frozen Objects is on in the Hide rollout in the Display panel, the node will be hidden regardless of this propertys value.
<node>.xray <node>.ignoreExtents Boolean Boolean default: false default: false

Get or set whether the node is displayed in See Through mode in shaded viewports. Get or set whether the extents of the node is ignored when performing a zoom extents.

General Node Properties

839

<node>.boxMode <node>.allEdges <node>.backFaceCull <node>.wireColor <node>.showLinks

Boolean Boolean Boolean Color Boolean

default: false default: false default: false default: random color default: false

Get or set whether the node is displayed in box mode in the viewports. Get or set whether all the nodes edges are displayed in the viewports. Get or set whether the nodes back faces are culled (not displayed) in the viewports. Get or set the nodes wireframe color Get or set whether to display a wireframe representation of the hierarchical link(s) from the node to its children.
<node>.showLinksOnly Boolean default: false

Get or set whether to display only the wireframe representation of the hierarchical link(s) for the node. Setting this property to true also sets showLinks to true.
<node>.isFrozen <node>.showTrajectory <node>.showVertexColors Boolean Boolean Boolean default: false default: false default: false

Get or set whether the node is frozen in the viewports. Get or set whether the nodes trajectory is displayed in the viewports. Get or set whether to display the effect of assigned vertex colors for the node in shaded viewports.
<node>.vertexColorsShaded Boolean default: false

Get or set whether the vertex color display for the node is shaded in the viewports. When true, the colors are unshaded and appear in their pure RGB values. When false, the colors appear like any other assigned color in the viewports.
<node>.isDependent Boolean default: false

Returns true if the node has its dependent flag set, otherwise returns false. A node is dependent in the sense of 3ds maxs Views/Show Dependencies mode. When the Modify panel is open, Show Dependencies will show all the nodes that are dependent on the current modifier or object being editing by highlighting them in green, and the dependent flag for the node is set. This property will always return false if the Modify panel is closed, or if Views/Show Dependencies is off. This property is read-only. -- Rendering Related Properties
<node>.castShadows Boolean default: true

Get or set whether the node casts shadows when rendered. This property parallels the Cast Shadows property in an objects right-click Object Properties dialog.
<node>.receiveShadows Boolean default: true

Get or set whether the node casts shadows when rendered. This property parallels the Receive Shadows property in an objects right-click Object Properties dialog.

840

Chapter 11

3ds max Objects

<node>.gbufferChannel

Integer

default: 0

Get or set the nodes g-buffer Object ID channel value. Valid object ID values in 3ds max range from 0 to 65535. This property parallels the G-Buffer Object Channel property in an objects right-click Object Properties dialog.
<node>.visibility Boolean default: true -- animatable

This is a boolean property (unlike its value as a signed float in the 3ds max Track View) true or on denotes visible, false or off invisible. Animate this property to control an nodes visibility at render-time, for example:
animate on ( at time 0 $foo.visibility = on at time 35 $foo.visibility = off at time 57 $foo.visibility = on )

The controller for this property is stored in the 1st subAnim of the node. You can access this controller as:
<node>[1].controller -- the visibility controller

You can also get a nodes visibility controller using the getVisController() method.
<node>.inheritVisibility Boolean default: true

Get or set whether the node inherits the visibility of its parent object (if any). This property parallels the Inherit Visibility property in an objects right-click Object Properties dialog.
<node>.renderable <node>.renderOccluded Boolean Boolean default: true default: false

Get or set whether the node is renderable. Get or set whether to Render Occluded Objects behind the node. This property parallels the Render Occluded Objects property in an objects right-click Object Properties dialog.
<node>.motionBlurOn Boolean default: true

Get or set whether motion blur is enabled for the object. This property parallels the Motion Blur Enabled property in an objects right-click Object Properties dialog.
<node>.motionBlurOnController <node>.motionBlur Controller Name default: undefined default: #none

Get or set the motion blur on/off controller used for the node. Get or set the type of motion blur to be used for the node. Valid parameter values are: #none, #object, and #image. For backward compatibility, this property can also be set to false for none or true for object motion blur. This property parallels the Motion Blur type specified in an objects right-click Object Properties dialog.

Node Transform Properties

841

<node>.imageMotionBlurMultiplier Float

default: 1.0

-- animatable

Get or set the nodes image motion blur multiplier value. The controller for this property is stored in the 6th subAnim of the node. You can access this controller as:
<node>[6].controller -- the imageMotionBlurMultiplier controller

You can also get and set a nodes imageMotionBlurMultiplier controller using the getImageBlurMultController() and setImageBlurMultController() methods.
<node>.rcvcaustics Boolean default: true

Get or set whether the node receives caustics. Caustics are not supported by the 3ds max scanline renderer.
<node>.generatecaustics Boolean default: false

Get or set whether the node generates caustics. Caustics are not supported by the 3ds max scanline renderer.
<node>.rcvGlobalIllum Boolean default: true

Get or set whether the node receives global illumination. Global illumination is not supported by the 3ds max scanline renderer.
<node>.generateGlobalIllum Boolean default: false

Get or set whether the node generates global illumination. Global illumination is not supported by the 3ds max scanline renderer.

Node Transform Properties

Unless otherwise noted, the following transform properties are always interpreted with respect to the current working coordinate system as defined by the currently active coordsys context (p. 681). The default coordsys is world. The pos, rotation, and scale properties of a node are aliases to the corresponding subcontroller for the nodes transform controller. If the transform controller does not have one of these subcontrollers, accessing the corresponding node property will result in an Unknown property error message. For example, the LookAt controller does not have a Rotation subcontroller, and the IK controller does not have any subcontrollers. You can still access the transform values using the Matrix3 properties of the nodes transform property, for example, objpos=obj.transform.translationpart.
<node>.transform : : : : : : : : : : : Matrix3 -- can read/write to. If written to, the Matrix3 value is decomposed into its position, rotation, and scale values, and these values are stored in the respective position, rotation, and scale controllers, if those controllers exist and can be written to. Point3 -- can use .position synonym throughout Controller -- can use .track synonym throughout Boolean, read-only -- true if position is animated MAXKeyArray Controller -- synonym of .pos.controller

<node>.pos <node>.pos.controller <node>.pos.isAnimated <node>.pos.keys <node>.pos.track <node>.rotation

: Quat

842

Chapter 11

3ds max Objects

<node>.rotation.x_rotation <node>.rotation.y_rotation <node>.rotation.z_rotation <node>.rotation.controller <node>.rotation.isAnimated <node>.rotation.keys <node>.rotation.track <node>.scale <node>.scale.controller <node>.scale.isAnimated <node>.scale.keys <node>.scale.track <node>.dir

: : : : : : : : : : : :

X rotation of node Y rotation of node Z rotation of node Controller -- can use .track synonym throughout Boolean, read-only -- true if rotation is animated MAXKeyArray Controller -- synonym of .rotation.controller Point3 -- fraction Controller -- can use .track synonym throughout Boolean, read-only -- true if scale is animated MAXKeyArray Controller -- synonym of .scale.controller

: Point3 -- local z-axis direction vector

Rotates node so that the nodes Z axis points in the specified direction. The node is rotated around its Z axis such that the Y axis points as much as possible in the world -Z direction.
<node>.max bounding box <node>.min bounding box <node>.center <node>.transform : Point3, read-only -- max coordinates of nodes : Point3, read-only -- min coordinates of nodes : Point3 -- coordinates of center of nodes bounding box : Matrix3 -- nodes main transformation matrix

Note that rotation in the internal transformation matrices is left-handed in contradiction to the 3ds max user interface and MAXScript. Take care when mixing rotation derived from these matrices and rotation used in rotation-related functions or from rotation properties.
<node>.pivot <node>.objectOffsetPos <node>.objectOffsetRot <node>.objectOffsetScale <node>.objectTransform : Point3 : Point3 : Quat : Point3 : Matrix3, read-only -- nodes pivot point position

Node geometrys position, rotation, and scale offset from the pivot in world coordinates. Node geometrys offset in world coordinates.

See also
Using Node Transform Properties (p. 843)

Using Node Transform Properties

843

Using Node Transform Properties

This topic provides information on three transforms related to nodes -- the Node Transform Matrix, the Object-Offset Transform Matrix, and the Object Transform Matrix. The Node and Object-Offset Transform Matrices are stored by 3ds max. The Object Transform Matrix is derived from these two matrices. This topic also presents information on how these transforms are constructed and how they are used by 3ds max, and how they can be accessed and manipulated in MAXScript. The Pivot Point -- The Node Transform Matrix The transform center, or pivot point, is the location about which a rotation takes place, or to and from which a scale occurs. All nodes in 3ds max have a pivot point. You can think of the pivot point as representing a nodes local center and local coordinate system. The pivot point of a node is used for a number of purposes: As the center for rotation and scaling. Defines the transform origin for linked children. Defines the joint location for Inverse Kinematics.

The thing that most users think of as the pivot point -- graphically represented in 3ds max by the axis tripod that is displayed when a node is selected and the coordinate system is set to local -- is actually just a visual representation of the nodes transform matrix. The nodes transform matrix is what is controlled by the transform controller that places the node in the scene. The transform controller controls the transform relative to the nodes parent. Construction of the Node Transform Matrix for the PRS Transform Controller The PRS controller uses sub-controllers to create the final transform. There are three sub-controllers -- one for Position, one for Rotation, and one for Scale. The PRS controller is passed the transform matrix of the nodes parent. If the node has no parent, the matrix starts out as the identity matrix. The PRS controller first calls the position controller, then the rotation controller, then the scale controller. First the position controller pre-multiplies the input matrix is by the position value. If the matrix passed is the identity matrix, this is equivalent to setting the bottom row (the translation row) of the matrix. Next, the rotation controller pre-multiplies the matrix by the rotation value. Finally, the scale controller pre-multiplies the matrix by the scale value. Some position controllers can actually apply more than just position to the matrix. For example, the Path Controller, when the Follow switch is active, actually applies some rotation to have the node remain tangent to the path it is following. Thus when the rotation controller receives the matrix, the matrix already has some rotation applied. The matrix, after the position, rotation and scale controllers have updated it, becomes the Node Transform Matrix 3ds max uses to position, rotate and scale nodes in the scene. Thus, the entire transform is:
Node Transform Matrix = Controller Scale * Controller Rotation * Controller Position * Parent Transform Matrix

844

Chapter 11

3ds max Objects

The Object-Offset Transform Matrix The Object-Offset Transform Matrix provides an offset of the geometry of an object from its node. One can see a nodes pivot point graphically represented in 3ds max by selecting a node, going to the Hierarchy branch of the Hierarchy panel, selecting the Pivot button, and choosing either the Affect Pivot Only or Affect Object Only button. This displays a large axis tripod that shows the location and orientation of the nodes pivot point. By choosing one of these buttons, and using the Move/Rotate/Scale toolbar controls, a user can manipulate the position of the geometry of the object independent of the pivot point. Or they may manipulate the pivot point independent of the geometry of the object. The way the user is able to independently manipulate the pivot and the object is managed internally using the Object-Offset Transform Matrix. The Object-Offset Transform Matrix affects how the geometry of the object is related to the node. The Object-Offset Transform Matrix transforms the geometry of the object itself some amount from the node. To understand how the Object-Offset Transform Matrix is used, consider the following example from the 3ds max user interface. In the Hierarchy branch under Pivot, when the user has chosen the Affect Object Only button they are free to move the geometry of the object around independent of the node. The pivot point does not move -- only how the geometry of the object is oriented relative to the pivot. What is happening internally is that the Object-Offset Transform Matrix is being manipulated. This transform is simply an additional offset that is applied to the geometry of the object that is independent of the node. The Object-Offset Transform Matrix is not inherited by any child nodes. As another example consider the use of the Affect Pivot Only button. This mode lets the user move the pivot without affecting the position of the geometry of the object. When the user moves the pivot point, what is actually happening is the Node Transform Matrix is being altered (to re-orient the pivot point), then the Object-Offset Transform Matrix is adjusted to counter the node transform. This lets the geometry of the object stay in the same place while the pivot point moves around. Construction of the Object-Offset Transform Matrix The Object-Offset Transform Matrix consists of separate position, rotation and scale transforms. Like the Node Transform Matrix, these are applied by pre-multiplying position, then rotation, then scale. Thus the Object-Offset Transform Matrix is:
Object-Offset Transform Matrix = Offset Scale * Offset Rotation * Offset Position

Unlike the Node Transform Matrix, the Object-Offset Transform Matrix is not inherited by children of the node.

Using Node Transform Properties

845

The Object Transform Matrix The Object Transform Matrix is the transform matrix an objects geometry needs to be multiplied by to transform it into world space. This transform matrix includes the parent transform, the Node Transform, and the Object Offset Transform. Thus, the entire transform used to transform the points of any object is:
Object Transform Matrix = Object-Offset Transform Matrix * Node Transform Matrix

This matrix could be used, for example, if you have a mesh object and wanted to get the world space coordinate of one of its vertices. You could do this by taking the vertex coordinate in object space and multiplying it by the Object Transform Matrix. Using the Node Transforms in MAXScript The node transform properties are derived from and modify the values of the transform controllers associated with the node, they are not associated directly with the nodes main transformation matrix. This has a number of consequences: 1. Assigning to a transform property (such as pos or rotation) with animation enabled plants keyframes only in the associated controller. If you modify the nodes transform matrix directly, keyframes are generated for all the transform controllers for that node. Rotation properties and in fact all rotation-related functions in MAXScript reflect the direction convention used in the 3ds max user interface. This convention is the right-hand rule, namely, positive angles rotate counter-clockwise about positive axes. Internally, however, 3ds max stores rotations in node matrices using the left-hand rule. It is important to remember this inversion when working directly with node transform matrices using the transform and objectTransform properties. Youll need to invert rotations (for example, by multiplying axes by [-1,-1,-1] or using the inverse() function on quaternions) when mixing them with 3ds max and MAXScript standard rotations. Certain controllers, such as the path controller with bank or follow enabled, affect the rotation of a node by adjusting the nodes transform matrix directly and this rotation is not reflected in rotation controller values. This means, in this example for instance, that bank and follow rotations are not directly accessible through the rotation property, you need to access them directly in the nodes transformation matrix using something like:
r = $foo.transform.rotationPart

2.

3.

which returns a quaternion. Remember, however, that the 3ds max rotation direction convention is not reflected when directly accessing a transform matrix, so to use this value in other rotation operations you would need to invert it:
$baz.rotation = inverse r

A nodes transform property contains the Node Transform Matrix, and reflects the position, rotation, and scale of the nodes pivot point. Accessing the pivot property will return the same value as the pos property. Setting the pivot property will move the pivot point location to the specified coordinates, however the nodes geometry will not be moved.

846

Chapter 11

3ds max Objects

A nodes objectoffsetpos, objectoffsetrot, and objectoffsetscale properties contain the component parts of the Object-Offset Transform Matrix. A nodes objecttransform property contains the Object Transform Matrix. Since this matrix is a combination of the Node Transform and Object-Offset Transform Matrices, this property is read only. Note that these properties are always returned in the World coordinate system context. The following script shows the initial node transform properties for a 25x25x25 box created at [75,75,0], after moving the pivot point to [50,50,0], and after rotating only the pivot point 35 degrees about the Z axis. Also shown is the position of one of the boxs vertices after each transform. Script:
fn DumpXForms obj = ( -- output node transform properties format %:\t%\n transform obj.transform format %:\t%\n position obj.pos format %:\t%\n rotation obj.rotation -- output nodes pivot point location format %:\t%\n pivot obj.pivot -- output object offsets format %:\t%\n objectoffsetpos obj.objectoffsetpos format %:\t%\n objectoffsetrot obj.objectoffsetrot format %:\t%\n objectoffsetscale obj.objectoffsetscale -- output object transform format %:\t%\n objecttransform obj.objecttransform -- output vertex position in local and world coordinates format %:\t%\n vert 1 (local) (in coordsys local getvert obj 1) format %:\t%\n vert 1 (world1) (in coordsys world getvert obj 1) -- calculate and output vertex position in world coordinates local v_pos=(in coordsys local getvert obj 1)* obj.objecttransform format %:\t%\n vert 1 (world2) v_pos ) --- define function for rotating only the pivot point fn RotatePivotOnly obj rotation= ( local rotValInv=inverse (rotation as quat) animate off in coordsys local obj.rotation*=RotValInv obj.objectoffsetrot*=RotValInv obj.objectoffsetpos*=RotValInv ) -( b=box pos:[75,75,0] -- create a 25x25x25 box, vertex 1 at [62.5,62.5,0] (world) convertToMesh b -- convert box to mesh so we can access the vertex location DumpXForms b -- print transforms b.pivot=[50,50,0] -- move pivot only to [50,50,0] DumpXForms b -- print transforms RotatePivotOnly b (EulerAngles 0 0 35) -- rotate pivot only 35 degrees about local Z DumpXForms b -- print transforms )

Using Node Transform Properties

847

Output:
DumpXForms() -- function definition RotatePivotOnly()-- function definition transform: (matrix3 [1,0,0], [0,1,0], [0,0,1], [75,75,0]) -- initial transforms position : [75,75,0] rotation : (quat 0 0 0 1) pivot : [75,75,0] objectoffsetpos : [0,0,0] objectoffsetrot : (quat 0 0 0 1) objectoffsetscale: [1,1,1] objecttransform : (matrix3 [1,0,0], [0,1,0], [0,0,1], [75,75,0]) vert 1 (local) : [-12.5,-12.5,0] vert 1 (world1) : [62.5,62.5,0] vert 1 (world2) : [62.5,62.5,0] transform: (matrix3 [1,0,0], [0,1,0], [0,0,1], [50,50,0]) -- transforms after move position : [50,50,0] rotation : (quat 0 0 0 1) pivot : [50,50,0] objectoffsetpos : [25,25,0] objectoffsetrot : (quat 0 0 0 1) objectoffsetscale: [1,1,1] objecttransform : (matrix3 [1,0,0], [0,1,0], [0,0,1], [75,75,0]) vert 1 (local) : [-12.5,-12.5,0] vert 1 (world1) : [62.5,62.5,0] vert 1 (world2) : [62.5,62.5,0] transform: (matrix3 [0.819152,0.573576,0], [-0.573576,0.819152,0], [0,0,1], [50,50,0]) -- transforms after rotate position : [50,50,0] rotation : (quat 0 0 0.300706 0.953717) pivot : [50,50,0] objectoffsetpos : [34.8182,6.13939,0] objectoffsetrot : (quat 0 0 0.300706 0.953717) objectoffsetscale: [1,1,1] objecttransform : (matrix3 [1,0,0], [0,1,0], [0,0,1], [75,75,0]) vert 1 (local) : [-12.5,-12.5,0] vert 1 (world1) : [62.5,62.5,0] vert 1 (world2) : [62.5,62.5,0]

848

Chapter 11

3ds max Objects

Node User-Defined Properties and Methods

The functions described in this topic give you access to scene object user properties, accessible in the 3ds max user interface in the User Defined tab in the Object Properties Dialog. There are two ways to access and set the user defined properties in the Object Properties dialog -- either as one single string representing the entire contents or as key/property pairs in the form:
<key1> = <property1> <key2> = <property2> ...

where the keys are identifiers (Name or String values) and the properties can be numbers, booleans (true/false) or text strings. There are two MAXScript methods for setting and getting individual keyed properties, and two methods that let you treat the property text as a single big string. Caution: There is currently a bug in the get/set property functions in the 3ds max SDK for text string properties that truncates retrieved string properties at the first space character in the string value. The <node> methods are:
getUserProp <node> <key_string>

retrieves the nodes user property with the given key as a string. <key_string> is either a String or a Name value. If the key does not exist, a value of undefined is returned.
setUserProp <node> <key_string> <value>

sets the nodes user property with the given key to the given value
getUserPropBuffer <node>

retrieves the entire user property buffer as a string containing all the user property settings. This is effectively the contents of the User Defined Properties box in the 3ds max Object Properties dialog
setUserPropBuffer <node> <string>

sets the user property buffer to the given string The following two example code fragments save and load user properties for objects in a scene. The first code fragment creates a file and loops through all objects outputting for each the object name and user property buffer string. Note that the object name goes out in a form that will come back in (via a readValue()) as a direct reference to a scene object. Also, the user property string is output using print() so it will be in a quoted form to be read as one (long) string literal by a corresponding readValue(). The second code fragment reads in the file created by the first piece and applies the user properties to any same-named object in the current scene. Note that readValue() can read in pathnames ($<name>) and will yield either the named scene object or undefined if the named object is not in the scene. The readValue() function can also read in a multiline string literal in one pass.

Node User-Defined Properties and Methods

849

-- create file and for all objects, -- dump object name and user props f = createFile foo.dat for o in objects do ( format $%\n o.name to:f -- output name in a pathname form print (getUserPropBuffer o) to:f -- output buffer as a string literal ) close f -- open file and read in object names and -- user properties to set f = openFile foo.dat while not eof f do ( o = readValue f -- read object if o != undefined then -- if present, read and set user prop string setUserPropBuffer o (readValue f) ) close f

Node Subclasses
In the following node subclasses, the properties listed can all be specified as optional constructor keyword arguments with defaults as shown, along with the common keyword arguments for all node constructors, listed in the Node : MAXWrapper (p. 820) topic. The property listings show name, type and Constructor default value. The following list displays the 3ds max node subclasses: GeometryClass (p. 850) Shape (p. 944) Light (p. 966) Camera (p. 974) Helper (p. 977) SpacewarpObject (p. 992)

850

Chapter 11

3ds max Objects

GeometryClass : Node
The following list shows the 3ds max geometry class objects: -- Standard Primitives Box (p. 853) Cone (p. 858) Cylinder (p. 859) Geosphere (p. 862) Plane (p. 867) Pyramid (p. 869) Sphere (p. 872) Teapot (p. 875) Torus (p. 875) Tube (p. 878) -- Extended Primitives Capsule (p. 855) ChamferBox (p. 856) ChamferCyl (p. 857) C_Ext (p. 854) Gengon (p. 861) Hedra (p. 863) L_Ext (p. 865) OilTank (p. 866) Prism (p. 868) RingWave (p. 870) Spindle (p. 873) TargetObject (p. 874) Torus_Knot (p. 877) -- Compound Objects OldBoolean (p. 887) Boolean2 (p. 887) Conform (p. 889) Connect (p. 889) Loft (p. 890) Morph (p. 891)

Node User-Defined Properties and Methods

851

Scatter (p. 891) ShapeMerge (p. 893) Terrain (p. 894) -- Particle Systems Blizzard (p. 906) PArray (p. 913) PCloud (p. 923) Snow (p. 931) Spray (p. 933) SuperSpray (p. 935) -- Patch Grids QuadPatch (p. 903) TriPatch (p. 904) -- NURBS Surfaces NURBSSurf (p. 943) Point_Surf (p. 943) -- Dynamics Objects Damper (p. 880) Spring (p. 883) -- Doors BiFold (p. 897) Pivot (p. 899) SlidingDoor (p. 901) -- Windows Awning (p. 897) Casement (p. 898) Fixed (p. 899) Pivoted (p. 900) Projected (p. 901) SlidingWindow (p. 902) -- AEC Extended Objects Terrain (p. 894)

852

Chapter 11

3ds max Objects

GeometryClass Common Properties, Operators, and Methods

The mesh operations underlying the Boolean Compound Object in 3ds max are accessible in MAXScript. They appear as operators (+, -, *) that you can apply to any two scene objects that are convertible to meshes. These objects are all GeometryClass objects with the exception of the particle systems. The operators are:
<node1> + <node2> -- the union of node1 and node2 <node1> - <node2> -- the subtraction of node2 from node1 <node1> * <node2> -- the intersection of node1 and node2

Example:
$foo - $baz $sphere01 + $sphere02 + $sphere03 + $sphere04

The Boolean operators change the first operand to be the result of the operation and leave the second operand untouched. So, in the first example, the $foo node is changed to an Editable Mesh object containing the result of the difference operation. In the second example, $sphere01 is successively unioned with each of the other spheres - $sphere01 contains the compound result and the other spheres are left standing. Note that unlike the Boolean compound object in 3ds max, this operation destructively modifies the first operand - you cannot retrieve the original first operand after the Boolean operation is performed. You can effectively keep the first operand by using a copy function, for example,
result = (copy $foo) - $baz

will put a modified copy of $foo into the variable result, leaving the original $foo unchanged.

Geometry - Standard and Extended Objects

The following list displays the standard and extended objects: Box (p. 853) Capsule (p. 855) ChamferBox (p. 856) ChamferCyl (p. 857) Cone (p. 858) Cylinder (p. 859) C_Ext (p. 854) Gengon (p. 861) Geosphere (p. 862) Hedra (p. 863) L_Ext (p. 865) OilTank (p. 866)

Box : GeometryClass

853

Plane (p. 867) Prism (p. 868) Pyramid (p. 869) RingWave (p. 870) Sphere (p. 872) Spindle (p. 873) TargetObject (p. 874) Teapot (p. 875) Torus (p. 875) Torus_Knot (p. 877) Tube (p. 878)

Box : GeometryClass
Constructor:
box ...

Properties:
<Box>.length <Box>.width <Box>.height <Box>.lengthsegs Length_Segments <Box>.widthsegs <Box>.heightsegs Height_Segments <Box>.mapcoords Float Float Float Integer default: 25.0 default: 25.0 default: 25.0 default: 1 -- animatable -- animatable -- animatable -- animatable, alias:

Sets the length of the box object. Sets the width of the box object. Sets the height of the box object.

Sets the number of divisions along the length of the object.

Integer Integer default: 1 default: 1 -- animatable, alias: Width_Segments -- animatable, alias:

Sets the number of divisions along the width of the object.

Sets the number of divisions along the height of the object.

Boolean default: false

When on, generates coordinates for applying mapped materials to the box.

854

Chapter 11

3ds max Objects

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

C_Ext : GeometryClass
Constructor:
c_ext ...

Note: This class is not available in 3D Studio VIZ. Properties:

<C_Ext>.Back_Length <C_Ext>.Side_Length <C_Ext>.Front_Length <C_Ext>.Back_Width <C_Ext>.Side_Width <C_Ext>.Front_Width <C_Ext>.height <C_Ext>.Back_Segments <C_Ext>.Side_Segments <C_Ext>.Front_Segments <C_Ext>.Width_Segments <C_Ext>.Height_Segments Float Float Float Float Float Float Float Integer Integer Integer Integer Integer default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 1 default: 1 default: 1 default: 1 default: 1 -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable

Sets the length of the back edge. Sets the length of the side edge. Sets the length of the front edge. Sets the width of the back edge. Sets the width of the side edge. Sets the width of the front edge. Sets the overall height of the object. The number of segments along the back edge of the object. The number of segments along the side edge of the object. The number of segments along the front edge of the object. The number of segments along the width of the object. The number of segments along the height of the object. Note: The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

Capsule : GeometryClass

855

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

Capsule : GeometryClass
Constructor:
capsule ...

Properties:
<Capsule>.radius <Capsule>.height <Capsule>.heighttype Float Float Integer default: 15.0 default: 25.0 default: 1 -- animatable -- animatable

The radius of the capsule. The height of the capsule. Set what .height specifies: Overall Centers (not including domed caps)
<Capsule>.sides Integer default: 24 -- animatable

Sets the number of sides around the capsule. Higher numbers shade and render as true circles with Smooth on. Lower numbers create regular polygonal objects with Smooth off.
<Capsule>.heightsegs height_segments <Capsule>.smooth <Capsule>.smooth_on Integer default: 1 -- animatable; alias:

The number of divisions along the capsules major axis.

Boolean Integer default: true default: 1 -- animatable -- animatable

When on, blends the faces of the capsule, creating a smooth appearance in rendered views. Smooth_on is an integer alias of smooth: OFF ON
<Capsule>.sliceon <Capsule>.slice_on Boolean Integer default: false -- animatable default: 0 -- animatable

Turns on/off the Slice function. Slice_on is an integer alias of sliceon: OFF ON

856

Chapter 11

3ds max Objects

<Capsule>.slicefrom slice_from <Capsule>.sliceto slice_to <Capsule>.mapCoords

Float

default: 0.0

-- animatable, angle; alias:

Sets the starting angle (on the local Z-axis) for slicing.
Float default: 0.0 -- animatable, angle; alias:

Sets the angle (on the local Z-axis) to slice to.

Boolean default: false

When on, sets up the required coordinates for applying mapped materials to the capsule.

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

ChamferBox : GeometryClass
Constructor:
chamferBox ...

Properties:
<ChamferBox>.length Float Float Float Float default: 0.1 default: 0.1 default: 0.1 default: 0.01 -- animatable -- animatable -- animatable -- animatable

The length of the object.

<ChamferBox>.width

The width of the object.

<ChamferBox>.height

The height of the object.

<ChamferBox>.Fillet

Slices off the edges of the chamferbox. The higher the number, the more filleted the chamferbox becomes.
<ChamferBox>.Length_Segments <ChamferBox>.Width_Segments <ChamferBox>.Height_Segments <ChamferBox>.Fillet_Segments Integer Integer Integer Integer default: 1 default: 1 default: 1 default: 3 -- animatable -- animatable -- animatable -- animatable

The number of divisions along the length of the object. The number of divisions along the width of the object. The number of divisions along the height of the object. The number of segments in the filleted edges of the box. Adding fillet segments increases the edge roundness.

ChamferCyl : GeometryClass

857

Note: The Generate Mapping Coordinates and Smooth properties are not accessible to MAXScript in 3ds max 4.

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

ChamferCyl : GeometryClass
Constructor:
chamferCyl ...

Properties:
<ChamferCyl>.radius <ChamferCyl>.height Float Float default: 0.0 default: 0.0 -- animatable -- animatable

The radius of the chamfered cylinder. The dimension along the central axis. Negative values create the chamfered cylinder below the construction plane.
<ChamferCyl>.Fillet Float default: 0.0 -- animatable

Slices off the edges of the chamfered cylinder. The higher the number, the more filleted the cylinder becomes.
<ChamferCyl>.Height_Segments <ChamferCyl>.Fillet_Segments Integer Integer default: 1 default: 1 -- animatable -- animatable

The number of divisions along the corresponding axis. The number of segments in the filleted edges of the box. Adding fillet segments curves the edges, producing a chamfered cylinder.
<ChamferCyl>.sides Integer default: 12 -- animatable

The number of sides around the chamfered cylinder. Higher numbers shade and render as true circles with Smooth on. Lower numbers create regular polygonal objects with Smooth off.
<ChamferCyl>.Cap_Segments Integer default: 1 -- animatable

The number of concentric divisions along the center of the chamfered cylinders top and bottom
<ChamferCyl>.Smooth Boolean default: true -- animatable

When on, blends the faces of the chamfered cylinder, creating a smooth appearance in rendered views.

858

Chapter 11

3ds max Objects

<ChamferCyl>.Smooth_On

Integer

default: 1

-- animatable

Integer alias for .smooth: OFF ON

<ChamferCyl>.SliceOn Boolean default: false Integer -- animatable -- animatable

Turn on/off the slice function.

<ChamferCyl>.Slice_On default: 0

Integer alias for .slice_on: OFF ON

<ChamferCyl>.Slice_From <ChamferCyl>.Slice_To Float Float default: 0.0 default: 0.0 -- animatable, angle -- animatable, angle

Sets the starting angle (on the local Z-axis) for slicing. Sets the angle (on the local Z-axis) to slice to. Note: The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

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

Cone : GeometryClass
Constructor:
cone ...

Properties:
<Cone>.radius1 <Cone>.radius2 <Cone>.height Float Float Float default: 15.0 default: 0.0 default: 25.0 -- animatable, alias: Radius_1 -- animatable, alias: Radius_2 -- animatable

The first radius of the cone. The second radius of the cone. Height along the central axis. Negative values create the cone below the construction plane.
<Cone>.heightsegs Height_Segments Integer default: 5 -- animatable, alias:

The number of divisions along the cones major axis.

Cylinder : GeometryClass

859

<Cone>.capsegs <Cone>.sides

Integer Integer

default: 1 default: 24

-- animatable, alias: Cap_Segments -- animatable

The number of concentric divisions around the center of the cones top and bottom. The number of sides around the cone. Higher numbers shade and render as true circles with Smooth selected. Lower numbers create regular polygonal objects with Smooth off.
<Cone>.smooth <Cone>.slice <Cone>.Slice_On Boolean Boolean Integer default: true default: false default: 0 -- animatable -- animatable, alias: sliceon

When on, blends the faces of the cone, creating a smooth appearance in rendered views. Turns on/off slice function. Integer alias for .slice: OFF ON
<Cone>.sliceFrom Slice_From <Cone>.sliceTo <Cone>.mapCoords Float default: 0.0 -- animatable, angle, alias:

Sets the starting angle (on the local Z-axis) for slicing.
Float Boolean default: 0.0 default: false -- animatable, angle, alias: Slice_To

Sets the angle (on the local Z-axis) to slice to. When on, sets up required coordinates for applying mapped materials to the cone.

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

Cylinder : GeometryClass
Constructor:
cylinder ...

Properties:
<Cylinder>.radius <Cylinder>.height Float Float default: 15.0 default: 25.0 -- animatable -- animatable

The radius of the cylinder. Height along the central axis. Negative values create the cylinder below the construction plane.
<Cylinder>.heightsegs Height_Segments Integer default: 1 -- animatable, alias:

The number of divisions along the cylinders major axis.

860

Chapter 11

3ds max Objects

<Cylinder>.capsegs Cap_Segments <Cylinder>.sides

Integer

default: 1

-- animatable, alias:

The number of concentric divisions around the center of the cylinders top and bottom.
Integer default: 24 -- animatable

The number of sides around the cylinder. With Smooth on, higher numbers shade and render as true circles. With Smooth off, lower numbers create regular polygonal objects.
<Cylinder>.smooth Boolean default: true -- animatable

When on, the faces of the cylinder are blended together, creating a smooth appearance in rendered views.
<Cylinder>.slice <Cylinder>.Slice_On Boolean Integer default: false default: 0 -- animatable, alias: sliceon

Turns on/off slice function. Integer alias for .slice: OFF ON

<Cylinder>.sliceFrom Slice_From <Cylinder>.sliceTo Slice_To <Cylinder>.mapCoords Float default: 0.0 -- animatable, angle, alias:

Sets the starting angle (on the local Z-axis) for slicing.
Float default: 0.0 -- animatable, angle, alias:

Sets the angle (on the local Z-axis) to slice to.

Boolean default: false

When on, sets up the required coordinates for applying mapped materials to the cylinder.

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

Gengon : GeometryClass

861

Gengon : GeometryClass
Generic polygon. Constructor:
gengon ...

Properties:
<Gengon>.sides Integer default: 5 -- animatable

The number of sides around the gengon. Higher numbers shade and render as true circles with Smooth on. Lower numbers create regular polygonal objects with Smooth off.
<Gengon>.radius Float Float Float default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable

The radius of the gengon.

<Gengon>.Fillet <Gengon>.height

The width of the fillet area. Height along the central axis. Negative values create the gengon below the construction plane.
<Gengon>.Side_Segments <Gengon>.Height_Segments <Gengon>.Fillet_Segments Integer Integer Integer default: 1 default: 1 default: 1 -- animatable -- animatable -- animatable

The number of divisions around the gengon. The number of divisions along the gengons major axis. The number of divisions for the edge filleting. The higher this setting, the rounder the fillet appears. Note: The Generate Mapping Coordinates and Smooth properties are not accessible to MAXScript in 3ds max R4.

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

862

Chapter 11

3ds max Objects

Geosphere : GeometryClass
Constructor:
geosphere ...

Properties:
<GeoSphere>.creationMethod Integer default: 1 -- alias: Creation_Method

Sets the creation method: Diameter (Draws a geosphere from edge to edge.) Center (Draws a geosphere from the center out.)
<GeoSphere>.typeInPos <GeoSphere>.typeInRadius <GeoSphere>.radius <GeoSphere>.segs segments Point3 Float Float Integer default: [0,0,0] default: 25.0 default: 25.0 default: 4 -- animatable -- animatable, alias:

The point3 position of the geosphere. The radius of the geosphere. The radius of the geosphere.

The total number of faces in the geosphere. The number of faces in a geosphere is equal to the sides of the base polyhedron times the segments squared. Lower segment values work best. Using the maximum segment value of 200 can generate up to 800,000 faces, impairing performance.
<GeoSphere>.baseType Integer default: 2 -- alias: Base_Type

Sets the type of basic geometry for the geosphere: Tetra (Based on a four-sided tetrahedron. The triangular facets can vary in shape and size. The sphere can be divided into four equal segments.) Octa (Based on an eight-sided octahedron. The triangular facets can vary in shape and size. The sphere can be divided into eight equal segments.) Icosa (Based on a 20-sided icosahedron. The facets are all equally sized equilateral triangles. The sphere can be divided into any number of equal segments, based on multiples and divisions of 20 faces.)
<GeoSphere>.smooth <GeoSphere>.hemisphere <GeoSphere>.baseToPivot Boolean Boolean Boolean default: true default: false default: false -- animatable -- animatable -- alias: Base_to_Pivot

When on, applies smoothing groups to the surface of the sphere. When on, creates a half-sphere. Sets the pivot point location. When on, the pivot is at the bottom of the sphere. When off, the pivot is at the center of the sphere. This option has no effect when Hemisphere is on.
<GeoSphere>.mapCoords Generate_mapping_coords Boolean default: false -- alias:

When on, applies default mapping coordinates to the geosphere.

Hedra : GeometryClass

863

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

Hedra : GeometryClass
Constructor:
hedra ...

Properties:
<Hedra>.family Integer default: 0

Sets the type of polyhedron to create: Tetra (Creates a tetrahedron) Cube/Octa (Creates a cubic or octahedral polyhedron, depending on parameter settings.) Dodec/Icos (Creates a dodecahedron or icosahedron, depending on parameter settings.) Star1 (Creates a star-like polyhedra.) Star2 (Creates a different star-like polyhedra.)
<Hedra>.p <Hedra>.q Float Float default: 0.0 default: 0.0 -- animatable, alias: Q_Value -- animatable, alias: P_Value

Interrelated parameters that provide a two-way translation between the vertices and facets of a polyhedron. They share the following: Range of possible values is 0.0 through 1.0. The combined total of the P and Q values can be equal to or less than 1.0. Extremes occur if either P or Q is set to 1.0; the other is automatically set to 0.0. Midpoint occurs when both P and Q are 0. In the simplest terms, P and Q change the geometry back and forth between vertices and facets. At the extreme settings for P and Q, one parameter represents all vertices, the other represents all facets. Intermediate settings are transition points, with the midpoint an even balance between the two parameters.
<Hedra>.scalep <Hedra>.scaleq <Hedra>.scaler <Hedra>.P_Scale Float Float Float Float default: 1.0 default: 1.0 default: 1.0 default: 100.0 -- animatable -- animatable -- animatable

Controls the axis of reflection for the p facet of a polyhedron. Controls the axis of reflection for the q facet of a polyhedron. Controls the axis of reflection for the r facets of a polyhedron. Controls the axis of reflection for the p facet of a polyhedron.

864

Chapter 11

3ds max Objects

<Hedra>.Q_Scale <Hedra>.R_Scale <Hedra>.vertices

Float Float Integer

default: 100.0 default: 100.0 default: 0 -- alias: vertType

Controls the axis of reflection for the q facet of a polyhedron. Controls the axis of reflection for the r facets of a polyhedron. Sets the internal geometry of each facet of the polyhedron: Basic (Facets are not subdivided beyond the minimum.) Center (Each facet is subdivided by placing an additional vertex at its center, with edges from each center point to the facet corners.) Center & Sides (Each facet is subdivided by placing an additional vertex at its center, with edges from each center point to the facet corners, as well as to the center of each edge. Compared to Center, Center & Sides doubles the number of faces in the polyhedron.)
<Hedra>.radius <Hedra>.mapCoords Float Boolean default: 25.0 default: false -- animatable

The radius of any polyhedron in current units. When on, sets up required coordinates for applying mapped materials to the hedra. Note: The (scalep, scaleq, scaler) and (P_Scale, Q_Scale, R_Scale) sets of scale parameters are aliases of each other, except that the first set is stored as fractions, and the second set is stored as percentages. This second set of parameters are those shown in the command panels and in Track View. In order to access the vertices property for hedra, you need to access the property via the baseobject property of the node. This is because vertices is also a property name for all nodes, and conflicts with the hedras vertices property. For example:
MyHedra.baseobject.vertices=1 -- set Vertices option to Center

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

L_Ext : GeometryClass

865

L_Ext : GeometryClass
Constructor:
l_ext ...

Note: This class is not available in 3D Studio VIZ. Properties:

<L_Ext>.Side_Length <L_Ext>.Front_Length <L_Ext>.Side_Width <L_Ext>.Front_Width <L_Ext>.height Float Float Float Float Float Integer Integer Integer Integer default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 1 default: 1 default: 1 default: 1 -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable

The length of the side edge. The length of the front edge. The width of the side edge. The width of the front edge. The height of the object.
<L_Ext>.Side_Segments <L_Ext>.Front_Segments <L_Ext>.Width_Segments <L_Ext>.Height_Segments

Number of segments along the side edge. Number of segments along the front edge. Number of segments along the width of the object. Number of segments along the height of the object. Note: The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

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

866

Chapter 11

3ds max Objects

OilTank : GeometryClass
Constructor:
oilTank ...

Properties:
<OilTank>.radius Float Float default: 0.0 default: 0.0 -- animatable -- animatable

The radius of the oiltank.

<OilTank>.height

The height along the central axis. Negative values create the oiltank below the construction plane.
<OilTank>.Cap_Height Float default: 0.0 -- animatable

Sets the height of the convex caps. The minimum value is 2.5% of the Radius setting. The maximum value is the Radius setting, unless the absolute value of the Height setting is less than the double Radius setting, in which case cap height cannot exceed half of the absolute value of the Height setting.
<OilTank>.blend <OilTank>.sides Float Integer default: 0.0 default: 12 -- animatable -- animatable

When greater than 0, creates a bevel at the edge of the caps. Sets the number of sides around the oiltank. To create a smoothly rounded object, use a higher number of sides and turn Smooth on. To create an oiltank with flat sides, use a lower number of sides and turn Smooth off.
<OilTank>.Height_Segments <OilTank>.Smooth_On Integer Integer default: 1 default: 1 -- animatable -- animatable

Sets the number of divisions along the oiltanks major axis. Turn on/off smooth: OFF ON
<OilTank>.Slice_On Integer default: 0 -- animatable

Turn on/off slice: OFF ON

<OilTank>.Slice_From <OilTank>.Slice_To Float Float default: 0.0 default: 0.0 -- animatable, angle -- animatable, angle

Sets the starting angle (on the local Z-axis) for slicing. Sets the angle (on the local Z-axis) to slice to. Note: The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

Plane : GeometryClass

867

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

Plane : GeometryClass
Constructor:
plane ...

Properties:
<Plane>.typeinCreationMethod Integer default: 0 -- alias: Creation_Method

Set the creation method: Rectangle (Creates the plane primitive from one corner to the diagonally opposite corner, interactively setting different values for length and width.) Square (Creates a square plane where length and width are equal.)
<Plane>.typeinPos <Plane>.typeinLength Point3 Float Float Float Float Integer default: [0,0,0] default: 25.0 default: 25.0 default: 25.0 default: 25.0 default: 4 -- animatable -- animatable -- animatable, alias:

Position of the plane in the World Space Coordinate system. Length of the plane object.
<Plane>.typeinWidth

Width of the plane object.

<Plane>.length

Length of the plane object.

<Plane>.width

Width of the plane object.

<Plane>.lsegs Length_Segments <Plane>.wsegs Width_Segments <Plane>.density

Number of divisions along the length of the plane object.

Integer default: 4 -- animatable, alias:

Number of divisions along the width of the plane object.

Float default: 1.0 -- animatable

Specifies the factor by which the number of segments in both length and width are multiplied at render time.
<Plane>.renderScale Render_Scale Float default: 1.0 -- animatable, alias:

Specifies the factor by which both length and width are multiplied at render time. Scaling is performed from the center outward.

868

Chapter 11

3ds max Objects

<Plane>.mapCoords

Boolean

default: false -- alias: Mapping

When on, generates coordinates for applying mapped materials to the box. Note: The renderScale property is a multiplier applied to the Planes length and width property values at render time. The density property is a multiplier applied to the Planes lsegs and wsegs property values at render time.

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

Prism : GeometryClass
Constructor:
prism ...

Properties:
<Prism>.side1Length <Prism>.side2Length <Prism>.side3Length <Prism>.height <Prism>.side1Segs <Prism>.side2Segs <Prism>.side3Segs <Prism>.heightsegs <Prism>.mapCoords Float Float Float Float Integer Integer Integer Integer Boolean default: 25.0 default: 25.0 default: 25.0 default: 10.0 default: 1 default: 1 default: 1 default: 1 default: false -- animatable, alias: Side_1_Length -- animatable, alias: Side_2_Length -- animatable, alias: Side_3_Length -- animatable -- animatable, alias: Side_1_Segments -- animatable, alias: Side_2_Segments -- animatable, alias: Side_3_Segments -- animatable, alias: Height_Segments

Sets the length of triangles first side. Sets the length of triangles second side. Sets the length of triangles third side. The height of the prisms central axis. The number of divisions along the first side. The number of divisions along the second side. The number of divisions along the third side. The number of divisions along the central axis. When on, sets up the required coordinates for applying mapped materials to the prism.

Pyramid : GeometryClass

869

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

Pyramid : GeometryClass
Constructor:
pyramid ...

Properties:
<Pyramid>.width <Pyramid>.depth <Pyramid>.height <Pyramid>.widthsegs Width_Segments <Pyramid>.depthSegs Depth_Segments <Pyramid>.heightsegs Height_Segments <Pyramid>.mapCoords Float Float Float Integer default: 25.0 default: 25.0 default: 25.0 default: 1 -- animatable -- animatable -- animatable -- animatable, alias:

The width of the pyramid. The depth of the pyramid. The height of the pyramid.

The number of divisions along the width of the pyramid.

Integer default: 1 -- animatable, alias:

The number of divisions along the depth of the pyramid.

Integer default: 1 -- animatable, alias:

The number of divisions along the height of the pyramid.

Boolean default: false

When on, sets up required coordinates for applying mapped materials to the pyramid.

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

870

Chapter 11

3ds max Objects

RingWave : GeometryClass
Constructor:
ringwave ...

Note: This class is not available in 3D Studio VIZ. Properties: Note: Some of the properties can be entered using more than one syntax. They are listed together in the following list. Either syntax can be used, they are connected.
<RingWave>.max diameter radius <RingWave>.Radius Segs radial_Segments <RingWave>.ring width Ring_Width <RingWave>.ring segments sides Float default: 500.0 -animatable; alias:

The outside radius of the ringwave.

Integer default: 1 -animatable; alias:

The segment count between the inner and outer surfaces in the direction of radius.
Float default: 1.0 -animatable; alias:

The mean ring width as measured inward from the outer radius.
Integer default: 200 -animatable; alias:

The number of segments in the circumferential direction for both the inner, outer, and end (cap) surfaces.
<RingWave>.height <RingWave>.Height Segs Height_Segments <RingWave>.Repeat <RingWave>.time on <RingWave>.time growing <RingWave>.display until End_Time <RingWave>.Outer Edge Breakup Outer_Edge_Breakup Integer Integer Float default: 1 default: 0.0 --- animatable

The height of the ringwave along its major axis.

animatable; alias:

The number of segments in the direction of the height.

Integer default: 0 default: 2 -- animatable

Repeat = 0 - Cyclic Growth; 1 - Grow and Stay; 2 - No Growth

-- animatable; alias: Start_Time -- alias: Grow_Time animatable; alias:

The time where the ringwave appears, and begins to grow.

Integer Integer default: 9600

The time after .time on that the ringwave takes to reach full size.
default: 16000 --

The time after which the ringwave disappears.

Boolean default: false -- alias:

Turns on breakup of the outer edge.

<RingWave>.Major Cycles Outer Outer_Edge_Major_Cycles Integer default: 1 -- alias:

The number of major waves around the outer edge.

RingWave : GeometryClass

871

<RingWave>.Major Cycle Flux Outer Outer_Edge_Major_Flux

Float

default: 0.0 -- animatable; alias:

The size of the major waves, expressed as a percentage of the unmodulated width.
<RingWave>.Major Cycle Flux Per Outer Integer alias: Outer_Edge_Major_Crawl_Time <RingWave>.Minor Cycles Outer Outer_Edge_Minor_Cycles <RingWave>.Minor Cycle Flux Outer alias: Outer_Edge_Minor_Flux Integer default: 16000 -animatable;

The time each major wave takes to move around the outer circumference of the RingWave.
default: 1 -- alias:

The number of random-sized smaller waves in each major cycle.

Float default: 0.0 -animatable;

The average size of the smaller waves, expressed as a percentage of the unmodulated width.
<RingWave>.Minor Cycle Flux Per Outer Integer alias: Outer_Edge_Minor_Crawl_Time <RingWave>.Inner Edge Breakup Inner_Edge_Breakup <RingWave>.Major Cycles Inner Inner_Edge_Major_Cycles <RingWave>.Major Cycle Flux Inner alias: Inner_Edge_Major_Flux Boolean default: -16000 -animatable;

The time each minor wave takes to move across its respective major wave.
default: true -- alias:

Turns on the breakup of the inner edge.

Integer default: 11 -- alias:

The number of major waves around the inner edge.

Float default: 25.0 -- animatable;

The size of the major waves, expressed as a percentage of the unmodulated width.
<RingWave>.Major Cycle Flux Per Inner Integer alias: Inner_Edge_Major_Crawl_Time <RingWave>.Minor Cycles Inner Inner_Edge_Minor_Cycles Integer default: 19360 -animatable;

The time each major wave takes to move around the inner circumference of the RingWave.
default: 29 -- alias:

The average size of the smaller waves, expressed as a percentage of the unmodulated width.
<RingWave>.Minor Cycle Flux Inner alias: Inner_Edge_Minor_Flux Float default: 10.0 -animatable;

The average size of the smaller waves, expressed as a percentage of the unmodulated width.
<RingWave>.Minor Cycle Flux Per Inner Integer alias: Inner_Edge_Minor_Crawl_Time <RingWave>.repeats Integer default: 2 default: -4320 -animatable;

The time each minor wave takes to move across its respective major wave.
-radio button number

The number of times the ringwave cycle repeats.

872

Chapter 11

3ds max Objects

<RingWave>.Mapping Coords <RingWave>.Smoothing Boolean

Boolean

default: false

When on, assigns mapping coordinates to the ringwave.

default: false

When on, smooths the surface of the ringwave.

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

Sphere : GeometryClass
Constructor:
sphere ...

Properties:
<Sphere>.radius <Sphere>.segs <Sphere>.smooth <Sphere>.hemisphere Float Integer Boolean Float default: 25.0 default: 16 default: true default: 0.0 -- animatable -- animatable, alias: segments -- animatable -- animatable

The radius of the sphere. The number of polygonal divisions for the sphere. When on, blends the faces of the sphere, creating a smooth appearance in rendered views. Increasing values progressively cut off the sphere, starting at the base, to create a partial sphere. Values range from 0.0 to 1.0. The default is 0.0, producing a full sphere. A setting of 0.5 produces a hemisphere, and 1.0 reduces the sphere to nothing.
<Sphere>.chop Integer default: 0

Sets whether the hemisphere is chopped or squashed: Chop (Reduces the number of vertices and faces in the sphere by chopping them out as the hemisphere is cut off.) Squash (Maintains the number of vertices and faces in the original sphere, squashing the geometry into a smaller and smaller volume toward the top of the sphere. Since the geometry is maintained, you can use different versions of a squashed sphere for morph objects.)
<Sphere>.slice Boolean default: false

When on, uses the From and To angles to create a partial sphere. The effect is similar to lathing a semicircular shape fewer than 360 degrees.
<Sphere>.sliceFrom Slice_From Float default: 0.0 -- animatable, angle, alias:

The start angle (on the local Z-axis) for slicing.

Spindle : GeometryClass

873

<Sphere>.sliceTo Slice_To <Sphere>.recenter

Float

default: 0.0

-- animatable, angle, alias:

The stop angle (on the local Z-axis) for slicing.

Boolean default: false

When on, moves a sphere upward along its local Z axis so the pivot point is at its base. When off, the pivot point is on the construction plane at the center of the sphere.
<Sphere>.mapCoords Boolean default: false

When on, generates coordinates for applying mapped materials to the box.

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

Spindle : GeometryClass
Constructor:
spindle ...

Properties:
<Spindle>.radius Float Float default: 0.0 default: 0.0 -- animatable -- animatable

The radius of the spindle.

<Spindle>.height

The height of the spindle, along the central axis. Negative values create the spindle below the construction plane.
<Spindle>.Cap_Height Float default: 0.0 -- animatable

The height of the conical caps. The minimum value is 0.1; the maximum value is 1/2 the absolute value of the Height setting.
<Spindle>.blend <Spindle>.sides Float Integer default: 0.0 default: 12 -- animatable -- animatable

When greater than 0, creates a bevel at the edge of the caps. The number of sides around the spindle. Higher numbers shade and render as true circles with Smooth on. Lower numbers create regular polygonal objects with Smooth off.
<Spindle>.Cap_Segments <Spindle>.Height_Segments Integer Integer default: 5 default: 1 -- animatable -- animatable

The number of concentric divisions along the center of the spindles top and bottom. The number of divisions along the spindles major axis.

874

Chapter 11

3ds max Objects

<Spindle>.Smooth_On

Integer

default: 1

-- animatable

Turns on/off smooth: OFF ON

<Spindle>.Slice_On Integer default: 0 -- animatable

Turn on/off slice: OFF ON

<Spindle>.Slice_From <Spindle>.Slice_To Float Float default: 0.0 default: 0.0 -- animatable, angle -- animatable, angle

The start angle (on the local Z-axis) for slicing. The stop angle (on the local Z-axis) for slicing. Note: The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.

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

TargetObject : GeometryClass
The generic target for cameras, spotlights, tape measure helpers, etc. In MAXScript, you must explicitly construct a target for those objects that need one. For example:
c = targetCamera pos:[x,y,z] target:(targetObject pos:[xt, yt, zt])

Constructor:
targetObject ...

Properties: There are no additional properties for TargetObject.

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

Teapot : GeometryClass

875

Teapot : GeometryClass
Constructor:
teapot ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Teapot>.radius <Teapot>.segs <Teapot>.smooth <Teapot>.body <Teapot>.handle <Teapot>.spout <Teapot>.lid <Teapot>.mapCoords Float Integer Boolean Boolean Boolean Boolean Boolean Boolean default: 25.0 default: 4 default: true default: true default: true default: true default: true default: false -- animatable -- animatable, alias: segments -- animatable -- animatable -- animatable -- animatable -- animatable

The radius of the teapot. The number of divisions for the teapot or its individual parts. When on, blends faces of the teapot, creating a smooth appearance in rendered views. When on, the body of the teapot is included in the object. When on, the handle of the teapot is included in the object. When on, the spout of the teapot is included in the object. When on, the lid of the teapot is included in the object. When on, sets up required coordinates for applying mapped materials to the teapot.

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

Torus : GeometryClass
Constructor:
torus ..

Properties:
<Torus>.segs Integer default: 24 -- animatable, alias: segments

The number of radial divisions around the torus. By reducing this number, you can create polygonal rings instead of circular ones.

876

Chapter 11

3ds max Objects

<Torus>.radius1

Float

default: 25.0

-- animatable, alias: Radius_1

The distance from the center of the torus to the center of the cross-sectional circle. This is the radius of the torus ring.
<Torus>.radius2 <Torus>.tubeRotation Float Float default: 10.0 default: 0.0 -- animatable, alias: Radius_2 -- animatable, angle

The radius of the cross-sectional circle. The degree of rotation. Vertices are uniformly rotated about the circle running through the center of the torus ring. Positive and negative values for this setting roll the vertices in either direction over the surface of the torus.
<Torus>.tubeTwist Float default: 0.0 -- animatable, angle, alias: Twist

The degree of twist. Cross sections are progressively rotated about the circle running through the center of the torus. Beginning with twist, each successive cross section is rotated until the last one has the number of degrees specified.
<Torus>.sides Integer default: 12 -- animatable

The number of sides on the cross-sectional circle of the torus. By reducing this number, you can create prism-like cross sections instead of circular ones.
<Torus>.smooth Integer default: 0 -- animatable

Select the level of smoothing: None (Turns off smoothing entirely, producing prism-like facets on the torus.) Sides (Smoothes the edges between adjacent segments, producing smooth bands running around the torus.) All (Produces complete smoothing on all surfaces of the torus.) Segments (Smoothes each segment individually, producing ring-like segments along the torus.)
<Torus>.slice <Torus>.sliceFrom Slice_From <Torus>.sliceTo <Torus>.mapCoords Boolean Float default: false -- animatable default: 0.0 -- animatable, angle, alias:

When on, creates a portion of a sliced torus rather than the entire 360 degrees.

The angle where the torus slice begins.

Float Boolean default: 0.0 default: false -- animatable, angle, alias: Slice_To

The angle where the torus slice ends. When on, sets up required coordinates for applying mapped materials to the torus.

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

Torus_Knot: GeometryClass

877

Torus_Knot: GeometryClass
Constructor:
torus_knot ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Torus_Knot>.Base_Curve Integer default: 0

Select the base curve for the Torus Know object: Knot (The torus interweaves itself.) Circle (The base curve is a circle, resulting in a standard torus if parameters are left at their defaults.)
<Torus_Knot>.radius <Torus_Knot>.segments <Torus_Knot>.p <Torus_Knot>.q <Torus_Knot>.Warp_Count <Torus_Knot>.Warp_Height <Torus_Knot>.radius2 <Torus_Knot>.sides <Torus_Knot>.Eccentricity Float Integer Float Float Float Float Float Integer Float default: 0.0 default: 120 default: 2.0 default: 3.0 default: 0.0 default: 0.0 default: 10.0 default: 12 default: 1.0 -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable

The radius of the base curve. The number of segments around the perimeter of the torus. Describe up and around-the-center winding numbers. Describe down and around-the-center winding numbers. The number of points in a star shape around the curve. The height of the points given as a percentage of the base curve radius. The radius of the cross section of the torus knot object. The number of sides around the cross section. The ratio of the major to minor axes of the cross section. A value of 1 provides a circular cross section, while other values create elliptical cross sections.
<Torus_Knot>.Twist <Torus_Knot>.Lumps <Torus_Knot>.Lump_Height <Torus_Knot>.Lump_Offset Float Float Float Float default: 0.0 default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable -- animatable, angle

The number of times the cross section twists around the base curve. The number of bulges in the torus knot. The height of the lumps, as a percentage of the radius of the cross section. The offset of the start of the lumps, measured in degrees. The purpose of this value is to animate the lumps around the torus.

878

Chapter 11

3ds max Objects

<Torus_Knot>.smooth

Integer

default: 2

Set smoothing in the torus knot: None (The torus knot is faceted.) Sides (Smoothes only the adjacent sides of the torus knot.) All (The torus knot is faceted.)
<Torus_Knot>.Gen_UV Integer default: 0

Turn on/off generate mapping coordinates OFF ON

<Torus_Knot>.U_Tile <Torus_Knot>.V_Tile <Torus_Knot>.U_Offset <Torus_Knot>.V_Offset Float Float Float Float default: 1.0 default: 1.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable -- animatable

Tile the mapping coordinates along U. Tile the mapping coordinates along V. Offset the mapping coordinates along U. Offset the mapping coordinates along V.

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

Tube : GeometryClass
Constructor:
tube ...

Properties:
<Tube>.radius1 <Tube>.radius2 Float Float default: 25.0 default: 20.0 -- animatable, alias: Radius_1 -- animatable, alias: Radius_2

The first radius for the tube. The second radius for the tube. Note: The larger radius specifies the outside radius of the tube, while the smaller specifies the inside radius.
<Tube>.height Float default: 50.0 -- animatable

The dimension along the central axis. Negative values create the tube below the construction plane.

Tube : GeometryClass

879

<Tube>.heightsegs <Tube>.capsegs <Tube>.sides

Integer Integer Integer

default: 1 default: 1 default: 24

-- animatable, alias: Height_Segments -- animatable, alias: Cap_Segments -- animatable

The number of divisions along the tubes major axis. The number of concentric divisions around the center of the tubes top and bottom. The number of sides around the tube. Higher numbers shade and render as true circles with Smooth on. Lower numbers create regular polygonal objects with Smooth off.
<Tube>.smooth Boolean default: true -- animatable

When on, faces of the tube are blended together, creating a smooth appearance in rendered views.
<Tube>.slice <Tube>.Slice_On Boolean Integer default: false -- animatable default: 0

Enables/Disables the Slice feature, which removes part of the tubes circumference. Integer alias of slice: OFF ON
<Tube>.sliceFrom <Tube>.sliceTo <Tube>.mapCoords Float Float Boolean default: 0.0 default: 0.0 default: false -- animatable, angle, alias: Slice_From -- animatable, angle, alias: Slice_To

The angle where the tube slice begins. The angle where the tube slice ends. When on, sets up required coordinates for applying mapped materials to the tube.

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

Geometry - Dynamics Objects

The following list displays the dynamics objects: Damper (p. 880) Spring (p. 883)

880

Chapter 11

3ds max Objects

Damper : GeometryClass
Constructor:
damper ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Damper>.End_Placement_Method Integer default: 1

Set binding method for damper: Reference Objects (Choose this option when binding the damper to two objects.) Free Spring (Choose this when using the damper as a simple object thats not bound to others or used in a dynamics simulation.)
<Damper>.Free_Damper_Height Float default: 2.0 -- animatable

The distance between the bottom center of the base and the top center of the piston when the damper is not bound.
<Damper>.Renderable_Spring Integer default: 1

Turn on/off renderability of the damper: not renderable renderable

<Damper>.Generate_Mapping_Coordinates Integer default: 0

Turn on/off mapping coordinates for the object: OFF ON

<Damper>.Base_Stud_Diameter <Damper>.Base_Stud_Height Float Float Float Float Integer Float Integer default: 0.5 default: 0.2 default: 1.0 default: 1.0 default: 8 default: 0.0 default: 0 -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable

The diameter of the base, or mount of the damper. The height of the base.
<Damper>.Cylinder_Diameter <Damper>.Cylinder_Height

The diameter of the main housing of the damper. The height of the main housing.
<Damper>.Cylinder_Sides <Damper>.Cylinder_Fillet_1 <Damper>.Cylinder_Fillet_1_Segments

The number of sides of both the base and the main housing. The size of the fillet on the lower edge of the main housing. The number of segments for Fillet 1. The higher this setting, the rounder the fillet profile appears.
<Damper>.Cylinder_Fillet_2 Float default: 0.0 -- animatable

The size of the fillet on the upper edge of the main housing.

Damper : GeometryClass

881

<Damper>.Cylinder_Fillet_2_Segments

Integer

default: 0

-- animatable

The number of segments for Fillet 2. The higher this setting, the rounder the fillet profile appears.
<Damper>.Inside_Diameter <Damper>.Smooth_Cylinder Float Integer default: 0.0 default: 1 -- animatable

The inside diameter of the main housing, which is actually a tube rather than a cylinder. Turn on/off smoothing for the base and the main housing: OFF ON
<Damper>.Piston_Diameter Float Float Integer Integer default: 0.2 default: 1.0 default: 6 default: 1 -- animatable -- animatable -- animatable

The diameter of the piston.

<Damper>.Piston_Height

The height of the piston.

<Damper>.Piston_Sides

The number of sides in the piston.

<Damper>.Smooth_Piston

Turn on/off smoothing for the piston: OFF ON

<Damper>.Enable_Boot Integer default: 0

Turn this on to add the boot to the damper: OFF ON The boot is an optional component of the damper thats similar to the rubber accordion boot found on various types of dampers, such as shock absorbers. The boot acts like a bound dynamic object, in that one of its ends is bound to the main housing, while the other is bound to the piston. Thus, as the piston moves within the housing, the boot expands and contracts to follow.
<Damper>.Boot_Small_Diameter Float default: 0.25 -- animatable

The minimum diameter of the boot. This and the next parameter affect the depth of the accordion folds in the boot.
<Damper>.Boot_Large_Diameter Float Integer Integer Integer default: 1.0 default: 8 default: 4 default: 4 -- animatable -- animatable -- animatable -- animatable

The maximum diameter of the boot.

<Damper>.Boot_Sides <Damper>.Boot_Folds <Damper>.Boot_Fold_Resolution

The number of sides making up the boot. The number of accordion folds (bulges) along the height of the boot. The number of segments in each fold.

882

Chapter 11

3ds max Objects

<Damper>.Boot_Stop_Diameter <Damper>.Boot_Stop_Height <Damper>.Boot_Stop_Setback <Damper>.Boot_Stop_Fillet <Damper>.Boot_Stop_Fillet_Segements

Float Float Float Float Integer

default: 0.4 default: 0.2 default: 0.2 default: 0.0 default: 0

-- animatable -- animatable -- animatable -- animatable -- animatable

The diameter of the stop, which is the ring at the top of the boot. The thickness (height) of the stop ring. The distance of the stop ring from the top of the piston. The size of the fillet on the upper edge of the stop ring. The number of segments the stop fillet. The higher this setting, the round the fillet profile appears.
<Damper>.Smooth_Boot Integer default: 1

Turn on/off smoothing for the boot: OFF ON

<Damper>.Dynamics_Object_Type Integer default: 0

Select which object is dynamic: Damper (Select this option to use the damper object as a damper rather than an actuator.) Actuator (Choose this when using the damper object as an Actuator.)
<Damper>.Drag Float Integer default: 0.0 default: 0 -- animatable

The force per unit linear speed.

<Damper>.Drag_Units

Sets the units of drag: Pounds per inch/second Newtons per meter/second
<Damper>.Damper_Direction Integer default: 2

Set the directional operation of the damper: Compression Only (The damper reacts only to compression forces.) Extension Only (The damper reacts only to expansion forces.) Both (The damper reacts to both compression and expansion forces.)
<Damper>.Force Float default: 0.0 -- animatable

The amount of force exerted between the two bound objects. Positive values push the objects apart, while negative values pull them together.
<Damper>.Force_Units Integer default: 0

Set the units of force: Pounds Newtons

Spring : GeometryClass

883

Note: The Reference End Point objects cannot be specified in MAXScript in 3ds max R4.

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

Spring : GeometryClass
Constructor:
spring ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Spring>.End_Placement_Method Integer default: 1

Set the end placement method: Reference Objects (Choose this when binding the spring to two objects.) Free Spring (Choose this when using the spring as a simple object thats not bound to other objects or used in a dynamics simulation.)
<Spring>.Free_Spring_Height Float default: 1.0 -- animatable

The straight-line height or length of the spring when it is not bound. This is not the actual length of the springs wire.
<Spring>.Diameter Float default: 1.0 -- animatable

The overall diameter of the spring, as measured at the center of the wire. (The diameter of the wire itself has no effect on this setting.)
<Spring>.Number_of_Turns <Spring>.Turn_Direction Float Integer default: 1.0 default: 0 -- animatable

The number of full 360-degree turns in the spring. Sets the direction of the turns in the spring: counterclockwise clockwise
<Spring>.Segmentation_Method Integer default: 0

Sets the segmentation method of the springs: Automatic Segments (Choose this option to force each turn of the spring to contains the same number of segments. Thus, if you increase the number of turns, the number of segments also increases.)

884

Chapter 11

3ds max Objects

Manual Segments (When this option is chosen, length of the spring contains a fixed number of segments, no matter how many turns in the spring. Thus, as you increase the number of turns, you must manually increase the number of segments to maintain a smooth curve.)
<Spring>.Segments_Per_Turn <Spring>.Segments_Along_Turn <Spring>.Smooth_Spring Integer Integer Integer default: 16 default: 16 default: 0 -- animatable -- animatable

The number of segments in each 360-degree turn of the spring. The total number of manual segments in the spring. Set smoothing method for spring: All (All surfaces are smoothed.) None (No smoothing is applied.) Sides (Smoothing runs along the length of the wire, but not around its perimeter.) Segments (Smoothing runs around the perimeter of the wire, but not along its length.)
<Damper>.Renderable_Spring Integer default: 1

When on, the object appears in the rendering; when off, the object does not appear: Not renderable Renderable
<Spring>.Wire Integer default: 0 -- animatable

Set the shape of the wire: Round Rectangular D-Section

<Spring>.Generate_Mapping_Coordinates Integer default: 0

Turn on/off generate texture coordinates OFF ON

<Spring>.Round_Wire_Diameter Float Integer Float Float Float default: 0.2 default: 6 default: 0.2 default: 0.2 default: 0.0 -- animatable -- animatable -- animatable -- animatable -- animatable

The diameter of the wire.

<Spring>.Round_Wire_Side_Count <Spring>.Rectangular_Wire_Width <Spring>.Rectangular_Wire_Depth <Spring>.Rectangular_Wire_Fillet_Size

The number of sides that make up the cross section of the round wire. Determines the width of the rectangular cross section. Determines the depth of the rectangular cross section. When combined with .Rectangular_Fillet_Sides, this lets you fillet (round) the corners of the cross section.

Spring : GeometryClass

885

<Spring>.Rectangular_Fillet_Sides

Integer Float

default: 0 default: 0.0

-- animatable -- animatable,

The number of segments in the fillet.

<Spring>.Rectangular_Wire_Rotation_Angle angle <Spring>.D_Section_Wire_Width

Rotates the angle of the cross section along the entire length of the spring.
Float Float Integer Float default: 0.2 default: 0.2 default: 4 default: 0.0 -- animatable -- animatable -- animatable -- animatable

Determines the width of the cross section.

<Spring>.D_Section_Wire_Depth

Determines the depth of the cross section.

<Spring>.D_Section_Round_Sides <Spring>.D_Section_Wire_Fillet_Size

The number of segments that make up the rounded side of the D-shape. When combined with .D_Section_Wire_Fillet_Sides, this lets you fillet (round) the corners of the cross section.
<Spring>.D_Section_Wire_Fillet_Sides Integer Float default: 0 default: 0.0 -- animatable -- animatable,

The number of segments in the fillet.

<Spring>.D_Section_Wire_Rotation_Angle angle <Spring>.Dynamics_Spring_Free_Height

Rotates the angle of the cross section along the entire length of the spring.
Float default: 1.0 -- animatable

Specifies the height (or length) at which the spring is relaxed and therefore contributes no force--either compression or extension.
<Spring>.Dynamics_K_Constant_Value Float default: 1.0 -- animatable

The amount of force exerted per unit change in length with respect to the Relaxed Hgt value. This could also be described as the measure of force-per-units-change in length as compared to the Relaxed Length.
<Spring>.Dynamics_K_Constant_Units Integer default: 0

Sets the Units for the K constant: Pounds per inch Newtons per meter
<Spring>.Dynamics_Spring_Direction Integer default: 0

Lets you specify the type of force you want the spring to exert. While most springs actually provide both compression and extension force, if your simulation requires only one, you can save calculation time by using one instead of both. Compression Only (This type of spring provides only expansive force when its length is shorter than the specified Free Length.)

886

Chapter 11

3ds max Objects

Extension Only (Provides contractive force when its length is greater than the specified Free Length.) Both (Provides both expansive and contractive force, depending on the variation from Relaxed Hgt.)
<Spring>.Generate_Texture_Coordinates Integer default: 0

Turn on/off generate texture coordinates: OFF ON Note: The Reference End Point objects cannot be specified in MAXScript in 3ds max R4.

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

Geometry - Compound Objects

The following list displays the compound objects: OldBoolean (p. 887) Boolean2 (p. 887) Conform (p. 889) Connect (p. 889) Loft (p. 890) Morph (p. 891) Scatter (p. 891) ShapeMerge (p. 893) Terrain (p. 894)

OldBoolean : GeometryClass

887

OldBoolean : GeometryClass
Constructor: OldBoolean compound objects are not constructable by MAXScript. Boolean objects created in previous versions of 3ds max use this class when they are loaded, and then the OldBoolean object is automatically converted to the new Boolean2 class. See the Boolean2 (p. 887) topic for a constructable boolean object.

Boolean2 : GeometryClass
Constructor:
boolObj.createBooleanObject <operand_A> [ <operand_B> <add_method> <mat_method> ]

Creates a Boolean2 object using node <operand_A> and an optional node <operand_B>. <add_method> specifies how <operand_B> is to be used as follows:
1 2 3 4 instance, operand is an instance of the original node reference, operand is a reference to original node copy, operand is a copy of original node move, original node should be deleted

<mat_method> specifies how the materials of the two operands are to be handled as follows:
1 2 3 4 5 combines materials without changing them or the IDs matches IDs to materials, then combines materials matches materials to IDs, then combines them discards original material, uses new nodes instead discards new nodes material, uses original

Properties: The following properties are available only after the boolean2 object has been created. The values shown for the properties are those for a boolean2 object created from two spheres. The operand transforms are in the local coordinate system of the boolean2 object.
<bool_obj>.Sphere02 <bool_obj>.Operand_A_Transform <bool_obj>.Sphere01 <bool_obj>.Operand_B_Transform SubAnim SubAnim SubAnim SubAnim default: default: default: default: SubAnim:Sphere02 SubAnim:Operand_A_Transform SubAnim:Sphere01 SubAnim:Operand_B_Transform

Methods:
boolObj.setOperandB <bool_obj> <operand_B> <add_method> <mat_method>

sets operand B. The values for <add_method> and <mat_method> are describe above.
boolObj.getOperandSel <bool_obj> <integer> boolObj.setOperandSel <bool_obj> <integer> <boolean>

these methods get and set whether operand_A and operand_B are selected in the Operands list. <integer> = 1 - operand_A, 2 - operand_B

888

Chapter 11

3ds max Objects

boolObj.getBoolOp <bool_obj> boolObj.setBoolOp <bool_obj> <integer>

these methods get and set the boolean Operation Type. Valid values are:
1 2 3 4 5 Union Intersection Subtraction (A-B) Subtraction (B-A) Cut

boolObj.getBoolCutType <bool_obj> boolObj.setBoolCutType <bool_obj> <integer>

these methods get and set the boolean Cut Type. The value for this property only has an effect if the Operation Type is Cut. The Cut Types are:
1 2 3 4 Refine Split Remove Inside Remove Outside

boolObj.getDisplayResult <bool_obj> boolObj.setDisplayResult <bool_obj> <boolean>

these methods get and set whether Results or Operands are displayed. If true, Result is displayed. If false, Operands are displayed.
boolObj.getShowHiddenOps <bool_obj> boolObj.setShowHiddenOps <bool_obj> <boolean>

these methods get and set whether Results + Hidden Operands are displayed. If true, Results + Hidden Operands are displayed. If false, the Results or Operands as specified using boolObj.SetDisplayResult() are displayed.
boolObj.getUpdateMode <bool_obj> boolObj.setUpdateMode <bool_obj> <integer>

these methods get and set the Update mode as follows:

1 - Always 2 - When Rendering 3 - Manually boolObj.getOptimize <bool_obj> boolObj.setOptimize <bool_obj> <boolean>

these methods get and set whether vertices are to be welded on the boolean result

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

Conform : GeometryClass

889

Conform : GeometryClass
Constructor: Conform compound objects are not constructable by MAXScript in 3ds max 4. Properties:
<Conform>.Projection_Distance Float default: 1.0 -- animatable

The distance a vertex in the Wrapper object will move from its original location if it does not intersect the Wrap-To object.
<Conform>.Standoff_Distance Float default: 1.0 -- animatable

The distance maintained between the vertex of the Wrapper object and the surface of the Wrap-To object The following properties are available only after the conform object has been created. The values shown for the properties are those for a conform object created from two spheres. The operand transforms are in the local coordinate system of the conform object.
<Conform>.S_Sphere02 <Conform>.Operand_A_Transform <Conform>.D_Sphere01 <Conform>.Operand_B_Transform SubAnim SubAnim SubAnim SubAnim default: default: default: default: SubAnim:S_Sphere02 SubAnim:Operand_A_Transform SubAnim:D_Sphere01 SubAnim:Operand_B_Transform

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

Connect : GeometryClass
Constructor: Connect compound objects are not constructable by MAXScript in 3ds max 4. Properties:
<Connect>.segments <Connect>.tension Integer Float default: 0 default: 0.5 -- animatable -- animatable

The number of segments in the connecting bridge. Controls the curvature in the connecting bridge. A value of 0 provides no curvature, while higher values create curves that attempt to more smoothly match the surface normals on either end of the connecting bridge.

890

Chapter 11

3ds max Objects

The following properties are available only after the connect object has been created. The values shown for the properties are those for a connect object created from two spheres. Similar SubAnims would be created if additions operands were used. The operand transforms are in the local coordinate system of the connect object.
<Connect>.Op_0__Sphere02 <Connect>.Op_0_Transform <Connect>.Op_1__Sphere01 <Connect>.Op_1_Transform SubAnim SubAnim SubAnim SubAnim default: default: default: default: SubAnim:Op_0__Sphere02 SubAnim:Op_0_Transform SubAnim:Op_1__Sphere01 SubAnim:Op_1_Transform

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

Loft : GeometryClass
Constructor: Loft compound objects are not constructable by MAXScript in 3ds max 4. Properties:
<Loft>.Def_Scale_X <Loft>.Def_Scale_Y <Loft>.Def_Twist <Loft>.Def_Teeter_X <Loft>.Def_Teeter_Y <Loft>.Def_Bevel <Loft>.Def_Fit_X <Loft>.Def_Fit_Y SubAnim SubAnim SubAnim SubAnim SubAnim SubAnim SubAnim SubAnim default: default: default: default: default: default: default: default: SubAnim:Def_Scale_X SubAnim:Def_Scale_Y SubAnim:Def_Twist SubAnim:Def_Teeter_X SubAnim:Def_Teeter_Y SubAnim:Def_Bevel SubAnim:Def_Fit_X SubAnim:Def_Fit_Y

These SubAnims contain the deformation curves of the loft object. You cannot create or access points in these curves unless the point is animated. In this case, you can access the animated point position as a SubAnim of the property. The following properties are available only after the loft object has been created. The values shown for the properties are those for a loft object created from an ellipse (the path) and a circle (the shape).
<loft>.ellipse <Loft>.circle SubAnim SubAnim default: SubAnim:Ellipse default: SubAnim:Circle

These SubAnims contain the parameters of the path and shape objects, respectively. If multiple shapes are used in a loft, each of these shape objects will have a corresponding SubAnim.

Morph : GeometryClass

891

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

Morph : GeometryClass
Constructor:
createMorphObject <source_node>

Modification of Morph objects, including setting the morph keys and adding morph targets, is performed using methods associated with the Morph controller. See the MorphController (p. 1302) topic for a description of these methods. Properties: The following properties are available only after the morph object has been created. The values shown for the properties are those for a morph object created from three spheres.
<Morph>.M_Sphere01 SubAnim <Morph>.M_Sphere02 SubAnim <Morph>.M_Sphere03 SubAnim <Morph>.Morph Barycentric_Morph_Controller Controller:Barycentric_Morph_Controller default: SubAnim:M_Sphere01 default: SubAnim:M_Sphere02 default: SubAnim:M_Sphere03 default:

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

Scatter : GeometryClass
Constructor: Scatter compounds are not constructable by MAXScript in 3ds max 4. Properties:
<Scatter>.Duplicates <Scatter>.Base_Scale percentage Integer Float default: 1 default: 100.0 -- animatable -- animatable,

The number of scattered duplicates of the source object.

Alters the scale of the source object, affecting each duplicate identically. This scale occurs before any other transforms.

892

Chapter 11

3ds max Objects

<Scatter>.Vertex_Chaos <Scatter>.Animation_Offset

Float Time

default: 0.0 default: 0f

-- animatable -- animatable

Applies a random perturbation to the vertices of the source object. The number of frames by which each source object duplicates animation is offset from the previous duplicate.
<Scatter>.x_rotation <Scatter>.y_rotation <Scatter>.z_rotation <Scatter>.X_Translation <Scatter>.Y_Translation <Scatter>.Z_Translation <Scatter>.A_Translation_on_Face Float Float Float Float Float Float Float default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable

The maximum random rotational offset you want about the local X-axis of each duplicate. The maximum random rotational offset you want about the local Y-axis of each duplicate. The maximum random rotational offset you want about the local Z-axis of each duplicate. The maximum random movement you want along the X-axis of each duplicate. The maximum random movement you want along the Y-axis of each duplicate. The maximum random movement you want along the Z-axis of each duplicate. The first barycentric coordinate on the surface of the face, upon which duplicates are translated.
<Scatter>.B_Translation_on_Face Float default: 0.0 -- animatable

The second barycentric coordinate on the surface of the face, upon which duplicates are translated.
<Scatter>.N_Translation_on_Face <Scatter>.Local_X_Scaling <Scatter>.Local_Y_Scaling <Scatter>.Local_Z_Scaling Float Float Float Float default: 0.0 default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable -- animatable

The offset along the normal of the face, upon which duplicates are translated. The percent of random scaling along the X-axis of each duplicate. The percent of random scaling along the X-axis of each duplicate. The percent of random scaling along the X-axis of each duplicate. The following properties are available only after the Scatter object has been created. The values shown for the properties are those for a Scatter object created from two boxes. The operand transforms are in the local coordinate system of the Scatter object.
<Scatter>.S_Box04 <Scatter>.Operand_A_Transform <Scatter>.D_Box05 <Scatter>.Operand_B_Transform SubAnim SubAnim SubAnim SubAnim default: default: default: default: SubAnim:S_Box04 SubAnim:Operand_A_Transform SubAnim:D_Box05 SubAnim:Operand_B_Transform

Note: Many properties associated with Scatter are not accessible to MAXScript in 3ds max 4.

ShapeMerge : GeometryClass

893

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

ShapeMerge : GeometryClass
Constructor: ShapeMerge compound objects are not constructable by MAXScript in 3ds max 4. Properties:
<ShapeMerge>.Operation_Type Integer default: 1

Set the shapemerge operation type: Cookie Cutter (Cuts the shape out of the mesh objects surface.) Merge (Merges the shape with the surface of the mesh object.)
<ShapeMerge>.Remove_Interior_Exterior Integer default: 0

Reverses the effect of Cookie Cutter or Merge. With the Cookie Cutter option, the effect is obvious. When Invert is off, the shape is a hole in the mesh object. When Invert is on, the shape is solid and the mesh is missing. When youre using Merge, Invert reverses the subobject mesh selection. Invert OFF Invert ON
<ShapeMerge>.Output_Sub_Mesh_Selection Integer default: 0

Sets which selection level is output: None (Outputs the full object.) Vertex (Outputs the vertices defined by the spline of the shape.) Edge (Outputs the edge of the merged shape.) Face (Outputs the faces within the merged shape.) The following properties are available only after the ShapeMerge object has been created. The values shown for the properties are those for a ShapeMerge object created from a sphere and a circle. SubAnims similar to the Circle01 SubAnim would be created if additions operands were used. The operand transforms are in the local coordinate system of the ShapeMerge object.
<ShapeMerge>.mesh__sphere01 <ShapeMerge>.mesh_transform <ShapeMerge>.shape_1__circle01 <ShapeMerge>.shape_1_transform SubAnim SubAnim SubAnim SubAnim default: default: default: default: SubAnim:Mesh__Sphere01 SubAnim:Mesh_Transform SubAnim:Shape_1__Circle01 SubAnim:Shape_1_Transform

894

Chapter 11

3ds max Objects

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

Terrain : GeometryClass
Constructor:
Terrain()

Properties:
<Terrain>.Form Integer default: 1

Set the terrain form: Graded Surface (Creates a graded surface of the mesh over the contours.) Graded Solid (Creates a graded surface with skirts around the sides and a bottom surface. This represents a solid that is visible from every direction.) Layered Solid (Creates a wedding cake or laminated solid similar to cardboard architectural models.)
<Terrain>.stitchBorder Boolean Boolean Integer default: false default: false default: 0

Turn on/off stitch border.

<Terrain>.retriangulate

Turn on/off retriangulate.

<Terrain>.display

Select the type of display for the terrain object: Terrain (Displays only the triangulated mesh over the contour line data.) Contours (Displays only the contour line data of the terrain object.) Both (Displays both the triangulated mesh and the contour line data of the terrain object.)
<Terrain>.update Integer default: 0

Set update settings for the terrain object: Always (Updates the terrain object immediately when you change an operand, including the original object of an instanced or referenced operand.) When Rendering (Updates the terrain object when you render the scene or when you force an update. With this option, viewports wont show current geometry unless you.) Manually (Updates the terrain object when you force an update.)

Terrain : GeometryClass

895

Note: The following properties of terrain compound objects cannot be operated on with MAXScript in 3ds max R4. However, they can be used by MAXScript in 3D Studio VIZ.
<Terrain>.numOps <Terrain>.horizSimplification Integer Integer default: 0 default: 0

The number of contour operands. Read-only. horizSimplification = 0 No Simplification; 1 Use 1/2 of Points; 2 - Use 1/4 of Points; 3 Interpolate Points * 2; 4 - Interpolate Points * 4
<Terrain>.vertSimplification Integer default: 0

vertSimplification = 0 - No Simplification; Use 1/2 of Lines; 2 - Use 1/4 of Lines The following properties are available only after the terrain object has been created. The values shown for the properties are those for a terrain object created from three circles. The operand transforms are in the local coordinate system of the terrain object.
<Terrain>.Op_0__Circle01 <Terrain>.Op_0_Transform <Terrain>.Op_1__Circle02 <Terrain>.Op_1_Transform <Terrain>.Op_2__Circle03 <Terrain>.Op_2_Transform SubAnim SubAnim SubAnim SubAnim SubAnim SubAnim default: default: default: default: default: default: SubAnim:Op_0__Circle01 SubAnim:Op_0_Transform SubAnim:Op_1__Circle02 SubAnim:Op_1_Transform SubAnim:Op_2__Circle03 SubAnim:Op_2_Transform

Note: All properties other than Form are not accessible in 3ds max. Methods: The following methods are available in 3DS VIZ:
terrainOps.addOperand <terrain> <node>

Appends a node as a contour operand to the terrain. Note this is done in Move mode, so the the supplied node is deleted after the addition. To simulate other modes, use appropriate MAXScript functions. For example,
terrainOps.addOperand $terrain01 (instance $line03) terrainOps.deleteOperand <terrain> <index_integer>

Deletes the indexed operand, index_integer is 1-based.

terrainOps.getOperand <terrain> <index_integer>

Returns the indexed contour operand as a 3ds max base object (not a node), index_integer is 1-based.

896

Chapter 11

3ds max Objects

terrainOps.getOperandTM <terrain> <index_integer>

Returns the indexed operands local transformation matrix as a Matrix3 value. This transformation matrix is relative to the terrains node transformation matrix.
terrainOps.setOperandTM <terrain> <index_integer> <matrix3>

Sets the indexed operands local transformation matrix. This transformation matrix is relative to the terrains node transformation matrix.
terrainOps.update <terrain>

Forces a terrain update for those in manual update mode. Note: The above methods are defined in the Landform DLL and so will only be present if the Landform DLL has been loaded. In installations set up with delayed plugin loading enabled, this will happen automatically if there are any existing terrain objects in the scene or a terrain object is created in the user interface or via MAXScript.

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

Geometry - Doors and Windows

The following list displays the door and window objects: Awning (p. 897) BiFold (p. 897) Casement (p. 898) Fixed (p. 899) Pivot (p. 899) Pivoted (p. 900) Projected (p. 901) SlidingDoor (p. 901) SlidingWindow (p. 902)

Awning : GeometryClass

897

Awning : GeometryClass
Constructor:
awning ...

Properties:
<Awning>.height <Awning>.width <Awning>.depth <Awning>.Horizontal_Frame_Width <Awning>.Vertical_Frame_Width <Awning>.Frame_Thickness <Awning>.Glazing_Thickness <Awning>.Rail_Width <Awning>.Number_of_Panels <Awning>.Percent_Open <Awning>.Generate_Mapping_Coords Float Float Float Float Float Float Float Float Integer Integer Boolean default: default: default: default: default: default: default: default: default: default: default: 0.0 0.0 0.0 2.0 2.0 0.5 0.25 1.0 1 0 false --------animatable animatable animatable animatable animatable animatable animatable animatable

-- animatable

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

BiFold : GeometryClass
Constructor:
bifold ...

Properties:
<BiFold>.height <BiFold>.width <BiFold>.depth <BiFold>.Double_Doors Float Float Float Integer Boolean Boolean Float Boolean Float Float Float Boolean Float Float default: default: default: default: default: default: default: default: default: default: default: default: default: default: 0.0 0.0 0.0 0 false false 0.0 true 2.0 1.0 0.0 false 2.0 4.0 -- animatable -- animatable -- animatable

Double_Doors = 0 - false; 1 - true

<BiFold>.Flip_Swing <BiFold>.Flip_Hinge <BiFold>.open <BiFold>.Create_Frame <BiFold>.Frame_Width <BiFold>.Frame_Depth <BiFold>.Door_Offset <BiFold>.Generate_Mapping_Coords <BiFold>.Leaf_Thickness <BiFold>.Stiles_Top_Rail

-- animatable -- animatable -- animatable -- animatable -- animatable -- animatable

898

Chapter 11

3ds max Objects

<BiFold>.Bottom_Rail <BiFold>.Number_of_Panels_Horizontally <BiFold>.Number_of_Panels_Vertically <BiFold>.Muntin <BiFold>.Panel_Type <BiFold>.Glass_Thickness <BiFold>.Bevel_Angle <BiFold>.Panel_Thickness_1 <BiFold>.Panel_Thickness_2 <BiFold>.Panel_Middle_Thickness <BiFold>.Panel_Width_1 <BiFold>.Panel_Width_2

Float Integer Integer Float Integer Float Float Float Float Float Float Float

default: default: default: default: default: default: default: default: default: default: default: default:

12.0 1 1 2.0 1 0.25 45.0 0.25 0.5 0.25 1.0 0.5

-- animatable

-- animatable

Panel_Type = 0 - None; 1 - Glass; 2 - Beveled

-------animatable animatable animatable animatable animatable animatable animatable

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

Casement : GeometryClass
Constructor:
casement ...

Properties:
<Casement>.height <Casement>.width <Casement>.depth <Casement>.Horizontal_Frame_Width <Casement>.Vertical_Frame_Width <Casement>.Frame_Thickness <Casement>.Glazing_Thickness <Casement>.Panel_Width <Casement>.Number_of_Casements <Casement>.Percent_Open <Casement>.Opens_to_Inside <Casement>.Generate_Mapping_Coords Float Float Float Float Float Float Float Float Integer Integer Boolean Boolean default: default: default: default: default: default: default: default: default: 0.0 0.0 0.0 2.0 2.0 0.5 0.25 1.0 1 --------animatable animatable animatable animatable animatable animatable animatable animatable

Number_of_Casements = 1 - One; 2 - Two

default: 0 -- animatable default: false default: false

Fixed : GeometryClass

899

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

Fixed : GeometryClass
Constructor:
fixed ...

Properties:
<Fixed>.height <Fixed>.width <Fixed>.depth <Fixed>.Horizontal_Frame_Width <Fixed>.Vertical_Frame_Width <Fixed>.Frame_Thickness <Fixed>.Glazing_Thickness <Fixed>.Rail_Width <Fixed>.Number_of_Panels_Horizontally <Fixed>.Number_of_Panels_Vertically <Fixed>.Chamfered_Profile <Fixed>.Generate_Mapping_Coords Float Float Float Float Float Float Float Float Integer Integer Boolean Boolean default: default: default: default: default: default: default: default: default: default: default: default: 0.0 0.0 0.0 2.0 2.0 0.5 0.25 1.0 1 1 false false --------animatable animatable animatable animatable animatable animatable animatable animatable

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

Pivot : GeometryClass
Constructor:
pivot ...

Properties:
<pivot>.height <pivot>.width <pivot>.depth <pivot>.Double_Doors Float Float Float Integer default: default: default: default: 0.0 0.0 0.0 0 -- animatable -- animatable -- animatable

Double_Doors = 0 - false; 1 - true

900

Chapter 11

3ds max Objects

<pivot>.Flip_Swing <pivot>.Flip_Hinge <pivot>.Open__degrees <pivot>.Create_Frame <pivot>.Frame_Width <pivot>.Frame_Depth <pivot>.Door_Offset <pivot>.Generate_Mapping_Coords <pivot>.Leaf_Thickness <pivot>.Stiles_Top_Rail <pivot>.Bottom_Rail <pivot>.Number_of_Panels_Horizontally <pivot>.Number_of_Panels_Vertically <pivot>.Muntin <pivot>.Panel_Type <pivot>.Glass_Thickness <pivot>.Bevel_Angle <pivot>.Panel_Thickness_1 <pivot>.Panel_Thickness_2 <pivot>.Panel_Middle_Thickness <pivot>.Panel_Width_1 <pivot>.Panel_Width_2

Boolean Boolean Float Boolean Float Float Float Boolean Float Float Float Integer Integer Float Integer Float Float Float Float Float Float Float

default: default: default: default: default: default: default: default: default: default: default: default: default: default: default: default: default: default: default: default: default: default:

false false 0.0 true 2.0 1.0 0.0 false 2.0 4.0 12.0 1 1 2.0 1 0.25 45.0 0.25 0.5 0.25 1.0 0.5

-- animatable -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable

-- animatable

Panel_Type = 0 - None; 1 - Glass; 2 - Beveled

-------animatable animatable animatable animatable animatable animatable animatable

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

Pivoted : GeometryClass
Constructor:
pivoted ...

Properties:
<Pivoted>.height <Pivoted>.width <Pivoted>.depth <Pivoted>.Horizontal_Frame_Width <Pivoted>.Vertical_Frame_Width <Pivoted>.Frame_Thickness <Pivoted>.Glazing_Thickness <Pivoted>.Rail_Width <Pivoted>.Vertical_Rotation <Pivoted>.Percent_Open <Pivoted>.Generate_Mapping_Coords Float Float Float Float Float Float Float Float Boolean Integer Boolean default: default: default: default: default: default: default: default: default: default: default: 0.0 0.0 0.0 2.0 2.0 0.5 0.25 1.0 false 0 false --------animatable animatable animatable animatable animatable animatable animatable animatable

-- animatable

Projected : GeometryClass

901

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

Projected : GeometryClass
Constructor:
projected ...

Properties:
<projected>.height <projected>.width <projected>.depth <projected>.Horizontal_Frame_Width <projected>.Vertical_Frame_Width <projected>.Frame_Thickness <projected>.Glazing_Thickness <projected>.Rail_Width <projected>.Middle_Height <projected>.Bottom_Height <projected>.Percent_Open <projected>.Generate_Mapping_Coords Float Float Float Float Float Float Float Float Float Float Integer Boolean default: default: default: default: default: default: default: default: default: default: default: default: 0.0 0.0 0.0 2.0 2.0 0.5 0.25 1.0 0.0 0.0 0 false -----------animatable animatable animatable animatable animatable animatable animatable animatable animatable animatable animatable

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

SlidingDoor : GeometryClass
Constructor:
slidingDoor ...

Properties:
<SlidingDoor>.height <SlidingDoor>.width <SlidingDoor>.depth <SlidingDoor>.Flip_Swing <SlidingDoor>.Flip_Hinge <SlidingDoor>.open <SlidingDoor>.Create_Frame Float Float Float Boolean Boolean Float Boolean default: default: default: default: default: default: default: 0.0 0.0 0.0 false false 0.0 true -- animatable -- animatable -- animatable

-- animatable

902

Chapter 11

3ds max Objects

<SlidingDoor>.Frame_Width <SlidingDoor>.Frame_Depth <SlidingDoor>.Door_Offset <SlidingDoor>.Generate_Mapping_Coords <SlidingDoor>.Leaf_Thickness <SlidingDoor>.Stiles_Top_Rail <SlidingDoor>.Bottom_Rail <SlidingDoor>.Number_of_Panels_Horizontally <SlidingDoor>.Number_of_Panels_Vertically <SlidingDoor>.Muntin <SlidingDoor>.Panel_Type

Float Float Float Boolean Float Float Float Integer Integer Float Integer Float Float Float Float Float Float Float Integer

default: default: default: default: default: default: default: default: default: default: default: default: default: default: default: default: default: default: default:

2.0 1.0 0.0 false 2.0 4.0 12.0 1 1 4.0 1 0.25 45.0 0.25 0.5 0.25 1.0 0.5 0

-- animatable -- animatable -- animatable -- animatable -- animatable -- animatable

-- animatable

Panel_Type = 0 - None; 1 - Glass; 2 - Beveled

<SlidingDoor>.Glass_Thickness <SlidingDoor>.Bevel_Angle <SlidingDoor>.Panel_Thickness_1 <SlidingDoor>.Panel_Thickness_2 <SlidingDoor>.Panel_Middle_Thickness <SlidingDoor>.Panel_Width_1 <SlidingDoor>.Panel_Width_2 <SlidingDoor>.Double_Doors -------animatable animatable animatable animatable animatable animatable animatable

Note: The Double_Doors property is not used by SlidingDoor.

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

SlidingWindow : GeometryClass
Constructor:
slidingWindow ...

Properties:
<SlidingWindow>.height animatable <SlidingWindow>.width animatable <SlidingWindow>.depth animatable <SlidingWindow>.Horizontal_Frame_Width animatable <SlidingWindow>.Vertical_Frame_Width animatable Float Float Float Float Float default: 0.0 default: 0.0 default: 0.0 default: 2.0 default: 2.0 ------

QuadPatch : GeometryClass

903

<SlidingWindow>.Frame_Thickness animatable <SlidingWindow>.Glazing_Thickness animatable <SlidingWindow>.Rail_Width animatable <SlidingWindow>.Number_of_Panels_Horizontally <SlidingWindow>.Number_of_Panels_Vertically <SlidingWindow>.Chamfered_Profile <SlidingWindow>.Hung <SlidingWindow>.Percent_Open animatable <SlidingWindow>.Generate_Mapping_Coords

Float Float Float Integer Integer Boolean Boolean Integer Boolean

default: 0.5 default: 0.25 default: 1.0 default: default: default: default: default:

----

1 1 false true 0 --

default: false

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

Geometry - Patch Objects

The following list displays the patch objects: QuadPatch (p. 903) TriPatch (p. 904)

QuadPatch : GeometryClass
Constructor:
quadpatch ...

Properties:
<QuadPatch>.length Float Float Integer default: 25.0 default: 25.0 default: 1 -- animatable -- animatable -- animatable, alias:

The patch length.

<QuadPatch>.width

The patch width.

<QuadPatch>.lengthsegs Length_Segments <QuadPatch>.mapCoords <QuadPatch>.widthsegs Width_Segments

The number of facets along the length of the grid.

Boolean Integer default: false default: 1 -- animatable, alias:

When on, applies mapping coordinates to the grid.

The number of facets along the width of the grid.

904

Chapter 11

3ds max Objects

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

TriPatch : GeometryClass
Constructor:
TriPatch ...

Properties:
<TriPatch>.length <TriPatch>.width <TriPatch>.mapCoords Float Float default: 25.0 default: 25.0 Boolean -- animatable -- animatable

The length of the patch. The width of the patch.

default: false

When on, applies mapping coordinates to the grid.

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

Geometry - Particle Systems

The following list displays the particle system objects: Blizzard (p. 906) PArray (p. 913) PCloud (p. 923) Snow (p. 931) Spray (p. 933) SuperSpray (p. 935) Note: Particle Systems are not available in 3D Studio VIZ.

Particle System Common Properties, Operators, and Methods

905

Particle System Common Properties, Operators, and Methods

Eight <node> functions work with particle system objects in 3ds max to allow you to get or set individual particle information. These functions return or set information about particles at the time set by the current at time context clause, or the current time slider if there is not time context active. A quick note about how the particle systems in 3ds max work will help you use these functions. The particle system keeps an array of particles big enough to hold all those alive at any one time. Each particle is identified by an index in this array. When one dies, it may be born again sometime later and appear to be a different particle. Over the course of an animation, the same particle may live and die many times as its indexed slot in the array gets re-used. Some of the functions described below use this index to identify particles, so you can have a situation where the same particle (by index) becomes a new particle in the animation as its slot gets re-used. The way you can check this is by looking at the age of the particle - if it cycles around to zero (or a lower number depending on time resolution), you know it has become a new particle. If a particle is actually not alive at a given time, for example at the beginning of an animation or when you set up an explosive emission, the functions below that get position, velocity and age return undefined. This tells you that the particle is not currently alive. Here are the particle system functions:
particleCount <particlesys_node>

Returns the number of current particle slots in the system as an integer. This value is the number of particles that are to be drawn to the viewports unless the scene is currently being rendered. If the scene is being rendered, the number returned can be either the render count or the viewport count, depending on whether the particle system has been evaluated for rendering or not.
particleSize <particlesys_node>

Returns the size of the particles in the system as float. This is set in the particle system parameter rollout - there is one size for all particles in a particle system. If you are using these functions to attach objects to particles, you can of course, make the individual objects any size you want.
particlePos <particlesys_node> <particle_index_integer>

Returns the position coordinate of the indexed particle at the current time as a point3. Indexes are 1-based. The coordinate returned is in the current working coordinate system. Returns undefined if the particle is not alive at the current time.
particleVelocity <particlesys_node> <particle_index_integer>

Returns the current velocity vector for the indexed particle as a point3. The vector returned is rotated into the current working coordinate system. Returns undefined if the particle is not alive at the current time.
particleAge <particlesys_node> <particle_index_integer>

Returns the current age of the indexed particle as a time value, relative to when it was last born. Remember, particles get recycled and you can detect this by looking at the age value cycling round. Returns undefined if the particle is not alive at the current time.

906

Chapter 11

3ds max Objects

Blizzard : GeometryClass
Constructor:
blizzard ...

Note: This class is not available in 3D Studio VIZ. Properties: -- Basic Parameters
<Blizzard>.Emitter_Width animatable Float default: 0.0 --

The width of the emitter icon.

<Blizzard>.Emitter_Length animatable Float default: 0.0 --

The width of the emitter icon.

<Blizzard>.emitterHidden Boolean default: false

When on, hides the emitter in viewports. When off, the emitter is displayed in viewports. The emitter is never rendered.
<Blizzard>.viewType Integer default: 0

Set the display icon for particles in the viewport: Dots (Displays the particles as dots.) Ticks (Displays the particles as crosses.) Mesh (Displays the particles as mesh objects. This results in slower viewport redraws.) Bbox (For instanced geometry only, this displays each instanced particle, whether a single object, a hierarchy, or a group, as a bounding box.)
<Blizzard>.viewPercent percentage, alias: Percentage_Displayed Float default: 10.0 --

Sets the percentage of particles displayed in the viewport. -- Particle Generation

<Blizzard>.quantityMethod Integer default: 0

Set the method by which the number of particles is determined over time: Use Rate (Specifies a fixed number of particles emitted per frame.) Use Total (Specifies a total number of particles formed over the life of the system.) Tip: Generally, Use Rate is best for a continuous flow of particles, like a trail of pixie dust, while Use Total is better for bursts of particles over a short period of time.
<Blizzard>.Birth_Rate animatable Integer default: 10 --

The number of particles emitted per frame.

<Blizzard>.Total_Number Integer default: 100

The total number of particles to be emitted.

Blizzard : GeometryClass

907

<Blizzard>.speed animatable <Blizzard>.Speed_Variation animatable, percentage <Blizzard>.tumble animatable

Float

default: 10.0

--

The velocity of the particle at birth, along the normal, in units traveled per frame.
Float default: 0.0 --

Percentage of variation to the speed of emission for each particle.

Float default: 0.0 --

Amount of random rotation of the particles.

<Blizzard>.Tumble_Rate animatable Float default: 0.0 --

Speed at which the particles rotate.

<Blizzard>.Emitter_Start Time Time Time Time default: 0f default: 30f default: 100f default: 30f --

The frame at which particles begin to exist in the scene.

<Blizzard>.Emitter_Stop

The last frame at which particles are emitted.

<Blizzard>.Display_Until <Blizzard>.life animatable

Time at which all particles will disappear, regardless of other settings.

The lifespan of each particle from the time of creation.

<Blizzard>.Life_Variation animatable <Blizzard>.subsampleCreationTime Time default: 0f --

The number of frames by which the life of each particle can vary from the norm.
Boolean default: false

When on, enables the addition of a time offset to the equations of motion that prevents puffing in time.
<Blizzard>.subsampleEmitterTranslation Boolean default: true

If the object-based emitter is moving in space, particles are created at integral times at positions along the geometrys path between renderable positions. This prevents puffing in space.
<Blizzard>.subsampleEmitterRotation <Blizzard>.size animatable Boolean Float default: true default: 1.0 --

If the emitter is rotating, turn this on to avoid puffing and produce smooth spiral effects.

The target size for all particles in the system.

<Blizzard>.Size_Variation animatable, percentage <Blizzard>.Growth_Time Float default: 0.0 --

The percentage by which the size of each particle may vary from the norm.
Time default: 10f

The number of intervals over which the particle grows from being very small (0.1a system constant) to the Size value.

908

Chapter 11

3ds max Objects

<Blizzard>.Fade_Time

Time

default: 10f

The number of intervals over which the particle will shrink to 1/10th its Size setting prior to its death.
<Blizzard>.seed alias: Random_Seed Integer default: 0 --

By changing the Seed value, you achieve different results using otherwise identical particle settings. -- Particle Type
<Blizzard>.particleType Integer default: 0

The type of particle emitted: Standard Particle (Uses one of several standard particle types, such as triangle, cube, tetra, and so on.) MetaParticles (Uses Metaball particles. These are particle systems in which the individual particles blend together in blobs or streams.) Instanced Geometry (Generates particles that are instances of either an object, a linked hierarchy of objects, or a group.)
<Blizzard>.standardParticle Integer default: 0

standardParticle = 0 - Triangle; 1 - Cube; 2 - Special; 3 - Facing; 4 - Constant; 5 - Tetra; 6 SixPoint; 7 - Sphere

<Blizzard>.Metaparticle_Tension animatable Float default: 1.0 --

Determines the tightness of the particles, with regard to their tendency to blend with other particles. The higher the Tension, the harder the blobs, and the harder it is for them to merge.
<Blizzard>.Metaparticle_Tension_Variation animatable, percentage Float default: 0.0 --

The percent of variation of the Tension effect.

<Blizzard>.metaballRenderCoarsness alias: Metaparticle_Coarseness Float default: 0.5 --

The coarseness for metaparticles in the rendered scene.

<Blizzard>.metaballViewCoarsness Float Boolean default: 1.0 default: true

The coarseness for the viewport display.

<Blizzard>.metaballAutoCoarsness

When this is on, the rendering coarseness is automatically set, based on the size of the particles, and the viewport coarseness is set to about twice that of the rendering coarseness.
<Blizzard>.Bubble_Amplitude Integer default: 0

Turns on/off One Connected Blob. OFF ON

Blizzard : GeometryClass

909

<Blizzard>.instancingObject

Node Boolean

default: undefined default: false

The object which is instanced.

<Blizzard>.instanceSubTree

Turn this on when you want to include the linked children of the picked object in the particle. If the picked object is a group, all children of the group are included.
<Blizzard>.instanceKeyOffsetType Integer default: 0

Set the animation offset keying: None (Each particle duplicates the timing of the original object. As a result, the animation of all particles will be identically timed.) Birth (The firstborn particle is an instance of the current animation of the source object at the moment of that particles birth. Each subsequent particle then use the same start time for the animation.) Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each particle is born using the same animation as the source object at the time of birth, but with a random offset of frames, based on the .instanceFrameOffset value.)
<Blizzard>.instanceFrameOffset alias: Animation_Offset_Amount Integer default: 0 --

The property value is the UI value times the number of ticks per frame. The number of ticks per frame is accessible via the ticksPerFrame system global variable.
<Blizzard>.mappingType Integer default: 0

Specifies how a mapped material affects the particles: Time (Maps particles over time.) Distance (Maps particles over a distance.) Emitter Fit Planar (Maps particles at birth, based on their point of emission from the rectangular Blizzard emitter icon. The UV range of the mapped material runs from 0 to 1 over the width and length of the emitter.)
<Blizzard>.Mapping_Time_Base animatable Time default: 30f --

The number of frames from the birth of the particle that it takes to complete one mapping of the particle.
<Blizzard>.Mapping_Distance_Base animatable Float default: 100.0 --

The distance, in units, from the birth of the particle that it takes to complete one mapping of the particle.
<Blizzard>.materialSource Integer default: 0

Updates the material carried by the particle system, using the source specified: Icon (The particles use the material currently assigned to the particle system icon.) Instanced Geometry (The particles use the material assigned to the instanced geometry.)

910

Chapter 11

3ds max Objects

-- Rotation and Collision

<Blizzard>.Spin_Time animatable <Blizzard>.Spin_Time_Variation animatable, percentage Time default: 30f --

The number of frames for one rotation of a particle. If set to 0, no rotation takes place.
Float default: 0.0 --

The percent of variation of the Spin Time.

<Blizzard>.Spin_Phase animatable, angle Float default: 0.0 --

The initial particle rotation, in degrees.

<Blizzard>.Spin_Phase_Variation animatable, percentage Float default: 0.0 --

The percent of variation of the Phase.

<Blizzard>.spinAxisType Integer default: 0

The spin axis for the particles: Random (The spin axis for each of the particles is random.) User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.)
<Blizzard>.X_Spin_Vector animatable Float default: 1.0 --

Spin vector of the X-axis.

<Blizzard>.Y_Spin_Vector animatable Float default: 0.0 --

Spin vector of the Y-axis.

<Blizzard>.Z_Spin_Vector animatable Float default: 0.0 --

Spin vector of the Z-axis.

<Blizzard>.Spin_Axis_Variation animatable, angle Float default: 0.0 --

The amount, in degrees, by which the spin axis of each particle may vary from the specified X Axis, Y Axis, and Z Axis settings.
<Blizzard>.Interparticle_Collisions_On Integer default: 0

Turn on/off interparticle collisions: OFF ON

<Blizzard>.Interparticle_Collision_Steps Integer default: 2

The number of intervals per rendering interval, during which an inter-particle collision test is conducted. The higher the value, the more accurate the simulation, but the slower the simulation will run.
<Blizzard>.Interparticle_Collision_Bounce animatable, percentage Float default: 100.0 --

The degree to which speed is recovered after a collision.

Blizzard : GeometryClass

911

<Blizzard>.Interparticle_Collision_Bounce_Variation animatable, percentage

Float

default: 0.0

--

The percentage of random variation of the Bounce value, applied to the particles. -- Object Motion Inheritance
<Blizzard>.motionInfluence animatable, alias: Object_Motion_Inheritance Float default: 100.0 --

The percent of particles that inherit the motion of the object-based emitter at the moment of particle formation.
<Blizzard>.motionMultiplier animatable, alias: Object_Motion_Multiplier Float default: 1.0 --

Modifies the amount by which the emitter motion affects the particle motion. This can be a positive or negative number.
<Blizzard>.motionVariation Float default: 0.0 animatable, percentage; alias: Object_Motion_Multiplier_Variation --

Percentage of variation of the Multiplier value. -- Particle Spawn

<Blizzard>.spawnType Integer default: 0

Determines what happens to particles at either collision or death: None (Particles act as they normally would. That is, upon collision, they either bounce or stick, depending on Particle Bounce settings in the deflector, and on death they disappear.) Die After Collision (Particles disappear when they strike a deflector to which theyre bound, such as the SDeflector.) Spawn on Collision (Spawn effects take place upon collision with a bound deflector.) Spawn on Death (Spawn effects take place at the end of each particles life.) Spawn Trails (Particles are spawned from existing particles at each frame of that particles life.)
<Blizzard>.Die__X_frames_after_collision animatable Time default: 0f --

The life, in frames, that the particle will persist after the collision. Setting this to 0 (the default) causes particles to vanish immediately after the collision.
<Blizzard>.Die__X_frames_after_collision_variation animatable, percentage Float default: 0.0 --

Varies the Persist value of each particle, when Persist is greater than 0. This lets you feather the dying off of the particle density.
<Blizzard>.Spawn_Affects Integer default: 100

The percentage of particles that will spawn. Reducing this reduces the number of particles that produce spawned particles.
<Blizzard>.Spawn_Multiplier_Variation percentage Float default: 0.0 --

Percentage range by which the Multiplier value will vary, frame by frame.

912

Chapter 11

3ds max Objects

<Blizzard>.Spawn_Direction_Chaos animatable

Float

default: 0.0

--

The amount by which the direction of the spawned particle can vary from the direction of the parent particle. A setting of 0 means no variance. A setting of 100 causes the spawned particle to travel in any random direction. A setting of 50 causes the spawned particle to deviate from its parents path by up to 90 degrees.
<Blizzard>.Spawn_Speed_Chaos animatable Float default: 0.0 --

The range of a percentage of change in the speed of the spawned particle relative to its parent. A value of 0 means no change.
<Blizzard>.spawnSpeedType Integer default: 0

Sets the type of speed applied to spawn particles: Slow (Applies the .spawn_Speed_Chaos value randomly to slow the speed of the spawned particles.) Fast (Randomly speeds up particles based on the .spawn_Speed_Chaos value.) Both (Some particles speed up, while others slow down, based on the .spawn_Speed_Chaos value.)
<Blizzard>.spawnInheritVelocity Boolean default: false

When on, spawned particles inherit the speed of their parents, in addition to the effect of the .spawn_Speed_Chaos value.
<Blizzard>.spawnSpeedFixed Boolean default: false

When on, uses the .spawn_Speed_Chaos value as a set value, rather than as a range applied randomly to each particle.
<Blizzard>.lifespanValueQueue Array default: #()

lifespanValueQueue is an array of integers which correspond to lifespan values for each spawned generation of particles.
<Blizzard>.objectMutationQueue Array default: #()

objectMutationQueue is an array of nodes which correspond to instanced-object particle types. Each generation of spawning will use the next node as its object type.

See also
Particle System Common Properties, Operators, and Methods (p. 905) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

PArray : GeometryClass

913

PArray : GeometryClass
Constructor:
parray ...

Note: This class is not available in 3D Studio VIZ. Properties: -- Basic Parameters
<PArray>.emitter Node Integer default: undefined default: 0 --

The object which acts as an emitter.

<PArray>.formation alias: Emitter_Distribution

Set the emitter distribution type: Over Entire Surface (Emits particles randomly over the entire surface of the object-based emitter.) Along Visible Edges (Emits particles randomly from the visible edges of the object.) At All Vertices (Emits particles from the vertices of the object.) At Distinct Points (Places a specified number of emitter points randomly over the surface of the object.) At Face Centers (Emits particles from the center of each triangular face.)
<PArray>.numDistinctPoints alias: Number_of_Emitters <PArray>.Use_Selected_Subobjects animatable Integer default: 20 --

The number of emitter points used when At Distinct Points is chosen.

Integer default: 0 --

With mesh-based emitters, this limits the source of the particle stream to the sub-object selection passed up the modifier stack in the object-based emitter. OFF ON
<PArray>.iconsize alias: Emitter_Width Float default: 20.0 --

The width of the emitter icon.

<PArray>.iconHidden Boolean default: false

When on, hides the emitter in viewports. When off, the emitter is displayed in viewports. The emitter is never rendered.
<PArray>.viewType Integer default: 0

Set the display icon for particles in the viewport: Dots (Displays the particles as dots.) Ticks (Displays the particles as crosses.)

914

Chapter 11

3ds max Objects

Mesh (Displays the particles as mesh objects. This results in slower viewport redraws.) Bbox (For instanced geometry only, this displays each instanced particle, whether a single object, a hierarchy, or a group, as a bounding box.)
<PArray>.viewPercent percentage, alias: Percentage_Displayed Float default: 10.0 --

The percentage of particles displayed in the viewport. -- Particle Generation

<PArray>.quantityMethod Integer default: 0

Set the method by which the number of particles is determined over time: Use Rate (Specifies a fixed number of particles emitted per frame.) Use Total (Specifies a total number of particles formed over the life of the system.) Tip: Generally, Use Rate is best for a continuous flow of particles, like a trail of pixie dust, while Use Total is better for bursts of particles over a short period of time.
<PArray>.Birth_Rate animatable Integer default: 10 --

The number of particles emitted per frame.

<PArray>.Total_Number Integer Float default: 100 default: 10.0 --

The total number of particles to be emitted.

<PArray>.speed animatable <PArray>.Speed_Variation animatable, percentage <PArray>.Divergence_Angle animatable, angle

The velocity of the particle at birth, along the normal, in units traveled per frame.
Float default: 0.0 --

Percentage of variation to the speed of emission for each particle.

Float default: 10.0 --

Applies an angular degree of variation by which each particles velocity can vary from the emitter normal.
<PArray>.Emitter_Start <PArray>.Emitter_Stop Time Time Time Time default: 0f default: 30f default: 100f default: 30f --

The frame at which particles begin to exist in the scene. The last frame at which particles are emitted.
<PArray>.Display_Until <PArray>.life animatable <PArray>.Life_Variation animatable

Time at which all particles will disappear, regardless of other settings.

The lifespan of each particle from the time of creation.

Time default: 0f --

The number of frames by which the life of each particle can vary from the norm.

PArray : GeometryClass

915

<PArray>.subsampleCreationTime

Boolean

default: false

When on, enables the addition of a time offset to the equations of motion that prevents puffing in time.
<PArray>.subsampleEmitterTranslation Boolean default: true

If the object-based emitter is moving in space, particles are created at integral times at positions along the geometrys path between renderable positions. This prevents puffing in space.
<PArray>.subsampleEmitterRotation <PArray>.size animatable Boolean Float default: true default: 1.0 --

If the emitter is rotating, turn this on to avoid puffing and produce smooth spiral effects.

The target size for all particles in the system.

<PArray>.Size_Variation animatable, percentage <PArray>.Growth_Time Float default: 0.0 --

The percentage by which the size of each particle may vary from the norm.
Time default: 10f

The number of intervals over which the particle grows from being very small (0.1a system constant) to the Size value.
<PArray>.Fade_Time Time default: 10f

The number of intervals over which the particle will shrink to 1/10th its Size setting prior to its death.
<PArray>.seed alias: Random_Seed Integer default: 0 --

By changing the Seed value, you achieve different results using otherwise identical particle settings. -- Particle Type
<PArray>.particleType Integer default: 0

The type of particle emitted: Standard Particle (Uses one of several standard particle types, such as triangle, cube, tetra, and so on.) MetaParticles (Uses Metaball particles. These are particle systems in which the individual particles blend together in blobs or streams.) Object Fragments (Creates particles out of fragments of an object.) Instanced Geometry (Generates particles that are instances of either an object, a linked hierarchy of objects, or a group.)

916

Chapter 11

3ds max Objects

<PArray>.standardParticle

Integer

default: 0

Set the type of particle used when standard particles is selected: Triangle (Renders each particle as a triangle. Use Triangle particles with noise opacity for steam or smoke.) Cube (Renders each particle as a cube.) Special (Each particle consists of three intersecting 2D squares. These are effective when you use a face-map material, optionally along with an opacity map, to create the effect of a three-dimensional particle.) Facing (Renders each particle as a square that always faces the view. Use with an appropriate opacity map for bubbles or snowflakes.) Constant (Provides a particle that remains the same size, in pixels, specified by the size value. This size never changes, regardless of its distance from the camera. Note that this particle type can only be displayed in the viewports as a dot or a tick. If you turn on this option while Mesh is selected, the viewport display is automatically switched to Ticks.) Tetra (Renders each particle as a mapped tetrahedron, whose tail points toward the normal vector of the emission, and whose head points away. Use Tetra particles for raindrops or sparks.) SixPoint (Renders each particle as a six-pointed, two-dimensional star.) Sphere (Renders each particle as a sphere.)
<PArray>.Metaparticle_Tension animatable Float default: 1.0 --

Determines the tightness of the particles, with regard to their tendency to blend with other particles. The higher the Tension, the harder the blobs, and the harder it is for them to merge.
<PArray>.Metaparticle_Tension_Variation animatable, percentage Float default: 0.0 --

The percent of variation of the Tension effect.

<PArray>.metaballRenderCoarsness alias: Metaparticle_Coarseness <PArray>.metaballViewCoarsness Float default: 0.5 --

The coarseness for metaparticles in the rendered scene.

Float Boolean default: 1.0 default: true

The coarseness for the viewport display.

<PArray>.metaballAutoCoarsness

When this is on, the rendering coarseness is automatically set, based on the size of the particles, and the viewport coarseness is set to about twice that of the rendering coarseness.

PArray : GeometryClass

917

<PArray>.fragmentMethod

Integer

default: 0

Method for object fragment particles: All Faces (Each face of the object becomes a particle. This results in triangular particles.) Number of Chunks (The object breaks into irregular fragments.) Smoothing Angle (The fragments are broken based on the angles between face normals, as specified in the fragSmoothingAngle value. Generally, the higher the value, the fewer the number of fragments.)
<PArray>.Fragment_Thickness Float default: 1.0

Sets the thickness of the fragments. At 0, the fragments are single-sided with no thickness. When greater than 0, the fragments are extruded, at fragmentation time, by the amount specified. The outer and inner surfaces of the fragment use identical smoothing, which is picked up from the object-based emitter. The edges of the fragments are not smoothed.
<PArray>.fragChunkMinimum alias: Fragment_Count Integer default: 100 --

Determines a number of seed faces in the geometry. Each seed face collects connecting faces surrounding it until all available faces are exhausted. Any leftover faces become unique particles, thus increasing the minimum number of fragments.
<PArray>.fragSmoothingAngle Float Node Boolean default: 0.0 default: undefined default: false

Sets the amount of smoothing angle.

<PArray>.instancingObject

The object which is instanced.

<PArray>.instanceSubTree

Turn this on when you want to include the linked children of the picked object in the particle. If the picked object is a group, all children of the group are included.
<PArray>.instanceKeyOffsetType Integer default: 0

Set the animation offset keying: None (Each particle duplicates the timing of the original object. As a result, the animation of all particles will be identically timed.) Birth (The firstborn particle is an instance of the current animation of the source object at the moment of that particles birth. Each subsequent particle then use the same start time for the animation.) Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each particle is born using the same animation as the source object at the time of birth, but with a random offset of frames, based on the .instanceFrameOffset value.)
<PArray>.instanceFrameOffset alias: Animation_Offset_Amount Integer default: 0 --

The property value is the UI value times the number of ticks per frame. The number of ticks per frame is accessible via the ticksPerFrame system global variable.

918

Chapter 11

3ds max Objects

<PArray>.mappingType

Integer

default: 0

Specifies how a mapped material affects the particles: Time (Maps particles over time.) Distance (Maps particles over a distance.)
<PArray>.Mapping_Time_Base animatable Time default: 30f --

The number of frames from the birth of the particle that it takes to complete one mapping of the particle.
<PArray>.Mapping_Distance_Base animatable Float default: 100.0 --

The distance, in units, from the birth of the particle that it takes to complete one mapping of the particle.
<PArray>.materialSource Integer default: 0

Updates the material carried by the particle system, using the source specified: Icon (The particles use the material currently assigned to the particle system icon.) Picked Emitter (The particles use the material assigned to the distribution object.) Instanced Geometry (The particles use the material assigned to the instanced geometry.)
<PArray>.fragOutsideMatID Integer default: 0

Specifies which face ID number is assigned to the outside faces of the fragments. This defaults to 0, which is not a valid ID number, forcing the outside of the particle fragments to use whatever material is currently assigned to the associated faces. Thus, if your distribution object already has several submaterials assigned to its outer faces, these materials are retained by using ID 0. If you want a single, specific submaterial, you can assign it by changing this value.
<PArray>.fragEdgeMatID <PArray>.fragBackMatID Integer Integer default: 2 default: 3

Specifies which submaterial ID number is assigned to the edges of the fragments. Specifies which submaterial ID number is assigned to the back sides of the fragments. -- Rotation and Collision
<PArray>.Spin_Time animatable <PArray>.Spin_Time_Variation animatable, percentage Time default: 0f --

The number of frames for one rotation of a particle. If set to 0, no rotation takes place.
Float default: 0.0 --

The percent of variation of the Spin Time.

<PArray>.Spin_Phase animatable, angle Float default: 0.0 --

The initial particle rotation, in degrees.

<PArray>.Spin_Phase_Variation animatable, percentage Float default: 0.0 --

The percent of variation of the Phase.

PArray : GeometryClass

919

<PArray>.spinAxisType

Integer

default: 0

The spin axis for the particles: Random (The spin axis for each of the particles is random.) Direction of Travel/Mblur (Rotates the particles about a vector formed by the direction in which theyre moving.) User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.)
<PArray>.Blur_Stretch animatable Integer default: 0 --

When greater than 0, the particles stretch along the travel axis, depending on their speed. Specifically, the Stretch value specifies the percent of their length per each unit of the Speed setting (in the Particle Motion group). Thus, if you set Stretch to 2 while Speed is set at 10, the particles are stretched 20 percent longer than their original size along the axis of their travel. This value is only available when you choose Direction of Travel/Mblur.
<PArray>.X_Spin_Vector animatable Float default: 1.0 --

Spin vector of the X-axis.

<PArray>.Y_Spin_Vector animatable Float default: 0.0 --

Spin vector of the Y-axis.

<PArray>.Z_Spin_Vector animatable Float default: 0.0 --

Spin vector of the Z-axis.

<PArray>.Spin_Axis_Variation animatable, angle Float default: 0.0 --

The amount, in degrees, by which the spin axis of each particle may vary from the specified X Axis, Y Axis, and Z Axis settings.
<PArray>.Interparticle_Collisions_On Integer default: 0

Turn on/off interparticle collisions: OFF ON

<PArray>.Interparticle_Collision_Steps Integer default: 2

The number of intervals per rendering interval, during which an inter-particle collision test is conducted. The higher the value, the more accurate the simulation, but the slower the simulation will run.
<PArray>.Interparticle_Collision_Bounce animatable, percentage <PArray>.Interparticle_Collision_Bounce_Variation animatable, percentage Float default: 100.0 --

The degree to which speed is recovered after a collision.

Float default: 0.0 --

The percentage of random variation of the Bounce value, applied to the particles.

920

Chapter 11

3ds max Objects

-- Object Motion Inheritance

<PArray>.motionInfluence animatable, alias: Object_Motion_Inheritance Float default: 100.0 --

The percent of particles that inherit the motion of the object-based emitter at the moment of particle formation.
<PArray>.motionMultiplier animatable, alias: Object_Motion_Multiplier Float default: 1.0 --

Modifies the amount by which the emitter motion affects the particle motion. This can be a positive or negative number.
<PArray>.motionVariation Float default: 0.0 animatable, percentage; alias: Object_Motion_Multiplier_Variation --

Percentage of variation of the Multiplier value. -- Bubble Motion

<PArray>.Bubble_Amplitude animatable <PArray>.Bubble_Amplitude_Variation animatable, percentage <PArray>.Bubble_Period animatable Float default: 0.0 --

The distance the particle moves off its usual velocity vector as it travels.
Float default: 0.0 --

The percent of Amplitude variation applied to each particle.

Time default: 100000f --

The cycle time for one complete oscillation of a particle through the bubble wave. A recommended value might be 20-30 intervals.
<PArray>.Bubble_Period_Variation animatable, percentage Float default: 0.0 --

The percent of Period variation for each particle.

<PArray>.Bubble_Phase animatable, angle <PArray>.Bubble_Phase_Variation animatable, percentage Float default: 0.0 --

The initial displacement of the bubble pattern along the vector.

Float default: 0.0 --

The percent of Phase variation for each particle. -- Particle Spawn

<PArray>.spawnType Integer default: 0

Determines what happens to particles at either collision or death: None (Particles act as they normally would. That is, upon collision, they either bounce or stick, depending on Particle Bounce settings in the deflector, and on death they disappear.) Die After Collision (Particles disappear when they strike a deflector to which theyre bound, such as the SDeflector.)

PArray : GeometryClass

921

Spawn on Collision (Spawn effects take place upon collision with a bound deflector.) Spawn on Death (Spawn effects take place at the end of each particles life.) Spawn Trails (Particles are spawned from existing particles at each frame of that particles life.)
<PArray>.Die__X_frames_after_collision animatable Time default: 0f --

The life, in frames, that the particle will persist after the collision. Setting this to 0 (the default) causes particles to vanish immediately after the collision.
<PArray>.Die__X_frames_after_collision_variation animatable, percentage Float default: 0.0 --

Varies the Persist value of each particle, when Persist is greater than 0. This lets you feather the dying off of the particle density.
<PArray>.Spawn_Generations Integer default: 1

The number of spawns beyond the original particle generation. For example, if this is set to 1, and youre spawning at death, one spawning will occur beyond the original lifespan of each particle.
<PArray>.Spawn_Affects Integer default: 100

The percentage of particles that will spawn. Reducing this reduces the number of particles that produce spawned particles.
<PArray>.Spawn_Multiplier <PArray>.Spawn_Multiplier_Variation percentage <PArray>.Spawn_Direction_Chaos animatable, percentage Integer Float default: 1 default: 0.0 --

Multiplies the number of particles spawned at each spawning event.

Percentage range by which the Multiplier value will vary, frame by frame.
Float default: 0.0 --

The amount by which the direction of the spawned particle can vary from the direction of the parent particle. A setting of 0 means no variance. A setting of 100 causes the spawned particle to travel in any random direction. A setting of 50 causes the spawned particle to deviate from its parents path by up to 90 degrees.
<PArray>.Spawn_Speed_Chaos animatable Float default: 0.0 --

Random percentage range of scaling of the spawned particles relative to their parents, and dependent on the options below.
<PArray>.spawnSpeedType Integer default: 0

Sets the type of speed applied to spawn particles: Slow (Applies the .spawn_Speed_Chaos value randomly to slow the speed of the spawned particles.) Fast (Randomly speeds up particles based on the .spawn_Speed_Chaos value.) Both (Some particles speed up, while others slow down, based on the .spawn_Speed_Chaos value.)

922

Chapter 11

3ds max Objects

<PArray>.spawnInheritVelocity

Boolean

default: false

When on, spawned particles inherit the speed of their parents, in addition to the effect of the .spawn_Speed_Chaos value.
<PArray>.spawnSpeedFixed Boolean default: false

When on, uses the .spawn_Speed_Chaos value as a set value, rather than as a range applied randomly to each particle.
<PArray>.Spawn_Scale_Chaos animatable Float default: 0.0 --

The range of a percentage of change in the speed of the spawned particle relative to its parent. A value of 0 means no change.
<PArray>.spawnScaleType Integer default: 0

The type of speed scaling for the spawned particles: Slow (Applies the speed factor randomly to slow the speed of the spawned particles.) Fast (Randomly speeds up particles based on the speed factor.) Both (Some particles speed up, while others slow down, based on the speed factor.)
<PArray>.spawnScaleFixed Boolean default: false

When on, uses the .spawn_Scale_Chaos value as a set value, rather than as a range applied randomly to each particle.
<PArray>.lifespanValueQueue Array default: #()

lifespanValueQueue is an array of integers which correspond to lifespan values for each spawned generation of particles.
<PArray>.Spawn_Lifespan Integer Array default: 0 default: #()

Value that sets initial lifespan of spawned particles.

<PArray>.objectMutationQueue

objectMutationQueue is an array of nodes which correspond to instanced-object particle types. Each generation of spawning will use the next node as its object type.

See also
Particle System Common Properties, Operators, and Methods (p. 905) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

PCloud : GeometryClass

923

PCloud : GeometryClass
Constructor:
pcloud ...

Note: This class is not available in 3D Studio VIZ. Properties: -- Basic Parameters
<PCloud>.emitter Node Integer default: undefined default: 0

The object which acts as an emitter.

<PCloud>.formation

Set the emitter formation: Box Emitter Sphere Emitter Cylinder Emitter Object-based Emitter
<PCloud>.Emitter_Rad_Len animatable <PCloud>.Emitter_Width animatable Float default: 0.0 --

The radius of a spherical or cylindrical icon, and the length of a box icon.
Float default: 0.0 --

The width of a box emitter.

<PCloud>.Emitter_Height animatable Float default: 0.0 --

The height of a box or cylindrical emitter.

<PCloud>.emitterHidden Boolean default: false

Hides the emitter in the viewport, when on. Note: the emitter is never rendered.
<PCloud>.viewType Integer default: 0

Set the display icon for particles in the viewport: Dots (Displays the particles as dots.) Ticks (Displays the particles as crosses.) Mesh (Displays the particles as mesh objects. This results in slower viewport redraws.) Bbox (For instanced geometry only, this displays each instanced particle, whether a single object, a hierarchy, or a group, as a bounding box.)
<PCloud>.viewPercent percentage, alias: Percentage_Displayed Float default: 10.0 --

The percentage of particles displayed in the viewport.

924

Chapter 11

3ds max Objects

-- Particle Generation
<PCloud>.quantityMethod Integer default: 0

Set the method by which the number of particles is determined over time: Use Rate (Specifies a fixed number of particles emitted per frame.) Use Total (Specifies a total number of particles formed over the life of the system.) Tip: Generally, Use Rate is best for a continuous flow of particles, like a trail of pixie dust, while Use Total is better for bursts of particles over a short period of time.
<PCloud>.Birth_Rate animatable Integer default: 10 --

The number of particles emitted per frame.

<PCloud>.Total_Number Integer Float default: 100 default: 0.0 --

The total number of particles to be emitted.

<PCloud>.speed animatable <PCloud>.Speed_Variation animatable, percentage <PCloud>.motionType

The velocity of the particle at birth, along the normal, in units traveled per frame.
Float default: 0.0 --

Percentage of variation to the speed of emission for each particle.

Integer default: 0

Set the particles motionType Random Direction (This option emits particles in random directions.) Enter Vector (The direction of the particles is determined by a vector defined by the three X, Y, and Z vectors.) Reference Object (Emits particles in the direction of the local Z axis of a specified object.)
<PCloud>.Direction_Vector_X animatable Float default: 1.0 --

The particle direction vectors for the X-axis.

<PCloud>.Direction_Vector_Y animatable Float default: 0.0 --

The particle direction vectors for the Y-axis.

<PCloud>.Direction_Vector_Z animatable Float default: 0.0 --

The particle direction vectors for the Z-axis.

<PCloud>.motionReferenceObject Node default: undefined default: 0.0 --

The object used as the reference object.

<PCloud>.directionVariation Float animatable, percentage, alias: Speed_Direction_Variation

Percentage of variation to the direction when you choose either the Direction Vector or Reference Object option.
<PCloud>.Emitter_Start Time default: 0f

The frame at which particles begin to exist in the scene.

PCloud : GeometryClass

925

<PCloud>.Emitter_Stop

Time Time Time

default: 0f default: 100f default: 101f --

The last frame at which particles are emitted.

<PCloud>.Display_Until <PCloud>.life animatable <PCloud>.Life_Variation animatable <PCloud>.size animatable

Time at which all particles will disappear, regardless of other settings.

The lifespan of each particle from the time of creation.

Time default: 0f --

The number of frames by which the life of each particle can vary from the norm.
Float default: 1.0 --

The target size for all particles in the system.

<PCloud>.Size_Variation animatable, percentage <PCloud>.Growth_Time Float default: 0.0 --

The percentage by which the size of each particle may vary from the norm.
Time default: 0f

The number of intervals over which the particle grows from being very small (0.1a system constant) to the Size value.
<PCloud>.Fade_Time Time default: 0f

The number of intervals over which the particle will shrink to 1/10th its Size setting prior to its death.
<PCloud>.seed alias: Random_Seed Integer default: 0 --

By changing the Seed value, you achieve different results using otherwise identical particle settings. -- Particle Type
<PCloud>.particleType Integer default: 0

The type of particle emitted: Standard Particle (Uses one of several standard particle types, such as triangle, cube, tetra, and so on.) MetaParticles (Uses Metaball particles. These are particle systems in which the individual particles blend together in blobs or streams.) Instanced Geometry (Generates particles that are instances of either an object, a linked hierarchy of objects, or a group.)
<PCloud>.standardParticle Integer default: 0

Set the type of particle used when standard particles is selected: Triangle (Renders each particle as a triangle. Use Triangle particles with noise opacity for steam or smoke.) Cube (Renders each particle as a cube.)

926

Chapter 11

3ds max Objects

Special (Each particle consists of three intersecting 2D squares. These are effective when you use a face-map material, optionally along with an opacity map, to create the effect of a three-dimensional particle.) Facing (Renders each particle as a square that always faces the view. Use with an appropriate opacity map for bubbles or snowflakes.) Constant (Provides a particle that remains the same size, in pixels, specified by the size value. This size never changes, regardless of its distance from the camera. Note that this particle type can only be displayed in the viewports as a dot or a tick. If you turn on this option while Mesh is selected, the viewport display is automatically switched to Ticks.) Tetra (Renders each particle as a mapped tetrahedron, whose tail points toward the normal vector of the emission, and whose head points away. Use Tetra particles for raindrops or sparks.) SixPoint (Renders each particle as a six-pointed, two-dimensional star.) Sphere (Renders each particle as a sphere.)
<PCloud>.Metaparticle_Tension animatable Float default: 1.0 --

Determines the tightness of the particles, with regard to their tendency to blend with other particles. The higher the Tension, the harder the blobs, and the harder it is for them to merge.
<PCloud>.Metaparticle_Tension_Variation animatable, percentage Float default: 0.0 --

The percent of variation of the Tension effect.

<PCloud>.metaballRenderCoarsness alias: Metaparticle_Coarseness <PCloud>.metaballViewCoarsness Float default: 0.5 --

The coarseness for metaparticles in the rendered scene.

Float Boolean default: 1.0 default: true

The coarseness for the viewport display.

<PCloud>.metaballAutoCoarsness

When this is on, the rendering coarseness is automatically set, based on the size of the particles, and the viewport coarseness is set to about twice that of the rendering coarseness.
<PCloud>.instancingObject Node Boolean default: undefined default: false

The object which is instanced.

<PCloud>.instanceSubTree

Turn this on when you want to include the linked children of the picked object in the particle. If the picked object is a group, all children of the group are included.
<PCloud>.instanceKeyOffsetType Integer default: 0

Set the animation offset keying: None (Each particle duplicates the timing of the original object. As a result, the animation of all particles will be identically timed.)

PCloud : GeometryClass

927

Birth (The firstborn particle is an instance of the current animation of the source object at the moment of that particles birth. Each subsequent particle then use the same start time for the animation.) Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each particle is born using the same animation as the source object at the time of birth, but with a random offset of frames, based on the .instanceFrameOffset value.)
<PCloud>.instanceFrameOffset alias: Animation_Offset_Amount Integer default: 0 --

The property value is the UI value times the number of ticks per frame. The number of ticks per frame is accessible via the ticksPerFrame system global variable.
<PCloud>.mappingType Integer default: 0

Specifies how a mapped material affects the particles: Time (Maps particles over time.) Distance (Maps particles over a distance.)
<PCloud>.Mapping_Time_Base animatable Time default: 30f --

The number of frames from the birth of the particle that it takes to complete one mapping of the particle.
<PCloud>.Mapping_Distance_Base animatable Float default: 100.0 --

The distance, in units, from the birth of the particle that it takes to complete one mapping of the particle.
<PCloud>.materialSource Integer default: 0

Updates the material carried by the particle system, using the source specified: Icon (The particles use the material currently assigned to the particle system icon.) Instanced Geometry (The particles use the material assigned to the instanced geometry.) -- Rotation and Collision
<PCloud>.Spin_Time animatable <PCloud>.Spin_Time_Variation animatable, percentage Time default: 0f --

The number of frames for one rotation of a particle. If set to 0, no rotation takes place.
Float default: 0.0 --

The percent of variation of the Spin Time.

<PCloud>.Spin_Phase animatable, angle Float default: 0.0 --

The initial particle rotation, in degrees.

<PCloud>.Spin_Phase_Variation animatable, percentage Float default: 0.0 --

The percent of variation of the Phase.

<PCloud>.spinAxisType Integer default: 0

The spin axis for the particles:

928

Chapter 11

3ds max Objects

Random (The spin axis for each of the particles is random.) Direction of Travel/Mblur (Rotates the particles about a vector formed by the direction in which theyre moving.) User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.)
<PCloud>.Blur_Stretch animatable Integer default: 0 --

When greater than 0, the particles stretch along the travel axis, depending on their speed. Specifically, the Stretch value specifies the percent of their length per each unit of the Speed setting (in the Particle Motion group). Thus, if you set Stretch to 2 while Speed is set at 10, the particles are stretched 20 percent longer than their original size along the axis of their travel. This value is only available when you choose Direction of Travel/Mblur.
<PCloud>.X_Spin_Vector animatable Float default: 1.0 --

Spin vector of the X-axis.

<PCloud>.Y_Spin_Vector animatable Float default: 0.0 --

Spin vector of the Y-axis.

<PCloud>.Z_Spin_Vector animatable Float default: 0.0 --

Spin vector of the Z-axis.

<PCloud>.Spin_Axis_Variation animatable, angle Float default: 0.0 --

The amount, in degrees, by which the spin axis of each particle may vary from the specified X Axis, Y Axis, and Z Axis settings.
<PCloud>.Interparticle_Collisions_On Integer default: 0

Turn on/off interparticle collisions: Off On

<PCloud>.Interparticle_Collision_Steps Integer default: 2

The number of intervals per rendering interval, during which an inter-particle collision test is conducted. The higher the value, the more accurate the simulation, but the slower the simulation will run.
<PCloud>.Interparticle_Collision_Bounce animatable, percentage <PCloud>.Interparticle_Collision_Bounce_Variation animatable, percentage Float default: 100.0 --

The degree to which speed is recovered after a collision.

Float default: 0.0 --

The percentage of random variation of the Bounce value, applied to the particles.

PCloud : GeometryClass

929

-- Object Motion Inheritance

<PCloud>.motionInfluence animatable, alias: Object_Motion_Inheritance Float default: 100.0 --

The percent of particles that inherit the motion of the object-based emitter at the moment of particle formation.
<PCloud>.motionMultiplier animatable, alias: Object_Motion_Multiplier Float default: 1.0 --

Modifies the amount by which the emitter motion affects the particle motion. This can be a positive or negative number.
<PCloud>.motionVariation Float default: 0.0 animatable, percentage; alias: Object_Motion_Multiplier_Variation --

Percentage of variation of the Multiplier value. -- Bubble Motion

<PCloud>.Bubble_Amplitude animatable <PCloud>.Bubble_Amplitude_Variation animatable, percentage <PCloud>.Bubble_Period animatable Float default: 0.0 --

The distance the particle moves off its usual velocity vector as it travels.
Float default: 0.0 --

The percent of Amplitude variation applied to each particle.

Time default: 100000f --

The cycle time for one complete oscillation of a particle through the bubble wave. A recommended value might be 20-30 intervals.
<PCloud>.Bubble_Period_Variation animatable, percentage Float default: 0.0 --

The percent of Period variation for each particle.

<PCloud>.Bubble_Phase animatable, angle <PCloud>.Bubble_Phase_Variation animatable, percentage Float default: 0.0 --

The initial displacement of the bubble pattern along the vector.

Float default: 0.0 --

The percent of Phase variation for each particle. -- Particle Spawn

<PCloud>.spawnType Integer default: 0

Determines what happens to particles at either collision or death: None (Particles act as they normally would. That is, upon collision, they either bounce or stick, depending on Particle Bounce settings in the deflector, and on death they disappear.) Die After Collision (Particles disappear when they strike a deflector to which theyre bound, such as the SDeflector.)

930

Chapter 11

3ds max Objects

Spawn on Collision (Spawn effects take place upon collision with a bound deflector.) Spawn on Death (Spawn effects take place at the end of each particles life.) Spawn Trails (Particles are spawned from existing particles at each frame of that particles life.)
<PCloud>.Die__X_frames_after_collision animatable Time default: 0f --

The life, in frames, that the particle will persist after the collision. Setting this to 0 (the default) causes particles to vanish immediately after the collision.
<PCloud>.Die__X_frames_after_collision_variation animatable, percentage Float default: 0.0 --

Varies the Persist value of each particle, when Persist is greater than 0. This lets you feather the dying off of the particle density.
<PCloud>.Spawn_Generations Integer default: 1

The number of spawns beyond the original particle generation. For example, if this is set to 1, and youre spawning at death, one spawning will occur beyond the original lifespan of each particle.
<PCloud>.Spawn_Multiplier <PCloud>.Spawn_Direction_Chaos animatable, percentage Integer Float default: 1 default: 0.0 --

Multiplies the number of particles spawned at each spawning event.

The amount by which the direction of the spawned particle can vary from the direction of the parent particle. A setting of 0 means no variance. A setting of 100 causes the spawned particle to travel in any random direction. A setting of 50 causes the spawned particle to deviate from its parents path by up to 90 degrees.
<PCloud>.Spawn_Speed_Chaos animatable Float default: 0.0 --

Random percentage range of scaling of the spawned particles relative to their parents, and dependent on the options below.
<PCloud>.spawnSpeedType Integer default: 0

Sets the type of speed applied to spawn particles: Slow (Applies the .spawn_Speed_Chaos value randomly to slow the speed of the spawned particles.) Fast (Randomly speeds up particles based on the .spawn_Speed_Chaos value.) Both (Some particles speed up, while others slow down, based on the .spawn_Speed_Chaos value.)
<PCloud>.spawnInheritVelocity Boolean default: false

When on, spawned particles inherit the speed of their parents, in addition to the effect of the .spawn_Speed_Chaos value.
<PCloud>.spawnSpeedFixed Boolean default: false

When on, uses the .spawn_Speed_Chaos value as a set value, rather than as a range applied randomly to each particle.

Snow : GeometryClass

931

<PCloud>.Spawn_Scale_Chaos animatable

Float

default: 0.0

--

The range of a percentage of change in the speed of the spawned particle relative to its parent. A value of 0 means no change.
<PCloud>.spawnScaleType Integer default: 0

The type of speed scaling for the spawned particles: Slow (Applies the speed factor randomly to slow the speed of the spawned particles.) Fast (Randomly speeds up particles based on the speed factor.) Both (Some particles speed up, while others slow down, based on the speed factor.)
<PCloud>.spawnScaleFixed Boolean default: false

When on, uses the .spawn_Scale_Chaos value as a set value, rather than as a range applied randomly to each particle.
<PCloud>.lifespanValueQueue Array default: #()

lifespanValueQueue is an array of integers which correspond to lifespan values for each spawned generation of particles.
<PCloud>.Spawn_Lifespan Integer Array default: 0 default: #()

Value that sets initial lifespan of spawned particles.

<PCloud>.objectMutationQueue

objectMutationQueue is an array of nodes which correspond to instanced-object particle types. Each generation of spawning will use the next node as its object type.

See also
Particle System Common Properties, Operators, and Methods (p. 905) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Snow : GeometryClass
Constructor:
snow ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Snow>.viewportcount <Snow>.rendercount <Snow>.flakesize Integer Integer Float default: 100 default: 100 default: 2.0 -- animatable, alias: Flake_Size

Maximum number of particles displayed in viewports at any given frame. Maximum number of particles that can appear in a single frame when you render it. Size of a particle in the active units.

932

Chapter 11

3ds max Objects

<Snow>.speed

Float

default: 10.0

-- animatable

Initial velocity of each particle as it leaves the emitter. Particles travel at this speed unless they are affected by a particle system space warp.
<Snow>.variation Float default: 2.0 -- animatable

Varies the initial speed and direction of particles. The greater the Variation, the broader the area of snowfall.
<Snow>.tumble Float default: 0.0 -- animatable

Amount of random rotation for snowflake particles. This parameter can range from 0 to 1. At 0, flakes do not rotate; at 1, they rotate the most. The axis of rotation is generated randomly for each particle.
<Snow>.tumblescale Tumble_Rate <Snow>.display Float default: 1.0 -- animatable, alias:

Speed at which snowflakes rotate. The greater the Tumble Rate, the faster the rotation.
Integer default: 0

Set how particles are displayed in viewports: Flakes (star-shaped snowflakes) Dots Ticks
<Snow>.render Integer default: 0

Set how particles are rendered: Six Point (Each particle is rendered as a six-pointed star. Each side of the star is a face to which you can assign a material.) Triangle (Each particle is rendered as a triangle. Only one side of the triangle is a face to which you can assign a material.) Facing (Particles are rendered as square faces whose width and height equal Flake Size. Facing particles are provided especially for use with material maps.)
<Snow>.start <Snow>.lifetime <Snow>.birthrate Time Time Time default: 0f default: 30f default: 0f -- alias: starttime -- alias: life -- animatable, alias: Birth_Rate

Number of the first frame where particles appear. The lifetime of a particle, in number of frames. The number of new particles born per frame. If this is less than or equal to the maximum sustainable rate, the particle system generates an even flow of particles. If it is greater than the maximum rate, the particle system generates particles in bursts.
<Snow>.constant Boolean default: true

When on, Birth Rate is unavailable and the birth rate used equals the maximum sustainable rate. When off, Birth Rate is available. Turning Constant off does not mean that the birth rate varies automatically; the birth rate remains constant unless you animate the Birth Rate parameter.
<Snow>.emitterwidth Float default: 25.0 -- animatable, alias: width

The width of the emitter.

Spray : GeometryClass

933

<Snow>.emitterheight <Snow>.hideemitter

Float Boolean

default: 25.0 default: false

-- animatable, alias: length

The height of the emitter. When on, the emitter is hidden in the viewports. Note: The emitter is never rendered.

See also
Particle System Common Properties, Operators, and Methods (p. 905) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Spray : GeometryClass
Constructor:
spray

Note: This class is not available in 3D Studio VIZ. Properties:

<Spray>.viewportcount <Spray>.rendercount <Spray>.dropsize <Spray>.speed Integer Integer Float Float default: 100 default: 100 default: 2.0 default: 10.0 -- animatable, alias: Drop_Size -- animatable

Maximum number of particles displayed in viewports at any given frame. Maximum number of particles that can appear in a single frame when you render it. Size of a particle in the active units. Initial velocity of each particle as it leaves the emitter. Particles travel at this speed unless they are affected by a particle system space warp.
<Spray>.variation Float default: 2.0 -- animatable

Varies the initial speed and direction of particles. The greater the Variation, the broader the area of snowfall.
<Spray>.display Integer default: 0

Set how particles are displayed in viewports: Drops (streaks) Dots Ticks

934

Chapter 11

3ds max Objects

<Spray>.render

Integer

default: 0

Set how particles are rendered: Tetrahedron (Particles are rendered as long tetrahedrons, with the length you specify in the Drop Size parameter. Tetrahedron is the default setting for rendering. It provides a basic simulation of water drops.) Facing (Particles are rendered as square faces whose width and height equal Drop Size. Facing particles are provided especially for use with material maps.)
<Spray>.start <Spray>.lifetime <Spray>.birthrate Birth_Rate Time Time Time default: 0f default: 30f default: 0f -- alias: starttime -- animatable, alias: life -- animatable, alias:

Number of the first frame where particles appear. The lifetime of a particle, in number of frames.

The number of new particles born per frame. If this is less than or equal to the maximum sustainable rate, the particle system generates an even flow of particles. If it is greater than the maximum rate, the particle system generates particles in bursts.
<Spray>.constant Boolean default: true

When on, Birth Rate is unavailable and the birth rate used equals the maximum sustainable rate. When off, Birth Rate is available. Turning Constant off does not mean that the birth rate varies automatically; the birth rate remains constant unless you animate the Birth Rate parameter.
<Spray>.emitterheight <Spray>.emitterwidth Float Float Boolean default: 25.0 default: 25.0 default: false -- animatable, alias: length -- animatable, alias: width

The height of the emitter. The width of the emitter.

<Spray>.hideemitter

When on, the emitter is hidden in the viewports. Note: The emitter is never rendered.

See also
Particle System Common Properties, Operators, and Methods (p. 905) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

SuperSpray : GeometryClass

935

SuperSpray : GeometryClass
Constructor:
superSpray ...

Note: This class is not available in 3D Studio VIZ. Properties: -- Basic Parameters
<SuperSpray>.Off_Axis animatable, angle <SuperSpray>.Axis_Spread animatable, angle Float default: 0.0 --

Affects the angle of the particle stream off the Z axis (along the plane of the X axis).
Float default: 0.0 --

Affects the spread of the particles away from the emission vector (along the plane of the X axis).
<SuperSpray>.Off_Plane animatable, angle <SuperSpray>.Plane_Spread animatable, angle Float default: 0.0 --

Affects the angle of emission about the Z axis. This has no effect if Off_Axis is set to 0.
Float default: 0.0 --

Affects the spread of the particles about the Off_Plane axis. This has no effect if Off_Axis is set to 0.
<SuperSpray>.iconsize alias: Emitter_Width Float default: 20.0 --

Size of the emitter icon.

<SuperSpray>.iconHidden Boolean default: false

When on, hides the emitter in viewports. When off, the emitter is displayed in viewports. The emitter is never rendered.
<SuperSpray>.viewType Integer default: 0

Set the display icon for particles in the viewport: Dots (Displays the particles as dots.) Ticks (Displays the particles as crosses.) Mesh (Displays the particles as mesh objects. This results in slower viewport redraws.) Bbox (For instanced geometry only, this displays each instanced particle, whether a single object, a hierarchy, or a group, as a bounding box.)
<SuperSpray>.viewPercent percentage, alias: Percentage_Displayed Float default: 10.0 --

The percentage of particles displayed in the viewport.

936

Chapter 11

3ds max Objects

-- Particle Generation
<SuperSpray>.quantityMethod Integer default: 0

Set the method by which the number of particles is determined over time: Use Rate (Specifies a fixed number of particles emitted per frame.) Use Total (Specifies a total number of particles formed over the life of the system.) Tip: Generally, Use Rate is best for a continuous flow of particles, like a trail of pixie dust, while Use Total is better for bursts of particles over a short period of time.
<SuperSpray>.Birth_Rate animatable Integer default: 10 --

The number of particles emitted per frame.

<SuperSpray>.Total_Number Integer Float default: 100 default: 10.0 --

The total number of particles to be emitted.

<SuperSpray>.speed animatable <SuperSpray>.Speed_Variation animatable, percentage <SuperSpray>.Emitter_Start

The velocity of the particle at birth, along the normal, in units traveled per frame.
Float default: 0.0 --

Percentage of variation to the speed of emission for each particle.

Time Time Time Time default: 0f default: 30f default: 100f default: 30f --

The frame at which particles begin to exist in the scene.

<SuperSpray>.Emitter_Stop

The last frame at which particles are emitted.

<SuperSpray>.Display_Until <SuperSpray>.life animatable

Time at which all particles will disappear, regardless of other settings.

The lifespan of each particle from the time of creation.

<SuperSpray>.Life_Variation animatable <SuperSpray>.subsampleCreationTime Time default: 0f --

The number of frames by which the life of each particle can vary from the norm.
Boolean default: false

When on, enables the addition of a time offset to the equations of motion that prevents puffing in time.
<SuperSpray>.subsampleEmitterTranslation Boolean default: true

If the object-based emitter is moving in space, particles are created at integral times at positions along the geometrys path between renderable positions. This prevents puffing in space.
<SuperSpray>.subsampleEmitterRotation <SuperSpray>.size animatable Boolean Float default: true default: 1.0 --

If the emitter is rotating, turn this on to avoid puffing and produce smooth spiral effects.

The target size for all particles in the system.

SuperSpray : GeometryClass

937

<SuperSpray>.Size_Variation animatable, percentage <SuperSpray>.Growth_Time

Float

default: 0.0

--

The percentage by which the size of each particle may vary from the norm.
Time default: 10f

The number of intervals over which the particle grows from being very small (0.1a system constant) to the Size value.
<SuperSpray>.Fade_Time Time default: 10f

The number of intervals over which the particle will shrink to 1/10th its Size setting prior to its death.
<SuperSpray>.seed alias: Random_Seed Integer default: 0 --

By changing the Seed value, you achieve different results using otherwise identical particle settings. -- Particle Type
<SuperSpray>.particleType Integer default: 0

The type of particle emitted: Standard Particle (Uses one of several standard particle types, such as triangle, cube, tetra, and so on.) MetaParticles (Uses Metaball particles. These are particle systems in which the individual particles blend together in blobs or streams.) Instanced Geometry (Generates particles that are instances of either an object, a linked hierarchy of objects, or a group.)
<SuperSpray>.standardParticle Integer default: 0

Set the type of particle used when standard particles is selected: Triangle (Renders each particle as a triangle. Use Triangle particles with noise opacity for steam or smoke.) Cube (Renders each particle as a cube.) Special (Each particle consists of three intersecting 2D squares. These are effective when you use a face-map material, optionally along with an opacity map, to create the effect of a three-dimensional particle.) Facing (Renders each particle as a square that always faces the view. Use with an appropriate opacity map for bubbles or snowflakes.) Constant (Provides a particle that remains the same size, in pixels, specified by the size value. This size never changes, regardless of its distance from the camera. Note that this particle type can only be displayed in the viewports as a dot or a tick. If you turn on this option while Mesh is selected, the viewport display is automatically switched to Ticks.)

938

Chapter 11

3ds max Objects

Tetra (Renders each particle as a mapped tetrahedron, whose tail points toward the normal vector of the emission, and whose head points away. Use Tetra particles for raindrops or sparks.) SixPoint (Renders each particle as a six-pointed, two-dimensional star.) Sphere (Renders each particle as a sphere.)
<SuperSpray>.Metaparticle_Tension animatable Float default: 1.0 --

Determines the tightness of the particles, with regard to their tendency to blend with other particles. The higher the Tension, the harder the blobs, and the harder it is for them to merge.
<SuperSpray>.Metaparticle_Tension_Variation animatable, percentage Float default: 0.0 --

The percent of variation of the Tension effect.

<SuperSpray>.metaballRenderCoarsness alias: Metaparticle_Coarseness Float default: 0.5 --

The coarseness for metaparticles in the rendered scene.

<SuperSpray>.metaballViewCoarsness Float Boolean default: 1.0 default: true

The coarseness for the viewport display.

<SuperSpray>.metaballAutoCoarsness

When this is on, the rendering coarseness is automatically set, based on the size of the particles, and the viewport coarseness is set to about twice that of the rendering coarseness.
<SuperSpray>.instancingObject Node Boolean default: undefined default: false

The object which is instanced.

<SuperSpray>.instanceSubTree

Turn this on when you want to include the linked children of the picked object in the particle. If the picked object is a group, all children of the group are included.
<SuperSpray>.instanceKeyOffsetType Integer default: 0

Set the animation offset keying: None (Each particle duplicates the timing of the original object. As a result, the animation of all particles will be identically timed.) Birth (The firstborn particle is an instance of the current animation of the source object at the moment of that particles birth. Each subsequent particle then use the same start time for the animation.) Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each particle is born using the same animation as the source object at the time of birth, but with a random offset of frames, based on the .instanceFrameOffset value.)
<SuperSpray>.instanceFrameOffset alias: Animation_Offset_Amount Integer default: 0 --

The property value is the UI value times the number of ticks per frame. The number of ticks per frame is accessible via the ticksPerFrame system global variable.

SuperSpray : GeometryClass

939

<SuperSpray>.mappingType

Integer

default: 0

Specifies how a mapped material affects the particles: Time (Maps particles over time.) Distance (Maps particles over a distance.)
<SuperSpray>.Mapping_Time_Base animatable Time default: 30f --

The number of frames from the birth of the particle that it takes to complete one mapping of the particle.
<SuperSpray>.Mapping_Distance_Base animatable Float default: 100.0 --

The distance, in units, from the birth of the particle that it takes to complete one mapping of the particle. -- Rotation and Collision
<SuperSpray>.Spin_Time animatable <SuperSpray>.Spin_Time_Variation animatable, percentage Time default: 30f --

The number of frames for one rotation of a particle. If set to 0, no rotation takes place.
Float default: 0.0 --

The percent of variation of the Spin Time.

<SuperSpray>.Spin_Phase animatable, angle Float default: 0.0 --

The initial particle rotation, in degrees.

<SuperSpray>.Spin_Phase_Variation animatable, percentage Float default: 0.0 --

The percent of variation of the Phase.

<SuperSpray>.spinAxisType Integer default: 0

The spin axis for the particles: Random (The spin axis for each of the particles is random.) Direction of Travel/Mblur (Rotates the particles about a vector formed by the direction in which theyre moving.) User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.)
<SuperSpray>.Blur_Stretch animatable Integer default: 0 --

When greater than 0, the particles stretch along the travel axis, depending on their speed. Specifically, the Stretch value specifies the percent of their length per each unit of the Speed setting (in the Particle Motion group). Thus, if you set Stretch to 2 while Speed is set at 10, the particles are stretched 20 percent longer than their original size along the axis of their travel. This value is only available when you choose Direction of Travel/Mblur.
<SuperSpray>.X_Spin_Vector animatable Float default: 1.0 --

Spin vector of the X-axis.

940

Chapter 11

3ds max Objects

<SuperSpray>.Y_Spin_Vector animatable

Float

default: 0.0

--

Spin vector of the Y-axis.

<SuperSpray>.Z_Spin_Vector animatable Float default: 0.0 --

Spin vector of the Z-axis.

<SuperSpray>.Spin_Axis_Variation animatable, angle Float default: 0.0 --

The amount, in degrees, by which the spin axis of each particle may vary from the specified X Axis, Y Axis, and Z Axis settings.
<SuperSpray>.Interparticle_Collisions_On Integer default: 0

Turn on/off interparticle collisions: OFF ON

<SuperSpray>.Interparticle_Collision_Steps Integer default: 2

The number of intervals per rendering interval, during which an inter-particle collision test is conducted. The higher the value, the more accurate the simulation, but the slower the simulation will run.
<SuperSpray>.Interparticle_Collision_Bounce animatable, percentage Float default: 100.0 --

The degree to which speed is recovered after a collision.

<SuperSpray>.Interparticle_Collision_Bounce_Variation animatable, percentage Float default: 0.0 --

The percentage of random variation of the Bounce value, applied to the particles. -- Object Motion Inheritance
<SuperSpray>.motionInfluence animatable, alias: Object_Motion_Inheritance Float default: 100.0 --

The percent of particles that inherit the motion of the object-based emitter at the moment of particle formation.
<SuperSpray>.motionMultiplier animatable, alias: Object_Motion_Multiplier Float default: 1.0 --

Modifies the amount by which the emitter motion affects the particle motion. This can be a positive or negative number.
<SuperSpray>.motionVariation Float default: 0.0 animatable, percentage; alias: Object_Motion_Multiplier_Variation --

Percentage of variation of the Multiplier value. -- Bubble Motion

<SuperSpray>.Bubble_Amplitude animatable <SuperSpray>.Bubble_Amplitude_Variation animatable, percentage Float default: 0.0 --

The distance the particle moves off its usual velocity vector as it travels.
Float default: 0.0 --

The percent of Amplitude variation applied to each particle.

SuperSpray : GeometryClass

941

<SuperSpray>.Bubble_Period - animatable

Time

default: 100000f -

The cycle time for one complete oscillation of a particle through the bubble wave. A recommended value might be 20-30 intervals.
<SuperSpray>.Bubble_Period_Variation animatable, percentage Float default: 0.0 --

The percent of Period variation for each particle.

<SuperSpray>.Bubble_Phase animatable, angle <SuperSpray>.Bubble_Phase_Variation animatable, percentage Float default: 0.0 --

The initial displacement of the bubble pattern along the vector.

Float default: 0.0 --

The percent of Phase variation for each particle. -- Particle Spawn

<SuperSpray>.spawnType Integer default: 0

Determines what happens to particles at either collision or death: None (Particles act as they normally would. That is, upon collision, they either bounce or stick, depending on Particle Bounce settings in the deflector, and on death they disappear.) Die After Collision (Particles disappear when they strike a deflector to which theyre bound, such as the SDeflector.) Spawn on Collision (Spawn effects take place upon collision with a bound deflector.) Spawn on Death (Spawn effects take place at the end of each particles life.) Spawn Trails (Particles are spawned from existing particles at each frame of that particles life.)
<SuperSpray>.Die__X_frames_after_collision animatable Time default: 0f --

The life, in frames, that the particle will persist after the collision. Setting this to 0 (the default) causes particles to vanish immediately after the collision.
<SuperSpray>.Die__X_frames_after_collision_variation animatable, percentage Float default: 0.0 --

Varies the Persist value of each particle, when Persist is greater than 0. This lets you feather the dying off of the particle density.
<SuperSpray>.Spawn_Affects Integer default: 100

The percentage of particles that will spawn. Reducing this reduces the number of particles that produce spawned particles.
<SuperSpray>.Spawn_Multiplier_Variation percentage Float default: 0.0 --

Percentage range by which the Multiplier value will vary, frame by frame.

942

Chapter 11

3ds max Objects

<SuperSpray>.Spawn_Direction_Chaos animatable, percentage

Float

default: 0.0

--

The amount by which the direction of the spawned particle can vary from the direction of the parent particle. A setting of 0 means no variance. A setting of 100 causes the spawned particle to travel in any random direction. A setting of 50 causes the spawned particle to deviate from its parents path by up to 90 degrees.
<SuperSpray>.Spawn_Speed_Chaos animatable Float default: 0.0 --

Random percentage range of scaling of the spawned particles relative to their parents, and dependent on the options below.
<SuperSpray>.spawnSpeedType Integer default: 0

Sets the type of speed applied to spawn particles: Slow (Applies the .spawn_Speed_Chaos value randomly to slow the speed of the spawned particles.) Fast (Randomly speeds up particles based on the .spawn_Speed_Chaos value.) Both (Some particles speed up, while others slow down, based on the .spawn_Speed_Chaos value.)
<SuperSpray>.spawnInheritVelocity Boolean default: false

When on, spawned particles inherit the speed of their parents, in addition to the effect of the .spawn_Speed_Chaos value.
<SuperSpray>.spawnSpeedFixed Boolean default: false

When on, uses the .spawn_Speed_Chaos value as a set value, rather than as a range applied randomly to each particle.
<SuperSpray>.Spawn_Scale_Chaos animatable Float default: 0.0 --

The range of a percentage of change in the speed of the spawned particle relative to its parent. A value of 0 means no change.
<SuperSpray>.spawnScaleType Integer default: 0

The type of speed scaling for the spawned particles: Slow (Applies the speed factor randomly to slow the speed of the spawned particles.) Fast (Randomly speeds up particles based on the speed factor.) Both (Some particles speed up, while others slow down, based on the speed factor.)
<SuperSpray>.spawnScaleFixed Boolean default: false

When on, uses the .spawn_Scale_Chaos value as a set value, rather than as a range applied randomly to each particle.
<SuperSpray>.lifespanValueQueue Array default: #()

lifespanValueQueue is an array of integers which correspond to lifespan values for each spawned generation of particles.
<SuperSpray>.objectMutationQueue Array default: #()

objectMutationQueue is an array of nodes which correspond to instanced-object particle types. Each generation of spawning will use the next node as its object type.

NURBSSurf : GeometryClass

943

See also
Particle System Common Properties, Operators, and Methods (p. 905) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Geometry - NURBS Objects

The following list displays the NURBS objects: NURBSSurf (p. 943) Point_Surf (p. 943)

NURBSSurf : GeometryClass
NURBSSurfs are NURBS surface objects defined by CVs (control vertices). All NURBS objects are created through the special NURBS descriptor classes (see Working with NURBS (p. 1384)) and the NURBSSurf class is used typically in object class testing with the classOf() function. Scene objects created as NURBSSurf objects in the 3ds max user interface have the class NURBSSurf. Constructor:
NURBSNode <nurbs_set> ...

See Creating New NURBS Objects (p. 1389) for details. Properties: Properties for NURBSSurf objects are accessed through a NURBSSet descriptor object. See Working with NURBS (p. 1384) for more details.

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

Point_Surf : GeometryClass
Point_Surfs are NURBS surface objects defined by interpolated points. All NURBS objects are created through the special NURBS descriptor classes (see Working with NURBS (p. 1384)) and the Point_Surf class is used typically in object class testing with the classOf() function. Scene objects created as Point Surface objects in the 3ds max user interface have the class Point_Surf. Constructor:
NURBSNode <nurbs_set> ...

See Creating New NURBS Objects (p. 1389) for details.

944

Chapter 11

3ds max Objects

Properties:
<Point_Surf>.thickness <Point_Surf>.sides <Point_Surf>.angle Float Integer Float default: 1.0 default: 12 default: 0.0 ---animatable animatable

Rendered thickness of the surface. Rendered sides of the surface.

animatable

The rotational position of the cross-section in the renderer. Other properties for Point Surfaces are accessed through a NURBSSet descriptor object. See Working with NURBS (p. 1384) for more details.

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

Shape : Node
The following list shows the 3ds max shape class objects: --Splines Arc (p. 949) Circle (p. 950) Donut (p. 951) Ellipse (p. 953) Helix (p. 954) Line (p. 955) NGon (p. 957) Rectangle (p. 958) Section (p. 959) Star (p. 960) Text (p. 962) --NURBS Curves CV_Curve (p. 964) Point_Curve (p. 965)

Shape Common Properties, Operators, and Methods

945

Shape Common Properties, Operators, and Methods

General Methods:
numKnots <shape> [ <spline_index_integer> ]

Returns the number of knots (also known vertices or control points) in the indexed spline as an integer. If the spline index is not specified, returns the number of knots in the entire shape. for example:
y = donut() numKnots y

Interpolation Methods There are a number of interpolation functions that operate on shape scene objects. They provide capabilities such as stepping along a curve within a shape getting coordinates on the curve, getting curve lengths or determining the closest point on a curve to a given coordinate. These are useful for placing cloned objects along a curve or keeping a set of objects in formation near a spine curve as it animates, etc. The interpolators all take a shape scene object (for example, a line), an optional curve number in case there are several curves in the shape, defaulting to 1, and a parameter in the range 0.0 to 1.0, that specifies a spot on the curve as a proportion along its length. There are two types of interpolator provided: One interpolator matches the 3ds max Path controller in which the percentage along the path is not uniform, but weighted by the vertex spacing. This simple interpolation is interpolating based on parameter space. If a spline has 4 segments, the first segment is parameter values 00.25, the second 0.25-0.5, the third 0.5-0.75 and the fourth 0.75-1.0. This is regardless of the length of each segment. Another interpolator that gives you a uniform interpolation along the length of the curve. This interpolation normalizes the parameter space to distance along the length of a spline. So parameter space 0 is the start, 1.0 is the end and 0.5 is halfway along the actual length of the curve.

The non-uniform Path interpolator in 3ds max gives rise to the varying velocity of a path-animated object when the path has unevenly spaced control points. The arc-length interpolators provided here give a uniform placing along the curve no matter how uneven the control point placement. The advantage of the Path interpolator is that it is computationally much more efficient than a uniform arc-length interpolator. The length interpolator uses some caches to speed it up, but you have to help manage them in the way described below. The optional steps: keyword argument for the methods listed below lets you specify the integration steps. The default steps value is 5 times the curves 3ds max unit length, which usually is more than enough. For example, if a curve has a length of 100 3ds max units, the default step size would be 500. The interpolation algorithm has an accuracy of no better than + or - (1/steps) 3ds max units. These methods employ a cache to speed up their operation in the common case where you step

946

Chapter 11

3ds max Objects

gradually along a single curve. The cache remembers the state for the last point on the curve and picks up there if you call again on the same curve at the same animation time. This can exponentially speed up interpolation processing. However, MAXScript does not have a way of knowing if youve edited the curve from one call to the next, so you have to be sure to reset the cache with the resetLengthInterp() method if the user can edit the curve between calls in your code. All coordinates are in the current coordinate system.
pathInterp <shape> [ <curve_num> ] <parameter>

Return a point3 coordinate on the numbered curve (defaults to 1) corresponding to the parameter value (0.0 to 1.0) that matches the 3ds max Path controller percentage (vertexbased) interpolation.
lengthInterp <shape> [ <curve_num> ] <parameter> [ steps:<integer> ]

Return a point3 coordinate on the numbered curve (defaults to 1) corresponding to the parameter value (0.0 to 1.0) that is that fraction along the curves total length.
resetLengthInterp()

Clear length interpolation cache. Use this if the curve you are length-interpolating along might have been edited between calls.
curveLength <shape> [ <curve_num> ]

Return the arc length of the numbered curve. This length does not reflect any transform level scaling performed on the shape.
pathTangent <shape> [ <curve_num> ] <parameter>

Return the tangent direction vector at the 3ds max Path (vertex-based) interpolated point along the specified curve. You can use this function, for example, to set an objects direction to follow the curve.
lengthTangent <shape> [ <curve_num> ] <parameter> [ steps:<integer> ]

Return the tangent direction vector at the arc-length-interpolated point along the specified curve. You can use this function to set an objects direction to follow the curve.
nearestPathParam <shape> [ <curve_num> ] <point3> [ steps:<integer> ]

Return the interpolation parameter value (0.0 to 1.0) corresponding to the point along the curve that is closest to the given <point3> coordinate. The parameter is given as a 3ds max Path (vertex-based) interpolation parameter value. You can then use pathInterp with this value to find the nearest points coordinates, or use one of the following functions for converting between arc-length parameters and 3ds max Path percentage parameters.
pathToLengthParam <shape> [ <curve_num> ] <parameter> [ steps:<integer> ]

Return the uniform arc-length length parameter corresponding to the given 3ds max Path (vertex-based) parameter for this curve.
lengthToPathParam <shape> [ <curve_num> ] <parameter> [ steps:<integer> ]

Return the 3ds max Path (vertex-based) parameter corresponding to the given uniform arclength parameter for this curve.

Spline Shape Common Properties, Operators, and Methods

947

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

Shapes - Splines
The following list shows the 3ds max spline shape class objects: Arc (p. 949) Circle (p. 950) Donut (p. 951) Ellipse (p. 953) Helix (p. 954) Line (p. 955) NGon (p. 957) Rectangle (p. 958) Section (p. 959) Star (p. 960)

Spline Shape Common Properties, Operators, and Methods

The following properties methods apply to all spline shape objects. Properties:
<spline>.renderable <spline>.thickness <spline>.mapCoords Boolean Float Boolean default: false default: 1.0 default: false

When on, the shape is rendered using a 12-sided circle as a cross section. The diameter of the rendered spline. When on, applies mapping coordinates. The U coordinate is wrapped once around the thickness of the spline, while the V coordinate is mapped once along the length of the spline. Tiling is achieved via the tiling parameters of the material. Note: Since renderable is a property for all nodes, a name conflict exists between the renderable property for nodes and the renderable property for splines. MAXScript handles the conflict for this property differently than for all other cases where an object class property name conflicts with a node level property name. Normally, you would access the node level property as a property of the node, and the object property as a property of the baseobject property of the node. The renderable property however is always applied to the spline objects renderable property rather than the nodes renderable property.

948

Chapter 11

3ds max Objects

So, looking in the Object Properties dialog, $.renderable=false turns off renderable at the node level. To turn off the splines renderable property, you need to say $.baseobject.renderable=false. Methods: The following methods are defined for 3D Studio VIZ.
applyOffset <spline_shape_node> <offset_float>

For each spline in the shape, makes a copy of the spline, offset on all sides to the distance in units specified by offset_float. If a spline is open, the resulting spline and its outline will make a single closed spline. Negative offset_float values create an offset spline to the left of the spline (as the spline is drawn from its start to its finish). The spline_shape_node is converted to a SplineShape (Editable Spline) if it is not already a SplineShape.
measureOffset <spline_shape_node> <point3>

Returns a Float value whose absolute value is the distance from point3 to the closest point on a spline in the shape. The sign of the value is positive if the point3 position is to the left of the spline (as the spline is drawn from its start to its finish). The value returned by this method can usually be used as the offset_float parameter in applyOffset() to have an offset spline pass through the point3 position. If the closest point on a spline in the shape is an endpoint of an open spline, the offset spline will not pass through the point3 position.
trimextend <fixed_node_array> <alterable_node_array> \ [trim: <boolean> ] [extend: <boolean>] [infinite: <boolean>] \ [project: #view | #3D | #grid]

If trim is true (the default), otherwise If extend is true (the default), otherwise If infinite is false (the default), , otherwise Project can be one of the following Name values: #view (the default) #3D #grid Broken. Document when working.

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

Arc : Shape

949

Arc : Shape
Constructor:
arc ...

Properties:
<Arc>.radius Float Float Float Boolean default: 25.0 default: 45.0 default: 135.0 default: false -- animatable -- animatable -- animatable

The arc radius.

<Arc>.from <Arc>.to <Arc>.pie

Location of the start point as an angle measured from the local positive X axis. Location of the end point as an angle measured from the local positive X axis. When on, creates a closed spline in the form of a pie. The start point and end point are connected to the center with straight segments.
<Arc>.reverseBooleandefault: false

When on, the direction of the arc spline is reversed, and the first vertex is placed at the opposite end of an open arc. As long as the shape remains an original shape (and not an editable spline), you can switch its direction by toggling reverse. Once the arc is converted to an editable spline, you can use Reverse at the Spline sub-object level to reverse direction.
<Arc>.steps <Arc>.optimize <Arc>.adaptive Integer Boolean Boolean default: 6 default: true default: false

Number of divisions between each vertex. When on, removes unneeded steps from straight segments in the spline. When on, sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.
<Arc>.angle <Arc>.thickness <Arc>.sides Float Float Float default: 0.0 default: 1.0 default: 12.0 ---animatable animatable animatable

The rotational position of the cross-section in the renderer. Diameter of the rendered spline. Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.
<Arc>.viewport_thickness Float default: 1.0 default: 12

Diameter of the viewport spline.

<Arc>.viewport_sides Integer

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.
<Arc>.viewport_angle Float default: 0.0

The rotational position of the cross-section in the viewports.

950

Chapter 11

3ds max Objects

<Arc>.DisplayRenderMesh <Arc>.UseViewportSettings

Boolean Boolean

default: false default: false default: true

When on, displays the mesh generated by the spline in the viewports. When on, displays the mesh generated by the Viewport settings.
<Arc>.DisplayRenderSettings <Arc>.renderableBoolean <Arc>.mapCoordsBoolean Boolean

When on, displays the mesh generated by the render settings.

default: true default: false

When on, the spline is displayed in the rendered scene. Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline. Note: The Reverse property is not accessible to MAXScript in 3ds max 4.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Circle : Shape
Constructor:
circle ...

Properties:
<Circle>.radius <Circle>.steps <Circle>.optimize <Circle>.adaptive Float Integer Boolean Boolean default: 25.0 default: 6 default: true default: false -- animatable

The radius of the circle. The number of divisions between each vertex. When on, removes unneeded steps from straight segments in the spline. When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.
<Circle>.angle <Circle>.thickness Float Float default: 0.0 default: 1.0 -animatable -animatable

The rotational position of the cross-section in the renderer. Diameter of the rendered spline.

Donut : Shape

951

<Circle>.sides

Float

default: 12.0

--

animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.
<Circle>.viewport_thickness Float default: 1.0 default: 12

Diameter of the viewport spline.

<Circle>.viewport_sides Integer

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.
<Circle>.viewport_angle <Circle>.DisplayRenderMesh <Circle>.UseViewportSettings <Circle>.DisplayRenderSettings <Circle>.renderableBoolean <Circle>.mapCoordsBoolean Float default: 0.0

The rotational position of the cross-section in the viewports.

Booleandefault: false Boolean Boolean default: false default: true

When on, displays the mesh generated by the spline in the viewports. When on, displays the mesh generated by the Viewport settings. When on, displays the mesh generated by the render settings.
default: true default: false

When on, the spline is displayed in the rendered scene. Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Donut : Shape
Constructor:
donut ...

Properties:
<Donut>.radius1 <Donut>.radius2 <Donut>.steps Float Float Integer default: 35.0 default: 25.0 default: 6 -- animatable -- animatable

Sets the radius of the first circle. Sets the radius of the second circle. The number of divisions between each vertex.

952

Chapter 11

3ds max Objects

<Donut>.optimize <Donut>.adaptive

Boolean Boolean

default: true default: false

When on, removes unneeded steps from straight segments in the spline When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.
<Donut>.angle <Donut>.thickness <Donut>.sides Float Float Float default: 0.0 default: 1.0 default: 12.0 ---animatable animatable animatable

The rotational position of the cross-section in the renderer. Diameter of the rendered spline. Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.
<Donut>.viewport_thickness <Donut>.viewport_sides Float Integer default: 1.0 default: 12

Diameter of the viewport spline. Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.
<Donut>.viewport_angle <Donut>.DisplayRenderMesh <Donut>.UseViewportSettings <Donut>.DisplayRenderSettings <Donut>.renderable Boolean Float default: 0.0

The rotational position of the cross-section in the viewports.

Boolean default: false Boolean Boolean default: false default: true

When on, displays the mesh generated by the spline in the viewports. When on, displays the mesh generated by the Viewport settings. When on, displays the mesh generated by the render settings.
default: true

When on, the spline is displayed in the rendered scene.

<Donut>.mapCoords Boolean default: false

Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Ellipse : Shape

953

Ellipse : Shape
Constructor:
ellipse ...

Properties:
<Ellipse>.length <Ellipse>.width <Ellipse>.steps <Ellipse>.optimize <Ellipse>.adaptive Float Float Integer Boolean Boolean default: 25.0 default: 35.0 default: 6 default: true default: false -- animatable -- animatable

The size of the Ellipse along the local Y axis. The size of the Ellipse local X axis. The number of divisions between each vertex. When on, removes unneeded steps from straight segments in the spline. When on, Adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.
<Ellipse>.angle <Ellipse>.thickness <Ellipse>.sides Float Float Float default: 0.0 default: 1.0 default: 12.0 ---animatable animatable animatable

The rotational position of the cross-section in the renderer. Diameter of the rendered spline. Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.
<Ellipse>.viewport_thickness Float default: 1.0 default: 12

Diameter of the viewport spline.

<Ellipse>.viewport_sides Integer

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.
<Ellipse>.viewport_angle <Ellipse>.DisplayRenderMesh <Ellipse>.UseViewportSettings <Ellipse>.DisplayRenderSettings <Ellipse>.renderableBoolean <Ellipse>.mapCoordsBoolean Float Boolean Boolean Boolean default: 0.0 default: false default: false default: true

The rotational position of the cross-section in the viewports. When on, displays the mesh generated by the spline in the viewports. When on, displays the mesh generated by the Viewport settings. When on, displays the mesh generated by the render settings.
default: true default: false

When on, the spline is displayed in the rendered scene. Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline.

954

Chapter 11

3ds max Objects

See also
Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Helix : Shape
Constructor:
helix ...

Properties:
<Helix>.radius1 <Helix>.radius2 <Helix>.height <Helix>.turns <Helix>.bias Float Float Float Float Float default: 35.0 -- animatable -- animatable

The radius for the Helix start.

default: 15.0 default: 25.0 default: 2.0 default: 0.0

The radius for the Helix end.

-- animatable -- animatable -- animatable

The height of the Helix. The number of turns the Helix makes between its start and end points. Forces the turns to accumulate at one end of the helix. A bias of -1.0 forces the turns towards the start of the helix, a bias of 0.0 evenly distributes the turns between the ends, and a bias of 1.0 forces the turns towards the end of the helix.
<Helix>.direction Integer default: 0

Set the direction the helix turns: Clockwise Counterclockwise

<Helix>.angle <Helix>.thickness <Helix>.sides Float Float Float default: 0.0 default: 1.0 default: 12.0 ---animatable animatable animatable

The rotational position of the cross-section in the renderer. Diameter of the rendered spline. Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.
<Helix>.viewport_thickness Float default: 1.0

Diameter of the viewport spline.

Line : Shape

955

<Helix>.viewport_sides

Integer

default: 12

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.
<Helix>.viewport_angle <Helix>.DisplayRenderMesh <Helix>.UseViewportSettings <Helix>.DisplayRenderSettings <Helix>.renderableBoolean <Helix>.mapCoordsBoolean Float Boolean Boolean Boolean default: 0.0 default: false default: false default: true

The rotational position of the cross-section in the viewports. When on, displays the mesh generated by the spline in the viewports. When on, displays the mesh generated by the Viewport settings. When on, displays the mesh generated by the render settings.
default: true default: false

When on, the spline is displayed in the rendered scene. Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Line : Shape
Constructor:
line ...

Properties:
<Line>.steps <Line>.optimize <Line>.adaptive Integer Boolean Boolean default: 6 default: true default: false

The number of divisions between each vertex. When on, removes unneeded steps from straight segments in the spline. When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.
<Line>.angle <Line>.thickness Float Float default: 0.0 default: 1.0 --animatable animatable

The rotational position of the cross-section in the renderer. Diameter of the rendered spline.

956

Chapter 11

3ds max Objects

<Line>.sides

Float

default: 12.0

--

animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.
<Line>.viewport_thickness Float default: 1.0 default: 12

Diameter of the viewport spline.

<Line>.viewport_sides Integer

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.
<Line>.viewport_angle <Line>.DisplayRenderMesh <Line>.UseViewportSettings <Line>.DisplayRenderSettings <Line>.renderableBoolean <Line>.mapCoordsBoolean Float Boolean Boolean Boolean default: 0.0 default: false default: false default: true

The rotational position of the cross-section in the viewports. When on, displays the mesh generated by the spline in the viewports. When on, displays the mesh generated by the Viewport settings. When on, displays the mesh generated by the render settings.
default: true default: false

When on, the spline is displayed in the rendered scene. Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline. Note: The Line shape is equivalent to a SplineShape shape. All the properties and methods associated with SplineShape are also valid on a Line shape. These properties and methods are described in the SplineShape : Shape (p. 1079) topic.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

NGon : Shape

957

NGon : Shape
Constructor:
ngon ...

Properties:
<NGon>.radius Float Integer default: 25.0 default: 0 -- animatable

The NGon radius.

<NGon>.scribe

Sets whether the NGon is: Circumscribed (Radius is measured from the center to the sides of the NGon) Inscribed (Radius is measured from the center to the corners of the NGon)
<NGon>.sides <NGon>.corner_Radius Integer Float default: 6 default: 0.0 -- animatable -- animatable

Number of sides and vertices used by the NGon. Degree of rounding to apply to the corners of the NGon. A setting of 0 specifies a standard unrounded corner.
<NGon>.circular <NGon>.steps <NGon>.optimize <NGon>.adaptive Boolean Integer Boolean Boolean default: true -- animatable

When on, specifies a circular NGon.

default: 6 default: true default: false

The number of divisions between each vertex. When on, removes unneeded steps from straight segments in the spline. When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.
<NGon>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

<NGon>.radiusFloat default: 1.0 -- animatable <NGon>.thickness Float default: 1.0 -- animatable

Radius of the rendered spline.

<NGon>.sides Float default: 12.0 -- animatable

Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.
<NGon>.viewport_thickness Float default: 1.0 default: 12

Diameter of the viewport spline.

<NGon>.viewport_sides Integer

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.
<NGon>.viewport_angle Float default: 0.0

The rotational position of the cross-section in the viewports.

958

Chapter 11

3ds max Objects

<NGon>.DisplayRenderMesh <NGon>.UseViewportSettings

Boolean Boolean

default: false default: false default: true

When on, displays the mesh generated by the spline in the viewports. When on, displays the mesh generated by the Viewport settings.
<NGon>.DisplayRenderSettings <NGon>.renderableBoolean <NGon>.mapCoordsBoolean Boolean

When on, displays the mesh generated by the render settings.

default: true default: false

When on, the spline is displayed in the rendered scene. Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Rectangle : Shape
Constructor:
rectangle ...

Properties:
<Rectangle>.length <Rectangle>.width <Rectangle>.Corner_Radius cornerRadius <Rectangle>.steps <Rectangle>.optimize <Rectangle>.adaptive Integer Boolean Boolean Float Float Float default: 10.0 default: 25.0 default: 0.0 -- animatable -- animatable -- animatable; alias:

The size of the rectangle along the local Y axis. The size of the rectangle along the local X axis.

Creates rounded corners. When set to 0, the rectangle contains 90-degree corners.
default: 6 default: true default: false

The number of divisions between each vertex. When on, removes unneeded steps from straight segments in the spline. When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.
<Rectangle>.angle Float default: 0.0 -- animatable

The rotational position of the cross-section in the renderer.

Section : Shape

959

<Rectangle>.thickness <Rectangle>.sides

Float Float

default: 1.0 default: 12.0

-- animatable -- animatable

Radius of the rendered spline. Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.
<Rectangle>.viewport_thickness Float default: 1.0 default: 12

Diameter of the viewport spline.

<Rectangle>.viewport_sides Integer

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.
<Rectangle>.viewport_angle <Rectangle>.DisplayRenderMesh <Rectangle>.UseViewportSettings <Rectangle>.DisplayRenderSettings <Rectangle>.renderableBoolean <Rectangle>.mapCoordsBoolean Float Boolean Boolean Boolean default: 0.0 default: false default: false default: true

The rotational position of the cross-section in the viewports. When on, displays the mesh generated by the spline in the viewports. When on, displays the mesh generated by the Viewport settings. When on, displays the mesh generated by the render settings.
default: true default: false

When on, the spline is displayed in the rendered scene. Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline.

See also
Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Section : Shape
Constructor:
section ...

Properties:
<Section>.length <Section>.width Float Float default: 0.0 default: 0.0 -- animatable -- animatable

The length of the displayed section rectangle. The width of the displayed section rectangle.

960

Chapter 11

3ds max Objects

Note: The Section Parameters rollout item properties are not accessible to MAXScript in 3ds max 4. A bug prevents a Section shape from being properly collapsed to a SplineShape in some cases. This only happens when a Section shape is created inside a loop and is being converted to a SplineShape. To collapse to a SplineShape, a viewport redraw must be performed after the Section shape is created. An example of creating contour lines from an object is: Script:
meshSelected = sphere() -- object to create contours of minZ = meshSelected.min.z -- get min and max Z positions maxZ = meshSelected.max.z numLevels = 10 -- the number of contours delta = (maxZ - minZ) / (numLevels + 1) -- the number of steps for currentZ = minZ to maxZ by delta do -- start loop... ( s = section pos:[0, 0, currentZ] -- create Section max views redraw -- this line needed to get around bug convertToSplineShape s -- convert Section to SplineShape s.renderable = true -- set to renderable )

See also
Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Star : Shape
Constructor:
star ...

Properties:
<Star>.radius1 <Star>.radius2 <Star>.points <Star>.distort Float Float Integer Float default: 25.0 -- alias: Radius_1 default: 12.0 -- alias: Radius_2 default: 6 default: 0.0 -- alias: numPoints -- alias: Distortion

The radius of the inner vertices of the star. The radius of the outer vertices of the star. The number of points on the star. The valid range is from 3 to 100. Rotates the outer vertices about the center of the star. This produces a saw-tooth affect.
<Star>.fillet1Floatdefault: 0.0

Rounds the inner vertices (the valleys) of the star.

Star : Shape

961

<Star>.fillet2Floatdefault: 0.0

Rounds the outer vertices (the points) of the star.

<Star>.steps <Star>.optimize <Star>.adaptive Integer Boolean Boolean default: 6 default: true default: false

The number of divisions between each vertex. When on, removes unneeded steps from straight segments in the spline. When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.
<Star>.angle <Star>.thickness <Star>.sides Float Float Float default: 0.0 default: 1.0 default: 12.0 -- animatable -- animatable -- animatable

The rotational position of the cross-section in the renderer. Radius of the rendered spline. Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.
<Star>.viewport_thickness Float default: 1.0 default: 12

Diameter of the viewport spline.

<Star>.viewport_sides Integer

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.
<Star>.viewport_angle <Star>.DisplayRenderMesh <Star>.UseViewportSettings <Star>.DisplayRenderSettings <Star>.renderableBoolean <Star>.mapCoords Boolean Float Boolean Boolean Boolean default: 0.0 default: false default: false default: true

The rotational position of the cross-section in the viewports. When on, displays the mesh generated by the spline in the viewports. When on, displays the mesh generated by the Viewport settings. When on, displays the mesh generated by the render settings.
default: true default: false

When on, the spline is displayed in the rendered scene. Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline. Note: The Fillet_Radius_1 and Fillet_Radius_2 properties are not accessible to MAXScript in 3ds max 4. In order to access the points property for Star, you need to access the property via the baseobject property of the node. This is because points is also a property name for all nodes, and conflicts with the Stars points property. For example:
MyStar.baseobject.points=10 -- set number of Star points to 10

962

Chapter 11

3ds max Objects

See also
Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Text : Shape
Constructor:
text ...

Properties:
<text>.font <text>.italic <text>.underline String Boolean Boolean default: Arial default: false default: false

Choose from a list of all fonts available to 3ds max. Turn on/off italicized text. Turn on/off underlined text.
<text>.alignmentIntegerdefault: 1

Sets the alignment of text: Align Left (Aligns text to the left side of its bounding box.) Center (Aligns text to the center of its bounding box.) Align Right (Aligns text to the right side of its bounding box.) Justify (Spaces all lines of text to fill the extents of the bounding box.)
<text>.size <text>.kerning <text>.leading <text>.text <text>.steps <text>.optimize <text>.adaptive Float Float Float String Integer Boolean Boolean default: 100.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable

Te text height where the height measuring method is defined by the active font. The kerning (the distance between letters). The leading (the distance between lines).
default: 3ds max Text default: 6 default: true default: false

The text displayed in the viewport. The number of divisions between each vertex. When on, removes unneeded steps from straight segments in the spline. When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.

Text : Shape

963

<text>.angle <text>.thickness <text>.sides

Float Float Float

default: 0.0 default: 1.0 default: 12.0

-- animatable -- animatable -- animatable

The rotational position of the cross-section in the renderer. Radius of the rendered spline. Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.
<text>.viewport_thickness Float default: 1.0 default: 12

Diameter of the viewport spline.

<text>.viewport_sides Integer

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.
<text>.viewport_angle <text>.DisplayRenderMesh <text>.UseViewportSettings <text>.DisplayRenderSettings <text>.renderableBoolean <text>.mapCoordsBoolean Float Boolean Boolean Boolean default: 0.0 default: false default: false default: true

The rotational position of the cross-section in the viewports. When on, displays the mesh generated by the spline in the viewports. When on, displays the mesh generated by the Viewport settings. When on, displays the mesh generated by the render settings.
default: true default: false

When on, the spline is displayed in the rendered scene. Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline. Note: The Manual Update and Alignment properties are not accessible to MAXScript in 3ds max 4. In 3DS VIZ, the default value for property Text is VIZ Text

See also
Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

964

Chapter 11

3ds max Objects

Shapes - NURBS Curves

The following list shows the 3ds max NURBS Curves shape class objects: CV_Curve (p. 964) Point_Curve (p. 965)

CV_Curve : Shape
CV_Curves are NURBS curve objects defined by CVs (control vertices). All NURBS objects are created through the special NURBS descriptor classes (see Working with NURBS (p. 1384)) and the CV_Curve class is used typically in object class testing with the classOf() function. Scene objects created as CV Curve shape objects in the 3ds max user interface have the class CV_Curve. Constructor:
NURBSNode <nurbs_set> ...

See Creating New NURBS Objects (p. 1389) for details. Properties:
<CV_Curve>.angle <CV_Curve>.thickness <CV_Curve>.sides Float Float Float default: 0.0 default: 1.0 default: 12.0 -- animatable -- animatable -- animatable

The rotational position of the cross-section in the renderer. Diameter of the rendered curve. Sets the number of sides for the curve mesh in the renderer. A value of 4 will give you a square cross section, for example.
<CV_Curve>.renderableBoolean <CV_Curve>.mapCoordsBoolean default: true default: false

When on, the curve is displayed in the rendered scene. Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the curve; the V coordinate is mapped once along the length of the curve. Additional Properties for CV curves are accessed through a NURBSSet descriptor object. See Working with NURBS (p. 1384) for more details.

See also
Shape Common Properties, Operators, and Methods (p. 945) NURBS Node Properties and Methods (p. 1397) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Point_Curve : Shape

965

Point_Curve : Shape
Point_Curves are NURBS curve objects defined by interpolated points. All NURBS objects are created through the special NURBS descriptor classes (see Working with NURBS (p. 1384)) and the Point_Curve class is used typically in object class testing with the classOf() function. Scene objects created as Point Curve shape objects in the 3ds max user interface have the class Point_Curve. Constructor:
NURBSNode <nurbs_set> ...

See Creating New NURBS Objects (p. 1389) for details. Properties:
<Point_Curve>.angle <Point_Curve>.thickness <Point_Curve>.sides Float Float Float default: 0.0 default: 1.0 default: 12.0 -- animatable -- animatable

The rotational position of the cross-section in the renderer. Diameter of the rendered curve.
-- animatable

Sets the number of sides for the curve mesh in the renderer. A value of 4 will give you a square cross section, for example.
<Point_Curve>.renderableBoolean <Point_Curve>.mapCoordsBoolean default: true default: false

When on, the curve is displayed in the rendered scene. Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the NURBS curve; the V coordinate is mapped once along the length of the curve. Additional properties for point curves are accessed through a NURBSSet descriptor object. See Working with NURBS (p. 1384) for more details.

See also
Shape Common Properties, Operators, and Methods (p. 945) NURBS Node Properties and Methods (p. 1397) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

966

Chapter 11

3ds max Objects

Light : Node
The following list shows the 3ds max light class objects: DirectionalLight (p. 970) FreeSpot (p. 971) OmniLight (p. 972) TargetSpot (p. 973) TargetDirectionalLight (p. 972)

See also
Light Common Properties, Operators, and Methods (p. 966)

Light Common Properties, Operators, and Methods

The following properties apply to all light types except for the Free_Point and Target_Point light types present in 3D Studio VIZ.
<light>.type Name default: #freeDirect

the valid type values are:

#omni #freeSpot #targetSpot #freeDirect #targetDirect <light>.enabled Boolean default: true -- alias: on

Turns the light on and off. When on, shading and rendering use the light to illuminate the scene. When off, the light is not used in shading or rendering.
<light>.excludeList <light>.includeList Array Array default: #() default: undefined

Objects in this array are excluded from the effects of the light. Objects in this array receive the effects of the light.
<light>.inclExclType Integer default: 3

Select the type of object in the Include/Exclude list: Illumination Shadow Casting Both
<light>.castShadows <light>.rgb animatable, alias: color Boolean Color default: false default: (color 180 180 180) --

When on, the light will cast shadows on objects.

The red, green, and blue components of the lights color.

Light Common Properties, Operators, and Methods

967

<light>.hsv <light>.hue

Point3 Integer Integer Integer Float Float

default: [0,0,180] default: 0 default: 0 default: 180 default: 1.0 default: 0.0 -- animatable -- animatable

Hue, Saturation, and Value color of light. Hue component of hsv.

<light>.saturation

Saturation component of hsv.

<light>.value

Value component of hsv.

<light>.multiplier <light>.contrast

Amplifies the power of the light by a positive or negative amount. Adjusts the contrast between the diffuse and ambient areas of the surface. Leave this set to 0 for normal contrast. Increase the value to increase the contrast for special effects: for example, the harsh light of outer space.
<light>.softenDiffuseEdge alias: Diffuse_Soften Float default: 0.0 -- animatable,

Increasing the value of Soften Diffuse Edge softens the edge between the diffuse and ambient portions of a surface. This helps eliminate edges that can appear on a surface under certain circumstances.
<light>.affectDiffuse Boolean default: true

When on, the light affects the diffuse properties of an objects surface. When off, the light has no effect on the diffuse surface.
<light>.affectSpecular Boolean default: true

When on, the light affects the specular properties of an objects surface. When off, the light has no effect on the specular properties.
<light>.ambientOnly <light>.projector <light>.projectorMap Boolean Boolean TextureMap default: false default: false default: undefined

When on, the light affects only the ambient component of the illumination. Turn on to project projectorMap. Assigning a TextureMap to projectorMap causes a new subAnim named Projection_Map to be created for the light. This subAnim contains the properties of the TextureMap.
<light>.useShadowProjectorMap Boolean default: false

When on, the light will project a map.

<light>.nearAttenStart Float animatable, alias: Attenuation_Near_Start <light>.nearAttenEnd Float animatable, alias: Attenuation_Near_End default: 0.0 -- alias:

The distance at which the light begins to fade in.

default: 40.0 -- alias:

The distance at which the light reaches its full value.

968

Chapter 11

3ds max Objects

<light>.useNearAtten <light>.showNearAtten

Boolean Boolean

default: false default: false

Enables/Disables near attenuation for the light. When on, displays the near attenuation range settings in viewports. For spotlights, attenuation ranges appear as lens-shaped sections of the cone. For directional lights, the ranges appear as circular sections of the cone. For omni lights and spot or directional lights with Overshoot turned on, the ranges appear as spheres.
<light>.farAttenStart alias: Attenuation_Far_Start <light>.farAttenEnd alias: Attenuation_Far_End <light>.useFarAtten <light>.showFarAtten Float default: 80.0 -- animatable,

The distance at which the light begins to fade out.

Float default: 200.0 -- animatable,

The distance at which the light has faded to zero.

Boolean Boolean default: false default: false

Enables/Disables far attenuation for the light. Displays the far attenuation range settings in viewports. For spotlights, attenuation ranges appear as lens-shaped sections of the cone. For directional lights, the ranges appear as circular sections of the cone. For omni lights and spot or directional lights with Overshoot turned on, the ranges appear as spheres.
<light>.attenDecay Integer default: 1

The type of decay to use: None (Applies no decay. The light maintains full strength from its source to infinity, unless you turn on far attenuation.) Inverse (Applies inverse decay. The formula is luminance=R0/R, where R0 is the radial source of the light if no attenuation is used, or the Near End value of the light if Attenuation is used. R is the radial distance of the illuminated surface from R0.) Inverse Square (Applies inverse-square decay. The formula for this is (R0/R)2. This is actually the real-world decay of light, but you might find it too dim in the world of computer graphics.)
<light>.DecayRadius alias: Decay_Falloff <light>.useGlobalShadowSettings Float default: 40.0 -- animatable,

The distance over which the decay occurs.

Boolean default: false

Turn on to use global settings for shadows cast by this light. Turn off to enable individual control of the shadows.
<light>.raytracedShadows Boolean default: false

When true, ray traced shadows are produced. When false, shadow-mapped shadows are produced.
<light>.ShadowColor alias: Shadow_Color Color default: (color 0 0 0) -- animatable,

The color of shadows cast by this light.

Light Common Properties, Operators, and Methods

969

<light>.shadowMultiplier alias: Shadow_Density <light>.shadowProjectorMap

Float TextureMap

default: 1.0

-- animatable,

default: undefined

Assigning a TextureMap to shadowProjectorMap causes a new subAnim named Shadow_Projection_Map to be created for the light. This subAnim contains the properties of the TextureMap.
<light>.lightAffectsShadow Boolean default: false

When on, blends the lights color with the shadow color (or shadow colors, if the shadow is mapped).
<light>.atmosShadows Boolean default: true default: 100.0 -- animatable,

When on, atmospheric effects cast shadows as the light passes through them.
<light>.atmosOpacity Float percentage, alias: Atmosphere_Opacity <light>.atmosColorAmt Float percentage, alias: Atmosphere_Color_Amount

Adjusts the opacity of the shadows. This value is a percentage.

default: 100.0 -- animatable,

Adjusts the amount that the atmospheres color is blended with the shadow color. If Shadow Maps are being used (raytracedShadows = false), the shadow properties are:
<light>.mapBias alias: map_bias <light>.mapSize alias: map_size <light>.sampleRange alias: map_range Float default: 1.0 -- animatable,

Moves the shadow toward or away from the shadow-casting object (or objects).
Integer default: 512 -- animatable,

Sets the size (in pixels squared) of the shadow map thats computed for the light.
Float default: 4.0 -- animatable,

Determines how much area within the shadow is averaged. This affects how soft the edge of the shadow is.
<light>.absoluteMapBias Boolean default: false -- animatable

When on, the bias for the shadow map is not normalized, but is instead based on a fixed scale expressed in 3ds max units. This value does not change during an animation. You must choose the value, based on the size of the scene extents. When off, the bias is computed relative to the rest of the scene, and then normalized to 1.0. This provides a common starting bias value in scenes of any size. If the scene extents change, this internal normalization can vary from frame to frame.
<light>.absolute_Bias absoluteMapBias Integer default: 0 -- integer alias of

970

Chapter 11

3ds max Objects

If Ray Traced Shadows are being used (raytracedShadows = true), the shadow properties are:
<light>.raytraceBias Float default: 0.2 -- animatable

Moves the shadow toward or away from the shadow-casting object (or objects). If the Bias value is too low, shadows can leak through places they shouldnt, produce moire patterns or making out-of-place dark areas on meshes. If Bias is too high, shadows can detach from an object. If the Bias value is too extreme in either direction, shadows might not be rendered at all.
<light>.maxDepth Integer default: 7 -- animatable

Adjusts the depth of the quadtree used by the raytracer. Greater quadtree depth values can improve ray-tracing time at the cost of memory use. However, there is a depth value where the performance improvement is offset by the time it takes to generate the quadtree itself. This depends on the geometry of the scene. Note: Setting includelist or excludelist sets the other to undefined. Assigning a Projector TextureMap adds a subAnim to the properties list. The properties of the subAnim are the properties of the TextureMap. The Attenuation Parameters/Decay/Show and Shadow Parameters/Map/Enable properties are not accessible by MAXScript in 3ds max 4.

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

DirectionalLight : Light
Constructor:
directionalLight ...

Properties:
<DirectionalLight>.aspect alias: Aspect_Ratio <DirectionalLight>.falloff <DirectionalLight>.showCone Float default: 1.0 -- animatable,

The aspect ratio for the rectangular light beam.

Float Boolean Float default: 45.0 default: false default: 43.0 -- animatable -- animatable

The size of a lights falloff. The Falloff value is measured in 3ds max units. Turns display of the cone on or off.
<DirectionalLight>.hotspot

The size of a lights cone. The Hotspot value is measured in 3ds max units.

FreeSpot : Light

971

<DirectionalLight>.overShoot

Boolean

default: false

When overshoot is on, the light casts light in all directions. However, projections and shadows occur only within its falloff cone.
<DirectionalLight>.coneShape Integer default: 1 -- alias: lightShape

The shape of the falloff and hotspot areas: Circle Rectangle

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

FreeSpot : Light
Constructor:
freeSpot ...

Properties:
<Freespot>.aspect Aspect_Ratio <Freespot>.falloff <Freespot>.showCone <Freespot>.hotspot <Freespot>.overShoot Float default: 1.0 -- animatable, alias:

The aspect ratio for the rectangular light beam.

Float Boolean Float Boolean default: 45.0 default: false default: 43.0 default: false -- animatable -- animatable

The angle of a lights falloff. The Falloff value is measured in degrees. Turns display of the cone on or off. The angle of a lights cone. The Hotspot value is measured in degrees. When on, the light casts light in all directions. However, projections and shadows occur only within its falloff cone.
<Freespot>.coneShape Integer default: 1 -- alias: lightShape

The shape of the falloff and hotspot areas: Circle Rectangle

972

Chapter 11

3ds max Objects

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

OmniLight : Light
Constructor:
omniLight ...

Properties: There are no additional properties for OmniLight.

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

TargetDirectionalLight : Light
Constructor:
targetDirectionalLight ...

Properties:
<TargetDirectionallight>.aspect alias: Aspect_Ratio <TargetDirectionallight>.falloff <TargetDirectionallight>.showCone Float default: 1.0 -- animatable,

The aspect ratio for the rectangular light beam.

Float Boolean Float Boolean default: 45.0 default: false default: 43.0 default: false -- animatable -- animatable

The angle of a lights falloff. The Falloff value is measured in degrees. Turns display of the cone on or off.
<TargetDirectionallight>.hotspot <TargetDirectionallight>.overShoot

The angle of a lights cone. The Hotspot value is measured in degrees. When on, the light casts light in all directions. However, projections and shadows occur only within its falloff cone.

TargetSpot : Light

973

<TargetDirectionallight>.coneShape lightShape

Integer

default: 1

-- alias:

The shape of the falloff and hotspot areas: Circle Rectangle Note: In MAXScript, you must explicitly construct a target for those objects that need one. For example:
c = TargetDirectionallight pos:[x,y,z] target:(targetObject pos:[xt, yt, zt])

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

TargetSpot : Light
Constructor:
targetSpot ...

Properties:
<Targetspot>.aspect Aspect_Ratio <Targetspot>.falloff <Targetspot>.showCone <Targetspot>.hotspot <Targetspot>.overShoot Float default: 1.0 -- animatable, alias:

The aspect ratio for the rectangular light beam.

Float Boolean Float Boolean default: 45.0 default: false default: 43.0 default: false -- animatable -- animatable

The angle of a lights falloff. The Falloff value is measured in degrees. Turns display of the cone on or off. The angle of a lights cone. The Hotspot value is measured in degrees. When on, the light casts light in all directions. However, projections and shadows occur only within its falloff cone.
<Targetspot>.coneShape Integer default: 1 -- alias: lightShape

The shape of the falloff and hotspot areas: Circle Rectangle Note: In MAXScript, you must explicitly construct a target for those objects that need one. For example:
c = Targetspot pos:[x,y,z] target:(targetObject pos:[xt, yt, zt])

974

Chapter 11

3ds max Objects

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

Camera : Node
The following list displays the camera objects: FreeCamera (p. 976) TargetCamera (p. 976)

See also
Camera Common Properties, Operators, and Methods (p. 974)

Camera Common Properties, Operators, and Methods

Properties: The following properties apply to all camera types:
<camera>.fov <camera>.orthoProjection Float Boolean default: 45.0 default: false -- animatable, angle

Determines how wide an area the camera views. When on, the camera view looks just like a User view. When off, the camera view is the standard perspective-like view.
<camera>.type Name default: #free

The type of camera: #free - Free Camera (Target view can be set in any direction) #target - Target Camera (Camera will always align view with target object)
<camera>.showCone Boolean default: false

Displays the cone (actually a pyramid) defined by a cameras field of view. The cone appears in the other viewports but does not appear in a camera viewport.
<camera>.showHorizon Boolean default: false

Displays the horizon line. A dark gray line appears at the level of the horizon in the cameras viewport.
<camera>.nearrange Near_Env_Range <camera>.farrange Far_Env_Range Float default: 0.0 -- animatable; alias:

The near range for atmospheric effects.

Float default: 1000.0 -- animatable; alias:

The far range for atmospheric effects.

Camera Common Properties, Operators, and Methods

975

<camera>.clipManually

Boolean

default: false

Turn on to define clipping planes. When Clip Manually is off, geometry closer to the camera than 3 units is not displayed.
<camera>.nearclip near_clip <camera>.farclip far_clip <camera>.showRanges Float default: 1.0 -- animatable, alias:

Objects closer than the near clipping plane are invisible to the camera.
Float default: 1000.0 -- animatable, alias:

Objects farther than the far clipping plane are invisible to the camera.
Boolean default: false

When on, displays yellow rectangles within the cameras cone to show the Near and Far range settings.
<camera>.targetDistance Target_Distance Float default: 160.0 -- animatable, alias:

Sets a point to use as an invisible target.

See also
Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Note: The fov parameter value is the horizontal FOV in degrees. The Vertical and Diagonal FOV and Lens values are based on the horizontal FOV and the current renderer Aperture Width. You can use the following function to calculate the Vertical FOV from the Horizontal FOV:
fn GetCamVFOV theCamera = ( local r_aspect=(renderWidth as float)/renderHeight 2.*atan(tan(theCamera.fov/2.)/r_aspect) )

Examples: The following script changes the fov of specified camera to simulate a zoom extents all for the camera. Script:
fn ZE_Cam cam objs = ( local max2, fov, asp, v -- declare local variables -- define a function that returns the maximum value of a set of values in an array fn maxof vals = (local v=vals[1]; for v1 in vals do (if v1 > v do v=v1);v) fov=0 -- initialize the fov value asp=(renderWidth as float)/renderHeight -- calculate the renderers image aspect ratio in coordsys cam -- work in coordinate system of the camera

976

Chapter 11

3ds max Objects

( for obj in objs where obj != cam do -- loop across all objects except the camera ( if obj.min.z >=0 do continue -- if object is behind camera, skip it -- get max value of the objects bounding box, correcting for the image aspect ratio -- in the y values v = maxof #((abs obj.max.x),(abs obj.min.x),(abs (obj.max.y*asp)),(abs (obj.min.y*asp))) fov = maxof #(fov,(2*atan(-v/obj.min.z))) -- increase fov if needed ) ) cam.fov=fov -- set the cameras fov to the new fov value ) --test bed -cam=$camera01 -- specify the camera to zoom extent all on ZE_Cam cam $* -- call the function, passing the camera and an object set containing all objects

FreeCamera : Camera
Constructor:
freecamera ...

Properties: There are no additional properties for FreeCamera.

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

TargetCamera : Camera
Constructor:
targetCamera ...

Properties: There are no additional properties for TargetCamera.

TargetCamera : Camera

977

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

Helper : Node
The following list shows the helper objects: -- Standard Bone (p. 978) Compass (p. 979) Dummy (p. 979) Grid (p. 980) Point (p. 980) Protractor (p. 981) Tape (p. 981) -- Atmospheric BoxGizmo (p. 982) CylGizmo (p. 983) SphereGizmo (p. 983) -- Camera Match CamPoint (p. 984) -- VRML 1.0/VRBL Inline (p. 984) LOD (p. 985) VRML_VRBL (p. 985) -- VRML97 Anchor (p. 986) AudioClip (p. 986) Background (p. 987) Billboard (p. 987) FogHelper (p. 987) InlineHelper (p. 988) LODHelper (p. 988) NavInfo (p. 988)

978

Chapter 11

3ds max Objects

ProxSensor (p. 989) Sound (p. 989) TouchSensor (p. 990) TimeSensor (p. 990)

Helper - Standard
The following list shows the standard helper objects: Bone (p. 978) Compass (p. 979) Dummy (p. 979) Grid (p. 980) Point (p. 980) Protractor (p. 981) Tape (p. 981)

Bone : Helper
Constructor:
bone ...

Properties: There are no additional properties for Bone.

See also
Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Note: The Bone helper object is used by 3ds max to represent the nodes in a Bones system. In 3ds max 4, it is not possible to create a Bones system using IK controllers on the Bones nodes. You can create a hierarchy of Bone helper objects which use the standard PRS transform controller for each node. For example:
b0 in in in = bone pos:[x,y,z] b0 b1 = bone pos:[x1,y1,z1] b1 b2 = bone pos:[x2,y2,z2] b2 b3 = bone pos:[x3,y3,z3]

Compass : Helper

979

You can rearrange bone hierarchies using the parent property. When a hierarchy of Bone helper objects is built, the showLinks and showLinksOnly properties are automatically set to true.

Compass : Helper
Constructor:
compass ...

Properties: There are no additional properties for Compass. Note: The Show Compass Rose and Radius properties are not accessible to MAXScript in 3ds max 4.

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

Dummy : Helper
Constructor:
dummy ...

Properties:
<Dummy>.boxsize Point3 default: [10,10,10]

Icon size.

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

980

Chapter 11

3ds max Objects

Grid : Helper
Constructor:
grid ...

Properties:
<grid>.length <grid>.width <grid>.grid Float Float Float default: 50.0 default: 50.0 default: 10.0 -- animatable -- animatable -- animatable

Length of the grid. Width of the grid. The size of the smallest square in the visible grid. Note: The Active Color and Display properties are not accessible to MAXScript in 3ds max 4.

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

Point : Helper
Constructor:
point ...

Properties:
<Point>.axisLength <Point>.size Float Float Boolean Boolean Boolean Boolean default: 20.0 default: 20.0 -animatable --animatable animatable

Sets the length of the tripod axis. Sets the size of of the point helper.
<Point>.centermarker <Point>.axistripod <Point>.cross <Point>.box default: false default: false default: true default: false ---

When turned on, a small X marker is displayed at the center of the point helper object. When this is turned on, an axis tripod with x, y, and z labels is displayed.
animatable

When this is turned on, an axis aligned cross is displayed.

animatable

When this is turned on, a square box is displayed centered at the center of the point helper object.

Protractor : Helper

981

<Point>.constantscreensize

Boolean

default: false

--

animatable

When this is turned on, the point object remains the same size in screen space regardless of how much the user zooms in or out.
<Point>.drawontop Boolean default: false -animatable

When this is on, the point helper object draws lines with the Z buffer turned off (which usually causes it to appear in front of other objects).

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

Protractor : Helper
Constructor:
protractor ...

Properties: There are no additional properties for Protractor. Note: There is not a way to set the Protractor reference objects using MAXScript in 3ds max 4.

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

Tape : Helper
Constructor:
tape ...

Properties:
<Tape>.length Float default: 50.0 -- animatable

Length of the tape object.

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

982

Chapter 11

3ds max Objects

Note: To construct a tape, you have to create its target node first (using the targetObject constructor), and then construct the tape giving it the target:
tape pos:p target:(targetObject pos:q)

The length property shows the tape length set in the 3ds max user interface, not the true distance from the tape to its target. The following function can be used to return this distance:
fn getTapeDist TapeObj = distance TapeObj TapeObj.target

An example usage is:

getTapeDist $tape01

Helper - Atmospheric
The following list shows the atmospheric helper objects: BoxGizmo (p. 982) CylGizmo (p. 983) SphereGizmo (p. 983)

BoxGizmo : Helper
Constructor:
boxGizmo ...

Properties:
<BoxGizmo>.length <BoxGizmo>.width <BoxGizmo>.height <BoxGizmo>.seed Float Float Float Integer default: 0.0 default: 0.0 default: 0.0 default: 0 -- animatable -- animatable -- animatable -- alias: parameter

Length of the box gizmo. Width of the box gizmo. Height of the box gizmo. Base value used to generate the atmospheric effect. Each apparatus in the scene should have a different seed. If more than one apparatus uses the same seed and same atmospheric effect, they will produce nearly identical results.

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

CylGizmo : Helper

983

CylGizmo : Helper
Constructor:
cylGizmo ...

Properties:
<CylGizmo>.radius <CylGizmo>.height <CylGizmo>.seed Float Float Integer default: 0.0 default: 0.0 default: 0 -- animatable -- animatable -- alias: parameter

Radius of cylinder gizmo object. Height of cylinder gizmo object. Base value used to generate the atmospheric effect. Each apparatus in the scene should have a different seed. If more than one apparatus uses the same seed and same atmospheric effect, they will produce nearly identical results.

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

SphereGizmo : Helper
Constructor:
sphereGizmo ...

Properties:
<SphereGizmo>.radius <SphereGizmo>.hemisphere Float Integer default: 0.0 default: 0 -- animatable

Radius of sphere gizmo object. When turned on, the bottom half of the SphereGizmo is discarded, creating a hemisphere: OFF ON
<SphereGizmo>.seed Integer default: 0

Base value used to generate the atmospheric effect. Each apparatus in the scene should have a different seed. If more than one apparatus uses the same seed and same atmospheric effect, they will produce nearly identical results.

984

Chapter 11

3ds max Objects

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

Helper - Camera Match

The following list shows the camera match helper objects: CamPoint (p. 984)

CamPoint : Helper
Constructor:
camPoint ...

Properties:
<CamPoint>.showAxis <CamPoint>.axisLength Boolean Float default: true default: 20.0

When on, an axis tripod is displayed with the camera point object. The length of the axis tripod.

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

Helper - VRML 1.0/VRBL

The following list shows the VRML 1.0/VRBL helper objects: Inline (p. 984) LOD (p. 985) VRML_VRBL (p. 985)

Inline : Helper
Constructor:
inline ...

Properties: There are no additional properties for Inline.

LOD : Helper

985

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

LOD : Helper
Constructor:
lod ...

Properties: There are no additional properties for LOD.

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

VRML_VRBL : Helper
Constructor:
vrml_vrbl ...

Properties: There are no additional properties for VRML_VRBL.

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

Helper - VRML97
The following list shows the VRML97 helper objects: Anchor (p. 986) AudioClip (p. 986) Background (p. 987) Billboard (p. 987) FogHelper (p. 987)

986

Chapter 11

3ds max Objects

InlineHelper (p. 988) LODHelper (p. 988) NavInfo (p. 988) ProxSensor (p. 989) Sound (p. 989) TouchSensor (p. 990) TimeSensor (p. 990)

Anchor : Helper
Constructor:
anchor ...

Properties: There are no additional properties for Anchor.

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

AudioClip : Helper
Constructor:
audioClip ...

Properties: There are no additional properties for AudioClip.

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

Background : Helper

987

Background : Helper
Constructor:
background ...

Properties: There are no additional properties for Background.

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

Billboard : Helper
Constructor:
billboard ...

Properties: There are no additional properties for Billboard.

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

FogHelper : Helper
Constructor:
fogHelper ...

Properties: There are no additional properties for FogHelper.

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

988

Chapter 11

3ds max Objects

InlineHelper : Helper
Constructor:
inlineHelper ...

Properties: There are no additional properties for InlineHelper.

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

LODHelper : Helper
Constructor:
lodHelper ...

Properties: There are no additional properties for LODHelper.

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

NavInfo : Helper
Constructor:
navInfo ...

Properties: There are no additional properties for NavInfo.

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

ProxSensor : Helper

989

ProxSensor : Helper
Constructor:
proxSensor ...

Properties: There are no additional properties for ProxSensor.

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

Sound : Helper
Constructor:
sound ...

Properties: There are no additional properties for Sound. Variables:

WAVsound.filename

Get/set Sound track filename as <string>. There currently is not a way to perform and Remove Sound via MAXScript
WAVsound.start

Get/set Sound track range start time as <time>.

WAVsound.end

A read only variable to get the Sound track range end time as a <time> value.
WAVsound.mute

Get/set whether Sound track is active as <boolean>.

WAVsound.isPlaying

A read only variable that returns whether the Sound track is currently playing as a <boolean> value. Methods:
WAVsound.scrub <interval>

Plays back the specified time interval of the Sound track.

990

Chapter 11

3ds max Objects

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

TimeSensor : Helper
Constructor:
timeSensor ...

Properties: There are no additional properties for TimeSensor.

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

TouchSensor : Helper
Constructor:
touchSensor ...

Properties: There are no additional properties for TouchSensor.

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

Bones : System

991

System : Node
System objects are not creatable by MAXScript. Once a system object in created in 3ds max, various properties associated with the system are accessible by MAXScript. The 3ds max system objects are: Bones (p. 991) Sunlight (p. 991) RingArray (p. 992) Note: Only the Sunlight class is available in 3D Studio VIZ.

Bones : System
Note: This class is not available in 3D Studio VIZ. Bones system objects are not creatable by MAXScript. A Bones system is comprised of the Bone Helper (p. 978) objects, a master IK controller, and slave IK controllers. The slave IK controllers are used as the transform controller for all nodes in the IK system, and the master IK controller controls the individual slave IK controllers. The methods associated with the IK controller are described in the IK_ControllerMatrix3Controller : Matrix3Controller (p. 1313) topic.

Sunlight : System
Sunlight system objects are not creatable by MAXScript. A Bones system is comprised of a Compass Helper (p. 979) object and a TargetDirectionalLight (p. 972) object. The TargetDirectionalLights transform is controlled by a set of float controllers, which are sub-controllers of a non-accessible position controller (a Sunlight_Slave_Controller position controller). These float controllers can be accessed as subAnims of the TargetDirectionalLight node. These float controllers, and their subAnim index number, are:
Solar_Time - subAnim[3] Solar_Date - subAnim[4] Latitude - subAnim[5] Longitude - subAnim[6] Orbital_Scale - subAnim[7]

For example, if node $Sun01 is the light for a Sunlight system, the Solar_Time controller can be accessed as:
solarTimeCont=$Sun01[3].object

992

Chapter 11

3ds max Objects

RingArray : System
Note: This class is not available in 3D Studio VIZ. RingArray system objects are not creatable by MAXScript. A RingArray system is comprised of a Dummy Helper (p. 979) object, a variable number of Box (p. 853) objects, a master controller, and Slave_Control controllers. The Slave_Control controllers are used as the transform controller for all Boxes in the RingArray system, and the master controller controls the individual Slave_Control controllers. The methods associated with the Slave_Control controller are described in the Slave_Controller : Matrix3Controller (p. 1333) topic.

SpacewarpObject : Node
Note: Spacewarp objects are not available in 3D Studio VIZ. The following list shows the space warp objects: -- Geometric/Deformable Bomb (p. 993) Conform (p. 995) SpaceDisplace (p. 996) SpaceFFDBox (p. 998) SpaceFFDCyl (p. 999) SpaceRipple (p. 1001) SpaceWave (p. 1002) -- Particles and Dynamics Gravity (p. 1003) Motor (p. 1004) PBomb (p. 1006) Push (p. 1008) Wind (p. 1010) -- Modifier-Based SpaceBend (p. 1011) SpaceNoise (p. 1012) SpaceSkew (p. 1014) SpaceStretch (p. 1015) SpaceTaper (p. 1016) SpaceTwist (p. 1017)

Bomb : SpacewarpObject

993

-- Dynamics Interface PDynaFlect (p. 1019) SDynaFlect (p. 1020) UDynaFlect (p. 1022) -- Particles Only Deflector (p. 1024) Path_Follow (p. 1025) POmniFlect (p. 1027) SDeflector (p. 1030) SOmniFlect (p. 1031) UDeflector (p. 1033) UOmniFlect (p. 1034)

Spacewarp - Geometric/Deformable
Note: Spacewarp objects are not available in 3D Studio VIZ. The following list shows the geometric/deformable space warp objects: Bomb (p. 993) Conform (p. 995) SpaceDisplace (p. 996) SpaceFFDBox (p. 998) SpaceFFDCyl (p. 999) SpaceRipple (p. 1001) SpaceWave (p. 1002)

Bomb : SpacewarpObject
Constructor:
bomb ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Bomb>.strength Float default: 1.0 -- animatable

The power of the bomb. Larger values make the particles fly farther. The closer an object is to the bomb, the greater the effect of the bomb.
<Bomb>.spin Float default: 0.0 -- animatable

The rate at which fragments rotate, in revolutions per second.

994

Chapter 11

3ds max Objects

<Bomb>.falloff

Float

default: 100.0

-- animatable

The distance from the bomb, in world units, of the effect of the bomb. Fragments past this distance are not affected by the Strength and Spin settings, but are affected by the Gravity setting.
<Bomb>.fallOffEnable <Bomb>.minFragmentSize Boolean Integer default: false default: 1

Turn on to use the Falloff setting. The falloff range appears as a yellow, tri-hooped sphere. The minimum number of faces per fragment to be randomly generated by the explosion.
<Bomb>.maxFragmentSize Integer default: 1

The maximum number of faces per fragment to be randomly generated by the explosion.
<Bomb>.Gravity Float default: 1.0 -- animatable

The acceleration due to gravity. Note that gravity is always in the direction of the world Z axis. You can have negative gravity.
<Bomb>.chaos Float default: 0.0 -- animatable

Adds random variation to the explosion to make it less uniform. A setting of 0.0 is totally uniform; 1.0 is a realistic setting. A value greater than 1.0 makes the explosion extra chaotic.
<Bomb>.detonation <Bomb>.seed Time Integer default: 5f default: 0

The frame at which the bomb goes off. Bound objects are unaffected before this time. Change to alter randomly generated numbers in the bomb. You can achieve a different bomb effect by changing Seed while maintaining the other settings. Associated Methods:
bindSpaceWarp <node> <bomb_node>

Associated Binding Modifier:

BombBinding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

ConformSpaceWarp : SpacewarpObject

995

ConformSpaceWarp : SpacewarpObject
Constructor:
conformSpaceWarp ...

Note: This class is not available in 3D Studio VIZ. Properties:

<ConformSpaceWarp>.Projection_Distance Float default: 0.0 -- animatable

The distance a vertex in the bound object moves from its original location if it does not intersect the target object.
<ConformSpaceWarp>.Standoff_Distance <ConformSpaceWarp>.Selected_Verts Float Integer default: 1.0 -- animatable default: 0 -- animatable

The distance maintained between the vertex and the surface of the target object. When on, only the sub-object selection of vertices on the Stack are pushed. When off, all vertices in the object are pushed regardless of the Stack selection: OFF ON
<ConformSpaceWarp>.Icon_Size Float default: 0.0

The size of the icon. Note: There is not a way to set the Wrap To Object using MAXScript in 3ds max 4. Associated Methods:
bindSpaceWarp <node> <conformSpaceWarp_node>

Associated Binding Modifier:

SpaceConform

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

996

Chapter 11

3ds max Objects

SpaceDisplace : SpacewarpObject
Constructor:
spaceDisplace ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Spacedisplace>.strength Float default: 0.0 -- animatable

When set to 0.0, the Displace warp has no effect. Values greater than 0.0 displace object geometry or particles away from the position of the Displace space warp object. Values less than 0.0 displace geometry toward the warp.
<Spacedisplace>.decay Float default: 0.0 -- animatable

By default, the Displace warp has the same strength throughout world space. Increasing Decay causes displacement strength to diminish as distance increases from the position of the Displace warp object.
<Spacedisplace>.lumCenterEnable <Spacedisplace>.lumCenter Boolean Float default: false default: 0.5 -- animatable

Turn on/off use of the luminance center. By default, the Displace space warp centers the luminance by using medium (50%) gray as the zero displacement value. Gray values greater than 128 displace in the outward direction (away from the Displace warp object) and gray values less than 128 displace in the inward direction (toward the Displace warp object).
<Spacedisplace>.bitmap <Spacedisplace>.map <Spacedisplace>.blur <Spacedisplace>.maptype Bitmap TextureMap Float Integer default: undefined default: undefined default: 0.0 default: 0 -- animatable

Bitmap assigned to use for displacement. Texture map assigned to use for displacement. Increase this value to blur or soften the effect of the bitmapped displacement. The map projection type: Planar (Projects the map from a single plane.) Cylindrical (Projects the map as if it were wrapped around the cylinder.) Spherical (Projects the map from a sphere, with singularities at the top and bottom of the sphere, where the bitmap edges meet at the spheres poles.) Shrink Wrap (Truncates the corners of the map and joins them all at a single pole, creating one singularity.)
<Spacedisplace>.length <Spacedisplace>.width Float Float default: 1.0 default: 1.0 -- animatable -- animatable

The length of the bounding box on the space warp gizmo. The width of the bounding box on the space warp gizmo.

SpaceDisplace : SpacewarpObject

997

<Spacedisplace>.height <Spacedisplace>.U_Flip <Spacedisplace>.U_Tile <Spacedisplace>.V_Flip <Spacedisplace>.V_Tile <Spacedisplace>.W_Flip <Spacedisplace>.W_Tile

Float Boolean Float Boolean Float Boolean Float

default: 1.0 default: false default: 1.0 default: false default: 1.0 default: false default: 1.0

-- animatable

The height of the bounding box on the space warp gizmo. When on, reverses the orientation of the map along the U-axis.
-- animatable

The number of times the map repeats along the U-axis. When on, reverses the orientation of the map along the V-axis.
-- animatable

The number of times the map repeats along the U-axis. When on, reverses the orientation of the map along the W-axis.
-- animatable

The number of times the map repeats along the U-axis. The following properties are defined for SpaceDisplace, but are not used:
<Spacedisplace>.axis <Spacedisplace>.cap <Spacedisplace>.useMap <Spacedisplace>.applyMap Integer Boolean Boolean Boolean default: default: default: default: 0 false false false

Associated Methods:
bindSpaceWarp <node> <spaceDisplace_node>

Associated Binding Modifier:

DisplaceBinding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier. Note: When a TextureMap is assigned to map, a Displacement_Map subAnim is added to the parameters. The parameters of the subAnim correspond to the TextureMap properties.

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

998

Chapter 11

3ds max Objects

SpaceFFDBox : SpacewarpObject
Constructor:
spaceFFDBox ...

Note: This class is not available in 3D Studio VIZ. Properties:

<SpaceFFDBox>.length <SpaceFFDBox>.width <SpaceFFDBox>.height <SpaceFFDBox>.dispLattice <SpaceFFDBox>.dispSource <SpaceFFDBox>.deformType Float Float Float Boolean Boolean Integer default: 0.0 default: 0.0 default: 0.0 default: true default: false default: 0 -- animatable -- animatable -- animatable -- alias: Lattice -- alias: Source_Volume

Sets the length of the lattice. Sets the width of the lattice. Sets the length of the lattice. When turned on, lines are drawn connecting the control points to make a grid. When on, the control points and lattice are displayed in their unmodified state. Specifies which vertices are affected by the FFD: Only In Volume (Only vertices that lie inside the source volume are deformed. Vertices outside the source volume are not affected.) All Vertices (All vertices are deformed regardless of whether they lie inside or outside the source volume, depending on the .falloff value.)
<SpaceFFDBox>.falloff Float default: 0.0 -- animatable

The distance from the lattice that the FFD effect will decrease to zero. When this value is set to 0, its effectively turned off, and there is no falloff; that is, all vertices are affected regardless of their distance from the lattice. The units of the Falloff parameter are specified relative to the size of the lattice: A falloff of 1 means that the effect will go to 0 for points that are a lattice width/length/height away from the lattice (depending on which side they are on).
<SpaceFFDBox>.tension <SpaceFFDBox>.continuity Float Float default: 25.0 default: 25.0 -- animatable -- animatable

Sets the tension of the deformation splines. Sets the continuity of the deformation splines. Associated Methods:
bindSpaceWarp <node> <spaceFFDBox_node>

SpaceFFDCyl : SpacewarpObject

999

Associated Binding Modifier:

FFD_Binding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier. Note: The number of control points in a SpaceFFDBox created by MAXScript is always 4x4x4. There is no method for assigning controllers to the FFD control points, nor is there a method for assigning the number or accessing the number of Length, Width, and Height points using MAXScript in 3ds max 4.

See also
Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation (p. 1461) for details on accessing the control points in an FFD.

SpaceFFDCyl : SpacewarpObject
Constructor:
spaceFFDCyl ...

Note: This class is not available in 3D Studio VIZ. Properties:

<SpaceFFDCyl>.radius <SpaceFFDCyl>.height <SpaceFFDCyl>.dispLattice <SpaceFFDCyl>.dispSource <SpaceFFDCyl>.deformType Float Float Boolean Boolean Integer default: 0.0 default: 0.0 default: true default: false default: 0 -- animatable -- animatable -- alias: Lattice -- alias: Source_Volume

Sets the radius of the lattice. Sets the height of the lattice. When on, lines are drawn connecting the control points to make a grid. When on, the control points and lattice are displayed in their unmodified state. Specifies which vertices are affected by the FFD: Only In Volume (Only vertices that lie inside the source volume are deformed. Vertices outside the source volume are not affected.) All Vertices (All vertices are deformed regardless of whether they lie inside or outside the source volume, depending on the .falloff value.)

1000

Chapter 11

3ds max Objects

<SpaceFFDCyl>.falloff

Float

default: 0.0

-- animatable

The distance from the lattice that the FFD effect will decrease to zero. When this spinner is set to 0, its effectively turned off, and there is no falloff; that is, all vertices are affected regardless of their distance from the lattice. The units of the Falloff parameter are specified relative to the size of the lattice: A falloff of 1 means that the effect will go to 0 for points that are a lattice width/length/height away from the lattice (depending on which side they are on).
<SpaceFFDCyl>.tension <SpaceFFDCyl>.continuity Float Float default: 25.0 default: 25.0 -- animatable -- animatable

Sets the tension of the deformation splines. Sets the continuity of the deformation splines. Associated Methods:
bindSpaceWarp <node> <spaceFFDCyl_node>

Associated Binding Modifier:

FFD_Binding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier. Note: The number of control points in a SpaceFFDCyl is always 4x8x4. There is no method for assigning controllers to the FFD control points, nor is there a method for assigning the number or accessing the number of Side, Radial, and Height points using MAXScript in 3ds max 4.

See also
Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation (p. 1461) for details on accessing the control points in an FFD.

SpaceRipple : SpacewarpObject

1001

SpaceRipple : SpacewarpObject
Constructor:
spaceRipple ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Spaceripple>.amplitude1 Float default: 5.0 -- animatable, alias: Amplitude_1

Ripple amplitude along the ripple warp objects local X axis. Amplitude is expressed in active units.
<Spaceripple>.amplitude2 Float default: 5.0 -- animatable, alias: Amplitude_2

Ripple amplitude along the ripple warp objects local Y axis. Amplitude is expressed in active units.
<Spaceripple>.wavelength <Spaceripple>.phase Float Float default: 25.0 -- animatable, alias: Wave_Length default: 0.0 -- animatable

The length of each wave, in active units. Offsets the phase of the wave from its origin at the ripple objects center. Whole values have no effect; only fractional values do. Animating this parameter makes the ripple appear to travel through space.
<Spaceripple>.decay Float default: 0.0 -- animatable

When set to 0.0, the ripple has the same amplitude or amplitudes throughout world space. Increasing the Decay value causes amplitude to diminish as distance increases from the position of the ripple warp object.
<Spaceripple>.circles <Spaceripple>.segments <Spaceripple>.divisions Integer Integer Integer default: 10 default: 16 default: 4

The number of circles in the ripple icon. The number of segments (pie slices) in the ripple icon. Adjusts the size of the ripple icon without altering the ripple effect as scaling would. Associated Methods:
bindSpaceWarp <node> <spaceRipple_node>

Associated Binding Modifier and Properties:

RippleBinding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. The following property is associated with this binding modifier:
<RippleBinding>.Flexibility Float default: 1.0

1002

Chapter 11

3ds max Objects

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

SpaceWave : SpacewarpObject
Constructor:
spaceWave ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Spacewave>.amplitude1 <Spacewave>.amplitude2 <Spacewave>.wavelength <Spacewave>.phase Float Float Float Float default: 5.0 default: 5.0 default: 25.0 default: 0.0 -- animatable, alias: Amplitude_1 -- animatable, alias: Amplitude_2 -- animatable, alias: Wave_Length -- animatable

Wave amplitude along the wave warp objects local X axis. Wave amplitude along the wave warp objects local Y axis. The length of each wave along the waves local Y axis, in active units. Offsets the phase of the wave from its origin at the wave objects center. Whole values have no effect; only fractional values do. Animating this parameter makes the wave appear to travel through space.
<Spacewave>.decay Float default: 0.0 -- animatable

When set to 0.0, the wave has the same amplitude or amplitudes throughout world space. Increasing the Decay value causes amplitude to diminish as distance increases from the position of the wave warp object.
<Spacewave>.circles <Spacewave>.segments <Spacewave>.divisions Integer Integer Integer default: 4 default: 20 default: 10

The number of side segments along the wave objects local X dimension. The number of segments along the wave objects local Y dimension. Adjusts the size of the wave icon without altering the wave effect as scaling would. Associated Methods:
bindSpaceWarp <node> <spaceWave_node>

Associated Binding Modifier and Properties:

WaveBinding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. The following property is associated with this binding modifier:
<WaveBinding>.Flexibility Float default: 1.0

Gravity : SpacewarpObject

1003

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

Spacewarp - Particles and Dynamics

Note: Spacewarp objects are not available in 3D Studio VIZ. The following list shows the particles and dynamics space warp objects: Gravity (p. 1003) Motor (p. 1004) PBomb (p. 1006) Push (p. 1008) Wind (p. 1010)

Gravity : SpacewarpObject
Constructor:
gravity ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Gravity>.strength Float default: 1.0 -- animatable

Increasing Strength increases the effect of gravity; that is, how objects move in relation to the Gravity icons direction arrow. Strength less than 0.0 creates negative gravity, which repels particles moving in the same direction and attracts particles moving in the opposite direction. When Strength is set to 0.0, the Gravity space warp has no effect.
<Gravity>.decay Float default: 1.0 -- animatable

When Decay is set to 0.0, the Gravity space warp has the same strength throughout world space. Increasing the Decay value causes gravity strength to diminish as distance increases from the position of the gravity warp object.
<Gravity>.gravitytype Integer default: 0

Set the type of gravity effect: 0 Planar 1 - Spherical

<Gravity>.showRangeBooleandefault: false

When on, and when the decay value is greater than 0.0, icons in the viewports indicate the range at which the force of gravity is half the maximum value.

1004

Chapter 11

3ds max Objects

<Gravity>.iconsize

Float

default: 10.0

-- animatable

Size of the Gravity warp object icon, in active units. You set the initial size when you drag to create the Gravity object. This value does not change the gravity effect.
<Gravity>.hoopson Boolean default: true

When on, and when the decay value is greater than 0.0, icons in the viewports indicate the range at which the force of gravity is half the maximum value. For the Planar option, the indicators are two planes; for use the Spherical option, the indicator is a doublehooped sphere. Associated Methods:
bindSpaceWarp <node> <gravity_node>

Associated Binding Modifier:

GravityBinding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

Motor : SpacewarpObject
Constructor:
motor ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Motor>.On_Time <Motor>.Off_Time <Motor>.Basic_Torque <Motor>.units Time Time Float Integer default: 0f default: 30f default: 1.0 default: 0 -- animatable

The frame at which the motor effect begins. The frame at which the motor effect ends. The amount of force exerted by the space warp. The unit of measure for the basic torque setting: Newton-meters Pound-feet Pound-inches

Motor : SpacewarpObject

1005

<Motor>.Feedback_On

Integer

default: 0

When on, the force varies depending on the speed of the affected objects relative to the specified Target Speed. When off, the force remains constant, regardless of the speed of the affected objects: OFF ON
<Motor>.Reversible Integer default: 0

When on, if the objects speed exceeds the Target Speed setting, the force is reversed: OFF ON
<Motor>.Target_Revs <Motor>.Revs_Units Float Integer default: 100.0 default: 1 -- animatable

The maximum revolutions before the feedback takes effect. The unit of measure for the target revolutions: RPH RPM RPS
<Motor>.Control_Gain Float default: 50.0 -- animatable

Specifies how quickly the force adjusts to approaching the target speed. If set to 100%, the correction is immediate. If set lower, a slower and looser response occurs.
<Motor>.Enable_Variation Integer default: 0

Turn on to enable the variations: OFF ON

<Motor>.Variation_Period_1 <Motor>.Amplitude_1 <Motor>.Variation_Phase_1 <Motor>.Variation_Period_2 <Motor>.Amplitude_2 <Motor>.Variation_Phase_2 Time Float Float Time Float Float default: 0.625f default: 100.0 default: 0.0 default: 0.625f default: 100.0 default: 0.0 -- animatable -- animatable, angle -- animatable -- animatable, angle

The time over which the noise variation makes a full cycle. The strength of the variation (in percent). Offsets the variation pattern. Provides an additional variation pattern to increase the noise. The strength of the variation of the second wave in (percent). Offsets the variation pattern of the second wave.

1006

Chapter 11

3ds max Objects

<Motor>.Range_Enable

Integer

default: 0

When on, limits the range of the effect to a sphere, displayed as a tri-hooped sphere. The effect falls off increasingly as the particles near the boundary of the sphere. OFF ON
<Motor>.Range_Value <Motor>.Icon_Size Float Float default: 1000.0 -- animatable default: 0.0

The radius of the range of the effect, in units. The size of the Motor icon. This is for display purposes only, and does not alter the Motor effect. Associated Methods:
bindSpaceWarp <node> <motor_node>

Associated Binding Modifier:

MotorMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

PBomb : SpacewarpObject
Constructor:
pbomb ...

Note: This class is not available in 3D Studio VIZ. Properties:

<PBomb>.symmetry Integer default: 0

The shape, or pattern of the blast effect: Spherical (The blast force radiates outward from the PBomb icon in all directions. The icon looks like a spherical anarchists bomb.) Cylindrical (The blast force radiates outward from and normal to the central axis, or core of the cylindrical icon. The icon looks like a stick of dynamite with a fuse.) Planar (The blast force radiates both up and down, perpendicular to the plane of the planar icon. The icon looks like a plane with arrows pointing up and down along the direction of the blast force.)

PBomb : SpacewarpObject

1007

<PBomb>.chaos

Float

default: 10.0

-- percentage

The blast forces vary for each particle or each frame, an effect similar to Brownian motion, with a rate of change in the direction of force equal to the rendering interval rate.
<PBomb>.Start_Time <PBomb>.Lasts_For Time Time default: 30f default: 1f

The frame number at which the impulse forces are first applied to the particles. The number of frames, beyond the first, over which the forces are applied. This value should typically be a small number, such as between 0 and 3.
<PBomb>.strength Float default: 1.0 -- animatable

The change in velocity along the blast vector, in units per frame. Increasing Strength increases the speed with which the particles are blown away from the bomb icon.
<PBomb>.Decay_Type Integer default: 1

Sets the decay type: Unlimited Range (The effects of the bomb icon reach all bound particles throughout the scene. This option ignores the Range setting, which specifies the distance of the PBomb effect.) Linear (The impulse forces decay linearly between the full Strength setting to a value of 0 at the specified Range setting.) Exponential (The impulse forces decay exponentially between the full Strength setting to a value of 0 at the specified Range setting.)
<PBomb>.range Float default: 1000.0 -- animatable

The maximum distance, in units, over which the PBomb icon affects the bound particle system. If the Range is large enough to reach only a portion of the particle system, only that part of the system is affected.
<PBomb>.Icon_Size Float default: 0.0

The overall size of the PBomb icon. Associated Methods:

bindSpaceWarp <node> <pbomb_node>

Associated Binding Modifier:

PBombMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

1008

Chapter 11

3ds max Objects

PushSpaceWarp : SpacewarpObject
Constructor:
pushSpaceWarp ...

Note: This class is not available in 3D Studio VIZ. Properties:

<PushSpaceWarp>.On_Time <PushSpaceWarp>.Off_Time <PushSpaceWarp>.Basic_Force <PushSpaceWarp>.units Time Time Float Integer default: 0f default: 30f default: 1.0 default: 0 -- animatable

The frame in which the space warp begins its effect. The frame in which the space warp ends its effect. The amount of force exerted by the space warp. The unit of force used by the basic force: Newtons Pounds
<PushSpaceWarp>.Feedback_On Integer default: 0

When on, the force varies depending on the speed of the affected objects relative to the specified Target Speed. When off, the force remains constant, regardless of the speed of the affected objects: OFF ON
<PushSpaceWarp>.Reversible Integer default: 0

When on, if the objects speed exceeds the Target Speed setting, the force is reversed OFF ON
<PushSpaceWarp>.Target_Speed <PushSpaceWarp>.Control_Gain Float Float default: 100.0 default: 50.0 -- animatable -- animatable

The maximum speed in units per frame before the Feedback takes effect. Specifies how quickly the force adjusts to approaching the target speed. If set to 100 percent, the correction is immediate. If set lower, a slower and looser response occurs.
<PushSpaceWarp>.Enable_Variation Integer default: 0

Turn on/off variations: OFF ON

<PushSpaceWarp>.Variation_Period_1 <PushSpaceWarp>.Amplitude_1 Time Float default: 0.625f -- animatable default: 100.0 -- animatable

The time over which the noise variation makes a full cycle. The strength of the variation (in percent).

PushSpaceWarp : SpacewarpObject

1009

<PushSpaceWarp>.Variation_Phase_1

Float Time Float Float Integer

default: 0.0

-- animatable, angle

Offsets the variation pattern.

<PushSpaceWarp>.Variation_Period_2 <PushSpaceWarp>.Amplitude_2 <PushSpaceWarp>.Variation_Phase_2 <PushSpaceWarp>.Range_Enable default: 0.625f -- animatable default: 100.0 default: 0.0 default: 0 -- animatable -- animatable, angle

Provides an additional variation pattern (a second wave) to increase the noise. The strength of the variation of the second wave (in percent). Offsets the variation pattern of the second wave When on, limits the range of the effect to a sphere, displayed as a tri-hooped sphere. The effect falls off increasingly as the particles near the boundary of the sphere. OFF ON
<PushSpaceWarp>.Range_Value <PushSpaceWarp>.Icon_Size Float Float default: 1000.0 -- animatable default: 0.0

The radius of the range of the effect, in units. The size of the Push icon. This is for display purposes only, and does not alter the Push effect. Associated Methods:
bindSpaceWarp <node> <pushSpaceWarp_node>

Associated Binding Modifier:

PushMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

1010

Chapter 11

3ds max Objects

Wind : SpacewarpObject
Constructor:
wind ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Wind>.strength Float default: 1.0 -- animatable

Increasing Strength increases the wind effect. Strength less than 0.0 creates a suction. It repels particles moving in the same direction and attracts particles moving in the opposite direction. When Strength is 0.0, the Wind warp has no effect.
<Wind>.decay Float default: 1.0 -- animatable

When Decay is set to 0.0, the Wind warp has the same strength throughout world space. Increasing the Decay value causes wind strength to diminish as distance increases from the position of the Wind warp object.
<Wind>.windtype Integer default: 0

Sets the type of wind: Planar Spherical

<Wind>.turbulence Float default: 1.0 -- animatable

Causes particles to change course randomly as the wind blows them. The greater the value, the greater the turbulence effect.
<Wind>.frequency Float default: 1.0 -- animatable

When set greater than 0.0, causes turbulence to vary periodically over time. This subtle effect is probably not visible unless your bound particle system generates a large number of particles.
<Wind>.windScale Float default: 0.0 -- animatable

Scales the turbulence effect. When Scale is small, turbulence is smoother and more regular. As Scale increases, turbulence grows more irregular and wild.
<Wind>.showRange Boolean default: false

When on, and when the decay value is greater than zero, icons appear in the viewports that represent the range at which the force of wind is half the maximum value.
<Wind>.iconsize <Wind>.hoopson Float Boolean default: 10.0 default: false -- animatable

Size of the Wind warp object icon, in active units. When turned on, icons appear in the viewports that represent the range at which the force of wind is half the maximum value. When you use the Planar option, the indicators are two planes; when you use the Spherical option, the indicator is a double-hooped sphere.

SpaceBend : SpacewarpObject

1011

Associated Methods:
bindSpaceWarp <node> <wind_node>

Associated Binding Modifier:

WindBinding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

Spacewarp - Modifier-Based
Note: Spacewarp objects are not available in 3D Studio VIZ. The following list shows the Modifier-Based space warp objects: SpaceBend (p. 1011) SpaceNoise (p. 1012) SpaceSkew (p. 1014) SpaceStretch (p. 1015) SpaceTaper (p. 1016) SpaceTwist (p. 1017)

SpaceBend : SpacewarpObject
Constructor:
spaceBend ...

Note: This class is not available in 3D Studio VIZ. Properties:

<SpaceBend>.length <SpaceBend>.width <SpaceBend>.height Float Float Float default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable

The length of the warp object. The width of the warp object. The height of the warp object.

1012

Chapter 11

3ds max Objects

<SpaceBend>.decay

Float

default: 0.0

-- animatable

When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially.
<SpaceBend>.angle <SpaceBend>.direction <SpaceBend>.Lower_Limit Float Float Float default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable, alias: Lowerlimit

The angle to bend from the vertical plane. Te direction of the bend relative to the horizontal plane. Te lower boundary in world units from the bend center point beyond which the bend no longer affects geometry.
<SpaceBend>.Upper_Limit Float default: 0.0 -- animatable, alias: Upperlimit

The upper boundary in world units from the bend center point beyond which the bend no longer affects geometry. Associated Methods:
bindSpaceWarp <node> <spaceBend_node>

Associated Binding Modifier:

SimpleOSMToWSMMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

SpaceNoise : SpacewarpObject
Constructor:
spaceNoise ...

Note: This class is not available in 3D Studio VIZ. Properties:

<SpaceNoise>.length <SpaceNoise>.width <SpaceNoise>.height Float Float Float default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable

The length of the warp object. The width of the warp object. The height of the warp object.

SpaceNoise : SpacewarpObject

1013

<SpaceNoise>.decay

Float

default: 0.0

-- animatable

When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially.
<SpaceNoise>.seed Integer default: 0 -- animatable

Generates a random start point from the number you set. Especially useful in creating terrain, because each setting can produce a different configuration.
<SpaceNoise>.scale Float default: 100 -- animatable

The size of the noise effect (not strength). Larger values produce smoother noise, lower values more jagged noise.
<SpaceNoise>.fractal Integer default: 0 -- animatable

When on, produces a fractal effect based on current settings: OFF ON

<SpaceNoise>.Rough <SpaceNoise>.iterations Float Float default: 0.0 default: 6.0 -- animatable -- animatable

Determines the extent of fractal variation. Lower values are less rough than higher values. The number of iterations (or octaves) used by the fractal function. Fewer iterations use less fractal energy and generate a smoother effect. An iteration of 1.0 is the same as turning Fractal off.
<SpaceNoise>.phase <SpaceNoise>.strength Integer Point3 default: 0 default: [0,0,0] -- animatable -- animatable

Shifts the start and end points of the underlying wave. The strength of the noise effect along each of three axes. Enter a value for at least one of these axes to produce a noise effect. Note: Since scale is a property for all nodes, a name conflict exists between the scale property for nodes and the scale property for SpaceNoise. To access the SpaceNoise scale property, you need to access this property as a property of a nodes baseObject property. For example:
sn=spaceNoise() sn.baseObject.scale=150

The Animate Noise property is not accessible using MAXScript in 3ds max 4. Associated Methods:
bindSpaceWarp <node> <spaceNoise_node>

Associated Binding Modifier:

SimpleOSMToWSMMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

1014

Chapter 11

3ds max Objects

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

SpaceSkew : SpacewarpObject
Constructor:
spaceSkew ...

Note: This class is not available in 3D Studio VIZ. Properties:

<SpaceSkew>.length <SpaceSkew>.width <SpaceSkew>.height <SpaceSkew>.decay Float Float Float Float default: 0.0 default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable -- animatable

The length of the warp object. The width of the warp object. The height of the warp object. When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially.
<SpaceSkew>.amount <SpaceSkew>.direction <SpaceSkew>.Lower_Limit Float Float Float default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable

The angle to skew from the vertical plane. The direction of the skew relative to the horizontal plane. The lower limit boundaries in world units from the skew center point, beyond which the skew no longer affects the geometry.
<SpaceSkew>.Upper_Limit Float default: 0.0 -- animatable

The upper limit boundaries in world units from the skew center point, beyond which the skew no longer affects the geometry. Associated Methods:
bindSpaceWarp <node> <spaceSkew_node>

Associated Binding Modifier:

SimpleOSMToWSMMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

SpaceStretch : SpacewarpObject

1015

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

SpaceStretch : SpacewarpObject
Constructor:
spaceStretch ...

Note: This class is not available in 3D Studio VIZ. Properties:

<SpaceStretch>.length <SpaceStretch>.width <SpaceStretch>.height <SpaceStretch>.decay Float Float Float Float default: 0.0 default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable -- animatable

The length of the warp object. The width of the warp object. The height of the warp object. When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially.
<SpaceStretch>.Stretch Float default: 0.0 -- animatable

The base scale factor for all three axes. The scale factor derived from the Stretch value varies according to the sign of the value: Positive stretch values define a scale factor equal to Stretch+1. For example, a stretch value of 1.5 yields a scale factor of 1.5+1=2.5, or 250 percent. Negative stretch values define a scale factor equal to -1/(Stretch-1). For example, a stretch value of -1.5 yields a scale factor of -1/(-1.5-1)=0.4, or 40 percent.
<SpaceStretch>.Amplify Float default: 0.0 -- animatable

The scale factor applied to the minor axes. Amplify generates a multiplier using the same technique as stretch. The multiplier is then applied to the Stretch value before the scale factor for the minor axes is calculated.
<SpaceStretch>.from Float default: 0.0 -- animatable

The boundary of the stretch effect along the negative Stretch Axis. The Lower Limit can be 0 or any negative number.
<SpaceStretch>.to Float default: 0.0 -- animatable

The boundary of the stretch effect along the positive Stretch Axis. The Upper Limit can be 0 or any positive number.

1016

Chapter 11

3ds max Objects

Associated Methods:
bindSpaceWarp <node> <spaceStretch_node>

Associated Binding Modifier:

SimpleOSMToWSMMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

SpaceTaper : SpacewarpObject
Constructor:
spaceTaper ...

Note: This class is not available in 3D Studio VIZ. Properties:

<SpaceTaper>.length <SpaceTaper>.width <SpaceTaper>.height <SpaceTaper>.decay Float Float Float Float default: 0.0 default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable -- animatable

The length of the warp object. The width of the warp object. The height of the warp object. When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially.
<SpaceTaper>.amount <SpaceTaper>.curvature Float Float default: 0.0 default: 0.0 -- animatable -- animatable

The extent to which the ends are scaled. Amount is a relative value with a maximum of 10. Applies a curvature to the sides of the Taper gizmo, thus affecting the shape of the tapered object. Positive values produce an outward curve along the tapered sides, negative values an inward curve. At 0, the sides are unchanged.

SpaceTwist : SpacewarpObject

1017

<SpaceTaper>.symmetry

Integer

default: 0

When on, produces a symmetrical taper around the primary axis. A taper is always symmetrical around the effect axis: OFF ON
<SpaceTaper>.Lower_Limit Float default: 0.0 -- animatable

The lower limit boundaries in world units from the taper center point, beyond which the taper no longer affects the geometry.
<SpaceTaper>.Upper_Limit Float default: 0.0 -- animatable

The upper limit boundaries in world units from the taper center point, beyond which the taper no longer affects the geometry. Associated Methods:
bindSpaceWarp <node> <spaceTaper_node>

Associated Binding Modifier:

SimpleOSMToWSMMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

SpaceTwist : SpacewarpObject
Constructor:
spaceTwist ...

Note: This class is not available in 3D Studio VIZ. Properties:

<SpaceTwist>.length <SpaceTwist>.width <SpaceTwist>.height Float Float Float default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable

The length of the warp object. The width of the warp object. The height of the warp object.

1018

Chapter 11

3ds max Objects

<SpaceTwist>.decay

Float

default: 0.0

-- animatable

When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially.
<SpaceTwist>.angle <SpaceTwist>.bias Float Float default: 0.0 default: 0.0 -- animatable -- animatable

The amount of twist around the vertical axis. Causes the twist rotation to bunch up at either end of the object. When the parameter is negative, the object twists closer to the gizmo center. When the value is positive, the object twists more away from the gizmo center. When the parameter is 0, the twisting is uniform.
<SpaceTwist>.Lower_Limit <SpaceTwist>.Upper_Limit Float Float default: 0.0 default: 0.0 -- animatable -- animatable

The lower limit for the twist effect. The upper limit for the twist effect. Associated Methods:
bindSpaceWarp <node> <spaceTwist_node>

Associated Binding Modifier:

SimpleOSMToWSMMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

Spacewarp - Dynamics Interface

Note: Spacewarp objects are not available in 3D Studio VIZ. The following list shows the Modifier-Based space warp objects: PDynaFlect (p. 1019) SDynaFlect (p. 1020) UDynaFlect (p. 1022)

PDynaFlect : SpacewarpObject

1019

PDynaFlect : SpacewarpObject
Constructor:
PDynaFlect ...

Note: This class is not available in 3D Studio VIZ. Properties:

<PDynaFlect>.Time_On <PDynaFlect>.Time_Off <PDynaFlect>.Reflects <PDynaFlect>.bounce Time Time Float Float default: 0f default: 100f default: 10000.0 default: 1.0 -- animatable -- animatable -- animatable

Specifies the frame at which the deflection begins. Specifies the frame at which the deflection ends. Specifies the percentage of particles to be reflected by the PDynaFlect. This multiplier specifies how much of the initial speed of the particle is maintained after collision with the PDynaFlect.
<PDynaFlect>.Bounce_Variation <PDynaFlect>.chaos <PDynaFlect>.Velocity_Inheritance Float Float Float default: 0.0 default: 0.0 default: 1.0 -- animatable -- animatable -- animatable

Specifies the variation of Bounce applied to the range of particles. Applies a random variation to the bounce angle. Determines how much of a moving PDynaFlects speed is applied to reflected or refracted particles.
<PDynaFlect>.Particle_Mass <PDynaFlect>.Particle_Mass_Units Float Integer default: 1.0 default: 0 -- animatable

Specifies the mass based on the chosen unit. Sets the mass unit for particles: Gram Kilogram Pound
<PDynaFlect>.width Float default: 0.0 -- animatable

Specify the width of the PDynaFlect icon. This is for display purposes only and does not influence the deflector effect.
<PDynaFlect>.height Float default: 0.0 -- animatable

Specify the height of the PDynaFlect icon. This is for display purposes only and does not influence the deflector effect.

1020

Chapter 11

3ds max Objects

Associated Methods:
bindSpaceWarp <node> <PDynaFlect_node>

Associated Binding Modifier:

PDynaFlectMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

SDynaFlect : SpacewarpObject
Constructor:
SDynaFlect ...

Note: This class is not available in 3D Studio VIZ. Properties:

<SDynaFlect>.time on time_on <SDynaFlect>.time off time_off <SDynaFlect>.affects alias: reflects Integer default: 0 -animatable; alias:

The time at which the deflection begins.

Integer default: 16000 -animatable; alias:

The time at which the deflection ends.

Float default: 10000.0 -animatable; percentage;

The percentage of particles to be reflected by the PDynaFlect.

<SDynaFlect>.bouncevar Float percentage; alias: bounce_variation <SDynaFlect>.inheritVelocity velocity_inheritance Float default: 0.0 -animatable;

The variation of Bounce applied to the range of particles.

default: 1.0 -animatable: alias:

Determines how much of a moving PDynaFlects speed is applied to reflected or refracted particles.
<SDynaFlect>.mass particle_mass Float default: 1.0 -animatable; alias:

The mass based on the chosen unit.

SDynaFlect : SpacewarpObject

1021

<SDynaFlect>.mass units particle_mass_units

Integer

default: 0

--

animatable; alias:

The unit to use for particle mass values: Gram Kilogram Pound
<SDynaFlect>.force in x Float Float Float Float Float Float Integer Float default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 --------animatable animatable animatable animatable animatable animatable

Force applied along the X-axis.

<SDynaFlect>.force in y

Force applied along the Y-axis.

<SDynaFlect>.force in z

Force applied along the Z-axis.

<SDynaFlect>.apply at x <SDynaFlect>.apply at y <SDynaFlect>.apply at z <SDynaFlect>.number

Location on the X-axis where force is applied. Location on the Y-axis where force is applied. Location on the Z-axis where force is applied.
default: 0 default: 0.0 animatable animatable

Number of particles.
<SDynaFlect>.friction

When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and theres no change in the particle behavior. As the friction value increases, particles begin to rebound at incorrect angles and with greater speed.
<SDynaFlect>.collider <SDynaFlect>.bounce Undefined default: undefined default: 1.0 -max object

Node which particles deflect off of.

Float -- animatable

Multiplier that specifies how much of the initial speed of the particle is maintained after collision with the SDynaFlect.
<SDynaFlect>.chaos <SDynaFlect>.radius Float Float default: 0.0 default: 0.0 -- animatable -- animatable

Applies a random variation to the bounce angle. Radius of the SdynaFlect icon. This setting also alters the effect of the deflection, because particles bounce off the perimeter of the icon.

1022

Chapter 11

3ds max Objects

Associated Methods:
bindSpaceWarp <node> <SDynaFlect_node>

Associated Binding Modifier:

SDynaFlectMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

UDynaFlect : SpacewarpObject
Constructor:
UDynaFlect ...

Note: This class is not available in 3D Studio VIZ. Properties:

<UDynaFlect>.time on <UDynaFlect>.time off time_off <UDynaFlect>.affects alias: reflects <UDynaFlect>.bounce Integer Integer default: 0 -- animatable; alias: time_on

Time at which the deflector turns on.

default: 1600000 -- animatable; alias:

Time at which the deflector turns off.

Float default: 10000.0 -- animatable; percentage;

The percentage of particles to be reflected by the UDynaFlect.

Float default: 1.0 -- animatable

This multiplier specifies how much of the initial speed of the particle is maintained after collision with the UDynaFlect.
<UDynaFlect>.bouncevar Float percentage; alias: bounce_variation <UDynaFlect>.chaos <UDynaFlect>.Friction default: 0.0 -animatable;

The variation of Bounce applied to the range of particles.

Float Float default: 0.0 default: 0.0 -- animatable -- animatable

Applies a random variation to the bounce angle. When set to 0.0 (the default) the surface of the deflector is treated as frictionless, and theres no change in particle behavior. As Friction increases, particles begin to rebound at incorrect angles and with greater speed.

UDynaFlect : SpacewarpObject

1023

<UDynaFlect>.inheritVelocity velocity_inheritance

Float

default: 1.0

-- animatable; alias:

Determines how much of a moving UDynaFlects speed is applied to reflected or refracted particles.
<UDynaFlect>.mass particle_mass Float default: 1.0 -- animatable; alias:

The mass value of the particle.

<UDynaFlect>.mass units particle_mass_units Integer default: 0 -- animatable; alias:

Sets the unit of mass to use: Gram Kilogram Pound

<UDynaFlect>.force in x Float Float Float Float Float Float Integer default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable -- animatable -- animatable -- animatable

Force applied along the X-axis.

<UDynaFlect>.force in y

Force applied along the Y-axis.

<UDynaFlect>.force in z

Force applied along the Z-axis.

<UDynaFlect>.apply at x <UDynaFlect>.apply at y <UDynaFlect>.apply at z <UDynaFlect>.number

Location on the X-axis where force is applied. Location on the Y-axis where force is applied. Location on the Z-axis where force is applied.
default: 20 -- animatable -max object

Number of particles.
<UDynaFlect>.collider <UDynaFlect>.radius Undefined default: undefined Float default: 0.0

Node which deflects particles.

-- animatable; alias: icon_size

The size of the UDynaFlect icon. Associated Methods:

bindSpaceWarp <node> <UDynaFlect_node>

Associated Binding Modifier:

UDynaFlectMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

1024

Chapter 11

3ds max Objects

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

Spacewarp - Particles Only

Note: Spacewarp objects are not available in 3D Studio VIZ. The following list shows the Particles Only space warp objects: Deflector (p. 1024) Path_Follow (p. 1025) POmniFlect (p. 1027) SDeflector (p. 1030) SOmniFlect (p. 1031) UDeflector (p. 1033) UOmniFlect (p. 1034)

Deflector : SpacewarpObject
Constructor:
deflector ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Deflector>.bounce Float default: 1.0 -- animatable

Controls the speed at which particles bounce off the deflector. At a setting of 1.0, particles bounce off the deflector at the same speed they struck it. At 0.0, particles do not bounce at all. At values between 0.0 and 1.0, particles bounce off the deflector at a speed reduced from their initial speed. At values greater than 1.0, particles bounce off the deflector at a speed greater than their initial speed.
<Deflector>.width <Deflector>.length <Deflector>.variation Float Float default: 10.0 default: 10.0 default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable ---animatable animatable animatable

The deflectors width. The deflectors length.

Float Float Float

The bounce variation.

<Deflector>.chaos <Deflector>.friction

Angle variation after bounce. Amount of friction applied to particle.

Path_Follow : SpacewarpObject

1025

<Deflector>.inheritVelocity Float default: 0.0 <Deflector>.quality Integer default: 20 --

--

animatable

Percentage of deflectors motion inherited by the particle.

animatable

Affects how well the system deflects particles. The lower the number, the more likely it is to leak, but the faster it will go. Associated Methods:
bindSpaceWarp <particlesys_node> <deflector_node>

Associated Binding Modifier:

DeflectorBinding

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

Path_Follow : SpacewarpObject
Constructor:
path_Follow ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Path_Follow>.Range_Limited Integer default: 1

When off, the range of influence of the space warp is limited to the value set in .range_value. When on, the space warp influences all bound particles in the scene, regardless of their distance from the path object. OFF ON
<Path_Follow>.Range_Value Float default: 100.0 -- animatable

The range of influence when Unlimited Range is off. This is the distance between the path object and the particle system. The position of the Path Follow space warps icon is ignored.

1026

Chapter 11

3ds max Objects

<Path_Follow>.Spline_Follow_Type

Integer

default: 1

Set the follow type: Along Offset Splines (The distance between the particle system and the path alter the effect of the particle motion. If the first vertex of the spline is at the birthplace of the particle, the particle follows the spline path. If you move the path away from the particle system, the particles are affected by the offset.) Along Parallel Splines (Particles follow a copy of the selected path, parallel to the particle system. In this mode, the position of the path relative to the particle system does not matter. The orientation of the path, however, affects the particle stream.)
<Path_Follow>.Constant_Speed Integer default: 0

When on, all particles travel at the same speed: OFF ON

<Path_Follow>.Tangent_Chaos Float default: 0.0 -- percentage

Causes particles to converge or diverge toward the path over time, or to simultaneously converge and diverge. You specify the effect by choosing Converge, Diverge, or Both (see following). This provides a tapering effect over the length of the path.
<Path_Follow>.Tang_Chaos_Var <Path_Follow>.Tangent_Dir Float Integer default: 0.0 default: 0

The amount by which .tangent_chaos can vary for each particle. Set behavior of tangent chaos: Converge (When .tangent_chaos is greater than 0, the particles move in toward the path as they follow the path. The effect is that the stream tapers from larger to smaller over time. Diverge (Provides the opposite effect of Converge. The particles diverge from the path over time.) Both (Splits the particle stream, causing some particles to converge and others to diverge.)
<Path_Follow>.Spiral_Chaos Float default: 0.0

The number of turns by which particles spiral about the path. In conjunction with .tangent_chaos, alters the diameter of the spiral.
<Path_Follow>.Spiral_Chaos_Var <Path_Follow>.Spiral_Dir Float Integer default: 0.0 default: 0

The amount by which each particle can vary from the Spiral value. The direction of spiraling behavior: Clockwise Counterclockwise Bidirectional (The stream is splits so that particles spiral in both directions.)
<Path_Follow>.Start_Time Time default: 0f

The frame at which Path Follow begins to influence the particles.

POmniFlect : SpacewarpObject

1027

<Path_Follow>.Travel_Time <Path_Follow>.Travel_Var <Path_Follow>.Stop_Time <Path_Follow>.Icon_Size

Time Float Time Float

default: 30f default: 0.0 default: 100f default: 0.0 -- percentage

The time each particle takes to traverse the path. The amount by which each particles travel time can vary. The frame at which Path Follow releases the particles and no longer influences them. The size of the Path Follow icon. Does not alter the Path Follow effect. Note: There is not a way to select the Path shape object using MAXScript in 3ds max 4. The Seed parameter in not accessible using MAXScript in 3ds max 4. Associated Methods:
bindSpaceWarp <particlesys_node> <path_Follow_node>

Associated Binding Modifier:

PathFollowMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

POmniFlect : SpacewarpObject
Constructor:
POmniFlect ...

Note: This class is not available in 3D Studio VIZ. Properties:

<POmniFlect>.deceleration <POmniFlect>.decel var percentage <POmniFlect>.friction Float Float default: 1.0 default: 0.0 --animatable animatable;

Sets the deceleration of particles.

Affects the variation in deceleration of particles.

Float default: 0.0 -animatable; percentage

When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and theres no change in the particle behavior. As the friction value increases, particles begin to rebound at incorrect angles and with greater speed.

1028

Chapter 11

3ds max Objects

<POmniFlect>.quality

Integer

default: 20

--

animatable

Affects how wells the system deflects particles. The lower the value, the more likely it is to leak, but the faster it will go.
<POmniFlect>.collider <POmniFlect>.time on <POmniFlect>.time off time_off <POmniFlect>.affects reflects Undefined default: undefined Integer Integer default: 0 --max object

Node which particles will deflect off of.

animatable; alias: time_on -animatable; alias:

The frame at which the deflection begins.

default: 16000

The frame at which the deflection ends.

Float default: 10000.0 -animatable; alias:

The percentage of particles to be reflected by the POmniFlect. Controller Scaling: (1 : 100.0)

<POmniFlect>.bounce Float default: 1.0 -- animatable

This multiplier specifies how much of the initial speed of the particle is maintained after collision with the POmniFlect.
<POmniFlect>.bouncevar bounce_variation Float default: 0.0 -animatable; alias:

The variation of Bounce applied to the range of particles. Controller Scaling: (1 : 100.0)
<POmniFlect>.chaos Float default: 0.0 -- animatable

Applies a random variation to the bounce angle. When set to 0.0 (no chaos), all particles bounce off the POmniFlect surface perfectly (like banking pool balls). A non-zero setting causes the deflected particles to scatter.
<POmniFlect>.Refracts <POmniFlect>.pass velocity alias: pass_velocity Float Float default: 100.0 default: 1.0 --- animatable animatable;

The percentage of particles not already reflected that will be refracted by the POmniFlect.

Sets how much of a particles initial speed is maintained after passing through the POmniFlect. The default setting of 1 retains the initial speed is retained, so theres no change. A setting of 0.5 reduces the speed by half.
<POmniFlect>.passvel var Float default: 0.0 percentage; alias: Pass_Velocity_Variation -animatable;

Variation of Pass Velocity applied to the range of particles.

<POmniFlect>.refraction Float percentage; alias: distortion default: 50.0 -animatable;

Controls the angle of refraction. A value of 0 means theres no refraction. A value of 100% sets the angle of the particles to be parallel with the POmniFlect surface. A value of 100% sets the angle perpendicular to the surface. The Distortion effect is reversed when particles strike the POmniFlect from the back side.

POmniFlect : SpacewarpObject

1029

<POmniFlect>.refraction var Float percentage; alias: distortion_variation

default: 0.0

--

animatable;

Range of variation of the Distortion effect.

<POmniFlect>.Diffusion percentage Float default: 0.0 -- animatable,

Applies a diffusion effect to the refraction by randomly modifying each particles Distortion angle by the Diffusion angle. This effectively scatters the particles into a hollow cone.
<POmniFlect>.diffusion var Float percentage; alias: diffusion_variation default: 0.0 -animatable;

Range of variation of the Diffusion value.

<POmniFlect>.inheritVelocity alias: velocity_inheritance Float default: 1.0 -animatable;

Determines how much of a moving POmniFlects speed is applied to reflected or refracted particles.
<POmniFlect>.spawn alias: spawn_percentage Float default: 100.0 -animatable; percentage;

The percentage of particles that can use spawn effects.

<POmniFlect>.Pass_Velocity Float default: 1.0 -- animatable

How much of the particles initial speed is maintained after passing through the POmniFlect.
<POmniFlect>.Pass_Velocity_Variation percentage <POmniFlect>.width Float default: 0.0 -- animatable,

The variation of the Pass Velocity setting applied to the range of particles.
Float default: 0.0 -- animatable

The width of the POmniFlect icon. This is for display purposes only and does not influence the deflector effect.
<POmniFlect>.height Float default: 0.0 -- animatable

The height of the POmniFlect icon. This is for display purposes only and does not influence the deflector effect. Note: getPropnames() and showProperties() show two sets of parameters called Pass_Velocity and Pass_Velocity_Variation. The first set is for Refraction, the second for Spawn Effects Only groups. Due to this sharing of property names, you cannot access the Spawn Effects Only Pass_Velocity and Pass_Velocity_Variation using their property names. You can access the value assigned to these parameters, and their controller if assigned, as subAnims 17 and 18 of the base object. Associated Methods:
bindSpaceWarp <particlesys_node> <POmniFlect_node>

1030

Chapter 11

3ds max Objects

Associated Binding Modifier:

POmniFlectMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

SDeflector : SpacewarpObject
Constructor:
sdeflector ...

Note: This class is not available in 3D Studio VIZ. Properties:

<SDeflector>.friction Float default: 0.0 -- animatable

When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and theres no change in the particle behavior. As the friction value increases, particles begin to rebound at incorrect angles and with greater speed.
<SDeflector>.collider <SDeflector>.bounce UndefinedClass Float default: undefined default: 1.0 -max object

Node which particles deflect off of.

-- animatable

Determines the speed with which particles bounce off the deflector. At 1.0, the particles bounce at the same speed as they approach. At 0, they dont deflect at all.
<SDeflector>.bouncevar <SDeflector>.chaos Float default: 0.0 Float -- animatable -- animatable

The amount by which each particle can vary from the Bounce setting.
default: 0.0

The amount of variation from the perfect angle of reflection (found when Chaos is set to 0.0). 100% induces a variation in reflection angle of up to 90 degrees
<SDeflector>.inheritVelocity velocity_inheritance Float default: 1.0 -- animatable; alias:

When the value is greater than 0, the motion of the deflector affects particles as well as the other settings. For example, to animate the SDeflector passing through a passive array of particles, turn up this value to affect the particles.
<SDeflector>.radius Float default: 0.0 -- animatable

The diameter of the SDeflector icon. This setting also alters the effect of the deflection, because particles bounce off the perimeter of the icon.

SOmniFlect : SpacewarpObject

1031

Associated Methods:
bindSpaceWarp <particlesys_node> <sdeflector_node>

Associated Binding Modifier:

SDeflectMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

SOmniFlect : SpacewarpObject
Constructor:
SOmniFlect ...

Note: This class is not available in 3D Studio VIZ. Properties:

<SOmniFlect>.time on <SOmniFlect>.time off time_off <SOmniFlect>.affects alias: reflects <SOmniFlect>.bounce Float Integer Integer default: 0 -animatable; alias: time_on animatable; alias:

Time at which the deflection starts.

default: 16000 --

Time at which the deflection ends.

default: 100.0 -animatable, percentage;

The percentage of particles to be reflected by the SOmniFlect.

Float default: 1.0 -- animatable

This is a multiplier that specifies how much of the initial speed of the particle is maintained after collision with the SOmniFlect. Using the default setting of 1.0 causes the particle to rebound with the same speed as it collides. A real-world effect would usually be less than 1.0. For a flubber effect, set greater than 1.0.
<SOmniFlect>.bouncevar alias: bounce_variation <SOmniFlect>.chaos Float default: 0.0 -animatable, percentage;

The variation of Bounce applied to the range of particles.

Float default: 0.0 -- animatable

Applies a random variation to the bounce angle. When set to 0.0 (no chaos), all particles bounce off the SOmniFlect surface perfectly (like banking pool balls). A non-zero setting causes the deflected particles to scatter.

1032

Chapter 11

3ds max Objects

<SOmniFlect>.Refracts percentage <SOmniFlect>.pass velocity alias: pass_velocity

Float

default: 100.0

-- animatable,

The percentage of particles not already reflected that will be refracted by the SOmniFlect.
Float default: 1.0 -animatable;

Defines how much of a particles initial speed is maintained after passing through the SOmniFlect. The default setting of 1 retains the initial speed is retained, so theres no change. A setting of 0.5 reduces the speed by half.
<SOmniFlect>.passvel var Float default: 0.0 percentage; alias: pass_velocity_variation <SOmniFlect>.refraction alias: distortion Float default: 50.0 --animatable;

Variation of the Pass Velocity setting applied to the range of particles.

animatable; percentage;

Controls the angle of refraction. A value of 0 means theres no refraction. A value of 100% sets the angle of the particles to be parallel with the SOmniFlect surface. A value of 100% sets the angle perpendicular to the surface. The Distortion effect is reversed when particles strike the SOmniFlect from the back side.
<SOmniFlect>.refraction var Float percentage; alias: distortion_variation default: 0.0 -animatable;

Range of variation of the Distortion effect.

<SOmniFlect>.Diffusion percentage Float default: 0.0 -- animatable,

Applies a diffusion effect to the refraction by randomly modifying each particles Distortion angle by the Diffusion angle. This effectively scatters the particles into a hollow cone.
<SOmniFlect>.diffusion var Float percentage; alias: diffusion_variation default: 0.0 -animatable;

Range of variation of the Diffusion value.

<SOmniFlect>.inheritVelocity velocity_inheritance Float default: 1.0 -- animatable; alias:

Determines how much of a moving SOmniFlects speed is applied to reflected or refracted particles.
<SOmniFlect>.deceleration <SOmniFlect>.decel var <SOmniFlect>.spawn alias: spawn_percentage <SOmniFlect>.friction Float Float Float default: 1.0 -- animatable default: 0.0 -default: 100.0 -animatable; percentage animatable; percentage;

Sets the deceleration of particles. Sets the variation in deceleration of particles.

The percentage of particles that can use spawn effects.

Float default: 0.0 -animatable; percentage

When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and theres no change in the particle behavior. As the friction value increases, particles begin to rebound at incorrect angles and with greater speed.

UDeflector : SpacewarpObject

1033

<SOmniFlect>.collider <SOmniFlect>.radius

Undefined

default: undefined -default: 0.0

max object

Node which particles deflect from.

Float -- animatable

The radius of the SomniFlect icon. Note: getPropnames() and showProperties() show two sets of parameters called Pass_Velocity and Pass_Velocity_Variation. The first set is for Refraction, the second for Spawn Effects Only groups. Due to this sharing of property names, you cannot access the Spawn Effects Only Pass_Velocity and Pass_Velocity_Variation using their property names. You can access the value assigned to these parameters, and their controller if assigned, as subAnims 17 and 18 of the base object. Associated Methods:
bindSpaceWarp <particlesys_node> <SOmniFlect_node>

Associated Binding Modifier:

SOmniFlectMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

UDeflector : SpacewarpObject
Constructor:
uDeflector ...

Note: This class is not available in 3D Studio VIZ. Properties:

<UDeflector>.bounce Float default: 1.0 -- animatable

The speed with which particles bounce off the deflector. At 1.0, the particles bounce at the same speed as they approach. At 0, they dont deflect at all.
<UDeflector>.bouncevar <UDeflector>.chaos Float default: 0.0 Float -- animatable -- animatable

The amount by which each particle can vary from the Bounce setting.
default: 0.0

The amount of variation from the perfect angle of reflection (found when Chaos is set to 0.0). 100% induces a variation in reflection angle of up to 90 degrees.

1034

Chapter 11

3ds max Objects

<UDeflector>.Friction

Float

default: 0.0

-- animatable, percentage

Determines the amount of tangential stick at the surface as particles bounce off the deflector.
<UDeflector>.inheritVelocity velocity_inheritance Float default: 1.0 -- animatable; alias:

When greater than 0, the motion of the deflector affects particles as well as the other settings. For example, to animate the SDeflector passing through a passive array of particles, increase this value to affect the particles.
<UDeflector>.radius <UDeflector>.collider Float default: 0.0 -- animatable; alias: icon_size -max object

The size of the Udeflector icon.

Undefined default: undefined

Node which particles deflect from. Note: There is no way to set the Deflector object using MAXScript in 3ds max 4. Associated Methods:
bindSpaceWarp <particlesys_node> <uDeflector_node>

Associated Binding Modifier:

UDeflectorMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

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

UOmniFlect : SpacewarpObject
Constructor:
UOmniFlect ...

Note: This class is not available in 3D Studio VIZ. Properties:

<UOmniFlect>.time on <UOmniFlect>.time off time_off Integer Integer default: 0 -- animatable; alias: time_on -- animatable; alias:

Time at which deflection starts.

default: 16000

Time at which deflection ends.

UOmniFlect : SpacewarpObject

1035

<UOmniFlect>.affects alias: reflects <UOmniFlect>.bounce

Float

default: 10000.0 --

animatable; percentage;

Percentage of particles to be reflected by the UOmniFlect.

Float default: 1.0 -- animatable

This multiplier specifies how much of the initial speed of the particle is maintained after collision with the UOmniFlect.
<UOmniFlect>.bouncevar alias: bounce_variation <UOmniFlect>.chaos Float default: 0.0 -- animatable; percentage;

Specifies the variation of Bounce applied to the range of particles.

Float default: 0.0 -- animatable

Applies a random variation to the bounce angle. When set to 0.0 (no chaos), all particles bounce off the UOmniFlect surface perfectly (like banking pool balls). A non-zero setting causes the deflected particles to scatter.
<UOmniFlect>.Refracts percentage Float default: 100.0 -- animatable,

Specifies the percentage of particles not already reflected that will be refracted by the UOmniFlect.
<UOmniFlect>.pass velocity pass_velocity Float default: 1.0 -- animatable; alias:

Specifies how much of a particles initial speed is maintained after passing through the UOmniFlect.
<UOmniFlect>.passvel var alias: pass_velocity_variation <UOmniFlect>.refraction alias: distortion Float default: 0.0 -- animatable; percentage;

Specifies the variation of Pass Velocity applied to the range of particles.

Float default: 50.0 -- animatable; percentage;

Controls the angle of refraction. A value of 0 means theres no refraction. A value of 100% sets the angle of the particles to be parallel with the UOmniFlect surface. A value of 100% sets the angle perpendicular to the surface. The Distortion effect is reversed when particles strike the UOmniFlect from the back side.
<UOmniFlect>.refraction var Float percentage; alias: distortion_variation <UOmniFlect>.Diffusion percentage Float default: 0.0 -- animatable;

Specifies a range of variation of the Distortion effect.

default: 0.0 -- animatable,

Applies a diffusion effect to the refraction by randomly modifying each particles Distortion angle by the Diffusion angle. This effectively scatters the particles into a hollow cone.
<UOmniFlect>.diffusion var Float percentage; alias: diffusion_variation default: 0.0 -animatable;

Specifies a range of variation of the Diffusion value.

1036

Chapter 11

3ds max Objects

<UOmniFlect>.Friction

Float

default: 0.0

-- animatable

When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and theres no change in the particle behavior. As the Friction value increases, particles begin to rebound at incorrect angles and with greater speed.
<UOmniFlect>.inheritVelocity velocity_inheritance Float default: 1.0 -- animatable; alias:

Determines how much of a moving UOmniFlects speed is applied to reflected or refracted particles.
<UOmniFlect>.deceleration <UOmniFlect>.decel var <UOmniFlect>.spawn spawn_percentage Float Float Float default: 1.0 default: 0.0 -- animatable -- animatable; percentage

The deceleration value for the particles. The range of variation in decelerations values.
default: 100.0 -- animatable; percentage; alias:

Specifies the percentage of particles that can use spawn effects

<UOmniFlect>.Pass_Velocity Float default: 1.0 -- animatable

Specifies how much of the particles initial speed is maintained after passing through the UOmniFlect.
<UOmniFlect>.Pass_Velocity_Variation percentage <UOmniFlect>.radius <UOmniFlect>.collider Float Float default: 0.0 -- animatable,

Specifies the variation of the Pass Velocity setting applied to the range of particles.
default: 0.0 -- animatable; alias: icon_size -max object

The size of the UOmniFlect icon.

UndefinedClass default: undefined

Node which particles deflect from. Note: getPropnames() and showProperties() show two sets of parameters called Pass_Velocity and Pass_Velocity_Variation. The first set is for Refraction, the second for Spawn Effects Only groups. Due to this sharing of property names, you cannot access the Spawn Effects Only Pass_Velocity and Pass_Velocity_Variation using their property names. You can access the value assigned to these parameters, and their controller if assigned, as subAnims 17 and 18 of the base object. Associated Methods:
bindSpaceWarp <particlesys_node> <UOmniFlect_node>

Associated Binding Modifier:

UOmniFlectMod

This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

XRefObject : Node

1037

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

XRef Objects and Scenes

XRefObject : Node
A XRefObject value represents an XRef object in 3ds max. A XRefObject value is returned when the xrefs.addNewXRefObject() function is called. There are two objects associated with an XRef object in 3ds max the non-proxy object and the proxy object. The proxy object is typically a lower resolution object that is used as a standin for the non-proxy object in the viewports. Constructor:
xrefs.addNewXRefObject <filename_string> <objectname_string> [#proxy]

Loads the specified node object from the specified scene file as an XRef object. The case of objectname_string must match the objects name in the scene file. If #proxy is specified, the node object is loaded as the proxy object, otherwise it is loaded as the non-proxy object. The XRefObject is always loaded at world center. Properties:
<XRefObject>.proxyFileName String String String default: varies default: varies default: varies

The file name of the proxy object.

<XRefObject>.fileName

The file name of the non-proxy object.

<XRefObject>.currentFileName

The file name of the non-proxy object if the useProxy property is false, the file name of the proxy object if the useProxy property is true.
<XRefObject>.objectName String String String default: varies default: varies default: varies

The name of the proxy object.

<XRefObject>.proxyObjectName

The name of the non-proxy object.

<XRefObject>.currentObjectName

The name of the non-proxy object if the useProxy property is false, the name of the proxy object if the useProxy property is true.
<XRefObject>.useProxy Boolean default: varies

If true, the proxy object will be displayed in the viewports, otherwise the non-proxy object will be displayed. If the XRef object is added to the scene using the xrefs.addNewXRefObject() method, this parameters default value will be true if #proxy is specified, false otherwise.

1038

Chapter 11

3ds max Objects

<XRefObject>.renderProxy

Boolean

default: false

If true, the proxy object will be rendered, otherwise the non-proxy object will be rendered.
<XRefObject>.updateMaterial <XRefObject>.ignoreAnimation Boolean Boolean default: false default: false

If true, sets the Update Material option on. If true, sets the Ignore Animation option on. Methods:
updateXRef <XRefObject>

Reloads the XRef object.

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

XRefScene Values
A XRefScene value represents a XRef Scene object in 3ds max. A XRefScene value is returned when the xref.addNewXRefFile() and xref.getXRefFile() functions are called. XRef Scene objects can be nested. For example, scene file A can contain an XRef Scene object specifying XRef file B, and XRef file B can contain an XRef Scene object specifying XRef file C (eg: A xrefs B, and B xrefs C). To provide access to the nested XRef scene objects, the applicable XRefScene methods provide an optional root keyword parameter. If this argument is provided then these methods act on the root node of the specified XRefScene value, otherwise they act on root node of the current scene. To get to C from A, you load A and do something like:
bXref = xrefs.getXRefFile 1 -- taken from root node of current scene cXref = xrefs.getXRefFile 1 root:bXref -- taken from root of bXref cRoot = cXref.tree -- to get root of C

Constructor:
xrefs.addNewXRefFile <filename_string> [ #noLoad ] [root:<XRefScene>]

Adds a new XRef Scene object and returns a XRefScene value. If #noLoad is not specified, the XRef Scene file is loaded immediately and the scene updated. If #noLoad is specified, the scene is not updated until the user requests it. Use the updateXRef() method to load the XRef Scene object. If root:<XRefScene> is specified, the XRef Scene object is treated in the current file during the current session as if it was an XRef Scene object in the file corresponding to the XRefScene value specified. If the specified root XRef Scene object is reloaded, either because the current scene was saved and then reloaded, or because updateXRef() was executed on the root XRef Scene object, the XRef Scene object is deleted from the scene.

XRefScene Values

1039

xrefs.getXRefFile <index> [root:<XRefScene>]

If root is not specified, returns the XRefScene value corresponding to the indexed XRef Scene object in the XRef Scenes dialog. If the root:<XRefScene> is specified, the XRefScene value corresponding to a nested XRef Scene object within the XRefScenes XRef Scene object is returned. The index is 1-based, and corresponds to the order of the XRef Scene objects listed in the XRef Scenes dialog. You can use the xrefs.getXRefFileCount() method to determine the number of XRef Scene objects in the scene. Properties:
<XRefScene>.filename String default: varies

The file name of the XRef Scene object. If you change this property to a new scene file name, the objects in the specified file are displayed, replacing the objects from the initial scene file.
<XRefScene>.tree Node

The root node of the XRef Scene object. This is a read-only property. You can access the children objects in an XRef Scene object using this property. For example:
aXref=xrefs.getXRefFile 1 aXref.tree.children ----aXref.tree.children[1].width -<XRefScene>.parent Node returns first XRef Scene object objects in the XRef Scene object, for example, may return: #children($Box01, $Box02) returns width value of $Box01 default: undefined

The parent of the XRef Scene object. By default this is undefined but can be set to any node in the scene.
<XRefScene>.autoUpdate <XRefScene>.boxDisp <XRefScene>.hidden <XRefScene>.disabled <XRefScene>.ignoreLights <XRefScene>.ignoreCameras <XRefScene>.ignoreShapes <XRefScene>.ignoreHelpers <XRefScene>.ignoreAnimation Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean default: false default: false default: false default: false default: false default: false default: false default: false default: false

If true, automatic XRef file updating is on. If true, all nodes the in the XRef Scene object are displayed in Box display mode. If true, the XRef Scene object is hidden. If true, the XRef Scene object is disabled. If true, the lights in the XRef Scene object will not be displayed. If true, the cameras in the XRef Scene object will not be displayed. If true, the shapes in the XRef Scene object will not be displayed. If true, the helpers in the XRef Scene object will not be displayed. If true, any animation in the XRef Scene object will be ignored.

1040

Chapter 11

3ds max Objects

Methods:
delete <XRefScene>

Deletes the XRef Scene object.

merge <XRefScene>

Merges the nodes in the XRef Scene object into the scene and deletes the XRef Scene object.
updateXRef <XRefScene>

Tries to reload the XRef Scene object. Returns true if the operation is successful, false otherwise.
flagChanged <XRefScene>

This method indicates that the specified XRef Scene object has been changed and should be updated. Use the xrefs.updateChangedXRefs() method to update the changed XRef Scene objects. Associated Methods:
xrefs.getXRefFileCount [root:<XRefScene>]

If root is not specified, returns the total number of top-level XRef Scene objects in the scene. If the root:<XRefScene> is specified, the total number of XRef Scene objects in the nested XRef file within the XRefScenes XRef file is returned.
xrefs.deleteAllXRefs [root:<XRefScene>]

If root is not specified, deletes all XRef Scene objects. If the root:<XRefScene> is specified, only the specified XRefScenes XRef Scene object, and its nested XRef Scene objects, are deleted.
xrefs.updateChangedXRefs [#noRedraw] [root:<XRefScene>]

If root is not specified, updates all XRef Scene objects flagged as changed. If the root:<XRefScene> is specified, only the specified XRefScenes XRef Scene objects flagged as changed are updated. If #noRedraw is specified, the viewports wont be updated after the XRef Scene objects are loaded. Returns true if the XRef Scene objects were loaded okay, otherwise false.
xrefs.findUnresolvedXRefs [root:<XRefScene>]

If root is not specified, returns an array of file name strings for all the unresolved XRef Scene objects. If the root:<XRefScene> is specified, only the unresolved XRef Scene objects within the specified XRefScenes XRef Scene object are returned.
xrefs.attemptUnresolvedXRefs [root:<XRefScene>]

If root is not specified, tries to load any XRef Scene objects that are currently unresolved. If the root:<XRefScene> is specified, only the unresolved XRef Scene objects within the specified XRefScenes XRef Scene object are loaded.

Editable_Mesh : GeometryClass and TriMesh : Value

1041

Editable Meshes, Splines, and Patches

Editable Meshes, Splines and Patches provide access to the basic components of meshes, splines, and patches. These classes are described in the following topics: Editable_Mesh and TriMesh (p. 1041) SplineShape (p. 1079) Patch (p. 1088)

Editable_Mesh : GeometryClass and TriMesh : Value

Editable_Mesh is the class of node objects that are the result of collapsing a modifier stack to an editable mesh object. Many of the mesh operations in MAXScript that modify meshes will only work on Editable_Mesh scene nodes. The TriMesh class is a MAXScript value wrapper for the low-level 3ds max SDK Mesh class used extensively in mesh-based objects and modifiers in 3ds max. Meshes hold the actual vertex and face arrays, and so on, in a triangular mesh. For example, an Editable_Mesh object contains an instance of a Mesh. The prime purpose of the TriMesh class is to allow scripted primitive object plug-ins to access and build the Mesh object inside geometry objects. This class has a large range of mesh manipulation and construction functions, corresponding to the low-level mesh operations on Editable Mesh scene nodes. The properties and methods described in this topic are applicable to both Editable_Mesh objects and TriMesh values are signified by a value type of <mesh>. The properties and methods applicable to just TriMesh values are signified by a value type of <trimesh>.

See also
Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Class and Object Inspector Functions (p. 799) Scripting Vertex and Control Point Animation (p. 1461) Note: 1. Only the update() function updates the meshs internal caches and images in 3ds max viewports. This is because updates can be computationally expensive and you dont want them performed on every function call. However, you must make sure you do call the update() function after a series of changes and before the mesh is to be worked on in 3ds max or by other functions in MAXScript. Coordinates are given in the MAXScript working coordinate system.

2.

1042

Chapter 11

3ds max Objects

3.

If the update() function is called on an object that is selected and currently open in the Modify panel, it will drop the current selection in order to avoid a potential crash in 3ds max, which at the moment, does not support scripted changes to an object open in the Modify panel. If you are creating or modifying a mesh, and have not yet run update() on the mesh, 3ds max will crash if you minimize and then maximize the 3ds max window. This is because an only partially created mesh is created, and the internal 3ds max mesh structure is left in an unstable state.

4.

Constructors (Editable_Mesh):
mesh [ length:<integer> ] [ width:<integer> ] \ [ lengthsegs:<integer> ] [ widthsegs:<integer> ]

Creates a flat rectangular mesh with the given size and number of segments. The default length and width are 50, the default number of segments is 5.
mesh [ numverts:<number> ] [ numfaces:<number> ]

Creates a mesh of the given geometry but with no topology (i.e., no faces or edges). You have to individually place the vertices and create the faces from the vertices. The default number of vertices and faces are 36 and 50, respectively.
mesh vertices:<array_of_point3s> \ faces:<array_of_point3s> \ [ materialIDs:<array_of_integers> ] \ [ tverts:<array_of_point3s> ]

Creates a mesh from an array of vertices and faces. Each Point3 value in the vertices array specifies the position of the vertex in the current coordinate system. Each Point3 value in the faces array specifies the 3 vertex indices that form the face. The materialIDs array specifies the material ID to be assigned to each face. Each Point3 value in the tverts array specifies the UVW coordinates of the texture vertices. See Texture Mapping in the methods section for more information on texture vertices. An example of construction a mesh using this form of the constructor is:
mesh vertices:#([0,0,0],[10,0,0],[0,10,0],[10,10,0]) \ faces:#([1,2,3],[2,4,3]) materialIDS:#(1,2) collapseStack <node> -- mapped

Collapses the object space modifiers out of a stack, leaving a resultant Editable Mesh as the base object of the node. If there are no object space modifiers in the stack when this is called, no action is taken. So, if you want to force an object to be an editable mesh (for example, for the mesh operation listed below), you can apply a null modifier and then collapse the stack:
addModifier $foo (normalModifier()) collapseStack $foo

collapseStack() does not collapse the effect of any world space modifiers (including bindings to space warps). The world space modifiers remain on the objects stack. To collapse an object to a mesh use the snapshot() method.

Editable_Mesh : GeometryClass and TriMesh : Value

1043

snapshot <node>

-- mapped

This function provides functionality similar to the SnapShot tool in 3ds max. It generates a new node that contains a copy of the world-state mesh of the source <node> at the time that the snapshot is made. Any existing modifiers are collapsed out of the new node and the mesh snapshot accounts for any space warps currently applied.
convertToMesh <node> -- mapped

Converts appropriate scene object types into Editable Meshes. It is similar to collapseStack() in that it will remove all object space modifiers present, but unlike collapseStack() it will always replace the base object with an editable mesh version, even if there are no modifiers present. It can be applied to any object that an Edit Mesh modifier can work on, such as geometry and shapes, but not helpers, space warps, lights, etc.
convertTo <node> [ TriMeshGeometry | Mesh ] -- mapped

Converts appropriate scene object types into Editable Meshes. Operates in an identical manner to convertToMesh(). Constructors (TriMesh):
TriMesh()

Creates an empty TriMesh. Use the methods listed below to build the mesh.
<node>.mesh

Extracts a copy of a nodes world state if it is convertible to a mesh.

<editable_mesh_baseobject>.mesh

Extracts a copy of base objects mesh.

<trimesh>.mesh

Extracts a copy of another TriMeshs mesh. Note: GeometryClass boolean operations (p. 852) also create editable_mesh objects. Operators: The following operators perform boolean operations on meshes. These operations destructively modify the first operand mesh to contain the boolean result, as do the same boolean <node> operations.
<mesh> + <mesh> <mesh> - <mesh> <mesh> * <mesh> -- union -- difference -- intersection

Properties:
<mesh>.numverts Integer Integer Integer

Get or set the number of vertices

<mesh>.numfaces

Get or set the number of faces

<mesh>.numtverts

Get or set the number of texture vertices

1044

Chapter 11

3ds max Objects

<mesh>.numcpvverts <mesh>.mesh

Integer TriMesh

Get or set the number of color-per-vertex vertices Reading this property yields a copy of the mesh, taken from after any modifiers are applied, but before any space warps are applied. Assigning to this property sets the mesh to the TriMesh value given. You can use this property, along with copy() and the <node_or_baseobject>.mesh property to build a TriMesh from other objects meshes. The following properties are not applicable to TriMeshes:
<mesh>.selectedVerts VertexArray

Get the currently selected vertices of the Editable_Mesh object. See VertexSelection Values (p. 786).
<mesh>.verts <mesh>.selectedFaces VertexArray FaceArray

Get all of the vertices of the Editable_Mesh object. See VertexSelection Values (p. 786). Get the currently selected faces of the Editable_Mesh object. See FaceSelection Values (p. 788).
<mesh>.Faces <mesh>.selectedEdges FaceArray EdgeArray

Get all of the faces of the Editable_Mesh object. See FaceSelection Values (p. 788). Get the currently selected edges of the Editable_Mesh object. See EdgeSelection Values (p. 790).
<mesh>.Edges <mesh>.displacementMapping EdgeArray Boolean

Get all of the edges of the Editable_Mesh object. See EdgeSelection Values (p. 790). Get or set whether to perform displacement mapping for the Editable_Mesh object. There is no corresponding user interface element for this property.
<mesh>.subdivisionDisplacement Boolean

Get or set whether to perform subdivision displacement for the Editable_Mesh object. This property corresponds to the Subdivision Displacement checkbox in the Surface Properties rollout.
<mesh>.splitMesh Boolean

Get or set whether to split the mesh during subdivision displacement. This property corresponds to the Split Mesh checkbox in the Surface Properties rollout. Setting this property will enable subdivisionDisplacement if it is set to false. You can both read and assign to the above properties with the exception of the properties that return a VertexSelection, FaceSelection, or EdgeSelection. If you assign numbers to them to add room for more vertices or faces, the mesh will lose all current topology/geometry (i.e., vertices, faces, and edges), assuming you want to rebuild it from scratch. If you want to retain the current topology/ geometry, use the setNumVerts(), setNumTVerts() and setNumFaces() methods described below.

Editable_Mesh : GeometryClass and TriMesh : Value

1045

Up to N vertex coordinates are available as properties on Editable_Mesh objects, where N is the number of vertices in the mesh. A vertex is available as a property once a controller has been assigned to the vertex. Controllers can be assigned to vertices using the animateVertex() method described in the Scripting Vertex and Control Point Animation (p. 1461) topic. For example, if a sphere object is collapsed to an Editable_Mesh, and some of its vertices are animated, the properties for the vertices would be similar to:
$Sphere01.vertex_209 $Sphere01.vertex_210 $Sphere01.vertex_211 Point3 Point3 Point3 value: [7.9,-40.0,0.0] -- animatable value: [-7.8,-39.3,-7.9] -- animatable value: [0.0,-40.0,-7.9] -- animatable

Methods: The following methods operate on the base object in a node if no object space modifiers are present. If object space modifiers are present, the mesh get operations access the world-state mesh, after the object space modifiers have been applied. The mesh set operations only work on base object Editable Meshes and signal an error if there are object space modifiers present, informing you that the mesh is not changeable when modifiers are present. You can convert objects to Editable Meshes with the collapseStack(), snapshot(), and convertToMesh() methods. If there are no object space modifiers present, both get and set operations work on the base editable mesh object. Because the mesh get operations require a mesh, the combination of base object and modifiers must yield a mesh at the top of the modifier stack. This excludes combinations such as Patch base-objects and deformer modifiers such as bend and twist, because they pass a patch object, not a mesh up the stack. Applying an Edit Mesh modifier always forces the world-state object to be a mesh. If world space modifiers are present, the mesh get operations access the world-state mesh, after any object space modifiers have been applied, but before the world space modifiers have been applied. Currently you can not access the position of vertices as affected by world space modifiers. The mesh set operations will work if only world space modifiers are applied to the object. Setting a vertices position in such a case will set its position before the world space modifiers have been applied. You can create a new mesh object using the snapshot() method which accounts for the effects of world space modifiers. The update() method makes any scripted changes to a base object mesh visible to 3ds max and you must call this function at some point after modifying a mesh so that 3ds max sees a valid mesh. Because this update can be a compute-intensive operation, it is made available as a separate function so you perform many changes on a mesh and then invoke the update just once to signal all the changes to 3ds max. All vertex and face indexes start at 1, following the other indexing conventions in MAXScript. All coordinates used are relative to the current working coordinate system. -- General Methods
update <mesh> [ geometry:<boolean> ] [ topology:<boolean> ] \ [ normals:<boolean> ] -- mapped

The three optional keyword arguments provide control over the kind of updating done to the mesh. If the geometry: argument is true, the geometry cache is rebuilt (normals and edge list) and the meshs bounding box is invalidated. If the topology: argument is true,

1046

Chapter 11

3ds max Objects

the edge and strip databases will be rebuilt. If normals: is true, the face normals are computed. All flags default to true, so that a simple call to update() causes a complete reconstruction of all the caches.
attach <mesh> <node>

Corresponds to the mesh attach function in the Editable Mesh Modify panel allowing you to construct a mesh by adding complete objects to it. Extracts the mesh from <node> (first converting to a mesh if need), adds it to <mesh> which must be an Editable Mesh object and then deletes <node>. The materials and material IDs in <node> are merged into <node> using the default settings for the attach operation in the Editable Mesh Modify panel. This method is not applicable to TriMeshes.
meshop.attach {<target_editable_mesh_node> | <target_mesh>} {<source_node> | <source_mesh>} \ targetNode:<node=unsupplied> sourceNode:<node=unsupplied> \ attachMat:<{#neither | #MatToID | #IDToMat}=#neither> condenseMat:<boolean=true> \ deleteSourceNode:<boolean=true>

Attaches the source mesh to the target mesh. If the target or source is specified as a mesh rather than a node, the mesh is attached using the local coordinate system of the mesh, and no material correction is performed. To get around this, if the target or source is a mesh, the corresponding targetNode or sourceNode named parameter is checked to see if a node is specified and, if it is, the transform and material for that node is used. If the source or target is specified as a node, the corresponding targetNode or sourceNode named parameter is not checked. The attachMat and condenseMat options correspond to the attach options in editable mesh. condenseMat is applicable only if attachMat:#IDToMat is specified. If deleteSourceNode:false is not specified, and the source was specified as a node, or as a mesh and a sourceNode was specified, the source node is deleted after the attach. Examples:
meshop.attach $.baseobject $sphere02 targetNode:$ meshop.attach $box01 $box02 attachMat:#IDToMat condenseMat:true deleteSourceNode:false meshop.getUIParam meshop.getUIParam meshop.setUIParam meshop.setUIParam <boolean> } <mesh> <node> <mesh> <node> <param_name> [ <modifier_or_index> ] <param_name> <param_name> { <float> | <boolean> } [ <modifier_or_index> ] <param_name> { <number> |

Get/set a user-interface value. The optional <modifier_or_index> identifies the Edit Mesh modifier on the given scene object to set the parameter value for. These methods are UI-dependent, and require that the specified editable mesh or Edit Mesh modifier be currently displayed in the Modify panel. The valid param_name values, their meaning, and parameter value type are: #SelByVertSelection - By Vertex (boolean) #IgBackSelection - Ignore Backfacing (boolean) #IgnoreVisSelection - Ignore Visibile Edges (boolean)

Editable_Mesh : GeometryClass and TriMesh : Value

1047

#PolyThreshSelection - Planar Threshold (number) #SoftSelSoft Selection - Use Soft Selection (boolean) #SSUseEDistSoft Selection - Edge Distance (boolean) #SSEDistSoft Selection - Edge Distance (number) [note: if value hasnt been changed, returns a value of 0] #SSBackSoft Selection - Ignore Backfacing (boolean) [note: this is the inverse of the UI element] #FalloffSoft Selection - Falloff (number) #PinchSoft Selection - Pinch (number) #BubbleSoft Selection - Bubble (number) #WeldDistWeld - Distance (number) #WeldBoxSizeWeld - Box Size in Pixels (number) #ExtrudeTypeExtrude/Chamfer (boolean) [note: true - Group; false - Local] #ShowVNormalsShow Vertex Normals (boolean) #ShowFNormalsShow Face Normals (boolean) #NormalSizeNormal Scale (number)

Vertex methods
meshop.breakVerts <Mesh mesh> <vertlist>

For each vertex in <vertlist>, N-1 new vertices are created at the same location, where N is the number of faces using that vertex. Each of these faces will use one of these vertices.
meshop.chamferVerts <Mesh mesh> <vertlist> <float amount>

Chamfers the specified vertices by the specified amount.

meshop.cloneVerts <Mesh mesh> <vertlist>

Clones the specified vertices.

meshop.cutVert <Mesh mesh> <int start_vert> <point3 destination> <point3 projdir> node:<node=unsupplied>

If <mesh> is a node, or if <mesh> is an Editable Mesh and <node> is specified, destination and projdir are in the current coordinate system context. If <mesh> is an Editable Mesh and <node> is not specified, destination and projdir are in the meshs local coordinate system. Returns the index of the new vertex if created, or undefined if no vertex was created.
meshop.deleteIsoVerts <Mesh mesh>

Deletes all vertices not used by a face.

meshop.deleteVerts <Mesh mesh> <vertlist>

Deletes the specified vertices.

1048

Chapter 11

3ds max Objects

meshop.detachVerts <Mesh mesh> <vertlist> delete:<boolean=true> asMesh:<boolean=false>

Detaches the faces used by the specified vertices. If <delete> is true, the faces are deleted after being detached. If <delete> is false, the faces are not deleted. If <asMesh> is true, the faces are detached and returned as a Mesh value. If <asMesh> is false, the faces are detached as an element in the mesh and a value of OK is returned.
meshop.getHiddenVerts <Mesh mesh>

Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices that are hidden.
meshop.getIsoVerts <Mesh mesh>

Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices that are not used by a face.
meshop.getNumVerts <Mesh mesh>

Returns the number of vertices in the mesh.

meshop.getVert <Mesh mesh> <int vertIndex> node:<node=unsupplied>

Returns the position of the specified vertex. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position returned is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the return value is in the meshs local coordinate system.
meshop.getVertexAngles <Mesh mesh> <vertlist>

This method calculates, for each vertex, the sum of the angles of this vertexs corner in each face its on. So for instance, a point lying in the middle of a grid would always have vertex angle 2*PI, whereas a corner of a box would only have 270. Returns an array of size=(#vertices in mesh). The array element for any vertices not specified in <vertlist> will contain the value 0.
meshop.getVertsByColor <Mesh mesh> <color color> <float red_thresh> <float green_thresh> <float blue_thresh> channel:<int=0>

Returns the vertices whose vertex color is within the color range as a <bitarray>. The range values shouldbe in the range of 0 to 255.
meshop.getVertsByColor <Mesh mesh> <point3 uvw> <Float u_thresh> <Float v_thresh> <Float w_thresh> channel:<int=0>

Returns the vertices whose vertex UVW is within the UVW range as a <bitarray>. The range values shouldbe in the range of 0 to 1.
meshop.makeVertsPlanar <Mesh mesh> <vertlist>

Moves the specified vertices so that they are planar.

meshop.minVertexDistanceFrom <Mesh mesh> <int vertIndex> <vertlist>

Returns the minimal distance from <vertIndex> to the vertices specified in <vertlist>.

Editable_Mesh : GeometryClass and TriMesh : Value

1049

meshop.minVertexDistancesFrom <Mesh mesh> <vertlist> <int iterations>

This function computes distances from selected vertices (as indicated by <vertlist>) to non-selected ones along edge paths. Returns an array of size=(#vertices in mesh). Each element in this array is set to -1 if there is no selection. Otherwise, selected vertices have an array element value of 0; non-selected vertices that are <iterations> or fewer edges away from a selected vertex are assigned the shortest edge-path distance to a selected vertex; and non-selected vertices that are more than <iterations> edges away are set to -1. If <iterations> is 0, the distances are computed from each vertex to the nearest selected vertex, regardless of topology. This is a VERY EXPENSIVE ALGORITHM, which takes almost 4 times as long for twice as many vertices. If <iterations> is non-zero, it represents the number of edges one should travel in trying to find the nearest selected vertex -- this means that it only takes twice as long for twice as many verts. (This is like the Edge Distance parameter in EMeshs Soft Selection dialog.)
meshop.moveVert <Mesh mesh> <vertlist> <point3 offset> node:<node=unsupplied>

Moves the specified vertices by <offset>. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the offset is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the offset is in the meshs local coordinate system.
meshop.moveVertsToPlane <Mesh mesh> <vertlist> <point3 normal> <float offset> node:<node=unsupplied>

Moves the specified vertices into the specified plane. The target plane is defined as all points which, when DotProdd with N, return offset. All vertices are moved along the normal vector N. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the normal is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the normal is in the meshs local coordinate system.
meshop.setHiddenVerts <Mesh mesh> <vertlist>

Sets the specified vertices as hidden, and non-specified vertices as visible.

meshop.setNumVerts <Mesh mesh> <int>

Sets the number of vertices in the mesh. Any new vertices are created at [0,0,0] in the meshs local coordinate system.
meshop.setVert <Mesh mesh> <vertlist> <point3 pos> node:<node=unsupplied>

Moves the specified vertices to the specified position. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the meshs local coordinate system.
meshop.setVertColor <Mesh mesh> <int mapChannel> <vertlist> <Color color>

Sets the vertex color for the specified vertices in the specified <mapChannel>.
meshop.weldVertsByThreshold <Mesh mesh> <vertlist> <float threshold>

Welds the specified vertices that are within the threshold distance.

1050

Chapter 11

3ds max Objects

meshop.weldVerts - renamed to weldVertSet meshop.weldVertSet <Mesh mesh> <vertlist> weldpoint:<point3=unsupplied> node:<node=unsupplied>

Welds the specified vertices. If <weldpoint> is specified, the resulting vertex is positioned at that point. The result is put at the average location of the selected vertices. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the meshs local coordinate system. If <weldpoint> is not specified, the resulting vertex is positioned at the average location of the specified vertices.

Vertex data methods

meshop.setNumVDataChannels <Mesh mesh> <Integer count> keep:<boolean=false>]

Sets the number of vertex data channels available. The number of vertex data channels can be set from 0 to 100. The first ten channels are for Discreets use only. If keep is false or not specified, the old channel data is discarded. If true, the old channel data is retained after the resize. The predefined channels are: channel 1: Soft Selection channel 2: Vertex weights (for NURMS MeshSmooth) channel 3: Vertex Alpha values channel 4: Cornering values for subdivision use
meshop.getNumVDataChannels <Mesh mesh>

Returns the number of vertex data channels available as an <integer>.

meshop.setVDataChannelSupport <Mesh mesh> <Integer vdChannel> <Boolean support>

Sets whether the specified vertex data channel is supported or not. If support is true, and thechannel support state is currently false, a new vertex data array of the same size as the number of vertices in the mesh is allocated. If support is false, and the channel support state is currently true, the existing vertex data channel array is deallocated. If support and the current channel support state are both the same, no action is performed. setNumVDataChannels() is automatically called if the specified vertex data channel is not available. vdChannel index values are 1-based, with channels 1 and 2 being the Vertex Soft Selection and Vertex Weight channels.
meshop.getVDataChannelSupport <Mesh mesh> <Integer vdChannel>

Returns whether the specified vertex data channel is supported.

meshop.getVDataValue <Mesh mesh> <Integer vdChannel> <Integer vert_index>

Returns the floating point data value associated with vertex vert_index in vertex data channel vdChannel as a <float>.
meshop.setVDataValue <Mesh mesh> <Integer vdChannel> <Integer vert_index> <Float value>

Sets the floating point data value associated with vertex vert_index in vertex data channel vdChannel.

Editable_Mesh : GeometryClass and TriMesh : Value

1051

meshop.freeVData <Mesh mesh> <Integer vdChannel>

Deallocates the existing vertex data channel array and turns off the vertex data channel support state.

Edge methods
meshop.chamferEdges <Mesh mesh> <edgelist> <float amount>

Chamfers the specified edges by the specified amount.

meshop.cloneEdges <Mesh mesh> <edgelist>

Clones the specified edges.

meshop.collapseEdges <Mesh mesh> <edgelist>

Collapses the specified edges.

meshop.cutEdge <Mesh mesh> <int edge1> <float prop1> <int edge2> <float prop2> <point3 projdir> node:<node=unsupplied>

If <mesh> is a node, or if <mesh> is an Editable Mesh and <node> is specified, projdir is in the current coordinate system context. If <mesh> is an Editable Mesh and <node> is not specified, projdir is in the meshs local coordinate system. Returns the index of the new vertex if created, or undefined if no vertex was created.
meshop.deleteEdges <Mesh mesh> <edgelist> delIsoVerts:<boolean=true>

Deletes the specified edges. If <delIsoVerts> is true, any isolated vertices are deleted.
meshop.divideEdge <Mesh mesh> <int edgeIndex> <float edgef> visDiag1:<boolean=false> visDiag2:<boolean=false> fixNeighbors:<boolean=true> split:<boolean=false>

Divides the specified edge at a fractional distance of <edgef> along its length. <visDiag1> and <visDiag2> specify whether each of the two new edges will be visible. If <fixNeighbors> is true, the face on the other side of this edge, that is, the reverse face, should be divided as well to prevent the introduction of a seam. If <split> is true, separate vertices for the two halves of the edge will be created, splitting the mesh open along the diagonal(s).
meshop.divideEdges <Mesh mesh> <edgelist>

Divides all the specified edges in half, creating new points and subdividing faces.
meshop.edgeTessellate <Mesh mesh> <facelist> <float tension>

Tessellates the specified edges. This algorithm is exactly the one used in the Tessellate modifier, when operating on Faces and Edge SO elements. <tension> specifies the tension for the edge tessellation. This value should be fairly small, between 0 and .5, and corresponds to the value in the Tessellate, Edit Mesh, or Editable Mesh UIs divided by 400.
meshop.extrudeEdges <Mesh mesh> <edgelist> <float height> dir:<{<point3 dir> | #independent | #common}=#independent> node:<node=unsupplied>

Creates new edges corresponding to the specified edges, and then moves the new edges by <height>. The direction the edges are moved is determined by <dir>. If <dir> is a point3 value, the edges will be moved in that direction. (If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the direction is in the current

1052

Chapter 11

3ds max Objects

coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the direction is in the meshs local coordinate system.) If dir:#independent is specified, the edges are moved based on the normals of the faces using the edge. If dir:#common is specified, the edges are moved based on the normals of the face clusters using the edge.
meshop.getEdgesUsingVert <Mesh mesh> <vertlist>

Returns a bitarray of size=(#edges in mesh) with bits set for all edges that use the specified vertices.
meshop.getOpenEdges <Mesh mesh>

Returns a bitarray of size=(#edges in mesh) with bits set for all edges that are used by a single face.
meshop.turnEdges - renamed to turnEdge, still showing in index meshop.turnEdge <Mesh mesh> <int edgeIndex>

Turns the specified edge. Only works on edges that have a face on both sides. These two faces are considered as a quad, where this edge is the diagonal, and remapped so that the diagonal flows the other way, between the vertices that were opposite this edge on each face.

Face methods
meshop.bevelFaces <Mesh mesh> <facelist> <float height> <float outline> dir:<{<point3 dir> | #independent | #common}=#independent> node:<node=unsupplied>

Moves the specified faces by <height> and outlines them by <outline>. The direction the faces are moved is determined by <dir>. If <dir> is a point3 value, the faces will be moved in that direction. (If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the direction is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the direction is in the meshs local coordinate system.) If dir:#independent is specified, the faces are moved based on the individual face normals. If dir:#common is specified, the faces are moved based on the face cluster normals.
meshop.cloneFaces <Mesh mesh> <facelist>

Clones the specified faces.

meshop.collapseFaces <Mesh mesh> <facelist>

Collapses the specified faces.

meshop.cutFace <Mesh mesh> <int face> <point3 start> <point3 destination> <point3 projdir> node:<node=unsupplied>

If <mesh> is a node, or if <mesh> is an Editable Mesh and <node> is specified, start, destination, and projdir are in the current coordinate system context. If <mesh> is an Editable Mesh and <node> is not specified, start, destination, and projdir are in the meshs local coordinate system. Returns the index of the new vertex if created, or undefined if no vertex was created.

Editable_Mesh : GeometryClass and TriMesh : Value

1053

meshop.deleteFaces <Mesh mesh> <facelist> delIsoVerts:<boolean=true>

Deletes the specified faces. If <delIsoVerts> is true, any isolated vertices are deleted.
meshop.detachFaces <Mesh mesh> <facelist> delete:<boolean=true> asMesh:<boolean=false>

Detaches the specified faces. If <delete> is true, the faces are deleted after being detached. If <delete> is false, the faces are not deleted. If <asMesh> is true, the faces are detached and returned as a Mesh value. If <asMesh> is false, the faces are detached as an element in the mesh and a value of OK is returned.
meshop.divideFace <Mesh mesh> <int faceIndex> baryCoord:<point3=unsupplied>

Divides the specified face. If <baryCoord> is specified, the new vertex will be created at the corresponding position. If <baryCoord> is not specified, the new vertex will be created at the center of the face.
meshop.divideFaceByEdges <Mesh mesh> <int faceIndex> <int edge1Index> <float edge1f> <int edge2Index> <float edge2f> fixNeighbors:<boolean=true> split:<boolean=false>

Divides the specifed face. New vertices are created on the specified edges at the specified fractional distance along their length. If <fixNeighbors> is true, the face on the other side of the edges, that is, the reverse faces, should be divided as well to prevent the introduction of a seam. If <split> is true, separate vertices for the two halves of the edges will be created, splitting the mesh open along the diagonal(s).
meshop.divideFaces <Mesh mesh> <facelist>

Divides the specified faces, with new vertices created at the center of the faces.
meshop.explodeAllFaces <Mesh mesh> <float threshold>

Explodes the mesh into separate elements. <threshold> specifies the angle between faces that indicates whether they should be in the same or different element.
meshop.explodeFaces <Mesh mesh> <facelist> <float threshold>

Explodes the specified faces into separate elements. <threshold> specifies the angle between faces that indicates whether they should be in the same or different element.
meshop.extrudeFaces <Mesh mesh> <facelist> <float height> <float outline> dir:<{<point3 dir> | #independent | #common}=#independent> node:<node=unsupplied>

Creates new faces corresponding to the specified faces, and then moves the new faces by <height> and outlines them by <outline>. The direction the faces are moved is determined by <dir>. If <dir> is a point3 value, the faces will be moved in that direction. (If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the direction is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the direction is in the meshs local coordinate system.) If dir:#independent is specified, the faces are moved based on the individual face normals. If dir:#common is specified, the faces are moved based on the face cluster normals.

1054

Chapter 11

3ds max Objects

meshop.getBaryCoords <Mesh mesh> <int faceIndex> <point3 pos> node:<node=unsupplied>

The barycentric coordinates of the specified point in the plane of the specified face, relative to the face. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the meshs local coordinate system.
meshop.getElementsUsingFace <Mesh mesh> <facelist> fence:<facelist=unsupplied>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces in elements where at least one face in the element is specified in <facelist>. If <fence> is specified, its faces are considered as barriers to the element and are not processed.
meshop.getFaceCenter <Mesh mesh> <int faceIndex> node:<node=unsupplied>

Returns the face center of the specified face. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the meshs local coordinate system.
meshop.getFaceRNormals <Mesh mesh> <int faceIndex> node:<node=unsupplied>

Returns a three element array of the render normals for the faces three vertices. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the meshs local coordinate system.
meshop.getFacesUsingVert <Mesh mesh> <vertlist>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces that use the specified vertices.
meshop.getHiddenFaces <Mesh mesh>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces that are hidden.
meshop.getNumFaces <Mesh mesh>

Returns the number of faces in the mesh.

meshop.getVertsUsedOnlyByFaces <Mesh mesh> <facelist>

Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices used by the specified faces.
meshop.makeFacesPlanar <Mesh mesh> <facelist>

Moves the specified faces so that they are planar.

meshop.removeDegenerateFaces <Mesh mesh>

Deletes any degenerate faces in the mesh. A degenerate face has two or more equal vertex indices.

Editable_Mesh : GeometryClass and TriMesh : Value

1055

meshop.removeIllegalFaces <Mesh mesh>

Deletes any illegal faces in the mesh. An illegal face has one or more vertex indices that are out of range.
meshop.setHiddenFaces <Mesh mesh> <facelist>

Sets the specified faces as hidden, and non-specified faces as visible.

meshop.setNumFaces <Mesh mesh> <int>

Sets the number of faces in the mesh.

Mesh methods
meshop.createPolygon <Mesh mesh> <vertIndex array> smGroup:<int=0> matID:<int=1>

Creates a set of faces using the specified vertices. The order of the vertices in the faces is the order in the vertex array. The polygon may be nonconvex, but should be (roughly) coplanar. <smGroup> and <matID> specify the smoothing group data and material ID number assigned to the new faces.
meshop.cut <Mesh mesh> <int edge1Index> <float edge1f> <int edge2Index> <float edge2f> <point3 normal> fixNeighbors:<boolean=true> split:<boolean=true> node:<node=unsupplied>

Cuts the mesh from a point on one edge to a point on another, along a line drawn by looking at the mesh from a particular viewpoint. <edge1Index> specifies the edge that the cut starts on. <edge1f> specifies the fractional distance along the edge to start the cut from. <edge2Index> specifies the edge that the cut ends on. <edge2f> specifies the fractional distance along the edge to finish the cut on. <normal> specifies the direction of view. The cut will take place on this side of the mesh, in the plane formed by this vector and the direction from the start to the end. If <fixNeighbors> is true, the faces on the other side of each end of the cut should be split to prevent splits at the ends. If <split> is true, the cut will split the mesh apart. If false, the cut will just refine the mesh by adding geometry. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the normal is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the normal is in the meshs local coordinate system.
meshop.getPolysUsingVert <Mesh mesh> <vertlist> ignoreVisEdges:<boolean=false> threshhold:<float=45.>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces that are in polygons containing the specified vertices. The definition of a polygon is all faces sharing invisible edges with edge angles below the threshhold angle. The default threshhold angle is 45 degrees. If ignoreVisEdges is set to true, the edge visibility is ignored but the threshhold is still relevant.

1056

Chapter 11

3ds max Objects

meshop.optimize <Mesh mesh> <float normalThreshold> <float edgeThreshold> <float bias> <float maxEdge> saveMatBoundries:<boolean=true> saveSmoothBoundries:<boolean=true> autoEdge:<boolean=true>

Reduces the mesh in complexity by reducing the number of faces based on a surface normal threshold. Adjacent faces whose difference in surface normal angle falls below <normalThreshold> will be collapsed into a single triangle. If <autoEdge> is true, when the angle between adjacent surface normals is less than <edgeThreshold> the edge will be invisible. When optimizing mesh objects, as the optimization increases, you can get lots of long skinny degenerate triangles (that cause rendering artifacts). Increasing <bias> keeps triangles from becoming degenerate. The range of values is from 0 to 1 (where 0 turns bias off). Values close to 1 reduce the amount of optimization in favor of maintaining equilateral triangles. A <maxEdge> value > 0 will prevent the optimize function from creating edges longer than this value. If this parameter is <=0 no limit is placed on the length of the edges. If <saveMatBoundries> is true, faces wont be collapsed across a material boundary. If <saveSmoothBoundries> is true, faces wont be collapsed across a dissimilar smoothing group boundary.
meshop.slice <Mesh mesh> <facelist> <point3 normal> <float offset> separate:<boolean=false> delete:<boolean=false> node:<node=unsupplied>

Slices the mesh along the specified slicing plane. The slicing plane is defined as all points which, when DotProdd with <normal>, return <offset>. <normal> should be normalized. <separate> specifies whether the slice should separate the mesh into two separate elements (true) or just refine the existing mesh by splitting faces (false). <delete> specifies whether the slice should remove the portion of the mesh below the slicing plane, where below is defined as the area where DotProd (p,<normal>) - <offset> < 0. If <delete> is true, <separate> is ignored. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the normal is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the normal is in the meshs local coordinate system.
copy <trimesh>

Yields a copy of the source TriMesh.

delete <trimesh>

Clears out the TriMeshs geometry and topology, effectively freeing its memory. The following method is not applicable to TriMeshes:
animateVertex <mesh> <vertex_spec>

Applies controllers to the specified vertices of the Editable_Mesh, where <vertex_spec> is one of:
<integer_index> <integer_index_array> #all

Editable_Mesh : GeometryClass and TriMesh : Value

1057

By assigning controllers to the vertices, the vertices are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the vertices. For example,
animateVertex $Sphere01 #all

The vertices to be animated are specified by index number or with the keyword #all to animate all vertices. See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation (p. 1461) for details on accessing the Editable_Mesh vertices. The controller values assigned to the vertices is in object space. See the Using Node Transform Properties (p. 843) topic for information on converting between world space to object space. The setMesh() method enables bulk changes to a mesh via arrays of vertices, faces, tverts, etc. setMesh() has the following forms:
setMesh <mesh> [ numverts:<integer> ] [ numfaces:<integer> ]

Resets the mesh to the given geometry but with no topology (i.e., no faces or edges). Any current mesh data is lost. You have to individually place the vertices and create the faces from the vertices. The default number of vertices and faces are 36 and 50, respectively.
setMesh <mesh> [ [ [ [ vertices:<array_of_point3s> ] \ faces:<array_of_point3s> ] \ materialIDs:<array_of_integers> ] \ tverts:<array_of_point3s> ]

Resets the mesh based on the given arrays. Only those portions of the mesh that are specified are reset. For example, if only the vertices parameter is specified, the existing face data is retained. Each Point3 value in the vertices array specifies the position of the vertex in the current coordinate system. Each Point3 value in the faces array specifies the 3 vertex indices that form the face. The materialIDs array specifies the material ID to be assigned to each face. Each Point3 value in the tverts array specifies the UVW coordinates of the texture vertices. See Texture Mapping in the methods section for more information on texture vertices.
setMesh <mesh> [ length:<integer> ] [ width:<integer> ] [ lengthsegs:<integer> ] \ [ widthhsegs:<integer> ]

Resets the mesh with a flat rectangular mesh with the given size and number of segments. The default length and width are 50, the default number of segments is 5.
setMesh <mesh> <trimesh>

Sets the mesh to a copy of the source TriMesh.

Mapping methods General

meshop.deleteIsoMapVertsAll <Mesh mesh>

For all mapping channels, deletes all mapping vertices that are not used by a mapping face.
meshop.freeMapChannel <Mesh mesh> <int mapChannel>

Deletes the map vertex and face arrays for the specified channel, and sets their count to 0.

1058

Chapter 11

3ds max Objects

meshop.getMapFacesUsingMapVert <Mesh mesh> <int mapChannel> <mapVertlist>

Returns a bitarray of size=(#map faces for channel in mesh) with bits set for all map faces that use the specified map vertices.
meshop.getMapVertsUsingMapFace <Mesh mesh> <int mapChannel> <mapFacelist>

Returns a bitarray of size=(#map vertices for channel in mesh) with bits set for all map vertices that use the specified map faces.
meshop.setFaceAlpha <Mesh mesh> <int mapChannel> <facelist> <float alpha>

For the specified map channel, sets the map vertex color to (color <alpha> <alpha> <alpha>) for the map vertices used by the map faces associated with the specified faces.
meshop.setFaceColor <Mesh mesh> <int mapChannel> <facelist> <color color>

For the specified map channel, sets the map vertex color to <color> for the map vertices used by the map faces associated with the specified faces.
meshop.setVertAlpha <Mesh mesh> <int mapChannel> <vertlist> <float alpha>

For the specified map channel, sets the map vertex color to (color <alpha> <alpha> <alpha>) for the specified map vertices.
meshop.setVertColor <Mesh mesh> <int mapChannel> <vertlist> <color color>

For the specified map channel, sets the map vertex color to <color> for the specified map vertices.
meshop.setNumMaps <Mesh mesh> <int count> keep:<boolean=false>

Sets the number of map channels available. The number of map channels can be set from 2 to 100. Map channels 1 and 2 are the Vertex Color and default Texture Map channels. If keep is false, the old mapping information is discarded. If true, the old mapping information is retained after the resize.
meshop.getNumMaps <Mesh mesh>

Returns the number of map channels available as an <integer>.

meshop.setMapSupport <Mesh mesh> <Integer mapChannel> <Boolean support>

Sets whether the specified mapping channel is supported or not. If support is true, and the channel support state is currently false, a new map face array of the same size as the number of faces in the mesh is allocated, but no map vertex array is allocated. If support is false, and the channel support state is currently true, existing map channel face and vertex arrays are deallocated. If support and the current channel support state are both the same, no action is performed. SetNumMaps() is automatically called if the specified map channel is not available. mapChannel index values are 0-based, with Map channels 0 and 1 being the Vertex Color and default Texture Map channels.
meshop.getMapSupport <Mesh mesh> <Integer mapChannel>

Returns whether the specified map channel is supported. This signifies that a map face arrayis present, but not necessarily a map vertex array.

Editable_Mesh : GeometryClass and TriMesh : Value

1059

meshop.setNumMapVerts <Mesh mesh> <Integer mapChannel> <Integer count> keep:<boolean=FALSE>

Sets the number of vertices for the map channel, initializing the map vertex array. If keep is false or not specified, the old map vertex information is discarded. If true, the old map vertex information is retained after the resize.
meshop.getNumMapVerts <Mesh mesh> <Integer mapChannel>

Returns the number of vertices for the map channel as an <integer>.

meshop.setNumMapFaces <Mesh mesh> <Integer mapChannel> <Integer count> keep:<boolean=false> keepCount:<int=0>

Sets the number of faces for the map channel. If keep is false or not specified, the old map face information is discarded. If true, the old map face information from the number of faces specified by keepCount is retained after the resize. Dangerous to use with map channels 0 and 1, so miminum mapChannel value is 2.
meshop.getNumMapFaces <Mesh mesh> <Integer mapChannel>

Returns the number of faces for the map channel as an <integer>.

meshop.setMapVert <Mesh mesh> <Integer mapChannel> <Integer index> <Point3 xyz>

Sets the coordinates of the specified map vertex.

meshop.getMapVert <Mesh mesh> <Integer mapChannel> <Integer index>

Returns the coordinates of the specified map vertex as a <point3>.

meshop.setMapFace <Mesh mesh> <Integer mapChannel> <Integer index> <Point3 face>

Sets the map vertices for the specified map face.

meshop.getMapFace <Mesh mesh> <Integer mapChannel> <Integer index>

Returns the vertices of the specified map face as a <point3>.

meshop.makeMapPlanar <Mesh mesh> <Integer mapChannel>

Applies a simple planar mapping to the specified channel. This is done by copying the mesh topology and vertex locations into the map, resizing the face and vertex arrays if necessary.
meshop.getIsoMapVerts <Mesh mesh> <Integer mapChannel>

Returns a <bitarray> with a bit set for each isolated map vertex (unrefereced by any map face) for the specified channel.
meshop.deleteMapVertSet <Mesh mesh> <Integer mapChannel> {<BitArray set> | <Integer index> | <integer array>}

Deletes the specified map vertices. Returns a <bitarray> with a bit set for each map face that used one of the deleted map vertices. Normally, you should delete or modify the map faces using the map vertices before deleting the map vertices, as after the vertex deletion you cant tell which vertex on a face was a vertex that was deleted.
meshop.freeMapVerts <Mesh mesh> <Integer mapChannel>

Deallocates the map vertex array and sets the number of map vertices to 0.
meshop.freeMapFaces <Mesh mesh> <Integer mapChannel>

Deallocates the map face array and sets the number of map faces to 0.

1060

Chapter 11

3ds max Objects

meshop.applyUVWMap <TriMesh mesh> {<#planar | #cylindrical | #spherical | #ball | #box> | <#face>} \ utile:<float=1.0> vtile:<float=1.0> wtile:<float=1.0> uflip:<boolean=false> vflip:<boolean=false> wflip:<boolean=false> cap:<boolean=true> tm:<Matrix3=identity matrix> channel:<int=1>

Applies the specified mapping type to the mapping channel. utile/vtile/wtile - Number of tiles in the U/V/W directions. uflip/vflip/wflip - U/V/W are mirrored if true. cap - used with #cylindrical. If true, then any face normal that is pointing more vertically than horizontally will be mapped using planar coordinates. tm - defines the mapping space. As each point is mapped, it is multiplied by this matrix, and then it is mapped. channel - the mapping channel the mappingis applied to, defaults to channel 1.
meshop.buildMapFaces <Mesh mesh> <Integer mapChannel> <Boolean keep>

Sets the number of map faces to the number of mesh faces, retaining existing mapping data if keep is true. Deletes any map vertices that are not used by the map faces.
meshop.defaultMapFaces <Mesh mesh> <Integer mapChannel> <Integer count>

Sets the number of map faces to the number of mesh faces, and the number of map vertices to the number of mesh vertices. The map face vertices are set to the same vertex index as the corresponding mesh face vertices (i.e., there will be a 1-to-1 correspondence between map faces/vertices and the mesh faces/vertices). The map vertex UVW coordinates are set to the normalized (0 to 1) position of the corresponding mesh vertex in the meshs bounding box.

Mapping methods Color per vertex channel (Channel 0)

meshop.getNumCPVVerts <Mesh mesh>

Returns the number of Color Per Vertex mapping channel vertices.

meshop.setNumCPVVerts <Mesh mesh> <int>

Sets the number of Color Per Vertex mapping channel vertices.

Mapping methods Default texture mapping channel (Channel 1)

meshop.getNumTVerts <Mesh mesh>

Returns the number of Default Texture mapping channel vertices.

meshop.setNumTVerts <Mesh mesh> <int>

Sets the number of Default Texture mapping channel vertices.

Data methods Vertex selection weight channel (Channel 1)

meshop.getVSelectWeight <Mesh mesh> <int vertIndex>

Returns the Vertex Selection Weight data value for the specified vertex.
meshop.setVSelectWeight <Mesh mesh> <vertlist> <float weight>

Sets the Vertex Selection Weight data value for the specified vertex.

Editable_Mesh : GeometryClass and TriMesh : Value

1061

meshop.resetVSelectWeights <Mesh mesh>

Sets the Vertex Selection Weight data value to 1.0 for all vertices.
meshop.supportVSelectWeights <Mesh mesh>

Enables support of the Vertex Selection Weight channel.

meshop.freeVSelectWeights <Mesh mesh>

Deletes (deallocates) the Vertex Selection Weight data array.

Data methods Vertex weight channel (Channel 2)

meshop.getVertWeight <Mesh mesh> <int vertIndex>

Returns the Vertex Weight data value for the specified vertex.
meshop.setVertWeight <Mesh mesh> <vertlist> <float weight>

Sets the Vertex Weight data value for the specified vertex.
meshop.resetVertWeights <Mesh mesh>

Sets the Vertex Weight data value to 1.0 for all vertices.
meshop.supportVertWeights <Mesh mesh>

Enables support of the Vertex Weight channel.

meshop.freeVertWeights <Mesh mesh>

Deletes (deallocates) the Vertex Weight data array.

Data methods Vertex Alpha channel (Channel 3)

meshop.getVAlpha <Mesh mesh> <int vertIndex>

Returns the Vertex Alpha data value for the specified vertex.
meshop.setVAlpha <Mesh mesh> <vertlist> <float alpha>

Sets the Vertex Alpha data value for the specified vertex.
meshop.resetVAlphas <Mesh mesh>

Sets the Vertex Alpha data value to 1.0 for all vertices.
meshop.supportVAlphas <Mesh mesh>

Enables support of the Vertex Alpha channel.

meshop.freeVAlphas <Mesh mesh>

Deletes (deallocates) the Vertex Alpha data array.

Data methods Vertex corner channel (Channel 4)

meshop.getVertCorner <Mesh mesh> <int vertIndex>

Returns the Vertex Corner data value for the specified vertex.
meshop.setVertCorner <Mesh mesh> <vertlist> <float weight>

Sets the Vertex Corner data value for the specified vertex.
meshop.resetVertCorners <Mesh mesh>

Sets the Vertex Corner data value to 0.0 for all vertices.

1062

Chapter 11

3ds max Objects

meshop.supportVertCorners <Mesh mesh>

Enables support of the Vertex Corner channel.

meshop.freeVertCorners <Mesh mesh>

Deletes (deallocates) the Vertex Corner data array.

Editable mesh UI property methods

meshop.getAffectBackfacing <Mesh mesh> -- editable mesh only meshop.setAffectBackfacing <Mesh mesh> <boolean> -- editable mesh only meshop.getBubble <Mesh mesh> -- editable mesh only meshop.setBubble <Mesh mesh> <float> -- editable mesh only meshop.getDisplacementMapping <Mesh mesh> -- editable mesh only meshop.setDisplacementMapping <Mesh mesh> <boolean> -- editable mesh only meshop.getExtrusionType <Mesh mesh> -- editable mesh only meshop.setExtrusionType <Mesh mesh> <int> -- editable mesh only meshop.getFalloff <Mesh mesh> -- editable mesh only meshop.setFalloff <Mesh mesh> <float> -- editable mesh only meshop.getIgnoreBackfacing <Mesh mesh> -- editable mesh only meshop.setIgnoreBackfacing <Mesh mesh> <boolean> -- editable mesh only meshop.getIgnoreVisEdges <Mesh mesh> -- editable mesh only meshop.setIgnoreVisEdges <Mesh mesh> <boolean> -- editable mesh only meshop.getNormalSize <Mesh mesh> -- editable mesh only meshop.setNormalSize <Mesh mesh> <float> -- editable mesh only meshop.getPinch <Mesh mesh> -- editable mesh only meshop.setPinch <Mesh mesh> <float> -- editable mesh only meshop.getPlanarThreshold <Mesh mesh> -- editable mesh only meshop.setPlanarThreshold <Mesh mesh> <float> -- editable mesh only meshop.getSelByVertex <Mesh mesh> -- editable mesh only meshop.setSelByVertex <Mesh mesh> <boolean> -- editable mesh only meshop.getShowFNormals <Mesh mesh> -- editable mesh only meshop.setShowFNormals <Mesh mesh> <boolean> -- editable mesh only meshop.getShowVNormals <Mesh mesh> -- editable mesh only meshop.setShowVNormals <Mesh mesh> <boolean> -- editable mesh only meshop.getSoftSel <Mesh mesh> -- editable mesh only meshop.setSoftSel <Mesh mesh> <boolean> -- editable mesh only meshop.getSplitMesh <Mesh mesh> -- editable mesh only meshop.setSplitMesh <Mesh mesh> <boolean> -- editable mesh only meshop.getSSEdgeDist <Mesh mesh> -- editable mesh only meshop.setSSEdgeDist <Mesh mesh> <int> -- editable mesh only meshop.getSSUseEdgeDist <Mesh mesh> -- editable mesh only meshop.setSSUseEdgeDist <Mesh mesh> <boolean> -- editable mesh only meshop.getSubdivisionAngle <Mesh mesh> -- editable mesh only meshop.setSubdivisionAngle <Mesh mesh> <float> -- editable mesh only meshop.getSubdivisionDisplacement <Mesh mesh> -- editable mesh only meshop.setSubdivisionDisplacement <Mesh mesh> <boolean> -- editable mesh only meshop.getSubdivisionDistance <Mesh mesh> -- editable mesh only meshop.setSubdivisionDistance <Mesh mesh> <float> -- editable mesh only meshop.getSubdivisionEdge <Mesh mesh> -- editable mesh only meshop.setSubdivisionEdge <Mesh mesh> <float> -- editable mesh only meshop.getSubdivisionMaxLevels <Mesh mesh> -- editable mesh only meshop.setSubdivisionMaxLevels <Mesh mesh> <int> -- editable mesh only

Editable_Mesh : GeometryClass and TriMesh : Value

1063

meshop.getSubdivisionMaxTriangles <Mesh mesh> -- editable mesh only meshop.setSubdivisionMaxTriangles <Mesh mesh> <int> -- editable mesh only meshop.getSubdivisionMethod <Mesh mesh> -- editable mesh only meshop.setSubdivisionMethod <Mesh mesh> {#regular | #spatial | #curvature | #spatialAndCurvature} -- editable mesh only meshop.getSubdivisionMinLevels <Mesh mesh> -- editable mesh only meshop.setSubdivisionMinLevels <Mesh mesh> <int> -- editable mesh only meshop.getSubdivisionSteps <Mesh mesh> -- editable mesh only meshop.setSubdivisionSteps <Mesh mesh> <int> -- editable mesh only meshop.getSubdivisionStyle <Mesh mesh> -- editable mesh only meshop.setSubdivisionStyle <Mesh mesh> {#tree | #grid | #delaunay} -- editable mesh only meshop.getSubdivisionView <Mesh mesh> -- editable mesh only meshop.setSubdivisionView <Mesh mesh> <boolean> -- editable mesh only meshop.getWeldPixels <Mesh mesh> -- editable mesh only meshop.setWeldPixels <Mesh mesh> <int> -- editable mesh only meshop.getWeldThreshold <Mesh mesh> -- editable mesh only meshop.setWeldThreshold <Mesh mesh> <float> -- editable mesh only

-- Vertex Methods
getNumVerts <mesh>

Returns number of vertices as an integer, equivalent to using <mesh>.numverts

setNumVerts <mesh> <vert_index_integer> [ <boolean> ]

Set the number of vertices as specified. If the optional boolean argument is true, the existing topology remains intact. If it is false or left off, the topology is lost.
getVert <mesh> <vert_index_integer>

Returns the position (in the current working coordinate system) of the indexed vertex as a point3
setVert <mesh> <vert_index_integer> ( <point3> | <float> <float> <float> )

Sets the position coordinates of the indexed vertex as a point3 value, or 3 floats - X,Y,Z
deleteVert <mesh> <vert_index_integer>

Deletes the indexed vertex from the mesh and all faces that share the vertex. Renumbers vertices and faces to account for the deletions. Also adjusts face vertex indexes as necessary.
getNormal <mesh> <vert_index_integer>

Returns the normal at the indexed vertexs position as a point3. The normal is based on the faces that use the vertex and the smoothing groups assigned to those faces.
setNormal <mesh> <vert_index_integer> <point3>

Sets the indexed vertexs normal vector

1064

Chapter 11

3ds max Objects

getVertSelection <node> [ <modifier_or_index> ] [ name:<name> ] getVertSelection <mesh>

Returns the current vertex selection set, or the specified named selection set if the optional name: parameter is specified, as a BitArray. The optional <modifier_or_index> identifies the Edit Mesh or Mesh Select modifier on the given scene object from which the selection BitArray is obtained. For example:
getVertSelection $foo $foo.modifiers[3]

If the optional <modifier_or_index> argument is not supplied, the <node> must be an Editable Mesh object and the selection is taken from the base object. If <modifier_or_index> is supplied, it must be either a modifier on the node or a number. If it is a modifier, it must be either an Edit Mesh or a Mesh Select modifier. If it is a number, it is used as an index into the Edit Mesh/Select Modifiers on the <node> starting from the top of the stack. Note that this index does not count any other types of modifier present. So, an index of 1 will always get the selection currently active at the top of the stack. The function returns a BitArray that are the 1-based indexes of the vertices currently selected, or the vertices specified by the named selection set, in the object by the given modifier. For example:
getVertSelection $foo $foo.modifiers[3]

yields
#{2..5,9,25..27}

This is a snapshot of the selection -- the BitArray doesnt change automatically as you make different selections. Further, it reflects the current vertex selection whether or not the modifier is in vertex sub-object selection mode (this selection is remembered and reestablished whenever you go back into vertex subobject mode). So, for example, if you select some vertices then click out of vertex subobject mode, the whole object rather than the selection is passed up the stack to the next modifier, but getVertSelection() returns the selected vertices at the time the subobject mode was exited. You might use the modifiers modifier array accessing scheme here if youve got many edit mesh modifiers with non-unique names. You can also use a constructed string as an index into the modifiers array, for example:
$foo.modifiers[edit mesh + i as string]

assuming the variable i had some indexing value and the names were set up thusly. + on strings concatenates.
setVertSelection <node> [ ( [ setVertSelection <mesh> ( [ <modifier_or_index> ] <sel_bitarray> | <sel_array> ) name:<name> ] [ keep:<boolean> <sel_bitarray> | <sel_array> ) keep:<boolean> ] \ \ ] \

Sets the vertex selections in an Editable Mesh base object, Mesh Select modifier, Edit Mesh Modifier, or TriMesh. This mirrors the selection getting method above.

Editable_Mesh : GeometryClass and TriMesh : Value

1065

The <modifier_or_index> argument is interpreted as for the get- form above, except that only the Mesh Select modifier is supported for set operations. For example:
setVertSelection $foo #{1..4,100..102} setFaceSelection $foo \ (getFaceSelection $baz) keep:true

If the optional name: argument is specified, the vertices in the specified named selection set in the Editable Mesh or Mesh Select modifier are selected. If the name: argument is not specified, the selection index argument gives the indexes of the sub-object items to be selected as either a BitArray or an array of integers. If the optional keep: keyword argument is false or not supplied, any current selection will be replaced by the new one. If the keep: keyword argument is true, the new selection is added to the current selection. The name: argument is not applicable to TriMeshes. Use the mesh update() function after making a group of selection changes in order to make them visible to any modifiers on the object.
averageSelVertCenter <node> [ <modifier_or_index> ]

Returns the average position (center) of the selected vertices in the given mesh as a Point3. If the object is not a mesh this method returns undefined. If no vertices are selected in the mesh, a value of [0,0,0] is returned. This method is not applicable to TriMeshes. The <modifier_or_index> argument is interpreted as for getVertSelection.
averageSelVertNormal <node> [ <modifier_or_index> ]

Returns the normalized average of the normals of the selected vertices in the given mesh as a Point3. If the given node is not a mesh, it returns undefined. If no vertices are selected in the mesh, or the averaged normal is [0,0,0], a value of [1,0,0] is returned. This method is not applicable to TriMeshes. The <modifier_or_index> argument is interpreted as for getVertSelection. The vertex normals used in this method do not consider smoothing group data of the faces that use the vertex. -- Face Methods
getNumFaces <mesh>

Returns number of faces as an integer, equivalent to using <mesh>.numfaces

getFace <mesh> <face_index_integer>

Returns the face vertex indexes for the indexed face as a point3. Each component of the point3 value contains a vertex index.
setFace <mesh> <face_index_integer> <vert_indices_point3>

Sets the face vertex indexes for the indexed face from a point3.
setFace <mesh> <face_index_integer> <vert_index_integer> \ <vert_index_integer> <vert_index_integer>

Sets the face vertex indexes for the indexed face from 3 vertex indexes.

1066

Chapter 11

3ds max Objects

deleteFace <mesh> <face_index_integer>

Deletes indexed face from the mesh. Renumbers faces accordingly.

collapseFace <mesh> <face_index_integer>

Deletes indexed face from the mesh, welding its 3 vertices together at the center of the original face. Renumbers faces accordingly.
getFaceNormal <mesh> <face_index_integer>

Returns the normal of the indexed face as a point3.

setFaceNormal <mesh> <face_index_integer> <point3>

Sets the indexed faces normal vector. As soon as you run update() on the mesh, this value is overwritten.
getFaceMatID <mesh> <face_index_integer>

Returns the indexed faces material ID as an integer.

setFaceMatID <mesh> <face_index_integer> <integer>

Sets the indexed faces material ID.

getFaceSmoothGroup <mesh> <face_index_integer>

Returns the indexed faces smoothing groups as a 32-bit integer. There are 32 possible smoothing groups. Each bit in the returned value corresponds to a smoothing group. If a bit is turned on, the face is part of that smoothing group. You can retrieve the list of smoothing groups for a face as a BitArray using the following function:
fn getfacesmoothgroupB obj face = ( local sgroup_val=getfacesmoothgroup obj face local sg_bitarray=#{} if sgroup_val < 0 do ( sg_bitarray[32]=true sgroup_val -= 2^31 ) for i = 1 to 31 do ( sg_bitarray[i]= (mod sgroup_val 2 > .5) sgroup_val /= 2 ) sg_bitarray ) setFaceSmoothGroup <mesh> <face_index_integer> <smoothing_group_integer>

Sets the indexed faces smoothing groups. If you have a faces desired smoothing groups as a BitArray, you could set the faces smoothing group data using the following function:
fn setfacesmoothgroupB obj face sg_bitarray = ( local sgroup_val=0 for i in sg_bitarray do sgroup_val += 2^(i-1) setfacesmoothgroup obj face sgroup_val update obj )

Editable_Mesh : GeometryClass and TriMesh : Value

1067

getFaceSelection <node> [ <modifier_or_index> ] [ name:<name> ] getFaceSelection <mesh>

Retrieves the face selection set, or the specified named selection set if the optional name: parameter is specified, as a BitArray. See the getVertSelection() method for more information.
setFaceSelection <node> [ ( [ setFaceSelection <mesh> ( [ <modifier_or_index> ] <sel_bitarray> | <sel_array> ) name:<name> ] [ keep:<boolean> <sel_bitarray> | <sel_array> ) keep:<boolean> ] \ \ ] \

Sets the face selections in an Editable Mesh base object, Mesh Select modifier, Edit Mesh modifier, or TriMesh. This mirrors the selection getting method above. See the setVertSelection() method for more information.
deselectHiddenFaces <mesh>

deselects the hidden faces in the mesh. This method is not applicable to TriMeshes.
extrudeFace <mesh> ( <index> | <bitarray> | <integer_array> | #selection ) \ <amount> <scale> \ [ dir:(<point3> | #common | #independent ) ]

Provides capabilities equivalent to the Extrude Face modifier. This function works only on Editable Mesh nodes. The second argument defines which faces to extrude, either a single face index, a BitArray of face indexes, an integer array of face indexes, or the name literal #selection meaning the current face selection in the Editable Mesh. The <amount> argument specifies the extrude distance and the <scale> specifies a % amount to scale each face cluster. If the optional dir: keyword argument is not specified, face clusters are extruded by moving their vertices independently along the average normal at each vertex, as does the Extrude Face modifier. If it is specified, it can be a point3 giving a direction vector in which all vertices are moved, or it can be the value #independent which is the same as the default direction, or it can be the value #common which extrudes face clusters along the average normal of all the face normals in each cluster. #common is equivalent to the Group Normal option in EditableMesh, and #independent is equivalent to the Local Normal option. An example usage is:
s=sphere() extrudeface s #{1..20} 10 100 dir:#independent update s meshop.getVertsUsingFace <Mesh mesh> <facelist>

Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices that are used by the specified faces.
meshop.getEdgesUsingFace <Mesh mesh> <facelist>

Returns a bitarray of size=(#edges in mesh) with bits set for all edges that are used by the specified faces.

1068

Chapter 11

3ds max Objects

meshop.getPolysUsingFace <Mesh mesh> <facelist> ignoreVisEdges:<boolean=false> threshhold:<float=45.>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces that are in polygons containing the specified faces. The definition of a polygon is all faces sharing invisible edges with edge angles below the threshhold angle. The default threshhold angle is 45 degrees. If ignoreVisEdges is set to true, the edge visibility is ignored but the threshhold is still relevant.
meshop.autoSmooth <Mesh mesh> <facelist> <float threshold>

Smooths the specified faces based on the threshold angle.

meshop.unifyNormals <Mesh mesh> <facelist>

Unifies the normals of the specified faces.

meshop.flipNormals <Mesh mesh> <facelist>

Flips the normal of the specified faces.

<float> meshop.getFaceArea <Mesh mesh> <facelist>

Returns the area of the specified faces as a <float>. -- Edge Methods

getEdgeVis <mesh> <face_index_integer> <edge_index_integer>

Returns the edge visibility for given edge (1,2,3) on indexed face as a boolean.
setEdgeVis <mesh> <face_index_integer> <edge_index_integer> <boolean>

Sets the edge visibility for given edge (1,2,3) on indexed face.
getEdgeSelection <node> [ <modifier_or_index> ] [ name:<name> ] getEdgeSelection <mesh>

Retrieves the edge selection set, or the specified named selection set if the optional name: parameter is specified, as a BitArray. See the getVertSelection() method for more information.
setEdgeSelection <node> [ ( [ setEdgeSelection <mesh> ( [ <modifier_or_index> ] <sel_bitarray> | <sel_array> ) name:<name> ] [ keep:<boolean> <sel_bitarray> | <sel_array> ) keep:<boolean> ] \ \ ] \

Sets the edge selections in an Editable Mesh base object, Mesh Select modifier, Edit Mesh Modifier, or TriMesh. This mirrors the selection getting method above. See the setVertSelection() method for more information.
deselectHiddenEdges <mesh>

Deselects the hidden edges in the mesh. This method is not applicable to TriMeshes.
meshop.getVertsUsingEdge <Mesh mesh> <edgelist>

Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices that are used by the specified edges.
meshop.getFacesUsingEdge <Mesh mesh> <edgelist>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces that use the specified edges.

Editable_Mesh : GeometryClass and TriMesh : Value

1069

meshop.getPolysUsingEdge <Mesh mesh> <edgelist> ignoreVisEdges:<boolean=false> threshhold:<float=45.>

Returns a bitarray of size=(#faces in mesh) with bits set for all faces that are in polygons containing the specified edges. The definition of a polygon is all faces sharing invisible edges with edge angles below the threshhold angle. The default threshhold angle is 45 degrees. If ignoreVisEdges is set to true, the edge visibility is ignored but the threshhold is still relevant.
meshop.getEdgesReverseEdge <Mesh mesh> <edgelist>

Returns a bitarray of size=(#edges in mesh) with bits set for all additional edges that use the same vertices as the specified edges. These are edges on the adjacent faces. Example:
Plane length:100 width:100 isSelected:on convertTo $ TriMeshGeometry max modify mode subobjectLevel = 1 select $.verts[13] -- get edges that use vertex 13 edges = meshop.getEdgesUsingVert $ (getVertSelection $) -- select the vertices used by those edges $.selectedVerts = meshop.getVertsUsingEdge $ edges update $ -- not what we wanted, really want all vertices surrounding vertex 13 faces = meshop.getPolysUsingVert $ 13 $.selectedVerts = meshop.getVertsUsingFace $ faces update $ -- or ... faces = meshop.getFacesUsingVert $ #(13) edges = meshop.getEdgesUsingFace $ faces -- turn off all visible edges for e in edges do edges[e]=not (getEdgeVis $ (1+(e-1)/3)(1+mod (e-1) 3)) -- get the edges on the adjacent faces that are the reverse of these edges -- OR that bitarray with the initial edges bitarray edges = (meshop.getEdgesReverseEdge $ edges) + edges -- get the faces that use the edges, and OR that bitarray with the initial -- face bitarray faces = (meshop.getFacesUsingEdge $ edges) + faces $.selectedVerts = meshop.getVertsUsingFace $ faces update $

1070

Chapter 11

3ds max Objects

meshop.autoEdge <Mesh mesh> <edgelist> <float threshold> type:<{#SetClear | #Set | #Clear}=#SetClear>

Sets/clears the edge visibility for the specified edges based on the threshold angle. Note: for an edge to be autoEdged, both it and the reverse edge on the face sharing the edge vertices must be specified in the edge specification. Note: 3ds max defines an edge as the edge of a face. In any mesh object, the number of edges is 3 times the number of faces. A face has 3 vertices, and the face edges connect these vertices. Edges 1, 2, and 3 are the edges between vertices 1 and 2, 2 and 3, and 3 and 1, respectively. The first edge in a mesh is edge 1 on face 1, and the last edge is edge 3 on the last face. The following script selects all of the visible edges in the specified mesh:
EdgeSelSet=#() for face = 1 to obj.numfaces do for edge = 1 to 3 do if (getedgevis obj face edge) then append EdgeSelSet (((face-1)*3)+edge) setedgeselection obj EdgeSelSet update obj

The following function returns the indices of the 2 vertices that define an edge as a Point2 value. The two arguments to the function are a editable mesh node or TriMesh value and the edge index. A value of undefined is returned if the first argument isnt an editable mesh node or TriMesh value, or if the edge index is out of range.
fn edgeVerts theObj theEdge = ( if not (classof theObj == Editable_mesh or classof theObj == triMesh) do return undefined if theEdge < 1 or theEdge > (theObj.numfaces*3) do return undefined local theFace = ((theEdge-1)/3)+1 local theVerts = getFace theObj theFace case ((mod (theEdge-1) 3) as integer) of ( 0: point2 theVerts.x theVerts.y 1: point2 theVerts.y theVerts.z 2: point2 theVerts.z theVerts.x ) )

-- Texture Vertex Methods

getNumTVerts <mesh>

Returns number of texture vertices as an integer, equivalent to using <mesh>.numtverts

setNumTVerts <mesh> <number> [ <boolean> ]

Sets the number of texture vertices as specified. If the optional boolean argument is true, the existing topology remains intact. If it is false or not supplied, the topology is lost.
getTVert <mesh> <tvert_index_integer>

Returns the UVW coordinates of the indexed texture vertex

Editable_Mesh : GeometryClass and TriMesh : Value

1071

setTVert <mesh> <tvert_index_integer> ( <point3> | <x> <y> <z> )

Sets the UVW coordinates of the indexed texture vertex as a point3 value, or 3 floats U,V,W
getTVFace <mesh> <face_index_integer> setTVFace <mesh> <face_index_integer> <vert_indices_point3> setTVFace <mesh> <face_index_integer> <tvert_index_integer> \ <tvert_index_integer> <tvert_index_integer>

The getTVFace() and setTVFace() functions mirror the getFace() and setFace() functions and are used to specify texture mapping topology in terms of texture vertices. You can set up and access texture vertices with the getTVert(), setTVert(), getNumTVerts(), and setNumTVerts() functions described above.
buildTVFaces <mesh> [ <boolean> ]

The buildTVFaces() function only needs to be called on meshes you are adding texture vertices to yourself to create the internal texture face array. Meshes that 3ds max applies mapping coordinates to maintain the TVFace array automatically. This is not done automatically when you add texture vertices to meshes yourself so you need to call buildTVFaces() explicitly whenever you change the texture vertex count, and before you construct the texture faces. If the optional boolean argument is true, the existing texture mapping remains intact. If it is false or not supplied, the existing texture mapping is lost (all texture faces are rebuilt, with all three vertices of the texture face using texture vertex 1).
numMapsUsed <mesh>

Returns the an upper limit on the number of texture map channels used by the given node. This is at least 1+(highest channel in use). This method is used so a script that does something to all map channels doesnt always have to do it to every channel up to 99 (the highest possible texture map channel), but rather only to this value. This method is not applicable to TriMeshes. Note: The mesh class contains a list of texture vertices which are completely independent of the regular vertices in the mesh. There is no correlation between the number of vertices in a mesh and the number of texture vertices. In addition to the texture vertices there are also texture faces. There needs to be one texture face for every regular face in the mesh. Each texture face has three indices into the texture vertex array. The coordinates of a texture vertex are UVW coordinates, and are accessed as Point3 values. The 3 components are U, V, and W, and each component value is in the range of 0 to 1. An example script for creating planar texture mapping on an object is shown in the Working with Editable Meshes (p. 1077) topic. The texture vertex methods do not support multiple mapping channels in 3ds max 4.

1072

Chapter 11

3ds max Objects

-- Color-Per-Vertex Methods
getNumCPVVerts <mesh>

Returns number of color-per-vertex vertices as an integer, equivalent to using <node>.numcpvverts

setNumCPVVerts <mesh> <integer> [ <boolean> ]

Sets the number of c-p-v vertices. If the optional boolean argument is true, the existing topology remains intact. If it is false or not supplied, the topology is lost.
buildVCFaces <mesh> [ <boolean> ]

Builds the c-p-v face array after you have set the c-p-v vertex count. If the optional boolean argument is true, the existing topology remains intact. If it is false or not supplied, the topology is lost.
defaultVCFaces <mesh>

Sets the number of c-p-v vertices and c-p-v faces to match exactly the current meshs geometry and topology and calls buildVCFaces()
getVertColor <mesh> <CPVvert_index_integer>

Returns the color of the indexed c-p-v vertex as a color

getVCFace <mesh> <CPVface_index_integer>

Returns the topology for the indexed c-p-v face as a point3 containing 3 c-p-v vertex indexes
setVCFace <mesh> <CPVface_index_integer> <CPVvert_indices_point3>

Sets the indexed c-p-v face topology from a point3 containing 3 c-p-v vertex indexes
setVCFace <mesh> <CPVface_index_integer> <CPVvert_index_integer> \ <CPVvert_index_integer> <CPVvert_index_integer>

Sets the indexed c-p-v face topology from 3 c-p-v vertex index number arguments The c-p-v vertex and face indexes are 1-based as with other mesh indexes in MAXScript. Remember that you need to call update() on the mesh after making changes to it for the changes to be reflected in the scene. Note: The mesh class contains a list of color vertices which are completely independent of the regular vertices in the mesh. There is no correlation between the number of vertices in a mesh and the number of color vertices. In addition to the color vertices there are also color faces. There needs to be one color face for every regular face in the mesh. Each color face has three indices into the color vertex array. The coordinates of a color vertex are RGB coordinates, and are accessed as Color values. The techniques for building and accessing color vertices and faces is virtually identical to the techniques for building and accessing texture vertices and faces. An example script for creating planar texture mapping on an object is shown in the Working with Editable Meshes (p. 1077) topic.

Editable_Mesh : GeometryClass and TriMesh : Value

1073

-- Subdivision Displacement Surface Properties Methods The following methods set the Subdivision Displacement Surface Properties for a mesh object. These methods are not applicable to TriMeshes.
setSplitMesh <mesh> <boolean>

Turns on or off split mesh subdivision displacement for the mesh. Calling this function will enable subdivisionDisplacement if it is set to false.
getSplitMesh <mesh>

Returns true if split mesh subdivision displacement is turned on for the mesh, false otherwise.
setSubdivisionDisplacement <mesh> <boolean>

Turns on or off subdivision displacement for the mesh.

getSubdivisionDisplacement <mesh>

Returns true if subdivision displacement is turned on for the mesh, false if off.
displacementToPreset <mesh> ( #low | #medium | #high )

Sets the mesh subdivision parameters to the specified preset value set.
setDisplacementMapping <mesh> <boolean>

Turns on or off whether to perform displacement mapping for the mesh. There is no corresponding user interface element for this method.
getDisplacementMapping <mesh>

Returns true if displacement mapping is turned on for the mesh, false if off. -- Editable Mesh Modify Panel Command Modes and Operations A suite of methods provide the ability for a script to invoke Editable Mesh and Edit Mesh Modify panel modes and operations, corresponding to buttons available at various mesh sub-object levels. These methods reside in the meshOps global structure. These methods effectively push the button in the 3ds max Modify panel. In order to use these methods, the node must be selected and the Modify panel open. In the description of these methods, the first argument <editable_mesh_node_or_modifier> should be interpreted as either an Editable Mesh node where the modifier stack level is at the base object, or an Edit Mesh modifier where the modifier stack level is at the Edit Mesh. In all cases, the following methods work at the current sub-object level, but only if that level is appropriate for the invoked operation. If you have made scripted changes to the mesh you must call the update() method on the mesh before calling these methods. You do not need to call update() after just calling one of these methods, as 3ds max will take care of updating the mesh. The follow methods invoke one of the user-interaction button operations in the Editable Mesh Modify panel, acting on the currently selected sub-objects. These methods highlight the corresponding button in the Edit Geometry rollout and start the operation, at which point the user interactively completes the operation. These methods return after starting the operation, and before the user completes the operation, so care should be taken to ensure that your script does not interfere with the operation. Invoking any of these methods is the same as clicking on the associated button in the Modify panel. Calling a method when the operation is already in effect (either due to

1074

Chapter 11

3ds max Objects

a user action or a MAXScript command) causes the operation to be terminated and the highlight is removed from the button. In 3ds max 4, there is no access to the spinner field values in the Editable Mesh rollouts.
meshOps.startAttach <editable_mesh_node_or_modifier>

Enters Attach command mode - valid in Vertex, Face, Polygon, and Element Sub-Object levels, and when not in Sub-Object mode.
meshOps.startBevel <editable_mesh_node_or_modifier>

Enters Bevel command mode - valid in Edge, Face, Polygon, and Element Sub-Object levels.
meshOps.startChamfer <editable_mesh_node_or_modifier>

Enters Chamfer command mode - valid in Vertex and Edge Sub-Object levels.
meshOps.startCreate <editable_mesh_node_or_modifier>

Enters Create command mode, valid in Vertex, Face, Polygon, and Element Sub-Object levels.
meshOps.startCut <editable_mesh_node_or_modifier>

Enters Cut command mode - valid in Edge, Face, Polygon, and Element Sub-Object levels.
meshOps.startDivide <editable_mesh_node_or_modifier>

Divides selected edges into 2 edges, for selected face into 3 faces - valid in Edge, Face, Polygon, and Element Sub-Object levels.
meshOps.startExtrude <editable_mesh_node_or_modifier>

Enters Extrude command mode - valid in Face, Polygon, and Element Sub-Object levels.
meshOps.startFlipNormalMode <editable_mesh_node_or_modifier>

Enters Flip Normal command mode - valid in Face, Polygon, and Element Sub-Object levels.
meshOps.startSlicePlane <editable_mesh_node_or_modifier>

Enters Slice Plane command mode - valid in all Sub-Object levels, and when not in SubObject mode.
meshOps.startTurn <editable_mesh_node_or_modifier>

Enters Turn command mode - valid in Edge Sub-Object level.

meshOps.startWeldTarget <editable_mesh_node_or_modifier>

Enters Weld Target command mode - valid in Vertex Sub-Object level. The following methods invoke one of the instantaneous button operations in the Editable Mesh Modify panel, acting on the currently selected sub-objects:
meshOps.autoEdge <editable_mesh_node_or_modifier>

Automatically sets the edge visibility on the selected sub-objects - valid in Edge Sub-Object level.
meshOps.break <editable_mesh_node_or_modifier>

Creates a new vertex for each face attached to the selected sub-objects - valid in Vertex Sub-Object level.

Editable_Mesh : GeometryClass and TriMesh : Value

1075

meshOps.collapse <editable_mesh_node_or_modifier>

Collapses the selected sub-objects - valid in Vertex, Edge, Face, Polygon, and Element SubObject levels.
meshOps.createShapeFromEdges <editable_mesh_node_or_modifier>

Displays Create Shape dialog allowing the user to specify an object name, shape type, and whether to ignore hidden edges. Valid in Edge Sub-Object level.
meshOps.delete <editable_mesh_node_or_modifier>

Deletes the selected sub-objects - valid in Vertex, Face, Polygon, and Element Sub-Object levels.
meshOps.detach <editable_mesh_node_or_modifier>

Displays Detach dialog allowing the user to specify an object name or to detach as element, and whether to clone the selected subobjects. Valid in Vertex, Face, Polygon, and Element Sub-Object levels.
meshOps.explode <editable_mesh_node_or_modifier>

Displays Explode to Objects dialog allowing the user to specify an object name. Explodes the selected faces into multiple elements or objects based on the angles of its edges. Valid in Vertex, Face, Polygon, and Element Sub-Object levels.
meshOps.flipNormal <editable_mesh_node_or_modifier>

Flips the normal of the selected faces - valid in Face, Polygon, and Element Sub-Object levels.
meshOps.gridAlign <editable_mesh_node_or_modifier>

Aligns the selected sub-objects to the construction plane - valid in Vertex, Edge, Face, Polygon, and Element Sub-Object levels.
meshOps.hide <editable_mesh_node_or_modifier>

Hides the selected sub-objects - valid in Vertex, Face, Polygon, and Element Sub-Object levels.
meshOps.invisibleEdge <editable_mesh_node_or_modifier>

Sets selected edges invisible. Valid in Vertex Sub-Object level.

meshOps.makePlanar <editable_mesh_node_or_modifier>

Forces all selected sub-objects to become coplanar - valid in Vertex, Edge, Face, Polygon, and Element Sub-Object levels.
meshOps.removeIsolatedVerts <editable_mesh_node_or_modifier>

Deletes all isolated vertices in the object regardless of the current selection.
meshOps.selectOpenEdges <editable_mesh_node_or_modifier>

Selects all edges with only one face. Valid in Edge Sub-Object level.
meshOps.slice <editable_mesh_node_or_modifier>

Subdivides edges and faces based on Slice Plane. meshOps.startSlicePlane() must be called to enter the Slice Plane command mode before slice is valid. Valid in all SubObject levels, and when not in Sub-Object mode.
meshOps.tessellate <editable_mesh_node_or_modifier>

Tessellates the selected sub-objects - valid in Face, Polygon, and Element Sub-Object levels.

1076

Chapter 11

3ds max Objects

meshOps.unhideAll <editable_mesh_node_or_modifier>

Unhides the hidden sub-objects at the current Sub-Object level - valid in Vertex, Face, Polygon, and Element Sub-Object levels.
meshOps.unifyNormal <editable_mesh_node_or_modifier>

Unifies the normals of the selected faces - valid in Face, Polygon, and Element Sub-Object levels.
meshOps.viewAlign <editable_mesh_node_or_modifier>

Aligns all selected sub-objects to the 0,0,0 plane of the active viewport - valid in Vertex, Edge, Face, Polygon, and Element Sub-Object levels.
meshOps.visibleEdge <editable_mesh_node_or_modifier>

Sets selected edges visible. Valid in Edge Sub-Object level.

meshOps.weld <editable_mesh_node_or_modifier>

Welds the selected vertices - valid in Vertex Sub-Object level. The meshOps methods depend on the Modify panel being open and the desired object, either an Editable Mesh base object or Edit Mesh modifier, being currently open in the panel. The meshOps methods do not perform any operation if these conditions arent met. You will need to use MAXScript functions like max modify mode or setCommandPanelTaskMode mode:#modify to open the Modify panel, select <obj> to select the object, subObjectLevel = <n> to set the SubObject level, and modPanel.setCurrentObject <obj_or_modifier> to establish the right context for the new functions to operate. For example: Script:
s=sphere() ConvertToMesh s s.selectedfaces=#{1..112} max modify mode select s modPanel.setCurrentObject s subObjectLevel = 4 meshOps.startExtrude s ------------create a sphere convert to an Editable Mesh select half the faces open the Modify panel select the sphere set modifier stack to the base object (not really needed in this example) set Sub-Object level to polygon start the face extrude command mode, highlighting its button in the Edit Geometry rollout, at which point the user interactively performs the extrude.

Another example is:

meshOps.Hide (modPanel.getCurrentObject())

which would invoke the Hide button operation on the current object open in the Modify panel if it was an Edit Mesh modifier or Editable Mesh base object.

Working with Editable Meshes

1077

Working with Editable Meshes

Flipping Face Normals The following function flips the face normal for all faces in the specified mesh object. Script:
fn FlipObjNormal obj = ( for f =1 to obj.numFaces do -- for each face in the mesh ( verts=getface obj f -- get its 3 vertices as a point3 local tmp=verts.x -- swap the first and third vertices verts.x=verts.z -- which flips the normal verts.z=tmp -- (right-hand rule), and setface obj f verts -- store the new vertex order for the face ) update obj -- update object so 3ds max sees the changes )

Texture Vertices and Faces The following script is an example of working with texture vertices and faces. Script:
----fn ( -------function to apply planar mapping to an object direction parameter specifies the axis the mapping is perpendicular to, and can have a value of #x, #y, or #z ApplyPlanarMap obj direction = local oldcoordsys, normalize_pos in this case, the number of texture vertices is equal to the number of mesh vertices obj.numtverts=obj.numverts build the texture vertex faces buildTVFaces obj operate in objects coordinate space. Save original coord system so we can restore later. oldcoordsys=set coordsys local for each vertex in mesh, get its position and normalize the position to a range of [0,0,0] to [1,1,1]. This is the planar UVW space. for v = 1 to obj.numverts do ( normalize_pos=((getvert obj v)-obj.min)/(obj.max-obj.min) flip around position component values based on which direction the planar mapping is perpendicular to case direction of (#x:( tmp=normalize_pos.x normalize_pos.x=normalize_pos.y normalize_pos.y=normalize_pos.z normalize_pos.z=tmp ) #y:( tmp=normalize_pos.y normalize_pos.y=normalize_pos.z normalize_pos.z=tmp )

---

1078

Chapter 11

3ds max Objects

) -- set the corresponding texture vertex position settvert obj v normalize_pos ) -- done positioning the texture vertices. Build the texture faces. -- since in this case there is a 1-to-1 correspondence between mesh and -- texture vertices, the vertex indices for a mesh face are also the -- texture vertex indices for the texture faces. for f = 1 to obj.numfaces do setTVFace obj f (getface obj f) -- all done. reset the coordinate system set coordsys oldcoordsys -- update the mesh so 3ds max sees the changes update obj ) --- test bed. Create a sphere, apply a material, set the diffuse map -- to a 2x3 tiled checker map, turn on viewport display of the -- checker texture map, and call the ApplyPlanarMap function -g=geosphere() convertToMesh g g.material=standard() g.material.maps[2]=checker() g.material.maps[2].coordinates.u_tiling=2 g.material.maps[2].coordinates.v_tiling=3 showTextureMap g.material g.material.maps[2] true ApplyPlanarMap g #x

Output:
ApplyPlanarMap() -- output of function $GeoSphere:GeoSphere02 @ [0.0,0.0,0.0] -$Editable_Mesh:GeoSphere02 @ [0.0,0.0,0.0] -Standard:Standard -Checker:Checker -2 -3 -OK -OK -declaration output line output line output line output line output line output line output line output line lines 5 to 45 51 52 53 54 55 56 57 58

SplineShape : Shape

1079

SplineShape : Shape
SplineShapes are the general editable versions of all the shape objects, in the same way that Editable Meshes relate to geometry objects. They are the objects that a shape is converted to when you apply an Edit Spline modifier and the result of collapsing a modifier stack on a shape base object. MAXScript lets you construct SplineShapes from scratch, adding individual curves and controls points or you can modify an existing shape by converting it to a SplineShape and using the methods listed below.

See also
Shape Common Properties, Operators, and Methods (p. 945) Spline Shape Common Properties, Operators, and Methods (p. 947) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Class and Object Inspector Functions (p. 799) Scripting Vertex and Control Point Animation (p. 1461) Note: 1. 2. You must convert existing shapes to SplineShapes in order to operate on them with the these methods. Use the convertToSplineShape() function to do this. Only the updateShape() function updates the shapes internal caches and images in 3ds max viewports. This is because updates can be computationally expensive and you dont want them performed on every function call. However, you must make sure you do call the updateShape() function after a series of changes and before the shape is to be worked on in 3ds max or by other functions in MAXScript. The in and out vectors for Bezier control points are given as vector handle coordinates, not as true vectors as the names suggests. Coordinates are given in the MAXScript working coordinate system - this is important to note if you are familiar with the corresponding SDK spline functions which always work in objectlocal coordinates. If the updateShape() function is called on an object that is selected and currently open in the Modify panel, it will drop the current selection in order to avoid a potential crash in 3ds max, which at the moment, does not support scripted changes to an object open in the Modify panel. If you are creating or modifying a spline object, and have not yet run updateShape() on the spline, 3ds max will crash if you minimize and then maximize the 3ds max window. This is because an only partially created spline is created, and the internal 3ds max spline structure is left in an unstable state.

3. 4.

5.

6.

1080

Chapter 11

3ds max Objects

Properties:
<SplineShape>.angle <SplineShape>.thickness <SplineShape>.sides Float Float Float default: 0.0 default: 1.0 default: 12.0 -- animatable -- animatable -- animatable

The rotational position of the cross-section in the renderer. Diameter of the rendered spline. Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example.
<SplineShape>.viewport_thickness Float Integer default: 1.0 default: 12

Diameter of the viewport spline.

<SplineShape>.viewport_sides

Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example.
<SplineShape>.viewport_angle <SplineShape>.DisplayRenderMesh <SplineShape>.UseViewportSettings <SplineShape>.DisplayRenderSettings <SplineShape>.numSplines Float default: 0.0

The rotational position of the cross-section in the viewports.

Booleandefault: false Boolean Boolean default: false default: true

When on, displays the mesh generated by the spline in the viewports. When on, displays the mesh generated by the Viewport settings. When on, displays the mesh generated by the render settings.
Integer, read-only

The number of individual spline curves in the shape. Up to 3*N vertex and tangent coordinates are available as properties, where N is the number of vertices in the SplineShape. A vertex and its tangents are available as properties once a controller has been assigned to the vertex. Controllers can be assigned to vertices using the animateVertex() method described in the Scripting Vertex and Control Point Animation (p. 1461) topic. For example, if a circle object is collapsed to a SplineShape, and some of its vertices are animated, the properties for the vertices and tangents would be similar to:
$Circle01.Spline_1___InVec_1 $Circle01.Spline_1___Vertex_1 $Circle01.Spline_1___OutVec_1 $Circle01.Spline_1___InVec_2 $Circle01.Spline_1___Vertex_2 $Circle01.Spline_1___OutVec_2 Point3 Point3 Point3 Point3 Point3 Point3 value: value: value: value: value: value: [-75,33,0] [-75,33,0] [-50,0,0] [-20,-33,0] [7,-66,0] [32,-95,0] ------animatable animatable animatable animatable animatable animatable

SplineShape : Shape

1081

Methods: -- Shape Methods

updateShape <shape>

Updates the shapes internal caches and viewport display to account for all the changes made by other functions in this kit. This update must be done before 3ds max or any other code tries to work with a modified shape object. The updateShape() function makes any scripted changes to a base object spline shape propagate into the bottom of any modifier stack that is present. Note that there is no check to warn you that modifications such as topology changes might invalidate modifiers already in the stack. This is equivalent to opening and modifying the base object in a Modify panel, ignoring its warnings about invalidating the object.
resetShape <shape>

Clears all the spline curves out of a shape

numSplines <shape>

Returns the number of spline curves in the shape as an integer. Equivalent to <shape>.numSplines.
setFirstSpline <shape> <spline_index_integer>

Rolls the order of the splines in a shape around so that the numbered spline is the first spline in the shape. This is useful when working with multi-spline shapes in the Lofter and some other modifiers such as Surface Tools which are sensitive to spline order.
hideselectedsplines <shape>

Hides the selected splines in the shape.

hideselectedsegments <shape>

Hides the selected segments in the shape.

hideselectedverts <shape>

Hides the segments attached to the selected knots in the shape.

unhidesegments <shape>

Unhides all segments in the shape.

addAndWeld <to_shape> <from_shape> <weldthreshold_float>

Add the splines from one spline shape to the specified bezier shape. The weld threshold will weld the endpoints of the new splines onto endpoints of existing ones if they are within the distance specified.
bindKnot <shape> <isEnd_boolean> <splineId_integer> \ <segIndex_integer> <splineSegId_integer>

Binds the first or end knot of a spline to the midpoint of the specified segment. A bind acts as a constraint, it constrains the first point or the end point of a spline to the mid point of a segment. If <isEnd_boolean> is true the end knot of the spline is bound, otherwise the first knot is bound. <splineId_integer> specifies the index of the spline the first/ end knot to bind belongs to, <segIndex_integer> specifies the index of the segment to bind to, and <splineSegId_integer> specifies the index of the spline the bind to segment belongs to.

1082

Chapter 11

3ds max Objects

unBindKnot <shape> <spline_index_integer> <isEnd_boolean>

Unbinds the specified end/first knot of the given spline

updateBindList <shape>

Called when the topology changes to update the bind list, for example when knots are deleted from bound spline or the spline bound to.
materialID <shape> <spline_index_integer> <segment_index_integer>

Returns the material id for the given segment of the given shape object.
animateVertex <shape> <vertex_spec>

Applies controllers to the specified vertices and tangents of the splineshape, where <vertex_spec> is one of:
<integer_index> <integer_index_array> #all

By assigning controllers to the vertices and tangents, the vertices and tangents are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the vertices and tangents. For example,
animateVertex $Circle01 #all

The vertices to be animated are specified by index number or with the keyword #all to animate all vertices. See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation (p. 1461) for details on accessing the splineshape vertices and tangents. The controller values assigned to the vertices and tangent handles is in object space. See the Using Node Transform Properties (p. 843) topic for information on converting between world space to object space. -- Spline Methods
addNewSpline <shape>

Adds a new spline curve to the spline shape and returns an integer reflecting the spline index of the newly added spline curve. Individual spline curves are given index numbers starting at 1. The addNewSpline() function adds new spline curves to the end of the list of curves in a shape.
getSplineSelection <shape>

Returns the indices of the selected splines in the shape as an array of integers.
setSplineSelection <shape> <spline_index_array> [ keep:<boolean> ]

Selects the splines specified by <spline_index_array> in the specified shape. <spline_index_array> is an array of integers specifying the spline indices. Splines already selected are de-selected unless keep:true is specified.
deleteSpline <shape> <spline_index_integer>

Deletes the indexed spline curve from the shape. The remaining curves are renumbered to account for the deletion.

SplineShape : Shape

1083

numSegments <shape> <spline_index_integer>

Returns the number of line segments in the indexed spline as an integer. This is the same as the number of knots for closed splines and 1 less for open splines.
numKnots <shape> [ <spline_index_integer> ]

Returns the number of knots (also known vertices or control points) in the indexed spline as an integer. If the spline index is not specified, returns the number of knots in the entire shape.
isClosed <shape> <spline_index_integer>

returns true if the indexed spline is closed, false if it is open.

close <shape> <spline_index_integer>

closes the indexed spline.

open <shape> <spline_index_integer>

opens the indexed spline between its last and first knots.
reverse <shape> <spline_index_integer>

reverses the order of the knots in the indexed spline.

setFirstKnot <shape> <spline_index_integer> <knot_index_integer>

rolls the order of the knots in the indexed spline around so that the specified knot becomes the first knot in the spline.
getSegLengths <splineShape> <spline_index> [cum:<boolean>] [byVertex:<boolean>] [numArcSteps:<integer>]

Returns array of segment lengths or vertex distances by spline fraction and length, and total spline length. Double precision calculations, very accurate. If cum:true, results are cumulative, otherwise they are relative. If byVertex:true results are per vertex, otherwise per segment. Defaults: cum:false byVertex:false numArcSteps:100
subdivideSegment <splineShape> <spline_index> <seg_index> <divisions>

Divides the segment into the specified number of divisions. Double precision calculations, very accurate.
interpCurve3D <splineShape> <spline_index> <param_float> [pathParam:<boolean>]

Returns a <point3> coordinate on the indexed curve. If pathParam:false, param is the fraction of the spline length, otherwise it is a segment-based (path) fraction. Default is pathParam:false
tangentCurve3D <splineShape> <spline_index> <param_float> [pathParam:<boolean>]

Returns a <point3> tangent on the indexed curve. If pathParam:false, param is the fraction of the spline length, otherwise it is a segment-based (path) fraction. Default is pathParam:false -- Segment Methods
getSegmentType <shape> <spline_index_integer> <seg_index_integer>

Gets the segment type of the indexed segment in the indexed spline
setSegmentType <shape> <spline_index_integer> \ <seg_index_integer> ( #curve | #line )

Sets the segment type of the indexed segment in the indexed spline

1084

Chapter 11

3ds max Objects

refineSegment <shape> <spline_index_integer> \ <seg_index_integer> <seg_interp_param_float>

Adds a new knot to the indexed segment of the indexed curve at a place along the indexed segment corresponding to the given segment interpolation parameter. This value is a float in the range 0.0 to 1.0, specifying a proportion along the segment. The new knot coordinates and in-vector and out-vector are automatically computed to maintain the segments existing curvature. This is the primitive used by the refine function in the Edit Spline modifier. You can use the MAXScript spline path interpolation functions to derive segment parameters given that a curves path interpolation parameter is divided evenly among the segments in a curve. (So given a path interpolation parameter u and a target segment n in a spline of m segments, the segment parameter is u - (n-1)/m.) The refineSegment() function returns the index of the newly inserted knot.
getSegSelection <shape> <spline_index_integer>

Returns the indices of the selected segments in the specified shape spline as an array of integers.
setSegSelection <shape> <spline_index_integer> \ <segment_index_array> [ keep: <boolean> ]

Selects the segments specified by <segment_index_array> in the specified shape spline. <segment_index_array> is an array of integers specifying the segment indices. Segments already selected are de-selected unless keep:true is specified.
setMaterialID <splineShape> <spline_index> <seg_index> <matID>

Sets the material ID of the specified spline segment.

getMaterialID <splineShape> <spline_index> <seg_index>

Gets the material ID of the specified spline segment. -- Knot Methods

addKnot <shape> <spline_index_integer> \ ( #smooth | #corner | #bezier | #bezierCorner ) \ ( #curve | #line ) <position_point3> \ [invec_point3 outvec_point3] [where_integer]

Adds a new knot (control point) to the indexed spline and returns an integer reflecting the index of the newly added knot. The 3rd argument specifies the type of the knot, the 4th specifies the type of the segment leaving the knot. The 5th specifies the coordinates for the new point (given in the current working coordinate system). If the knot type is bezier or bezierCorner, you must give the in-vector and out-vector handle coordinates as the 6th and 7th arguments. In the same way as splines are indexed in a shape, knots are indexed in a spline. The optional last argument lets you specify where in the knot order the new knot is to be inserted, defaulting to the end of the spline if you leave this argument off.
deleteKnot <shape> <spline_index_integer> <knot_index_integer>

Deletes the indexed knot in the indexed spline. The remaining knots are renumbered to account for the deletion.
getKnotType <shape> <spline_index_integer> <knot_index_integer>

Returns the knot type of the indexed knot in the indexed spline. The value is one of the names #smooth, #corner, #bezier, or #bezierCorner.

SplineShape : Shape

1085

setKnotType <shape> <spline_index_integer> <knot_index_integer> \ (#smooth | #corner | #bezier | #bezierCorner )

Sets the knot type of the indexed knot in the indexed spline. This is equivalent to the right-mouse-button change you can make to spline control-points using the Edit Spline modifier in 3ds max.
getKnotPoint <shape> <spline_index_integer> <knot_index_integer>

Retrieves the coordinates of the indexed knot as a point3 in the current working coordinate system.
setKnotPoint <shape> <spline_index_integer> <knot_index_integer> <point3>

Sets the coordinates of the indexed knot in the indexed spline. Coordinates are given in the current working coordinate system.
getInVec <shape> <spline_index_integer> <knot_index_integer>

Retrieves the coordinates of the in-vector handle for the indexed knot as a point3 in the current working coordinate system.
setInVec <shape> <spline_index_integer> <knot_index_integer> <point3>

Sets the coordinates of the in-vector handle of the indexed knot. Coordinates are given in the current working coordinate system.
getOutVec <shape> <spline_index_integer> <knot_index_integer>

Retrieves the coordinates of the out-vector handle for the indexed knot as a point3 in the current working coordinate system.
setOutVec <shape> <spline_index_integer> <knot_index_integer> <point3>

Sets the coordinates of the out-vector handle of the indexed knot. Coordinates are given in the current working coordinate system.
getKnotSelection <shape> <spline_index_integer>

Returns the indices of the selected knots in the specified shape spline as an array of integers.
setKnotSelection <shape> <spline_index_integer> \ <knot_index_array> [keep: <boolean> ]

Selects the knots specified by <knot_index_array> in the specified shape spline. <knot_index_array> is an array of integers specifying the knot indices. Knots already selected are de-selected unless keep:true is specified. -- Editable Spline Modify Panel Command Modes and Operations A suite of methods provide the ability for a script to invoke Editable Spline, Line, and Edit Spline Modify panel modes and operations, corresponding to buttons available at various shape sub-object levels. These methods reside in the splineOps global structure. These methods effectively push the button in the Modify panel. In order to use these methods, the node must be selected and the Modify panel open. In the description of these methods, the first argument <editable_spline_or_line_node_or_modifier> should be interpreted as either an Editable Spline or Line node where the modifier stack level is at the base object, or an Edit Spline modifier where the modifier stack level is at the Edit Spline. In all cases, the following methods work at the current sub-object level, but only if that level is appropriate for the invoked operation.

1086

Chapter 11

3ds max Objects

If you have made scripted changes to the shape you must call the updateShape() method on the mesh before calling these methods. You do not need to call updateShape() after just calling one of these methods, as 3ds max will take care of updating the shape. The following methods invoke one of the user-interaction button operations in the Editable Spline Modify panel, acting on the currently selected sub-objects. These methods highlight the corresponding button in the Geometry rollout and start the operation, at which point the user interactively completes the operation. These methods return after starting the operation, and before the user completes the operation, so care should be taken to ensure that your script does not interfere with the operation. Invoking any of these methods is the same as clicking on the associated button in the Modify panel. Calling a method when the operation is already in effect (either due to a user action or a MAXScript command) causes the operation to be terminated and the highlight is removed from the button.
splineOps.startUnion <editable_spline_or_line_node_or_modifier>

Enters Boolean Union command mode - valid in Spline Sub-Object level. Only 1 closed spline must be selected to enter this command mode.
splineOps.startSubtract <editable_spline_or_line_node_or_modifier>

Enters Boolean Subtract command mode - valid in Spline Sub-Object level. Only 1 closed spline must be selected to enter this command mode.
splineOps.intersect <editable_spline_or_line_node_or_modifier>

Enters Boolean Intersect command mode - valid in Spline Sub-Object level. Only 1 closed spline must be selected to enter this command mode.
splineOps.startAttach <editable_spline_or_line_node_or_modifier>

Enters Attach command mode - valid in all Sub-Object levels, and when not in SubObject mode.
splineOps.startBind <editable_spline_or_line_node_or_modifier>

Enters Bind command mode - valid in Vertex Sub-Object level.

splineOps.startBreak <editable_spline_or_line_node_or_modifier>

Enters Break command mode - valid in Vertex and Segment Sub-Object levels.
splineOps.startChamfer <editable_spline_or_line_node_or_modifier>

Enters Chamfer command mode - valid in Vertex Sub-Object level.

splineOps.startConnect <editable_spline_or_line_node_or_modifier>

Enters Connect command mode - valid in Vertex Sub-Object level.

splineOps.startCreateLine <editable_spline_or_line_node_or_modifier>

Enters Create Line command mode - valid in all Sub-Object levels, and when not in SubObject mode.
splineOps.startCrossInsert <editable_spline_or_line_node_or_modifier>

Enters CrossInsert command mode - valid in Vertex Sub-Object level.

splineOps.startExtend <editable_spline_or_line_node_or_modifier>

Enters Extend command mode - valid in Spline Sub-Object level.

splineOps.startFillet <editable_spline_or_line_node_or_modifier>

Enters Fillet command mode - valid in Vertex Sub-Object level.

SplineShape : Shape

1087

splineOps.startInsert <editable_spline_or_line_node_or_modifier>

Enters Insert command mode - valid in all Sub-Object levels, and when not in SubObject mode.
splineOps.startOutline <editable_spline_or_line_node_or_modifier>

Enters Outline command mode - valid in Spline Sub-Object level.

splineOps.startRefine <editable_spline_or_line_node_or_modifier>

Enters Refine command mode - valid in Vertex and Segment Sub-Object levels. This method does not turn off the Connect checkbox, so it is effectively the same as the startRefineConnect() method.
splineOps.startRefineConnect <editable_spline_or_line_node_or_modifier>

Enters Refine command mode - valid in Vertex and Segment Sub-Object levels. This method does not turn on the Connect checkbox, so it is effectively the same as the startRefine() method.
splineOps.startTrim <editable_spline_or_line_node_or_modifier>

Enters Trim command mode - valid in Spline Sub-Object level. The following methods invoke one of the instantaneous button operations in the Editable Shape Modify panel, acting on the currently selected sub-objects:
splineOps.attachMultiple <editable_spline_or_line_node_or_modifier>

Displays Attach Multiple dialog allowing the user to select multiple shapes to attach. Valid in all Sub-Object levels, and when not in Sub-Object mode.
splineOps.close <editable_spline_or_line_node_or_modifier>

Closes the selected splines valid in Spline Sub-Object level.

splineOps.cycle <editable_spline_or_line_node_or_modifier>

Cycles through the vertices of the spline, selecting each vertex. At least one vertex must be selected before calling this method, or no vertex is selected. If more than one vertex is selected when this method is called, the first vertex of the first shape is selected. Valid in Vertex Sub-Object level.
splineOps.delete <editable_spline_or_line_node_or_modifier>

Deletes the selected sub-objects - valid in all Sub-Object levels.

splineOps.detach <editable_spline_or_line_node_or_modifier>

Displays Detach dialog allowing the user to specify an object name. Valid in all Sub-Object levels.
splineOps.divide <editable_spline_or_line_node_or_modifier>

Divides the selected segments - valid in Segment Sub-Object level.

splineOps.explode <editable_spline_or_line_node_or_modifier>

Explodes the each segment in the selected splines into separate splines or objects. Valid in Spline Sub-Object level.
splineOps.hide <editable_spline_or_line_node_or_modifier>

Hides the selected sub-objects - valid in all Sub-Object levels.

splineOps.makeFirst <editable_spline_or_line_node_or_modifier>

Makes the selected vertices the first vertex in the spline- valid in Vertex Sub-Object level.

1088

Chapter 11

3ds max Objects

splineOps.mirrorBoth <editable_spline_or_line_node_or_modifier>

Mirrors the selected splines horizontally and vertically valid in Spline Sub-Object level.
splineOps.mirrorHoriz <editable_spline_or_line_node_or_modifier>

Mirrors the selected splines horizontally valid in Spline Sub-Object level.

splineOps.mirrorVert <editable_spline_or_line_node_or_modifier>

Mirrors the selected splines vertically valid in Spline Sub-Object level.

splineOps.reverse <editable_spline_or_line_node_or_modifier>

Reverses the order of vertices in the selected splines valid in Spline Sub-Object level.
splineOps.unbind <editable_spline_or_line_node_or_modifier>

Unbinds the selected vertices - valid in Vertex Sub-Object level.

splineOps.unhideAll <editable_spline_or_line_node_or_modifier>

Unhides all hidden sub-objects -valid in all Sub-Object levels, and when not in Sub-Object mode.
splineOps.weld <editable_spline_or_line_node_or_modifier>

Welds the selected vertices - valid in Vertex Sub-Object level.

Patch : GeometryClass
Patches are the general editable versions of all the patch objects, in the same way that Editable Meshes relate to geometry objects. They are the objects that a patch is converted to when you apply an Edit Patch modifier and the result of collapsing a modifier stack on a patch base object. While MAXScript lets you construct patches, there are no properties or methods for accessing or modifying the sub-objects (vertices, edges, and patches) within the patch object. Constructor:
patch ...

To create a Patch scene object from scratch, you call the Patch constructor function, for example:
patch pos:[10,10,10] name:foo

This creates an empty patch.

convertTo <node> patch -- mapped

Converts the given scene node to a Patch object. If the object cannot be converted (typically, if it is not a geometry object), the function returns undefined. Any modifiers present will be collapsed. The collapseStack() function can also be used as can the collapse button in the modifier stack dialog in 3ds max; both generate a Patch, but will only do so if there is at least one modifier present.

Patch : GeometryClass

1089

Properties: A control vertex and its tangents are available as properties once a controller has been assigned to the control vertex. The number of tangents for a control vertex is the number of edges associated with the control vertex. Controllers can not be assigned to the control vertices using MAXScript in 3ds max 4. If a TriPatch object is collapsed to a SplineShape, and some of its control vertices are animated, the properties for the control vertices and tangents would be similar to:
$TriPatch01.Vertex_1 $TriPatch01.Vertex_1_Vector_1 $TriPatch01.Vertex_1_Vector_2 $TriPatch01.Vertex_2 $TriPatch01.Vertex_2_Vector_1 $TriPatch01.Vertex_2_Vector_2 Point3 Point3 Point3 Point3 Point3 Point3 value: value: value: value: value: value: [-21.5,-6.4,0] [-21.5,-2.1,0] [-7.1,-6.4,0] [21.5,-6.4,0] [7.1,-6.4,0] [7.1,-2.1,0] ------animatable animatable animatable animatable animatable animatable

See also Class and Object Inspector Functions (p. 799) for details on accessing the patch vertices and tangents. The controller values assigned to the vertices and tangent handles is in object space. See the Using Node Transform Properties (p. 843) topic for information on converting between world space to object space. Methods:
getPatchSteps <editable_patch_node>

Returns the number of steps the patch uses in the viewports, and reflects the View Steps spinner in the Modify panel.
setPatchSteps <editable_patch_node> <integer>

Sets the number of View Steps used by the editable patch object to the specified value. Editable Patch Modify Panel Command Modes and Operations A suite of methods provide the ability for a script to invoke Editable Patch and Edit Mesh Modify panel modes and operations, corresponding to buttons available at various mesh sub-object levels. These methods reside in the patchOps global structure. These methods effectively push the button in the Modify panel. In order to use these methods, the node must be selected and the Modify panel open. In the description of these methods, the first argument <editable_patch_node_or_modifier> should be interpreted as either an Editable Patch node where the modifier stack level is at the base object, or an Edit Patch modifier where the modifier stack level is at the Edit Patch. In all cases, the following methods work at the current sub-object level, but only if that level is appropriate for the invoked operation. The follow methods invoke one of the user-interaction button operations in the Editable Patch Modify panel, acting on the currently selected sub-objects. These methods highlight the corresponding button in the Geometry rollout and start the operation, at which point the user interactively completes the operation. These methods return after starting the operation, and before the user completes the operation, so care should be taken to ensure that your script does not interfere with the operation. Invoking any of these methods is the same as clicking on the associated button in the Modify panel. Calling a method when the operation is already in effect (either due to a user action or a MAXScript command) causes the operation to be terminated and the highlight is removed from the button.

1090

Chapter 11

3ds max Objects

patchOps.startAttach <editable_patch_node_or_modifier>

Enters Attach command mode - valid in all Sub-Object levels, and when not in SubObject mode.
patchOps.startBevel <editable_patch_node_or_modifier>

Enters Bevel command mode - valid in Patch Sub-Object level.

patchOps.startBind <editable_patch_node_or_modifier>

Enters Bind command mode - valid in Vertex Sub-Object level.

patchOps.startCreate <editable_patch_node_or_modifier>

Enters Create command mode - valid in Vertex, Patch, and Element Sub-Object levels.
patchOps.startExtrude <editable_patch_node_or_modifier>

Enters Extrude command mode - valid in Patch Sub-Object level.

patchOps.startFlipNormalMode <editable_patch_node_or_modifier>

Enters Flip Normal command mode - valid in Patch and Element Sub-Object levels.
patchOps.startWeldTarget <editable_patch_node_or_modifier>

Enters Weld Target command mode - valid in Vertex Sub-Object level. The following methods invoke one of the instantaneous button operations in the Editable Patch Modify panel, acting on the currently selected sub-objects:
patchOps.addTri <editable_patch_node_or_modifier>

Adds a TriPatch to the selected edge - valid in Edge Sub-Object level.

patchOps.addQuad <editable_patch_node_or_modifier>

Adds a QuadPatch to the selected edge - valid in Edge Sub-Object level.

patchOps.break <editable_patch_node_or_modifier>

Creates a new vertex for each patch attached to the selected sub-objects - valid in Vertex and Edge Sub-Object levels.
patchOps.clearAllSG <editable_patch_node_or_modifier>

Clears the smoothing groups on the currently selected patches - valid in Face, Polygon, and Element Sub-Object levels.
patchOps.createShapeFromEdges <editable_patch_node_or_modifier>

Displays Create Shape dialog allowing the user to specify an object name for the shape to create from the selected edges. Valid in Edge Sub-Object level.
patchOps.delete <editable_patch_node_or_modifier>

Deletes the selected sub-objects - valid in all Sub-Object levels.

patchOps.detach <editable_patch_node_or_modifier>

Displays Detach dialog allowing the user to specify an object name. Valid in Patch SubObject level.
patchOps.flipNormal <editable_patch_node_or_modifier>

Flips the normal of the selected patches - valid in Patch and Element Sub-Object levels.
patchOps.hide <editable_patch_node_or_modifier>

Hides the selected sub-objects - valid in all Sub-Object levels.

Patch : GeometryClass

1091

patchOps.selectByID <editable_patch_node_or_modifier>

Display a Select By Material ID dialog and choose patches with the specified material ID valid in Patch and Element Sub-Object levels.
patchOps.selectBySG <editable_patch_node_or_modifier>

Display a Select By Smooth Groups dialog and choose patches with the specified smoothing groupd IDs - valid in Patch and Element Sub-Object levels.
patchOps.selectOpenEdges <editable_patch_node_or_modifier>

Selects all edges with only one patch. Valid in Edge Sub-Object level.
patchOps.subdivide <editable_patch_node_or_modifier>

Divides the selected sub-objects - valid in Edge and Patch Sub-Object levels.
patchOps.unbind <editable_patch_node_or_modifier>

Unbinds the selected vertices - valid in Vertex Sub-Object level.

patchOps.unifyNormal <editable_patch_node_or_modifier>

Unifies the normals of the selected patches - valid in Patch and Element Sub-Object levels.
patchOps.unhideAll <editable_patch_node_or_modifier>

Unhides all hidden sub-objects -valid in all Sub-Object levels, and when not in Sub-Object mode.
patchOps.weld <editable_patch_node_or_modifier>

Welds the selected vertices - valid in Vertex Sub-Object level. There is now a new patch function containing a large number of functions for creating, modifying and accessing patch objects. The following functions are used to get and set the overall geometry of the patch. Set keep:true to the setNumXXX functions for them to retain existing vertex/vector/patch/edge data. This value defaults to false, which cleans out the geometry
patch.getNumVerts <obj> -> integer patch.setNumVerts <obj> <num> [keep:<boolean>] patch.getNumVecs <obj> -> integer patch.setNumVecs <obj> <num> [keep:<boolean>] patch.getNumPatches <obj> -> integer patch.setNumPatches <obj> <num> [keep:<boolean>] patch.getNumEdges <obj> -> integer patch.setNumEdges <obj> <num> [keep:<boolean>]

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

1092

Chapter 11

3ds max Objects

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

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

where: index = The index of the patch to create (0> = index < numPatches). va = The first vertex. vab = Vector ab. vba = Vector ba. vb = The second vertex. vbc = Vector bc. vcb = Vector cb. vc = The third vertex. vca = Vector ca.

Patch : GeometryClass

1093

vac = Vector ac. i1 = Interior 1. i2 = Interior 2. i3 = Interior 3. sm = The smoothing group mask The following function forces all geometry and topology caches to be rebuilt, change notifications to be sent and a screen redraw request to be flagged.You must call this function after making any changes to a path object, before exiting the script. If you make the changes otherwise, an invalid patch may be passed to MAX, possibly causing a crash. The patch.update() function is similar in function and purpose to the update() function in mesh object scripting.
patch.update <obj>

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

The following functions access and manipulate the texture mapping information in the patch object.
patch.setNumMaps <obj> <num> [keep:<bool>] -> patch.getNumMaps <obj> -> integer patch.setMapSupport <obj> <map_chan> [init:<boolean>] -> patch.getMapSupport <obj> <map_chan> -> boolean patch.maxMapChannels <obj> -> patch.setNumMapVerts <obj> <map_chan> <num> [keep:<boolean>] patch.getNumMapVerts <obj> <map_index> patch.setNumMapPatches <obj> <map_chan> <num> [keep:<boolean>] patch.getMapVert <obj> <map_chan> <index> patch.setMapVert <obj> <map_chan> <index> <point3> patch.getMapPatch <obj> <map_chan> <index> patch.setMapPatch <obj> <map_chan> <index> <index_array>

1094

Chapter 11

3ds max Objects

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

The following functions access and control viewport and renderer tesselation and visibility.
patch.setMeshSteps <obj> <steps> patch.getMeshSteps <obj> patch.setMeshStepsRender <obj> <steps> patch.getMeshStepsRender <obj> patch.setShowInterior <obj> <bool> patch.getShowInterior <obj> patch.setAdaptive <obj> <bool> patch.getAdaptive <obj>

The following functions access topology info for the specified sub-object.
patch.getEdges <obj> <v1> [<v2>] -> integer_array patch.getPatches <obj> <v1> [<v2>] -> integer_array patch.getVectors <obj> <vert> -> integer_array

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

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

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

The following functions get and manipulate surface normal information. Again, normal vectors are given in MAXScripts current working coordinate context.
patch.patchNormal <obj> <patch> patch.edgeNormal <obj> <edge> patch.updatePatchNormals <obj> patch.flipPatchNormal <obj> <patch> patch.unifyNormals <obj> patch.autoSmooth <obj> <angle> <useSel_bool> <preventIndirectSmoothing_bool>

Patch : GeometryClass

1095

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

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

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

See also
Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Class and Object Inspector Functions (p. 799) Scripting Vertex and Control Point Animation (p. 1461)

Modifier : MAXWrapper and SpacewarpModifier : MAXWrapper

The Modifier and SpacewarpModifier families of classes can be created and added to an objects modifier stack using the addModifier() or modPanel.addModToSelection() methods. Unless otherwise noted, the term modifier will be used to mean members of either class. By making a single modifier and adding it to several objects, you are sharing the modifier between the objects, as you would by applying a modifier to a selection of objects in the 3ds max user interface. The constructors in the following classes can take any of the listed properties as optional keyword arguments with the defaults as shown. Existing modifiers can be accessed in two ways: As a property access on a <node>. When you access a property on a <node> scene object, such as its name or position, or length, MAXScript will also consider modifiers on the object to be properties, for example:
$box1.heightsegs $box1.twist $box1.twist.angle -- get creation parameter -- get the twist modifier -- the twists angle

1096

Chapter 11

3ds max Objects

You can then access modifier properties as subproperties on the modifier as shown. If the modifier name has spaces in it, you can use the _ as space convention that pathnames use, like this:
$box1.uvw_map -- to get the UVW Map modifier

This will work in simple situations, but there may be several modifiers with the same name, or a modifier with the same name as a creation parameter (which is always looked for first). In this situation you can use the modifier array mechanism, which yields an array of modifiers you can index into:
$box1.modifiers $box1.modifiers[3] $box1.modifiers[#twist] $box1.modifiers[ffd 4x4x4] ----get get get get modifier array the 3rd down the list the one named twist the FFD

As you can see from the examples, you can use both name literals and strings to index modifiers by name in the table, so this is a way to get at modifiers with characters you cannot use in a MAXScript property name. The ordering is as you would see in the Modify panel, numbered starting at 1 from top-to-bottom. The classes derived directly from the Modifier and SpacewarpModifier classes are described in the Modifier and SpacewarpModifier Types (p. 1100) topic. The properties, operators, and methods that are common to all classes derived directly from the Modifier and SpacewarpModifier classes are described in the Modifier Common Properties, Operators, and Methods (p. 1096) topic. The Modifier and SpacewarpModifier classes are derived from the MAXWrapper class, and inherits the properties and methods defined for that class. These properties and methods are described in the MAXWrapper Common Properties, Operators, and Methods (p. 809) topic.

Modifier Common Properties, Operators, and Methods

Properties: All modifiers have the following properties:
<modifier>.name : string : boolean : boolean

get and set modifier name

<modifier>.enabled <modifier>.enabledInViews

lets you control the modifiers enabled/disabled state. These are read/write properties that let you determine and set the enabled state of the given modifier, for example:
$foo.modifiers[2].enabled = false -- turn off 2nd modifier

The enabledInViews property controls viewport display, enabled controls both viewport and rendered display.

Patch : GeometryClass

1097

Associated Methods: The modifier stack on a scene node can be manipulated using the following <node> methods:
validModifier ( <node> | <objectset>) <modifier>

Tests whether a particular modifier may be added the given <node> or <objectset>. Returns true if so, false if not. The validModifier() method operates exactly as does the Modify panel in determining modifier applicability. Any modifier that takes a deformable object will return true for all scene objects except Helpers. This corresponds to the Modify panels behavior of allowing modifiers such as Bend, Taper, etc. to be applied to lights and cameras, space warp objects, etc., as well as geometry types like box, sphere, etc., but not helpers such as dummys or bones.
addModifier <node> <modifier> [before:index] -- mapped

adds the modifier to all instances of the node to which the function is applied. The optional before: keyword argument can be used to insert the modifier into the nodes modifier stack just before the indexed modifier, counting from the top of the stack. The added modifier will apply to any appropriate active sub-object selection in the node only if the node is currently selected and open in the Modify panel at the desired sub-object level. You can use the 3ds max System global variable, subObjectLevel to test and set the level for the object currently open in the Modify panel. For example:
max modify mode select $box01 subObjectLevel = 3 addModifier $box01 (ffd_2x2x2()) ----open mod panel select box01 into mod panel subobject level to Face add FFD mod to those faces

If the before: keyword argument would place a modifier in an invalid position in the stack, the modifier will be placed at the nearest valid position. For example, if you tried to place a SpacewarpModifier class object below a Modifier class object, the SpacewarpModifier object would be placed below any SpacewarpModifier objects, and above any Modifier objects. If <node> is a collection, an instance of the modifier is placed on each of the nodes in the collection. Unlike interactively applying a modifier to a selection, the position and size of each modifier instances gizmo corresponds to position and size of the node the modifier instance is applied to. To apply a modifier to a collection in the same manner that 3ds max applies modifiers, use the modPanel.addModToSelection() described in the Modify Panel (p. 1572) topic. A limitation of the addModifier() function is that it cannot generally apply modifiers to sub-object selections, and so it disables any current sub-object levels. To apply a modifier to a sub-object selection in the same manner that 3ds max applies modifiers, use the modPanel.addModToSelection(). This function correctly observes the currently selected sub-object level in the Modify panel.

1098

Chapter 11

3ds max Objects

deleteModifier <node> <modifier_or_index>

lets you delete modifiers from the modifier stack. Takes either a modifier value present on the <node> stack, or an index specifying the index of the modifier to delete, counting from the top of the stack.
collapseStack <node> -- mapped

collapses the modifiers out of a stack, leaving the appropriate resultant editable base class, such as Editable Mesh, Editable Spline, NURBS Surface, etc., as the base object of the node. If there are no modifiers in the stack when this is called, no action is taken. If you want to force a stack collapse or conversion to editable base class form, use one of the node conversion functions, such as convertToMesh(),convertToSplineShape(), etc. See the methods section in Node Common Properties, Operators, and Methods (p. 820) for more details.
getModContextTM <node> <modifier>

Returns a Matrix3 value giving the modifiers context transform for the local coordinates used in modifier sub-object gizmos. Accessing the transform properties of a modifier subobject such as a gizmo or a center in MAXScript yields values that are relative to that modifiers context transform, equivalent to the values shown in track view for those properties. If the modifier is not operating on a sub-object selection, such as a face or vertex selection, or if the modifier was interactively applied to an object selection, this context TM is the local coordinate space of the object itself. However, if the modifier is operating on either an object selection set or a sub-object selection, the context transform gives the position and orientation of that selection, and so you can use getModContextTM() to get the world-space transform properties of any of its sub-objects.
getModContextBBoxMin <node> <modifier> getModContextBBoxMax <node> <modifier>

These functions complement the getModContextTM() function and can be used to derive the world-space coordinates of the bounding box of the modifier context. This can be used, for example, to determine the bounds of a modifier operating on a sub-selection or the bounds of an FFD lattice. This is particularly useful for scripting FFD control point placement, since these control points live in a 0-to-1 lattice space--the mod context bounding box gives the world space bounds of this lattice space allowing you to compute scaled lattice space coordinates from world coordinates. The functions return Point3 values for the minimum and maximum extents of the bounding box.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Modifier Sub-Object Transform Properties (p. 1099)

Modifier Sub-Object Transform Properties

1099

Modifier Sub-Object Transform Properties

In MAXScript, the values of modifier sub-object transform properties, such as centers and gizmo position, rotation and scale, are not given in the current working coordinate system, but rather are typically in the coordinate system of the object to which it is applied. This is in contrast to scene node transform properties. The values given are exactly as would be seen in the sub-objects corresponding track view or as might be referenced in an Expression controller track variable for that sub-object property. To convert from local to world coordinates, you multiply the local coordinates by the nodes objecttransform matrix. To convert from world to local coordinates, you multiple the world coordinates by the inverse of the nodes objecttransform matrix. For example:
obj=box pos:[10,20,30] addModifier obj (affect_region()) objTM=obj.objecttransform modTM=getModContextTM obj obj.affect_region -- calculate world coordinates of end point obj.affect_region.end_point * (inverse modTM) * objTM -- set end point at world coordinates [20,20,0] obj.affect_region.end_point = [20,20,0] * modTM * (inverse objTM)

FFD Control Points FFD control point sub-object properties are also accessible but have several special considerations. The control points properties are named as they appear in the track view, subject to the MAXScript convention of using _ underscores for spaces, so for example:
$foo.ffd_2x2x2.control_point_1 $baz.ffd_3x3x3.control_point_32 = [1,2,3]

There are two special considerations when accessing FFD control points. First, you can only access control points that have ALREADY been animated by hand, or by using the animateVertex() or the animateAll() MAXScript functions (see the Scripting Vertex and Control Point Animation (p. 1461) topic). The FFD doesnt actually create accessible control points until you do this, a behavior that shows up in the track view in normal 3ds max use - you cannot actually place control point keyframes in the track view until youve animated the control point. Second, control point coordinates are in FFD lattice space. This is a normalized space, with [0,0,0] at the lower left-hand corner (at control_point_1) and [1,1,1] at the opposite corner of the FFD lattice, so you have to be careful about computing and scaling correct coordinates when you set them. This is also reflected in the track view for FFD control points in normal 3ds max use - if you look at their values in a keyframe property dialog or a function graph, they are in this normalized lattice space, not world-space coordinates. Youd have to work in this space also if you tried to use expression controllers to control FFDs. The modifier utility functions getModContextBBoxMin() and getModContextBBoxMin() can be used to determine the world-space bounds of an FFD lattice allowing you to compute scaled lattice space coordinates from world coordinates. See details on these functions in the Modifier Common Properties, Operators, and Methods (p. 1096) topic. An example

1100

Chapter 11

3ds max Objects

of accessing and converting coordinate systems for FFD control points is shown in the following script:
b=box pos:[10,20,0] ffd=ffdbox() addModifier b ffd animateVertex ffd 64 cp64posL=ffd.control_point_64 objTM=b.objecttransform modTM=(getModContextTM b ffd)*ffd.lattice_transform.value modBBMin=getModContextBBoxMin b ffd modBBMax=getModContextBBoxMax b ffd cp64posW=(modBBMin+(cp64posL*(modBBMax-modBBMin)) * (inverse modTM) * objTM

Modifier and SpacewarpModifier Types

The following list shows the 3ds max Modifier and SpacewarpModifier class objects: -- Modifier Affect_Region (p. 1103) Bend (p. 1104) Bevel (p. 1106) Bevel_Profile (p. 1108) CameraMap (p. 1109) Cap_Holes (p. 1110) CrossSection (p. 1110) DeleteMesh (p. 1111) DeleteSpline (p. 1111) Disp_Approx (p. 1111) Displace_Mesh (p. 1198) Edit_Mesh (p. 1114) Edit_Patch (p. 1115) Edit_Spline (p. 1115) Extrude (p. 1115) Face_Extrude (p. 1127) FFDBox (p. 1117) FFDCyl (p. 1119) FFD_2x2x2 (p. 1121) FFD_3x3x3 (p. 1123) FFD_4x4x4 (p. 1124)

Modifier Sub-Object Transform Properties

1101

FFD_Select (p. 1126) Fillet_Chamfer (p. 1127) Flex (p. 1128) Lathe (p. 1133) Lattice (p. 1135) Linked_XForm (p. 1136) MaterialByElement (p. 1136) Material (p. 1137) Melt (p. 1138) MeshSmooth (p. 1139) Mesh_Select (p. 1142) Mirror (p. 1143) Morpher (p. 1144) NCurve_Sel (p. 1145) Noise (p. 1145) Normalize_Spline (p. 1146) Normal (p. 1147) NSurf_Sel (p. 1147) Optimize (p. 1148) PatchDeform (p. 1150) PathDeform (p. 1151) Preserve (p. 1152) Push (p. 1153) Relax (p. 1154) Ripple (p. 1154) Skew (p. 1155) Skin (p. 1157) Slice (p. 1165) Smooth (p. 1166) Spherify (p. 1167) SplineSelect (p. 1167) Squeeze (p. 1167) STL_Check (p. 1169) Stretch (p. 1170)

1102

Chapter 11

3ds max Objects

Surface (p. 1171) SurfDeform (p. 1171) Taper (p. 1173) Tesselate (p. 1174) Trim_Extend (p. 1175) Twist (p. 1175) Unwrap_UVW (p. 1176) UVWMap (p. 1188) UVW_XForm (p. 1187) Vertex_Colors (p. 1191) VertexPaint (p. 1191) VolumeSelect (p. 1192) Wave (p. 1194) XForm (p. 1195) -- SpacewarpModifier The SpacewarpModifier classes are separated into two groups. The first group are those classes that bind a node to a SpaceWarp (p. 992) node. The SpacewarpModifier classes in this group are not directly created in MAXScript, but are rather created and applied to a node using the bindSpaceWarp() method. The second group are those SpacewarpModifier classes that are created and applied to a node like any other modifier. -- Spacewarp Binding SpacewarpModifiers SimpleOSMToWSMMod (p. 1196) BombBinding (p. 1196) DeflectorBinding (p. 1196) DisplaceBinding (p. 1196) FFD_Binding (p. 1196) GravityBinding (p. 1196) MotorMod (p. 1196) PathFollowMod (p. 1196) PBombMod (p. 1196) PDynaFlectMod (p. 1196) POmniFlectMod (p. 1196) PushMod (p. 1196) RippleBinding (p. 1196) SDeflectMod (p. 1196)

Affect_Region : Modifier

1103

SDynaFlectMod (p. 1196) SOmniFlectMod (p. 1196) SpaceConform (p. 1196) UDeflectorMod (p. 1196) UDynaFlectMod (p. 1196) UOmniFlectMod (p. 1196) WaveBinding (p. 1196) WindBinding (p. 1196) -- Other SpacewarpModifiers Displace_Mesh (p. 1198) Displace_NURBS (p. 1198) MapScaler (p. 1198) SpaceCameraMap (p. 1199) SpacePatchDeform (p. 1199) SpacePathDeform (p. 1200) SpaceSurfDeform (p. 1201) Surface_Mapper (p. 1202)

Modifiers
Affect_Region : Modifier
Constructor:
affect_region ...

Properties:
<Affect_Region>.falloff Float default: 20.0 -- animatable

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry.
<Affect_Region>.Pinch Float default: 0.0 -- animatable

Raises and lowers the top point of the curve along the vertical axis. Sets the relative pointedness of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis.

1104

Chapter 11

3ds max Objects

<Affect_Region>.Bubble

Float

default: 0.0

-- animatable

Expands and contracts the curve along the vertical axis. Sets the relative fullness of the region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble move the bottom of the curve below the surface, creating a valley around the base of the region.
<Affect_Region>.ignoreBackfacing Booleandefault: off

When on, affects only those vertices whose face normals are in the same general direction as the gizmo arrow. When turned off, all vertices in the Falloff group are affected.
<Affect_Region>.start_point <Affect_Region>.end_point Point3 Point3 default: [0,0,0] -- animatable

The starting point for the application of the affect region.

default: [0,0,25] animatable

The end point for application of the affect region. Methods:

AffectRegionVal <distance> <falloff> <pinch> <bubble>

The standard affect region function, based on a distance and the three affect region parameters (same as the editable mesh). This function is a cubic curve which returns 1 at distance 0, 0 if distance is greater than falloff, and other values for distance between 0 and falloff. Note: The Ignore Back Facing property is not accessible to MAXScript in 3ds max 4.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Bend : Modifier
Constructor:
bend ...

Properties:
<Bend>.angle <Bend>.direction Float Float default: 0.0 default: 0.0 -- animatable -- animatable

The angle to bend from the vertical plane. The direction of the bend relative to the horizontal plane.

Bend : Modifier

1105

<Bend>.axis

Integer

default: 2

Specifies the axis to be bent. Note that this axis is local to the Bend gizmo and not related to the selected entity: X Y Z
<Bend>.limit <Bend>.upperlimit Boolean Float default: false default: 0.0 -- animatable, alias: Upper_Limit

When on, applies limit constraints to the bend effect. The upper boundary in world units from the bend center point beyond which the bend no longer affects geometry.
<Bend>.lowerlimit Float default: 0.0 -- animatable, alias: Lower_Limit

The lower boundary in world units from the bend center point beyond which the bend no longer affects geometry.
<Bend>.center Point3 default: [0,0,0] -- animatable

You can translate and animate the center, altering the Bend gizmos shape, and thus the shape of the bent object.
<Bend>.gizmo SubAnim

You can transform and animate the gizmo like any other object, altering the effect of the Bend modifier.
<Bend.gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the gizmo object. Translating the gizmo translates its center an equal distance.
<Bend.gizmo>.rotation <Bend.gizmo>.scale Quat Point3 default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the gizmo object. Rotating the gizmo takes place with respect to its center. The scaling of the gizmo object. Scaling the gizmo takes place with respect to its center.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1106

Chapter 11

3ds max Objects

Bevel : Modifier
Constructor:
bevel ...

Properties:
<Bevel>.Cap_Bottom Integer default: 1

When on, caps the end with the lowest local Z value (bottom) of the object. When turned off, the bottom is open. OFF ON
<Bevel>.Cap_Top Integer default: 1

When on, caps the end with the highest local Z value (top) of the object. When turned off, the end is left open. OFF ON
<Bevel>.Cap_Type Integer default: 0

Sets cap type: Morph (Creates cap faces suitable for morphing.) Grid (Creates cap faces in a grid pattern. This cap type deforms and renders better than morph capping.)
<Bevel>.Side_Type Integer default: 0

Side type: Linear Sides (Segment interpolation between levels follows a straight line.) Curved Sides (Segment interpolation between levels follows a Bezier curve.)
<Bevel>.segments <Bevel>.Smooth_Levels Integer Integer default: 1 default: 0 -- animatable

The number of intermediate segments between each level. Controls whether smoothing groups are applied to the sides of a beveled object. Caps always use a different smoothing group than the sides. When turned on, smoothing groups are applied to the sides, and the sides appear rounded. When turned off, smoothing groups are not applied, and the sides appear as flat bevels. OFF ON
<Bevel>.Produce_Mapping_Coords Integer default: 0

When turned on, mapping coordinates are applied to the beveled object. OFF ON

Bevel : Modifier

1107

<Bevel>.Keep_Lines_From_Crossing

Integer

default: 0

When on, this prevents outlines from crossing over themselves. This is accomplished by inserting extra vertices in the outline and replacing sharp corners with a flat line segment. OFF ON
<Bevel>.Separation_Between_Lines <Bevel>.Starting_Outline Float Float default: 1.0 default: 0.0 -- animatable -- animatable

The distance to be maintained between edges. The distance the outline is offset from the original shape. A non-zero setting changes the original shapes size. Positive values make the outline larger and negative values make the outline smaller.
<Bevel>.Level_1_Height <Bevel>.Level_1_Outline <Bevel>.Use_Level_2 Float Float Integer default: 0.0 default: 0.0 default: 0 -- animatable -- animatable

The distance of Level 1 above the Start level. The distance to offset the Level 1 outline from the Start Outline. Adds a level after Level 1 when on. OFF ON
<Bevel>.Level_2_Height Float Float Integer default: 0.0 default: 0.0 default: 0 -- animatable -- animatable

The distance above Level 1.

<Bevel>.Level_2_Outline <Bevel>.Use_Level_3

The offset distance of the Level 2 outline from Level 1. Adds a level after the previous level. If Level 2 is not on, Level 3 is added after Level 1. OFF ON
<Bevel>.Level_3_Height <Bevel>.Level_3_Outline Float Float default: 0.0 default: 0.0 -- animatable -- animatable

The distance above the previous level. The offset distance of Level 3 from the previous level.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1108

Chapter 11

3ds max Objects

Bevel_Profile : Modifier
Constructor:
bevel_profile ...

Properties:
<Bevel_Profile>.Produce_Mapping_Coords Integer default: 0

When on, assigns UV coordinates. OFF ON

<Bevel_Profile>.Cap_Bottom Integer default: 1

When on, caps the end with the lowest local Z value (bottom) of the object. When turned off, the bottom is open. OFF ON
<Bevel_Profile>.Cap_Top Integer default: 1

When on, caps the end with the highest local Z value (top) of the object. When turned off, the end is left open. OFF ON
<Bevel_Profile>.Cap_Type Integer default: 0

Cap type: Morph (Selects a deterministic method of capping that provides the same number of vertices for morphing between objects.) Grid (Creates gridded caps that are better for cap deformations.)
<Bevel_Profile>.Keep_Lines_From_Crossing Integer default: 0

When on, prevents beveled surfaces from self intersecting. This requires more processor calculation and can be time-consuming in complex geometry. OFF ON
<Bevel_Profile>.Separation_Between_Lines <Bevel_Profile>.profile_gizmo Float SubAnim default: 1.0 -- animatable

The distance that sides should be kept apart to prevent intersections. You can move, scale, and rotate the gizmo to alter the effect of the bevel profile modifier on the object.
<Bevel_Profile.Profile_Gizmo>.position animatable Point3 default: [0,0,0] --

The position of the profile gizmo.

CameraMap : Modifier

1109

<Bevel_Profile.Profile_Gizmo>.rotation animatable

Quat

default: (quat 0 0 0 1) --

The rotation of the profile gizmo.

<Bevel_Profile.Profile_Gizmo>.scale animatable Point3 default: [1,1,1] --

The scale of the profile gizmo. Note: There is no way to set the Profile shape using MAXScript in 3ds max 4.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

CameraMap : Modifier
Constructor:
cameraMap ...

Properties: There are no additional properties for CameraMap. Note: There is no way to set the Camera using MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1110

Chapter 11

3ds max Objects

Cap_Holes : Modifier
Constructor:
cap_holes ...

Properties:
<Cap_Holes>.Smooth_New_Faces Integer default: 1

When on, assigns the same smoothing group number to all new faces. If possible, this will be a smoothing group number not used elsewhere in the object. OFF ON
<Cap_Holes>.Smooth_With_Old_Faces Integer default: 0

Smoothes new triangular faces using the smoothing groups from bordering old faces. This smoothes only one level in from the perimeter of the border of the hole, so you might need to use both this and the Smooth New Faces option to properly smooth a large hole. OFF ON
<Cap_Holes>.Make_All_New_Edges_Visible Integer default: 0

When on, makes all of the edges visible in the new faces. OFF ON

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

CrossSection : Modifier
Constructor:
crossSection ...

Properties: There are no additional properties for CrossSection.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

DeleteMesh : Modifier

1111

DeleteMesh : Modifier
Constructor:
deleteMesh ...

Properties: There are no additional properties for DeleteMesh.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

DeleteSplineModifier : Modifier
Constructor:
deleteSplineModifier ...

Properties: There are no additional properties for DeleteSplineModifier.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Disp_Approx : Modifier
Constructor:
disp_Approx ...

Properties: There are no additional properties for Disp_Approx.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1112

Chapter 11

3ds max Objects

Displace : Modifier
Constructor:
displace ...

Properties:
<Displace>.strength Float default: 0.0 -- animatable

When set to 0.0, Displace has no effect. Values greater than 0.0 displace object geometry or particles away from the position of the gizmo. Values less than 0.0 displace geometry toward the gizmo.
<Displace>.decay Float default: 0.0 -- animatable

Varies the displacement strength with distance. By default, Displace has the same strength throughout world space. Increasing Decay causes the displacement strength to diminish as distance increases from the position of the Displace gizmo. This has the effect of concentrating the force field near the gizmo, similar to the field around a magnet repelling its opposite charge.
<Displace>.lumCenterEnable Boolean default: false

When on, the software uses .center to determine which level of gray Displace uses as the zero displacement value.
<Displace>.center lumCenter Float default: 0.5 -- animatable, alias:

By default, Displace centers the luminance by using medium (50 percent) gray as the zero displacement value. Gray values greater than 128 displace in the outward direction (away from the Displace gizmo) and gray values less than 128 displace in the inward direction (toward the Displace gizmo). This value adjusts the default. With a Planar projection, the displaced geometry is repositioned above or below the Planar gizmo.
<Displace>.bitmap <Displace>.map <Displace>.blur <Displace>.maptype Bitmap TextureMap Float Integer default: undefined default: undefined default: 0.0 default: 0 -- animatable

This bitmap is used for displacement. This texture map is used for displacement. Blurs or softens the effect of the bitmapped displacement by increasing the value. Type of map projection: Planar (Projects the map from a single plane.) Cylindrical (Projects the map as if it were wrapped around the cylinder.) Spherical (Projects the map from a sphere, with singularities at the top and bottom of the sphere where the bitmap edges meet at the spheres poles.) Shrink Wrap (Projects the map from a sphere, as Spherical does, but truncates the corners of the map and joins them all at a single pole, creating only one singularity at the bottom.)

Displace : Modifier

1113

<Displace>.cap <Displace>.length <Displace>.width <Displace>.height

Boolean Float Float Float

default: false default: 1.0 default: 1.0 default: 1.0 -- animatable -- animatable -- animatable

When on, a copy of the map is projected from the ends of the cylinder. The length of the displace gizmos bounding box. The width of the displace gizmos bounding box. The height of the displace gizmos bounding box. Height has no effect on Planar mapping.
<Displace>.U_Tile <Displace>.U_Flip <Displace>.V_Tile <Displace>.V_Flip <Displace>.W_Tile <Displace>.W_Flip <Displace>.useMap Float Boolean Float Boolean Float Boolean Boolean default: 1.0 default: false default: 1.0 default: false default: 1.0 default: false default: false -- animatable -- animatable -- animatable

The number of times the bitmap repeats along the U-axis. When on, reverses the orientation of the map along the U-axis. The number of times the bitmap repeats along the V-axis. When on, reverses the orientation of the map along the V-axis. The number of times the bitmap repeats along the W-axis. When on, reverses the orientation of the map along the W-axis. When on, has Displace use the UV mapping set earlier in the stack. This has no effect if the object is not mapped.
<Displace>.applyMap Boolean default: false

When on, applies the Displace UV mapping to the bound object. This lets you apply material maps to the object using the same mapping coordinates as the modifier.
<Displace>.Map_or_Vertex_Color Integer default: 0

Specifies whether to apply the displacement projection to a mapping channel or a vertex color channel: Map Channel Vertex Color Channel
<Displace>.Map_Channel <Displace>.axis Integer Integer default: 1 default: 2

The map channel to use for displacement projection. Flips the alignment of the mapping gizmo along one of its three axes: X Y Z

1114

Chapter 11

3ds max Objects

<Displace>.gizmo

SubAnim

You can move, scale, and rotate the gizmo to alter the effect of the displacement modifier on the object.
<Displace.Gizmo>.position <Displace.Gizmo>.rotation <Displace.Gizmo>.scale Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the displace gizmo.

default: (quat 0 0 -1 0) -- animatable default: [1,1,1] -- animatable

The rotation of the displace gizmo. The scaling of the displace gizmo. Note: The Gizmo property is not present until the Displace modifier has been applied to a node.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Edit_Mesh : Modifier
Constructor:
edit_mesh ...

Properties: There are no additional properties for Edit_Mesh. See the getVertSelection(), getFaceSelection(), and getEdgeSelection() functions in the Editable_Mesh (p. 1041) topic for information about accessing the current selections in the Edit_Mesh modifier. See the Editable Mesh Modify Panel Command Modes and Operations section in the Editable_Mesh (p. 1041) topic for information on invoking the various Edit_Mesh operations.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Edit_Patch : Modifier

1115

Edit_Patch : Modifier
Constructor:
edit_patch ...

Properties: There are no additional properties for Edit_Patch. See the Editable Patch Modify Panel Command Modes and Operations section in the Patch (p. 1088) topic for information on invoking the various Edit_Patch operations.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Edit_Spline : Modifier
Constructor:
edit_spline ...

Properties: There are no additional properties for Edit_Spline. See the Editable Spline Modify Panel Command Modes and Operations section in the SplineShape (p. 1079) topic for information on invoking the various Edit_Spline operations.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Extrude : Modifier
Constructor:
extrude ...

Properties:
<Extrude>.amount <Extrude>.segs Float Integer default: 25.0 default: 1 -- animatable -- animatable, alias: segments

The depth of the extrusion. The number of segments that will be created in the extruded object.

1116

Chapter 11

3ds max Objects

<Extrude>.capStart <Extrude>.capEnd <Extrude>.capType

Boolean Boolean Integer

default: true default: true default: 0

When on, generates a flat surface over the start of the extruded object. When on, generates a flat surface over the end of the extruded object. Cap type: Morph (Arranges cap faces in a predictable, repeatable pattern, which is necessary for creating morph targets. Morph capping can generate long, thin faces that dont render or deform as well as grid capping. Use morph capping primarily if youre extruding multiple morph targets.) Grid (Arranges cap faces in a square grid trimmed at the shape boundaries. This method produces a surface of evenly sized faces that can be deformed easily by other modifiers. When you choose the Grid capping option, the grid lines are hidden edges rather than visible edges.)
<Extrude>.output Integer default: 1

Set the output: Patch (Produces an object that you can collapse to a patch object.) Mesh (Produces an object that you can collapse to a mesh object.) NURBS (Produces an object that you can collapse to a NURBS surface.)
<Extrude>.matIDsBoolean default: true

When on, assigns different material IDs to the sides and the caps of the extruded object. Specifically, the sides receive ID 3, and the caps receive IDs 1 and 2.
<Extrude>.useShapeIDsBooleandefault: false

When on, the software uses the material ID values assigned to segments in the modified object.
<Extrude>.smoothBoolean <Extrude>.mapCoords default: true default: false

When on, applies smoothing to the extruded shape.

Boolean

Creates the extruded object with mapping coordinates already applied. When Generate Mapping Coordinates is turned on, additional mapping coordinates are applied to the end caps placing a single 1 x 1 tile on each cap. Note: The Generate Material IDs, Use Shape IDs, and Smooth properties are not accessible to MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

FFDBox : Modifier

1117

FFDBox : Modifier
Constructor:
ffdBox ...

Properties:
<FFDBox>.dispLattice <FFDBox>.dispSource <FFDBox>.deformType <FFDBox>.falloff <FFDBox>.tension <FFDBox>.continuity <FFDBox>.inPoints <FFDBox>.outPoints <FFDBox>.offset Boolean Boolean Integer Float Float Float Boolean Boolean Float default: true -- alias: Lattice

Draws lines connecting the control points to make a grid.

default: false -- alias: Source_Volume default: 0 default: 0.0 default: 25.0 default: 25.0 default: true default: true default: 0.05 -- animatable -- animatable -- animatable -- alias: Inside_Points -- alias: Outside_Points -- animatable

Displays the control points and lattice in their unmodified state. deformType = 0 - Only In Volume; 1 - All Vertices Determines the distance from the lattice that the FFD effect will decrease to zero. Adjusts the tension of the deformation splines. Adjusts the continuity of the deformation splines. Only control points inside the object are affected by Conform to Shape. Only control points outside the object are affected by Conform to Shape. The distance by which control points affected by Conform to Shape are offset from the object surface.
<FFDBox>.lattice_transform SubAnim <FFDBox.lattice_transform>.position <FFDBox.lattice_transform>.rotation <FFDBox.lattice_transform>.scale Point3 Quat Point3 default: [0,0,0] -- animatable default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

Methods:
conformToShape <FFDBox>

conforms the control points of the FFD to the node the FFD is applied to. If an instance of the FFD modifier has been applied to more than one object, no action is performed.
resetLattice <FFDBox>

resets the control points of the FFD to their default positions.

getDimensions <FFDBox> setDimensions <FFDBox> <Point3>

Get and set the number of control points for the FFDBox modifier. The first component value in the Point3 specifies the number of Width control points, the second the number of Length control points, and the third the number of Height control points. The minimum value for each component value is 2.

1118

Chapter 11

3ds max Objects

animateVertex <FFDBox> <control_point_spec>

Applies controllers to the specified control points of the FFD modifier, where <control_point_spec> is one of:
<integer_index> <integer_index_array> #all

By assigning controllers to the control points, the control points are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the control points. For example,
animateVertex $box01.modifier[1] #all

The control points to be animated are specified by index number or with the keyword #all to animate all control points. See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation (p. 1461) for details on accessing the control points in an FFD and Modifier SubObject Transform Properties (p. 1099) for details on the coordinate system used for FFD control points.
animateAll <FFDBox>

Applies controllers to all control points of the FFD modifier. Note: The default number of control points in a FFDBox created by MAXScript is 4x4x4.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Class and Object Inspector Functions (p. 799) Scripting Vertex and Control Point Animation (p. 1461) Modifier Sub-Object Transform Properties (p. 1099)

FFDCyl : Modifier

1119

FFDCyl : Modifier
Constructor:
ffdCyl ...

Properties:
<FFDCyl>.dispLattice <FFDCyl>.dispSource <FFDCyl>.deformType Boolean Boolean Integer default: true -- alias: Lattice

Draws lines connecting the control points to make a grid.

default: false -- alias: Source_Volume default: 0

Displays the control points and lattice in their unmodified state. Deform type: Only In Volume (Deforms vertices that lie inside the source volume. Vertices outside the source volume are not affected.) All Vertices (Deforms all vertices regardless of whether they lie inside or outside the source volume depending on the value in the Falloff spinner. The deformation outside the volume is a continuous extrapolation of the deformation inside the volume. Note that the deformation can be extreme for points far away from the source lattice.)
<FFDCyl>.falloff <FFDCyl>.tension <FFDCyl>.continuity <FFDCyl>.inPoints <FFDCyl>.outPoints <FFDCyl>.offset Float Float Float Boolean Boolean Float default: 0.0 default: 25.0 default: 25.0 default: true default: true default: 0.05 -- animatable -- animatable -- animatable -- alias: Inside_Points -- alias: Outside_Points -- animatable

Determines the distance from the lattice that the FFD effect will decrease to zero. Adjusts the tension of the deformation splines. Adjusts the continuity of the deformation splines. Only control points inside the object are affected by Conform to Shape. Only control points outside the object are affected by Conform to Shape. The distance by which control points affected by Conform to Shape are offset from the object surface.
<FFDCyl>.lattice_transform SubAnim Point3 Quat Point3 default: [0,0,0] -- animatable default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

<FFDCyl.lattice_transform>.position <FFDCyl.lattice_transform>.rotation <FFDCyl.lattice_transform>.scale

1120

Chapter 11

3ds max Objects

Methods:
conformToShape <FFDCyl>

conforms the control points of the FFD to the node the FFD is applied to. If an instance of the FFD modifier has been applied to more than one object, no action is performed.
resetLattice <FFDCyl>

resets the control points of the FFD to their default positions.

getDimensions <FFDCyl> setDimensions <FFDCyl> <Point3>

sets the number of control points for the FFDCyl modifier. The first component value in the Point3 specifies the number of Side control points, the second the number of Radial control points, and the third the number of Height control points. The minimum component values are 6, 2, and 2, respectively.
animateVertex <FFDCyl> <control_point_spec>

Applies controllers to the specified control points of the FFD modifier, where <control_point_spec> is one of:
<integer_index> <integer_index_array> #all

By assigning controllers to the control points, the control points are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the control points. For example,
animateVertex $box01.modifier[1] #all

The control points to be animated are specified by index number or with the keyword #all to animate all control points. See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation (p. 1461) for details on accessing the control points in an FFD and Modifier SubObject Transform Properties (p. 1099) for details on the coordinate system used for FFD control points.
animateAll <FFDCyl>

Applies controllers to all control points of the FFD modifier. Note: The default number of control points in a FFDCyl created by MAXScript is always 4x6x4.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Class and Object Inspector Functions (p. 799)

FFD_2x2x2 : Modifier

1121

Scripting Vertex and Control Point Animation (p. 1461) Modifier Sub-Object Transform Properties (p. 1099)

FFD_2x2x2 : Modifier
Constructor:
ffd_2x2x2 ...

Properties:
<FFD_2x2x2>.dispLattice <FFD_2x2x2>.dispSource <FFD_2x2x2>.deformType Boolean Boolean Integer default: true -- alias: Lattice

Draws lines connecting the control points to make a grid.

default: false -- alias: Source_Volume default: 0

Displays the control points and lattice in their unmodified state. Deform type: Only In Volume (Deforms vertices that lie inside the source volume. Vertices outside the source volume are not affected.) All Vertices (Deforms all vertices, regardless of whether they lie inside or outside the source volume.)
<FFD_2x2x2>.inPoints <FFD_2x2x2>.outPoints <FFD_2x2x2>.offset Boolean Boolean Float default: true default: true default: 0.05 -- alias: Inside_Points -- alias: Outside_Points -- animatable

Only control points inside the object are affected by Conform to Shape. Only control points outside the object are affected by Conform to Shape. The distance by which control points affected by Conform to Shape are offset from the object surface.
<FFD_2x2x2>.lattice_transform SubAnim Point3 Quat Point3 default: [0,0,0] --

<FFD_2x2x2.lattice_transform>.position animatable <FFD_2x2x2.lattice_transform>.rotation animatable <FFD_2x2x2.lattice_transform>.scale animatable

default: (quat 0 0 0 1) -default: [1,1,1] --

Note: The Falloff, Tension, and Continuity parameters are not accessible by MAXScript in 3ds max 4.

1122

Chapter 11

3ds max Objects

Methods:
conformToShape <FFD_2x2x2>

conforms the control points of the FFD to the node the FFD is applied to. If an instance of the FFD modifier has been applied to more than one object, no action is performed.
resetLattice <FFD_2x2x2>

resets the control points of the FFD to their default positions.

animateVertex <FFD_2x2x2> <control_point_spec>

Applies controllers to the specified control points of the FFD modifier, where <control_point_spec> is one of:
<integer_index> <integer_index_array> #all

By assigning controllers to the control points, the control points are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the control points. For example,
animateVertex $box01.modifier[1] #all

The control points to be animated are specified by index number or with the keyword #all to animate all control points. See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation (p. 1461) for details on accessing the control points in an FFD and Modifier SubObject Transform Properties (p. 1099) for details on the coordinate system used for FFD control points.
animateAll <FFD_2x2x2>

Applies controllers to all control points of the FFD modifier.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Class and Object Inspector Functions (p. 799) Scripting Vertex and Control Point Animation (p. 1461) Modifier Sub-Object Transform Properties (p. 1099)

FFD_3x3x3 : Modifier

1123

FFD_3x3x3 : Modifier
Constructor:
ffd_3x3x3 ...

Properties:
<FFD_3x3x3>.dispLattice <FFD_3x3x3>.dispSource <FFD_3x3x3>.deformType Boolean Boolean Integer default: true -- alias: Lattice

Draws lines connecting the control points to make a grid.

default: false -- alias: Source_Volume default: 0

Displays the control points and lattice in their unmodified state. Deform type: Only In Volume (Deforms vertices that lie inside the source volume.) All Vertices (Deforms all vertices, regardless of whether they lie inside or outside the source volume.)
<FFD_3x3x3>.inPoints <FFD_3x3x3>.outPoints <FFD_3x3x3>.offset Boolean Boolean Float default: true default: true default: 0.05 -- alias: Inside_Points -- alias: Outside_Points -- animatable

Only control points inside the object are affected by Conform to Shape. Only control points outside the object are affected by Conform to Shape. The distance by which control points affected by Conform to Shape are offset from the object surface.
<FFD_3x3x3>.lattice_transform SubAnim Point3 Quat Point3 default: [0,0,0] --

<FFD_3x3x3.lattice_transform>.position animatable <FFD_3x3x3.lattice_transform>.rotation animatable <FFD_2x2x2.lattice_transform>.scale animatable

default: (quat 0 0 0 1) -default: [1,1,1] --

Note: The Falloff, Tension, and Continuity parameters are not accessible by MAXScript in 3ds max 4. Methods:
conformToShape <FFD_3x3x3>

conforms the control points of the FFD to the node the FFD is applied to. If an instance of the FFD modifier has been applied to more than one object, no action is performed.
resetLattice <FFDBox>

resets the control points of the FFD to their default positions.

1124

Chapter 11

3ds max Objects

animateVertex <FFD_3x3x3> <control_point_spec>

Applies controllers to the specified control points of the FFD modifier, where <control_point_spec> is one of:
<integer_index> <integer_index_array> #all

By assigning controllers to the control points, the control points are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the control points. For example,
animateVertex $box01.modifier[1] #all

The control points to be animated are specified by index number or with the keyword #all to animate all control points. See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation (p. 1461) for details on accessing the control points in an FFD and Modifier SubObject Transform Properties (p. 1099) for details on the coordinate system used for FFD control points.
animateAll <FFD_3x3x3>

Applies controllers to all control points of the FFD modifier.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Class and Object Inspector Functions (p. 799) Scripting Vertex and Control Point Animation (p. 1461) Modifier Sub-Object Transform Properties (p. 1099)

FFD_4x4x4 : Modifier
Constructor:
ffd_4x4x4 ...

Properties:
<FFD_4x4x4>.dispLattice <FFD_4x4x4>.dispSource Boolean Boolean default: true -- alias: Lattice

Draws lines connecting the control points to make a grid.

default: false -- alias: Source_Volume

Displays the control points and lattice in their unmodified state.

FFD_4x4x4 : Modifier

1125

<FFD_4x4x4>.deformType

Integer

default: 0

Deform type: Only In Volume (Deforms vertices that lie inside the source volume.) All Vertices (Deforms all vertices, regardless of whether they lie inside or outside the source volume.)
<FFD_4x4x4>.inPoints <FFD_4x4x4>.outPoints <FFD_4x4x4>.offset Boolean Boolean Float default: true default: true default: 0.05 -- alias: Inside_Points -- alias: Outside_Points -- animatable

Only control points inside the object are affected by Conform to Shape. Only control points outside the object are affected by Conform to Shape. The distance by which control points affected by Conform to Shape are offset from the object surface.
<FFD_4x4x4>.lattice_transform SubAnim Point3 Quat Point3 default: [0,0,0] --

<FFD_4x4x4.lattice_transform>.position animatable <FFD_4x4x4.lattice_transform>.rotation animatable <FFD_4x4x4.lattice_transform>.scale animatable

default: (quat 0 0 0 1) -default: [1,1,1] --

Note: The Falloff, Tension, and Continuity parameters are not accessible by MAXScript in 3ds max 4. Methods:
conformToShape <FFD_4x4x4>

conforms the control points of the FFD to the node the FFD is applied to. If an instance of the FFD modifier has been applied to more than one object, no action is performed.
resetLattice <FFDBox>

resets the control points of the FFD to their default positions.

animateVertex <FFD_4x4x4> <control_point_spec>

Applies controllers to the specified control points of the FFD modifier, where <control_point_spec> is one of:
<integer_index> <integer_index_array> #all

By assigning controllers to the control points, the control points are added to the Master subAnim and appear as animatables in the Track View, allowing further scripting of the control points. For example,
animateVertex $box01.modifier[1] #all

1126

Chapter 11

3ds max Objects

The control points to be animated are specified by index number or with the keyword #all to animate all control points. See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation (p. 1461) for details on accessing the control points in an FFD and Modifier SubObject Transform Properties (p. 1099) for details on the coordinate system used for FFD control points.
animateAll <FFD_4x4x4>

Applies controllers to all control points of the FFD modifier.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Class and Object Inspector Functions (p. 799) Scripting Vertex and Control Point Animation (p. 1461) Modifier Sub-Object Transform Properties (p. 1099)

FFD_Select : Modifier
Constructor:
ffd_select ...

Properties: There are no additional properties for FFD_Select.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Face_Extrude : Modifier

1127

Face_Extrude : Modifier
Constructor:
face_extrude ...

Properties:
<Face_Extrude>.amount Float Float Point3 default: 0.0 default: 100.0 default: [0,0,0] -- animatable -- animatable -- animatable; alias:

The extent of the extrusion.

<Face_Extrude>.scale <Face_Extrude>.extrude_center extrudeFromCenter

Scales each cluster of selected faces independently about its center.

Extrudes each vertex radially from the point. Note: The Extrude From Center parameter is not accessible by MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Fillet_Chamfer : Modifier
Constructor:
fillet_chamfer ...

Properties: There are no additional properties for Fillet_Chamfer.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1128

Chapter 11

3ds max Objects

Flex : Modifier
Constructor:
flex ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Flex>.flex <Flex>.strength <Flex>.sway Float Float Float default: 1.0 default: 3.0 default: 7.0 -- animatable -- animatable -- animatable

Sets the amount of flex and bend. Larger values increase the effect. Range=0 to 1000. Sets the spring strength. A value of 100 is rigid. Range=0 to 100. Sets the time for the object to come to rest. Lower values increase the time for the object to come to rest. Range=0 to 100.
<Flex>.chase <Flex>.center <Flex>.solver Boolean Boolean Integer default: true default: true default: 0

Turns chase springs on/off. Turns the use of weights on/off. The type of solver that will be used: Euler Solver Mid-point solver Runnge Kutta The higher the solver number, the more accurate/stable it is, and the slower it will run.
<Flex>.samples Integer default: 5 -animatable

The number of samples per frame that the solver will use. The higher the number, the more accurate and stable; at the cost of a slower system.
<Flex>.stretch Float default: 5.0 -animatable

This parameter slaves to the stretch strength/sway fields. It is normalized then copied to the strength/sway fields to prevent the system from becoming unstable.
<Flex>.stiffness Float default: 0.1 -animatable

This parameter slaves to the torque strength/sway fields. It is normalized then copied to the strength/sway fields to prevent the system from becoming unstable.
<Flex>.paintStrength Float default: 0.1

Sets the amount of weight that the brush leaves on the mesh. Higher values leave more weight. Range=-1 to 1.
<Flex>.paintRadius <Flex>.paintFeather Float Float default: 36.0 default: 0.7

Set the size of the brush in world units. Range=.001 to 99999. Set the hardness of the brush. A value of 1 is soft. Range=-1 to 1.

Flex : Modifier

1129

<Flex>.absolute

Boolean

default: false

Turn on to change the value of the Vertex Weight parameter to assign absolute weights to the selected vertices. Turn off to add or remove weight based on the vertices current weight.
<Flex>.forceNode ArrayParameter Nodes; alias: Force_Nodes <Flex>.colliderNode <Flex>.referenceFrame <Flex>.endFrame <Flex>.enableEndFrame <Flex>.affectAll ArrayParameter Integer Integer Boolean Boolean default: #() --array containing Force

Assigns force effect to particle space warps identified in an array.

default: #() default: 0 default: 100 default: false default: false default: false -node array

Array contains a list of collider objects that flex will use.

-- alias: Reference_Frame

Flex will start computing at this frame. Flex will stop computing after this time. Turns the end frame on/off. Forces flex to ignore any selection in the stack, causing it to flex the entire object.
<Flex>.enableAdvanceSprings Boolean

Enables the advance spring fields. When this is off, the Stretch and Torque parameters are slaved to the Stretch and Stiffness parameters.
<Flex>.stretchStrength Float <Flex>.stretchSway <Flex>.torqueStrength <Flex>.torqueSway <Flex>.holdLength Float Float Float Boolean default: 0.2 default: 0.2 default: 0.2 default: 0.2 ----animatable animatable animatable animatable

Controls the strength of stretch springs. Controls the sway of stretch springs. Controls the strength of torque springs. Controls the sway of torque springs.
default: false default: 25.0 default: 0

Turns on/off the hold length parameter.

<Flex>.holdLengthPercent Float <Flex>.addMode Integer

The maximum percentage the spring can stretch/squash. Flag to determine how springs will be added: Single spring across selected vertices Edge Springs Edge Springs across only selected vertices Hold Springs Hold Springs across only selected vertices
<Flex>.displaySprings Booleandefault: false

Turns on/off the display of spring when in sub-object mode.

1130

Chapter 11

3ds max Objects

<Flex>.holdRadius <Flex>.extraStrength 0.2, 0.2, 0.2, 0.2)

Float

default: 50.0 default: #(0.2, 0.2, 0.2, 0.2, 0.2, 0.2,

The maximum distance that will be looked around when the hold springs are added.
ArrayParameter -- float array

Control the strength of extra springs (those that belong to a group other than 0 [stretch] or 1 [torque]).
<Flex>.extraSway 0.2, 0.2, 0.2, 0.2) ArrayParameter -- float array default: #(0.2, 0.2, 0.2, 0.2, 0.2, 0.2,

Control the sway of extra springs (those that belong to a group other than 0 [stretch] or 1 [torque]).
<Flex>.lazyEval Boolean default: false

Turns on/off lazy evaluation, which causes the system to be reevaluated less at the expense of a less accurate display.
<Flex>.springColors ArrayParameter default: #([0,0,1], [0.909091,0,0], [0.818182,0,0], [0.727273,0,0], [0.636364,0,0], [0.545455,0,0], [0.454545,0,0], [0.363636,0,0], [0.272727,0,0], [0.181818,0,0], [0.0909091,0,0], [0,0,0]) -point3 array

The colors for the springs for each group.

<Flex>.customSpringDisplay ArrayParameter default: #(true, true, true, true, true, true, true, true, true, true, true, true) -- bool array

This boolean array lets you turn on/off the display of the spring group.
<Flex>.createSpringDepth Integer <Flex>.createSpringMult Float default: 2 default: 2.0

The number of times the system is recursed when using create soft body. The amount the flex effect is multiplied after each recursion when using create soft body. The following property is defined by Flex, but is not used:
<Flex>.paintBackface Boolean default: true

Flex Methods:
Paint <flex>

Presses the paint button in the flex interface.

SetReference <flex>

Presses the Set Reference button in the flex interface.

Reset <flex>

Presses the Reset button in the flex interface.

AddForce <flex> <force>

Adds a force to the force list. force (node) - The force to be added to the force list.
RemoveForce <flex> <force>

Removes a force to the force list. force (integer) - The index of the force to be removed. If this index = -1 then the selected force will be removed.

Flex : Modifier

1131

NumberVertices <flex>

Returns and integer containing the number of points in the system.

SelectVertices <flex> <sel> <update>

Selects the vertices passed in sel. Sel (bitarray) - The bitarray that holds the selection. Update (boolean) - Determines whether the viewports get updated.
GetSelectedVertices <flex>

Returns bitarray containing the current selected vertices.

GetVertexWeight <flex> <index>

Returns the weight of a specific vertex. index (integer) - The index of the vertex you want to get the weight of.
SetVertexWeight <flex> <Index_tab> <values_tab>

Sets the weight of vertices. These tables should be the same size. index_tab (integer table) - A table of indices of the vertex you want to set the weight of. values_tab (float table) - A table of values containing the weights.
SetEdgeList <flex> <sel> <update>

Sets the edges to sel. Sel (bitarray) - The bitarray that holds the edge selection. Update (boolean) - Determines whether the viewports get updated.
GetEdgeList <flex>

Returns bitarray containing the current edge selection list.

AddSpringFromSelection <flex> <flag> <addDupes>

This creates one spring between 2 selected vertices that belong to a group. flag (integer) - The group that this spring will belong to. addDupes (boolean) - Will add duplicates if true.
addSpring <flex> <a> <b> <flag> <addDupes>

This creates a spring between the 2 specified vertices. a (integer) - Index of vertex of the start of the spring. b (integer) - Index of the vertex of the end of the spring. flag (integer) - Group springs belongs to (0 to12). addDupes (boolean) When true, if there is a duplicate spring it will be added.
removeAllSprings <flex>

Removes all the springs the in the system.

addSpringButton <flex>

Equivalent of hitting the Add Spring button in the interface.

RemoveSpringButton <flex>

Equivalent of hitting the Remove Spring button in the interface.

optionsButton <flex>

Equivalent of hitting the Options button in the interface.

1132

Chapter 11

3ds max Objects

createSimpleSoftButton <flex>

Equivalent of hitting the Create Simple Soft Bodies button in the interface.
RemoveSpringByEnd <flex> <a>

This removes all springs that are connected to a vertex. a (integer) The vertex index to be checked.
removeSpringByEnds <flex> <a> <b>

This removes all springs that are connected to both vertex a and b. a (integer) First vertex index. b (integer) Second vertex index.
removeSpringByIndex <flex> <index>

Remove a spring from the list which is at index in the spring list. index (integer) Index of the spring.
numberSprings <flex>

Returns the number of springs in the system

getSpringGroup <flex> <index>

Returns the group that the spring belongs to. index (integer) Index of the spring you want to examine.
setSpringGroup <flex> <index> <group>

Sets the springs groups. index (integer) Index of the spring. group (integer) The group number (0-12).
getSpringLength <flex> <index>

Gets the rest length of a particular spring. index (integer) Index of the spring that you want to examine.
setSpringLength <flex> <index> <length>

Sets the rest length of a particular spring. index (integer) Index of the spring that you want to examine. length (float) The rest length of the spring.
getIndex <flex> <a> <b>

Returns the index of a spring that uses vertex a and b. a (integer) Index of the start vertex of the spring. b (integer) Index of the start end of the spring. FlexOps Methods:
flexOps.GetNumberVertices <Flex>

Returns the number of vertices in the object the Flex modifier is applied to.
flexOps.GetVertexWeight <Flex> <vertex_index_integer>

Returns the weight of the specified vertex.

flexOps.SelectVertices <Flex> \ ( <vertex_index_integer> | <index_integer_array> | <bitarray> )

Lathe : Modifier

1133

Selects the specified vertices. Clears any previously selected vertices.

flexOps.isEdgeVertex <Flex> <vertex_index_integer>

Returns 0 if the specified vertex is not an edge vertex, 1 if it is an edge vertex.

flexOps.ClearEdgeVertices <Flex> \ ( <vertex_index_integer> | <index_integer_array> )

Sets the specified vertices to not be edge vertices.

flexOps.SetEdgeVertices <Flex> \ ( <vertex_index_integer> | <index_integer_array> )

Sets the specified vertices to be edge vertices.

flexOps.SetVertexWeights <Flex> \ ( <vertex_index_integer> | <index_integer_array> ) \ ( <weight_integer> | <weight_integer_array> )

Assigns the specified weights to the specified vertices. If the vertices and weights are specified as arrays, the arrays must be of equal size. Note: If deferred plug-in loading is enabled, an instance of the Flex modifier must be created before these methods will be visible. This is because these methods are defined in the Flex modifier plug-in.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Lathe : Modifier
Constructor:
lathe ...

Properties:
<Lathe>.degrees Float default: 360.0 -- animatable, angle

Determines the number of degrees that the object is spun around the axis of revolution (0 to 360, default=360). You can set keyframes for Degrees to animate the circular growth of a lathed object. The Lathe axis auto-sizes itself to the height of the shape being lathed.
<Lathe>.weldCore Boolean default: false

When on, simplifies the mesh by welding together vertices that lie on the axis of revolution.
<Lathe>.flipNormals Boolean default: false

Depending on the direction of the vertices on your shape, and the direction of rotation, the lathed object might be inside out. Toggle this value to fix this.
<Lathe>.segs Integer default: 16 -- animatable, alias: segments

Determines how many interpolated segments are created in the surface between the start and endpoint.

1134

Chapter 11

3ds max Objects

<Lathe>.capStart <Lathe>.capEnd <Lathe>.capType

Boolean Boolean Integer

default: false default: false default: 0

Caps the start of the lathed object with Degrees set to less than 360 and a closed shape. Caps the end of the lathed object with Degrees set to less than 360 and a closed shape. Cap type: Morph (Arranges cap faces in a predictable, repeatable pattern necessary for creating morph targets. Morph capping can generate long, thin faces that dont render or deform as well as grid capping. Use morph capping primarily if you are lathing multiple morph targets.) Grid (Arranges cap faces in a square grid trimmed at the shape boundaries. This method produces a surface of evenly sized faces that can easily be deformed by other modifiers.)
<Lathe>.output Integer default: 1

Output: Patch (Produces an object that you can collapse to a patch object.) Mesh (Produces an object that you can collapse to a mesh object.) NURBS (Produces an object that can be collapsed to a NURBS surface.)
<Lathe>.mapCoords Boolean default: false

When on, applies mapping coordinates to the lathed object. When Degrees is less than 360, and Generate Mapping Coordinates is turned on, additional mapping coordinates are applied to the end caps, placing a 1 x 1 tile on each cap.
<Lathe>.matIDs Boolean default: true

When on, the software assigns different material IDs to the sides and the caps of the lathed object. Specifically, the sides receive ID 3, and the caps (when Degrees is less than 360 and the lathed shape is closed) receive IDs 1 and 2.
<Lathe>.useShapeIDs Boolean <Lathe>.smooth <Lathe>.axis Boolean SubAnim Point3 default: [0,0,0] -default: false default: true

When on, the software uses the material ID values assigned to segments in the object. When on, applies smoothing to the extruded shape. At this sub-object level, you can transform and animate the axis of revolution.
<Lathe.axis>.position animatable <Lathe.axis>.rotation <Lathe.axis>.scale animatable

Position of the axis of revolution.

Quat Point3 default: (quat -0.707107 0 0 0.707107) -- animatable default: [1,1,1] --

Rotation of the axis of revolution.

Scale of the axis of revolution.

Lattice : Modifier

1135

Note: The Flip Normals, Generate Material IDs, and Use Shape IDs properties are not accessible by MAXScript in 3ds max 4.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Lattice : Modifier
Constructor:
lattice ...

Properties:
<Lattice>.Strut_Radius Float Integer default: 2.0 default: 1 -- animatable -- animatable

The radius of the struts.

<Lattice>.Strut_Segments

The number of segments along the struts. Increase this value when you need to deform or distort the struts with subsequent modifiers.
<Lattice>.Strut_Sides <Lattice>.Joint_Radius Integer Float Integer default: 4 default: 5.0 default: 1 -- animatable -- animatable -- animatable

The number of sides around the perimeter of the struts. The radius of the joints.
<Lattice>.Joint_Segs

The number of segments in the joints. The more segments, the more spherical the joints shape. Note: The Geometry, Struts Material ID, Struts Ignore Hidden Edges, Struts End Caps, Struts Smooth, Joints Base Type, Joints Material ID, Joints Smooth, and Mapping Coordinates parameters are not accessible by MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1136

Chapter 11

3ds max Objects

Linked_XForm : Modifier
Constructor:
linked_xform ...

Properties:
<Linked_xform>.Control Node default: undefined

Object that the vertices are linked to. When transformed, the vertices follow. Note: While you can assign a node to the Control property in MAXScript, an internal transform in Linked_XForm is not properly set. This will cause an immediate, undesired offset of the geometry of the node the modifier is applied to.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

MaterialByElement : Modifier
Constructor:
materialByElement ...

Properties:
<MaterialByElement>.method Integer default: 1

Set method: Random Distribution (Assigns the materials at random to different elements in the object.) List Frequency (Determines an approximate relative weight (percentage) for each of up to eight material IDs)
<MaterialByElement>.Material_ID_Count Integer default: 2 -- animatable

The minimum number of material IDs to assign. Because material ID assignment is random, setting it to the number of materials in the multi/sub-object material or higher doesnt guarantee that all materials get used.
<MaterialByElement>.Material_ID__1 <MaterialByElement>.Material_ID__2 <MaterialByElement>.Material_ID__3 <MaterialByElement>.Material_ID__4 Float Float Float Float default: 0.5 -- animatable default: 0.5 -- animatable default: 0.0 -- animatable default: 0.0 -- animatable

Approximate relative weight (percentage) for first material ID. Approximate relative weight (percentage) for second material ID. Approximate relative weight (percentage) for third material ID. Approximate relative weight (percentage) for fourth material ID.

MaterialModifier : Modifier

1137

<MaterialByElement>.Material_ID__5 <MaterialByElement>.Material_ID__6 <MaterialByElement>.Material_ID__7 <MaterialByElement>.Material_ID__8 <MaterialByElement>.Random_Seed

Float Float Float Float Integer

default: 0.0 -- animatable default: 0.0 -- animatable default: 0.0 -- animatable default: 0.0 -- animatable default: 12345

Approximate relative weight (percentage) for fifth material ID. Approximate relative weight (percentage) for sixth material ID. Approximate relative weight (percentage) for seventh material ID. Approximate relative weight (percentage) for eighth material ID. The seed value for the (pseudo-)randomization of material ID assignments. Note: Material_ID values are shown as percentages in the 3ds max user interface, but stored as fractions.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

MaterialModifier : Modifier
Constructor:
materialModifier ...

Properties:
<Materialmodifier>.materialid Material_ID Integer default: 1 -- animatable, alias:

The material ID to be assigned. If the input object is in face sub-selection, then the ID is only applied to selected faces, otherwise it is applied to the entire object. The ID number refers to one of the materials in a multi/sub-object material. Note: The default modifier name used when creating a MaterialModifier modifier is material. If you then try to access the modifier as a property of the node it is applied to, a name conflict occurs with the material property of nodes. To prevent this conflict, you should specify a name during MaterialModifier creation. For example:
addModifier myObj (materialModifier materialID:5 name:MaterialMod)

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1138

Chapter 11

3ds max Objects

Melt : Modifier
Constructor:
melt ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Melt>.Melt_Amount <Melt>.Spread Float Float default: 0.0 default: 19.0 -- animatable -- animatable

The extent of the decay, or melting effect applied to the gizmo, thus affecting the object. Specifies how much the object and melt will spread as the Amount value increases. Its basically a bulge along a flat plane.
<Melt>.Solidity_Preset Integer default: 0

The relative height of the center of the melted object. Less-solid substances like jelly tend to settle more in the center as they melt. This group provides several presets for different types of substances, as well as a Custom spinner for setting your own solidity: Ice (The default Solidity setting.) Glass (Uses a high Solidity setting to simulate glass.) Jelly (Causes a significant drooping effect in the center.) Custom (Sets any solidity between 0.2 and 30.0.)
<Melt>.Solidity_Custom_Value Float Integer default: 1.0 default: 0 -- animatable

Custom solidity value.

<Melt>.axis

The axis (local to the object) on which the melt will occur. Note that this axis is local to the Melt gizmo and not related to the selected entity. Z Y X
<Melt>.Negative_Axis Integer default: 0

Normally, the melt occurs from the positive direction toward the negative along a given axis. Turn on Flip Axis to reverse this direction. Dont Flip Axis Flip Axis
<Melt>.center Point3 SubAnim default: [0,0,0]

The center of the melt gizmo.

<Melt>.gizmo

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Melt modifier.
<Melt.gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the gizmo. Translating the gizmo translates its center an equal distance.

MeshSmooth : Modifier

1139

<Melt.gizmo>.rotation <Melt.gizmo>.scale

Quat Point3

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the gizmo. Rotating the gizmo takes place with respect to its center. The scaling of the gizmo. Scaling the gizmo takes place with respect to its center. The following properties are defined by Melt, but are not used:
<Melt>.cut_Off__obsolete <Melt>.Confine_To_Gizmo Float Integer default: 0.0 default: 0 -- animatable

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

MeshSmooth : Modifier
Constructor:
meshSmooth ...

Properties:
<MeshSmooth>.subdivMethod Integer default: 2

Selects the Subdivision method to use: Classic (Produces three- and four-sided facets.) Quad Output (Produces only four-sided facets.) NURMS (Produces Non-Uniform Rational MeshSmooth object.)
<MeshSmooth>.Apply_To_Whole_Mesh Boolean default: true

When turned on, any sub-object selection passed up the stack is ignored and MeshSmooth is applied to the entire object. Note that the sub-object selection is still passed up the stack to any subsequent modifiers.
<MeshSmooth>.ignoreSel Boolean default: true

When turned on, any sub-object selection passed up the stack is ignored and MeshSmooth is applied to the entire object.
<MeshSmooth>.oldMapping Boolean default: false

Uses the algorithm from the previous release of the program to apply MeshSmooth to the mapping coordinates. This technique tends to distort the underlying mapping coordinates as it creates new faces and as texture coordinates shift.
<MeshSmooth>.iterations Integer default: 0 -- animatable

The number of iterations used to smooth the mesh. Each iteration generates new faces using the vertices created from the previous iteration.

1140

Chapter 11

3ds max Objects

<MeshSmooth>.smoothness smoothness_filter

Float

default: 1.0

--

animatable; alias:

Determines how sharp a corner must be before faces are added to smooth it. Smoothness is calculated as the average angle of all edges connected to a vertex. A value of 0.0 prevents the creation of any faces. A value of 1.0 adds faces to all vertices even if they lie on a plane.
<MeshSmooth>.useRenderIterations use_render_iterations Boolean default: false; alias:

Turn on/off use of render iterations, for using a different number of iterations at render time. When off, the software will use the iterations value.
<MeshSmooth>.renderIterations render_iterations <MeshSmooth>.useRenderSmoothness use_render_smoothness Integer default: 0 -animatable; alias:

Number of smoothing iterations to be applied to the object at render time.

Boolean default: false; alias:

Turn on/off use of render smoothness, for using a different smoothness value at render time. When off, the software will use the smoothness value.
<MeshSmooth>.renderSmoothness alias: render_smoothness <MeshSmooth>.ignoreBackfacing Float default: 1.0 -animatable;

Lets you choose a different Smoothness value to be applied to the object at render time.
Boolean default: false

When on, selection of sub-objects selects only those sub-objects whose normals are visible in the viewport. When off (the default), selection includes all sub-objects, regardless of the direction of their normals.
<MeshSmooth>.controlLevel Integer default: 0

Allows you to see the control mesh after one or more iterations and to edit sub-object points and edges at that level.
<MeshSmooth>.displayCage display_control_mesh Boolean default: false; alias:

Displays an orange wireframe gizmo that shows what the control mesh looks like after its been converted to polygons (if applicable) and before the smoothing occurs.
<MeshSmooth>.useSoftSel Boolean default: false

Affects the action of Move, Rotate, and Scale functions within editable object or edit modifier, and the action of deformation modifiers applied to the object if they are operating on a sub-object selection. When on, 3ds max applies a spline curve deformation to the unselected sub-objects surrounding the selection that you transform.
<MeshSmooth>.useEdgeDist Boolean Integer default: false

Turn on/off use Edge Distance.

<MeshSmooth>.edgeDist default: 1

Limits the region affected by the number of edges between the selection and the affected vertices.

MeshSmooth : Modifier

1141

<MeshSmooth>.affectBackfacing

Boolean

default: false

When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the normals of faces to which theyre attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence.
<MeshSmooth>.falloff Float default: 20.0

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry.
<MeshSmooth>.pinch Float default: 0.0

Raises and lowers the top point of the curve along the vertical axis. Sets the relative pointedness of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis.
<MeshSmooth>.bubble Float default: 0.0

Expands and contracts the curve along the vertical axis. Sets the relative fullness of the region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble move the bottom of the curve below the surface, creating a valley around the base of the region.
<MeshSmooth>.strength Float default: 0.5 -- animatable

Sets the size of the added faces using a range from 0.0 to 1.0. Values near 0.0 create small faces that are very thin and close to the original vertices and edges, values near 0.5 size faces evenly between edges, and values near 1.0 create large new faces and make the original faces very small.
<MeshSmooth>.Relax <MeshSmooth>.limitSurface project_to_limit_surface Boolean Float default: 0.0 -- animatable

Applies a positive relax effect to smooth all vertices.

default: false; alias:

Places all points on the limit surface of the MeshSmooth result, which is the surface youd get after an infinite number of iterations.
<MeshSmooth>.smoothResult <MeshSmooth>.sepByMats separate_by_materials <MeshSmooth>.sepBySmGroups separate_by_smoothing_group Boolean Boolean default: false; alias: smooth_output

Applies the same smoothing group to all faces.

default: false; alias:

Prevents the creation of new faces for edges between faces that do not share Material IDs.
Boolean default: false; alias:

Prevents the creation of new faces at edges between faces that dont share at least one smoothing group.

1142

Chapter 11

3ds max Objects

<MeshSmooth>.faceType

Integer

default: 1

Select the type to operate on during input conversion: Faces Polygons Operate On Faces treats every triangle as a face and smooths across all edges, even invisible edges. Operate On Polygons ignores invisible edges, treating polygons (like the quads making up a box or the cap on a cylinder) as a single face.
<MeshSmooth>.keepConvex keep_input_faces_convex Boolean default: false; alias:

Keeps all input polygons convex. Selecting this option causes non-convex polygons to be handled as a minimum number of separate faces, each of which is convex.
<MeshSmooth>.update Integer default: 0; alias: update_options

Set update options: Always update Update when rendering Update Manually
<MeshSmooth>.reset Integer default: 0

Select reset settings: Reset all levels Reset this level Note: The edge and vertex weight properties are not accessible to MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Mesh_Select : Modifier
Constructor:
mesh_select ...

Properties:
<Mesh_Select>.Use_Soft_Selection Integer Float Float Float default: 0 default: 20.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable -- animatable

Use_Soft_Selection = 0 - off; 1 - on
<Mesh_Select>.falloff <Mesh_Select>.Pinch <Mesh_Select>.Bubble

Mirror : Modifier

1143

See the getVertSelection(), getFaceSelection(), and getEdgeSelection() functions in the Editable_Mesh (p. 1041) topic for information about accessing the current selections in the Mesh_Select modifier.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Mirror : Modifier
Constructor:
mirror ...

Properties:
<Mirror>.mirror_axis Integer default: 0

The axis or axes about which the mirroring takes place: X Y Z XY YZ ZX

<Mirror>.Mirror_Offset <Mirror>.copy <Mirror>.mirror_center Float Boolean SubAnim default: 0.0 default: false -- animatable

The offset, in units, from the mirror axis. When on, copies the geometry rather than simply mirroring it. Represents the axis of the mirror effect. You can move, rotate or scale the gizmo to affect the mirroring.
<Mirror.Mirror_Center>.position Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the mirror center.

<Mirror.Mirror_Center>.rotation default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the mirror center.

<Mirror.Mirror_Center>.scale

The scaling of the mirror center.

1144

Chapter 11

3ds max Objects

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Morpher : Modifier
Constructor:
Morpher ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Morpher>.Use_Limits <Morpher>.Spinner_Minimum Integer Float Float Integer default: 1 default: 0.0 default: 100.0 default: 0

When on, 3ds max uses the minimum and maximum limits for all channels. The minimum limit.
<Morpher>.Spinner_Maximum

The maximum limit.

<Morpher>.Use_Selection

Turn on to limit morphing to vertices selected in a modifier below the Morpher modifier in the modifier stack.
<Morpher>.Value_Increments <Morpher>.Autoload_of_targets Integer Integer default: 1 default: 0

Turn this on to allow animated targets to be updated dynamically by the Morpher modifier. Note: You cannot get or set the morph channel objects and percentages using MAXScript in 3ds max 4. The morpher modifier developer is planning on releasing a MAXScript extension that will provide access to the morph channel objects. You can access the morph channel percentage controllers as subAnims of the morpher modifier once an object has been assigned to the channel. There is a one-to-one correspondence between the channel number and the subAnim number. For example, if you assign an object to channel 1, the channel 1s percentage controller is stored in subAnim 1.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

NCurve_Sel : Modifier

1145

NCurve_Sel : Modifier
Constructor:
NCurve_Sel ...

Properties: There are no additional properties for NCurve_Sel.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

NoiseModifier : Modifier
Constructor:
noiseModifier ...

Properties:
<Noisemodifier>.seed <Noisemodifier>.scale Integer Float default: 0 default: 100.0 -- animatable -- animatable

A random start point is generated from the number you set. The size of the noise effect (not strength). Larger values produce smoother noise, lower values more jagged noise.
<Noisemodifier>.fractal <Noisemodifier>.roughness <Noisemodifier>.iterations Boolean Float Float default: false default: 0.0 default: 6.0 -- animatable -- animatable, alias: rough -- animatable

When on, produces a fractal effect based on current settings. The extent of fractal variation. Lower values are less rough than higher values. The number of iterations (or octaves) used by the fractal function. Fewer iterations use less fractal energy and generate a smoother effect. An iteration of 1.0 is the same as turning .fractal off.
<Noisemodifier>.strength Point3 default: [0,0,0] -- animatable

The strength of the noise effect along each of three axes. Enter a value for at least one of these axes to produce a noise effect.
<Noisemodifier>.animate <Noisemodifier>.frequency Boolean Float default: false default: 0.25

Enables/disables animation playback. The speed of the noise effect. Higher frequencies make the noise quiver faster. Lower frequencies produce a smoother and more gentle noise.
<Noisemodifier>.phase Time default: 0f -- animatable

1146

Chapter 11

3ds max Objects

Shifts the start and end points of the underlying wave.

<Noisemodifier>.center Point3 default: [0,0,0] -- animatable

You can move, rotate, or scale the center sub-object to affect the noise. You can also animate the sub-object transforms.
<Noisemodifier>.gizmo SubAnim

You can move, rotate, or scale the gizmo sub-object to affect the noise. You can also animate the sub-object transforms.
<Noisemodifier.gizmo>.position Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the gizmo.

<Noisemodifier.gizmo>.rotation default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the gizmo.

<Noisemodifier.gizmo>.scale

The scaling of the gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Normalize_Spline : Modifier
Constructor:
normalize_spline ...

Properties:
<normalize_spline>.Length Float default: 20.0

Determines how many control points are added. Smaller values produce more control points; larger values produce fewer.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

NormalModifier : Modifier

1147

NormalModifier : Modifier
Constructor:
normalModifier ...

Properties:
<Normalmodifier>.unify Boolean default: false

When on, unifies the normals of an object by flipping the normals so that they all point in the same direction, usually outward.
<Normalmodifier>.flip Boolean default: false

When on, reverses the direction of all the surface normals of the faces of the selected object or objects.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

NSurf_Sel : Modifier
Constructor:
NSurf_Sel ...

Properties: There are no additional properties for NSurf_Sel.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1148

Chapter 11

3ds max Objects

Optimize : Modifier
Constructor:
optimize ...

Properties:
<optimize>.renderLOD Integer default: 0

You can store two different optimization settings for the renderer, in two separate levels; L1 & L2. Set the level of display for the default scanline renderer: L1 L2
<optimize>.viewLOD Integer default: 0

You can store two different optimization settings for the viewport, in two separate levels; L1 & L2. Set the level of display for the viewport: L1 L2
<optimize>.facethreshold1 Face_Threshold_L1 Float default: 4.0 -- animatable, angle, alias:

The threshold angle used to determine which faces are collapsed. Low values produce less optimization but better approximations of the original shape. Higher values improve optimization, but are more likely to result in faces that render poorly .
<optimize>.edgethreshold1 Edge_Threshold_L1 Float default: 1.0 -- animatable, angle, alias:

Sets a different threshold angle for open edges (those that bound only one face). A low value preserves open edges. At the same time you can apply a high face threshold to get good optimization.
<optimize>.bias1 Float default: 0.1 -- animatable, alias: Bias_L1

Helps eliminate the skinny or degenerate triangles that occur during optimization, which can cause rendering artifacts. Higher values keeps triangles from becoming degenerate. The default of 0.1 is enough to eliminate the skinniest triangles.
<optimize>.Max_Edge_Length_1 Float default: 0.0 -- animatable

The maximum length, beyond which an edge cannot be stretched when optimized. When Max_Edge_Length_1 is 0, it has no effect. Any value greater than 0 specifies the maximum length of the edges.
<optimize>.preservemat1 <optimize>.preservesmooth1 Boolean Boolean default: false default: false

When on, prevents face collapse across material boundaries. When turned on, allows only faces that share at least one smoothing group to collapse.

Optimize : Modifier

1149

<optimize>.facethreshold2 Face_Threshold_L2

Float

default: 4.0

-- animatable, angle, alias:

The threshold angle used to determine which faces are collapsed. Low values produce less optimization but better approximations of the original shape. Higher values improve optimization, but are more likely to result in faces that render poorly .
<optimize>.edgethreshold2 Edge_Threshold_L2 Float default: 1.0 -- animatable, angle, alias:

Sets a different threshold angle for open edges (those that bound only one face). A low value preserves open edges. At the same time you can apply a high face threshold to get good optimization.
<optimize>.bias2 Float default: 0.1 -- animatable, alias: Bias_L2

Helps eliminate the skinny or degenerate triangles that occur during optimization, which can cause rendering artifacts. Higher values keeps triangles from becoming degenerate. The default of 0.1 is enough to eliminate the skinniest triangles.
<optimize>.Max_Edge_Length_2 Float default: 0.0 -- animatable

The maximum length, beyond which an edge cannot be stretched when optimized. When Max_Edge_Length_2 is 0, it has no effect. Any value greater than 0 specifies the maximum length of the edges.
<optimize>.preservemat2 <optimize>.preservesmooth2 <optimize>.manualUpdate Boolean Boolean Boolean default: false default: false

When on, prevents face collapse across material boundaries. When turned on, allows only faces that share at least one smoothing group to collapse.
default: false

When on, enables the Update button. When turned off, Optimize works as it does by default, updating the viewport display dynamically.
<optimize>.autoedge Boolean default: false

When on, turns edges on and off following optimization. Turns on any open edges. Turns off any edges between faces whose normals are within the face threshold; such edges beyond the threshold are not turned on. Note: The Manual Update property is not accessible to MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1150

Chapter 11

3ds max Objects

PatchDeform : Modifier
Constructor:
patchDeform ...

Properties:
<PatchDeform>.U_Percent percentage Float default: 50.0 -- animatable,

Moves the object along the U (horizontal) axis of the gizmo patch, based on a percentage of the U distance. This defaults to a setting of 50 percent, which places the object at the center of the gizmo patch. A setting of 0 percent places the object at the left edge of the gizmo patch, as seen from the viewport where the patch was created.
<PatchDeform>.U_Stretch <PatchDeform>.V_Percent percentage Float Float default: 1.0 -- animatable

Scales the object along the U (horizontal) axis of the gizmo patch.
default: 50.0 -- animatable,

Moves the object along the V (vertical) axis of the gizmo patch, based on a percentage of the V distance. A setting of 0 percent places the object at the bottom of the gizmo patch.
<PatchDeform>.V_Stretch <PatchDeform>.rotation <PatchDeform>.Plane_to_Patch_Deform Float Float Integer default: 1.0 default: 0.0 default: 0 -- animatable -- animatable, angle

Scales the object along the V (vertical) axis of the gizmo patch. Rotates the modified object with respect to the gizmo patch. Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo patch: XY YZ ZX
<PatchDeform>.Flip_deformation_axis Integer default: 0

When on, reverses the gizmo direction. Dont flip Flip

<PatchDeform>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the modifier. The PatchDeform gizmo is a representation of the deforming patch object, so transforming it determines which part of the patch affects the modified object.

PathDeform : Modifier

1151

<PatchDeform.gizmo>.position <PatchDeform.gizmo>.rotation <PatchDeform.gizmo>.scale

Point3 Quat Point3

default: [0,0,0]

-- animatable

The position of the patchdeform gizmo.

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the patchdeform gizmo. The scale of the patchdeform gizmo. Note: There is no way to specify the patch to deform to using MAXScript in 3ds max 4.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

PathDeform : Modifier
Constructor:
pathDeform ...

Properties:
<PathDeform>.path Node Float default: undefined default: 0.0 -- animatable,

The selected path object.

<PathDeform>.Percent_along_path percentage <PathDeform>.Stretch

Moves the object along the gizmo path based on a percentage of the path length.
Float default: 1.0 -- animatable

Scales the object along the gizmo path, using the objects pivot point as the base of the scale.
<PathDeform>.rotation <PathDeform>.Twist Float Float default: 0.0 -- animatable, angle default: 0.0 -- animatable, angle

Rotates the object about the gizmo path. Twists the object about the path. The twist angle is based on the rotation of one end of the overall length of the path. Typically, the deformed object takes up only a portion of the path, so the effect can be subtle.

1152

Chapter 11

3ds max Objects

<PathDeform>.axis

Integer

default: 2

The axus if the gizmo object which is aligned with the corresponding local axis of the path object: X Y Z
<PathDeform>.Flip_deformation_axis Integer default: 0

When on, reverses the gizmo path 180 degrees about the specified axis. Dont flip Flip
<PathDeform>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the modifier. The PathDeform gizmo is a representation of the deforming path object, so transforming it determines which part of the path affects the modified object.
<PathDeform.Gizmo>.position <PathDeform.Gizmo>.rotation <PathDeform.Gizmo>.scale Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the pathdeform gizmo.

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the pathdeform gizmo. The scale of the pathdeform gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Preserve : Modifier
Constructor:
preserve ...

Properties:
<Preserve>.iterations Integer default: 25 -- animatable

The number of calculations toward the solution. The higher this number, the closer the object comes to matching the original object and the slower the process. When this is set to zero, the original object has no effect, as if the Preserve modifier were never applied.
<Preserve>.Edge_Length_Weight Float default: 1.0 -- animatable

The relative importance of the edge length.

Push : Modifier

1153

<Preserve>.Face_Angle_Weight <Preserve>.Volume_Weight <Preserve>.Apply_To_Whole_Mesh

Float Float Integer

default: 0.3 default: 0.3 default: 0

-- animatable -- animatable

The relative importance of the face angle. The relative importance of the volume. When on, applies Preserve to the entire object, regardless of the selection passed from previous levels of the stack: OFF ON
<Preserve>.Selected_Verts_Only Integer default: 0

When on, uses previous sub-object vertex selections. Note that it doesnt matter if the Vertex sub-object level is active in a previous stack item. As long as vertices have been selected, Preserve will use that selection. OFF ON
<Preserve>.Invert_Selection Integer default: 0

When on, inverts the selection passed up the stack. OFF ON Note: There is no way to specify the Original object using MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Push : Modifier
Constructor:
push ...

Properties:
<Push>.Push_Value Float default: 0.0 -- animatable

The distance in world units by which vertices are moved with respect to the object center. Use a positive value to move vertices outward, or a negative value to move vertices inward.

1154

Chapter 11

3ds max Objects

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Relax : Modifier
Constructor:
relax ...

Properties:
<Relax>.iterations Integer default: 1 -- animatable

The number of times Relax is repeated. Each iteration recalculates average vertex locations based on the result of the previous iteration.
<Relax>.Relax_Value Float default: 0.5 -- animatable

The distance a vertex moves as a percentage of the distance between a vertex and the average location of its neighbors.
<Relax>.Keep_Boundary_Pts_Fixed Integer default: 1

When on, vertices at the edge of open meshes do not relax. OFF ON

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Ripple : Modifier
Constructor:
ripple ...

Properties:
<Ripple>.amplitude1 <Ripple>.amplitude2 <Ripple>.wavelength Float Float Float default: 5.0 default: 5.0 default: 25.0 -- animatable, alias: Amplitude_1 -- animatable, alias: Amplitude_2 -- animatable, alias: Wave_Length

The amplitude of the first ripple. The amplitude of the second ripple, which is perpendicular to the first ripple. The distance between the peaks of the wave. The greater the length, the smoother and more shallow the ripple for a given amplitude.

Skew : Modifier

1155

<Ripple>.phase

Float

default: 0.0

-- animatable

Shifts the ripple pattern over the object. Positive numbers move the pattern inward, while negative numbers move it outward.
<Ripple>.decay Float default: 0.0 -- animatable

Limits the effect of the wave generated from its center. A default decay of zero means that the wave will generate infinitely from its center. Increasing the decay value reduces the distance over which the wave is generated.
<Ripple>.center Point3 default: [0,0,0] -- animatable

At this sub-object level, you can translate and animate the center of the ripple effect, and thus the shape and positions of the ripples.
<Ripple>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Ripple modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Ripple.gizmo>.position <Ripple.gizmo>.rotation <Ripple.gizmo>.scale Point3 Quat Point3 default: [0,0,0] -- animatable

The poosition of the ripple gizmo.

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the ripple gizmo. The scale of the ripple gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Skew : Modifier
Constructor:
skew ...

Properties:
<Skew>.amount <Skew>.direction Float Float default: 25.0 default: 0.0 -- animatable -- animatable

The angle to skew from the vertical plane. The direction of the skew relative to the horizontal plane.

1156

Chapter 11

3ds max Objects

<Skew>.axis

Integer

default: 2

The axis that will be skewed: X Y Z

<Skew>.limit <Skew>.upperlimit Boolean Float default: false default: 0.0 -- animatable, alias: Upper_Limit

When on, applies limit constraints to the Skew modifier. The upper limit boundaries in world units from the skew center point, beyond which the skew no longer affects the geometry.
<Skew>.lowerlimit Float default: 0.0 -- animatable, alias: Lower_Limit

The lower limit boundaries in world units from the skew center point, beyond which the skew no longer affects the geometry.
<Skew>.center <Skew>.gizmo Point3 SubAnim default: [0,0,0] -- animatable

At this sub-object level, you can translate and animate the center of the Skew effect. At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Skew modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Skew.Gizmo>.position <Skew.Gizmo>.rotation <Skew.Gizmo>.scale Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the skew gizmo.

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the skew gizmo. The scale of the skew gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Skin : Modifier

1157

Skin : Modifier
Constructor:
skin ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Skin>.Effect Float default: 0.0 Boolean Boolean Boolean Boolean default: false default: true default: true default: false

Absolute weight of selected vertices.

<Skin>.filter_vertices <Skin>.filter_cross_sections <Skin>.filter_envelopes

Turn vertex selection on/off. Turn cross-section selection on/off. Turn envelope selection on/off.
<Skin>.draw_all_envelopes

When turned on, displays all envelopes. When off, only the selected envelopes are displayed.
<Skin>.draw_vertices <Skin>.ref_frame <Skin>.paint_radius Boolean Integer Float Float Float Boolean default: true default: 0 default: 24.0 default: 0.7 default: 10.0 default: true

Turn on/off the display of weighted vertices. Sets the frame where the bones and the mesh are in a reference position. Sets the brush radius.
<Skin>.paint_feather

Sets the brush falloff.

<Skin>.cross_radius <Skin>.always_deform

Scales the selected envelope cross-section. Always deforms the skin when the bones are moved. The Animate button does not have to be turned on to move bones and deform the skin.
<Skin>.paint_str <Skin>.localSquash <Skin>.initialSquash Float Array Array default: 0.1 default: #() default: #() Boolean --float array float array

Sets the brush strength. Amount of squash applied to each bone. Array containing initial squash values for a bone.
<Skin>.initialStaticEnvelope default: false

When turned on, an initial static envelope size is used when a bone is added. When off, the initial envelope size is determined by the object bounding box.

1158

Chapter 11

3ds max Objects

<Skin>.initialInnerEnvelopePercent Float

default: 0.75

The multiplier used to find the inner cross-section size when initialStaticEnvelope is false.
<Skin>.initialOuterEnvelopePercent Float default: 3.5

The multiplier used to find the outer cross-section size when initialStaticEnvelope is false.
<Skin>.initialEnvelopeInner <Skin>.initialEnvelopeOuter <Skin>.draw_all_gizmos <Skin>.draw_all_vertices <Skin>.shadeweights Boolean Float Float Boolean default: 10.0 default: 50.0 default: true default: false

The inner cross-section size when initialStaticEnvelope is true. The outer cross-section size when initialStaticEnvelope is true. Turn on/off the display off all gizmos.
Boolean

Turns on/off the display of all vertices as small dots.

default: true Boolean Boolean default: true default: true

Turn on/off display of weighted vertices using vertex colors.

<Skin>.envelopesAlwaysOnTop <Skin>.crossSectionsAlwaysOnTop <Skin>.rigid_vertices <Skin>.rigid_handles <Skin>.fast_update <Skin>.gizmos Array Boolean Boolean Boolean

Turn on/off display of envelopes on top of the mesh. Turn on/off display of cross-sections on top of the mesh.
default: false default: false default: false default: #() -max object array

When turned on, a single vertex can only be affected by one bone. When turned on, all handles have the same weights as the knot that owns them. When turned on, the system uses only rigid vertices for the viewport display. Array containing all gizmos assigned to skin. Methods: The following methods require that the Skin modifier be the displayed modifier in the Modify panel, and that the Modify panel is active.
skinops.addbone <Skin> <Bone_node> <Update_integer>

Adds a bone to the current system. For Update_integer, - 1 forces a complete update and redraw, 0 does not update the system. This allows you to add a bunch of bones to a system and then update once at the end.
skinops.addBoneFromViewEnd <Skin>

Ends the addBoneFromViewStart command mode.

skinops.addBoneFromViewStart <Skin>

Puts you in a command mode where you can select bones from the viewport by clicking on them. You can exit this mode by right clicking or calling addBoneFromViewEnd.

Skin : Modifier

1159

skinops.addCrossSection <Skin> <BoneID_integer> <U_float> <OuterRadius_float>

<InnerRadius_float>

Adds a cross section to the bone whose index matches BoneID_integer. U_float, which ranges from 0.0-1.0, defines where along the bone to add the cross-section.
skinops.addCrossSection <Skin> <U_float>

Adds a cross section to the current selected bone. The inner and outer radii are computed based on the neighboring cross sections. U_float, which ranges from 0.0-1.0, defines where along the bone to add the cross-section.
skinops.addCrossSection <Skin> <U_float> <InnerRadius_float> <OuterRadius_float>

Adds a cross section to the current selected bone. U_float, which ranges from 0.0-1.0, defines where along the bone to add the cross-section.
skinops.buttonAdd <Skin>

Presses the add bone button.

skinops.buttonAddCrossSection <Skin>

Presses the add cross section button.

skinops.buttonAddGizmo <Skin>

Presses the add gizmo button in the gizmo rollout.

skinops.buttonCopyGizmo <Skin>

Presses the copy gizmo button in the gizmo rollout.

skinops.buttonExclude <Skin>

Presses the exclude vertices button.

skinops.buttonInclude <Skin>

Presses the include vertices button.

skinops.buttonPaint <Skin>

Presses the paint button.

skinops.buttonPasteGizmo <Skin>

Presses the paste gizmo button in the gizmo rollout.

skinops.buttonRemove <Skin>

Presses the remove bone button.

skinops.buttonRemoveCrossSection <Skin>

Presses the remove cross section button.

skinops.buttonRemoveGizmo <Skin>

Presses the remove gizmo button in the gizmo rollout.

skinops.buttonSelectExcluded <Skin>

Presses the select excluded vertices button.

skinops.copySelectedBone <Skin>

Copies current selected bone properties to the copy buffer.

skinops.enableGizmo <Skin> <GizmoID_integer> <Enable_bool>

Enables/disables the gizmo type whose index equals GizmoID_integer.

1160

Chapter 11

3ds max Objects

skinOps.GetBoneName <Skin> <bone_integer> <nameflag_index>

Returns the name of the indexed bone as a string. where nameflag_index can be 0 or 1. If nameflag_index = 0 the node that holds the transform for this bone is returned; = 1 the name that exists in the list box is returned. If a Bones system is used for the Skin bones, the transform for a bone is held by its parent.
skinops.getBonePropEnvelopeVisible <Skin> <BoneID_integer>

Returns the bone visibility parameter of the bone. 0 is invisible, 1 is visible.

skinops.getBonePropFalloff <Skin> <BoneID_integer>

Returns the falloff parameter of the bone. 1 linear 2 sinual 3 fast out 4 slow out
skinops.getBonePropRelative <Skin> <BoneID_integer>

Gets the relative property of the bone. It returns 1 if relative or 0 is absolute.

skinops.GetCrossSectionU <Skin> <BoneID_integer> <CrossSectionID_integer>

Gets the U value from the specified bone and cross section
skinops.getCurrentSelectGizmoType <Skin>

Returns the current selected gizmo type.

skinops.GetEndPoint <Skin> <BoneID_integer>

Returns a point3 which is the end point of the bone.

skinOps.GetInnerRadius <Skin> \ <bone_integer> <CrossSectionID_integer>

Returns the inner cross section radius for the specified bone and cross section.
skinOps.GetNumberBones <Skin>

Returns the number of bones in the system.

skinOps.getNumberCrossSections <Skin> <bone_integer>

Returns the number of cross sections for the specified bone.

skinops.getNumberOfGizmos <Skin>

Returns the number of gizmos.

skinops.getNumberOfGizmoTypes <Skin>

Returns the number of gizmo types.

skinOps.GetNumberVertices <Skin>

Returns the number of vertices for the object the Skin modifier is applied to.
skinOps.GetOuterRadius <Skin> \ <bone_integer> <CrossSectionID_integer>

Returns the outer cross section radius for the specified bone and cross section.
skinOps.GetSelectedBone <Skin>

Returns the index of the current selected bone in the Bone list.

Skin : Modifier

1161

skinops.getSelectedBonePropEnvelopeVisible <Skin>

Returns the bone visibility parameter of the current selected bone. 0 is invisible, 1 is visible.
skinops.getSelectedBonePropFalloff <Skin>

Returns the falloff parameter of the current selected bone: 1 linear 2 sinual 3 fast out 4 slow out
skinops.getSelectedBonePropRelative <Skin>

Gets the relative property of the current selected bone. It returns 1 if relative or 0 is absolute.
skinops.getSelectedGizmo <Skin>

Returns the current selected gizmo.

skinops.GetStartPoint <Skin> <BoneID_integer>

Returns a point3 which is the start point of the bone.

skinOps.GetVertexWeight <Skin> \ <vertex_integer> <vertex_bone_integer>

Returns the influence of the Nth bone affecting the specified vertex.
skinOps.GetVertexWeightBoneID <Skin> \ <vertex_integer> <vertex_bone_integer>

Returns the system bone index of the Nth bone affecting the specified vertex.
skinOps.GetVertexWeightCount <Skin> <vertex_integer>

Returns the number of bones influencing the specified vertex.

skinops.isBoneSelected <Skin> <BoneID_integer>

Returns 1 if the bone is selected otherwise 0.

skinOps.IsVertexModified <Skin> <vertex_integer>

Returns 1 if the vertex has been modified, 0 if it has not been modified. A modified vertex is vertex that has been weighted by hand or painting, an unmodified vertex weight depends solely on the envelopes.
skinOps.IsVertexSelected <Skin> <vertex_integer>

Returns 1 if the vertex is selected, 0 if it is not selected.

skinops.loadEnvelope <Skin>

Opens the load envelopes dialog

skinops.loadEnvelope <Skin> <filename_string>

Loads the envelopes to the file supplied

skinops.multiRemove <Skin>

Brings up a list box where the user can delete multiple bones instead of one at a time.
skinops.pasteToAllBones <Skin>

Pastes the copy buffer to all the bones.

1162

Chapter 11

3ds max Objects

skinops.pasteToBone

<Skin> <BoneID_int> <Skin>

Pastes the copy buffer to bone id supplied.

skinops.pasteToSelectedBone skinops.removebone <Skin>

Pastes the copy buffer to the current selected bone. Removes the current selected bone from the bones system.
skinops.removebone <Skin> <BoneID_integer>

Removes the BoneID from the bones system.

skinops.RemoveCrossSection $<Skin>

Removes the current selected cross section from the current selected bone.
skinops.RemoveCrossSection <Skin> <BoneID_integer> <CrossSectionID_integer>

Removes a particular cross-section from a particular bone.

skinOps.ReplaceVertexWeights <Skin> <vertex_integer> ( <vertex_bone_integer> | <vertex_bone_array> ) ( <weight_float> | <weight_array> ) \ \

Sets the influence of the specified bone(s) to the specified vertex. Any influence weights for the bone(s) that are not specified are erased. If the bones and weights are specified as arrays, the arrays must be of the same size.
skinops.resetAllBones <Skin>

Resets all bones.

skinops.resetSelectedBone <Skin>

Resets the current selected bone.

skinops.resetSelectedVerts <Skin>

Resets the current selected vertices.

skinops.saveEnvelope <Skin>

Opens the save envelopes dialog

skinops.saveEnvelope <Skin> <filename_string>

Saves the envelopes to the file supplied

skinOps.SelectBone <Skin> <bone_integer>

Selects the specified bone in the Bone list.

skinops.selectCrossSection <Skin> <CrossSectionID_integer> <Inner_Outer_integer>

Selects a cross section on the current selected bone. For Inner_Outer_integer, 0 is the inner envelope 1 is the outer envelope.
skinops.selectEndPoint <Skin>

Selects the start point of the envelope the current selected bone.
skinops.selectGizmo <Skin> <gizmoID_int>

Desc this function selects the gizmo who index equals gizmoID.
skinops.selectGizmoType <Skin> <gizmoTypeID_int>

Selects the gizmo type whose index equals gizmoTypeID.

skinops.selectNextBone <Skin>

Selects the next bone in the bone list.

Skin : Modifier

1163

skinops.selectPreviousBone <Skin>

Selects the next bone in the bone list.

skinops.selectStartPoint <Skin>

Selects the end point of the envelope of the current selected bone.
skinOps.SelectVertices <Skin> \ ( <vertex_integer> | <vertex_array > | <<vertex_bitarray> )

Selects the specified vertices.

skinops.setBonePropEnvelopeVisible <Skin> <BoneID_integer> <Visible_integer>

Sets the bone visibility parameter of the bone whose index matches BoneID_integer. For Visible_integer, 0 is visible, 1 is invisible when not selected.
skinops.setBonePropFalloff <Skin> <BoneID_integer> <Falloff_integer>

Sets the falloff parameter of the bone. For Faloff_integer, the fall off of the bone is: 1 linear 2 sinual 3 fast out 4 slow out
skinops.setBonePropRelative <Skin> <BoneID_integer> <Relative_integer>

Sets the relative property of the bone whose index matches BoneID_integer. For Relative_integer, 0 is absolute and 1 is relative.
skinops.SetCrossSectionU <Skin> <BoneID_integer> <CrossSectionID_integer> <U_float>

Sets the U value from the specified bone and cross section.
skinops.SetEndPoint <Skin> <BoneID_integer> <EndPointPos_point3>

Sets the end point of the specified bone.

skinOps.SetInnerRadius <Skin> \ <bone_integer> <CrossSectionID_integer> <Radius_float>

Sets the inner cross section radius for the specified bone and cross section.
skinOps.SetOuterRadius <Skin> \ <bone_integer> <CrossSectionID_integer> <Radius_float>

Sets the outer cross section radius for the specified bone and cross section.
skinops.setSelectedBonePropEnvelopeVisible <Skin> <Visible_integer>

Sets the bone visibility parameter of the current selected bone. For Visible_integer, 0 = visible, 1 = invisible when not selected

1164

Chapter 11

3ds max Objects

skinops.setSelectedBonePropFalloff

<Skin> <Falloff_integer>

Sets the falloff parameter of the current selected bone. The falloff_integer sets the fall off of the bone: 1 linear 2 sinual 3 fast out 4 slow out
skinops.setSelectedBonePropRelative <Skin> <Relative_integer>

Sets the relative property of the current selected bone. For relative_integer, 0 is relative mode, 1 is absolute mode.
skinops.SetStartPoint <Skin> <BoneID_integer> <EndPointPos_point3>

Sets the start point of the specified bone

skinOps.SetVertexWeights <Skin> <vertex_integer> \ ( <vertex_bone_integer> | <vertex_bone_array> ) ( <weight_float> | <weight_array> ) \

Sets the influence of the specified bone(s) to the specified vertex. Any influence weights for the bone(s) that are not specified are retained. If the bones and weights are specified as arrays, the arrays must be of the same size.
skinops.ZoomToBone <Skin> <All_boolean>

Zooms the active or all views to the selected bone. If All_boolean is true, then all views are zoomed.
skinops.ZoomToGizmo <Skin> <All_boolean>

Zooms the active or all views to the selected gizmo. If All_boolean is true, then all views are zoomed. Note: If deferred plug-in loading is enabled, an instance of the Skin modifier must be created before these methods will be visible. This is because these methods are defined in the Skin modifier plug-in.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

SliceModifier : Modifier

1165

SliceModifier : Modifier
Constructor:
sliceModifier ...

Properties:
<sliceModifier>.Slice_Type Integer default: 0

Defines how the slice plane will affect the geometry to which it has been applied: Refine Mesh (Adds new vertices and edges along the intersection of the geometry with the slicing plane. Faces cut by the plane are subdivided into new faces.) Split Mesh (Adds a double set of vertices and edges along the plane boundary producing two separate meshes (one on either side of the slice plane), which you can modify differently if desired. Use this to break a mesh in two.) Remove Top (Deletes all the faces and vertices above the Slice Plane.) Remove Bottom (Deletes all the faces and vertices below the Slice Plane.)
<sliceModifier>.Faces___Polygons_Toggle Integer default: 1

Specifies how the slice handles quads and other polygons: Operate on Face (Treats the selection set as a set of triangular faces, slicing each one in turn.) Operate on Polygon (Treats the selection set as polygonal facets based on visible edges. Hidden edges within a polygon are recomputed to give the best result for the whole polygons.)
<sliceModifier>.slice_plane SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object to determine where the slice occurs. Scaling the gizmo has no effect, because its extents are effectively infinite. If you need to limit the extent of the slice, use it on a sub-object selection set of faces, rather than on the entire object.
<sliceModifier.Slice_Plane>.position animatable Point3 default: [0,0,0] --

The position of the slice plane object.

<sliceModifier.Slice_Plane>.rotation Quat Point3 default: (quat 0 0 0 1) -- animatable default: [1,1,1] --

The rotation of the slice plane object.

<sliceModifier.Slice_Plane>.scale animatable

The scale of the slice plane object.

1166

Chapter 11

3ds max Objects

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Smooth : Modifier
Constructor:
smooth ...

Properties:
<smooth>.autosmooth Boolean default: false

When on, the object is auto-smoothed using the threshold value. Auto Smooth sets the smoothing groups based on the angle between faces. Any two adjacent faces are put in the same smoothing group if the angle between their normals is less than the threshold angle.
<smooth>.preventIndirect Boolean default: false

Turn on to prevent smoothing leaks when using Auto Smooth. If you apply Auto Smooth to an object, and portions of that object that should not be smoothed become smoothed, then turn on Prevent Indirect Smoothing to see if it corrects the problem.
<smooth>.threshold Float default: 30.0 -- animatable, angle

The threshold angle in degrees. Any two adjacent faces are put in the same smoothing group if the angle between their normals is less than the threshold angle.
<SmoothModifier>.smoothingBits Integer default: 0

The smoothing group assigned to the selected face. Note: See the Editable_Mesh (p. 1041) topic, Face Methods for a description of the smoothing group integer value.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Spherify : Modifier

1167

Spherify : Modifier
Constructor:
spherify ...

Properties:
<Spherify>.percent Float default: 100.0 -- animatable

The percentage of spherical distortion to apply to an object.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

SplineSelect : Modifier
Constructor:
splineSelect ...

Properties: There are no additional properties for SplineSelect.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Squeeze : Modifier
Constructor:
squeeze ...

Properties:
<Squeeze>.Bulge_Amount Float default: 0.0 -- animatable

The magnitude of the bulging effect. Higher values effectively elongate the object and cause the ends to curve outward.
<Squeeze>.Bulge_Curviture Float default: 2.0 -- animatable

The degree of curvature on the bulging ends. You can use this to control whether the bulge is smooth or pointy.

1168

Chapter 11

3ds max Objects

<Squeeze>.Squeeze_Amount

Float

default: 0.0

-- animatable

The magnitude of the squeezing action. Values larger than zero tend to constrict the waist of the object, and values less than zero tend to bulge the waistline out, as if the object had been stepped on.
<Squeeze>.Squeeze_Curvature Float default: 2.0 -- animatable

The degree of curvature into the squeeze. Low values cause a sharp squeezing effect, while high values create a gradual, less pronounced squeeze.
<Squeeze>.Limit_Squeeze_Effects Integer default: 0

When on, limits the extent of the squeeze effect as defined by the Lower and Upper Limit settings. OFF ON
<Squeeze>.Squeeze_Lower_Limit <Squeeze>.Squeeze_Upper_Limit <Squeeze>.Bias percentage <Squeeze>.Volume percentage <Squeeze>.center Float Float Float default: -50.0 default: 50.0 default: 0.0 -- animatable -- animatable -- animatable,

The limit of the squeeze effect in the positive direction along the Z axis. The limit of the squeeze effect in the negative direction along the Z axis.

The relative amounts of bulge and squeeze while retaining a constant object volume.
Float default: 100.0 -- animatable,

Increases or decreases the effects of both Squeeze and Bulge in parallel.

Point3 default: [0,0,0] -- animatable

At this sub-object level, you can translate and animate the center, altering the Squeeze gizmos shape, and thus the shape of the squeezed object.
<Squeeze>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Squeeze modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Squeeze.Gizmo>.position <Squeeze.Gizmo>.rotation <Squeeze.Gizmo>.scale Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the squeeze gizmo.

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the squeeze gizmo. The scale of the squeeze gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

STL_Check : Modifier

1169

STL_Check : Modifier
Constructor:
stl_check ...

Properties:
<STL_Check>.Selection_Type Integer default: 4

Selects incorrect geometry specific to the following settings: Open Edge (Checks for open edges.) Double Face (Checks for faces that share the same 3D space.) Spike (Checks for spikes, which are isolated faces that share only one edge with the object.) Multiple Edge (Checks for faces that share more than one edge.) Everything (Checks for all of the above.)
<STL_Check>.Select_Faces Integer default: 1

These options specify the level of incorrect geometry thats selected, based on the settings for the selection_type value: Dont Select (When on, STL Check doesnt select any part of objects in error.) Select Edges (When on, STL Check marks the edges of faces in error by selecting them. The selection of erroneous edges is visible in viewports.) Select Faces (When on, STL Check marks the faces of any object in error by selecting them. The selection of erroneous faces is visible in viewports.)
<STL_Check>.Check_Now Integer default: 0

Turn on to perform the STL check. For complex objects, expect a pause between the time you turn this on, and the time you see the reported errors in the Status group. OFF ON
<STL_Check>.Change_MatID Integer default: 1

When on, STL Check also marks faces in error by assigning them a unique material ID. OFF ON
<STL_Check>.Material_ID Integer default: 2

The material ID that STL Check assigns to faces in error.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1170

Chapter 11

3ds max Objects

Stretch : Modifier
Constructor:
stretch ...

Properties:
<Stretch>.Stretch Float default: 0.0 -- animatable

The base scale factor for all three axes. The scale factor derived from the Stretch value varies according to the sign of the value.
<Stretch>.Amplify Float default: 0.0 -- animatable

The scale factor applied to the minor axes. Amplify generates a multiplier using the same technique as stretch. The multiplier is then applied to the stretch value before the scale factor for the minor axes is calculated.
<Stretch>.axis Integer default: 2

Determines which of the objects local axes is the Stretch Axis: X Y Z

<Stretch>.limit <Stretch>.from <Stretch>.to <Stretch>.center Boolean Float Float Point3 default: false default: 0.0 default: 0.0 default: [0,0,0] -- animatable -- animatable -- animatable

When on, the stretch effect is limited by the from and to values. The boundary of the stretch effect along the negative Stretch Axis. The boundary of the stretch effect along the positive Stretch Axis. At this sub-object level, you can translate and animate the center, altering the Stretch gizmos shape, and thus the shape of the stretched object.
<Stretch>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Stretch modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Stretch.Gizmo>.position <Stretch.Gizmo>.rotation <Stretch.Gizmo>.scale Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the stretch gizmo.

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the stretch gizmo. The scale of the stretch gizmo. Note: The Limit Effect property is not accessible by MAXScript in 3ds max 4.

Surface : Modifier

1171

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Surface : Modifier
Constructor:
surface ...

Properties:
<surface>.threshold Float default: 1.0 -- animatable

The overall distance that is used to weld the vertices of the spline object. All vertices/ vectors within the threshold of each other are treated as one.
<surface>.steps Integer default: 5 -- animatable

The number of steps used between each vertex. The higher the step count, the smoother the curve you will get between vertices. Note: The Flip Normals, Remove Interior Patches, and Use Only Selected Segs. properties are not accessible by MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

SurfDeform : Modifier
Constructor:
surfDeform ...

Properties:
<SurfDeform>.surface <SurfDeform>.U_Percent percentage Node Float default: undefined default: 50.0 -- animatable,

The surface used to apply deformation.

Moves the object along the U (horizontal) axis of the gizmo patch, based on a percentage of the U distance. This defaults to a setting of 50 percent, which places the object at the center of the gizmo patch. A setting of 0 percent places the object at the left edge of the gizmo patch, as seen from the viewport where the patch was created.

1172

Chapter 11

3ds max Objects

<SurfDeform>.U_Stretch <SurfDeform>.V_Percent percentage

Float Float

default: 1.0 default: 50.0

-- animatable -- animatable,

Scales the object along the U (horizontal) axis of the gizmo patch.

Moves the object along the V (vertical) axis of the gizmo patch, based on a percentage of the V distance. A setting of 0 percent places the object at the bottom of the gizmo patch.
<SurfDeform>.V_Stretch <SurfDeform>.rotation <SurfDeform>.Plane_to_Patch_Deform Float Float Integer default: 1.0 default: 0.0 default: 0 -- animatable -- animatable, angle

Scales the object along the V (vertical) axis of the gizmo patch. Rotates the modified object with respect to the gizmo patch. Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo patch: XY YZ ZX
<SurfDeform>.Flip_deformation_axis Integer default: 0

When on, reverses the gizmo direction. Dont flip Flip

<SurfDeform>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the modifier. The PatchDeform gizmo is a representation of the deforming patch object, so transforming it determines which part of the patch affects the modified object.
<SurfDeform.Gizmo>.position <SurfDeform.Gizmo>.rotation <SurfDeform.Gizmo>.scale Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the surfdeform gizmo.

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the surfdeform gizmo. The scale of the surfdeform gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Taper : Modifier

1173

Taper : Modifier
Constructor:
taper ...

Properties:
<Taper>.amount <Taper>.curve Float Float default: 1.0 default: 0.0 -- animatable -- animatable, alias: curvature

The extent to which the ends are scaled. Amount is a relative value with a maximum of 10. Applies a curvature to the sides of the Taper gizmo, thus affecting the shape of the tapered object. Positive values produce an outward curve along the tapered sides, negative values an inward curve. At 0, the sides are unchanged.
<Taper>.primaryaxis Integer default: 2

The central axis or spine of the taper: X Y Z

<Taper>.effectaxis Integer default: 2

The axis, or pair of axes, indicating the direction of the taper from the primary axis. The available choices are determined by the choice of primary axis. The effect axis can be either of the two remaining axes, or their combination. If the primary axis is X, the effect axis can be Y, Z, or YZ. Z Y ZY
<Taper>.symmetry Boolean default: false -- animatable

When on, produces a symmetrical taper around the primary axis. A taper is always symmetrical around the effect axis.
<Taper>.limit <Taper>.upperlimit Boolean Float default: false default: 0.0 -- animatable, alias: Upper_Limit

Enables/disables upper and lower limits for the taper effect. The upper limit boundaries in world units from the taper center point, beyond which the taper no longer affects the geometry.
<Taper>.lowerlimit Float default: 0.0 -- animatable, alias: Lower_Limit

The lower limit boundaries in world units from the taper center point, beyond which the taper no longer affects the geometry.
<Taper>.center Point3 default: [0,0,0] -- animatable

At this sub-object level, you can translate and animate the center, altering the Taper gizmos shape, and thus the shape of the melted object

1174

Chapter 11

3ds max Objects

<Taper>.gizmo

SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Taper modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Taper.Gizmo>.position <Taper.Gizmo>.rotation <Taper.Gizmo>.scale Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the taper gizmo.

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the taper gizmo. The scale of the taper gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Tessellate : Modifier
Constructor:
tessellate ...

Properties:
<Tessellate>.tension Float default: 2500.0 -- animatable, percentage

Determines if the new faces are flat, concave, or convex after Edge tessellation. A positive value rounds faces by pushing vertices outward. A negative value creates concave faces by pulling vertices inward. A setting of 0 keeps the faces flat. Note: The tension value is 100* the value shown in the 3ds max user interface. Most properties in the Tessellate modifier are not accessible by MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Trim_Extend : Modifier

1175

Trim_Extend : Modifier
Constructor:
trim_extend ...

Properties: There are no additional properties for Trim_Extend.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Twist : Modifier
Constructor:
twist ...

Properties:
<Twist>.angle <Twist>.bias Float Integer default: 0.0 default: 0 -- animatable -- animatable

The amount of twist around the vertical axis. Causes the twist rotation to bunch up at either end of the object. When the parameter is negative, the object twists closer to the gizmo center. When the value is positive, the object twists more away from the gizmo center. When the parameter is 0, the twisting is uniform.
<Twist>.axis Integer default: 2

The axis along which the twist will occur. This is the local axis of the Twist gizmo. X Y Z
<Twist>.limit <Twist>.upperlimit <Twist>.lowerlimit <Twist>.center Boolean Float Float Point3 default: false default: 0.0 default: 0.0 default: [0,0,0] -- animatable, alias: Upper_Limit -- animatable, alias: Lower_Limit -- animatable

When on, applies limit constraints to the Twist modifier. The upper limit for the twist effect. The lower limit for the twist effect. You can translate and animate the center at this sub-object level, altering the Twist gizmos shape, and thus the shape of the twisted object.

1176

Chapter 11

3ds max Objects

<Twist>.gizmo

SubAnim

You can transform and animate the gizmo like any other object at this sub-object level, altering the effect of the Twist modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Twist.Gizmo>.position <Twist.Gizmo>.rotation <Twist.Gizmo>.scale Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the twist gizmo.

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the twist gizmo. The scale of the twist gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Unwrap_UVW : Modifier
Constructor:
unwrap_UVW ...

Note: This class is not available in 3D Studio VIZ. Properties: There are no additional properties for Unwrap_UVW. Methods: The following methods require that the Unwrap UVW modifier be the displayed modifier in the Modify panel, and that the Modify panel is active.
PlanarMap()

Presses the Planar Map button in the rollup interface

Save()

Presses the Save button in the rollup interface

Load()

Presses the Load button in the rollup interface

Reset()

Presses the Reset button in the rollup interface

Edit()

Presses the Edit button in the rollup interface

Unwrap_UVW : Modifier

1177

SetMapChannel <channel>

Sets the Map Channel field in the rollup Channel (integer) The channel that you want to set to.
GetMapChannel()

Returns the Map Channel field value in the rollup

SetVC <VertexColor>

Sets the Vertex Color Channel radio button in the rollup on or off. VertexColor (integer) Turn the vertex color on/off.
GetVC()

Returns the state of the Vertex Color Channel radio button in the rollup.
SetProjectionType <Proj>

Proj (integer) The type of mapping you want: 1 X aligned 2 Y aligned 3 Z aligned 4 normal aligned
GetProjectionType()

Returns the state of the mapping align radio buttons: 1 X aligned 2 Y aligned 3 Z aligned 4 normal aligned
Move()

Presses the Move button in the edit floater.

MoveH()

Presses the Move Horizontal button in the edit floater.

MoveV()

Presses the Move Vertical button in the edit floater.

Rotate()

Presses the Rotate button in the edit floater.

Scale()

Presses the Scale button in the edit floater.

ScaleH()

Presses the Scale Horizontal button in the edit floater.

ScaleV()

Presses the Scale Vertical button in the edit floater.

MirrorH()

Presses the Mirror Horizontal button in the edit floater.

1178

Chapter 11

3ds max Objects

MirrorV()

Presses the Mirror Vertical button in the edit floater.

ExpandSelection()

Presses the Expand Selection button in the edit floater.

ContractSelection()

Presses the Contract Selection button in the edit floater

SetFalloffType <falloff>

Sets the falloff type in the edit floater. falloff (integer) The falloff type: 1 Linear falloff 2 Sinual falloff 3 Fast falloff 4 Slow falloff
GetFalloffType()

Returns the falloff type in the edit floater: 1 Linear falloff 2 Sinual falloff 3 Fast falloff 4 Slow falloff
SetFalloffSpace <space>

Sets the falloff space in the edit floater. space (integer) The space you want the falloff to be computed in: 1 XY (The local space of the object.) 2 UV (The UVW space of the object.)
GetFalloffSpace()

Returns the falloff space in the edit floater.

SetFalloffDist <dist>

Sets the falloff distance in the edit floater. dist (float) The falloff distance.
GetFalloffDist()

Returns the falloff distance from the edit floater.

BreakSelected()

Presses the Break Selected button in the edit floater.

Weld()

Presses the Target Weld button in the edit floater.

WeldSelected()

Presses the Weld Selected button in the edit floater.

Updatemap()

Presses the Update Map button in the edit floater.

Unwrap_UVW : Modifier

1179

Displaymap <DisplayMap>

Toggles the Display Map button in the edit floater. DisplayMap (boolean) The state that you want to set the Display Map to.
IsMapDisplayed()

Returns the state of the Display Map button.

SetUVSpace <UVspace>

Sets the UV Space fly out in the edit floater. UVSpace (integer) The space that you want to view the texture vertices in: 1 UV 2 VW 3 UW
GetUVSpace()

Returns the state of the UV Space fly out in the edit floater: 1 UV 2 VW 3 UW
Options()

Presses the Options button in the edit floater.

Lock()

Toggles the Lock Selected Vertices button in the edit floater.

Hide()

Presses the Hide button in the edit floater.

Unhide()

Presses the Unhide button in the edit floater.

Freeze()

Presses the Freeze button in the edit floater.

Thaw()

Presses the Unfreeze button in the edit floater

FilterSelected()

Toggles the Filter Selected Faces button in the edit floater.

Pan()

Presses the Pan button in the edit floater.

Zoom()

Presses the Zoom button in the edit floater.

ZoomRegion()

Presses the Zoom Region button in the edit floater.

Fit()

Presses the Fit button in the edit floater.

FitSelected()

Presses the Fit Selected button in the edit floater.

1180

Chapter 11

3ds max Objects

Snap()

Presses the Snap button in the edit floater.

GetCurrentMap()

Returns the index into the map drop down list of the current map in the view of the edit floater.
SetCurrentMap <map>

Changes the currently displayed map to the index provided. map (integer) The index of the map in the drop down list that you want to display.
NumberMaps()

Returns the number of maps in the map drop down list.

GetLineColor()

Returns the color of the lines used to connect the texture vertices edges as a Point3 value.
SetLineColor <color>

Sets the line color of the texture vertices. color (point3) The color that you want to set the lines to.
GetSelColor()

Returns the texture vertices selection color as a Point3 value.

SetSelColor <color>

Sets the color of selected texture vertices. color (point3) The color that you want the selected vertice to be.
GetRenderWidth <dist>

Returns the width of the bitmap used to render 2d/3d textures to.
SetRenderWidth <width>

Sets the width of the bitmap used to render to for display. width (integer) The width in pixels for the bitmap.
GetRenderHeight()

Returns the height of the bitmap used to render 2d/3d textures to.
SetRenderHeight <height>

Sets the width of the bitmap used to render to the display. height (integer) - The height in pixels for the bitmap.
GetUseBitmapRes()

Returns the state of the Use Bitmap Resolution as a boolean value. If false, the bitmaps are rendered using the RenderWidth/Height values.
SetUseBitmapRes <useBitmapRes>

Sets the state of the Use Bitmap Resolution value. If it is false the bitmaps are rendered using the RenderWidth/Height values. UseBitmapRes (boolean) - Toggle Use Bitmap Resolution.
GetWeldThresold()

Returns the weld threshold

Unwrap_UVW : Modifier

1181

SetWeldThreshold <threshold>

Sets the threshold values for welds. threshold (float) Threshold for welds.
GetConstantUpdate()

Returns the state of Constant Update as a boolean value. When true, viewport is updated on every move, otherwise it is just updated on mouse up.
SetConstantUpdate <constantUpdates>

Sets the state of the Constant Update value. When true, the viewport is updated on every move, otherwise it is just updated on mouse up.
GetShowSelectedVertices()

Returns a boolean value which indicates whether the selected texture vertices are also displayed in the view port.
SetShowSelectedVertices <show>

Sets whether the selected texture vertices are also displayed in the viewport. show (boolean) The state of Show Selected Vertices.
GetMidPixelSnape()

Returns a boolean value which indicated whether the mid pixels snap is used, if it is false the snap is set to the bottom right corner of the pixel, else it snaps to the center of the pixel.
SetMidPixelSnape <snap>

Sets whether mid pixels snap is used. When false, the snap is set to the bottom right corner of the pixel. When true, it snaps to the center of the pixel. snap (boolean) The mid pixel snap state to be set.
GetMatID()

Returns the current material id index filter.

SetMatID <matid>

Sets the material drop list to the index supplied. matid (integer) The material id index to be set.
NumberMatIDs()

Returns the number of material ids in the material id filter drop down.
GetSelectedVerts()

Returns the current selected texture vertices in the edit floater as a bitarray.
SelectVerts <sel>

Selects texture vertices in the edit floater dialog. sel (bitarray) The selection set.
IsVertexSelected <index>

Returns a boolean value which indicates whether a texture vertex is selected. index (integer) The index of the vertex to check.

1182

Chapter 11

3ds max Objects

MoveSelectedVertices <offset>

Moves the selected texture vertices by the offset. offset (point3) - The offset by which you want to move the vertices.
RotateSelectedVertices <angle>

Rotates the selected vertices around their center point. angle (float) The angle in radians that you want to rotate the selection by.
RotateSelectedVertices <angle> <axis>

Rotates the selected vertices around a specific axis. angle (float) The angle in radians that you want to rotate the selection by. axis (point3) The axis that you want to rotate the selected vertices by. This is in the space of the window.
ScaleSelectedVertices <scale> <dir>

Scales the selected points around their center. scale (float) The amount that you want to scale by. dir (integer) The direction you want to scale by: 0 Scales uniform 1 Scales in the x 2 Scales in the y
ScaleSelectedVertices <scale> <dir> <axis>

Scales the selected points around their center around the axis. scale (float) The amount that you want to scale by. dir (integer) The direction: 0 Scales uniform 1 Scales in the x 2 Scales in the y axis (point3) The axis that you want to rotate the selected vertices by. This is in the space of the window.
GetVertexPosition <time> <index>

Returns the position of the vertex as a Point3 value. time (timevalue) The time at which you wan to check. index (integer) The index of the vertex.
NumberVertices()

Returns the number of texture vertices.

MoveX <p>

This sets the selected vertices x values in absolute coordinates. p (float) The absolute position along the x axis.

Unwrap_UVW : Modifier

1183

MoveY <p>

This sets the selected vertices y values in absolute coordinates. p (float) The absolute position along the y axis.
MoveZ <p>

This sets the selected vertices xzvalues in absolute coordinates. p (float) The absolute position along the z axis.
GetSelectedPolygons()

Returns the selected polygons in the view port as a bitarray.

SelectPolygons <sel>

Selects the polygons in the view ports. sel (bitarray) The polygons to select.
IsPolygonSelected <index>

Returns whether a polygon is selected or not. index (integer) Index of the polygon to check.
NumberPolygons()

Returns the number of polygons in the object.

DetachEdgeVerts()

Detaches any vertex that is not completely surrounded by selected vertices. This is similar to a polygon selection detach except it uses the vertex selection to determine what is detached.
FlipH()

This presses the Flip Horizontal button in the edit floater dialog.
FlipV()

This presses the Flip Vertical button in the edit floater dialog.
GetLockAspect()

Returns whether the edit window aspect ratio is locked or not. If the aspect ratio is not locked the image will try stretch to fit the aspect ratio of the window.
SetLockAspect <aspect>

This sets the Lock Aspect Ratio value. aspect (boolean) Aspect lock toggle.
GetMapScale()

Returns the scaling factor when the user applies a planar map. The smaller the value the more planar map is scaled down
SetMapScale <scale>

Sets the scaling factor when the user applies a planar map. The smaller the value the more planar map is scaled down. scale (float) - The scaling factor for planar map.
GetSelectionFromFace()

This takes the current polygon selection and uses it to select the texture vertices that are associated with it.

1184

Chapter 11

3ds max Objects

ForceUpdate <update>

This sets a flag to determines how Unwrap will behave when a topology change occurs. If update is TRUE the mapping gets reset, otherwise unwrap skips mapping the object if it has a different topology. It is sometimes useful to turn this off if you have MeshSmooth or other topology changing modifiers below Unwrap that have different topologies when rendering. update (boolean) Determines whether the mapping is reset on topology change.
ZoomToGizmo <all>

This zooms the selected or all the viewports to zoom to the current planar map gizmo. all (boolean) Determines whether the active or all the viewports get zoomed.
UpdateView()

This forces the viewport and dialog to update.

SetVertexPosition <t> <index> <pos>

This sets the position of a UVW vertex at a specific time. t (timeValue) The time at what you want to set the pos. index (integer) The index of the vertex. pos (point3) The position of the vertex in UVW space. The functions below work on the UVW topology allowing you to rearrange the topology or add new topology. Use these with care since you can create invalid topology which can cause unpredictable results. Unwrap has topology similar to meshes but it has been changed to support everything except patches and polygons at the same time. Unwrap has a list of Point3 values which are the texture vertices positions. Then there are texture faces which contain an array of integers which are indices into the texture vertex list. There can be 3 to N number of ints in this array depending on the topology being fed into Unwrap. In addition to this, there are also 2 arrays of integers for the handles and interior handles if the topology is a patch which also points into the texture vertex list. The functions below allow you to manipulate these arrays to do things like break, weld, and other topological functions.
MarkAsDead <index>

This marks a vertex that it is dead, and no longer in use. Vertices are not actually deleted they are just marked and recycled when needed. That means that when a vertex is added vertices marked as dead will be the first ones checked. If there are no dead vertices, the vertex is appended to the end of the list. Use this function carefully, since marking a vertex in use as dead will cause strange results. index (integer) The index of the vertex to mark as dead.
NumberPointsInFace <index>

This retrieves the numbers of vertices that a face contains. A face can contain 3 to N number of points depending on what type of topology Unwrap is working on. For Tri Meshes this is always 3; for patches this can be 3 or 4; and for polygons this can be 3 or greater. Unwrap abstracts all three object types into one generic format. index (integer) The index of the face that you are inspecting.

Unwrap_UVW : Modifier

1185

GetVertexIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a vertex, from a face. A face contains 0 to N number of vertices, so to retrieve a particular vertex index, you give it the face index and the ith vertex that you want to inspect. For example, if you wanted to look at the 3 vertex on face 1 you would call GetVertexIndexFromFace (1,3). FaceIndex (integer) The index of the face that you want to inspect. IthVertexIndex (integer) The ith vertex of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains.
GetHandleIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a handle, from a face, which contains 0 to N number of handles. To retrieve a particular handle index, you give it the face index and the ith handle that you want to inspect. For example, if you wanted to look at the 3 handle on face 1 you would call GetHandleIndexFromFace (1,3). This only applies to patch meshes. FaceIndex (integer) The index of the face that you want to inspect. IthVertexIndex (integer) The ith handle of that you want to retrieve. This value should range from 1 to the twice the number of vertices that the face contains.
GetInteriorIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a interior handle from a face. A face contains 0 to N number of interior handles, so to retrieve a particular interior handle index, you give it the face index and the ith interior handle that you want to inspect. For example, if you wanted to look at the 3 interior handle on face 1 you would call GetInteriorIndexFromFace (1,3). This only applies for patch meshes. FaceIndex (integer) The index of the face that you want to inspect. IthVertexIndex (integer) The ith interior handle of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains.
GetVertexGIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a geometric vertex from a face. This the vertex that is attached to the mesh and not the texture faces. A face contains 0 to N number of vertices, so to retrieve a particular vertex index, you give it the face index and the ith vertex that you want to inspect. For example, if you wanted to look at the 3 vertex on face 1 you would call GetVertexGeomIndexFromFace (1,3). FaceIndex (integer) The index of the face that you want to inspect. IthVertexIndex (integer) The ith vertex of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains.
GetHandleGIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a geometric handle from a patch. This the handle that is attached to the patch and not the texture faces. A face contains 0 to N number of handles, so to retrieve a particular handle index, you give it the face index and the ith handle that you want to inspect. For example, if you wanted to look at the 3 handle on face 1 you would call GetHandleGeomIndexFromFace(1,3).

1186

Chapter 11

3ds max Objects

FaceIndex (integer) The index of the face that you want to inspect. IthVertexIndex (integer) The ith handle of that you want to retrieve. This value should range from 1 to twice the number of vertices that the face contains.
GetInteriorGIndexFromFace <faceindex> <ithVertexIndex>

This retrieves the index of a geometric interior handle from a patch. This the interior handle that is attached to the patch and not the texture faces. A face contains 0 to N number of interior handles, so to retrieve a particular interior handle index, you give it the face index and the ith interior handle that you want to inspect. For example, if you wanted to look at the 3 interior handle on face 1 you would call GetInteriorGeomIndexFromFace (1,3). FaceIndex (integer) The index of the face that you want to inspect. IthVertexIndex (integer) The ith interior handle of that you want to retrieve. This value should range from 1 to the number of vertices that the face contains.
SetFaceVertex <pos> <fIndex> <vIndex> <sel>

This allows you to manipulate the position of vertex attached to a face. Basically, it detaches the vertex if multiple faces share that vertex and then moves it to the position specified. So if you want to move the 3rd vertex of face 1 to (.5,.5,.0) you would do setFaceVertex [.5 .5 .0] 1 3. If you dont want the vertex broken use SetVertexSPosition. pos (point3) - The position that you want to move a vertex to. fIndex (integer) The index of the face that you wish to work on. vIndex (integer) The ith vertex of the face that you want to change. sel (boolean) Whether or not to select the vertex after it is recreated.
SetFaceHandle <pos> <fIndex> <vIndex> <sel>

Identical to SetFaceVertex except works on patch handles. pos (point3) - The position that you want to move a vertex to. fIndex (integer) The index of the face that you wish to work on. vIndex (integer) The ith vertex of the face that you want to change. sel (boolean) Whether or not to select the vertex after it is recreated.
SetFaceInterior <pos> <fIndex> <vIndex> <sel>

Identical to SetFaceVertex except works on patch interior handles. pos (point3) - The position that you want to move a vertex to. fIndex (integer) The index of the face that you wish to work on. vIndex (integer) The ith vertex of the face that you want to change. sel (boolean) Whether or not to select the vertex after it is recreated.

UVW_Xform : Modifier

1187

SetFaceVertexIndex <fIndex> <ithV> <vIndex>

This allows you to set the index of the ith vertex of a face. For example, if you wanted to change the index of the 3rd vertex of face 1 to 100 you would call setFaceVertexIndex 1 3 100. fIndex (integer) Index of the face you want work on. ithV (integer) The ith vertex that you want to manipulate. vIndex (integer) The index into the vertex list that you want to set to.
SetFaceHandleIndex <fIndex> <ithV> <vIndex>

Identical to setFaceVertexIndex but works on handles for patches. fIndex (integer) Index of the face you want work on. ithV (integer) The ith vertex that you want to manipulate. vIndex (integer) The index into the vertex list that you want to set to.
SetFaceInteriorIndex <fIndex> <ithV> <vIndex>

Identical to setFaceVertexIndex but works on interior handles for patches. fIndex (integer) Index of the face you want work on. ithV (integer) The ith vertex that you want to manipulate. vIndex (integer) The index into the vertex list that you want to set to.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

UVW_Xform : Modifier
Constructor:
uvw_xform ...

Properties:
<UVW_Xform>.U_Tile Float Integer default: 1.0 default: 0 -- animatable

The tiling along the U-axis.

<UVW_Xform>.U_Flip

When on, reverses the direction of the map along the U-axis. OFF ON
<UVW_Xform>.V_Tile Float default: 1.0 -- animatable

The tiling along the V-axis.

1188

Chapter 11

3ds max Objects

<UVW_Xform>.V_Flip

Integer

default: 0

When on, reverses the direction of the map along the V-axis. OFF ON
<UVW_Xform>.W_Tile Float Integer default: 1.0 default: 0 -- animatable

The tiling along the W-axis.

<UVW_Xform>.W_Flip

When on, reverses the direction of the map along the W-axis. OfFF ON
<UVW_Xform>.U_Offset Float Float Float Integer default: 0.0 default: 0.0 default: 0.0 default: 0 -- animatable -- animatable -- animatable

Offsets the map along the U-axis.

<UVW_Xform>.V_Offset

Offsets the map along the V-axis.

<UVW_Xform>.W_Offset <UVW_Xform>.Map_or_Vertex_Color

Offsets the map along the W-axis. Specifies whether to apply the transform to a mapping channel or a vertex color channel: Map Channel Vertex Color Channel Note: The Map Channel property is not accessible by MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

UVWmap : Modifier
Constructor:
uvwmap ...

Properties:
<Uvwmap>.maptype Integer default: 0

Determines the type of mapping coordinates used. Different kinds of mapping are distinguished by how the map is geometrically projected onto the object and how the projection interacts with the objects surfaces.

UVWmap : Modifier

1189

Planar (Projects the map from a single plane flat against the object, somewhat like projecting a slide. Planar projection is useful when only one side of an object needs to be mapped. It is also useful for obliquely mapping multiple sides, and for mapping two sides of a symmetrical object.) Cylindrical (Projects the map from a cylinder, wrapping it around an object. Seams where the edges of the bitmap meet are visible unless a seamless map is used. Cylindrical projection is useful for objects that are roughly cylindrical in shape.) Spherical (Surrounds the object by projecting the map from a sphere. You see a seam and mapping singularities at the top and bottom of the sphere where the bitmap edges meet at the spheres poles. Spherical mapping is useful for objects that are roughly spherical in shape.) Shrink Wrap (Uses spherical mapping, but truncates the corners of the map and joins them all at a single pole, creating only one singularity. Shrink-wrap mapping is useful when you want to hide the mapping singularity.) Box (Projects the map from the six sides of a box. Each side projects as a planar map, and the effect on the surface depends on the surface normal. Each face is mapped from the closest box surface whose normal most closely parallels its own normal.) Face (Applies a copy of the map to every face of an object. Pairs of faces sharing a hidden edge are mapped with the full rectangular map. Single faces with no hidden edge are mapped with a triangular portion of the map.) XYZ to UVW (Maps 3D procedural coordinates to UVW coordinates. This sticks the procedural texture to the surface. If the surface stretches, so does the 3D procedural map.)
<Uvwmap>.cap <Uvwmap>.length <Uvwmap>.width <Uvwmap>.height <Uvwmap>.utile <Uvwmap>.uflip <Uvwmap>.vtile <Uvwmap>.vflip <Uvwmap>.wtile Boolean Float Float Float Float Boolean Float Boolean Float default: false default: 1.0 default: 1.0 default: 1.0 default: 1.0 default: false default: 1.0 default: false default: 1.0 -- animatable, alias: W_Tile -- animatable, alias: V_Tile -- animatable -- animatable -- animatable -- animatable, alias: U_Tile

When on, applies planar mapping coordinates to the caps of the cylinder. The length of the UVW mapping gizmo. The width of the UVW mapping gizmo. The height of the UVW mapping gizmo. The tiling of the UVW map along the U-axis. When on, reverses the image about the U-axis. The tiling of the UVW map along the V-axis. When on, reverses the image about the V-axis. The tiling of the UVW map along the W-axis.

1190

Chapter 11

3ds max Objects

<Uvwmap>.wflip <Uvwmap>.channel

Boolean Integer

default: false default: 0

When on, reverses the image about the W-axis. Specifies whether to apply the transform to a mapping channel or a vertex color channel: Map Channel Vertex Color Channel
<Uvwmap>.mapChannel <Uvwmap>.axis Integer default: 1

The map channel used to apply mapping transforms.

Integer default: 2

Specifies which axis of the gizmo is aligned with the local Z-axis of the object: X Y Z
<Uvwmap>.gizmo SubAnim

Enables gizmo transformations. Turn on and then move, scale, and rotate the gizmo in the viewports to position the map. In the Material Editor, you turn on the Show Map in Viewport option to make the map visible in a shaded viewport, the map moves on the surface of the object as you transform the gizmo.
<Uvwmap.Gizmo>.position <Uvwmap.Gizmo>.rotation <Uvwmap.Gizmo>.scale Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the UVWmap gizmo.

default: (quat 0 0 -1 0) -- animatable default: [1,1,1] -- animatable

The rotation of the UVWmap gizmo. The scale of the UVWmap gizmo. Note: The Map Channel property is not accessible by MAXScript in 3ds max 4. The Gizmo property is not present until the Uvwmap modifier has been applied to a node.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Vertex_Colors : Modifier

1191

Vertex_Colors : Modifier
Constructor:
The Vertex_Colors modifier is not creatable by MAXScript. It can only be created using the Assign Vertex Colors utility.

Properties: There are no additional properties for Vertex_Colors.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

VertexPaint : Modifier
Constructor:
vertexPaint ...

Note: This class is not available in 3D Studio VIZ. Properties: There are no additional properties for VertexPaint.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1192

Chapter 11

3ds max Objects

VolumeSelect : Modifier
Constructor:
volumeselect ...

Properties:
<Volumeselect>.level Integer default: 0

Volume Select provides three selection levels. Vertex and Face levels put the modifier stack in sub-object selection. You can make one sub-object selection for each Volume Select modifier. You can then toggle the one selection between Face and Vertex level to send either up the stack. Object (top) level lets you modify the whole object while retaining any sub-object selection. Object Vertex Face
<Volumeselect>.type Integer default: 0

Sets the volume select type: Replace (Clears any selection passed up the stack to the Volume Select modifier, and then selects geometry within the volume.) Add (Selects all geometry within the volume, adding to any previous selection.) Subtract (Deselects all geometry within the volume.)
<Volumeselect>.invert Boolean default: false

When on, the entire selection set is reversed. Geometry that was unselected becomes selected, and vice versa.
<Volumeselect>.method Integer default: 0

Lets you determine whether selected faces are wholly or partially within the defined volume: Window (Selects only faces with all three vertices within the selection volume.) Crossing (Selects faces with only one vertex within the selection volume.)
<Volumeselect>.volume Integer default: 0

These controls let you define the selection with a primitive, a mesh object, or by surface characteristics: Box Sphere Cylinder Mesh Object Texture Map Material Id Smoothing Group

VolumeSelect : Modifier

1193

<Volumeselect>.Node <Volumeselect>.matID Material_ID

Node Integer

default: undefined default: 1 -- alias:

The node which defines the selection space when .volume is set to 3 (mesh object).

When .volume is set to 5 (material ID), all faces or vertices using the material ID specified by this value are selected.
<Volumeselect>.smGroup Smoothing_Group Integer default: 1 -- alias:

When .volume is set to 6 (smoothing group), all faces or vertices using the smoothing group specified by this value are selected.
<Volumeselect>.texture TextureMap <Volumeselect>.map Map_Channel_Type TextureMap default: undefined -- alias:

When .volume is set to 4 (texture map), this texture map will define the selection space.
Integer default: 0 -- alias:

Specifies whether to apply the selection by mapping channel or vertex color channel: Map Channel Vertex Color Channel
<Volumeselect>.mapChannel Map_Channel <Volumeselect>.autofit Integer default: 1 -- alias:

Specifies which map channel to use when .map is set to 0.

Boolean default: true -- alias: Auto_fit

When on, automatically adjusts the gizmo size and shape to fit the object as you change the underlying topology.
<Volumeselect>.UseAffectRegion Use_affect_region <Volumeselect>.falloff Boolean default: false -- alias:

When on, a soft selection region is applied.

Float default: 20.0 -- animatable

Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry.
<Volumeselect>.pinch Float default: 0.0 -- animatable

Raises and lowers the top point of the curve along the vertical axis. Sets the relative pointedness of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis.
<Volumeselect>.bubble Float default: 0.0 -- animatable

Expands and contracts the curve along the vertical axis. Sets the relative fullness of the region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble move the bottom of the curve below the surface, creating a valley around the base of the region.

1194

Chapter 11

3ds max Objects

<Volumeselect>.center

Point3

default: [0,0,0]

-- animatable

You can translate and animate the center, which affects rotation or scaling of the Volume Select modifiers gizmo.
<Volumeselect>.gizmo SubAnim

You can transform and animate the gizmo to change the selection. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Volumeselect.Gizmo>.position <Volumeselect.Gizmo>.rotation <Volumeselect.Gizmo>.scale Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the volumeselect gizmo.

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the volumeselect gizmo. The scale of the volumeselect gizmo. Note: The Map Channel property is not accessible by MAXScript in 3ds max 4. The center and gizmo properties are not present until the Volumeselect modifier has been applied to a node.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Wave : Modifier
Constructor:
wave ...

Properties:
<Wave>.amplitude1 Float default: 5.0 -- animatable, alias: Amplitude_1

This produces a sine wave along the gizmo s Y-axis. Switching a value from positive to negative reverses the positions of peaks and troughs.
<Wave>.amplitude2 Float default: 5.0 -- animatable, alias: Amplitude_2

This produces a sine wave the gizmos X-axis. Switching a value from positive to negative reverses the positions of peaks and troughs.
<Wave>.wavelength <Wave>.phase Float Float default: 25.0 default: 0.0 -- animatable, alias: Wave_Length -- animatable

The distance in current units between the crests of both waves. Shifts the wave pattern over the object. Positive numbers move the pattern in one direction, while negative numbers move it in the other.

XForm : Modifier

1195

<Wave>.decay

Float

default: 0.0

-- animatable

Limits the effect of the wave generated from its origin. A decay value decreases the amplitude at increasing distance from the center. As this value increases, the wave is concentrated at the center and flattened until it disappears (completely decays).
<Wave>.center Point3 default: [0,0,0] -- animatable

At this sub-object level, you can translate and animate the center, altering the Wave gizmos shape, and thus the shape of the wavy object.
<Wave>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Wave modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<Wave.Gizmo>.position <Wave.Gizmo>.rotation <Wave.Gizmo>.scale Point3 Quat Point3 default: [0,0,0] -- animatable

The position of the wave gizmo.

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the wave gizmo. The scale of the wave gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

XForm : Modifier
Constructor:
xform ...

Properties:
<XForm>.center Point3 default: [0,0,0] -- animatable

At this sub-object level, you can translate and animate the center, altering the Xform gizmos shape, and thus the shape of the object.
<XForm>.gizmo SubAnim

At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Xform modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center.
<XForm.Gizmo>.position Point3 default: [0,0,0] -- animatable

The position of the wave gizmo.

1196

Chapter 11

3ds max Objects

<XForm.Gizmo>.rotation <XForm.Gizmo>.scale

Quat Point3

default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable

The rotation of the wave gizmo. The scale of the wave gizmo.

See also
Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Spacewarp Binding SpacewarpModifiers

The SpaceWarp Binding SpacewarpModifiers are not directly created in MAXScript, but are rather created and applied to a node using the bindSpaceWarp() method. Most of the SpacewarpModifiers do not have any additional properties. Constructors and Properties:
SimpleOSMToWSMMod: bindSpaceWarp <node> bindSpaceWarp <node> bindSpaceWarp <node> bindSpaceWarp <node> bindSpaceWarp <node> bindSpaceWarp <node> <spaceBend_node> <spaceNoise_node> <spaceSkew_node> <spaceStretch_node> <spaceTaper_node> <spaceTwist_node>

BombBinding: bindSpaceWarp <node> <bomb_node> DeflectorBinding: bindSpaceWarp <particlesys_node> <deflector_node> DisplaceBinding: bindSpaceWarp <node> <spaceDisplace_node> FFD_Binding: bindSpaceWarp <node> <spaceFFDBox_node> bindSpaceWarp <node> <spaceFFDCyl_node> GravityBinding: bindSpaceWarp <node> <gravity_node> MotorMod: bindSpaceWarp <node> <motor_node> PathFollowMod: bindSpaceWarp <particlesys_node> <path_Follow_node>

XForm : Modifier

1197

PBombMod: bindSpaceWarp <node> <pbomb_node> PDynaFlectMod: bindSpaceWarp <node> <PDynaFlect_node> POmniFlectMod: bindSpaceWarp <particlesys_node> <POmniFlect_node> PushMod: bindSpaceWarp <node> <pushSpaceWarp_node> RippleBinding: bindSpaceWarp <node> <spaceRipple_node> <RippleBinding>.Flexibility Float default: 1.0 SDeflectMod: bindSpaceWarp <particlesys_node> <sdeflector_node> SDynaFlectMod: bindSpaceWarp <node> <SDynaFlect_node> SOmniFlectMod: bindSpaceWarp <particlesys_node> <SOmniFlect_node> SpaceConform: bindSpaceWarp <node> <conformSpaceWarp_node> UDeflectorMod: bindSpaceWarp <particlesys_node> <uDeflector_node> UDynaFlectMod: bindSpaceWarp <node> <UDynaFlect_node> UOmniFlectMod: bindSpaceWarp <particlesys_node> <UOmniFlect_node> WaveBinding: bindSpaceWarp <node> <spaceWave_node> <WaveBinding>.Flexibility Float WindBinding: bindSpaceWarp <node> <wind_node>

-- animatable

default: 1.0

-- animatable

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1198

Chapter 11

3ds max Objects

Other SpacewarpModifiers
Displace_Mesh : SpacewarpModifier
Constructor:
displace_Mesh ...

Properties: There are no additional properties for Displace_Mesh.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Displace_NURBS : SpacewarpModifier
Constructor:
displace_NURBS ...

Properties: There are no additional properties for Displace_NURBS.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

MapScaler : SpacewarpModifier
Constructor:
MapScaler ...

Properties:
<MapScaler>.scale Float default: 100.0 -- animatable

The size of one repeat of the texture pattern. Size is measured in current scene units. Repeats occur across the object in the U direction.
<MapScaler>.channel Integer default: 1

The map channel used.

SpaceCameraMap : SpacewarpModifier

1199

<MapScaler>.Wrap_Texture

Integer

default: 1

When on, Map Scaler attempts to wrap the texture evenly around the object. This option requires more computing, but usually produces the most satisfactory results. OFF ON
<MapScaler>.Up_Direction Integer default: 1

Sets the map alignment: World Z Axis (Aligns the map with the Z axis of the world.) Local Z Axis (Aligns the map with the local Z axis of the object.)

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

SpaceCameraMap : SpacewarpModifier
Constructor:
SpaceCameraMap ...

Properties:
<SpaceCameraMap>.camera Node default: undefined

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

SpacePatchDeform : SpacewarpModifier
Constructor:
SpacePatchDeform ...

Properties:
<SpacePatchDeform>.U_Percent percentage Float default: 50.0 -- animatable,

Moves the object along the U (horizontal) axis of the gizmo patch, based on a percentage of the U distance. This defaults to a setting of 50 percent, which places the object at the center of the gizmo patch. A setting of 0 percent places the object at the left edge of the gizmo patch, as seen from the viewport where the patch was created.

1200

Chapter 11

3ds max Objects

<SpacePatchDeform>.U_Stretch <SpacePatchDeform>.V_Percent percentage

Float Float

default: 1.0 default: 50.0

-- animatable -- animatable,

Scales the object along the U (horizontal) axis of the gizmo patch.

Moves the object along the V (vertical) axis of the gizmo patch, based on a percentage of the V distance. A setting of 0 percent places the object at the bottom of the gizmo patch.
<SpacePatchDeform>.V_Stretch <SpacePatchDeform>.rotation angle <SpacePatchDeform>.Plane_to_Patch_Deform Float Float default: 1.0 default: 0.0 -- animatable -- animatable,

Scales the object along the V (vertical) axis of the gizmo patch.

Rotates the modified object with respect to the gizmo patch.

Integer default: 0

Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo patch: XY YZ ZX
<SpacePatchDeform>.Flip_deformation_axis Integer default: 0

When on, reverses the gizmo direction: OFF ON Note: There is no way to specify the patch to deform to using MAXScript in 3ds max 4.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

SpacePathDeform : SpacewarpModifier
Constructor:
SpacePathDeform ...

Properties:
<SpacePathDeform>.path Node Float default: undefined default: 0.0 -- animatable,

The node designated as the path.

<SpacePathDeform>.Percent_along_path percentage

Moves the object along the gizmo path based on a percentage of the path length.

SpaceSurfDeform : SpacewarpModifier

1201

<SpacePathDeform>.Stretch

Float

default: 1.0

-- animatable

Scales the object along the gizmo path, using the objects pivot point as the base of the scale.
<SpacePathDeform>.rotation angle Float default: 0.0 -- animatable,

Rotates the object about the gizmo path.

<SpacePathDeform>.Twist angle Float default: 0.0 -- animatable,

Twists the object about the path. The twist angle is based on the rotation of one end of the overall length of the path. Typically, the deformed object takes up only a portion of the path, so the effect can be subtle.
<SpacePathDeform>.axis Integer default: 2

Choose one to rotate the gizmo path to align with a specified local axis of the object: X Y Z
<SpacePathDeform>.Flip_deformation_axis Integer default: 0

When on, reverses the gizmo path 180 degrees about the specified axis. OFF ON

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

SpaceSurfDeform : SpacewarpModifier
Constructor:
SpaceSurfDeform ...

Properties:
<SpaceSurfDeform>.surface Node Float default: undefined default: 50.0 -- animatable,

The surface used for deformation.

<SpaceSurfDeform>.U_Percent percentage

Moves the object along the U (horizontal) axis of the gizmo patch, based on a percentage of the U distance. This defaults to a setting of 50 percent, which places the object at the center of the gizmo patch. A setting of 0 percent places the object at the left edge of the gizmo patch, as seen from the viewport where the patch was created.

1202

Chapter 11

3ds max Objects

<SpaceSurfDeform>.U_Stretch <SpaceSurfDeform>.V_Percent percentage

Float Float

default: 1.0 default: 50.0

-- animatable -- animatable,

Scales the object along the U (horizontal) axis of the gizmo patch.

Moves the object along the V (vertical) axis of the gizmo patch, based on a percentage of the V distance. A setting of 0 percent places the object at the bottom of the gizmo patch.
<SpaceSurfDeform>.V_Stretch <SpaceSurfDeform>.rotation angle <SpaceSurfDeform>.Plane_to_Patch_Deform Float Float default: 1.0 default: 0.0 -- animatable -- animatable,

Scales the object along the V (vertical) axis of the gizmo patch.

Rotates the modified object with respect to the gizmo patch.

Integer default: 0

Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo patch: XY YZ ZX
<SpaceSurfDeform>.Flip_deformation_axis Integer default: 0

Flip_deformation_axis = 0 - off; 1 - on

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Surface_Mapper : SpacewarpModifier
Constructor:
surface_mapper ...

Properties: There are no additional properties for Surface_Mapper. Methods:

updateSurfaceMapper <surface_mapper>

This method has the effect of performing a manual update to the mapping provided by the associated NURBS surface. Note: There is no way to specify the Source Texture Surface using MAXScript in 3ds max 4.

Material Common Properties, Operators, and Methods

1203

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Material : MAXWrapper
The Material class represents the materials which you can assign to objects in 3ds max. You can create materials like standard, blend, and raytrace, access various properties on them, and assign these materials to 3ds max objects. The classes derived directly from the Material class are described in the Material Types (p. 1204) topic. Other classes are derived from these classes, and inherit the properties and methods defined for the Material class. The properties, operators, and methods that are common to all classes derived directly from the Material class are described in the Material Common Properties, Operators, and Methods (p. 1203) topic. The Material class is derived from the MAXWrapper class, and inherits the properties and methods defined for that class. These properties and methods are described in the MAXWrapper (p. 808) topic.

Material Common Properties, Operators, and Methods

Properties:
<material>.name

All the material subclasses can access the name property and specify it as a constructor parameter.
<material>.effectsChannel

All the material subclasses can access the effectsChannel property and specify it as a constructor parameter. Methods:
assignNewName <material>

Modifies the name of the specified material to make it unique. The name is of the form Material #1 where the number is incremented as required to make ensure its unique.
okMtlForScene <material>

Tests the material name against other material names in the scene, and returns true if there are no other materials with the same name, false otherwise. Before assigning material to scene, call this to avoid duplicate names.

1204

Chapter 11

3ds max Objects

getMTLMEditFlags ( <material> | <texture> ) setMTLMEditFlags ( <material> | <texture> ) <bitarray>

Get and set the MEdit options for the specified material or texture as a <bitarray>. If a bit is on, the corresponding option is turned on. The order of the bits is: #{MTL_BEING_EDITED,BACKGROUND,BACKLIGHT,VIDEO_COLOR_CHECK} The first bit is set if the rollout for the specified material or texture is currently displayed in the active MEdit slot. The state of this bit is ignored in setMTLMEditFlags().
getMTLMeditObjType ( <material> | <texture> ) setMTLMeditObjType ( <material> | <texture> ) <integer>

Get and set the MEdit sample object type for the specified material or texture. The valid values are: 1 - sphere; 2 - cylinder; 3 - cube; 4 - custom
getMTLMeditTiling ( <material> | <texture> ) setMTLMeditTiling ( <material> | <texture> ) <integer>

Get and set the MEdit tiling type for the specified material or texture. The valid values are: 1 - 1x1; 2 - 2x2; 3 - 3x3; 4 - 4x4
updateMTLInMedit ( <material> | <texture> )

Performs a set of 3ds max notifications that forces an update of the material or texture throughout 3ds max, including the MEdit and material browser. You can get and set Material Editor materials using the getMeditMaterial() and setMeditMaterial() functions. You can also get a material from the Material Editor using the meditMaterials virtual array. See the Material Editor (p. 1606) and MaterialLibrary Values (p. 795) topics for more information.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Material Types
The following list displays the 3ds max material subclasses: Blend (p. 1205) Composite (p. 1206) DoubleSided (p. 1207) MatteShadow (p. 1208) MorpherMaterial (p. 1209) MultiMaterial (p. 1210)

Blend : Material

1205

NoMaterial (p. 1212) RaytraceMaterial (p. 1212) Shellac (p. 1233) Standard (p. 1224) TopBottom (p. 1233)

Blend : Material
Constructor:
blend ...

Properties:
<blend>.map1 <blend>.map1Enabled <blend>.map2 <blend>.map2Enabled Material Boolean Material Boolean TextureMap default: Standard default: true default: Standard default: true default: undefined -- alias: Map_1 -- alias: Map_1_Enable -- alias: Map_1 -- alias: Map_2_Enable

The first material to be blended. Turn on/off the use of the first material in the blend. the second material to be blended. Turn on/off
<Blend>.mask

Selects a map to use as a mask. The two materials will blend in greater or lesser degree according to the intensity of the map. Lighter (whiter) areas of the mask show Material 1. Darker (blacker) areas of the mask show Material 2.
<blend>.maskEnabled <blend>.interactive Boolean Integer default: true default: 0 -- alias: MaskEnable

Enable/disable the use of the map mask. Selects which of the two materials is displayed on object surfaces in viewports by the interactive renderer: Material 1 Material 2
<blend>.mixAmount Float default: 0.0 -- animatable; percentage

The proportion of the blend (percentage). 0 means only Material 1 is visible on the surface; 100 means only Material 2 is visible.

1206

Chapter 11

3ds max Objects

<blend>.useCurve <blend>.upper <blend>.lower

Boolean Float Float

default: false default: 0.75 default: 0.25 -- animatable -- animatable

Determines whether the Mixing Curve affects the mix.

These values adjust the level of the Upper and Lower limits. If the two values are the same, the two materials meet at a definite edge. Wider ranges give more gradual blending from one sub-material to the other. The mixing curve displays the effect of changing these values.

See also
Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

CompositeMaterial : Material
Constructor:
compositeMaterial()

Properties:
<compositematerial>.materialList Array default: #(Standard, undefined, ... , undefined, undefined) -- alias: Material

This array contains all of the materials included in the composite material.
<compositematerial>.mapEnables true) -- alias: Map_Enable Array default: #(true, true, ... , true,

This array turns on/off the use of materials (corresponding to the .materialList array) in the composite material.
<compositematerial>.mixType Array default: #(0, 0, ... , 0, 0) -- alias: Composite_Type

This array sets the mix type for each material in the .materialList of the composite material: Additive Subtractive Mix
<compositematerial>.amount 100.0) -- animatable Array default: #(100.0, 100.0, ... , 100.0,

This array sets the amount of mixing for each corresponding material in the .materialList.
<compositematerial>.baseMaterial Standard Material materialList[0] default: (null) alias for

S ets a base material for the composite material.

DoubleSided : Material

1207

Note: The materialList array stores the material for the base material and the sub-materials, the mapEnables array stores whether a sub-material is enabled, the mixTypes array stores the type of mixing to be performed for a sub-material, and the mixTypes array stores the amount of mixing to be performed for a sub-material. The materialList array contains N elements, corresponding to the base material and the (N-1) sub-materials. The remaining arrays store (N-1) elements, corresponding to the (N-1) sub-materials. A property alias exists for each element of the amount array. The property aliases have the name amount_X, where X is the array element index. So the alias for the first amount element is amount_1, for the second amount_2, etc.
baseMaterial is an alias for materialList[1].

See also
Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

DoubleSided : Material
Constructor:
doubleSided ... doubleSidedMat ...

Properties:
<DoubleSided>.translucency Float default: 0.0 -- animatable

The amount that one material shows through the other. This is a percentage that can range from 0.0 to 100.0. At 100 percent, the outer material is visible on inner faces and the inner material is visible on outer faces. At intermediate values, the specified percentage of the inner material bleeds through and is visible on outer faces.
<DoubleSided>.material1 Material Boolean Material Boolean default: Standard default: true default: Standard default: true -- alias: Material_1 -- alias: Map_1_Enable -- alias: Material_2 -- alias: Map_2_Enable

The facing material.

<DoubleSided>.map1Enabled <DoubleSided>.material2

Turn on/off display of the facing material. The back material.

<DoubleSided>.map2Enabled

Turn on/off display of the back material.

1208

Chapter 11

3ds max Objects

See also
Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

MatteShadow : Material
Constructor:
matteShadow ... matte ...

Properties:
<MatteShadow>.opaqueAlpha Boolean default: true -- alias: Opaque_Alpha

Determines whether or not the matte material appears in the alpha channel. If you turn off Opaque Alpha, the matte object will not make an alpha channel, and the image can be used for compositing, just as if there are no matte objects in the scene.
<MatteShadow>.applyAtmosphere <MatteShadow>.atmosphereDepth Boolean Integer default: false default: 0

Turns the fogging of matte objects on and off. When applying fog, you can choose between two different methods. You can either apply fog as if the matte surface is at an infinite distance from the camera or you can apply it as if the matte surface is actually at that point on the object being shaded. In other words, you can apply the fog to the matte surface in either 2D or 3D. The following controls determine how this is applied: At Background Depth (This is the 2D method. The scanline renderer fogs the scene, and then renders its shadows. In this case, the shadows wont be lightened by the fog. If you want to lighten the shadows, you need to turn up the shadow brightness.) At Object Depth (This is the 3D method. The renderer first renders the shadows, and then fogs the scene. Since this varies the amount of fog over the 3D matte surface, the generated matte/alpha channels dont blend perfectly into the background. Use At Object Depth when the matte object is meant to be a 3D object in the scene that the 2D background represents.)
<MatteShadow>.receiveShadows <MatteShadow>.affectAlpha Boolean Boolean default: false default: false

When on, renders shadows on the matte surfaces. When on, shadows cast on a matte material are applied to the alpha channel. This lets you render bitmaps with alpha channels that you can composite later.

MorpherMaterial : Material

1209

<MatteShadow>.shadowBrightness Shadow_Brightness

Float

default: 0.0

-- animatable, alias:

Sets shadow brightness. At 0.5, the shadows will not be attenuated on the matte surface; at 1.0, the shadows are brightened to the color of the matte surface; and at 0.0 they are darkened to completely obliterate the matte surface.
<MatteShadow>.color alias: Shadow_Color Color default: (color 0 0 0) -- animatable,

The color of the shadow.

<MatteShadow>.amount Float percentage, alias: Reflection_Amount <MatteShadow>.map TextureMap Boolean default: 50 -- animatable,

The amount of reflection to use. This is a percentage that can range from 0 to 100.
default: undefined default: true

The map used for reflections.

<MatteShadow>.useReflMap

Turns on/off the use of a reflection map.

See also
Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

MorpherMaterial : Material
Constructor:
morphermaterial ...

Note: This class is not available in 3D Studio VIZ. Properties:

<MorpherMaterial>.Channel_0 <MorpherMaterial>.Channel_1 <MorpherMaterial>.Channel_2 ... <MorpherMaterial>.Channel_98 <MorpherMaterial>.Channel_99 <MorpherMaterial>.Channel_100 Float Float Float Float Float Float default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 default: 0.0 -- animatable, percentage -- animatable, percentage -- animatable, percentage -- animatable, percentage -- animatable, percentage -- percentage

Note: The Morph modifier associated with a MorpherMaterial can not be set using MAXScript in 3ds max 4. The Channel_N properties are instances of the Morph modifier channel percentage properties, where MorpherMaterial Channel_N corresponds to the Morph modifier channel N+1. The MorpherMaterial Channel_100 value corresponds to Morph modifier base object percentage.

1210

Chapter 11

3ds max Objects

The Channel_N property values are 100* the value shown for the corresponding Morph modifier channel percentage value. The submaterial for each channel is stored as a subAnim, and can not be set using MAXScript. Once a material has been assigned to a channel (channel N), the properties of that material can be accessed as subAnim N+1 of the MorpherMaterial, and the base object submaterial is subAnim 101. As an example, suppose you had an object called MyMorph which has two morph channels defined, and a MorpherMaterial applied to it. You would need to assign the channel submaterials in the 3ds max user interface. To access this material and its submaterials you could use:
mtl=$MyMorph.material -- get the MorpherMaterial MM_C1_percent=mtl.Channel_0/100. -- get morph target 1 percentage and scale it correctly MM_C1_mtl=mtl[1] -- get morph target 1 submaterial MM_base_percent=mtl.Channel_100/100. -- get morph base object percentage and scale it correctly MM_base_mtl=mtl[101] -- get morph base object submaterial

See also
Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

MultiMaterial : Material
Constructor:
multimaterial [ numsubs:<integer> ] multiSubMaterial [ numsubs:<integer> ]

Properties:
<multimaterial>.numsubs <multisubmaterial>.numsubs

the number of sub-materials in the multimaterial.

<multimaterial>.materialList ArrayParameter default: #(Standard, Standard, ... Standard, Standard) <multisubmaterial>.materialList ArrayParameter default: #(Standard, Standard, ... Standard, Standard)

Stores the Material for each sub-material.

<multimaterial>.mapEnabled ArrayParameter default: #(true, true, ... true, true) <multisubmaterial>.mapEnabled ArrayParameter default: #(true, true, ... true, true)

Stores whether the sub-material is enabled.

<multimaterial>.names ArrayParameter default: #(, , ... , )

MultiMaterial : Material

1211

<multisubmaterial>.names

ArrayParameter

default: #(, , ... , )

Stores the sub-material slot name (not the sub-material name).

<Multimaterial>.materialIDList ArrayParameter default: #(0, 1, 2, 3, 4, 5, 6, 7, 8, 9) -- int array; Index <Multisubmaterial>.materialIDList ArrayParameter default: #(0, 1, 2, 3, 4, 5, 6, 7, 8, 9) -- int array; Index

Stores the sub-material IDs.

<Multimaterial>.material1 for materialList[0]; SubAnim <Multisubmaterial>.material1 for materialList[0]; SubAnim Standardmaterial Standardmaterial default: Standard default: Standard -alias -alias

Stores the material. Note: MultiSubMaterial is obsolete and is visible only for backward compatibility. Each of the arrays contains numsubs elements. The materialList array stores the Material for each sub-material, the mapEnabled array stores whether that sub-material is enabled, and the names array stores the sub-material slot name (not the sub-material name). MultiMaterials have sub-materials arranged in a table, so MAXScript also allows you to access these sub-materials using the array indexing accessor:
mm = multimaterial numsubs:3 mm[1] = $foo.material $baz.material = mm[2]

If the numsubs named parameter is not specified, the default numsubs value is 10. The number of sub-materials can be changed after material creation by changing the numsubs property value. The number of sub-materials can also be changed by setting the count property for the materialList, mapEnabled, or names property to the desired number.
material1 is an alias for materialList[1].

See also
Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1212

Chapter 11

3ds max Objects

NoMaterial : Material
Assigning this material is equivalent to setting the material to None in the Material Editor. Setting a material to the value undefined is also equivalent to setting the material to None in the Material Editor. For example, if a box had a Top_Bottom material assigned, the following would set the Top sub-material to None:
$box01.material.TopMaterial=noMaterial()

or
$box01.material.TopMaterial=undefined

Constructor:
noMaterial ...

Properties: There are no additional properties for NoMaterial.

See also
Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

RayTraceMaterial : Material
Constructor:
rayTraceMaterial ...

Properties:
<RaytraceMaterial>.Ambient_Color_On <RaytraceMaterial>.Ambient animatable <RaytraceMaterial>.Ambient_Amount percentage Float Color default: 0.0 default: (color 0 0 0) --

If Ambient_Color_On = 0, Ambient_Amount is used, otherwise Ambient is used

Sets the degree to which the material absorbs ambient light.

Float default: 0.0 -- animatable;

The amount that the ambient map affects the material expressed as a percentage of full intensity.
<RaytraceMaterial>.Luminosity_Color_On Float default: 0.0

If Luminosity_Color_On = 0, Self_Illum__Amount is used, otherwise Luminosity is used

RayTraceMaterial : Material

1213

<RaytraceMaterial>.Luminosity animatable <RaytraceMaterial>.Self_Illum_Amount percentage

Color

default: (color 0 0 0) --

The self-illumination color of the material.

Float default: 0.0 -- animatable;

The amount that the self-illumination map affects the material expressed as a percentage of full intensity.
<RaytraceMaterial>.Diffuse 127.5) -- animatable Color default: (color 127.5 127.5

Sets the diffuse color.

<RaytraceMaterial>.Transparency_Color_On Float default: 0.0

If Transparency_Color_On = 0, Transparency_Amount is used, otherwise Transparecy is used

<RaytraceMaterial>.Transparecy animatable Color default: (color 0 0 0) --

The filter color of the material.

<RaytraceMaterial>.Transparency_Amount percentage Float default: 0.0 -- animatable;

The amount that the transparency map affects the material expressed as a percentage of full intensity.
<RaytraceMaterial>.Reflect_Color_On <RaytraceMaterial>.Reflect animatable Float Color default: 0.0 default: (color 0 0 0) --

If Reflect_Color_On = 0, Reflect_Amount is used, otherwise Reflect is used

The specular reflection color.

<RaytraceMaterial>.Reflect_amount percentage Float default: 0.0 -- animatable;

The amount that the reflection map affects the material expressed as a percentage of full intensity.
<RaytraceMaterial>.Index_of_Refraction percentage Float default: 100.0 -- animatable;

The index of refraction (IOR) controls how severely the material refracts transmitted light. At 1.0, the IOR of air, the object behind the transparent object does not distort. At 1.5, the object behind distorts greatly, like a glass marble. At an IOR slightly less than 1.0, the object reflects along its edges, like a bubble seen from under water.
<RaytraceMaterial>.Spec__Color - animatable Color default: (color 255 255 255) -

Sets the color of specular highlights.

<RaytraceMaterial>.Specular_Level percentage Float default: 50.0 -- animatable;

Sets the intensity of specular highlights. Set the Specular Level to a very high value for very strong, tight highlights.

1214

Chapter 11

3ds max Objects

<RaytraceMaterial>.Glossiness percentage

Float

default: 40.0

-- animatable;

Affects the size of the specular highlight. As you increase the value, the highlight gets smaller and the material appears shinier.
<RaytraceMaterial>.Soften <RaytraceMaterial>.Extra_Lighting animatable <RaytraceMaterial>.translucency animatable <RaytraceMaterial>.Fluorescence animatable Float Color default: 0.1 -- animatable

Softens the effect of highlights formed by glancing light.

default: (color 0 0 0) --

Adds light to the surface of objects with the Raytrace material.

Color default: (color 0 0 0) --

Creates a translucent effect. The Translucency color is a non-directional diffuse reflection.

Color default: (color 0 0 0) --

Creates an effect similar to black light on a black light poster. The light from a black light is largely ultraviolet, outside the visible spectrum. Under black light, fluorescent paints flare or glow. The fluorescence in Raytrace material takes whatever light it sees in the scene, applies the Bias to it, and then, regardless of the color of the lights in the scene, illuminates the fluorescent material as if it were lit by white light.
<RaytraceMaterial>.Fluorescence_Bias percentage Float default: 70.0 -- animatable;

At 0.5, The Bias makes Fluorescence behave just like diffuse coloring. Bias values higher than 0.5 increase the fluorescent effect, making the object brighter than other objects in the scene. Bias values lower than 0.5 make the object dimmer than other objects in the scene.
<RaytraceMaterial>.Wire_Size percentage <RaytraceMaterial>.Color_Density_Enable Float default: 100.0 -- animatable;

Sets the size of the wire in wireframe mode.

Boolean Float Float default: false -- animatable default: 0.0 default: 25.0 default: 1.0 -- animatable -- animatable -- animatable

Turns on/off the color density controls.

<RaytraceMaterial>.Color_Density_Start <RaytraceMaterial>.Color_Density_End

The position in the object where the density color begins to appear. The position in the object where the density color reaches its full Amount value.
<RaytraceMaterial>.Color_Density_Amount Float

The amount of density color. It can range from 0 to 1.0. Reducing this value reduces the density color effect.
<RaytraceMaterial>.Color_Density_Color - animatable Color default: (color 255 255 255) -

Sets a transmission color based on thickness. While filter (Transparency) color tints objects behind the transparent object, the density color gives the appearance of color within the object itself, like tinted glass.

RayTraceMaterial : Material

1215

<RaytraceMaterial>.Fog_Enable <RaytraceMaterial>.Fog_Start <RaytraceMaterial>.Fog_End <RaytraceMaterial>.Fog_Amount

Boolean Float Float Float

default: false -- animatable default: 0.0 default: 25.0 default: 1.0 -- animatable -- animatable -- animatable

Turn on/off the use of density fog in the raytrace material. The position in the object where the density fog begins to appear. The position in the object where the density fog reaches its full Amount value. Controls the amount of density fog. It can range from 0 to 1.0. Reducing this value reduces the density fog effect and makes the fog translucent.
<RaytraceMaterial>.Fog_Color - animatable Color default: (color 255 255 255) -

The color of the density fog.

<RaytraceMaterial>.Reflection_Type Integer default: 0 -- animatable

Set the type of reflection: Default (Reflections are layered with the diffuse color) Additive (Refelections are added to the diffuse color)
<RaytraceMaterial>.Reflection_Gain Float default: 0.5 -- animatable

Controls reflection brightness. The lower the gain value, the brighter the reflection. At a gain of 1.0, no reflection is visible.
<RaytraceMaterial>.Enable_Raytraced_Reflections Boolean Boolean Integer default: false default: true default: 0 --

Turns raytracing of reflective objects on or off.

<RaytraceMaterial>.Enable_Raytraced_Refractions

Turns raytracing of transparent objects on or off.

<RaytraceMaterial>.Reflection_Falloff_Mode animatable

When on, dims reflections to black at distance specified by Reflection_Falloff_End_Distance: Off (Turns off attenuation) Linear Inverse Square (Inverse square is the actual attenuation rate for light in the real world.) Exponential
<RaytraceMaterial>.Reflection_Falloff_End_Distance animatable Float default: 100.0 --

The distance in world units where the reflected ray is fully attenuated.

1216

Chapter 11

3ds max Objects

<RaytraceMaterial>.Refraction_Falloff_Mode animatable

Integer

default: 0

--

Sets the falloff mode for refraction in the raytrace material: Off (Turns off attenuation) Linear Inverse Square (Inverse square is the actual attenuation rate for light in the real world.) Exponential
<RaytraceMaterial>.Refraction_Falloff_End_Distance animatable <RaytraceMaterial>.Bump_Map_Effect Float Float default: 100.0 --

The distance in world units where the refracted ray is fully attenuated.
default: 1.0 Boolean -- animatable default:

Adjusts the effect of bump maps on raytraced reflections and refractions.

<RaytraceMaterial>.Override_Global_Antialiasing_Settings false -- animatable

If Override_Global_Antialiasing_Settings = false, Global Antialiasing Settings are used. If true, the antialiaser is determined by Adaptive_Antialiasing_On.
<RaytraceMaterial>.Adaptive_Antialiasing_On - animatable Boolean default: false -

If Adaptive_Antialiasing_On = true, the Multiresolution Adaptive Antialiaser is used; otherwise the Fast Adaptive Antialiaser is used. This property only has an effect if Override_Global_Antialiasing_Settings = true. The following properties are associated with the Options dialog
<RaytraceMaterial>.Options___Raytracer_Enable - animatable Boolean default: true -

Turns the raytracer on or off.

<RaytraceMaterial>.Options___Antialiasing_Enable - animatable Boolean default: true -

Turns antialiasing on or off.

<RaytraceMaterial>.Options___Self_Reflect_Refract - animatable Boolean default: true -

Turns self reflection/refraction on or off.

<RaytraceMaterial>.Options___Raytrace_Atmospherics - animatable Boolean default: true -

Turns the raytracing of atmospheric effects on or off. Atmospheric effects include combustion, fog, volume light, and so on.
<RaytraceMaterial>.Options___Reflect_Refract_Material_ID_s true -- animatable <RaytraceMaterial>.Options___Raytrace_Objects_in_Glass true -- animatable Boolean default:

When on, the material reflects effects assigned to material IDs in the renderers G-Buffer.
Boolean default:

Turns the raytracing of objects inside raytraced objects on or off.

RayTraceMaterial : Material

1217

<RaytraceMaterial>.Options___Raytrace_Atmospherics_in_Glass true -- animatable <RaytraceMaterial>.Options___Color_Density___Fog_Enable true -- animatable

Boolean

default:

Turns the raytracing of atmospherics inside raytraced objects on or off.

Boolean default:

Turns the color density and fog features on or off. The following properties are associated with the Antialiaser configuration dialogs.
<RaytraceMaterial>.Local_Threshold 0.1 -- animatable Float default:

The sensitivity of the adaption algorithm. This value can range from 0 to 1, where 0 always casts the maximum number of rays and 1 always casts only the minimum number of rays.
<RaytraceMaterial>.Local_Min__Rays 4 -- animatable Integer default:

The minimum number of rays that the algorithm casts.

<RaytraceMaterial>.Local_Max__Rays 32 -- animatable Integer default:

The maximum number of rays the algorithm casts.

<RaytraceMaterial>.Local_Blur_Offset 0.0 -- animatable Float default:

The sharpness or blurriness of reflections or refractions without regard to distance. This value is specified in pixels.
<RaytraceMaterial>.Local_Blur_Aspect 1.0 -- animatable Float default:

Changes the shape of the blur by changing the aspect ratio.

<RaytraceMaterial>.Local_Defocus 0.0 -- animatable Float default:

Blurs based on distance. Objects near the surface are not blurred, but objects farther away are blurred. The rays cast are spread as they leave the surface of the raytrace map object.
<RaytraceMaterial>.Local_Defocus_Aspect 1.0 -- animatable Float default:

Changes the shape of the defocusing by changing the aspect ratio. The following properties are associated with the Maps rollout.
<RaytraceMaterial>.ambientMap undefined TextureMap default:

The map assigned to the ambient map channel.

<RaytraceMaterial>.ambientMapAmount 100.0 Float default:

The relative strength of the ambient map channel.

<RaytraceMaterial>.ambientMapEnable false Boolean default:

Turn on/off use of the ambient map channel.

<RaytraceMaterial>.bumpMap undefined TextureMap default:

The map assigned to the bump map channel.

1218

Chapter 11

3ds max Objects

<RaytraceMaterial>.bumpMapAmount 100.0

Float

default:

The relative strength of the bump map channel.

<RaytraceMaterial>.bumpMapEnable false Boolean default:

Turn on/off use of the bump map channel.

<RaytraceMaterial>.diffuseMap undefined TextureMap default:

The map assigned to the diffuse map channel.

<RaytraceMaterial>.diffuseMapAmount 100.0 Float default:

The relative strength of the diffuse map channel.

<RaytraceMaterial>.diffuseMapEnable false Boolean default:

Turn on/off use of the diffuse map channel.

<RaytraceMaterial>.displacementMap undefined TextureMap default:

The map assigned to the displacement map channel.

<RaytraceMaterial>.displacementMapAmount 100.0 Float default:

The relative strength of the displacement map channel.

<RaytraceMaterial>.displacementMapEnable false Boolean default:

Turn on/off use of the displacement map channel.

<RaytraceMaterial>.reflectionMap undefined TextureMap default:

The map assigned to the reflection map channel.

<RaytraceMaterial>.reflectionMapAmount 100.0 Float default:

The relative strength of the reflection map channel.

<RaytraceMaterial>.reflectionMapEnable false Boolean default:

Turn on/off use of the reflection map channel.

<RaytraceMaterial>.refractionMap undefined TextureMap default:

The map assigned to the refraction map channel.

<RaytraceMaterial>.refractionMapAmount 100.0 Float default:

The relative strength of the refraction map channel.

<RaytraceMaterial>.refractionMapEnable false Boolean default:

Turn on/off use of the refraction map channel.

RayTraceMaterial : Material

1219

<RaytraceMaterial>.glossinessMap undefined

TextureMap

default:

The map assigned to the glossiness map channel.

<RaytraceMaterial>. glossinessMapAmount <RaytraceMaterial>. glossinessMapEnable <RaytraceMaterial>.specularLevelMap lt: undefined Float default: 100.0

The relative strength of the glossiness map channel.

Boolean default: false TextureMap defau

Turn on/off use of the glossiness map channel.

The map assigned to the specularLevel map channel.

<RaytraceMaterial>.specularLevelMapAmount lt: 100.0 Float defau

The relative strength of the specularLevel map channel.

<RaytraceMaterial>.specularLevelMapEnable lt: false Boolean defau

Turn on/off use of the specularLevel map channel.

<RaytraceMaterial>.luminosityMap undefined TextureMap default:

The map assigned to the luminosity map channel.

<RaytraceMaterial>.luminosityMapAmount 100.0 Float default:

The relative strength of the luminosity map channel.

<RaytraceMaterial>.luminosityMapEnable false Boolean default:

Turn on/off use of the luminosity map channel.

<RaytraceMaterial>.transparencyMap t: undefined TextureMap defaul

The map assigned to the transparency map channel.

<RaytraceMaterial>.transparencyMapAmount t: 100.0 Float defaul

The relative strength of the transparency map channel.

<RaytraceMaterial>.transparencyMapEnable t: false Boolean defaul

Turn on/off use of the transparency map channel.

<RaytraceMaterial>.environmentMap : undefined TextureMap default

The map assigned to the environment map channel.

<RaytraceMaterial>.environmentMapAmount : 100.0 Float default

The relative strength of the environment map channel.

1220

Chapter 11

3ds max Objects

<RaytraceMaterial>.environmentMapEnable : false

Boolean

default

Turn on/off use of the environment map channel.

<RaytraceMaterial>.transEnvMap undefined TextureMap default:

The map assigned to the transEnv map channel.

<RaytraceMaterial>.transEnvMapAmount 100.0 Float default:

The relative strength of the transEnv map channel.

<RaytraceMaterial>.transEnvMapEnable false Boolean default:

Turn on/off use of the transEnv map channel.

<RaytraceMaterial>.iorMap undefined TextureMap default:

The map assigned to the ior map channel.

<RaytraceMaterial>.iorMapAmount Float Boolean default: 100.0 default: false TextureMap defaul

The relative strength of the ior map channel.

<RaytraceMaterial>.iorMapEnable

Turn on/off use of the ior map channel.

<RaytraceMaterial>.translucencyMap t: undefined

The map assigned to the translucency map channel.

<RaytraceMaterial>.translucencyMapAmount t: 100.0 Float defaul

The relative strength of the translucency map channel.

<RaytraceMaterial>.translucencyMapEnable t: false Boolean defaul

Turn on/off use of the translucency map channel.

<RaytraceMaterial>.extraLightingMap lt: undefined TextureMap defau

The map assigned to the extraLighting map channel.

<RaytraceMaterial>.extraLightingMapAmount lt: 100.0 Float defau

The relative strength of the extraLighting map channel.

<RaytraceMaterial>.extraLightingMapEnable lt: false Boolean defau

Turn on/off use of the extraLighting map channel.

<RaytraceMaterial>.flourescenceMap t: undefined TextureMap defaul

The map assigned to the flourescence map channel.

<RaytraceMaterial>.flourescenceMapAmount t: 100.0 Float defaul

The relative strength of the flourescence map channel.

RayTraceMaterial : Material

1221

<RaytraceMaterial>.flourescenceMapEnable t: false

Boolean

defaul

Turn on/off use of the flourescence map channel.

<RaytraceMaterial>.colorDensityMap t: undefined TextureMap defaul

The map assigned to the colorDensity map channel.

<RaytraceMaterial>.colorDensityMapAmount t: 100.0 Float defaul

The relative strength of the colorDensity map channel.

<RaytraceMaterial>.colorDensityMapEnable t: false Boolean defaul

Turn on/off use of the colorDensity map channel.

<RaytraceMaterial>.fogColorMap undefined TextureMap default:

The map assigned to the fogColor map channel.

<RaytraceMaterial>.fogColorMapAmount 100.0 Float default:

The relative strength of the fogColor map channel.

<RaytraceMaterial>.fogColorMapEnable false Boolean default:

Turn on/off use of the fogColor map channel.

<RaytraceMaterial>.diffusionMap undefined TextureMap default:

The map assigned to the diffusion map channel.

<RaytraceMaterial>.diffusionMapAmount 100.0 Float default:

The relative strength of the diffusion map channel.

<RaytraceMaterial>.diffusionMapEnable false Boolean default:

Turn on/off use of the diffusion map channel.

<RaytraceMaterial>.specularMap undefined TextureMap default:

The map assigned to the specular color map channel.

<RaytraceMaterial>.specularMapAmount 100.0 Float default:

The relative strength of the specular color map channel.

<RaytraceMaterial>.specularMapEnable false Boolean default:

Turn on/off use of the specular color map channel.

1222

Chapter 11

3ds max Objects

The following properties are associated with the Dynamics Properties rollout. These properties are not present in 3D Studio VIZ.
<RaytraceMaterial>.Bounce_Coefficient 1.0 -- animatable Float default:

Sets how far an object bounces after hitting a surface. The higher the value, the greater the bounce. A value of 1 represents a perfectly elastic collision, or a bounce in which no kinetic energy is lost.
<RaytraceMaterial>.Static_Friction 0.0 -- animatable Float default:

Sets how difficult it is for the object to start moving along a surface. The higher this value, the more difficult.
<RaytraceMaterial>.Sliding_Friction 0.0 -- animatable Float default:

Sets how difficult it is for the object to keep moving over a surface. The higher this value, the more difficult for the object to keep moving. The following properties do not correspond to any user-interface items, but appear to be used by the raytracer. These properties appear to be similar to the corresponding properties for the Raytrace TextureMap (p. 1271).
<RaytraceMaterial>.Attenuation_Start Float Float Integer default: 0.0 default: 2.0 default: 0

The distance in world units where attenuation begins.

<RaytraceMaterial>.Attenuation_Exponent

The distance in world units where the ray is fully attenuated.

<RaytraceMaterial>.Attenuation_Color_Mode

This affects the behavior of light rays as they attenuate out: Background (As the ray attenuates out, returns the background (either the scenes background or the background specified locally in the Raytracer Parameters rollout) rather than the actual color of what the reflected/refracted ray sees.) Use Attenuation_Color
<RaytraceMaterial>.Attenuation_Color (color 0 0 0) Color default:

The color used for attenuation.

<RaytraceMaterial>.Attenuation_Near Float default: 1.0

The strength of the reflected/refracted ray at the start range distance. This is a normalized percentage that can range from 0.0 to 1.0.
<RaytraceMaterial>.Attenuation_Control_1 Float Float Float default: 0.6666 default: 0.3333 default: 0.0

Controls the shape of the curve near the curve start.

<RaytraceMaterial>.Attenuation_Control_2

Controls the shape of the curve near the curve end.

<RaytraceMaterial>.Attenuation_Far

Sets the strength of the reflected/refracted ray at the end range distance. This is a normalized percentage that can range from 0.0 to 1.0.

RayTraceMaterial : Material

1223

<RaytraceMaterial>.Blur_Map false

Boolean

default:

When on, the software uses a map to apply the Blur Offset value. That is, where the map is white, blur offset is fully applied, and where it is black, it is ignored. For example, if the map is a Checker map, blur offset is applied only in every other square. Values between black and white cause less blur.
<RaytraceMaterial>.Defocus_Map false Boolean default:

When on, uses a map to apply the Defocus value. That is, where the map is white, Defocus is fully applied, and where it is black, it is ignored. For example, if the map is a Checker map, Defocus is applied only in every other square. Values between black and white cause less defocusing.
<RaytraceMaterial>.Enable_Reflection_Falloff false Boolean default:

Turns on/off falloff of reflection.

<RaytraceMaterial>.Reflection_Falloff_Distance Float Boolean Float default: 0.0 default: false default: 0.0

The distance until the reflections are fully attenuated.

<RaytraceMaterial>.Enable_Refraction_Falloff

Turns on/off falloff of refraction.

<RaytraceMaterial>.Refraction_Falloff_Distance

The distance until the refractions are fully attenuated. Note: The following user-interface properties not exposed to MAXScript in 3ds max 4: Shading, 2-Sided, Wire, Face Map, and SuperSample

See also
Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1224

Chapter 11

3ds max Objects

StandardMaterial : Material
Constructor:
standardMaterial ... standard ...

Properties: The properties of a standard material vary based on the shader type. The following properties are applicable to all shader types:
<Standard>.shaderType Shader_Type Integer default: 1 -- alias:

Sets the shader type: Anisotropic Blinn Metal Multi-Layer Oren-Nayar-Blinn Phong Strauss
<Standard>.shaderByName Shader_Name String default: Blinn -- alias:

Sets the type of shader with a string, rather than a number. Enter anisotropic, blinn, metal, multi-layer, oren-nayar-blinn, phong, or strauss. Note: The .shaderType and .shaderByName are linked and will automatically change each others values.
<Standard>.wire <Standard>.twoSided Two_sided <Standard>.faceMap Face_Map Boolean Boolean default: false default: false -- alias:

When on, the material will be rendered in wireframe mode.

When on, the material will be applied to both sides of the selected faces.
Boolean default: false -- alias:

Applies the material to the faces of the geometry. If the material is a mapped material, it requires no mapping coordinates. The map is automatically applied to each facet of the object.
<Standard>.faceted <Standard>.adTextureLock Ambient_Diffuse_Texture_Lock Boolean Boolean default: false default: false -- alias:

Renders each face of a surface as if it were flat.

When on, ambient and diffuse texture maps will be locked.

StandardMaterial : Material

1225

<Standard>.adLock Ambient_Diffuse_Lock <Standard>.opacityType Opacity_Type

Boolean

default: false

-- alias:

When on, ambient and diffuse colors will be locked.

Integer default: 0 -- alias:

Sets the type of opacity: Filter Subtractive Additive

<Standard>.opacity percentage Float default: 100.0 -- animatable,

Sets the opacity/transparency of the material as a percentage.

<Standard>.filterColor Color 127.5) -- animatable, alias: Filter_Color <Standard>.opacityFallOffType Falloff_Type Integer default: (color 127.5 127.5

The color transmitted through transparent or semi-transparent materials such as glass.

default: 0, -- alias:

Sets the fallof type: In (Increases transparency towards the inside of the object, as in a glass bottle. ) Out (Increases transparency towards the outside of the object, as in a cloud of smoke.)
<Standard>.opacityFallOff percentage, alias: Falloff <Standard>.ior alias: Index_of_Refraction Float default: 0.0 -- animatable,

Specifies the amount of transparency at the outside or inside extreme.

Float default: 1.5 -- animatable,

Sets the index of refraction (IOR) used by refraction maps and raytracing. The IOR controls how severely the material refracts transmitted light. Left at 1.0, the IOR of air, the object behind the transparent object does not distort. At 1.5 the object behind distorts greatly, like a glass marble. At an IOR slightly less than 1.0, the object reflects along its edges, like a bubble seen from under water.
<Standard>.wireSize alias: Wire_Size <Standard>.wireUnits Wire_Units Float default: 1.0 -- animatable,

Sets the size of the wire in wireframe mode.

Integer default: 0 -- alias:

Sets the unites to use with the .wiresize value: Pixels Units
<Standard>.applyReflectionDimming Apply_Reflection_Dimming Boolean default: false -- alias:

Turn on to use reflection dimming. When off, the reflection-mapped material is not affected by the presence or absence of direct light.

1226

Chapter 11

3ds max Objects

<Standard>.dimLevel alias: Dim_Level

Float

default: 0.0

-- animatable,

The amount of dimming that takes place in shadow. At 0.0, the reflection map is completely dark in shadow. At 0.5, the reflection map is half dimmed. At 1.0, the reflection map is not dimmed and the material appears as if Apply were turned off.
<Standard>.reflectionLevel alias: Reflection_Level Float default: 3.0 -- animatable,

Affects the intensity of the reflection that is not in shadow. The Reflection Level value multiplies the illumination level of the lit area of the reflection, to compensate for dimming.
<Standard>.sampler Pixel_Sampler Integer default: 3 -- alias:

Sets the sampler type: Adaptive Halton (Spaces samples along both X and Y axes according to a scattered, quasi random pattern. Depending on Quality, the number of samples can range from 4 to 40. ) Adaptive Uniform (Spaces samples regularly, from a minimum quality of 4 samples to a maximum of 36. The pattern is not square, but skewed slightly to improve accuracy in the vertical and horizontal axes. ) Hammersley (Spaces samples regularly along the X axis, but along the Y axis it spaces them according to a scattered, quasi random pattern. Depending on Quality, the number of samples can range from 4 to 40.)
Max 2.5 Star (The sample at the center of the pixel is averaged with 4 samples surrounding it. The pattern is like the fives on dice.) <Standard>.samplerByName String default: Max 2.5 Star -alias: Sampler_Name

Sets the sampler type by name. Enter Adaptive Halton, Adaptive Uniform, Hammersley, or Max 2.5 Star.
<Standard>.samplerEnable alias: Sampler_Enable <standard>.subSampleTextureOn SubSample_Textures Boolean default: false -- animatable,

When on, applies supersampling to the material.

Boolean default: true -- alias:

When on, the maps applied to the material are supersampled as well. When off, the supersampler uses pixel averages for maps.
<Standard>.samplerQuality alias: Sampler_Enable Float default: 0.5 -- animatable,

Adjusts the quality of supersampling by controlling the number of samples used for each pixel.
<Standard>.samplerAdaptOn Adaptive_On Boolean default: true -- alias:

When on, these methods take fewer samples than the Quality specifies unless samples show a change in color greater than the Threshold value. In that case, they take all the

StandardMaterial : Material

1227

samples specified by the Quality. Turning on Adaptive On can reduce the amount of time required to supersample.
<Standard>.samplerAdaptThreshold Adaptive_Threshold Float default: 0.1 -- alias:

Controls the Adaptive methods. A change in color greater than the Threshold value causes the adaptive methods to take the full number of samples specified by the Quality. If the color does not change as much, the adaptive method takes fewer samples and does not require as much processing time.
<Standard>.samplerAdvancedOptions Advanced_Options Boolean default: true -- alias:

The samplerAdvancedOptions property is defined as a property, but is not used by the Standard material.
<standard>.UserParam0 Optional_Param0 <standard>.UserParam1 Optional_Param1 Float Float default: 0.0 default: 0.0 -- alias: -- alias:

The UserParam0 and UserParam1 properties are defined as properties, but are not used by the Standard material.
<Standard>.maps ArrayParameter undefined, ... , undefined, undefined) <Standard>.mapEnables ArrayParameter false, false) -- alias: Map_Enables <Standard>.mapAmounts ArrayParameter 100.0, 100.0) -- animatable, alias: Map_Amounts default: #(undefined, default: #(false, false, ... , default: #(100.0, 100.0, ... ,

The three map arrays each have 24 elements and store data related to the materials maps. The maps array stores the textureMap for each channel, the mapEnables array stores whether the that map channel is enabled, and the mapAmounts array stores the amount value for each channel. The meaning of each map channel depends on the shaderType value. Table Map Channels for Standard Material Shaders (p. 1232) shows the meaning of each map channel for each shader. For example, for the Blinn shader type element 5 of the map arrays correspond to the Glossiness map channel. The names in this table also reflect property aliases that have been defined for easier access to the map channels. Again for the Blinn shader type, array element 4, the property aliases for the 3 map arrays are: GlossinessMap (maps[5]), GlossinessMapEnable (mapEnables[5]), and GlossinessMapAmount (mapAmounts[5]). A textureMap needs to be assigned to a maps array element (or alias) before the corresponding mapAmounts property (or alias) can be animated. The following properties are associated with the Dynamics Properties rollout. These properties are not present in 3D Studio VIZ.
<Standard>.bounce alias: Bounce_Coefficient Float default: 1.0 -- animatable,

Sets how far an object bounces after hitting a surface. The higher the value, the greater the bounce. A value of 1 represents a perfectly elastic collision, or a bounce in which no kinetic energy is lost.

1228

Chapter 11

3ds max Objects

<Standard>.staticFriction alias: Static_Friction

Float

default: 0.0

-- animatable,

Sets how difficult it is for the object to start moving along a surface. The higher this value, the more difficult.
<Standard>.slidingFriction alias: Sliding_Friction Float default: 0.0 -- animatable,

Sets how difficult it is for the object to keep moving over a surface. The higher this value, the more difficult for the object to keep moving. Shader Types: Phong; Metal; Blinn; Oren-Nayar-Blinn; Anisotropic Unless otherwise noted, the following additional properties are applicable to the above shader types:
<Standard>.ambient Color animatable, alias: Ambient_Color <Standard>.diffuse Color animatable, alias: Diffuse_Color <Standard>.specular Color animatable, alias: Specular_Color default: (color 25.5 25.5 25.5) --

Controls the ambient color. The ambient color is the color in direct light.
default: (color 127.5 127.5 127.5) --

Controls the diffuse color. The diffuse color is the color in direct light.
default: (color 229.5 229.5 229.5) --

Controls the specular color. The specular color is the color of the highlight on a shiny object.
<Standard>.dsLock Diffuse_Specular_Lock <Standard>.useSelfIllumColor Use_Self_Illumination Boolean default: false -- alias:

When on, the diffuse and specular colors are linked together.
Boolean default: false -- alias:

When on, the material uses a special self-illumination color (.selfIllumColor). When off, the material uses the diffuse color for self-illumination.
<Standard>.selfIllumAmount alias: Self_Illumination <Standard>.selfIllumColor alias: Self_Illum_Color <Standard>.specularLevel alias: Specular_Level Float default: 0.0 -- animatable, percentage,

Sets the amount of self-illumination.

Color default: (color 0 0 0) -- animatable,

Sets a separate color to use for self-illumination.

Float default: 5.0 -- animatable, percentage,

Affects the intensity of the specular highlight. As you increase the value, the highlight grows brighter.
<Standard>.glossiness Float default: 25.0 -- animatable, percentage

Affects the size of the specular highlight. As you increase the value, the highlight gets smaller and the material appears shinier.

StandardMaterial : Material

1229

<Standard>.soften Soften_Level

Float

default: 0.1

-- animatable, alias:

Softens the effect of specular highlights, especially those formed by glancing light. When Specular Level is high and Glossiness is low, you can get harsh backlights on surfaces. Increase the value of Soften to mitigate this effect. At 0 there is no softening. At 1.0, the maximum amount of softening is applied. Note: Soften is not applicable to the Anisotropic shader The following additional properties are applicable to the Oren-Nayar-Blinn shader:
<Standard>.diffuseLevel alias: Diffuse_Level Float default: 100.0 -- animatable, percentage,

Controls the brightness of the materials diffuse component. Increasing this value increases diffuse brightness, and decreasing it reduces diffuse brightness without affecting the specular highlight.
<Standard>.diffuseRoughness alias: Diff_Roughness Float default: 50.0 -- animatable, percentage,

Controls how quickly the diffuse component blends into the ambient component. As you increase roughness, the matte appearance of the material increases. It also grows darker and appears more flat. The following additional properties are applicable to the Anisotropic shader:
<Standard>.diffuseLevel alias: Diffuse_Level Float default: 100.0 -- animatable, percentage,

Controls the brightness of the materials diffuse component. Increasing this value increases diffuse brightness, and decreasing it reduces diffuse brightness without affecting the specular highlight.
<Standard>.anisotropy Float default: 50.0 -- animatable, percentage

Controls the anisotropy, or shape, of the highlight. At 0, the highlight is round. At 100, the highlight is extremely narrow.
<Standard>.orientation <Standard>.unused Float Integer default: 0.0 default: 1 -- animatable, percentage

Changes the orientation of the highlight. the unused property is defined but not used by the shader Shader Type: Multi-Layer
<Standard>.ambient Color animatable, alias: Ambient_Color <Standard>.diffuse Color animatable, alias: Diffuse_Color <Standard>.useSelfIllumColor Use_Self_Illumination Boolean default: (color 25.5 25.5 25.5) --

Controls the ambient color. The ambient color is the color not in direct light.
default: (color 127.5 127.5 127.5) --

Controls the diffuse color. The diffuse color is the color in direct light.
default: false -- alias:

When on, the material uses a special self-illumination color (.selfIllumColor). When off, the material uses the diffuse color for self-illumination.

1230

Chapter 11

3ds max Objects

<Standard>.selfIllumAmount alias: Self_Illumination

Float

default: 0.0

-- animatable, percentage,

Sets the amount of self-illumination. As you increase self-illumination, the selfillumination color takes over from the ambient color. At a setting of 100, the material shows no shaded areas, although it can show specular highlights.
<Standard>.selfIllumColor alias: Self_Illum_Color <Standard>.diffuseLevel alias: Diffuse_Level Color default: (color 0 0 0) -- animatable,

Sets an alternate color to use for self-illumination.

Float default: 100.0 -- animatable, percentage,

Controls the brightness of the materials diffuse component. Increasing this value increases diffuse brightness, and decreasing it reduces diffuse brightness without affecting the specular highlight.
<Standard>.diffuseRoughness alias: Diff_Roughness Float default: 0.0 -- animatable, percentage,

Controls how quickly the diffuse component blends into the ambient component. As you increase roughness, the matte appearance of the material increases. It also grows darker and appears more flat.
<Standard>.specular animatable, alias: Color_1 Color default: (color 229.5 229.5 229.5) --

Controls the specular color of the first colors highlight. The specular color is the color of the highlight on a shiny surface.
<Standard>.specularLevel alias: Level_1 Float default: 5.0 -- animatable, percentage,

Affects the intensity of the first colors specular highlight. As you increase the value, the highlight grows brighter.
<Standard>.glossiness alias: Glossiness_1 Float default: 25.0 -- animatable, percentage,

Affects the size of the first colors specular highlight. As you increase the value, the highlight gets smaller and the material appears shinier.
<Standard>.anisotropy Anisotropy_1 Float default: 0.0 -- animatable, alias:

Controls the anisotropy, or shape, of the first colors highlight. At 0, the highlight is round. At 100, the highlight is extremely narrow.
<Standard>.orientation <Standard>.specular2 animatable, alias: Color_2 Float Color default: 0.0 -- animatable, percentage

Changes the orientation of the first colors highlight.

default: (color 229.5 229.5 229.5) --

Affects the intensity of the second colors specular highlight. As you increase the value, the highlight grows brighter.
<Standard>.specularLevel2 alias: Level_2 Float default: 0.0 -- animatable, percentage,

Affects the intensity of the second colors specular highlight. As you increase the value, the highlight grows brighter.

StandardMaterial : Material

1231

<Standard>.glossiness2 alias: Glossiness_2

Float

default: 25.0

-- animatable, percentage,

Affects the size of the second colors specular highlight. As you increase the value, the highlight gets smaller and the material appears shinier.
<Standard>.anisotropy2 Anisotropy_2 Float default: 0.0 -- animatable, alias:

Controls the anisotropy, or shape, of the second colors highlight. At 0, the highlight is round. At 100, the highlight is extremely narrow.
<Standard>.orientation2 Float default: 0.0 -- animatable, percentage

Changes the orientation of the second colors highlight. Shader Type: Strauss
<Standard>.diffuse Color animatable, alias: Diffuse_Color default: (color 127.5 127.5 127.5) --

Controls the color of the material. This corresponds to the diffuse color you specify for other kinds of shaders. With the Strauss shader, you control only this color. The shader calculates the ambient and specular color components.
<Standard>.glossiness Float default: 25.0 -- animatable, percentage

Affects the size and intensity of the specular highlight. As you increase the value, the highlight gets smaller and the material appears shinier.
<Standard>.metalness Float default: 0.0 -- animatable, percentage

Changes the metallic appearance of a material. Increasing the Metalness value increases the metallic appearance, with glancing as well as primary highlights. Because a metallic appearance principally depends on highlights, the Metalness value has little effect unless you also increase the Glossiness value.

See also
Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1232

Chapter 11

3ds max Objects

Map Channels for Standard Material Shaders

Anisotropic
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

Blinn
AmbientMap DiffuseMap SpecularMap DiffuseLevel Map SpecularLevel Map

Metal
AmbientMap DiffuseMap SpecularMap SpecularLevel Map GlossinessMap

Multi-Layer
AmbientMap DiffuseMap SpecularMap SpecularLevel Map GlossinessMap SelfIllumMap OpacityMap FilterMap BumpMap ReflectionMap RefractionMap Displacement Map

Oren-NayarBlinn
AmbientMap DiffuseMap

Phong
AmbientMap DiffuseMap

Strauss
AmbientMap DiffuseMap SpecularMap SpecularLevel Map GlossinessMap SelfIllumMap OpacityMap FilterMap DiffuseMap GlossinessMap MetalnessMap OpacityMap FilterMap BumpMap ReflectionMap RefractionMap Displacement Map

DiffuseLevelMap SpecularMap Diffuse RoughnessMap SpecularMap SpecularLevel Map GlossinessMap AnisotropyMap GlossinessMap SpecularLevel Map SelfIllumMap OpacityMap FilterMap

Glossiness Map SelfIllumMap Anisotropy Map OpacityMap

OrientationMap FilterMap SelfIllumMap OpacityMap FilterMap BumpMap ReflectionMap RefractionMap Displacement Map BumpMap ReflectionMap RefractionMap Displacement Map

OrientationMap DiffuseLevelMap BumpMap specularMap2 SpecularLevel Map2 Diffuse RoughnessMap BumpMap ReflectionMap RefractionMap Displacement Map

GlossinessMap2 ReflectionMap AnisotropyMap2 RefractionMap Orientation Map2 SelfIllumMap OpacityMap FilterMap BumpMap ReflectionMap RefractionMap Displacement Map Displacement Map

Shellac : Material

1233

Shellac : Material
Constructor:
Shellac ...

Properties:
<Shellac>.shellacMtl1 Material Material default: Standard default: Standard -- alias: Base_Material -- alias:

The base sub-material.

<Shellac>.shellacMtl2 Shellac_Material

The shellac material.

<Shellac>.shellacColorBlend Float default: 0.0 percentage, alias: Shellac_Color_Blend -- animatable,

Controls the amount of color mixing. At 0.0, the shellac material has no effect. Increasing the Shellac Color Blend value increases the amount of shellac material color blended into the base material color. There is no upper limit on this parameter. Large values overload the shellac material colors.

See also
Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

TopBottom : Material
Constructor:
topBottom ... topBottomMat ...

Properties:
<TopBottom>.topMaterial Top______Standard Material default: Standard -- alias:

The top material.

<TopBottom>.bottomMaterial Bottom______Standard Material default: Standard -- alias:

The bottom material.

<TopBottom>.map1Enabled <TopBottom>.map2Enabled Boolean Boolean default: true default: true -- alias: Map_1_Enable -- alias: Map_2_Enable

Turns on/off the use of the top material in the topbottom material. Turns on/off the use of the bottom material in the topbottom material.

1234

Chapter 11

3ds max Objects

<TopBottom>.blend

Float

default: 0.0

-- animatable

Blends the edge between the top and bottom sub-materials. This is a percentage that can range from 0 to 100. At 0, there is a sharp line between the top and bottom sub-materials. At 100, the top and bottom sub-materials tint each other.
<TopBottom>.position Float default: 50.0 -- animatable

Determines where the division between the two materials lies on an object. This is a percentage that can range from 0 to 100. 0 is at the bottom of the object, and displays only the top material. 100 is at the top of the object, and displays only the bottom material.
<TopBottom>.coordinates Integer default: 0

Choose how the software determines the boundary between top and bottom: World (Faces point up or down according to the scenes world coordinates. When you rotate the object, the boundary between top and bottom faces remains in place.) Local (Faces point up or down according to the objects local coordinates. When you rotate the object, the material rotates with it.)

See also
Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

TextureMap : Material
The TextureMap class represents the 2D and 3D texture maps which you can assign to materials or certain object properties in 3ds max. You can create texture maps like bitmap, dent, and swirl, access various properties on them, and assign these texture maps to materials and to certain 3ds max object properties. The classes derived directly from the TextureMap class are described in the TextureMap Types (p. 1240) topic. The properties, operators, and methods that are common to all classes derived directly from the TextureMap class are described in the TextureMap Common Properties, Operators, and Methods (p. 1235) topic. TextureMaps also share a set of classes for properties that are used in several different TextureMap classes. These shared classes are described in the TextureMap Shared Classes (p. 1236) topic. The TextureMap class is derived from the Material class, and inherits the properties and methods defined for that class. These properties and methods are described in the Material Common Properties, Operators, and Methods (p. 1203) topic.

TextureMap Common Properties, Operators, and Methods

1235

TextureMap Common Properties, Operators, and Methods

Properties:
<TextureMap>.name

All the TextureMap subclasses can access the name property and specify it as a constructor parameter. Methods:
assignNewName <TextureMap>

Modifies the name of the specified texture to make it unique. The name is of the form Map #1 where the number is incremented as required to make ensure its unique.
renderMap <TextureMap> [ [ [ [ [ [ into:<bitmap> ] size:<point2> ] filename:<string> ] scale:<float> ] filter:<boolean> ] display:<boolean> ] \ \ \ \ \

Provides access the Render Map function available in the Material Editor. The function returns a Bitmap value containing a rendering of the given texture map. If you specify the optional into: argument, the function renders the map into the supplied bitmap, taking size and other attributes from the existing bitmap. If you dont, a new bitmap value is created using the size: and fileName: arguments in its creation. Default size value is [200,200]. The scale: argument is a scale factor applied to 3D TextureMaps. This is the scale of the surface in 3d space that is mapped to UV and controls how much of the texture appears in the bitmap representation. Default scale value is 1. If the filter: argument is true, the bitmap is filtered. It is quite a bit slower to rescale bitmaps with filtering on. Defaults filter value is false/off. If the display: argument is true, the resulting bitmap is displayed using the virtual frame buffer; otherwise it is not. Default display value is false/off. Example:
rm = renderMap $foo.material.diffuseMap size:[640,480] \ fileName:foodif.bmp save rm close rm

The above will render a map to a bitmap and save it as a .bmp file.

1236

Chapter 11

3ds max Objects

Associated Methods:
showTextureMap <material> <TextureMap> <boolean>

This method provides control over the visibility of textures in the shaded viewport. You specify the material containing the texture map, the texture map in that material to be controlled, and a boolean to turn the display on or off. For example:
showTextureMap $foo.material $foo.material.diffuseMap on tm = checker() mat = standardMaterial diffuseMap:tm mm = multimaterial() mm[1] = mat $box01.material = mm showTextureMap mm[1] tm on

Note that for multimaterials, you need to specify the appropriate sub-material (using [] indexing, for example).

See also
Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

TextureMap Shared Classes

The following set of material classes are shared by multiple texture maps. These shared classes correspond to the Coordinates, Noise, and Output rollouts for texture maps in Material Editor. These classes are not constructable in MAXScript, rather they are automatically constructed by the texture map. These shared material classes are the 2D and 3D texture map coordinate properties, and the Output properties: UVGenClass (p. 1237) StandardXYZGen (p. 1238) TexOutputClass (p. 1239)

UVGenClass : Material

1237

UVGenClass : Material
Properties:
<textureMap.coordinates>.mappingType Integer default: 0

mappingType = 0 - Texture; 1 - Environment If the Coordinates rollout for the textureMap is displayed in Material Editor and this propertys value is changed, the Texture/Environ radiobutton and Mapping dropdown displays are not updated to reflect the change.
<textureMap.coordinates>.mapping Integer default: varies

If mapping type is Texture mapping (mappingType = 0), the default value for this property is 0. mapping = 0 Explicit Map Channel; 1 Vertex Color Channel; 2 Planar from Object XYZ; 3 Planar from World XYZ If mapping type is Environment mapping (mappingType = 1), the default value for this property is 4. mapping = 0 - Spherical; 1 - Cylindrical; 2 - Shrink-Wrap; 3 Screen The mapping source for Texture and Environment mapping types are internally stored in separate variables, and the mapping source set for a mapping type is retained if you change the mapping source for the other mapping type.
<textureMap.coordinates>.mapChannel Integer Float Float default: 1 default: 0.0 default: 0.0 -- animatable -- animatable

The UV coordinate map channel.

<textureMap.coordinates>.U_Offset <textureMap.coordinates>.V_Offset

Offset mapping coordinates along the surfaces local U axis or V axis. That is, at 0.0 (the default), the map begins at the U or V origin. Increasing an Offset value moves the map forward along that axis, and decreasing it moves it backward.
<textureMap.coordinates>.U_Tiling <textureMap.coordinates>.V_Tiling Float Float default: 1.0 default: 1.0 -- animatable -- animatable

The tiling of UV mapping coordinates; that is, the number of times a mapped materials map is repeated in the surfaces local U axis or V axis.
<textureMap.coordinates>.U_Angle <textureMap.coordinates>.V_Angle <textureMap.coordinates>.W_Angle <textureMap.coordinates>.Blur Float Float Float Float default: 0.0 default: 0.0 default: 0.0 default: 1.0 -- animatable, angle -- animatable, angle -- animatable, angle -- animatable

Rotates the map about the U-axis (in degrees). Rotates the map about the V-axis (in degrees). Rotates the map about the W-axis (in degrees). Affects the sharpness or blurriness of the map based on its distance from the view. The farther away the map is, the greater the blurring. The Blur value blurs maps in world space.
<textureMap.coordinates>.Blur_Offset Float default: 0.0 -- animatable

Affects the sharpness or blurriness of the map without regard to its distance from the view. Blur Offset blurs the image itself in object space. Use this option when you want to soften or defocus the details in a map to achieve the effect of a blurred image.

1238

Chapter 11

3ds max Objects

<textureMap.coordinates>.Phase <textureMap.coordinates>.Noise_Amount

Float Float

default: 0.0 default: 1.0

-- animatable -- animatable

The speed of the animation of the noise function. The strength of the fractal function, expressed as a percentage. If the amount is 0 there is no noise. If the amount is 100 the map becomes pure noise.
<textureMap.coordinates>.Noise_Levels Integer default: 1 -- animatable

The number of times the function is applied. The effect of the level is dependent on the Amount value. The stronger the amount, the greater the effect of increasing the Levels value.
<textureMap.coordinates>.Noise_Size Float default: 1.0 -- animatable

The scale of the noise function relative to geometry. At very small values, the noise effect becomes white noise. At large values, the scale can exceed the scale of the geometry, in which case it has little or no effect. Note: The following properties are not accessible by MAXScript in 3ds max 4: Show Map on Back, Mirror, and Tile checkboxes and UV/VW/WU radiobuttons in the Coordinates rollout, and Animate and On checkboxes in the Noise rollout.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

StandardXYZGen : Material
Properties:
<textureMap.coords>.coordType Integer default: 0

The type of coordinates used for mapping: Object XYZ (Uses planar mapping based on the objects local coordinates (disregarding the pivot point location).) World XYZ (Uses planar mapping based on the scenes world coordinates (disregarding the objects bounding box).) Explicit Map Channel (Uses the map channel specified by the .mapChannel value.) Vertex Color Channel (Uses assigned vertex colors as a channel.)
<textureMap.coords>.mapChannel <textureMap.coords>.offset <textureMap.coords>.Tiling Integer Point3 Point3 default: 1 default: [0,0,0] default: [1,1,1] -- animatable -- animatable

The map channel used for mapping coordinates. Changes the position of the map in UV coordinates. The map moves in relation to its size. The number of times the map is tiled across each axis.

TexOutputClass : Material

1239

<textureMap.coords>.angle angle <textureMap.coords>.blur

Point3

default: [0,0,0]

-- animatable, point3

Rotates the map about the U, V, and W-axis (in degrees).

Float default: 1.0 -- animatable

Affects the sharpness or blurriness of the map based on its distance from the view. The farther away the map is, the greater the blurring. The Blur value blurs maps in world space.
<textureMap.coords>.Blur_Offset Float default: 0.0 -- animatable

Affects the sharpness or blurriness of the map without regard to its distance from the view. Blur Offset blurs the image itself in object space.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

TexOutputClass : Material
Properties:
<texturemap.output>.Output_Amount Float default: 1.0 -- animatable

The amount of the map being mixed into a composite material. Affects the saturation and alpha value of the map.
<texturemap.output>.RGB_Offset Float default: 0.0 -- animatable

This value is added to the RGB values of the map colors, which affects the tonal value of the colors. Eventually the map becomes white and self-illuminated. Lowering the value decreases the tonal value towards black.
<texturemap.output>.RGB_Level Float default: 1.0 -- animatable

The RGB values of the map colors are multiplied by this value, which affects the saturation of the color. Eventually the map becomes fully saturated and self-illuminated. Lowering the value decreases the saturation and makes the map colors grayer.
<texturemap.output>.Bump_Amount Float default: 1.0 -- animatable

Adjusts the amount of bumpiness. This value has an effect only when the map is used as a bump map.
<texturemap.output>.Mono_Color_Map subAnim

The Mono_Color_Map SubAnim contains the monochrome color mapping curve. You cannot create this curve in MAXScript, or access this curve unless you first turn on the Enable Color Map checkbox in the user interface.
<texturemap.output>.RGB_Color_Map subAnim

The RGB_Color_Map SubAnim contains the RGB color mapping curves. You cannot create these curves in MAXScript, or access the curves unless you first turn on the Enable Color Map checkbox and select the RGB radiobutton in the user interface.

1240

Chapter 11

3ds max Objects

<texturemap.output.Mono_Color_Map>.curve_1

SubAnim

The curve_1 SubAnim contains the monochrome color mapping curve points. You cannot create or access these points unless the point is animated. If a point is animated, you can access the point position using the .Point_X property of curve_1, where X in the point number.
<texturemap.output.RGB_Color_Map>.curve_1 <texturemap.output.RGB_Color_Map>.curve_2 <texturemap.output.RGB_Color_Map>.curve_3 SubAnim SubAnim SubAnim

The curve_1, curve_2, and curve_3 SubAnims contains the R, G, and B color mapping curve, respectively. You cannot create or access points in these curves unless the point is animated. If a point is animated, you can access the point position using the .Point_X property of the curve, where X in the point number. Note: The following properties are not accessible by MAXScript in 3ds max 4: Invert, Clamp, Alpha from RGB Intensity, and Enable Color Map checkboxes, and the RGB/Mono radio-button.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

TextureMap Types
The following list displays the 3ds max TextureMap subclasses: Adobe_Photoshop_Plug_In_Filter (p. 1241) Adobe_Premiere_Video_Filter (p. 1242) Bitmap (p. 1243) Bricks (p. 1245) Cellular (p. 1247) Checker (p. 1249) Composite (p. 1250) Dent (p. 1251) Falloff (p. 1252) FalloffTextureMap (p. 1255) FlatMirror (p. 1255) Gradient (p. 1257) Gradient_Ramp (p. 1259) Marble (p. 1261) Mask (p. 1262) Mix (p. 1262)

Adobe_Photoshop_Plug_In_Filter : TextureMap

1241

Noise (p. 1263) NoTexture (p. 1265) Output (p. 1265) Paint (p. 1266) Particle_Age (p. 1266) Particle_Mblur (p. 1267) Perlin_Marble (p. 1268) Planet (p. 1269) Raytrace (p. 1271) Reflect_Refract (p. 1276) RGB_Multiply (p. 1278) RGB_Tint (p. 1278) Smoke (p. 1279) Speckle (p. 1280) Splat (p. 1281) Stucco (p. 1282) Swirl (p. 1283) Thin_Wall_Refraction (p. 1284) Vertex_Color (p. 1285) Water (p. 1286) Wood (p. 1010)

Adobe_Photoshop_Plug_In_Filter : TextureMap
Constructor:
adobe_photoshop_plug_in_filter ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Adobe_Photoshop_Plug_In_Filter>.blur animatable, percentage <Adobe_Photoshop_Plug_In_Filter>.Foreground_Color 0) -- animatable <Adobe_Photoshop_Plug_In_Filter>.Background_Color 0) -- animatable Float Color default: 0.0 --

default: (color 0 0

Specifies the foreground color for the image, used by some Photoshop filters.
Color default: (color 0 0

Specifies the background color for the image, used by some Photoshop filters.

1242

Chapter 11

3ds max Objects

<Adobe_Photoshop_Plug_In_Filter>.coordinates <Adobe_Photoshop_Plug_In_Filter>.output

SubAnim StandardTextureOutput

See the UVGenClass (p. 1237) topic for the StandardUVGen properties. See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties. Note: The following properties are not accessible by MAXScript in 3ds max 4: the Use Alpha Plane checkbox in the Parameters rollout, and all properties in the Bitmap Parameters and Time Parameters rollouts.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Adobe_Premiere_Video_Filter : TextureMap
Constructor:
adobe_premiere_video_filter ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Adobe_Premiere_Video_Filter>.coordinates <Adobe_Premiere_Video_Filter>.output SubAnim StandardTextureOutput

See the UVGenClass (p. 1237) topic for the StandardUVGen properties. See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties. Note: The following properties are not accessible by MAXScript in 3ds max 4: all properties in the Time Parameters rollout.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

BitmapTexture : TextureMap

1243

BitmapTexture : TextureMap
Constructor:
bitmaptexture ... bitmaptex ...

Properties:
<Bitmaptexture>.bitmap Bitmap default: Bitmap:

Returns the bitmap of the texture map. The script can perform any bitmap operations on this bitmap and the changes will be reflected in the texture map. In order to see the results of changing the bitmap in Material Editor and in the viewports, you need to modify any one bitmapTexture property in the Material Editor user interface. This is a read only property.
<Bitmaptexture>.filename String Integer default: default: 0 -- alias: file_name

The name of the bitmap file.

<Bitmaptexture>.filtering

The method of pixel averaging used in antialiasing the bitmap: Pyramidal (Requires less memory and is adequate for most purposes.) Summed Area (Requires much more memory, but yields generally superior results.) None (Turns off filtering.)
<Bitmaptexture>.monoOutput Integer default: 0

Some parameters, such as opacity or specular level are a single value as opposed to a materials three-value color components. Controls in this group determine the source of the Output mono channel in terms of the input bitmap: RGB Intensity (Uses the intensity of the red, green, and blue channels for mapping. The color of the pixels is ignored and only the value or luminance of the pixels is used. The colors are computed as gray values in the range between 0 (black) and 255 (white).) Alpha (Uses the intensity of the alpha channel for mapping.)
<Bitmaptexture>.RGBOutput Integer default: 0

The RGB Channel Output determines where the output RGB part comes from. The controls in this group affect only maps for material components that display color: Ambient, Diffuse, Specular, Filter Color, Reflection, and Refraction. RGB (Displays the full color values of the pixels.) Alpha as Gray (Displays tones of gray based on the levels of the alpha channel.)
<Bitmaptexture>.apply <Bitmaptexture>.cropPlace Boolean Integer default: false default: 0

Turn on to use the cropping or placements settings. Set whether cropping or placement is active: Crop Place

1244

Chapter 11

3ds max Objects

<Bitmaptexture>.clipu clip_u_offset <Bitmaptexture>.clipv clip_v_offset <Bitmaptexture>.clipw clip_u_width <Bitmaptexture>.cliph clip_v_width <Bitmaptexture>.jitter jitter_placement <Bitmaptexture>.alphasource

Float

default: 0.0

-- animatable, alias:

Adjusts the bitmap location along the U-axis.

Float default: 0.0 -- animatable, alias:

Adjusts the bitmap location along the V-axis.

Float default: 1.0 -- animatable, alias:

Adjusts the width of the bitmap.

Float default: 1.0 -- animatable, alias:

Adjusts the height of the bitmap.

Float default: 1.0 -- animatable, alias:

The amount of random offset. At 0, there is no random offset.

Integer default: 0

Controls in this group determine the source of the Output alpha channel in terms of the input bitmap: Image Alpha (Uses the images alpha channel.) RGB Intensity (Converts the colors in the bitmap to grayscale tonal values and uses them for transparency. Black is transparent and white is opaque.) None (Opaque; does not use transparency.)
<Bitmaptexture>.preMultAlpha Boolean default: true

Determines how alpha is treated in the bitmap. When turned on, the default, premultiplied alpha is expected in the file. When turned off, the alpha is treated as nonpremultiplied, and any RGB values are ignored.
<Bitmaptexture>.starttime <Bitmaptexture>.playbackrate Timedefault: 0f Float default: 1.0

The frame where the playback of the animated map will begin. Lets you speed up and slow down the rate that the animation is applied to the map (for example, 1.0 is normal speed, 2.0 is twice as fast, .333 is 1/3 as fast).
<Bitmaptexture>.endcondition Integer default: 0

These controls determine what happens after the last frame of the animation: Loop (Causes the animation to loop over and over again.) Ping Pong (Causes the animation to be played backwards, making every animated sequence loop smoothly.) Hold (Causes the last frame of the animation to be frozen on the surface until the end of the scene.)
<Bitmaptexture>.coords StandardUVGen -- alias: coordinates

See the UVGenClass (p. 1237) topic for the StandardUVGen properties.

Bricks : TextureMap

1245

<Bitmaptexture>.output

StandardTextureOutput

See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties. Associated Methods:
enumerateFiles [ <MAXWrapper_obj> ] <function> [ <arg> ] [ #inactive ] [ #videoPost ] [ #render ] [ #missing ] [ #localOnly ] \ \

Lets you run through all the bitmap files currently used in the scene or in an individual object. You can filter this so it just gives you the bitmap files that are inactive or missing. See the Bitmap Files (p. 1641) topic for a description of this methods parameters.
freeSceneBitmaps()

Frees up all the memory used by the image file bitmap caches. This is useful if memory is fragmented with a lot of different bitmaps and you want to have just the ones currently active reloaded.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Bricks : TextureMap
Constructor:
bricks ...

Properties:
<Bricks>.Brick_Type Integer default: 1

Brick_Type = 0 - Custom Bricks; 1 - Running Bond; 2 - Common Flemish Bond; 3 - English Bond; 4 - 1/2 Running Bond; 5 - Stack Bond; 6 - Fine Running Bond; 7 - Fine Stack Bond The brick_type values define a set of predefined values for the Stacking and Row and Column Editing properties. Changing brick_type only updates these properties if Material Editor is displayed and the material is in the active slot.
<Bricks>.Show_Texture_Swatches Integer default: 1

When on, updates to show the texture assigned by a map for Bricks or Mortar. OFF ON
<Bricks>.Brick_Color animatable Color default: (color 165.75 76.5 51) --

The color of the bricks.

<Bricks>.Horizontal_Count Float default: 3.0 -- animatable

The number of bricks in a row.

1246

Chapter 11

3ds max Objects

<Bricks>.Vertical_Count <Bricks>.Color_Variance <Bricks>.Fade_Variance <Bricks>.Mortar_Color animatable

Float Float Float Color

default: 8.0 default: 0.4 default: 0.2

-- animatable -- animatable -- animatable --

The number of bricks in a column. The color variation among the bricks. The fading variation among the bricks.
default: (color 211.65 196.35 183.6)

The color of the mortar.

<Bricks>.Horizontal_Gap <Bricks>.Vertical_Gap <Bricks>.Lock_Gap_Symmetry Float Float Integer default: 1.0 default: 1.0 default: 1 -- animatable -- animatable

The horizontal size of the mortar between the bricks. The vertical size of the mortar between the bricks. When on, the vertical_gap and horizontal_gap values are locked to one another. Off On
<Bricks>.Holes Integer default: 0 -- animatable

The percentage of holes in the bricked surface caused by missing bricks. The mortar shows through the holes.
<Bricks>.Edge_Roughness <Bricks>.Random_Seed Float Integer default: 0.0 default: 43304 -- animatable -- animatable

Controls the roughness of the edges of the mortar. Randomly applies patterns of color variation to the bricks. Does not require any other setting to generate completely different patterns.
<Bricks>.Line_Shift <Bricks>.Random_Shift <Bricks>.Use_Row_Edit Float Float Integer default: 0.0 default: 0.0 default: 0 -- animatable -- animatable

Shifts every second row of bricks a distance of one unit. Randomly shifts all rows of bricks a distance of one unit. Turn on/off row edit: Off On
<Bricks>.Per_Row Integer Float default: 2 default: 1.0

The amount of bricks per row.

<Bricks>.Change_Row

For every row you specify in the Per_Row value, the software stores the amount of bricks that you specify in the Change_row value.

Cellular : TextureMap

1247

<Bricks>.Use_Column_Edit

Integer

default: 0

Turn on/off column edit: OFF ON

<Bricks>.Per_Column <Bricks>.Change_Column Float Float default: 1.0 default: 1.0

The amount of bricks per column. For every row you specify in the Per_Column value, the software stores the amount of bricks that you specify in the Change_column value.
<Bricks>.coordinates SubAnim

See the UVGenClass (p. 1237) topic for the StandardUVGen properties. Note: The Bricks and Mortar sub-maps are not accessible to MAXScript in 3ds max 4 unless they have already been assigned to the Bricks map. Once these maps have been assigned, they are available as properties of the Bricks TextureMap value. The property names, however, are dependent on the type of maps assigned. For example, if a Checker and a Cellular map were assigned as the Bricks and Mortar maps, the property names would be similar to Bricks__Map__7____Checker and Mortar__Map__6____Cellular. These maps are also stored as subAnims 15 and 16 of the Bricks TextureMap value. If the subAnim name for the subAnim is Bricks__None and Mortar__None, respectively, no map has been assigned. There is an error in the parameter naming for Bricks. The Per_Column property is exposed with the name Change_Row, which conflicts with the existing Change_Row property name. As a result, you can not access the b property.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Cellular : TextureMap
Constructor:
cellular ...

Properties:
<Cellular>.celcolor alias: Cell_Color Color default: (color 255 255 255) -- animatable,

The color of the cell.

<Cellular>.cellmap textureMap default: undefined

Assigns a map to the cells, rather than a solid color.

1248

Chapter 11

3ds max Objects

<Cellular>.map1Enabled <Cellular>.variation

Boolean Float

default: true default: 0.0

-- alias: Map1_On -- animatable

When on, enables the map. When off, disables the map (cell color reverts to celcolor). Varies the color of the cells by randomly altering RGB values. The higher the variation, the greater the random effect. This percentage value can range from 0 to 100. At 0, the color swatch or the map completely determines the cell color.
<Cellular>.divcolor1 Color animatable, alias: Division_Color1 default: (color 127.5 127.5 127.5) --

The color of the first cell division.

<Cellular>.divmap1 <Cellular>.map2Enabled textureMap Boolean default: undefined default: true -- alias: DivisionMap1 -- alias: Map2_On

Assigns a map to the first cell division. When on, enables the first cell division map. When off, disables the associated map (the division color reverts to divcolor1).
<Cellular>.divcolor2 Division_Color2 <Cellular>.divmap2 <Cellular>.map3Enabled Color default: (color 0 0 0) -- animatable, alias:

The color of the second cell division.

textureMap Boolean default: undefined default: true -- alias: DivisionMap2

Assigns a map to the second cell division.

-- alias: Map3_On

When on, enables the second cell division map. When off, disables the associated map (the division color reverts to divcolor2).
<Cellular>.type Integer default: 0

Sets the shape and size of the cells: Circular (This gives a more organic, or bubbly look.) Chips (With Chips, the cells have linear edges. This gives a more chipped or mosaic appearance.)
<Cellular>.size <Cellular>.spread <Cellular>.smooth Bump_smoothing Float Float Float default: 5.0 default: 0.5 default: 0.1 -- animatable -- animatable -- animatable, alias:

Alters the overall scale of the map. Adjust this value to fit the map to your geometry. Alters the size of individual cells.

When you use a cellular map as a bump map, you might encounter aliasing or jagginess at the boundaries of the cells. If this occurs, increase this value.
<Cellular>.fractal <Cellular>.iteration Iterations Boolean Float default: false default: 3.0 -- animatable, alias:

When on, makes the cellular pattern a fractal pattern.

Sets the number of times the fractal function is applied. Caution: Increasing this value increases rendering time.

Checker : TextureMap

1249

<Cellular>.adaptive

Boolean

default: true

When on, the number of fractal iterations is set adaptively. That is, the number of iterations increases the closer the geometry is to the scenes point of view, and decreases in the distance. This reduces aliasing and also saves time while rendering.
<Cellular>.roughness Float default: 0.0 -- animatable

When you use the Cellular map as a bump map, this parameter controls how rough the bumps are. When Roughness is zero, each iteration is half the strength of the previous iteration, and half the size. As Roughness increases, each iteration is closer in strength and size to the previous iteration. When Roughness is at its maximum value of 1.0, each iteration is the same size and strength as the previous. In effect, this turns off the fractalization. Roughness has no effect unless Iterations is greater than 1.0.
<Cellular>.lowthresh <Cellular>.midthresh <Cellular>.highthresh Float Float Float default: 0.0 default: 0.5 default: 1.0 -- animatable, alias: Low -- animatable, alias: Mid -- animatable, alias: High

These controls affect the relative size of cells and divisions. They are expressed as normalized percentages (0 to 1) of the sizes specified by the default algorithm. lowthresh: Adjusts the size of the cells. Default=0.0. midthresh: Adjusts the size of the first division color, relative to the second. Default=0.5. highthresh: Adjusts the overall size of divisions. Default=1.0.
<Cellular>.coords <Cellular>.output StandardXYZGen StandardTextureOutput -- alias: coordinates

See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties. See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Checker : TextureMap
Constructor:
checker ...

Properties:
<Checker>.soften <Checker>.color1 Color_1 Float Color default: 0.0 -- animatable

Blurs the edges between the checkers. A little blurs a lot.

default: (color 0 0 0) -- animatable, alias:

Sets the color of one of the checkers.

1250

Chapter 11

3ds max Objects

<Checker>.map1

textureMap

default: undefined

-- alias: Map_1

Selects a map to use within the area of the checker color. For example, you could put an additional checkerboard within one of the checker colors.
<Checker>.map1Enabled <Checker>.color2 alias: Color_2 <Checker>.map2 Boolean Color default: true -- alias: Map_1_Enable

This enables the associated map.

default: (color 255 255 255) -- animatable,

Sets the color of the second checker.

textureMap default: undefined -- alias: Map_2

Selects a map to use within the area of the checker color. For example, you could put an additional checkerboard within one of the checker colors.
<Checker>.map2Enabled <Checker>.coords Boolean default: true -- alias: Map_2_Enable -- alias: coordinates

This enables the associated map.

StandardUVGen

See the UVGenClass (p. 1237) topic for the StandardUVGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

CompositeTextureMap : TextureMap
Constructor:
compositeTextureMap ... compositeTexture ...

Properties:
<CompositeTexturemap>.mapList undefined) -- alias: Maps <CompositeTexturemap>.mapEnabled alias: Map_1_Enable ArrayParameter ArrayParameter default: #(undefined, default: #(true, true) --

Dent : TextureMap

1251

Note: Each of the map arrays initially contains 2 elements, corresponding to 2 sub-texturemaps for the CompositeTextureMap. The mapList array stores the TextureMap for each sub-TextureMap, the mapEnabled array stores whether that sub-TextureMap is enabled. To change the number of sub-texturemaps, set the count property for either the mapList or mapEnabled property to the desired number. For example, to create a compositeTextureMap with 5 sub-texturemaps, you would say:
c=compositeTextureMap() c.mapList.count=5

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Dent : TextureMap
Constructor:
dent ...

Properties:
<Dent>.size Float default: 200.0 -- animatable

Sets the relative size of dents. As the size increases, the number of dents decreases when other settings are the same.
<Dent>.strength Float default: 20.0 -- animatable

Higher values increase the number of dents, lower values decrease the number of dents. Decreasing Strength reduces the number of dents over a surface. At 0, the surface is smooth (no dents). Increasing Strength increases the number of dents over a surface. 100 is maximum.
<Dent>.iterations <Dent>.color1 Color_1 <Dent>.map1 <Dent>.map1Enabled Integer Color default: 2 -- animatable

Sets the number of calculations used to create the dents.

default: (color 0 0 0) -- animatable, alias:

Sets the color of the dent.

TextureMap Boolean default: undefined default: true -- alias: MapOn1

Colors can be replaced by maps in the dent pattern. Enables the associated map.

1252

Chapter 11

3ds max Objects

<Dent>.color2 alias: Color_2 <Dent>.map2 <Dent>.map2Enabled <Dent>.coords

Color

default: (color 255 255 255)

-- animatable,

Sets the second color of the dent.

TextureMap Boolean default: undefined default: true -- alias: MapOn2 -- alias: coordinates

Assigns second map to the dent pattern. Enables the associated map.
StandardXYZGen

See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Falloff : TextureMap
Constructor:
falloff ...

Properties:
<Falloff>.color1 Color_1 <Falloff>.map1Amount Map_Amount_1 <Falloff>.map1 <Falloff>.map1On <Falloff>.color2 alias: Color_2 <Falloff>.map2Amount Map_Amount_2 <Falloff>.map2 <Falloff>.map2On Color default: (color 0 0 0) -- animatable, alias:

Sets the first color for falloff.

Float default: 100.0 -- animatable, alias:

Relative strength of the first color in the falloff map.

TextureMap Boolean Color default: undefined default: true -- alias: Map_1

Assigns a map to the first slot in the falloff.

-- alias: Map_1_Enable

When on, the selected maps are used in the falloff. When off, colors are used.
default: (color 255 255 255) -- animatable,

Sets the second color for falloff.

Float default: 100.0 -- animatable, alias:

Relative strength of the second color in the falloff map.

TextureMap Boolean default: undefined default: true -- alias: Map_1

Assigns a map to the second slot in the falloff.

-- alias: Map_2_Enable

When on, the selected maps are used in the falloff. When off, colors are used.

Falloff : TextureMap

1253

<Falloff>.type Falloff_Type

Integer

default: 1

-- animatable, alias:

Sets the type of falloff: Towards/Away (Sets the angular falloff ranges between face normals that face toward (parallel to) the falloff direction and normals that face away from the falloff direction. The falloff range is based on a 180-degree change in face normal direction.) Perpendicular/Parallel (Sets the angular falloff ranges between face normals that are perpendicular to the falloff direction and normals that are parallel to the falloff direction. The falloff range is based on a 90-degree change in face normal direction.) Fresnel (Based on adjustments to the Index of Refraction (IOR). Results in dim reflections on surfaces facing the view, with much brighter reflections on angled faces, creating highlights like those on the sides of a glass.) Lit/Shadowed (Adjusts between two subtextures based on how much light is falling on the object.) Distance Blend (Adjusts between two subtextures based on Near Distance and Far Distance values. Uses include reducing aliasing on large terrain objects and controlling the shading in non-photorealistic environments.)
<Falloff>.mtlIOROverride Mtl_IOR_Override_Enable <Falloff>.ior Index_of_Refraction <Falloff>.nearDistance Near_Distance Boolean default: true -- alias:

When on, allows change to the Index of Refraction set by the material.
Float default: 1.6 -- animatable, alias:

Sets a new Index of Refraction.

Float default: 0.0 -- animatable, alias:

The distance at which the blend effect begins. Note: This is only available for the Distance Blend falloff type.
<Falloff>.farDistance Far_Distance Float default: 100.0 -- animatable, alias:

The distance at which the blend effect ends. Note: This is only available for the Distance Blend falloff type.
<Falloff>.extrapolateOn Boolean Distance_Blend_Extrapolate default: false -- alias:

When on, allows the effect to continue beyond the Near and Far settings. Note: This is only available for the Distance Blend falloff type.
<Falloff>.direction Falloff_Direction Integer default: 0 -- animatable, alias:

Sets the direction of the falloff: Viewing Direction (Sets the falloff direction relative to the camera (or screen). Changing object orientation doesnt affect the falloff map.)

1254

Chapter 11

3ds max Objects

Object ( Picks an object whose orientation determines the falloff direction, .node. The falloff direction is the direction from the point being shaded toward the objects center. Points on the side toward the object center get the Towards value, and those away from the object get the Away value.) Local X Axis (Sets the falloff direction to the objects local X-axis. Changing the orientation of the object changes the falloff direction. When no object is chosen, the falloff direction uses the local X-axis of the object being shaded.) Local Y Axis (Sets the falloff direction to the objects local Y-axis. Changing the orientation of the object changes the falloff direction. When no object is chosen, the falloff direction uses the local Y-axis of the object being shaded.) Local Z Axis (Sets the falloff direction to the objects local Z-axis. Changing the orientation of the object changes the falloff direction. When no object is chosen, the falloff direction uses the local Z-axis of the object being shaded.) World X Axis (Sets the falloff direction to the world coordinate system X-axis. Changing object orientation doesnt affect the falloff map.) World Y Axis (Sets the falloff direction to the world coordinate system Y-axis. Changing object orientation doesnt affect the falloff map.) World Z Axis (Sets the falloff direction to the world coordinate system Z-axis. Changing object orientation doesnt affect the falloff map.)
<Falloff>.node Falloff_Direction_Object <Falloff>.texture_output <Falloff>.mixcurve <Falloff.mixcurve>.curve_1 Node default: undefined -- alias:

When Falloff_Direction = 1, this object will determine the falloff direction.

StandardTextureOutput SubAnim SubAnim default: SubAnim:MixCurve default: SubAnim:Curve_1

See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties. This mix curve determines the falloff. The curve_1 SubAnim contains the mix curve points. You cannot create or access these points unless the point is animated. If a point is animated, you can access the point position using the .Point_X property of curve_1, where X in the point number.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

FalloffTextureMap : TextureMap

1255

FalloffTextureMap : TextureMap
Constructor: The falloffTextureMap class is used to convert 3ds max R2.5 falloff texture maps to the new 3ds max 4 falloff texture map. FalloffTextureMap objects are not creatable in MAXScript. Properties: There are no properties associated with falloffTextureMap.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

FlatMirror : TextureMap
Constructor:
flatMirror ...

Properties:
<FlatMirror>.applyBlur Boolean default: true

Turns on filtering to blur the maps. Antialiasing is also applied to the Distortion effect, if any, when Apply Blur is turned on.
<FlatMirror>.blurAmount Float default: 1.0 -- animatable

Affects the sharpness or blurriness of the generated map based on its distance from the object. The farther away the map is, the greater the blurring.
<FlatMirror>.frame Integer default: 1

When this is set to 0, the renderer creates the automatic flat mirror only on the first frame. When this is set to 1, the renderer creates the automatic flat mirror based on nthframe.
<FlatMirror>.nthFrame <FlatMirror>.useEnviroment Integer Boolean default: 1 default: true

When off, environment maps are ignored by the mirror during rendering. Its useful to turn this off when you have mirrors in the scene and youre rotoscoping against a flat screen environment map. A screen environment map does not exist in 3D space the way the other environment-map types do, and will not render properly.
<FlatMirror>.applyToFaceID <FlatMirror>.faceID Boolean Integer default: false default: 1

When on, a specified material is applied to the mirror face. Specifies the material ID number where you want the mirror assigned.

1256

Chapter 11

3ds max Objects

<FlatMirror>.distortionType

Integer

default: 0

To simulate irregular surfaces, you can distort the flat-mirror reflections. Distortion can be based on a bump map or on noise controls built into Flat Mirror material. None (No distortion) Use Bump Map (Distorts the reflection using the materials bump map. A flat mirror surface that has a Bump map will appear bumpy, but its reflection wont be distorted by the bumps unless you use this option.) Use Built-in Noise (Distorts the reflection using the settings in the Noise group.)
<FlatMirror>.noiseType Integer default: 0

Sets the type of noise when distortionType is set to 2. Regular (Generates plain noise. Basically the same as Fractal noise with the Levels setting at 1. When the noise type is set to Regular, the Levels spinner is inactive, because Regular is not a fractal function.) Fractal (Generates noise using a fractal algorithm. The Levels setting determines the number of iterations for the fractal noise.) Turbulence (Generates fractal noise with an absolute value function applied to it to make fault lines.)
<FlatMirror>.distortionAmount Float default: 0.5 -- animatable

Adjusts the amount of distortion to the reflected image. This is the only value that affects the amount of distortion.
<FlatMirror>.phase Float default: 0.0 -- animatable

Controls the speed of the animation of the noise function. A 3D noise function is used for the noise, so that the first two parameters are U and V and the third is phase.
<FlatMirror>.size <FlatMirror>.level Float Float default: 10.0 default: 2.0 -- animatable -- animatable

Sets the scale of the noise function. Smaller values give smaller chunks of noise. Sets the number of fractal iterations or turbulence (as a continuous function).

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Gradient : TextureMap

1257

Gradient : TextureMap
Constructor:
gradient ...

Properties:
<Gradient>.color1 alias: Color_1 <Gradient>.map1 <Gradient>.map1Enabled Map_1_Enable <Gradient>.color2 animatable, alias: Color_2 <Gradient>.map2 <Gradient>.map2Enabled Map_2_Enable <Gradient>.color3 - animatable, alias: Color_3 <Gradient>.map3 <Gradient>.map3Enabled Map_3_Enable <Gradient>.color2Pos alias: Color_2_Position Color default: (color 0 0 0) -- animatable,

The gradient interpolates between 3 colors. This is the first color.

TextureMap Boolean default: undefined default: true -- alias: Map_1 -- alias:

You can interpolate between 3 maps instead of colors. This is the first map.

When on, the associated map is enabled.

Color default: (color 127.5 127.5 127.5) --

The gradient interpolates between 3 colors. This is the second color.

TextureMap Boolean default: undefined default: true -- alias: Map_2 -- alias:

You can interpolate between 3 maps instead of colors. This is the second map.

When on, the associated map is enabled.

Color default: (color 255 255 255) -

The gradient interpolates between 3 colors. This is the third color.

TextureMap Boolean default: undefined default: true -- alias: Map_3 -- alias:

You can interpolate between 3 maps instead of colors. This is the third map.

When on, the associated map is enabled.

Float default: 0.5 -- animatable,

Controls the centerpoint of the middle color. The position ranges from 0 to 1. When it is 0, color2 replaces color3. When it is 1, color2 replaces color1.
<Gradient>.gradientType Gradient_Type Integer default: 0 -- alias:

Sets the type of gradient: Linear (Interpolates the color based on the vertical position.) Radial (Interpolates based on the distance from the center of the map.)
<Gradient>.noiseAmount alias: Noise_Amount Float default: 0.0 -- animatable,

When nonzero (ranges from 0 to 1), applies a noise effect. This perturbs the color interpolation parameter using a 3D noise function based on U, V, and Phase.

1258

Chapter 11

3ds max Objects

<Gradient>.noiseType Noise_Type

Integer

default: 0

-- alias:

Set the type of noise Regular (Generates plain noise. This is the same as Fractal noise with the Levels setting at 1.) Fractal (Generates noise using a fractal algorithm. noiselevels sets the number of iterations for the fractal noise.) Turbulence (Generates fractal noise with an absolute value function applied to it to make fault lines. The noise amount must be greater than 0 to see any effects of turbulence.)
<Gradient>.noiseSize alias: Noise_Size <Gradient>.noisePhase alias: Noise_Phase Float default: 1.0 -- animatable,

Scales the noise function. Smaller values give smaller chunks of noise.
Float default: 0.0 -- animatable,

Controls the speed of the animation of the noise function. A 3D noise function is used for the noise. The first two parameters are U and V and the third is phase.
<Gradient>.noiseLevels alias: Noise_Levels <Gradient>.noiseThresholdLow alias: Low_Threshold <Gradient>.noiseThresholdHigh alias: High_Threshold <Gradient>.noiseThresholdSMooth alias: Threshold_Smoothing Float default: 4.0 -- animatable,

Sets the number of fractal iterations or turbulence (as a continuous function).

Float Float Float default: 0.0 default: 1.0 default: 0.0 -- animatable, -- animatable, -- animatable,

When the noise value is above the Low threshold and below the High threshold, the dynamic range is stretched to fill 0-1. This produces a smaller discontinuity at the threshold transition and thus causes less potential aliasing. noiseThresholdLow: Sets the low threshold. noiseThresholdHigh: Sets the high threshold. NoiseThresholdSmooth: Helps make a smoother transition from the threshold value to the noise value. When 0, no smoothing is applied. When it is 1, the maximum amount of smoothing is applied.
<Gradient>.coords coordinates <Gradient>.output StandardUVGen -- alias:

See the UVGenClass (p. 1237) topic for the StandardUVGen properties.
StandardTextureOutput

See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.

Gradient_Ramp : TextureMap

1259

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Gradient_Ramp : TextureMap
Constructor:
gradient_ramp ...

Properties:
<Gradient_Ramp>.Gradient_Type Integer default: 4

The type of gradient: 4 Corner (An asymmetrical linear transition of colors.) Box (A box.) Diagonal (A linear diagonal transition of colors.) Lighting (Based on the light intensity value.) Linear (A smooth, linear transition of colors.) Mapped (Based on the luminance. Remaps the colors of the source map used in the gradient.) Normal (Based on the angle between the vector from the camera to the object and the surface normal vector at the sample point.) Pong (A diagonal sweep that repeats in the middle.) Radial (A radial transition of colors.) Spiral (A smooth, circular transition of colors.) Sweep (A linear sweep transition of colors.) Tartan (A plaid.)
<Gradient_Ramp>.Source_Map_On Integer default: 1

When on, assigns a map to a mapped gradient. OFF ON

1260

Chapter 11

3ds max Objects

<Gradient_Ramp>.Noise_Type

Integer

default: 0

Sets the noise type: Regular (Generates plain noise. Basically the same as fractal noise with levels disabled, because Regular is not a fractal function.) Fractal (Generates noise using a fractal algorithm. levels sets the number of iterations for the fractal noise.) Turbulence (Generates fractal noise with an absolute value function applied to it to make fault lines. Note that amount must be greater than 0 to see any effects of turbulence.)
<Gradient_Ramp>.amount Float default: 0.0 -- animatable

When nonzero, a random noise effect is applied to the gradient, based on the interaction of the gradient ramp colors (and maps, if present). The higher this value, the greater the effect.
<Gradient_Ramp>.size <Gradient_Ramp>.phase Float Float default: 1.0 default: 0.0 -- animatable -- animatable

Sets the scale of the noise function. Smaller values give smaller chunks of noise. Controls the speed of the animation of the noise function. A 3D noise function is used for the noise; the first two parameters are U and V and the third is phase.
<Gradient_Ramp>.Levels <Gradient_Ramp>.Low_Threshold <Gradient_Ramp>.High_Threshold Float Float Float default: 4.0 default: 0.0 default: 1.0 -- animatable -- animatable -- animatable

Sets the number of fractal iterations or turbulence (as a continuous function).

When the noise value is above the Low threshold and below the High threshold, the dynamic range is stretched to fill 0 to 1. This causes a smaller discontinuity at the threshold transition and produces less potential aliasing.
<Gradient_Ramp>.Threshold_Smoothing Float default: 0.0 -- animatable

Helps make a smoother transition from the threshold value to the noise value. When 0, no smoothing is applied. When 1, the maximum amount of smoothing is applied.
<Gradient_Ramp>.coordinates <Gradient_Ramp>.output SubAnim StandardTextureOutput

See the UVGenClass (p. 1237) topic for the StandardUVGen properties. See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.
<Gradient_Ramp>.gradient_ramp SubAnim <Gradient_Ramp.gradient_ramp>.flag__1 SubAnim <Gradient_Ramp.gradient_ramp>.flag__2 SubAnim <Gradient_Ramp.gradient_ramp>.flag__3 SubAnim <Gradient_Ramp.gradient_ramp.flag__1>.color Point3 animatable <Gradient_Ramp.gradient_ramp.flag__2>.color Point3 animatable <Gradient_Ramp.gradient_ramp.flag__3>.color Point3 animatable <Gradient_Ramp.gradient_ramp.flag__3>.position Float animatable

default: [255,0,0] default: [0,0,255] default: [0,255,0] default: [0,255,0]

-----

Marble : TextureMap

1261

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Marble : TextureMap
Constructor:
marble ...

Properties:
<Marble>.size <Marble>.width Vein_width <Marble>.color1 Color_1 <Marble>.map1 <Marble>.map1Enabled <Marble>.color2 alias: Color_2 <Marble>.map2 <Marble>.map2Enabled <Marble>.coords Float Float default: 70.0 default: 0.025 -- animatable -- animatable, alias:

Sets the spacing between the veins.

Sets the width of the veins.

Color default: (color 51 51 25.5) -- animatable, alias:

The color for the veins.

TextureMap Boolean Color default: undefined default: true -- alias: Map_1 -- alias: Map_1_Enable

The map used for the veins. When on, the veins use map1 as their color.
default: (color 209.1 209.1 153) -- animatable,

The color of the background.

TextureMap Boolean default: undefined default: true -- alias: Map_2 -- alias: Map_2_Enable -- alias: coordinates

The map used for the background. When on, map2 is used for the background.
StandardXYZGen

See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1262

Chapter 11

3ds max Objects

Mask : TextureMap
Constructor:
mask ... maskTex ...

Properties:
<Mask>.map <Mask>.mapEnabled TextureMap Boolean TextureMap Boolean Boolean default: undefined default: true default: undefined default: true default: false -- alias: Map_2_Enable -- alias: Invert -- alias: Map_1_Enable

The map viewed through the mask. Enables the map.

<Mask>.mask <Mask>.maskEnabled <Mask>.maskInverted

The map to be used as a mask. Enables the mask map. When on, inverts the effect of the mask.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Mix : TextureMap
Constructor:
mix ...

Properties:
<Mix>.color1 <Mix>.map1 <Mix>.map1Enabled <Mix>.color2 Color_2 <Mix>.map2 Color TextureMap Boolean Color default: (color 0 0 0) -- animatable, alias: Color_1 default: undefined default: true -- alias: Map_1 -- alias: Map_1_Enable

The first color to be mixed. Sets a map to be used instead of color1. When on, map1 is enabled.
default: (color 255 255 255) -- animatable, alias:

The second color to be mixed.

TextureMap default: undefined -- alias: Map_2

Sets a map to be used instead of color2.

Noise : TextureMap

1263

<Mix>.map2Enabled <Mix>.mixAmount

Boolean Float

default: true default: 0.0

-- alias: Map_2_Enable -- animatable, percentage

When on, map2is enabled. Determines the proportion of the mix. 0 means only color1 is visible on the surface, 1 means only color2 is visible.
<Mix>.mask TextureMap default: undefined

You can also use a map instead of the mix amount. The two colors will mix in greater or lesser degree according to the intensity of the map.
<Mix>.maskEnabled <Mix>.useCurve <Mix>.lower <Mix>.upper Boolean Boolean Float Float default: true default: false default: 0.3 default: 0.7 -- animatable -- animatable -- alias: MaskEnable

When on, mask is used instead of mixAmount. Determines whether the Mixing Curve effects the mix.

Adjusts the level of the upper and lower limits. If the two values are the same, the two materials will meet at a definite edge. Wider ranges give more gradual mixing.
<Mix>.output StandardTextureOutput

See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Noise : TextureMap
Constructor:
noise ...

Properties:
<Noise>.type Integer default: 0

Sets the type of noise: Regular (Generates plain noise. Basically the same as fractal noise with levels at 1.) Fractal (Generates noise using a fractal algorithm. levels sets the number of iterations for the fractal noise.) Turbulence (Generates fractal noise with an absolute value function applied to it to make fault lines.)
<Noise>.size Noise_Size Float default: 25.0 -- animatable, alias:

Sets the scale of the noise function.

1264

Chapter 11

3ds max Objects

<Noise>.thresholdLow Low_Threshold <Noise>.thresholdHigh High_Threshold

Float Float

default: 0.0 default: 1.0

-- animatable, alias: -- animatable, alias:

When the noise value is above the Low threshold and below the High threshold, the dynamic range is stretched to fill 0-1. This creates a smaller discontinuity (technically, 1st order instead of 0 order) at the threshold transition and produces less potential aliasing.
<Noise>.levels Noise_Levels Float default: 3.0 -- animatable, alias:

Determines how much fractal energy is used for the Fractal and Turbulence noise functions. You can set the exact amount of turbulence you want, and also animate the number of fractal levels.
<Noise>.phase Float default: 0.0 -- animatable

Controls the speed of the animation of the noise function. Use this option to animate the noise function.
<Noise>.color1 Color_1 <Noise>.map1 <Noise>.map1Enabled <Noise>.color2 alias: Color_2 <Noise>.map2 <Noise>.map2Enabled <Noise>.coords <Noise>.output Color default: (color 0 0 0) -- animatable, alias:

Sets the first principal noise color.

TextureMap Boolean Color default: undefined default: true -- alias: Map_1 -- alias: Map_1_Enable

Map used in place of color1. When on, map1 is enabled.

default: (color 255 255 255) -- animatable,

Sets the second principal noise color.

TextureMap Boolean default: undefined default: true -- alias: Map_2 -- alias: Map_2_Enable -- alias: coordinates

Map used in place of color2. When on, map2 is enabled.

StandardXYZGen StandardTextureOutput

see the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties see the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

NoTexture : TextureMap

1265

NoTexture : TextureMap
Assigning this texture is equivalent to setting a texture to None in the Material Editor. Setting a texture to the value undefined is also equivalent to setting the texture to None in the Material Editor. For example:
$box01.material.bumpmap=noTexture()

or
$box01.material.bumpmap=undefined

Constructor:
noTexture ...

Properties: There are no additional properties associated with NoTexture.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Output : TextureMap
Constructor:
output ...

Properties:
<output>.map1 <output>.map1Enabled <output>.output TextureMap Boolean default: undefined default: true -- alias: Map_1 -- alias: Map_1_Enable

Map used to apply output settings. When on, enables the associated map.
StandardTextureOutput

see the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1266

Chapter 11

3ds max Objects

Paint : TextureMap
Note: Paint maps are no longer supported in 3ds max 4. Constructor:
paint ...

Properties:
<Paint>.height <Paint>.width <Paint>.coordinates Integer Integer SubAnim default: 0 default: 0 -- animatable -- animatable

See the UVGenClass (p. 1237) topic for the StandardUVGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Particle_Age : TextureMap
Constructor:
particle_age ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Particle_Age>.color1 alias: Color_1 <Particle_Age>.map1 <Particle_Age>.map1Enabled <Particle_Age>.age1 Age_1 Color default: (color 0 0 0) -- animatable,

Sets the color of a particle at its birth.

TextureMap Boolean Float default: undefined default: true default: 0.0 -- alias: Map_1 -- alias: Map_1_Enable -- animatable, alias:

Sets the map used for a particle at its birth. When on, the associated map is enabled.

Sets the age where a particle starts changing from color1 to color2, expressed as a percentage of the particles entire life.
<Particle_Age>.color2 animatable, alias: Color_2 <Particle_Age>.map2 Color default: (color 127.5 127.5 127.5) --

Sets the color of a particle in mid-life.

TextureMap default: undefined -- alias: Map_2

Sets the map used for a particle in mid-life.

Particle_MBlur : TextureMap

1267

<Particle_Age>.map2Enabled <Particle_Age>.age2 Age_2

Boolean Float

default: true default: 50.0

-- alias: Map_2_Enable -- animatable, alias:

When on, the associated map is enabled.

Sets the age where a particles color equals color2, expressed as a percentage of the particles entire life.
<Particle_Age>.color3 alias: Color_3 <Particle_Age>.map3 <Particle_Age>.map3Enabled <Particle_Age>.age3 Age_3 Color default: (color 255 255 255) -- animatable,

Sets the color of a particle at its death.

TextureMap Boolean Float default: undefined default: true default: 100.0 -- alias: Map_3 -- alias: Map_3_Enable -- animatable, alias:

Sets the map used for a particle at its death. When on, the associated map is enabled.

Sets the age where a particle changes to color3, expressed as a percentage of the particles entire life.
<Particle_Age>.output StandardTextureOutput

See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Particle_MBlur : TextureMap
Constructor:
particle_mblur ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Particle_MBlur>.color1 Color_1 Color default: (color 255 255 255) -- animatable, alias:

A particle approaches this color as it reaches its slowest speed. By default, this color is white to provide the opaque end of the range for an opacity map.
<Particle_MBlur>.color2 Color_2 Color default: (color 0 0 0) -- animatable, alias:

A particle approaches this color as it speeds up. As a default, this color is black to provide transparency in an opacity map.

1268

Chapter 11

3ds max Objects

<Particle_MBlur>.sharp

Float

default: 2.0

-- animatable, alias: Sharpness

Controls the transparency, relative to the speed. If Sharpness is set to 0, the entire particle is blurry and transparent, no matter how slow it is traveling. The default works well in many cases.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Perlin_Marble : TextureMap
Constructor:
perlin_marble ...

Properties:
<Perlin_Marble>.size Float default: 50.0 -- animatable

Sets the size of the marble pattern. Change this to change the scale of marble, relative to the objects geometry.
<Perlin_Marble>.level Levels Float default: 8.0 -- animatable, alias:

Sets the number of times the turbulence algorithm is applied. Can range from 1.0 to 10.0. The higher the value, the more complicated the marble pattern.
<Perlin_Marble>.color1 animatable, alias: Color_1 <Perlin_Marble>.saturation1 Color_1_Saturation Color default: (color 189.975 189.975 160.65) --

The first color used in the marble.

Float default: 85.0 -- animatable, alias:

Controls the saturation of the color in the map, without altering the color displayed in the color swatch. Lower values darken the color, and higher values lighten it.
<Perlin_Marble>.map1 <Perlin_Marble>.map1Enabled <Perlin_Marble>.color2 animatable, alias: Color_2 <Perlin_Marble>.saturation2 Color_2_Saturation TextureMap Boolean Color default: undefined default: true -- alias: EnableMap1

Map used in place of color1. When on, the associated map is enabled.
default: (color 59.925 89.25 59.925) --

The second color used in the marble.

Float default: 70.0 -- animatable, alias:

Controls the saturation of the color in the map, without altering the color displayed in the color swatch. Lower values darken the color, and higher values lighten it.

Planet : TextureMap

1269

<Perlin_Marble>.map2 <Perlin_Marble>.map2Enabled <Perlin_Marble>.coords - alias: Coordinates

TextureMap Boolean

default: undefined default: true -- alias: EnableMap2 -

Map used in place of color2. When on, the associated map is enabled.
StandardXYZGen

See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Planet : TextureMap
Constructor:
planet ...

Properties:
<Planet>.color1 alias: Color_1 <Planet>.color2 alias: Color_2 <Planet>.color3 alias: Color_3 <Planet>.color4 alias: Color_4 <Planet>.color5 alias: Color_5 <Planet>.color6 alias: Color_6 <Planet>.color7 alias: Color_7 <Planet>.color8 alias: Color_8 Color default: (color 10.2 20.4 79.05) -- animatable,

The color at the center of the water mass.

Color default: (color 10.2 30.6 79.05) -- animatable,

The color surrounding the center of the water mass.

Color default: (color 10.2 40.8 79.05) -- animatable,

The color surrounding color2, meeting the land.

Color Color Color Color Color default: (color 10.2 99.45 12.75) -- animatable,

default: (color 99.45 79.05 12.75) -- animatable, default: (color 79.05 20.4 7.65) default: (color 99.45 79.05 51) -- animatable, -- animatable,

default: (color 99.45 99.45 99.45) -- animatable,

The colors in these five swatches are applied to the land areas of the planet surface. Their arrangement continues that of the water colors. color4 is the shoreline of the land, meeting the water; color5 comes next, working toward the center of the land mass. color8 is at the center of the land mass.

1270

Chapter 11

3ds max Objects

<Planet>.continentSize Continent_Size

Float

default: 40.0

-- animatable, alias:

Sets the size of the fractal noise pattern used to generate the continents. Can range from 0 to 100. The higher the value, the larger the continents.
<Planet>.islandFactor Island_Factor Float default: 0.5 -- animatable, alias:

Sets the size of the fractal noise pattern used to generate islands and mountains. Can range from 0 to 100. At 0, the geography is very low. Higher settings create a more rugged landscape.
<Planet>.oceanPercent Ocean_Percent <Planet>.randomSeed Float default: 60.0 -- animatable, alias:

Sets the percentage of the planets surface that is covered by water.

Integer default: 12345

Sets the seed for pseudo-random generation of the pattern. Changing this number can completely change the pattern, even if other settings remain the same. On the other hand, a different Planet map with the same settings including the same Random Seed will appear the same.
<Planet>.blendWaterLand Boolean default: true

When on, the boundary between water and land is blended, giving a hazy appearance. When off, the boundary between water and land is sharp.
<Planet>.coords StandardXYZGen -- alias: Coordinates

See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Raytrace : TextureMap

1271

Raytrace : TextureMap
Constructor:
raytrace ...

Properties:
<Raytrace.parameters>.Trace_Mode Integer default: 0

Sets whether to cast reflected or refracted rays: Auto Detect (If assigned to the materials Reflection component, the raytracer will reflect. If assigned to Refraction, it will refract. If you assign Raytrace to any other component, you have to manually specify whether you want reflected rays or refracted rays.) Reflection (Casts reflected rays off the objects surface.) Refraction (Casts refracted rays into or through the objects surface.)
<Raytrace.parameters>.Options__Raytracer_Enable true -- animatable Boolean default:

Turns the raytracer on or off. Even with raytracing off, Raytrace material and Raytrace map still reflect and refract the environment, including both the environment map for the 3ds max scene, and the environment map assigned to the Raytrace material.
<Raytrace.parameters>.Options__Antialiasing_Enable true -- animatable Boolean default:

Turns antialiasing on or off. Antialiasing is possibly the slowest portion of raytrace rendering.
<Raytrace.parameters>.Options__Self_Reflect_Refract true -- animatable Boolean default:

Turns self reflection/refraction on or off.

<Raytrace.parameters>.Options__Raytrace_Atmospherics true -- animatable Boolean default:

Turns the raytracing of atmospheric effects on or off. Atmospheric effects include fire, fog, volume light, and so on.
<Raytrace.parameters>.Options__Reflect_Refract_Material_ID_s true -- animatable Boolean default:

When on, the material reflects effects assigned to material IDs in the renderers G-buffer on or off.
<Raytrace.parameters>.Options__Raytrace_Objects_in_Glass true -- animatable Boolean default:

Turns the raytracing of objects inside raytraced objects on or off.

<Raytrace.parameters>.Options__Raytrace_Atmospherics_in_Glass true -- animatable <Raytrace.parameters>.Options__Color_Density___Fog_Enable true -- animatable Boolean default:

Same as the previous control, but for atmospheric effects instead of objects.
Boolean default:

Turns the color density and fog features on or off.

1272

Chapter 11

3ds max Objects

<Raytrace.parameters>.Background_Mode

Integer

default: 0

Sets Background Mode: Use Environment Settings (Respects the environment settings of the current scene.) Use Background_Color (Overrides environment settings) Use background map (Overrides the environment settings with the specified map.)
<Raytrace.parameters>.Background_Color (color 0 0 0) -- animatable Color default:

Color used as background.

<Raytrace.parameters>.Local_Antialias_Override false Boolean default:

When on, allows you to modify local anitialiasing settings.

<Raytrace.parameters>.Adaptive_Antialiasing false Boolean default:

When on, enables the adaptive antialiaser for this Raytrace map.
<Raytrace.parameters>.Local_Threshold 0.1 -- animatable Float default:

Determines the sensitivity of the adaption algorithm. This value can range from 0 to 1, where 0 always casts the maximum number of rays and 1 always casts only the minimum number of rays.
<Raytrace.parameters>.Local_Min__Rays 4 -- animatable Integer default:

Sets the initial number of rays cast per pixel.

<Raytrace.parameters>.Local_Max_Rays 32 -- animatable Integer default:

Sets the maximum number of rays the algorithm casts.

<Raytrace.parameters>.Local_Blur_Offset 0.0 -- animatable Float default:

Affects the sharpness or blurriness of reflections or refractions without regard to distance. You can use this to soften the details of a reflection or refraction. This value is specified in pixels.
<Raytrace.parameters>.Local_Blur_Aspect 1.0 -- animatable Float default:

Changes the shape of the blur by changing the aspect ratio. Usually you will not need to change this setting.
<Raytrace.parameters>.Local_Defocus_Amount 0.0 -- animatable Float default:

Blurs based on distance. Objects near the surface are not blurred, but objects farther away are blurred. The rays cast are spread as they leave the surface of the Raytrace map object.
<Raytrace.parameters>.Local_Defocus_Aspect 1.0 -- animatable Float default:

Changes the shape of the defocusing by changing the aspect ratio. Usually you will not need to change this setting.

Raytrace : TextureMap

1273

<Raytrace.parameters>.Use_Blur_Map false

Boolean

default:

When on, uses a map to apply the Blur Offset value. That is, where the map is white, blur offset is fully applied, and where it is black, it is ignored. For example, if the map is a Checker map, blur offset is applied only in every other square. Values between black and white cause less blur.
<Raytrace.parameters>.Use_Defocus_Map false Boolean default:

When on, uses a map to apply the Defocus value. That is, where the map is white, Defocus is fully applied, and where it is black, it is ignored. For example, if the map is a Checker map, Defocus is applied only in every other square. Values between black and white cause less defocusing.
<Raytrace.parameters>.Attenuation_Mode Integer default: 0

Sets Attenuation Mode: Off Linear (Linear attenuation is calculated between the attenuation_start and attenuation_end values.) Inverse Scale (Sets inverse square attenuation. Inverse square attenuation is calculated beginning at the attenuation_start range, and doesnt use the attenuation_end range. Inverse scale is the actual attenuation rate for light in the real world. However, it doesnt always give the effect you want in a rendered scene.) Exponential (Sets exponential attenuation. Exponential attenuation is calculated between the attenuation_start and attenuation_end values. You also specify the exponent to use.) Custom Falloff (Specifies a custom curve to use for attenuation.)
<Raytrace.parameters>.Attenuation_Start 0.0 -- animatable Float default:

The distance in world units where attenuation begins.

<Raytrace.parameters>.Attenuation_End 100.0 -- animatable <Raytrace.parameters>.Attenuation_Exponent 2.0 -- animatable <Raytrace.parameters>.Attenuation_Color_Mode <Raytrace.parameters>.Attenuation_Color (color 0 0 0) -- animatable Float Float Integer Color default: default: default: 0 default:

Attenuation_Color_Mode = 0 - Background; 1 - use Attenuation_Color

Sets the distance in world units where the ray is fully attenuated.
<Raytrace.parameters>.Attenuation_Near 1.0 -- animatable Float default:

Sets the strength of the reflected/refracted ray at the start range distance. This is a normalized percentage that can range from 0.0 to 1.0.

1274

Chapter 11

3ds max Objects

<Raytrace.parameters>.Attenuation_Control_1 0.6666 -- animatable

Float

default:

Controls the shape of the curve near the curve start.

<Raytrace.parameters>.Attenuation_Control_2 0.3333 -- animatable Float default:

Controls the shape of the curve near the curve end.

<Raytrace.parameters>.Attenuation_Far 0.0 -- animatable Float default:

Sets the strength of the reflected/refracted ray at the end range distance. This is a normalized percentage that can range from 0.0 to 1.0.
<Raytrace.parameters>.Use_Reflectivity_Map false -- animatable Boolean default:

Enables a reflectivity map.

<Raytrace.parameters>.Reflectivity_Map_Amount 1.0 -- animatable <Raytrace.parameters>.Basic_Tint_Enable false Float default:

Controls the amount of raytracing used by the material it is assigned to.

Boolean default:

Turns basic tinting on or off.

<Raytrace.parameters>.Tint_Amount 1.0 -- animatable Float default:

Sets the amount of tinting used.

<Raytrace.parameters>.Tint_Color (color 255 255 255) -- animatable Color default:

Assigns a tint color for reflections.

<Raytrace.parameters>.Use_Tint_Map false Boolean default:

Enables the use of a map for tinting.

<Raytrace.parameters>.Color_Density_Enable false Boolean default:

Turns color density on or off.

<Raytrace.parameters>.Color_Density_Color (color 255 255 255) -- animatable Color default:

Sets the transmission color.

<Raytrace.parameters>.Color_Density_Amount 1.0 -- animatable Float default:

Controls the amount of density color. It can range from 0 to 1.0. Reducing this value reduces the density color effect.

Raytrace : TextureMap

1275

<Raytrace.parameters>.Color_Density_Start 0.0 -- animatable <Raytrace.parameters>.Color_Density_End 25.0 -- animatable

Float Float

default: default:

A thin piece of tinted glass is mainly clear, while a thick piece of the same glass has more color. Start and End Distance, expressed in world units, controls help you simulate this effect. Start is the position in the object where the density color begins to appear. End is the position in the object where the density color reaches its full Amount value. To have a lighter effect, increase the End value. To have a heavier effect, reduce the End value.
<Raytrace.parameters>.Use_Color_Density_Map false Boolean default:

Enables the use of a map for the color density filter.

<Raytrace.parameters>.Fog_Enable false Boolean default:

Turns fog on or off.

<Raytrace.parameters>.Fog_Color (color 255 255 255) -- animatable Color default:

Sets the fog color.

<Raytrace.parameters>.Fog_Amount 1.0 -- animatable Float default:

Controls the amount of density fog. It can range from 0 to 1.0. Reducing this value reduces the density fog effect and makes the fog translucent.
<Raytrace.parameters>.Fog_Start 0.0 -- animatable <Raytrace.parameters>.Fog_End 25.0 -- animatable Float Float default: default:

Start and End Distance controls, expressed in world units, adjust the fog effect based on the objects dimensions. Start is the position in the object where the density fog begins to appear. End is the position in the object where the density fog reaches its full Amount value. To have a lighter effect, increase the End value. To have a heavier effect, reduce the End value.
<Raytrace.parameters>.Use_Fog_Map false Boolean default:

Enables a map for the fog color. The following properties do not correspond to any user-interface items, and may or may not be used by the raytracer.
<Raytrace.parameters>.Interobject_Interphase_Fusing false <Raytrace.parameters>.IIF_Tolerance 1.0 Boolean Float default: default:

1276

Chapter 11

3ds max Objects

Note: The sub-maps that can be assigned to a Raytrace texturemap are not accessible to MAXScript in 3ds max 4 unless they have already been assigned to the Bricks map. Once these maps have been assigned, they are available as properties of the Bricks TextureMap value. The property names, however, are dependent on the type of maps assigned. For example, if dent maps were assigned to all the sub-maps, the property names would be similar to Background__Map__17____Dent, Blur_Map__Map__18____Dent, Defocus_Map__Map__19____Dent, Reflectivity_Map__Map__20____Dent, Tint_Map__Map__21____Dent, Color_Density_Map__Map__22____Dent, and Fog_Color_Map__Map__23____Dent. These maps are also stored as subAnims 2 through 8 of the Raytrace TextureMap value, respectively. If the subAnim name for a subAnim is similar to Background__None, no map has been assigned to that sub-map.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Reflect_Refract : TextureMap
Constructor:
reflect_refract ...

Properties:
<Reflect_Refract>.source Integer default: 0

Chooses the source of the six cubic maps: Automatic (Automatically generates by looking out in six directions from the pivot of the object with the material, then mapped onto the surface during rendering. When on, the options in the Automatic group are active, letting you choose whether the maps will be generated only once, or regenerated at specified frames in the animation.) From File (When on, you can specify the bitmaps to use.)
<Reflect_Refract>.size Integer default: 100 -- animatable

Sets the size of the Reflect/Refract maps. The default value of 100 produces distinct images. Lower values lose progressively more detail.
<Reflect_Refract>.useAtmosphericMap Use_Atmospheric Boolean default: true -- alias:

When off, environment maps are ignored by Reflect/Refract map during rendering. Its useful to turn this off when you have mirrors in the scene and youre rotoscoping against a flat screen environment map. A screen environment map does not exist in 3D space the way the other environment-map types do, and will not render properly.

Reflect_Refract : TextureMap

1277

<Reflect_Refract>.apply

Boolean Float

default: true default: 0.0 -- animatable,

Turns on filtering to blur the maps.

<Reflect_Refract>.blurOffset alias: Blur_Offset

Affects the sharpness or blurriness of the map without regard to its distance from the object. Use this when you want to soften or defocus the details in a map to achieve the effect of a blurred image.
<Reflect_Refract>.blur Float default: 1.0 -- animatable

Affects the sharpness or blurriness of the generated map based on its distance from the object. The farther away the map is, the greater the blurring. Blur is primarily used to avoid aliasing. Its a good idea to use a small amount of blurring for all maps in order to avoid the scintillation or aliasing that can occur when pixel details are reduced off in the distance.
<Reflect_Refract>.near alias: Near_Value Float default: 0.0 -- animatable,

Sets the near range for fog.

<Reflect_Refract>.far alias: Far_Value Float default: 500.0 -- animatable,

Sets the far range for fog.

<Reflect_Refract>.frametype Integer default: 0

Sets the frame type: First Frame Only (Tells the renderer to create automatic maps only on the first frame.) Every Nth Frame (Tells the renderer to create animated auto maps based on nthframe.)
<Reflect_Refract>.nthframe <Reflect_Refract>.bitmapName undefined) Integer ArrayParameter default: 1 default: #(undefined, ... ,

Sets the frame rate for automatic maps.

Array with 6 elements. Each element stores a string reflecting the name of a source bitmap file.
<Reflect_Refract>.outputname Output_Name String default: undefined -- alias:

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1278

Chapter 11

3ds max Objects

RGB_Multiply : TextureMap
Constructor:
rgb_multiply ...

Properties:
<RGB_Multiply>.color1 alias: Color_1 <RGB_Multiply>.map1 <RGB_Multiply>.map1Enabled Color TextureMap Boolean Color TextureMap Boolean Integer default: (color 255 255 255) -- animatable, default: undefined default: true -- alias: Map_1 -- alias: Map_1_Enable

Enables associated map.

<RGB_Multiply>.color2 alias: Color_2 <RGB_Multiply>.map2 <RGB_Multiply>.map2Enabled default: (color 255 255 255) -- animatable, default: undefined default: true default: 2 -- alias: Map_2 -- alias: Map_2_Enable

Enables associated map.

<RGB_Multiply>.alphaFrom

Determines how to generate alpha for the map: Map #1 (Uses the first maps alpha channel.) Map #2 (Uses the second maps alpha channel.) Multiply Alphas (Generates a new alpha channel by multiplying the alpha channels of the two maps.)

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

RGB_Tint : TextureMap
Constructor:
rgb_tint ...

Properties:
<RGB_Tint>.red <RGB_Tint>.green <RGB_Tint>.blue Color Color Color default: (color 255 0 0) -- animatable default: (color 0 255 0) -- animatable default: (color 0 0 255) -- animatable

The tint of the red color channel. The tint of the green color channel. The tint of the blue color channel.

Smoke : TextureMap

1279

<RGB_Tint>.map1 <RGB_Tint>.map1Enabled

TextureMap Boolean

default: undefined default: true

-- alias: Map_1 -- alias: Map_1_Enable

Sets the map to be tinted. Enable the effect of map1.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Smoke : TextureMap
Constructor:
smoke ...

Properties:
<Smoke>.size <Smoke>.iterations Float Integer default: 40.0 default: 5 -- animatable -- animatable

Changes the scale of the smoke clumps. Sets the number of times the fractal function is applied. The higher the value, the more detail within the smoke, but the longer the calculation time.
<Smoke>.phase Float default: 0.0 -- animatable

Shifts the turbulence within the smoke pattern. Animate this parameter to animate the movement of the smoke.
<Smoke>.exponent Float default: 1.5 -- animatable

Makes color2, representing the smoke, sharper and more wispy. As this value increases, the smoke tendrils become smaller within the pattern.
<Smoke>.color1 Color_1 <Smoke>.map1 <Smoke>.map1On <Smoke>.color2 alias: Color_2 <Smoke>.map2 Color default: (color 0 0 0) -- animatable, alias:

The smokeless portion of the effect.

TextureMap Boolean Color default: undefined default: true -- alias: Map1_On

The map used for the smokeless portion of the effect. Enables the associated map.
default: (color 229.5 229.5 229.5) -- animatable,

The color of the smoke.

TextureMap default: undefined

The map used for the smoke.

1280

Chapter 11

3ds max Objects

<Smoke>.map2On <Smoke>.coords

Boolean

default: true

-- alias: Map2_On -- alias: Coordinates

Enables the associated map.

StandardXYZGen

See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Speckle : TextureMap
Constructor:
speckle ...

Properties:
<Speckle>.size <Speckle>.color1 Color_1 <Speckle>.map1 <Speckle>.map1On <Speckle>.color2 Color_2 <Speckle>.map2 <Speckle>.map2On <Speckle>.coords Float Color default: 60.0 -- animatable

Adjusts the size of the speckles. Use this to make the speckles match your geometry.
default: (color 51 127.5 255) -- animatable, alias:

The color of the speckles.

TextureMap Boolean Color default: undefined default: true -- alias: Map1_On

The map used as the color of the speckles. Enables associated map.
default: (color 178.5 204 204) -- animatable, alias:

The color of the background.

TextureMap Boolean default: undefined default: true -- alias: Map2_On -- alias: Coordinates

The map used as the color of the background. Enables associated map.
StandardXYZGen

See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Splat : TextureMap

1281

Splat : TextureMap
Constructor:
splat ...

Properties:
<Splat>.size <Splat>.iterations Float Integer default: 40.0 default: 4 -- animatable -- animatable

Adjusts the size of the splats. Use this to make the splats match your geometry. Sets the number of times the fractal function is evaluated. The higher the number, the more detailed the splats, but the longer the calculation time.
<Splat>.threshold Float default: 0.2 -- animatable

Determines how much of color1 is mixed with color2. At 0, only color1 is displayed; at 1, only color2 is displayed.
<Splat>.color1 Color_1 <Splat>.map1 <Splat>.map1On <Splat>.color2 Color_2 <Splat>.map2 <Splat>.map2On <Splat>.coords Color default: (color 178.5 204 204) -- animatable,

The color of the background.

TextureMap Boolean Color default: undefined default: true -- alias: Map1_On -- animatable,

The map used as the color of the background. Enables associated map.
default: (color 51 127.5 255)

The color of the splats.

TextureMap Boolean default: undefined default: true -- alias: Map2_On -- alias: Coordinates

The map used as the color of the splats. Enables associated map.
StandardXYZGen

See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1282

Chapter 11

3ds max Objects

Stucco : TextureMap
Constructor:
stucco ...

Properties:
<Stucco>.size Float default: 20.0 -- animatable

Adjusts the size of the indentations. Use this to make the scale of the stucco match your geometry.
<Stucco>.thickness Float default: 0.15 -- animatable

Blurs the border between the two colors. At 0, the borders are sharp. The higher the Thickness, the more the borders are blurred and the less distinct the indentations are. When you use Stucco as a bump map, the indentations are very faint at 0.5 and disappear at values not much greater.
<Stucco>.threshold Float default: 0.57 -- animatable

Determines how much of color1 is mixed with color2. At 0, only color1 is displayed; at 1, only color2 is displayed.
<Stucco>.color1 Color_1 <Stucco>.map1 <Stucco>.map1On <Stucco>.color2 alias: Color_2 <Stucco>.map2 <Stucco>.map2On <Stucco>.coords Color default: (color 0 0 0) -- animatable, alias:

The color of the indentations.

TextureMap Boolean Color default: undefined default: true -- alias: Map1_On

The map used as the color of the indentations. Enables associated map.
default: (color 229.5 229.5 229.5) -- animatable,

The background stucco color.

TextureMap Boolean default: undefined default: true -- alias: Map2_On -- alias: Coordinates

The map used as the background stucco color. Enables associated map.
StandardXYZGen

See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Swirl : TextureMap

1283

Swirl : TextureMap
Constructor:
swirl ...

Properties:
<Swirl>.Base <Swirl>.Swirl <Swirl>.Color_Contrast Color Color Float default: (color 229.5 147.9 76.5) -- animatable default: (color 0 25.5 51) -- animatable default: 0.4 -- animatable

The underlying layer for the swirl effect. Mixed with the Base color or map, produces the swirl effect. Controls the contrast between Base and Swirl. At 0, the swirl is blurred. Higher values increase the contrast until all colors become black and white, even if Swirl Intensity and Swirl Amount are very high.
<Swirl>.Swirl_Intensity Float default: 2.0 -- animatable

Controls the intensity of the swirl color. Higher values create a more vibrant mix of colors. At 0, the swirl effect disappears.
<Swirl>.Swirl_Amount Float default: 1.0 -- animatable

Controls the quantity of the swirl color that gets mixed into the base color. If set to 0, only the base color is used.
<Swirl>.Twist Float default: 1.0 -- animatable

Changes the number of spirals in the swirl effect. Higher values increase the number of spirals. Negative values change the direction of the twist. At 0, the colors are randomly distributed, not swirled.
<Swirl>.Constant_Detail Integer default: 4 -- animatable

Changes the level of detail within a swirl. Lower values minimize the level of detail within the swirl. At 0, all detail is lost. Higher values increase detail until the swirl effect disappears.
<Swirl>.Center_Position_Y <Swirl>.Center_Position_X <Swirl>.Lock_Background Float Float Integer default: -0.5 default: -0.5 default: 1 -- animatable -- animatable

Adjusts the location of the swirls center on the object. X and Y values remain identical as you adjust them. By turning off Lock and adjusting either the X or Y position, you can slide the swirl effect across the object. OFF ON
<Swirl>.Random_Seed Float default: 23638.4 -- animatable

Sets a new starting point for the swirl effect. Changes the swirl pattern while maintaining other parameters.
<Swirl>.coordinates SubAnim

See the UVGenClass (p. 1237) topic for the StandardUVGen properties.

1284

Chapter 11

3ds max Objects

Note: The Base and Swirl sub-maps are not accessible to MAXScript in 3ds max 4 unless they have already been assigned to the Swirl map. Once these maps have been assigned, they are available as properties of the Swirl TextureMap value. The property names, however, are dependent on the type of maps assigned. For example, if a Checker and a Cellular map were assigned as the Base and Swirl sub-maps, the property names would be similar to Swirl__Map__7____Checker and Swirl__Map__6____Cellular. These maps are also stored as subAnims 12 and 13 of the Swirl TextureMap value. If the subAnim name for the subAnim is Swirl__None and Swirl__None, respectively, no map has been assigned.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Thin_Wall_Refraction : TextureMap
Constructor:
thin_wall_refraction ...

Properties:
<Thin_Wall_Refraction>.applyBlur Boolean Float default: true default: 1.0 -- animatable

Turns on filtering to blur the maps.

<Thin_Wall_Refraction>.blur

Affects the sharpness or blurriness of the generated map based on its distance from the object. The farther away the map is, the greater the blurring. Blur is primarily used to avoid aliasing. Its a good idea to use a small amount of blurring for all maps in order to avoid the scintillation or aliasing that can occur when pixel details are reduced off in the distance.
<Thin_Wall_Refraction>.frame Integer default: 0

Affects how the refraction should behave in animations: First Frame Only (Tells the renderer to create the refracted image only on the first frame.) Every Nth Frame (Tells the renderer to regenerate the refracted image based on nthframe.)
<Thin_Wall_Refraction>.nthFrame Integer Boolean default: 1 default: true

Sets the regeneration rate in animations.

<Thin_Wall_Refraction>.useEnviroment

When off, environment maps are ignored by the refraction during rendering. Its useful to turn it this off when you have refractions in the scene and youre rotoscoping against a flat screen environment map. A screen environment map does not exist in 3D space the way the other environment map types do, and will not render properly.

Vertex_Color : TextureMap

1285

<Thin_Wall_Refraction>.thicknessOffset alias: Thickness_Offset

Float

default: 0.5

-- animatable,

Affects the size of the refractive offset, or jog effect. At 0, theres no offset, and the object can appear invisible in the rendered scene. At 10.0, the offset is at its greatest.
<Thin_Wall_Refraction>.bumpMapEffect alias: Bump_Map_Effect Float default: 1.0 -- animatable,

Affects the magnitude of refraction due to the presence of a bump map. This parameter multiplies the current bump map Amount in the parent material. Reduce this value to reduce the effect of the secondary refraction; increase this value to increase the effect. If there is no bump map assigned, this value has no effect.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Vertex_Color : TextureMap
Constructor:
vertex_color ...

Properties: There are no additional properties for vertex_color.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1286

Chapter 11

3ds max Objects

Water : TextureMap
Constructor:
water ...

Properties:
<Water>.numWaveSets Num_Wave_Sets Integer default: 10 -- animatable, alias:

Specifies how many wave sets are used in the pattern. Wave sets are groups of radially symmetrical waves that originate from randomly computed points along the surface of an imaginary sphere inside the object (a circle, in the case of 2D wave distribution). For calm water, set this to a low number. Use a high number for choppy water.
<Water>.waveRadius Wave_Radius Float default: 800.0 -- animatable, alias:

Specifies the radius, in 3ds max units, of the imaginary sphere (3D distribution) or circle (2D distribution) whose surface is the origin of each wave set. A large radius produces large circular wave patterns, while a small radius produces dense, smaller waves.
<Water>.waveLenMax <Water>.waveLenMin Float Float default: 50.0 default: 5.0 -- animatable -- animatable

Define the interval used to randomly chose each wave center. If these two values are close together, the water appears more regular. If theyre farther apart, the water is less regular.
<Water>.amplitude Float default: 1.0 -- animatable

Adjusts the strength and the depth of the waves by increasing the contrast between the two colors.
<Water>.phase <Water>.distribution Float Integer default: 0.0 default: 0 -- animatable

Shifts the wave pattern. Animate this parameter to animate the motion of the pattern. 3D distributes the wave centers on the surface of an imaginary sphere, affecting all sides of a 3D object. 2D distributes the wave in circles centered on the XY plane, which is more appropriate for flat water surfaces such as oceans and lakes. 3D 2D
<Water>.randomSeed Integer default: 30159

Provides a seed number to generate the water pattern. The pattern changes with each seed, but all other settings are maintained.
<Water>.color1 alias: Color_1 <Water>.map1 <Water>.map1On Color default: (color 198.9 198.9 239.7) -- animatable,

Sets the wave trough color.

TextureMap Boolean default: undefined default: true -- alias: Map1_On

Sets a map as the wave trough color. Enables associated map.

Wood : TextureMap

1287

<Water>.color2 alias: Color_2 <Water>.map2 <Water>.map2On <Water>.coords

Color

default: (color 25.5 25.5 198.9) -- animatable,

The color of wave peaks.

TextureMap Boolean default: undefined default: true -- alias: Map2_On -- alias: Coordinates

Sets a map as the color of wave peaks. Enables associated map.

StandardXYZGen

See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Wood : TextureMap
Constructor:
wood ...

Properties:
<Wood>.thickness Grain_Thickness <Wood>.radialNoise Radial_Noise Float default: 7.0 -- animatable, alias:

Sets the relative thickness of the color bands that make up the grain.
Float default: 1.0 -- animatable, alias:

Sets the relative randomness of the pattern on a plane perpendicular to the grain, the circular ring structure.
<Wood>.axialNoise Axial_Noise Float default: 1.0 -- animatable, alias:

Sets the relative randomness of the pattern on a plane parallel with the grain, along the length of the grain.
<Wood>.color1 alias: Color_1 <Wood>.map1 <Wood>.map1Enabled Color TextureMap Boolean default: (color 201.45 175.95 68.85) -- animatable, default: undefined default: true

-- alias: MapOn1

Enables associated map.

1288

Chapter 11

3ds max Objects

<Wood>.color2 alias: Color_2 <Wood>.map2 <Wood>.map2Enabled <Wood>.coords

Color TextureMap Boolean

default: (color 130.05 81.6 12.75) -- animatable, default: undefined default: true

-- alias: MapOn2 -- alias: Coordinates

Enables associated map.

StandardXYZGen

See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.

See also
TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Animation Controllers
All animation in 3ds max is implemented using one of the many controller classes accessible in the Track View and Motion Panel, or assigned automatically by 3ds max when you use the Animate button to do keyframing. Certain controllers (keyframeable controllers) store their animation values as keys. This section includes topics that discuss all aspects of scripting 3ds max controllers and the Key classes used in keyframing. Controller Common Properties, Operators, and Methods (p. 1289) Time and Key Functions on Object Hierarchies (p. 1299) Controllers - Superclass Level (p. 1300) The controllers are arranged in a hierarchy of superclasses and classes. All classes in a superclass output a specific data type (for example, Float or Point3). Each animatable property in 3ds max has a data type, and any of the classes in the superclass that outputs that data type can be assigned that property. So, for example, the linear_float and noise_float controllers are classes in the Float superclass, and either can be assigned to the height property of a box, which is has a Float data type. The list of controller superclasses can be determined using the apropos() function:
apropos controller:super

The list of available controllers can be determined using the showClass() function:
showClass *:*controller*

which lists all the known classes that have controller in their superclass name. The controllers include, at least, 3ds maxs core controllers and any 3rd-party plug-in controllers. In some cases, embedded controllers for some complex plug-ins may be visible in the showClass() listing (such as for character studio and HyperMatter). You should not attempt to create and use these controllers individually, this may result in system exceptions.

Wood : TextureMap

1289

Controller Common Properties, Operators, and Methods

Properties: All controllers have the following properties:
<controller>.keys <controller>.value MAXKeyArray -- read-only, the controllers key array varies -- get or set the current controller value

The keys and value properties give you access to the value and keys in a free-standing controller, which is useful when working with the global tracks controllers that are accessible in MAXScript. Those controllers that are not keyframeable return an empty KeyArray for their keys property. The value property is sensitive to the current time and animate contexts, so you can use it to evaluate a controller at various times or to plant keyframes in those controllers that support keys. You can only assign a value to a controllers value property if the controller is a key-based controller. The only exception to this is that you can assign a Matrix3 value to a PRS controllers value property. MAXScript will automatically set the individual position, rotation, and scale values to the values represented in the Matrix3 value. If an Ease Curve has been assigned to a controller, the following controller-related sub-property is available:
<controller>.Ease_Curve Float -- the controllers ease curve value

If an Ease Curve has been assigned to a controller, the following controller-related sub-property is available:
<controller>.Multiplier_Curve Float -- the controllers multiplier curve value

See the Ease and Multiplier Curve Functions (p. 1297) topic for methods and notes related to ease and multiplier curves. Example:
globaltracks.float.mycontroller.value globaltracks.float.mycontroller.keys[2]

Associated Properties: All animatable properties in 3ds max objects let you reference several controller-related subproperties. These are:
<property>.controller <property>.track <property>.isAnimated <property>.keys ----the propertys controller a synonym for .controller a boolean indicating whether the property is animated read-only, gets the propertys controllers key array

The track property is a simple synonym for controller. If an animatable property does not yet have a controller assigned, the isAnimated property returns false and the controller, track, and keys properties return undefined.

1290

Chapter 11

3ds max Objects

Example:
$foo.pos.controller bend_mod1.angle.isAnimated $bar.taper.gizmo.scale.keys[2]

You create controllers as you do other 3ds max objects by calling the class as a function:
c = bezier_position()

and assign them to animatable properties by assigning to the controller property in those animatables. Example:
$foo.pos.controller = c $baz.bend.gizmo.rotation.controller = tcb_rotation() $box01.length = linear_float()

Methods:
getPointControllers {<editable_mesh_node> | <editable_spline_node>}

Returns an array of controllers assigned to the vertices in the mesh or spline. If no controller has been assigned to a vertex, the array element value will be undefined. For editable splines, each knot consists of 3 vertices: the in vector, the knot, and the out vector. The array of controllers returned is a snapshot of the current controllers. If controllers are assigned or changed for a vertex, this change is not reflected in the array. If a vertex is added/deleted, the array is not resized to reflect the change in number of vertices.
getPointController <editable_mesh_node> <vertex_index_integer>

Returns the controller currently assigned to the vertex, undefined if no controller assigned.
getPointController <editable_spline_node> <spline_index_integer> <vertex_index_integer>

Returns the controller for specified vertex in the specified spline, undefined if no controller assigned. Each spline knot consists of 3 vertices: the in vector, the knot, and the out vector. Note: Applying a controller to a property causes the controller to take on the properties value at frame 0. If keys are present for the controller before the assignment to the property, all keys will be adjusted by the difference between the controllers value at frame 0 and the propertys value. This is shown in the following example.

Wood : TextureMap

1291

Script:
a=bezier_float() addnewkey a 0 addnewkey a 10 a.keys[1].value=10 a.keys[2].value=100 b=box() b.height b.height.controller=a b.height at time 10 b.height

Output:
Controller:Bezier_Float #Bezier Float key(1 @ 0f) #Bezier Float key(2 @ 10f) 10 100 $Box:Box01 @ [0.0,0.0,0.0] 25.0 Controller:Bezier_Float 25.0 -- result line 115.0 -- result line -- result line 1 -- result line 2 -- result line 3 -- result line 4, key value at time 0 -- result line 5, key value at time 10 -- result line 6 -- result line 7, default property value -- result line 8 9, key value changed from 10 to 25 (delta= +15) 10, key value changed by delta = +15

A somewhat strange situation can arise when a single controller is assigned to multiple object properties. The value actually stored in a controller may not necessarily be the same value seen in Track View or in the command panels, nor the same value returned by accessing the property value in MAXScript. Part of a MAXWrapper property definition is scaling value that is applied when reading or setting the true value stored in a controller. For example, the slice_to and slice_from properties associated with many of the geometry primitives is displayed in degrees. The actual value stored in the controller associated with these properties are in radians. This scaling factor is an internal property of the MAXWrapper property, and not an internal property of the controller. Both 3ds max and MAXScript automatically apply the specified scaling factor when accessing properties, so this scaling is normally invisible to the user. If the same controller is assigned to two properties which have different scaling factors, the question arises as to which scaling factor to apply to the output of the controller. If you are accessing the controllers value through a MAXWrapper property, the scaling factor associated with that property is applied to the controllers value. MAXScript also internally stores the last scaling factor applied to the controllers value. If you are directly accessing the value property of the controller, or the value property of a key in the controller, the stored scaling factor is used. This can result in a controllers value property returning different values at different times in a script, based on how the controller was last accessed. Because of this, it is highly recommended that you do not instance a controller onto multiple MAXWrapper properties which have different scaling factors. The scaling factor, if any, is listed for each MAXWrapper property in the documentation of the MAXWrapper classes.

1292

Chapter 11

3ds max Objects

Methods:
displayControlDialog <controller> <string>

Displays the modal controller dialog, if any. The string will be in the dialog title bar. If the controller is a keyframe controller, the key info dialog will be displayed for the selected keys. If no keys are selected, no dialog will be displayed. Controllers that can be keyframed support several time and key-related functions, as described in the following topics: Controller Time Functions (p. 1292) Controller Key Functions (p. 1294) Controller Out-Of-Range Functions (p. 1296) Controller Ease and Multiplier Curve Functions (p. 1297) Controller Key Reducer (p. 1299)

See also
Key Common Properties, Operators, and Methods (p. 768) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Controller Time Functions

supportsTimeOperations <ctrl>

returns true or false depending on whether the controller supports the following time operations
deleteTime <controller> <interval> [ #incLeft ] [ #incRight ] [ #noSlide ]

Deletes an interval of time from the controller, removing all the keys with that interval and, by default, sliding the keys to the right of the interval to the left by the width of the interval. The optional symbolic arguments choose one of several options: #incLeft: includes any key exactly at the start time of the interval #incRight: includes any key exactly at the end time of the interval #noSlide: doesnt slide the later keys to fill in the gap removed- this effectively just deletes any keys in the interval. The <interval> argument can be specified as an Interval value or as two numbers or time values defining the start and end times. Number values are taken as frame numbers.
reverseTime <controller> <interval> [ #incLeft ] [ #incRight ]

Reverses time in the given interval, essentially swapping keys around so that their time placements are reversed within the interval. The notes on inclusion and interval arguments from deleteTime() apply.

Controller Time Functions

1293

scaleTime <controller> <interval> <float_scale>

Scales the times of the keys within the given interval. Again, the <interval> argument can be specified as an Interval value or as two numbers or time values defining the start and end times. Number values are taken as frame counts.
insertTime <controller> <at_time> <amount_time>

Inserts a block of time at the specified time, effectively moving all later keys out in time by the amount inserted. The times can be numbers or Time values. Numbers are taken as frame counts.
getTimeRange <controller> [ #selOnly ] [ #allKeys ] [ #children ]

Returns a time Interval value specifying the range of time covered by keys in the controller. The optional symbolic arguments specify options: #selOnly: return the time range covered by the currently selected keys (in the track view) #allKeys (default): the time range for all keys in the controller #children: descends into sub-controllers and returns the total time interval covering all keys in all sub-controllers
setTimeRange <controller> [ <interval> ] [ #linkToKeys ]

Sets the time range to be an interval other than that covered by existing keys, typically to influence when the out-of-range methods take over. If the optional #linkToKeys argument is given any keys exactly at the start or end of the given interval become anchors for the time range and moving them move the time range for the controller. If you call setTimeRange() with just the single argument, #linkToKeys, it will set the time range to the current start and end keys in all the controllers affected:
setTimeRange $box* #linkToKeys

This is equivalent to the Recouple Ranges function in the Position Ranges mode in Track View. Example: The following script shows example usages of some of the above methods. Script:
-- controller test bed 1 b=box height:10 at time 5 animate on b.height=50 at time 10 animate on b.height=100 bhc=b.height.controller bhk=bhc.keys supportstimeoperations bhc deletetime bhc 4 5 bhk deletetime bhc 4 5 #incLeft bhk deletetime bhc 1 4 #noslide bhk at time 5 animate on b.height=50 deletetime bhc (interval 5 8) #incLeft

1294

Chapter 11

3ds max Objects

bhk at time 10 animate on b.height=150 for k in bhk do format %:%\n k.time k.value reversetime bhc 5 15 #incLeft #incRight for k in bhk do format %:%\n k.time k.value insertTime bhc 12 5 bhk getTimeRange bhc

Controller Key Functions

addNewKey <controller> <time> [ #select ]

Adds a new key to the controller track at the time specified. The value for the new key is the interpolated controller value at the specified time. The new key is also selected if the #select optional argument is specified. The value for the new key is the interpolated controller value at that time. addNewKey() will not add a key if a key already exists at the specified time. The return value in this case is the key located at the specified time. This function returns a MAXKey value representing the key so you can set its various properties. See the Controller Key Functions (p. 1294) topic for details.
deleteKeys <controller> [ #allKeys ] [ #selection ]

Deletes keys from the controller according to the optional symbolic argument supplied. #allKeys (default): deletes all keys in the controller. #selection: deletes the currently selected keys
deleteKey <controller> <index>

Deletes the indexed key. Key indexes are 1-based.

selectKeys <controller> [ <interval> | <time> ]

Selects the specified keys in the track view. If an interval is given, all the keys within the interval are selected. If a single time is given, the key at that time is selected. If no time or interval is given, select all keys.
deselectKeys <controller> [ <interval> | <time> ]

Deselects specified keys. Arguments are as described in selectKeys().

selectKey <controller> <index_integer>

Selects the indexed key. Key indexes are 1-based.

isKeySelected <controller> <index_integer>

Returns true if indexed key is selected, false otherwise. Key indexes are 1-based.
deselectKey <controller> <index_integer>

Deselects the indexed key. Key indexes are 1-based.

moveKeys <controller> <time> [ #selection ]

Moves the specified keys by the time given. If #selection is specified, move the current selection otherwise move all keys.
moveKey <controller> <index_integer> <time>

Move the indexed key by the specified time.

Controller Key Functions

1295

numKeys <controller>

Returns the number of keys in the controller. Returns -1 if you call it on a controller that does not support keyframing.
getKey <controller> <index_integer>

Returns the indexed key as a MAXKey instance. See the Controller Key Functions (p. 1294) topic for MAXKey class information.
getKeyTime <controller> <index_integer>

Returns the time of indexed key.

getKeyIndex <controller> <time>

Returns the index of the key at the specified time.

numSelKeys <controller>

Returns the number of keys currently selected in the track view.

sortKeys <controller>

Re-sorts keys according to their times. Some MAXKey operations can result in out of order keys and this function must be called to correctly order keys. See the Controller Keys and Key Properties topic for MAXKey properties information.
createLockKey <controller> <time> <rot_or_pos_integer>

This method is called to create a locking key at the specified time. This is a key that looks back to the previous key and creates a new key at the specified time which matches the previous key in value. It also adjusts the parameters for the key such that the value stays constant from the previous key to this key. For instance, for a TCB controller the continuity of the previous key and new key will set to 0. For a Bezier controller the out tangent type of the previous key is set to linear and the in tangent type of the new key is set to linear. If the controller passed to this method is a transform level controller, <rot_or_pos_integer> specifies whether to create the key in the transform controllers position or rotation (or roll angle) sub-controller. If rot_or_pos_integer = 0, the key is created in the position controller. For all other values, the key is created in the rotation (or roll angle) controller. If the controller passed to this method is not a transform level controller, the <rot_or_pos_integer> value is not used. Returns true if the key creation was successful, false otherwise.

1296

Chapter 11

3ds max Objects

Example: The following script shows example usages of some of the above methods. Script:
-- controller test bed 2 b=box height:10 at time 5 animate on b.height=50 at time 10 animate on b.height=100 bhc=b.height.controller bhk=bhc.keys addnewkey bhc 7 addnewkey bhc 9 for k in bhk do format %:%\n k.time k.value selectKeys bhc (interval 7 9) deleteKeys bhc #selection bhk addnewkey bhc 7 addnewkey bhc 9 selectKeys bhc (interval 7 9) deleteKeys bhc #selection #slide bhk addnewkey bhc 7 addnewkey bhc 9 selectKeys bhc (interval 7 9) deleteKeys bhc #selection #slide #rightToLeft bhk addnewkey bhc 8 i=getKeyIndex bhc 8 selectKey bhc i moveKey bhc i 10 bhk getKeyTime bhc 4 b.width.controller=noise_float() numkeys b.width.controller

Controller Out-Of-Range Functions

getBeforeORT <controller>

Gets the Out-of-Range type (ORT) for the controller for the time before the first key. Returns one of the following name values:
#constant #cycle #loop #pingPong #linear #relativeRepeat getAfterORT <controller>

Gets the Out-of-Range (ORT) type for the controller for the time after the last key. Returns one of the name values as for getBeforeORT() shown above.

Controller Ease and Multiplier Curve Functions

1297

setBeforeORT <controller> <ORT_type_name>

Sets the Out-of-Range (ORT) type for the controller for the time before the first key. The <ORT_type_name> must be one of the following name values:
#constant #cycle #loop #pingPong #linear #relativeRepeat setAfterORT <controller> <ORT_type_name>

Sets the Out-of-Range (ORT) type for the controller for the time after the last key. The <ORT_type_name> must be one of the symbolic values shown in setBeforeORT() above. No testing done on the validity of <ORT_type_name> is performed.
enableORTs <controller> <boolean>

Enables or disables the Out-of-Range processing for the controller. If set to disabled with false, the controller effectively employs a constant ORT.

Controller Ease and Multiplier Curve Functions

addEaseCurve <controller> [ <float_controller> ]

Adds an ease curve to the specified controller. You may provide an optional float controller for the curve or have the function generate a default float controller for you. When you add a ease curve in Track View, keys are automatically created at the beginning and end of the current animation range. The addEaseCurve() method does not generate these keys, so you will need to add them to the ease curve controller.
deleteEaseCurve <controller> <index_integer>

Deletes the indexed ease curve from the controller. The indexes are 1-based and correspond to the order in which the curves were originally added to the controller.
numEaseCurves <controller>

Returns the number of ease curves currently operating on the controller.

applyEaseCurve <controller> <time>

Applies the combined ease curves in the specified controller to the given time value, returning the transformed time.
addMultiplierCurve <controller> [ <float_controller> ]

Adds a multiplier curve to the specified controller. You may provide an optional float controller for the curve or have the function generate a default float controller for you. When you add a ease curve in Track View, keys are automatically created at the beginning and end of the current animation range. The addMultiplierCurve() method does not generate these keys, so you will need to add them to the ease curve controller.
deleteMultiplierCurve <controller> <index_integer>

Deletes the indexed multiplier curve from the controller. The indexes are 1-based and correspond to the order in which the curves were originally added to the controller.

1298

Chapter 11

3ds max Objects

numMultiplierCurves <controller>

Returns the number of multiplier curves currently operating on the controller.

getMultiplierValue <controller> <time>

Returns the combined (float) value of the multiplier curves in the specified controller at the given time value. Associated Properties: If an Ease Curve has been assigned to a controller, the following controller-related sub-property is available:
<controller>.Ease_Curve -- the controllers ease curve value

If an Ease Curve has been assigned to a controller, the following controller-related sub-property is available:
<controller>.Multiplier_Curve -- the controllers multiplier curve value

Note: The values stored in an Ease Curve controller are stored as integer time ticks. Example: The following script shows example usages of some of the above methods. Script:
-- controller test bed 3 b=box height:10 at time 5 animate on b.height=50 at time 10 animate on b.height=100 bhc=b.height.controller ec=bezier_float() at time 0 animate on ec.value = 0 at time 100 animate on ec.value=100*ticksPerFrame setBeforeORT ec #linear setAfterORT ec #linear addEaseCurve bhc ec applyEaseCurve bhc 50 addEaseCurve bhc ec numEaseCurves bhc deleteEaseCurve bhc 2 numEaseCurves bhc at time 50 bhc.ease_curve.value mc=bezier_float() at time 0 animate on mc.value = 1 at time 100 animate on mc.value = 2 addMultiplierCurve bhc mc at time 50 bhc.multiplier_curve

Controller Key Reducer

1299

Controller Key Reducer

reduceKeys <controller> <threshold> <step> [ <range> ]

where <threshold> is the closeness that the key-reduced controller will match the original keys, <step> is the time step at which the controller will be sampled and <range> is an optional time range within which the keys are reduced given as either 2 time values or an Interval value, defaulting to the active animation range. Examples:
reduceKeys $foo.pos.controller 0.5 1f

reduce keys on foos position, retain 0.5 units accuracy, sample every frame.
reduceKeys $baz.bend.angle.controller 0.1 0.5f (interval 20 75)

Reduce keys on bazs bend angle, retain 0.1 units accuracy, sample every half frame, reduce within the interval 20f to 75f. As with the reducer in the track view, a progress bar and cancel button is displayed.

Time and Key Functions on Object Hierarchies

Certain of the controller time and key functions can be called on any 3ds max object or collection of 3ds max objects, not just individual controllers. If called in this way, they apply recursively to all the nested controllers within those objects and on any on sub-objects and sub-controllers within those objects. In this way, they work in a manner similar to the object-level tracks in the 3ds max Track View that allow you to manipulate keys and time for all the sub-objects and sub-controllers within them. The time and controller functions that work this way are:
deleteTime reverseTime scaleTime insertTime setTimeRange addNewKey deleteKeys selectKeys deselectKeys moveKeys sortKeys reduceKeys addEaseCurve deleteEaseCurve setBeforeORT setAfterORT enableORTs

1300

Chapter 11

3ds max Objects

The above functions can be called on any 3ds max object collection (such as a wild-card pathname or object set or array of objects ) and will recursively apply to all animation within those objects. If they are called on components within an object that themselves have nested controllers, they are applied to all those nested controllers - see the examples below. Examples:
insertTime $box01.xform 0f 10f

all keys after 0f in all controllers in the xform modifier are moved by 10f
insertTime $box01 0f 10f

all keys after 0f in box01 are moved (transform, creation, modifiers)

selectKeys $box02.xform.gizmo.rotation.controller 0f 100f

selects keys in 0-100f, if controller is Euler, e.g., will select x, y and z keys
deleteTime $box* 10f 10f

delete 10f at frame 10 in all keys in all objects named $box* (works with any pathname or array of objects)
insertTime $box03.children 0f 10f

inserts time in all controllers of all children of $box03

reduceKeys $box01.modifiers 0.5 1f

applies key reductions to all controllers in all modifiers in $box01 (leaves transform and creation parameters alone)

Controller Types
Controllers - Superclass Level
The following is a list of the controller superclasses: FloatController (p. 1301) Matrix3Controller (p. 1302) MorphController (p. 1302) Point3Controller (p. 1302) PositionController (p. 1303) RotationController (p. 1303) ScaleController (p. 1304) QuatController (p. 1304) MasterBlockController (p. 1301)

FloatController : MAXWrapper

1301

FloatController : MAXWrapper
FloatController is the superclass for all controllers that can be assigned to parameters that are simple numbers (Float or Integer). The following is a list of the core FloatController classes accessible in MAXScript: AudioFloat (p. 1306) Bezier_Float (p. 1309) Block (p. 1311) Float_Expression (p. 1313) Float_List (p. 1317) Float_Motion_Capture (p. 1321) Float_Reactor (p. 1326) Float_Script (p. 1329) Linear_Float (p. 1315) LOD_Controller (p. 1319) Noise_Float (p. 1322) On_Off (p. 1323) SlaveFloat (p. 1333) TCB_Float (p. 1334) Waveform_Float (p. 1335)

MasterBlockController : MAXWrapper
MasterBlockController is the superclass for the controllers associated with the Block Control Track View node. These classes are: Block_Control (p. 1311) MasterBlock (p. 1320)

1302

Chapter 11

3ds max Objects

Matrix3Controller : MAXWrapper
Matrix3Controller is the superclass for all controllers that can be assigned to transform or Position-Rotation-Scale parameters. The following is a list of the core Matrix3Controller classes accessible in MAXScript: Link_Control (p. 1316) LookAt (p. 1319) PRS (p. 1325) IK_ControllerMatrix3Controller (p. 1313) Slave_Controller (p. 1333)

MorphController : MAXWrapper
MorphController is the superclass for all controllers that can be assigned to morph objects. The following is a list of the core MorphController classes accessible in MAXScript: Barycentric_Morph_Controller (p. 1306) Cubic_Morph_Controller (p. 1312)

Point3Controller : MAXWrapper
Point3Controller is the superclass for all controllers that can be assigned to Point3 parameters. The following is a list of the core Point3Controller classes accessible in MAXScript: AudioPoint3 (p. 1306) Bezier_Color (p. 1309) Bezier_Point3 (p. 1309) Color_RGB (p. 1335) Noise_Point3 (p. 1322) Point3_Expression (p. 1313) Point3_List (p. 1317) Point3_Motion_Capture (p. 1321) Point3_Reactor (p. 1326) Point3_Script (p. 1329) Point3_XYZ (p. 1335) Slave_Point3 (p. 1333) TCB_Point3 (p. 1334)

PositionController : MAXWrapper

1303

PositionController : MAXWrapper
PositionController is the superclass for all controllers that can be assigned to position parameters. The following is a list of the core Point3Controller classes accessible in MAXScript: Attachment (p. 1304) Audioposition (p. 1306) Bezier_Position (p. 1309) Dynamic_Position_Controller (p. 1312) Linear_Position (p. 1315) Noise_Position (p. 1322) Path (p. 1324) Position_Expression (p. 1313) Position_List (p. 1317) Position_Motion_Capture (p. 1321) Position_Reactor (p. 1326) Position_Script (p. 1329) Position_XYZ (p. 1335) Surfaceposition (p. 1334) TCB_Position (p. 1334)

RotationController : MAXWrapper
RotationController is the superclass for all controllers that can be assigned to rotation parameters. The following is a list of the core RotationController classes accessible in MAXScript: AudioRotation (p. 1306) Bezier_Rotation (p. 1309) Dynamics_Rotation_Controller (p. 1312) Euler_XYZ (p. 1335) Linear_Rotation (p. 1315) Local_Euler_XYZ (p. 1335) Noise_Rotation (p. 1322) Rotation_List (p. 1317)

1304

Chapter 11

3ds max Objects

Rotation_Motion_Capture (p. 1321) Rotation_Reactor (p. 1326) Rotation_Script (p. 1329) SlaveRotation (p. 1333) TCB_Rotation (p. 1334)

ScaleController : MAXWrapper
ScaleController is the superclass for all controllers that can be assigned to scale parameters. The following is a list of the core ScaleController classes accessible in MAXScript: AudioScale (p. 1306) Bezier_Scale (p. 1309) Linear_Scale (p. 1315) Noise_Scale (p. 1322) Scale_Expression (p. 1313) Scale_List (p. 1317) Scale_Motion_Capture (p. 1321) Scale_Reactor (p. 1326) Scale_Script (p. 1329) ScaleXYZ (p. 1335) SlaveScale (p. 1333) TCB_Scale (p. 1334)

QuatController : MAXWrapper
There are presently no classes associated with the QuatController superclass.

Attachment : PositionController
Constructor:
attachment ...

Properties:
<attachment>.keys <attachment>.node <attachment>.align : MAXKeyArray : Node : Booleandefault: true

Fixes the orientation of the attached object to the face where its assigned. When this is turned off, the orientation of the attached object is not affected by the orientation of the face on the target object.

Attachment Controller Keys

1305

<attachment>.manupdate

: Booleandefault: false

Enables the update button. Methods:

AttachCtrl.getKey <attachment> <index_integer>

Returns the indexed key as a MAXAKey value

AttachCtrl.addNewKey <attachment> <time>

Returns the indexed key as a MAXAKey value

AttachCtrl.update <attachment>

Causes the controller to update if the manual update property is turned on for the attachment controller. Note: Accessing a key for these controllers by indexing into the .keys property will return a MAXKey value. The only properties available for a key accessed in this manner are the .time and .selected properties. The AttachCtrl.getKey() method returns a key of class MAXAKey, which provides access to the attachment controller key specific properties. All the common key functions like deleteKey, selectKeys, movekeys, etc. can be used with Attachment controllers.

See also
MAXKeyArray Values (p. 793) Attachment Controller Keys (p. 1305) Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Attachment Controller Keys

Properties: For Attachment controller keys, the following properties are accessible:
<key>.time <key>.selected : Time (time value or number [interpreted as frames]) Read-only. : Boolean

Specifies whether the key is selected. Read/write access. The AttachCtrl.getKey() method returns keys of class MAXAKey. These keys have the following properties:
<MAXAKey>.face <MAXAKey>.coord <MAXAKey>.time <MAXAKey>.selected <MAXAKey>.tension <MAXAKey>.continuity <MAXAKey>.bias <MAXAKey>.easeTo <MAXAKey>.easeFrom : : : : : : : : : Integer (0-based) Point2 (barycentric coordinates) Time Boolean Float Float Float Float Float

1306

Chapter 11

3ds max Objects

See also
Key Common Properties, Operators, and Methods (p. 768) Value Common Properties, Operators, and Methods (p. 714)

Audio Controllers
audiofloat : floatController audiopoint3 : point3Controller audioposition : positionController audiorotation : rotationController audioscale : scaleController Constructor:
audiofloat ... audiopoint3 ... audioposition ... audiorotation ... audioscale ...

Properties: There are no additional properties accessible for Audio controllers.

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Barycentric_Morph_Controller : MorphController
You access the morph controller on a morph compound object via the <node>.morph property, for example:
c = $foo.morph mk1 = c.keys[1] -- get the morph controller -- get the first morph key

Constructor:
createMorphObject <source_node>

Turns the given scene node into a Morph compound object - does nothing if it already is a Morph object. The returned morph object has a morph controller created accessible via the morph property.

Barycentric_Morph_Controller : MorphController

1307

Methods:
addMorphTarget <morph_controller> <target_node> <add_method>

Adds a new morph target object to the given morph controller. The <add_method> argument defines the method of attaching the target and should be a number between 1 and 4 with the following interpretation:
1 2 3 4 ----by by by by reference copy move instance

The return value is an Integer giving the target index of the added target object.
setMorphTarget <morph_controller> <target_index_integer> <target_node> <add_method>

Replaces an existing target with a different scene node. The arguments are the same as for addMorphTarget().
getMKTargetNames <morph_controller>

Returns an array of names of the targets in the given morph controller.

deleteMorphTarget <morph_controller> <target_index_integer>

Deletes the numbered morph target in the given controller.

setMorphTargetName <morph_controller> <target_index_integer> <name_string>

Changes the target name of the numbered target in the given morph controller.
getMKTargetWeights <morph_controller> <time> <dest_array>

A quick way of retrieving all the target weights for a given key at the time specified. The targets are placed into <dest_array> which must be an array of the right size. You can find out how many targets there by getting the size of the array returned by the getMKTargetNames() function which returns an array of target names.
getMKKey <morph_controller> <time>

Returns the morph key on the given controller at the specified time, yields undefined if there is no key at that time.
getMKKeyIndex <morph_controller> <time>

Returns the index of the key at the specified time, yields undefined if there is no key at that time. Note: When using the addnewkey() method to create a key for the Barycentric_Morph_Controller controller, the time component of the key value returned is usually not correct. Use the getMKKey() method to access the created key.

1308

Chapter 11

3ds max Objects

See also
Barycentric_Morph_Controller Keys (p. 1308) Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Barycentric_Morph_Controller Keys
Note: This class is not available in 3D Studio VIZ. The morph key functions operate on MAXScript key values that are accessed on Barycentric morph controllers in the same way as keys on other keyable controllers. For Barycentric_Morph_Controller keys, the following properties and methods are accessible: Properties:
<key>.time only. <key>.selected access. Time Boolean -- time value or number (interpreted as frames). Read-- specifies whether the key is selected. Read/write

Methods:
getMKTime <morph_key>

Returns the given morph keys time.

setMKTime <morph_key> <time>

Sets the time of the given morph key.

getMKWeight <morph_key> <target_index_integer>

Gets the weight as a percentage for the numbered target on the given morph key. Targets are numbered in order as seen in the target list in the morph key Track View dialog. This is the order in which the targets were added.
setMKWeight <morph_key> <target_index_integer> <pcnt_float> <keep100%_boolean>

Sets the percentage weight of the numbered target on the given morph key. The last argument is a boolean, if true adjusts other target weights so the maximum is 100%. Note: When using the addnewkey() method to create a key for the Barycentric_Morph_Controller controller, the time component of the key value returned is usually not correct. Use the getMKKey() method to access the created key.

See also
Key Common Properties, Operators, and Methods (p. 768) Value Common Properties, Operators, and Methods (p. 714)

Bezier Controllers

1309

Example: Script:
sel1 = sphere radius:30 sel2 = sphere radius:50 createMorphObject sel1 mobj1= sel1.morph addmorphtarget mobj1 sel2 3 k=mobj1.keys[1] setMKWeight k 1 100 true addnewkey mobj1 50 k=getMKKey mobj1 50 setMKWeight k 2 100 true -----------target 1 target 2 create the morph object from sel1 grab morph controller add sel2 as target - creates key with target weights of 0 and 100% grab the key set target 1 to 100%, keep total 100% create morph key at frame 50 grab the key set target 2 to 100%, keep total 100%

Output:
$Sphere:Sphere01 @ [0.0,0.0,0.0] $Sphere:Sphere02 @ [0.0,0.0,0.0] $Editable_Mesh:Sphere01 @ [0.0,0.0,0.0] Controller:Barycentric_Morph_Controller 2 #Barycentric Morph Controller key(1 @ 0f) 1 #Barycentric Morph Controller key(0 @ 50f) #Barycentric Morph Controller key(2 @ 50f) 2 ---------result result result result result result result result result line line line line line line line line line 1 2 3 4 5 7 8 9 10

Bezier Controllers
bezier_color : point3Controller bezier_float : floatController bezier_point3 : point3Controller bezier_position : positionController bezier_rotation : rotationController bezier_scale : scaleController Constructor:
bezier_color ... bezier_float ... bezier_point3 ... bezier_position ... bezier_rotation ... bezier_scale ...

Properties:
<bezier_controller>.keys MAXKeyArray

1310

Chapter 11

3ds max Objects

See also
MAXKeyArray Values (p. 793) Bezier Controller Keys (p. 1310) Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Bezier Controller Keys

For Bezier controller keys, the following properties are accessible: Properties:
<key>.time <key>.selected <key>.value <key>.inTangent <key>.outTangent <key>.inTangentType <key>.outTangentType <key>.x_locked <key>.y_locked <key>.z_locked <key>.constantVelocity Time Boolean varies varies varies Name Name Boolean Boolean Boolean Boolean -- time value or number (interpreted as frames) -- specifies whether the key is selected -- class determined by its containing controller -- float or point3 (see below) -- float or point3 (see below) -- see list of permitted names below -- see list of permitted names below default: true default: true default: true default: false

The inTangent and outTangent values are Floats in keys of float controllers and Point3s for the other appropriate controllers. Default value is 0 for float controllers, [0,0,0] otherwise. The inTangentType and outTangentType properties have symbolic name values representing the 6 possible tangent types available in the drop-down menu in the Bezier key property dialog:
#smooth (default) #linear #step #fast #slow #custom

See also
Key Common Properties, Operators, and Methods (p. 768) Value Common Properties, Operators, and Methods (p. 714)

Block : FloatController

1311

Examples:
c = bezier_position () $bar.pos.controller = c k = addNewKey c 0f k.value = [10,0,0] k.outTangentType = #slow k = addNewKey c 100f k.value = [200,10,0] k.inTangentType = #custom k.inTangent = [0.2, 0.02, 0.112] k.x_locked = false -- create and assign new controller

-- add a key at frame 0 -- set value there -- and outgoing tangent type -----add another key at 100 set value make inTangent custom set its tangents and unlock handles

Block : FloatController
Constructor: The Block controller is not creatable by MAXScript. It can only be created by creating a Masterblock in the Block Control node in the Global Tracks node of Track View. See the MasterBlock : MasterBlockController (p. 1320) topic for more information.

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Block_Control : MasterBlockController
Constructor: The Block_Control controller is not creatable by MAXScript. Only one instance of the class exists in 3ds max - the Block Control node in the Global Tracks node of Track View. See the MasterBlock : MasterBlockController (p. 1320) topic for more information.

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1312

Chapter 11

3ds max Objects

Cubic_Morph_Controller : MorphController
The Barycentric_Morph_Controller (p. 1306) should be used instead of a Cubic_Morph_Controller controller. Constructor:
Cubic_Morph_Controller ...

Note: This class is not available in 3D Studio VIZ. Properties:

<Cubic_Morph_Controller>.keys MAXKeyArray

See also
MAXKeyArray Values (p. 793) Cubic_Morph_Controller Keys (p. 1312) Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Cubic_Morph_Controller Keys
Properties: For Cubic_Morph_Controller keys, the following properties are accessible:
<key>.time only. <key>.selected access. Time Boolean -- time value or number (interpreted as frames). Read-- specifies whether the key is selected. Read/write

See also
Key Common Properties, Operators, and Methods (p. 768) Value Common Properties, Operators, and Methods (p. 714)

Dynamics Controllers
Dynamics_Position_Controller : positionController Dynamics_Rotation_Controller : rotationController Constructor: The Dynamics controllers are created by the Dynamics utility, and are not creatable in MAXScript. Note: These classes are not available in 3D Studio VIZ.

Expression Controllers

1313

Properties: When you solve a dynamics solution in the Dynamics utility, the Dynamics controllers are assigned as the position and rotation controllers of all objects not flagged as unyielding. These controllers are similar to List controllers in that they contain multiple sub-controllers. The first sub-controller is a Bezier controller of the appropriate type that contains the keys generated while solving the dynamics solution. This controller can be accessed as the Dynamic_position_controller or Dynamic_rotation_controller property of the dynamics controller. The second sub-controller is the original position or rotation controller assigned to the object, and can be accessed as the old_position or old_position property.

Expression Controllers
float_expression : floatController point3_expression : point3Controller position_expression : positionController scale_expression : scaleController Constructor:
float_expression ... point3_expression ... position_expression ... scale_expression ...

Note: These classes are not available in 3D Studio VIZ. Properties: There are no additional properties accessible for Expression controllers.

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

IK_ControllerMatrix3Controller : Matrix3Controller
The functions described in this topic provide access to some of the Inverse Kinematics (IK) parameters of the IK controller. The IK controller is typically used by the Bones system in 3ds max. You cannot create a Bones system using MAXScript in 3ds max 3, but these methods provide access to the IK controller for existing Bones systems. An IK system actually consists of two types of controllers the master IK controller and slave IK controllers. The slave IK controllers are used as the transform controller for all nodes in the IK system, and the master IK controller controls the individual slave IK controllers.

1314

Chapter 11

3ds max Objects

All the IK-related methods are in the ik structure and are associated with a parameter in the Motion panel, IK Controller Parameters rollout. These functions return undefined if executed on an object whose controller is not an IK controller. The controller actually being accessed in these methods is the master IK controller. Accessing the IK controller for any object in the IK system accesses the same master IK controller. Note: The following ik structure methods are still present, but not applicable in 3ds max 4. Getting/setting via these methods return a value of undefined:
GetRotThreshold SetRotThreshold GetPosThreshold SetPosThreshold GetIterations SetIterations ik.GetPosThreshold <node> ik.SetPosThreshold <node> <float>

Get and set the Position threshold value for the specified object.
ik.GetRotThreshold <node> ik.SetPosThreshold <node> <float>

Get and set the Rotation threshold value for the specified object.
ik.GetIterations <node> ik.SetIterations <node> <integer>

Get and set the Iterations value for the specified object.
ik.GetStartTime <node> ik.SetStartTime <node> <time>

Get and set the Start time for the specified object
ik.GetEndTime <node> ik.SetEndTime <node> <time>

Get and set the End time for the specified object
ik.getPinNode <node>

Gets the node the specified node is bound to in the IK panel as a <node> value, undefined if none.
ik.setPinNode <node> (<node> | undefined)

Sets the node the specified node is bound to in the IK panel. If undefined is specified, the node is unbound. Returns true if the bind was successful, false otherwise.
ik.getPrecedence <node>

Gets the precedence of the node as specified in the IK panel as an <integer> value
ik.setPrecedence <node> <number>

Sets the precedence of the node as specified in the IK panel. Returns true if the assignment was successful, false otherwise.
ik.getIsTerminator <node> ik.setIsTerminator <node> <boolean>

Get/set whether the node is a terminator.

Linear Controllers

1315

ik.getBindPos <node> ik.setBindPos <node> <boolean>

Get/set whether Bind Position is turned on for the node.

ik.getBindOrient <node> ik.setBindOrient <node> <boolean>

Get/set whether Bind Orientation is turned on for the node.

Linear Controllers
linear_float : floatController linear_position : positionController linear_rotation : rotationController linear_scale : scaleController Constructor:
linear_float ... linear_position ... linear_rotation ... linear_scale ...

Properties:
<controller>.keys MAXKeyArray

See also
MAXKeyArray Values (p. 793) Linear Controller Keys (p. 1315) Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Linear Controller Keys

For Linear controller keys, the following properties are accessible: Properties:
<key>.time <key>.selected <key>.value Time Boolean varies -- time value or number (interpreted as frames) -- specifies whether the key is selected -- class determined by its containing controller

See also
Key Common Properties, Operators, and Methods (p. 768) Value Common Properties, Operators, and Methods (p. 714)

1316

Chapter 11

3ds max Objects

Link_Control : Matrix3Controller
Constructor:
link_control ...

Properties:
<link_control>.transform Matrix3Controller

Contains the transform controller below the link controller Methods:

linkCtrl.getLinkCount <link_control>

Returns the number of nodes linked to as an integer.

linkCtrl.getLinkNode <link_control> <index_integer>

Returns the node for the indexed link as a node value.

linkCtrl.setLinkNode <link_control> <index_integer> <node>

Sets the node for the indexed link. The indexed link must already exist.
linkCtrl.getLinkTime <link_control> <index_integer>

Returns the time for the indexed link as a time value.

linkCtrl.setLinkTime <link_control> <index_integer> <time>

Sets the time for the indexed link. The indexed link must already exist.
linkCtrl.addLink <link_control> <node> <time>

Adds the specified node as a link with the specified time.

linkCtrl.deleteLink <link_control> <index_integer>

Deletes the indexed link.

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

List Controllers

1317

List Controllers
float_list : floatController point3_list : point3Controller position_list : positionController rotation_list : rotationController scale_list : scaleController Constructor:
float_list ... point3_list ... position_list ... rotation_list ... scale_list ...

Properties: The property list for a list controller contains the sub-controllers in the list controller (if any), plus an available property. The available property has a controller property, which contains a phantom controller. To add a controller to a list controller, assign the controller to the available.controller property. The following script shows an example of creating and adding controllers to a list controller. Script:
p=float_list() showproperties p p.available.controller p1=bezier_float() p.available.controller=p1 p2=bezier_float() p.available.controller=p2 getpropnames p showproperties p p.numSubs getsubanimnames p p[2].object ------------create a list controller show its properties the phantom controller create a new bezier float controller add it to the list controller create a new bezier float controller add it to the list controller show the list controller properties show the list controller properties the number of list controller subAnims show the list controller subAnim names retrieve the second bezier float controller

Output:
Controller:Float_List .available : float OK Controller: Controller:Bezier_Float Controller:Bezier_Float Controller:Bezier_Float Controller:Bezier_Float #(#bezier_float, #available) .bezier_float : float .bezier_float : float .available : float ------------result output result result result result result result result output output output line line line line line line line line line line line line 1 2 2 3 (the phantom controller) 4 5 6 7 8 9 9 9

1318

Chapter 11

3ds max Objects

OK -- result line 9 3 -- result line 10 #(#bezier_float, #bezier_float, #available) -- result line 11 Controller:Bezier_Float -- result line 12

In line 9 of the output, only one occurrence of #bezier_float is shown. The reason for this is this is that multiple properties with the same name are not shown by MAXScript. This is because all property names are normally supposed to be unique. In the case of list controllers, this is not true. Instead of accessing the controllers added to a list controller as properties of the list controller, the controllers should be accessed through the subAnims of the list controller as shown in the last line of the example. There currently is not a method for removing a controller from a list controller. To easiest way to accomplish this is to create a new list controller, instance all other sub-controllers from the original list controller, and then replace the original list controller with the new list controller. The following script shows a example which performs these actions. Script:
--fn ( -------creates new list controller from old, deleting indexed controller returns the new controller deleteFromListController list_cont index = create new list controller based on class of input list controller new_cont=execute ((classof list_cont as string) + ()) for each subAnim (except the last, which is the phantom available controller).. for i=1 to (list_cont.numSubs-1) do if not the sub-controller to delete if i != index do instance the sub-controller (contained in the .object property of the subAnim) to the new list controller new_cont.available.controller=list_cont[i].object and return the new list controller return new_cont

) --- example usage (obj.pos already has list controller) obj.pos.controller = deleteFromListController obj.pos.controller 2

Methods:
listCtrl.getName <list_controller> <index_integer>

Returns the name of the indexed subcontroller in the list controller

listCtrl.setName <list_controller> <index_integer> <string>

Sets the name of the indexed subcontroller in the list controller. If the string is a null string (), the default controller name is used.

LOD_Controller : FloatController

1319

listCtrl.getActive <list_controller>

Returns the index of the active subcontroller in the list controller

listCtrl.setActive <list_controller> <index_integer>

Sets the indexed subcontroller in the list controller as the active controller

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

LOD_Controller : FloatController
Constructor: The LOD_Controller controller is not creatable by MAXScript. It can only be created using the Level of Detail utility. Properties: There are no additional properties for LOD_Controller.

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

LookAt : Matrix3Controller
Constructor:
lookat ...

Properties:
<lookAt>.position <lookAt>.roll_angle <lookAt>.scale Bezier_Position Bezier_Float Bezier_Scale -- the position controller -- the roll controller -- the scale controller

1320

Chapter 11

3ds max Objects

There presently are no methods for directly accessing or setting the target node in the LookAt controller. To set the target node, the LookAt controller needs to be assigned to a node, and then the lookat property of the node is set to the target node. If the transform controller for a node is not a LookAt controller, and a target node is assigned to the lookat property of the node, a LookAt controller is automatically assigned to the node. For example,
$box01.lookat=$box02

is equivalent to
$box01.transform.controller=lookat() $box01.lookat=$box02

Note: The following properties are not accessible by MAXScript in 3ds max 4 the Axis radio-button and the Flip checkbox.

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

MasterBlock : MasterBlockController
Constructor: The MasterBlock controller is not creatable by MAXScript. It can only be created in the Block Control node in the Global Tracks node of Track View. If multiple MasterBlocks are present, you will need to access the MasterBlocks as a subAnim of trackviewnodes.global_tracks. block_control. This is because all MasterBlocks have the same name (MasterBlock). Properties: Once a MasterBlock has been created in Track View, the following MasterBlock property is available:
<MasterBlock>.blend Float

Once a track has been added to the MasterBlock, a Block controller is added to the MasterBlock, and the tracks controller is added as an input controller to the Block controller. The name assigned to the Block controller is the name specified for the block. The Block controller is then available as a property of the MasterBlock, and the tracks controller is available as a property of the Block controller. In addition, the tracks controller is replaced with a list controller and the tracks original controller is placed in the list controller along with a Slave controller. This Slave controller is controlled by the Block controller. For example, if a block with name BoxHeight is present, and contains the height controller for a box object, the block and its track can be accessed as follows:

Motion Capture Controllers

1321

mb=trackviewnodes.global_tracks.block_control[1] -- SubAnim:MasterBlock getpropnames mb -- #(#Blend, #height) h=mb.height -- SubAnim:height h.object -- Controller:Block getpropnames h -- #(#Box01_Height) h.box01_height -- 157.083 - the boxs height h.box01_height.controller -- Controller:Bezier_Float - the boxs height controller

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Motion Capture Controllers

float_motion_capture : floatController point3_motion_capture : point3Controller position_motion_capture : positionController rotation_motion_capture : rotationController scale_motion_capture : scaleController Constructor:
float_motion_capture ... point3_motion_capture ... position_motion_capture ... rotation_motion_capture ... scale_motion_capture ...

Note: These classes are not available in 3D Studio VIZ. Properties:

<motion_capture>.data Controller

The data controller type depends on the motion controller data type. The controller is typically a Bezier controller. There are presently no properties or methods associated with the motion capture controllers themselves.

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1322

Chapter 11

3ds max Objects

Noise Controllers
noise_float : floatController noise_point3 : point3Controller noise_position : positionController noise_rotation : rotationController noise_scale : scaleController Constructor:
noise_float ... noise_point3 ... noise_position ... noise_rotation ... noise_scale ...

Properties: Access to the following properties is available on all noise controllers:

<noise_controller>.seed <noise_controller>.frequency <noise_controller>.fractal <noise_controller>.roughness <noise_controller>.rampin <noise_controller>.rampout Integer Float Boolean Float Time Time default: default: default: default: default: default: 0 0.5 true 0.0 0f 0f

In addition, for noise float controllers you can get these properties:
<noise_controller>.noise_strength <noise_controller>.positive Float Boolean default: 50 default: false -- animatable

limits values to > 0 and for noise position, point3, rotation and scale controllers:
<noise_controller>.noise_strength Point3 default: varies -- animatable position and point3 default: [50,50,50] rotation default: [0.785398,0.785398,0.785398] scale default: [0.5,0.5,0.5] <noise_controller>.x_positive <noise_controller>.y_positive <noise_controller>.z_positive Boolean Boolean Boolean default: false default: false default: false

limits values to > 0

On_Off : FloatController

1323

Note: You need to access these properties explicitly on a controller, for example:
$box01.position.controller.x_strength = 100

or,
c = $box01.rotation.controller c.seed = random 0 100 c.fractal = off c.frequency = random 0.1 0.2

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

On_Off : FloatController
Constructor:
on_off ...

Properties:
<on_off>.keys MAXKeyArray

See also
MAXKeyArray Values (p. 793) On_Off Controller Keys (p. 1323) Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

On_Off Controller Keys

Properties: For On_Off keys, the following properties are accessible:
<key>.time only. <key>.selected access. Time Boolean -- time value or number (interpreted as frames). Read-- specifies whether the key is selected. Read/write

1324

Chapter 11

3ds max Objects

See also
Key Common Properties, Operators, and Methods (p. 768) Value Common Properties, Operators, and Methods (p. 714)

Path : PositionController
Constructor:
path ...

Properties:
<path>.allowUpsideDown Boolean default: false -- alias: Allow_Upside_Down

Turn on to avoid the situation in which an object flips when going around a vertically oriented path.
<path>.axis Integer Boolean Boolean Float default: 0 default: false default: false default: 0.5 -- animatable, alias: -- alias: Axis_Flip

axis = 0 - X; 1 - Y; 2 - Z
<path>.axisFlip <path>.bank <path>.bankAmount Bank_Amount

Flips the direction of the object on the path 180 degrees. Allows the object to bank (roll) as it negotiates the curves of the spline.

The amount of the banking to one side or the other, depending on whether the value is positive or negative.
<path>.constantVel Boolean default: false -- alias: Constant_Velocity

Provides a constant velocity along the path. When off, the velocity of the object along the path varies depending on the distance between the vertices on the path.
<path>.follow <path>.loop Booleandefault: false Boolean default: false -boolean

Aligns the object to the trajectory as it follows the contour. When turned on, the path controlled object will loop back to the start point of the path, after the end point is reached.
<path>.path <path>.pathlist Node Array default: undefined - node; Path_Constraint default: #() -node array; SubAnim

The spline in the scene that you want the selected object to follow. The object will follow the resultant path which is the weighted average of the paths in this array. The weight for each path is found in the corresponding entry in <path>.weightlist.
<path>.percent <path>.relative Floatdefault: 0.0 Boolean default: false -- animatable, percentage -booleanExample

The percent that the object is positioned along the path. When turned on, the path controlled object will maintain the position offset between its initial position and the start point of the path.

PRS : Matrix3Controller

1325

<path>.smoothness

Float

default: 0.5

-- animatable

Controls how rapidly the roll angle changes as the object moves through bends in the trajectory. Smaller values will make the object more responsive to subtle changes in the curve, while larger values smooth out jerking. The default value is a good value for general damping along the curve. Values below 2 tend to make the action jerky, but values around 3 can be very useful for simulating a certain degree of realistic instability.
<path>.weightlist Array default: #() -float array; Weight; SubAnim

Array containing weights corresponding to entries in the <path>.pathlist array. The object will follow the resultant path which is the weighted average of the selected paths. The following script shows an example of assigning and animating a path controller. Script:
thePath=circle radius:50 theObj=cone radius1:6 radius2:0 height:15 theObj.pos.controller=path follow:true PosCont=theObj.pos.controller PosCont.path=thePath PosCont.axis=2 animate on ( at time 30 PosCont.percent=25 at time 100 PosCont.percent=95 ) ---------create shape node for path create object to travel on path assign path controller to object grab the path controller set path to shape node point local Z axis along path create keys at frame 30 - 25% along path frame 100 - 95% along path

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

PRS : Matrix3Controller
Constructor:
prs ...

Properties:
<prs>.position <prs>.rotation <prs>.scale Bezier_Position TCB_Rotation Bezier_Scale -- the position controller -- the rotation controller -- the scale controller

Note: You can assign a Matrix3 value to a PRS controllers value property. MAXScript will automatically set the individual position, rotation, and scale values to the values represented in the Matrix3 value.

1326

Chapter 11

3ds max Objects

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Reactor Controllers
float_Reactor : floatController point3_Reactor : point3Controller position_Reactor : positionController rotation_Reactor : rotationController scale_Reactor : scaleController Constructor:
float_Reactor ... point3_Reactor ... position_Reactor ... rotation_Reactor ... scale_Reactor ...

Methods:
createReaction <reactor_controller>

Creates a new reaction for the specified reactor controller.

deleteReaction <reactor_controller> <index_integer>

Deletes the specified reaction. <index_integer> is the reaction you want to delete. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.
reactTo <reactor_controller> ( <controller> | <node> )

Sets the controller that the reactor controller reacts to. You can either specify either a controller you want to react to or a node whose world position to react to.
getReactionCount <reactor_controller>

Returns the number of reactions for the specified reactor controller.

selectReaction <reactor_controller> <index_integer>

Selects the specified reaction. <index_integer> is the reaction you want to select. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.
getSelectedReactionNum <reactor_controller>

Returns the number of the selected reaction.

getReactionFalloff <reactor_controller> <index_integer>

Returns the specified reactions falloff. <index_integer> is the reaction you want to get the falloff from. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.

Reactor Controllers

1327

setReactionFalloff <reactor_controller> <index_integer> <float>

Sets the specified reactions falloff to the specified value. <index_integer> is the reaction you want to set the falloff for. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.
getReactionInfluence <reactor_controller> <index_integer>

Returns the specified reactions influence. <index_integer> is the reaction you want to get the influence from. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.
setReactionInfluence <reactor_controller> <index_integer> <float>

Sets the specified reactions influence to the specified value. <index_integer> is the reaction you want to set the influence for. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.
getReactionStrength <reactor_controller> <index_integer>

Returns the specified reactions strength. <index_integer> is the reaction you want to get the strength from. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.
setReactionStrength <reactor_controller> <index_integer> <float>

Sets the specified reactions strength to the specified value. <index_integer> is the reaction you want to set the strength for. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.
getReactionState <reactor_controller> <index_integer>

Returns the specified reactions state. The value type returned matches the reactor controller type. <index_integer> is the reaction you want to get the state from. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.
setReactionState <reactor_controller> <index_integer> <value>

Sets the specified reactions state to the specified value. <index_integer> is the reaction you want to set the state for. The order of reactions is the order in which they are created, and the order in which the reactions are listed in. The <value> type must match the reactor controller type.
getReactionValue <reactor_controller> <index_integer>

Returns the specified reactions value. The return value type is the same as the controller type being reacted to. <index_integer> is the reaction you want to get the value from. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog.
setReactionValue <reactor_controller> <index_integer> <value>

Sets the specified reactions value to the specified value. <index_integer> is the reaction you want to set the value for. The order of reactions is the order in which they are created, and the order in which the reactions are listed in. The <value> type must match the controller type being reacted to.

1328

Chapter 11

3ds max Objects

setReactionName <reactor_controller> <index_integer> <string>

Sets the name of the specified reaction. <index_integer> is the reaction you want to set the name for. The order of reactions is the order in which they are created, and the order in which the reactions are listed in.
getReactionName <reactor_controller> <which>

Returns the specified reactions name. <index_integer> is the reaction you want to get the name of. The order of reactions is the order in which they are created, and the order in which the reactions are listed in the Reactor Parameters dialog. Script:
-- Setup a scene b1 = box name:box01 pos:[-32.5492,-21.2796,0] -- create two boxes b2 = box name:box02 pos:[51.3844,-17.2801,0] animate on at time 100 b1.pos = [-48.2522,167.132,0] -- animate position of one box --- Assign a reactor, pick the react to object, and create reactions cont = b2.pos.controller = position_Reactor() --- you can either react to a controller reactTo cont b1.pos.controller -- or a node (the World Space position of the box) -- reactTo cont b1 -slidertime = 100 createReaction cont slidertime = 50 createReaction cont deleteReaction cont 3 --- Set the reaction parameters setReactionState cont 2 [65.8385,174.579,0] selectReaction cont 1 setReactionInfluence cont 1 100 setReactionStrength cont 1 1.2 setReactionFalloff cont 1 1.0 setReactionValue cont 1 [-40.5492,-20.0,0] setReactionName cont 1 My Reaction --- get the reaction parameters getReactionInfluence cont 1 getReactionStrength cont 1 getReactionFalloff cont 1 getReactionState cont 1 getReactionValue cont 1 getSelectedReactionNum cont getReactionCount cont getReactionName cont 1

Script Controllers

1329

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Script Controllers
float_script : floatController point3_script : point3Controller position_script : positionController rotation_script : rotationController scale_script : scaleController Constructor:
float_script ... point3_script ... position_script ... rotation_script ... scale_script ...

Properties:
<script_controller>.script String default: varies

lets you programmatically get and set the text for scripts. For example,
$foo.position.controller=position_script() $foo.position.controller.script = $baz.pos - [20,20,35]

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Script controllers function in similar way to expression controllers, providing a properties dialog in which a script can be entered that is used to compute the controller value. The primary advantages of script controllers are: They can use all the features of the MAXScript language including loops, scripted functions, pathnames, etc. Almost any property of any object in the scene can be used to help compute controller values, including things like mesh vertices, values of properties at arbitrary frame times, and other nonanimatable properties that are not accessible in Expression controllers. They can use MAXScript global variables to communicate and coordinate with other controllers and scripts in 3ds max.

1330

Chapter 11

3ds max Objects

When you assign a Script controller to some parameter, a properties dialog becomes available in Track View through the right-mouse-button menu or the Properties button on the Track View toolbar. This dialog contains two text boxes and several buttons: Script text box: You type the script to compute the controller value here. See the section below on writing controller scripts for details. Result text box: This box shows the results of an evaluation or any error messages caused by errors in your script. Evaluate button: Cause an evaluation of the controller script to be made and prints the result in the Result box. The evaluation is computed for the current position of the 3ds max time slider. Load/Save buttons: Load and save scripts to text files. Close button: Compiles and checks the controller script and if all is OK, close the properties dialog. Any problems result in a dialog asking whether you really want to close the box with an incorrect script. If you do, the controller yields a null value (0, [0,0,0], etc.) when evaluated by 3ds max.

Script Controllers

1331

Writing Controller Scripts 3ds max interprets the text you type into the Script text box as the body of a MAXScript block expression, so you can type as many expressions as you want on as many lines as you want and they are evaluated in turn and the value of the last expression is taken as the controller value. This value must yield the right type for the controller, Float for float, Point3 for position, Quat for rotation, etc. The value returned from a script controller may not necessarily be the same value seen in Track View or in the command panels, nor the same value returned by accessing the property value in MAXScript. Part of a MAXWrapper property definition is a scaling value that is applied when reading or setting the true value stored in a controller. For example, the slice_to and slice_from properties associated with many of the geometry primitives is displayed in degrees. The actual value stored in the controller associated with these properties are in radians. This scaling factor is an internal property of the MAXWrapper property, and not an internal property of the controller. Both 3ds max and MAXScript automatically apply the specified scaling factor when accessing properties, so this scaling is normally invisible to the user. The exception is when script or expression controllers are used. For these controllers, the data value returned must be the unscaled value, as 3ds max will then apply the scaling factor to the output value. In the documentation of the MAXWrapper classes, any scaling applied to a property is shown. If there is no scaling listed, no scaling occurs for that property. For example, a portion of the Capsule documentation is:
<Capsule>.radius <Capsule>.height <Capsule>.slice_from <Capsule>.slice_to Float Float Float Float default: default: default: default: 0.0 0.0 0.0 0.0 ----animatable animatable animatable, angle animatable, angle

From this, a scripted controller would return unscaled values for the radius and height properties, and radians for slice_from and slice_to. The scaling types, stored value meaning, and scaling value applied to the true controller value are as follows: Angle -- value stored in radians, output scaled by 57.29578 Percentage -- value stored as fraction (0 to 1), output scaled by 100 For properties that have a Color value type, the controller output is automatically scaled by 255. If a point3_script is assigned to one of these properties, each component value should stored as fraction (0 to 1). Remember that converting a MAXScript Color value to a Point3 value does not apply a scaling factor red as point3 returns a value of [255,0,0]. Therefore you must explicitly scale a Color value by dividing by 255 if it is output by the script controller. The body of a script controllers script is any valid MAXScript expression that evaluates to the proper data type, and can contain global and local variables, functions, and structure definitions. The script is compiled in its own local scope, and the locals are only visible inside the scope of the script controller. Script controller local variables are heap-based locals, which are slightly different from normal (stack-based) locals. Normal locals are visible in the current scope and have a lifetime of one execution of that scope. Heap-based locals are also visible only in the current scope, but have a lifetime equal to the lifetime of the top-level expression where they are defined. A script controllers locals are created the first time the script is executed and are kept permanently in the heap (unless

1332

Chapter 11

3ds max Objects

and until you redefine the script). This means you can store values in local variables during one execution of the script controller and these values will still be present at the next evaluation. You cannot access the script controllers locals from another utility or from Listener, because they are not executing within the scope of the script controller. See the Scope of Variables (p. 646) topic for more information. As a special case, you can exit a script controllers script using a return <expr>. A controller is always evaluated by 3ds max with respect to a specific animation time. This might be the current time slider or incrementing frame time if an animation is playing or a render is under way. In the case of Script controllers, the time being evaluated is used to establish an automatic at time context around the controller script, so any properties you access (outside of other explicit at time expressions) yield the correct values for the current controller evaluation time. This means you dont have to do anything special in your scripts to work at the correct time. You can access the evaluation time if you need to with the standard MAXScript variable, currentTime. You can also reference scene property values at other times by using explicit at time expressions in your scripts, as in normal MAXScript programming. Remember that MAXScript lets you write multiline string literals, if you need. Examples: A position script keeping the object at the center of all other objects in the scene as they move about:
local pos = [0,0,0] for o in objects where o != $foo do pos += o.pos pos / (objects.count - 1)

The above script computes the average position of all objects except the current one (written as $foo here) by setting up a local variable that iterates through all objects except $foo, accumulates a total position vector, and computes the average in the last line, which is the final result of the script. A position script keeping the object attached to the highest vertex in a given object:
local high_index = 1, high_z = (getVert $foo 1).z for i in 2 to $foo.numVerts do if (getVert $foo i).z > high_z then ( high_index = i high_z = (getVert $foo i).z ) getVert $foo high_index

The above script runs over the vertices in $foo remembering the index of the vertex with the largest z and returns that vertexs coordinates as the new position.

Slave_Control : Matrix3Controller

1333

Limitations Script controllers are not automatically updated when you interactively modify objects that they depend on. If you move the time slider or if you animate the changes and then play the animation, the changes are reflected automatically. Because the scripts can refer to other objects in very indirect ways or conditional ways, it is not possible for MAXScript to automatically determine the objects a script depends on.

Slave_Control : Matrix3Controller
Note: This class is not available in 3D Studio VIZ. The Slave_Control is used as the transform controller for the boxes in a RingArray system object. You cannot create a RingArray system using MAXScript in 3ds max 4, but properties for this controller are accessible by MAXScript for existing RingArray systems. A RingArray system actually consists of two types of controllers the master controller and Slave_Control controllers. The Slave_Control controllers are used as the transform controller for all the boxes in the RingArray system, and the master controller controls the individual Slave_Control controllers. Changing a property value for one Slave_Control in a RingArray system changes the property value for all Slave_Controls in the system. Properties:
<Slave_Control>.radius <Slave_Control>.cycles <Slave_Control>.amplitude <Slave_Control>.phase Float Float Float Float default: default: default: default: 100.0 3.0 20.0 1.0 ----animatable animatable animatable animatable

Slave Controllers
slavefloat : floatController slave_point3 : point3Controller slavepos : positionController slaverotation : rotationController slavescale : scaleController Constructor: The Slave controllers are not creatable by MAXScript. They can only be created by creating a Masterblock in the Block Control node in the Global Tracks node of Track View. See the MasterBlock : MasterBlockController (p. 1320) topic for more information.

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1334

Chapter 11

3ds max Objects

Surface_position : PositionController
Constructor:
Surface_position ...

Properties:
<Surface_position>.surface <Surface_position>.u <Surface_position>.v <Surface_position>.align <Surface_position>.flip Node Float Float Integer Boolean default: default: default: default: undefined 0.0 -- animatable 0.0 -- animatable 1

align = 1 - No Alignment; 2 - Align to U; 3 - Align to V

default: false

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

TCB Controllers
TCB_float : floatController TCB_point3 : point3Controller TCB_position : positionController TCB_rotation : rotationController TCB_scale : scaleController Constructor:
TCB_float ... TCB_point3 ... TCB_position ... TCB_rotation ... TCB_scale ...

Properties:
<controller>.keys MAXKeyArray

See also
MAXKeyArray Values (p. 793) TCB Controller Keys (p. 1335) Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

TCB Controller Keys

1335

TCB Controller Keys

For TCB controller keys, the following additional properties are accessible:
<key>.time <key>.selected <key>.value <key>.tension <key>.continuity <key>.bias <key>.easeTo <key>.easeFrom Time Boolean varies Float Float Float Float Float -- time value or number (interpreted as frames) -- specifies whether the key is selected -- class determined by its containing controller default: 25.0 default: 25.0 default: 25.0 default: 0.0 default: 0.0

See also
Key Common Properties, Operators, and Methods (p. 768) Value Common Properties, Operators, and Methods (p. 714)

Waveform_Float : FloatController
Constructor:
waveform_float ...

Properties: There are no additional properties accessible for Waveform_Float controllers.

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

XYZ Controllers
Color_RGB : Point3Controller Euler_XYZ : RotationController Local_Euler_XYZ : RotationController Point3_XYZ : Point3Controller Position_XYZ : PositionController ScaleXYZ : ScaleController

1336

Chapter 11

3ds max Objects

Constructor:
Color_RGB ... Euler_XYZ ... Local_Euler_XYZ ... Point3_XYZ ... Position_XYZ ... ScaleXYZ ...

Properties: The property names for the XYZ controllers vary between the specific controllers. Color_RGB:
<Color_RGB>.r <Color_RGB>.g <Color_RGB>.b Float Float Float default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable

Euler_XYZ:
<Euler_XYZ>.x_rotation <Euler_XYZ>.y_rotation <Euler_XYZ>.z_rotation <Euler_XYZ>.axisOrder Float Float Float Integer default: 1 default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable

Get/set the order of application of the axis angles. Its value can be any of the following: 1 - XYZ 2 - XZY 3 - YZX 4 - YXZ 5 - ZXY 6 - ZYX 7 - XYX 8 - YZY 9 - ZXZ Local_Euler_XYZ:
<Local_Euler_XYZ>.local_x_rotation Float default: 0.0 <Local_Euler_XYZ>.local_y_rotation Float default: 0.0 <Local_Euler_XYZ>.local_z_rotation Float default: 0.0 <Local_Euler_XYZ>.axisOrder Integer default: 1 -- animatable -- animatable -- animatable

Get/set the order of application of the axis angles. Its value can be any of the following: 1 - XYZ 2 - XZY 3 - YZX 4 - YXZ 5 - ZXY 6 - ZYX

XYZ Controllers

1337

7 - XYX 8 - YZY 9 - ZXZ Point3_XYZ:

<Point3_XYZ>.x <Point3_XYZ>.y <Point3_XYZ>.z Float Float Float default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable

Position_XYZ:
<Position_XYZ>.x_position <Position_XYZ>.y_position <Position_XYZ>.z_position Float Float Float default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable

ScaleXYZ:
<ScaleXYZ>.x_scale <ScaleXYZ>.y_scale <ScaleXYZ>.z_scale Float Float Float default: 0.0 default: 0.0 default: 0.0 -- animatable -- animatable -- animatable

Methods:
getXYZControllers <controller>

Returns an array of the X, Y, and Z sub-controllers of the specified controller

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Atmospheric : MAXWrapper
The Atmospheric class lets you set up volumetric rendering effects with MAXScript. You can create atmospherics like combustion and fog, access various properties on them and maintain their list of gizmo nodes such as lights and atmospheric helpers. The classes derived directly from the Atmospheric class are described in the Atmospheric Effect Types (p. 1339) topic. The properties, operators, and methods that are common to all classes derived directly from the Atmospheric class are described in the Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) topic. The Atmospheric class is derived from the MAXWrapper class, and inherits the properties and methods defined for that class. These properties and methods are described in the MAXWrapper Common Properties, Operators, and Methods (p. 809) topic.

1338

Chapter 11

3ds max Objects

Atmospheric Effects Common Properties, Operators, and Methods

Atmospherics have the following common properties and methods: Properties:
<atmos>.name String default: varies

The name as it appears in the Environment dialog list. The class name is used as the default name when no name: creation parameter is supplied.
<atmos>.numGizmos Integer -- read-only

The number of gizmos ever assigned to the atmospheric. A gizmo obtained via .numGizmos may be undefined, meaning a gizmo was added and then deleted. The atmospheric maintains an array of gizmos, and not every slot is necessarily in use. numGizmos is the size of the array, not the number of used slots. Methods:
isActive <atmos>

Returns true if the atmospheric is set to active; false otherwise.

getGizmo <atmos> <index_integer>

Retrieves the indexed gizmo node from the atmospheric. The gizmo node will be a light or atmospheric helper. The Index is 1-based.
deleteGizmo <atmos> <index_integer>

Deletes the indexed gizmo from the atmospheric.

appendGizmo <atmos> <node>

Appends the node to the gizmo list on the atmospheric. It must be of the right kind for the atmospheric, lights for volumeLights, helper gizmos for combust, etc.
setActive <atmos> <boolean>

Sets the atmospheric active or inactive. If <boolean> is true the atmospheric is set to active; if false, inactive. Associated Methods: You can use the following functions for maintaining the list of atmospherics in the global rendering environment:
addAtmospheric <atmos>

Appends the atmospheric to the Atmospheric Effects list

getAtmospheric <index_integer>

Retrieves the atmospheric at the indexed position in the Atmospheric Effects list. Index is 1-based.
setAtmospheric <index_integer> <atmos>

Sets the atmospheric at the indexed position in the Atmospheric Effects list to the specified atmospheric. If the Atmospheric Effects dialog is displayed when this method is called, the displayed Atmospheric Effects list is not updated.
deleteAtmospheric <index_integer>

Deletes the atmospheric at the indexed position in the Atmospheric Effects list. Index is 1based.

Fire_Effect : Atmospheric

1339

editAtmosphere <atmos> <node>

Opens the Environment dialog, and opens the rollout for the specified atmospheric if it has been added to the Atmospheric Effects list. If the specified node is a gizmo for the atmospheric, that gizmo is selected in the atmospheric s gizmo list.
editAtmospheric <atmos> [ gizmo: <node> ]

Opens the Environment dialog, and opens the rollout for the specified atmospheric if it has been added to the Atmospheric Effects list. If the optional gizmo: argument is specified, and the specified node is a gizmo for the atmospheric, that gizmo is selected in the atmospherics gizmo list. The 3ds max global variable numAtmospherics gives you the number of current atmospherics in the rendering environment. Note: Unlike most MAXWrapper objects, you can not copy an Atmospheric.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Example:
atmos = combust density:20 outer_color:red appendGizmo atmos $SphereGizmo01

Atmospheric Effect Types

The following list shows the 3ds max Atmospheric Effect types: Fire_Effect (p. 1339) Fog (p. 1342) Volume_Fog (p. 1343) Volume_Light (p. 1344)

Fire_Effect : Atmospheric
Constructor:
Fire_Effect ...

Properties:
<Fire_Effect>.Inner_Color Color default: (color 252 202 0) -- animatable

Sets the color of the densest part of the effect. For a typical fire, this color represents the hottest part of the flame.

1340

Chapter 11

3ds max Objects

<Fire_Effect>.Outer_Color

Color

default: (color 225 30 30)

-- animatable

Sets the color of the sparsest part of the effect. For a typical fire, this color represents the cooler, dissipating edge of the flame. The fire effect is colored using a gradient between the inner and outer colors. The dense areas of the effect use the inner color and gradually blend to the outer color near the edges of the effect.
<Fire_Effect>.Smoke_Color <Fire_Effect>.Flame_Type Color Integer default: (color 25.5 25.5 25.5) default: 0 -- animatable

Sets the color of smoke for use with the Explosion option. Sets the flame type: Fire Ball (Creates round puffy flames. Fireballs are well suited for explosions.) Tendril (Creates directional pointed flames with veins along their center. The flames orient along the local Z axis of the fire apparatus. Tendril creates campfire-like flames.)
<Fire_Effect>.Stretch Float default: 1.0 -- animatable

Scales flames along the Z axis of the apparatus. Stretch works best with Tendril flames, but you can use it to give Fireballs an oval shape. Values less than 1.0 compress flames, making them shorter and thicker. Values greater than 1.0 stretch flames, making them long and skinny.
<Fire_Effect>.Regularity Float default: 0.2 -- animatable

Modifies how the flames fill the apparatus. A value of 1.0 completely fills the apparatus. The effect fades near the edges of the apparatus, but the overall shape is still very noticeable. A value of 0.0 produces a very irregular effect that might occasionally reach the boundary of the apparatus, but usually gets trimmed back and is smaller.
<Fire_Effect>.Flame_Size Float default: 35.0 -- animatable

Sets the size of individual flames inside the apparatus. The size of the apparatus affects the flame size. A larger apparatus requires a larger flame size. Use a range from 15.0 to 30.0 for the best results. Large values work best for Fireballs. Small values work best for Tendrils.
<Fire_Effect>.Flame_Detail Float default: 3.0 -- animatable

Controls the amount of color change and edge sharpness seen within each flame. Low values produce smooth, fuzzy flames and render faster. High values produce patterned, sharp flames and render slower.
<Fire_Effect>.Density Float default: 15.0 -- animatable

Sets the opacity and brightness of the fire effect. The size of the apparatus affects the density. A large apparatus with the same density as a small apparatus appears more opaque and brighter because of its larger size. Low values make the effect less opaque and use more of the outer color. High values make the effect more opaque and brighten the effect by gradually replacing the inner color with white. The higher the value, the more white the center of the effect is.
<Fire_Effect>.Samples Integer default: 15 -- animatable

Sets the rate at which the effect is sampled. Higher values produce more accurate results but take longer to render.
<Fire_Effect>.phase Float default: 0.0 -- animatable

Controls the rate of change for the fire effect.

Setting explosion start and end times for Fire-Effect

1341

<Fire_Effect>.Drift

Float

default: 0.0

-- animatable

Sets how flames are rendered along the Z-axis of the fire apparatus. The value is the amount of rise in units.
<Fire_Effect>.Explosion Integer default: 0

When on, animates size, density, and color automatically based on the animation of the phase value. OFF ON
<Fire_Effect>.Smoke Integer default: 1

Controls whether or not the explosion creates smoke. OFF ON

<Fire_Effect>.Fury Float default: 1.0

Varies the churning effect of the Phase parameter. Values greater than 1.0 cause faster churning. Values less than 1.0 cause slower churning. Note: The Explosion, Smoke, and Fury properties are not available in 3D Studio VIZ.

See also
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Setting explosion start and end times for Fire-Effect

The start and end spinners in the Explosion Setup dialog for Fire-Effect effectively install keyframes and set times and values for them in the controller for phase. You can achieve the same effect by manually constructing a phase controller and its keyframes. In the following example, the start and end times are set at 20 and 75:
c = getAtmospheric 1 -- to set up a new phase controller like the setup dialog does: -- make and set the controller pc = bezier_float() c.phase.controller = pc -- add key 1 at 20 & set properties k = addNewKey pc 20 k.value = 0 k.inTangentType = #slow k.outTangentType = #fast

1342

Chapter 11

3ds max Objects

-- add key 2 at 75 & set k = addNewKey pc 75 k.value = 300 k.inTangentType = #slow k.outTangentType = #fast -- or, to change times if the keys are already there: c.phase.keys[1].time = 20 c.phase.keys[2].time = 75

Fog : Atmospheric
Constructor:
fog ...

Properties:
<Fog>.Fog_Color <Fog>.Use_Color_Map <Fog>.Use_Opacity_Map <Fog>.Fog_Background <Fog>.Fog_Type <Fog>.Exponential <Fog>.Near <Fog>.Far <Fog>.Top <Fog>.Bottom <Fog>.Density <Fog>.falloff <Fog>.Horizon_Noise <Fog>.size <Fog>.angle <Fog>.phase Color Integer Integer Integer Integer Integer Float Float Float Float Float Integer Integer Float Float Float default: (color 255 255 255) default: 0 default: 0 default: 1 default: 0 default: 0 default: default: default: default: default: default: 0.0 100.0 100.0 0.0 50.0 2 -----animatable, percentage animatable, percentage animatable animatable animatable -- animatable

Use_Color_Map = 0 - off; 1 - on Use_Opacity_Map = 0 - off; 1 - on Fog_Background = 0 - off; 1 - on Fog_Type = 0 - Standard; 1 - Layered Exponential = 0 - off; 1 - on

falloff = 0 - Top; 1 - Bottom; 2 - None

default: 0 default: 20.0 default: 5.0 default: 0.0 -- animatable -- animatable, angle -- animatable

Horizon_Noise = 0 - off; 1 - on

Note: You currently cannot assign texture maps as the color and opacity maps using MAXScript. Once these texture maps have been assigned, they are accessible as subAnims of Fog.

Volume_Fog : Atmospheric

1343

See also
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Volume_Fog : Atmospheric
Constructor:
volume_fog ...

Properties:
<Volume_Fog>.Soften_Gizmo_Edges <Volume_Fog>.Fog_Color animatable <Volume_Fog>.Exponential Float Color Integer Float Float Integer Integer Integer Integer Float Float Float Float Float Float Float Integer default: 0.2 -- animatable default: (color 255 255 255) default: 0 default: default: default: default: 20.0 4.0 100 1 -- animatable --

Exponential = 0 - off; 1 - on
<Volume_Fog>.Density <Volume_Fog>.Step_Size <Volume_Fog>.Max_Steps <Volume_Fog>.Fog_Background

Fog_Background = 0 - off; 1 - on
<Volume_Fog>.Noise_Type <Volume_Fog>.invert default: 0 default: 0 default: default: default: default: default: default: default: default: 1.0 0.0 0.0 3.0 20.0 0.0 0.0 0 ------animatable animatable animatable animatable animatable animatable

Noise_Type = 0 - Regular; 1 - Fractal; 2 - Turbulence invert = 0 - off; 1 - on

<Volume_Fog>.High_Threshold <Volume_Fog>.Low_Threshold <Volume_Fog>.Uniformity <Volume_Fog>.Levels <Volume_Fog>.size <Volume_Fog>.phase <Volume_Fog>.Wind_Strength <Volume_Fog>.Wind_Direction

Wind_Direction = 0 - Front; 1 - Back; 2 - Left; 3 - Right; 4 - Top; 5 - Bottom

See also
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1344

Chapter 11

3ds max Objects

Volume_Light : Atmospheric
Constructor:
volume_light ...

Properties:
<Volume_Light>.Fog_Color 255) -- animatable <Volume_Light>.attenuation_color 255) -- animatable <Volume_Light>.Exponential Color Color Integer Float Float Float Integer Float Integer Integer Integer Float Float Integer Float Integer Integer Integer Float Float default: (color 255 255 default: (color 0 0 default: 0 default: 5.0 default: 90.0 default: 0.0 default: 0 default: 2.0 default: 3 default: 20 default: 1 default: 100.0 default: 100.0 default: 0 default: 0.0 default: 0 default: 0 default: 0 default: 1.0 default: 0.0 ----------

Exponential = 0 - off; 1 - on
<Volume_Light>.Density animatable <Volume_Light>.Max_Light animatable <Volume_Light>.Min_Light animatable <Volume_Light>.Use_Attenuation_Color

Use_Attenuation_Color = 0 - off; 1 - on
<Volume_Light>.Attenuation_Color_Multiplier animatable <Volume_Light>.Filter_Shadows <Volume_Light>.Samples <Volume_Light>.Auto_Sample

Filter_Shadows = 0 - Low; 1 - Medium; 2 - High; 3 - Use Light Smp Range

Auto_Sample = 0 - off; 1 - on
<Volume_Light>.Atten_Start animatable <Volume_Light>.Atten_End animatable <Volume_Light>.Noise_On

Noise_On = 0 - off; 1 - on
<Volume_Light>.Noise_Amount animatable <Volume_Light>.Link_To_Light

Link_To_Light = 0 - off; 1 - on
<Volume_Light>.Noise_Type <Volume_Light>.invert invert = 0 - off; 1 - on <Volume_Light>.High_Threshold animatable <Volume_Light>.Low_Threshold animatable

Noise_Type = 0 - Regular; 1 - Fractal; 2 - Turbulence

Volume_Light : Atmospheric

1345

<Volume_Light>.Uniformity animatable <Volume_Light>.Levels animatable <Volume_Light>.size animatable <Volume_Light>.phase animatable <Volume_Light>.Wind_Strength <Volume_Light>.Wind_Direction

Float Float Float Float Float Integer

default: 0.0 default: 3.0 default: 20.0 default: 0.0 default: 0.0 default: 0

-----

Wind_Direction = 0 - Front; 1 - Back; 2 - Left; 3 - Right; 4 - Top; 5 - Bottom

See also
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Working with Atmospherics

The following 3ds max system global variables give you access to the global rendering environment:
backgroundColor

Lets you get and set a Color value that defines the global rendering environment (Rendering\Environment) background color.
backgroundColorController

Lets you get and set a Controller value that defines the global rendering environment (Rendering\Environment) background color controller.
ambientColor

Lets you get and set a Color value that defines the global rendering environment (Rendering\Environment) ambient lighting color.
ambientColorController

Lets you get and set a Controller value that defines the global rendering environment (Rendering\Environment) ambient lighting color controller.
environmentMap

Lets you get and set a TextureMap value that defines the global rendering environment (Rendering\Environment) environment map.
useEnvironmentMap

Lets you get and set the global rendering environment (Rendering\Environment) Use Map value. A Boolean value - true if Use Map is on, false if off.
lightTintColor

Lets you get and set a Color value that defines the global rendering environment (Rendering\Environment) Global Lighting Tint color.
lightTintColorController

Lets you get and set a Controller value that defines the global rendering environment (Rendering\Environment) Global Lighting Tint color controller.

1346

Chapter 11

3ds max Objects

lightLevel

Lets you get and set a Float value that defines the global rendering environment (Rendering\Environment) Global Lighting Tint Level.
lightLevelController

Lets you get and set a Controller value that defines the global rendering environment (Rendering\Environment) Global Lighting Tint Level controller.
numAtmospherics

Contains an Integer value that defines the number of atmospheric events, as shown in Rendering\Environment. This variable is read-only. The following methods set options in the global rendering environment:
getUseEnvironmentMap() setUseEnvironmentMap <boolean>

Lets you get and set the global rendering environment (Rendering\Environment) Use Map value. If <boolean> is true Use Map is turned on, false it is turned off.
getBackGroundController()

Returns the global rendering environment (Rendering\Environment) background color controller.

setBackGround <time> <point3>

Lets you set a Point3 value that defines the global rendering environment (Rendering\Environment) background color at the specified time. Each component of the Point3 value is in the range of 0 to 255.
setBackGroundController ( <color_controller> | <point3_controller> )

Assigns the specified controller as the global rendering environment (Rendering\Environment) background color controller. Examples:
ambientColor = color 10 10 25 environmentMap = bitmapTexture filename:foo.bmp

The following script shows an example of creating Volume Fog and Volume Light atmospherics. Script:
-- Atmospheric Effects Test Bed -- create a geosphere, sphere gizmo, onnilight, and targetted camera geos=geosphere radius:24 sgizmo=spheregizmo radius:40 omni=omnilight farAttenStart:20 farAttenEnd:100 useFarAtten:true v=255 cam=targetcamera pos:[150,-50,100] target:(targetobject()) --- put a material on the geosphere geos.material=standard() geos.material.selfIllumColor = color 238 241 2 --- create a Volume Fog atmospheric. Set name so it has one in Environment dialog. vf=volume_fog name:VolFog soften_gizmo_edges:0.7 exponential:1 density:75 vf.fog_color=color 255 157 0 vf.noise_type=2

Render Effects Common Properties, Operators, and Methods

1347

vf.size=4 appendGizmo vf sgizmo addAtmospheric vf --- create a Volume Light atmospheric. Set name so it has one in Environment dialog. vl=volume_light name: VolLight exponential:1 density:20 vl.fog_color=color 255 30 0 vl.attenuation_color= color 255 162 0 vl.Use_Attenuation_Color=1 vl.noise_on=1 vl.Noise_Amount=1 vl.size=5 vl.noise_type=2 appendGizmo vl omni addAtmospheric vl --- and render away renderWidth=320 renderHeight=200 render camera:cam

RenderEffect : MAXWrapper
The RenderEffect class lets you set up rendering effects with MAXScript. You can create render effects such as blur, color balance, and film grain effect. The classes derived directly from the RenderEffect class are described in the Render Effect Types (p. 1348) topic. The properties, operators, and methods that are common to all classes derived directly from the RenderEffect class are described in the Render Effects Common Properties, Operators, and Methods (p. 1347) topic. The RenderEffect class is derived from the MAXWrapper class, and inherits the properties and methods defined for that class. These properties and methods are described in the MAXWrapper Common Properties, Operators, and Methods (p. 809) topic.

Render Effects Common Properties, Operators, and Methods

Render Effects have the following common properties and methods: Properties:
<renderEffect>.name String default: varies

The name as it appears in the Rendering/Effects dialog list. The class name is used as the default name when no name: creation parameter is supplied. Methods:
addEffect <renderEffect>

Adds the render effect to the Rendering/Effects dialog list.

1348

Chapter 11

3ds max Objects

setActive <renderEffect> <boolean>

Sets the render effect active or inactive. If <boolean> is true the render effect is set to active; if false, inactive. Associated Methods and Global Variables: You can use the following global variables and functions for maintaining the list of render effects in the Rendering/Effects dialog list:
IsActive <renderEffect>

Returns true if the render effect is set to active; false otherwise.

numEffects

Global variable containing an Integer value that defines the number of current render effects defined in the Rendering/Effects dialog list. This variable is read-only.
getEffect <index_integer>

Retrieves the render effect at the indexed position in the Rendering/Effects dialog list. The index is 1-based.
editEffect <renderEffect> [ gizmo: <node> ]

Opens the Rendering/Effects dialog, and opens the rollout for the specified render effect if it has been added to the Render Effects list. If the optional gizmo: argument is specified, and the specified node is a gizmo for the render effect, that gizmo is selected in the render effects gizmo list.
setEffect <index_integer> <renderEffect>

Sets the render effect at the indexed position in the Rendering/Effects dialog list to the specified render effect. If the Render Effects dialog is displayed when this method is called, the displayed Render Effects list is not updated.
deleteEffect <index_integer>

Deletes the indexed render effect from the Rendering/Effects dialog list. The index is 1based. Note: Unlike most MAXWrapper objects, you can not copy an RenderEffect.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Render Effect Types

The following list shows the 3ds max Render Effect types: Blur Effect (p. 1349) Brightness and Contrast (p. 1353) Color Balance Effect (p. 1354) Depth of Field (p. 1354)

Blur : RenderEffect

1349

File Output Effect (p. 1356) Film Grain (p. 1356) Lens Effects (p. 1357)

Blur : RenderEffect
Constructor:
blur ...

Properties:
<blur>.blur_type Integer default: 0 -- animatable

Select a blur type: Uniform Directional Radial

<blur>.bUnifPixRad Float default: 10.0

Determines the intensity of the Blur effect. Increasing the value increases the number of surrounding pixels that each pixel will use to compute its blur. The more pixels used means a greater blur for the image.
<blur>.bUnifAlpha <blur>.bDirUPixRad Boolean Float default: true default: 10.0 -- animatable

Applies the Uniform Blur effect to the alpha channel when turned on. Determines the horizontal intensity of the Blur effect. Increasing the value increases the number of surrounding pixels that each pixel will use to compute its blur. The more pixels used means a greater horizontal blur for the image.
<blur>.bDirVPixRad Float default: 10.0

Determines the vertical intensity of the Blur effect. Increasing the value increases the number of surrounding pixels that each pixel will use to compute its blur. The more pixels used means a greater vertical blur for the image.
<blur>.bDirUTrail Float default: 0.0

Adds direction to your blur by weighting more blur to either side of the U axis. This adds a streaking effect and creates the illusion that your objects or your camera are rapidly moving in a particular direction.
<blur>.bDirVTrail Float default: 0.0

Adds direction to your blur by weighting more blur to either side of the V axis. This adds a streaking effect and creates the illusion that your objects or your camera are rapidly moving in a particular direction.

1350

Chapter 11

3ds max Objects

<blur>.bDirRotation

Integer

default: 0

Rotates the axis of the U and V pixels that will be blurred by the U and V Pixel Radius spinners. By using Rotation with the U and V Pixel Radius spinners you can have the Blur effect applied to any direction in your rendered image. When rotation is 0, U corresponds to the images X-axis and V corresponds to the images Y-axis.
<blur>.bDirAlpha <blur>.bRadialPixRad Boolean Float default: true default: 20.0 -- animatable

Applies the Directional Blur effect to the Alpha channel when turned on. Determines the intensity of the Radius Blur effect. Increasing the value increases the number of surrounding pixels that each pixel will use to compute its blur. The more pixels used means a greater blur for the image.
<blur>.bRadialXOrig <blur>.bRadialYOrig axis.<blur>.bRadialTrail Integer Integer Float default: 320 default: 240 default: 0.0

Sets the origin for the radial blur effect along the X axis. Sets the origin for the radial blur effect along the Y axis. Adds direction to your blur by weighting more or less blur towards the center of the Blur effect. This adds a streaking effect and creates the illusion that your objects or your camera are rapidly moving in a particular direction.
<blur>.bRadialAlpha <blur>.bRadialNode <blur>.bRadialUseNode <blur>.selImageActive Boolean Node Boolean Boolean default: true -- animatable

Applies the Radial Blur effect to the Alpha channel when turned on.
default: undefined default: false default: true -- animatable

Node to which radial blur is assigned. Turn on/off use object center for selected node, bradialnode. When on, the blur affects the entire rendered image. This is useful when the blur effect dims your rendered image.
<blur>.selImageBrighten <blur>.selImageBlend Float Float default: 0.0 default: 100.0

Brightens the entire image. Blends the Blur effect and the Whole Image parameters with the original rendered image. This can be used to create a soft-focus effect.
<blur>.selIBackActive Boolean default: false

Affects everything but the background image or animation when turned on. This is useful when the Blur effect has dimmed you scene objects but not the background.
<blur>.selIBackBrighten <blur>.selIBackBlend Float Float default: 0.0 default: 100.0

Brightens the rendered image except for the background image or animation. Blends the Blur effect and the Non-Background parameters with the original rendered image.

Blur : RenderEffect

1351

<blur>.selIBackFRadius

Float

default: 10.0

Feathers the Blur effect applied to the Non-Background elements of your scene. When using Non-Background as a Pixel Selection you will notice that the scene objects have a hard edge to their blur since the objects are being blurred but the background is not.
<blur>.selLumActive Boolean default: false

Affects any pixels that have luminance values that fall between its Min and Max values, selLumMin & selLumMax.
<blur>.selLumBrighten <blur>.selLumBlend <blur>.selLumMin Float Float Float default: 0.0 default: 100.0 default: 90.0

Brightens pixels that fall between the Minimum and Maximum luminance values. Blends the Blur effect and the Luminance parameters with the original rendered image. The minimum luminance value necessary for each pixel in order for the Blur effect to be applied to the pixel.
<blur>.selLumMax Float default: 100.0

The maximum luminance value a pixel can have in order for the Blur effect to be applied to the pixel.
<blur>.selLumFRadius Float default: 10.0

Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum luminance values. When using Luminance as a Pixel Selection the Blur effect can create a hard edge on the effect.
<blur>.selMaskActive Boolean default: false

When turned on, applies the Blur effect according to the channel selected and mask applied through the Material/Map Browser.
<blur>.selMaskMap <blur>.selMaskChannel select_mask_channel TextureMap Integer default: undefined default: 4 -- alias:

Map assigned to the blur effect.

Selects a channel that the Blur effect will be applied to: Red Blue Green Alpha Luminance
<blur>.selMaskBrighten <blur>.selMaskBlend <blur>.selMaskMin Float Float Float default: 0.0 default: 100.0 default: 90.0

Brightens the portions of the image that the Blur effect is applied to. Blends the Map Mask Blur effect with the original rendered image. The minimum value (RGB, Alpha, or Luminance) a pixel must have in order to have the Blur effect applied to it.

1352

Chapter 11

3ds max Objects

<blur>.selMaskMax

Float

default: 100.0

The maximum value (RGB, Alpha, or Luminance) a pixel can have for the Blur effect to be applied to it.
<blur>.selMaskFRadius Float default: 10.0

Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum channel values. When using map mask as a Pixel Selection the Blur effect can create a hard edge on the effect.
<blur>.selObjIdsActive Boolean default: false -animatable

When turned on, applies the Blur effect to an object or part of an object with a specific Object ID, if the object matches the Filter settings.
<blur>.selObjIdsIds <blur>.selObjIdsBrighten <blur>.selObjIdsBlend <blur>.selObjIdsFRadius Array Float Float Float default: #() default: 0.0 default: 100.0 default: 10.0 ----int array animatable animatable animatable

This array contains all of the Object IDs to which the blur effects will be applied. Brightens the portion of the image that the Object ID-specific Blur effect is applied to. Blends the Object ID Blur effect with the original rendered image. Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum luminance values.
<blur>.selObjIdsLumMin Float default: 0.0 -animatable

The minimum luminance value a pixel must have in order to have the Blur effect applied to it.
<blur>.selObjIdsLumMax <blur>.selMatIdsActive Float Boolean default: 100.0 default: false --animatable animatable

The maximum luminance value a pixel can have for the Blur effect to be applied to it. Applies the Blur effect to a material or part of a material with a specific material effects channel, if the material matches the Filter settings.
<blur>.selMatIdsIds <blur>.selMatIdsBrighten <blur>.selMatIdsBlend <blur>.selMatIdsFRadius Array Float Float Float default: #() default: 0.0 default: 100.0 default: 10.0 ----int array animatable animatable animatable

This array contains all of the Material IDs to which the blur effects will be applied. Brightens the portion of the image that the Blur effect is applied to. Blends the Material ID Blur effect with the original rendered image. Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum luminance values.
<blur>.selMatIdsLumMin Float default: 0.0 -animatable

The minimum luminance value a pixel must have in order to have the Blur effect applied to it.
<blur>.selMatIdsLumMax Float default: 100.0 -animatable

The maximum luminance value a pixel can have for the Blur effect to be applied to it.

Brightness_and_Contrast : RenderEffect

1353

<blur>.selGenBrightType

Integer

default: 1

--

animatable

Selects the type of brightening applied to the feather falloff curve: Additive Multiplicative
<blur>.select_falloff_curve SubAnim <blur.select_falloff_curve>.curve_1 <blur.select_falloff_curve>.curve_2 default: SubAnim:Select_Falloff_Curve SubAnim default: SubAnim:Curve_1 SubAnim default: SubAnim:Curve_2

The brightening curve for the feather falloff. The blend curve for the feather falloff.

See also
Render Effects Common Properties, Operators, and Methods (p. 1347) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Brightness_and_Contrast : RenderEffect
Constructor:
brightness_and_contrast ...

Properties:
<Brightness_and_Contrast>.Brightness <Brightness_and_Contrast>.contrast <Brightness_and_Contrast>.ignoreBack alias: ignore_background Float Float Boolean default: 0.5 default: 0.5 default: false -- animatable -- animatable -- animatable,

See also
Render Effects Common Properties, Operators, and Methods (p. 1347) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1354

Chapter 11

3ds max Objects

Color_Balance : RenderEffect
Constructor:
color_balance ...

Properties:
<Color_Balance>.red <Color_Balance>.green <Color_Balance>.blue <Color_Balance>.preserveLum Preserve_Luminosity <Color_Balance>.ignoreBack Ignore_Background Integer Integer Integer Boolean Boolean default: default: default: default: 0 0 0 false ----animatable animatable animatable animatable, alias:

default: false

-- animatable, alias:

See also
Render Effects Common Properties, Operators, and Methods (p. 1347) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Depth_of_Field : RenderEffect
Constructor:
depth_of_field ...

Properties:
<Depth_of_Field>.AffectAlpha <Depth_of_Field>.camNodeIndex Boolean Integer default: true default: -1 -- alias: Affect_Alpha -- alias: Camera_Index

camNodeIndex specifies which camera in the Depth of Field camera dropdown is the selected camera. A value of -1 specifies that no camera is selected. The index is otherwise 0based.
<Depth_of_Field>.focalNodeIndex Integer default: -1 -- alias: Focal_Index

focalNodeIndex specifies which camera in the Depth of Field focal point node dropdown is the selected focal point node. A value of -1 specifies that no focal point node is selected. The index is otherwise 0-based.
<Depth_of_Field>.FocalPoint <Depth_of_Field>.FocalType Integer Integer default: 0 default: 0 -- alias: Focal_Point -- alias: Focal_Type

FocalPoint = 0 - Focal Node; 1 - Use Camera FocalType = 0 - Custom; 1 - Use Camera

Depth_of_Field : RenderEffect

1355

<Depth_of_Field>.HorizFocalLoss Horiz_Focal_Loss <Depth_of_Field>.VertFocalLoss Vert_Focal_Loss <Depth_of_Field>.FocalRange Focal_Range <Depth_of_Field>.FocalLimit Focal_Limit

Float Float Float Float

default: 10.0 default: 10.0

-- animatable, alias: -- animatable, alias:

default: 100.0 -- animatable, alias: default: 200.0 -- animatable, alias:

Methods:
DOF.addCam <Depth_of_Field> <camera_node_name_string>

Adds the specified camera to the Depth of Field camera dropdown. camera_node_name_string is the name of the camera as a string, and must match the case of the cameras name. Returns true if the addition was successful, false if it failed. The normal reason for a failure is that the named camera is not present in the scene.
DOF.addFocalNode <Depth_of_Field> <node_name_string>

Adds the specified node to the Depth of Field focal point node dropdown. node_name_string is the name of the node as a string, and must match the case of the nodes name. Returns true if the addition was successful, false if it failed. The normal reason for a failure is that the named node is not present in the scene.
DOF.deleteCam <Depth_of_Field> <index_integer>

Deletes the indexed camera from the Depth of Field camera dropdown, where <index_integer> is the index of the camera in the dropdown. The index is 0-based to maintain consistency with the camNodeIndex property. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the indexed camera is not present in the dropdown.
DOF.deleteCamByName <Depth_of_Field> <camera_node_name_string>

Deletes the specified camera from the Depth of Field camera dropdown. camera_node_name_string is the name of the camera as a string, and must match the case of the cameras name. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the named camera is not present in the dropdown.
DOF.deleteFocalNode <Depth_of_Field> <index_integer>

Deletes the indexed node from the Depth of Field focal point node dropdown, where <index_integer> is the index of the node in the dropdown. The index is 0-based to maintain consistency with the focalNodeIndex property. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the indexed node is not present in the dropdown.
DOF.deleteFocalNodeByName <Depth_of_Field> <node_name_string>

Deletes the specified node from the Depth of Field focal point node dropdown. node_name_string is the name of the node as a string, and must match the case of the nodes name. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the named node is not present in the dropdown.

1356

Chapter 11

3ds max Objects

See also
Render Effects Common Properties, Operators, and Methods (p. 1347) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

File_Output : RenderEffect
Constructor:
file_output ...

Properties:
<File_Output>.bitmap <File_Output>.channelType <File_Output>.active <File_Output>.affectSource affect_source <File_Output>.cameraNode <File_Output>.nearZ near_z_depth <File_Output>.farZ far_z_depth <File_Output>.fitScene fit_entire_scene BitMap Integer Boolean Boolean Node Float Float Boolean default: BitMap: default: 0 default: true default: false default: undefined default: 0.0 default: -500.0 default: true -- output bitmap -- alias: channel_type -- animatable -- animatable, alias: -- alias: camera_node -- animatable, alias: -- animatable, alias: -- animatable, alias:

channelType = 0 - Whole Image; 1 - Luminance; 2 - Depth; 3 - Alpha

See also
Render Effects Common Properties, Operators, and Methods (p. 1347) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Film_Grain : RenderEffect
Constructor:
film_grain ...

Properties:
<Film_Grain>.Grain Float <Film_Grain>.Mask Background Boolean Ignore_Background default: 0.2 default: false -- animatable -- animatable; alias:

Lens_Effects : RenderEffect

1357

See also
Render Effects Common Properties, Operators, and Methods (p. 1347) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Lens Effects
Lens_Effects : RenderEffect
Constructor:
lens_effects ...

Properties:
<Lens_Effects>.size <Lens_Effects>.intensity <Lens_Effects>.seed <Lens_Effects>.angle <Lens_Effects>.squeeze <Lens_Effects>.affectAlpha Affect_Alpha <Lens_Effects>.affectZBuffer Affect_Z_Buffer <Lens_Effects>.distAffectsSize Distance_Affects_Size <Lens_Effects>.distAffectsIntensity Distance_Affects_Intensity <Lens_Effects>.centerAffectsSize Off_Center_Affects_Size <Lens_Effects>.centerAffectsIntensity Off_Center_Affects_Intensity <Lens_Effects>.innerOcclusionRadius alias: Inner_Occlusion_Radius <Lens_Effects>.outerOcclusionRadius alias: Outer_Occlusion_Radius <Lens_Effects>.occlusionAffectsSize Occlusion_Affects_Size <Lens_Effects>.occlusionAffectsIntensity Occlusion_Affects_Intensity <Lens_Effects>.affectByAtmosphere Affect_By_Atmosphere Float Float Integer Float Float Boolean Boolean Boolean Boolean Boolean Boolean Float Float Boolean Boolean Boolean default: default: default: default: default: default: 100.0 100.0 1357 0.0 0.0 true -- animatable -- animatable -- animatable -- animatable -- alias: -- alias: -- alias: -- alias: -- alias: -- alias: -- animatable, -- animatable, -- alias: -- alias: -- alias:

default: false default: false default: false default: false default: false default: 3.0 default: 33.0 default: true default: true default: false

1358

Chapter 11

3ds max Objects

Methods: The following methods add elements to a Lens Effects, load and save a Lens Effects configuration file, add and delete lights, and delete Lens Effects elements.
le.addASec <Lens_Effects>

Adds a Auto Secondary element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.
le.addGlow <Lens_Effects>

Adds a Glow element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.
le.addMSec <Lens_Effects>

Adds a Manual Secondary element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.
le.addRay <Lens_Effects>

Adds a Ray element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.
le.addRing <Lens_Effects>

Adds a Ring element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.
le.addStar <Lens_Effects>

Adds a Star element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.
le.addStreak <Lens_Effects>

Adds a Streak element to the Lens Effect. The element is appended to any elements present. Returns true if the addition was successful, false if it failed.
le.load <Lens_Effects> <filename_string> le.save <Lens_Effects> <filename_string>

Saves the Lens Effects configuration to the file specified by <filename_string>. Animated parameter values are not saved.
le.numLights <Lens_Effects>

Returns the number of lights in the light list.

le.addLightNode <Lens_Effects> <light_node>

Adds light node to the light list.

le.addLight <Lens_Effects> <light_node_name_string>

Adds the specified light to the Lens Effects Lights dropdown. light_node_name_string is the name of the light as a string, and must match the case of the lights name. Returns true if the addition was successful, false if it failed. The normal reason for a failure is that the named light is not present in the scene.
le.deleteLight <Lens_Effects> <index_integer>

Deletes the indexed light from the Lens Effects Lights dropdown, where <index_integer> is the index of the light in the Lens Effects Lights dropdown. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the indexed light is not present in the dropdown.

Lens_Effects : RenderEffect

1359

le.deleteLightByName <light_node_name_string>

Deletes the named light from the Lens Effects Lights dropdown. light_node_name_string is the name of the light as a string, and must match the case of the lights name. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the named light is not present in the dropdown.
le.lightIndex <Lens_Effects> <light_node_name_string>

Returns the light list index of the named light. Returns 1 if the lights name is not in the light list.
le.lightName <Lens_Effects> <index>

Returns the node name of the light for the specified light list index. If the index is out of range, a null string will be returned.
le.deleteElement <Lens_Effects> <index_integer>

Deletes the indexed element, where <index_integer> is the index of the element in the Lens Effects composition window. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the indexed element does not exist.
le.deleteElementByName <element_name_string>

Deletes the named element. element_name_string is the name of the element as a string, and must match the case of the elements name. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the named element does not exist.

See also
Lens_Effects - Auto_Secondary (p. 1360) Lens_Effects - Glow (p. 1363) Lens_Effects - Manual_Secondary (p. 1366) Lens_Effects - Ray (p. 1370) Lens_Effects - Ring (p. 1373) Lens_Effects - Star (p. 1376) Lens_Effects - Streak (p. 1379) Render Effects Common Properties, Operators, and Methods (p. 1347) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1360

Chapter 11

3ds max Objects

Lens_Effects - Auto_Secondary
Constructor:
le.addASec <Lens_Effects>

Properties:
<auto_secondary>.elementName alias: Name <auto_secondary>.on <auto_secondary>.minSize animatable; alias: Min_Size <auto_secondary>.maxSize animatable; alias: Max_Size <auto_secondary>.axis animatable <auto_secondary>.intensity animatable <auto_secondary>.quantity animatable <auto_secondary>.colorSource animatable; alias: Source_Color <auto_secondary>.sides <auto_secondary>.occlusion animatable <auto_secondary>.presets <auto_secondary>.squeeze <auto_secondary>.radialColor1 animatable; alias: Radial_Color_1 <auto_secondary>.radialColor2 animatable; alias: Radial_Color_2 <auto_secondary>.radialColor3 animatable; alias: Radial_Color_3 <auto_secondary>.radialColor4 animatable; alias: Radial_Color_4 <auto_secondary>.colorRadius1 animatable; alias: Radius_Color_1 <auto_secondary>.colorRadius2 animatable; alias: Radius_Color_2 <auto_secondary>.colorRadius3 animatable; alias: Radius_Color_3 <auto_secondary>.colorRadius4 animatable; alias: Radius_Color_4 <auto_secondary>.radialMtl Radial_Material <auto_secondary>.useRadialMtl Apply_Radial_Color_Map <auto_secondary>.radial_falloff String Boolean Float Float Float Float Integer Float Integer Float Integer Boolean Color Color Color Color Float Float Float Float TextureMap Boolean SubAnim default: Auto Secondary -default: true default: 25.0 default: 100.0 default: 3.0 default: 30.0 default: 12 default: 20.0 default: 0 default: 100.0 default: 0 default: false default: (color 0 0 0) -default: (color 57 34 89) -default: (color 85 139 85) -default: (color 190 99 10) -default: 90.0 default: 92.0 default: 95.0 default: 98.0 default: undefined default: false ------ alias: -- alias: --

-------

sides = 0 - Circular; 1 - Three; 2 - Four; 3 - Five; 4 - Six; 5 - Seven; 6 - Eight

presets selects a preset from the indexed list. presets = 0 - no preset.

Lens_Effects - Auto_Secondary

1361

<auto_secondary>.radialMap Radial_Falloff_Map <auto_secondary>.useRadialMap Apply_Radial_Falloff_Map <auto_secondary>.circularColorMix animatable; alias: Circular_Color_Mix <auto_secondary>.quadrant1Color animatable; alias: Quadrant_1_Color <auto_secondary>.quadrant2Color animatable; alias: Quadrant_2_Color <auto_secondary>.quadrant3Color animatable; alias: Quadrant_3_Color <auto_secondary>.quadrant4Color animatable; alias: Quadrant_4_Color <auto_secondary>.circularMtl Circular_Material <auto_secondary>.useCircularMtl Apply_Circular_Color_Map <auto_secondary>.circular_falloff <auto_secondary>.circularMap Circular_Falloff_Map <auto_secondary>.useCircularMap Apply_Circular_Falloff_Map <auto_secondary>.radial_size <auto_secondary>.radialSizeMap Radial_Size_Map <auto_secondary>.useRadialSizeMap Apply_Radial_Size_Map <auto_secondary>.applyLights Apply_to_Lights <auto_secondary>.applyImage Apply_to_Image <auto_secondary>.applyImageCenters Apply_to_Image_Centers <auto_secondary>.sourceObjectID Source_Object_ID <auto_secondary>.objectID animatable; alias: Object_ID <auto_secondary>.sourceEffectsID Source_Effects_ID <auto_secondary>.effectsID animatable; alias: Effects_ID <auto_secondary>.sourceUnclampedColor Source_Unclamped_Color <auto_secondary>.unclampedColor animatable; alias: Unclamped_Color <auto_secondary>.unclampedColorInvert Source_Unclamped_Color_Invert <auto_secondary>.sourceSurfaceNormal Source_Surface_Normal

TextureMap Boolean Float Color Color Color Color TextureMap Boolean SubAnim TextureMap Boolean SubAnim TextureMap Boolean Boolean Boolean Boolean Boolean Integer Boolean Integer Boolean Float Boolean Boolean

default: undefined default: false default: 0.0

-- alias: -- alias: ------

default: (color 255 0 0) default: (color 255 0 0) default: (color 255 0 0) default: (color 255 0 0) default: undefined default: false

-- alias: -- alias:

default: undefined default: false

-- alias: -- alias:

default: undefined default: false default: true default: false default: false default: false default: 1 default: false default: 0 default: false default: 1.0 default: false default: false

-- alias: -- alias: -- alias: -- alias: -- alias: -- alias: --- alias: --- alias: --- alias: -- alias:

1362

Chapter 11

3ds max Objects

<auto_secondary>.surfaceNormal animatable; alias: Surface_Normal <auto_secondary>.surfaceNormalInvert Source_Surface_Normal_Invert <auto_secondary>.sourceWhole Source_Whole <auto_secondary>.sourceAlpha Source_Alpha <auto_secondary>.alpha <auto_secondary>.sourceZBuffer Source_Z_Buffer <auto_secondary>.zHi animatable; alias: Z_Hi <auto_secondary>.zLo animatable; alias: Z_Lo <auto_secondary>.filterAll Filter_All <auto_secondary>.filterEdge Filter_Edge <auto_secondary>.filterPerimeterAlpha Filter_Perimeter_Alpha <auto_secondary>.filterPerimeter Filter_Perimeter <auto_secondary>.filterBrightness Filter_Brightness <auto_secondary>.brightness animatable; alias: Bright <auto_secondary>.brightnessInvert Filter_Brightness_Invert <auto_secondary>.filterHue Filter_Hue <auto_secondary>.hueRange animatable; alias: Hue_Range <auto_secondary>.hue animatable <auto_secondary>.applyNoise Apply_Additional_Effects <auto_secondary>.noiseMap Noise_Map <auto_secondary>.radial_density <auto_secondary>.radialDensity Radial_Density_Map <auto_secondary>.useRadialDensity Apply_Radial_Density_Map <auto_secondary.radial_falloff>.curve_1

Float Boolean Boolean Boolean Integer Boolean Float Float Boolean Boolean Boolean Boolean Boolean Integer Boolean Boolean Integer Color Boolean TextureMap SubAnim TextureMap Boolean

default: 0.0 default: false default: false default: false default: 0 default: false default: 1000.0 default: 0.0 default: true default: false default: false default: false default: false default: 0 default: false default: false default: 0

--- alias: -- alias: -- alias:

-- alias: ---- alias: -- alias: -- alias: -- alias: -- alias: --- alias: -- alias: --

default: (color 255 0 0) -default: false default: undefined -- alias: -- alias:

default: undefined default: false

-- alias: -- alias:

SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

Lens_Effects - Glow

1363

<auto_secondary.circular_falloff>.curve_1

SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<auto_secondary.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<auto_secondary.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. Note: The le.addASec <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for auto_secondary elements is auto_secondary. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

See also
Lens_Effects : RenderEffect (p. 1357) Value Common Properties, Operators, and Methods (p. 714)

Lens_Effects - Glow
Constructor:
le.addGlow <Lens_Effects>

Properties:
<glow>.elementName String <glow>.on Boolean <glow>.size Float <glow>.intensity Float <glow>.objectsHide Boolean <glow>.occlusion Float <glow>.squeeze Boolean <glow>.useSourceColor Float Source_Color <glow>.centerColor Color animatable; alias: Center_Color <glow>.edgeColor Color alias: Edge_Color default: default: default: default: default: default: default: default: Glow true 30.0 110.0 true 100.0 false 0.0 -- alias: Name ----animatable animatable alias: Object_Hide animatable

-- animatable; alias:

default: (color 255 255 255) -default: (color 255 0 0) -- animatable;

1364

Chapter 11

3ds max Objects

<glow>.radialMtl Radial_Material <glow>.useRadialMtl Apply_Radial_Color_Map <glow>.radial_falloff <glow>.radialMap Radial_Falloff_Map <glow>.useRadialMap Apply_Radial_Falloff_Map <glow>.circularColorMix Circular_Color_Mix <glow>.quadrant1Color alias: Quadrant_1_Color <glow>.quadrant2Color alias: Quadrant_2_Color <glow>.quadrant3Color alias: Quadrant_3_Color <glow>.quadrant4Color alias: Quadrant_4_Color <glow>.circularMtl Circular_Material <glow>.useCircularMtl Apply_Circular_Color_Map <glow>.circular_falloff <glow>.circularMap Circular_Falloff_Map <glow>.useCircularMap Apply_Circular_Falloff_Map <glow>.radial_size <glow>.radialSizeMap Radial_Size_Map <glow>.useRadialSizeMap Apply_Radial_Size_Map <glow>.applyLights Apply_to_Lights <glow>.applyImage Apply_to_Image <glow>.applyImageCenters Apply_to_Image_Centers <glow>.sourceObjectID Source_Object_ID <glow>.objectID Object_ID <glow>.sourceEffectsID Source_Effects_ID <glow>.effectsID Effects_ID <glow>.sourceUnclampedColor Source_Unclamped_Color <glow>.unclampedColor Unclamped_Color

TextureMap Boolean SubAnim TextureMap Boolean Float Color Color Color Color TextureMap Boolean SubAnim TextureMap Boolean SubAnim TextureMap Boolean Boolean Boolean Boolean Boolean Integer Boolean Integer Boolean Float

default: undefined default: false

-- alias: -- alias:

default: undefined default: false default: 0.0

-- alias: -- alias: -- animatable; alias:

default: (color 255 0 0) -- animatable; default: (color 255 0 0) -- animatable; default: (color 255 0 0) -- animatable; default: (color 255 0 0) -- animatable; default: undefined default: false -- alias: -- alias:

default: undefined default: false

-- alias: -- alias:

default: undefined default: false default: true default: true default: false default: false default: 1 default: false default: 1 default: false default: 1.0

-- alias: -- alias: -- alias: -- alias: -- alias: -- alias: -- animatable; alias: -- alias: -- animatable; alias: -- alias: -- animatable; alias:

Lens_Effects - Glow

1365

<glow>.unclampedColorInvert Boolean Source_Unclamped_Color_Invert <glow>.sourceSurfaceNormal Boolean Source_Surface_Normal <glow>.surfaceNormal Float Surface_Normal <glow>.surfaceNormalInvert Boolean Source_Surface_Normal_Invert <glow>.sourceWhole Boolean Source_Whole <glow>.sourceAlpha Boolean Source_Alpha <glow>.alpha Integer <glow>.sourceZBuffer Boolean Source_Z_Buffer <glow>.zHi Float Z_Hi <glow>.zLo Float Z_Lo <glow>.filterAll Boolean <glow>.filterEdge Boolean <glow>.filterPerimeterAlpha Boolean Filter_Perimeter_Alpha <glow>.filterPerimeter Boolean Filter_Perimeter <glow>.filterBrightness Boolean Filter_Brightness <glow>.brightness Integer Bright <glow>.brightnessInvert Boolean Filter_Brightness_Invert <glow>.filterHue Boolean <glow>.hueRange Integer Hue_Range <glow>.hue Color <glow>.applyNoise Boolean Apply_Additional_Effects <glow>.noiseMap TextureMap <glow>.radial_density SubAnim <glow>.radialDensity TextureMap Radial_Density_Map <glow>.useRadialDensity Boolean Apply_Radial_Density_Map <glow.radial_falloff>.curve_1

default: false default: false default: 0.0 default: false default: false default: false default: 0 default: false default: 1000.0 default: 0.0 default: true default: false default: false default: false default: false default: 0 default: false default: false default: 0

-- alias: -- alias: -- animatable; alias: -- alias: -- alias: -- alias: -- animatable -- alias: -- animatable; alias: -- animatable; alias: -- alias: Filter_All -- alias: Filter_Edge -- alias: -- alias: -- alias: -- animatable; alias: -- alias: -- alias: Filter_Hue -- animatable; alias:

default: (color 255 0 0) -- animatable default: false -- alias: default: undefined default: undefined default: false -- alias: Noise_Map -- alias: -- alias:

SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

1366

Chapter 11

3ds max Objects

<glow.circular_falloff>.curve_1

SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<glow.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<glow.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. Note: The le.addGlow <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for glow elements is glow. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

See also
Lens_Effects : RenderEffect (p. 1357) Value Common Properties, Operators, and Methods (p. 714)

Lens_Effects - Manual_Secondary
Constructor:
le.addMSec <Lens_Effects>

Properties:
<manual_secondary>.elementName Secondary -- alias: Name <manual_secondary>.on <manual_secondary>.size animatable <manual_secondary>.intensity animatable <manual_secondary>.plane animatable <manual_secondary>.colorSource animatable; alias: Source_Color <manual_secondary>.sides String Boolean Float Float Float Float Integer default: Manual default: true default: 50.0 default: 30.0 default: 150.0 default: 20.0 default: 0

-----

sides = 0 - Circular; 1 - Three; 2 - Four; 3 - Five; 4 - Six; 5 - Seven; 6 - Eight

Lens_Effects - Manual_Secondary

1367

<manual_secondary>.occlusion animatable <manual_secondary>.squeeze <manual_secondary>.presets <manual_secondary>.radialColor1 animatable; alias: Radial_Color_1 <manual_secondary>.radialColor2 animatable; alias: Radial_Color_2 <manual_secondary>.radialColor3 animatable; alias: Radial_Color_3 <manual_secondary>.radialColor4 animatable; alias: Radial_Color_4 <manual_secondary>.colorRadius1 animatable; alias: Radius_Color_1 <manual_secondary>.colorRadius2 animatable; alias: Radius_Color_2 <manual_secondary>.colorRadius3 animatable; alias: Radius_Color_3 <manual_secondary>.colorRadius4 animatable; alias: Radius_Color_4 <manual_secondary>.radialMtl Radial_Material <manual_secondary>.useRadialMtl Apply_Radial_Color_Map <manual_secondary>.radial_falloff <manual_secondary>.radialMap Radial_Falloff_Map <manual_secondary>.useRadialMap Apply_Radial_Falloff_Map <manual_secondary>.circularColorMix animatable; alias: Circular_Color_Mix <manual_secondary>.quadrant1Color animatable; alias: Quadrant_1_Color <manual_secondary>.quadrant2Color animatable; alias: Quadrant_2_Color <manual_secondary>.quadrant3Color animatable; alias: Quadrant_3_Color <manual_secondary>.quadrant4Color animatable; alias: Quadrant_4_Color <manual_secondary>.circularMtl Circular_Material <manual_secondary>.useCircularMtl Apply_Circular_Color_Map <manual_secondary>.circular_falloff <manual_secondary>.circularMap Circular_Falloff_Map <manual_secondary>.useCircularMap Apply_Circular_Falloff_Map <manual_secondary>.radial_size

Float Boolean Integer Color Color Color Color Float Float Float Float TextureMap Boolean SubAnim TextureMap Boolean Float Color Color Color Color TextureMap Boolean SubAnim TextureMap Boolean SubAnim

default: 100.0 default: false default: 0

--

presets selects a preset from the indexed list. presets = 0 - no preset.

default: (color 0 0 0) -default: (color 57 34 89) -default: (color 85 139 85) -default: (color 190 99 10) -default: 90.0 default: 92.0 default: 95.0 default: 98.0 default: undefined default: false ------ alias: -- alias:

default: undefined default: false default: 0.0

-- alias: -- alias: --

default: (color 255 0 0) -default: (color 255 0 0) -default: (color 255 0 0) -default: (color 255 0 0) -default: undefined default: false -- alias: -- alias:

default: undefined default: false

-- alias: -- alias:

1368

Chapter 11

3ds max Objects

<manual_secondary>.radialSizeMap Radial_Size_Map <manual_secondary>.useRadialSizeMap Apply_Radial_Size_Map <manual_secondary>.applyLights Apply_to_Lights <manual_secondary>.applyImage Apply_to_Image <manual_secondary>.applyImageCenters Apply_to_Image_Centers <manual_secondary>.sourceObjectID Source_Object_ID <manual_secondary>.objectID animatable; alias: Object_ID <manual_secondary>.sourceEffectsID Source_Effects_ID <manual_secondary>.effectsID animatable; alias: Effects_ID <manual_secondary>.sourceUnclampedColor Source_Unclamped_Color <manual_secondary>.unclampedColor animatable; alias: Unclamped_Color <manual_secondary>.unclampedColorInvert Source_Unclamped_Color_Invert <manual_secondary>.sourceSurfaceNormal Source_Surface_Normal <manual_secondary>.surfaceNormal animatable; alias: Surface_Normal <manual_secondary>.surfaceNormalInvert Source_Surface_Normal_Invert <manual_secondary>.sourceWhole Source_Whole <manual_secondary>.sourceAlpha Source_Alpha <manual_secondary>.alpha <manual_secondary>.sourceZBuffer Source_Z_Buffer <manual_secondary>.zHi animatable; alias: Z_Hi <manual_secondary>.zLo animatable; alias: Z_Lo <manual_secondary>.filterAll Filter_All <manual_secondary>.filterEdge Filter_Edge <manual_secondary>.filterPerimeterAlpha Filter_Perimeter_Alpha <manual_secondary>.filterPerimeter Filter_Perimeter <manual_secondary>.filterBrightness Filter_Brightness

TextureMap Boolean Boolean Boolean Boolean Boolean Integer Boolean Integer Boolean Float Boolean Boolean Float Boolean Boolean Boolean Integer Boolean Float Float Boolean Boolean Boolean Boolean Boolean

default: undefined default: false default: true default: false default: false default: false default: 1 default: false default: 0 default: false default: 1.0 default: false default: false default: 0.0 default: false default: false default: false default: 0 default: false default: 1000.0 default: 0.0 default: true default: false default: false default: false default: false

-- alias: -- alias: -- alias: -- alias: -- alias: -- alias: --- alias: --- alias: --- alias: -- alias: --- alias: -- alias: -- alias:

-- alias: ---- alias: -- alias: -- alias: -- alias: -- alias:

Lens_Effects - Manual_Secondary

1369

<manual_secondary>.brightness animatable; alias: Bright <manual_secondary>.brightnessInvert Filter_Brightness_Invert <manual_secondary>.filterHue Filter_Hue <manual_secondary>.hueRange animatable; alias: Hue_Range <manual_secondary>.hue animatable <manual_secondary>.applyNoise Apply_Additional_Effects <manual_secondary>.noiseMap Noise_Map <manual_secondary>.radial_density <manual_secondary>.radialDensity Radial_Density_Map <manual_secondary>.useRadialDensity Apply_Radial_Density_Map <manual_secondary.radial_falloff>.curve_1

Integer Boolean Boolean Integer Color Boolean TextureMap SubAnim TextureMap Boolean

default: 0 default: false default: false default: 0

--- alias: -- alias: --

default: (color 255 0 0) -default: false default: undefined -- alias: -- alias:

default: undefined default: false

-- alias: -- alias:

SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<manual_secondary.circular_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<manual_secondary.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<manual_secondary.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. Note: The le.addMSec <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for manual_secondary elements is manual_secondary. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

1370

Chapter 11

3ds max Objects

See also
Lens_Effects : RenderEffect (p. 1357) Value Common Properties, Operators, and Methods (p. 714)

Lens_Effects - Ray
Constructor:
le.addRay <Lens_Effects>

Properties:
<ray>.elementName <ray>.on <ray>.size <ray>.intensity <ray>.number Quantity <ray>.angle <ray>.sharpness <ray>.objectsHide <ray>.occlusion <ray>.squeeze <ray>.colorSource Source_Color <ray>.centerColor alias: Center_Color <ray>.edgeColor alias: Edge_Color <ray>.radialMtl Radial_Material <ray>.useRadialMtl Apply_Radial_Color_Map <ray>.radial_falloff <ray>.radialMap Radial_Falloff_Map <ray>.useRadialMap Apply_Radial_Falloff_Map <ray>.circularColorMix Circular_Color_Mix <ray>.quadrant1Color alias: Quadrant_1_Color <ray>.quadrant2Color alias: Quadrant_2_Color <ray>.quadrant3Color alias: Quadrant_3_Color <ray>.quadrant4Color alias: Quadrant_4_Color <ray>.circularMtl Circular_Material String Boolean Float Float Integer Float Float Boolean Float Boolean Float Color Color TextureMap Boolean SubAnim TextureMap Boolean Float Color Color Color Color TextureMap default: default: default: default: default: default: default: default: default: default: default: Ray true 300.0 10.0 100 0.0 8.0 false 100.0 false 100.0 -- alias: Name -- animatable -- animatable -- animatable; alias: -- animatable -- animatable -- animatable -- animatable; alias:

default: (color 255 255 255) -- animatable; default: (color 255 0 0) -- animatable; default: undefined default: false -- alias: -- alias:

default: undefined default: false default: 0.0

-- alias: -- alias: -- animatable; alias:

default: (color 255 0 0) -- animatable; default: (color 255 0 0) -- animatable; default: (color 255 0 0) -- animatable; default: (color 255 0 0) -- animatable; default: undefined

Lens_Effects - Ray

1371

<ray>.useCircularMtl Boolean Apply_Circular_Color_Map <ray>.circular_falloff SubAnim <ray>.circularMap TextureMap Circular_Falloff_Map <ray>.useCircularMap Boolean Apply_Circular_Falloff_Map <ray>.radial_size SubAnim <ray>.radialSizeMap TextureMap Radial_Size_Map <ray>.useRadialSizeMap Boolean Apply_Radial_Size_Map <ray>.applyLights Boolean Apply_to_Lights <ray>.applyImage Boolean Apply_to_Image <ray>.applyImageCenters Boolean Apply_to_Image_Centers <ray>.sourceObjectID Boolean Source_Object_ID <ray>.objectID Integer Object_ID <ray>.sourceEffectsID Boolean Source_Effects_ID <ray>.effectsID Integer Effects_ID <ray>.sourceUnclampedColor Boolean Source_Unclamped_Color <ray>.unclampedColor Float Unclamped_Color <ray>.unclampedColorInvert Boolean Source_Unclamped_Color_Invert <ray>.sourceSurfaceNormal Boolean Source_Surface_Normal <ray>.surfaceNormal Float Surface_Normal <ray>.surfaceNormalInvert Boolean Source_Surface_Normal_Invert <ray>.sourceWhole Boolean <ray>.sourceAlpha Boolean <ray>.alpha Integer <ray>.sourceZBuffer Boolean Source_Z_Buffer <ray>.zHi Float Z_Hi <ray>.zLo Float Z_Lo <ray>.filterAll Boolean <ray>.filterEdge Boolean <ray>.filterPerimeterAlpha Boolean Filter_Perimeter_Alpha

default: false

-- alias:

default: undefined default: false

-- alias: -- alias:

default: undefined default: false default: true default: true default: false default: false default: 1 default: false default: 1 default: false default: 1.0 default: false default: false default: 0.0 default: false default: default: default: default: false false 0 false

-- alias: -- alias: -- alias: -- alias: -- alias: -- alias: -- animatable; alias: -- alias: -- animatable; alias: -- alias: -- animatable; alias: -- alias: -- alias: -- animatable; alias: -- alias: ----alias: Source_Whole alias: Source_Alpha animatable alias:

default: 1000.0 default: 0.0 default: true default: false default: false

-- animatable; alias: -- animatable; alias: -- alias: Filter_All -- alias: Filter_Edge -- alias:

1372

Chapter 11

3ds max Objects

<ray>.filterPerimeter Filter_Perimeter <ray>.filterBrightness Filter_Brightness <ray>.brightness Bright <ray>.brightnessInvert Filter_Brightness_Invert <ray>.filterHue <ray>.hueRange Hue_Range <ray>.hue <ray>.applyNoise Apply_Additional_Effects <ray>.noiseMap <ray>.radial_density <ray>.radialDensity Radial_Density_Map <ray>.useRadialDensity Apply_Radial_Density_Map <ray.radial_falloff>.curve_1

Boolean Boolean Integer Boolean Boolean Integer Color Boolean TextureMap SubAnim TextureMap Boolean

default: false default: false default: 0 default: false default: false default: 0

-- alias: -- alias: -- animatable; alias: -- alias: -- alias: Filter_Hue -- animatable; alias:

default: (color 255 0 0) -- animatable default: false -- alias: default: undefined default: undefined default: false -- alias: Noise_Map -- alias: -- alias:

SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<ray.circular_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<ray.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<ray.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. Note: The le.addRay <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for ray elements is ray. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

Lens_Effects - Ring

1373

See also
Lens_Effects : RenderEffect (p. 1357) Value Common Properties, Operators, and Methods (p. 714)

Lens_Effects - Ring
Constructor:
le.addRing <Lens_Effects>

Properties:
<ring>.elementName String <ring>.on Boolean <ring>.size Float <ring>.intensity Float <ring>.plane Float <ring>.thickness Float <ring>.objectsHide Boolean <ring>.occlusion Float <ring>.squeeze Boolean <ring>.colorSource Float Source_Color <ring>.centerColor Color animatable; alias: Center_Color <ring>.edgeColor Color alias: Edge_Color <ring>.radialMtl TextureMap Radial_Material <ring>.useRadialMtl Boolean Apply_Radial_Color_Map <ring>.radial_falloff SubAnim <ring>.radialMap TextureMap Radial_Falloff_Map <ring>.useRadialMap Boolean Apply_Radial_Falloff_Map <ring>.circularColorMix Float Circular_Color_Mix <ring>.quadrant1Color Color alias: Quadrant_1_Color <ring>.quadrant2Color Color alias: Quadrant_2_Color <ring>.quadrant3Color Color alias: Quadrant_3_Color <ring>.quadrant4Color Color alias: Quadrant_4_Color <ring>.circularMtl TextureMap Circular_Material <ring>.useCircularMtl Boolean Apply_Circular_Color_Map <ring>.circular_falloff SubAnim default: default: default: default: default: default: default: default: default: default: Ring true 75.0 75.0 0.0 10.0 false 100.0 false 0.0 -- alias: Name ------animatable animatable animatable animatable alias: Object_Hide animatable

-- animatable; alias:

default: (color 255 255 255) -default: (color 255 0 0) -- animatable; default: undefined default: false -- alias: -- alias:

default: undefined default: false default: 0.0

-- alias: -- alias: -- animatable; alias:

default: (color 255 0 0) -- animatable; default: (color 255 0 0) -- animatable; default: (color 255 0 0) -- animatable; default: (color 255 0 0) -- animatable; default: undefined default: false -- alias: -- alias:

1374

Chapter 11

3ds max Objects

<ring>.circularMap TextureMap Circular_Falloff_Map <ring>.useCircularMap Boolean Apply_Circular_Falloff_Map <ring>.radial_size SubAnim <ring>.radialSizeMap TextureMap Radial_Size_Map <ring>.useRadialSizeMap Boolean Apply_Radial_Size_Map <ring>.applyLights Boolean Apply_to_Lights <ring>.applyImage Boolean Apply_to_Image <ring>.applyImageCenters Boolean Apply_to_Image_Centers <ring>.sourceObjectID Boolean Source_Object_ID <ring>.objectID Integer Object_ID <ring>.sourceEffectsID Boolean Source_Effects_ID <ring>.effectsID Integer Effects_ID <ring>.sourceUnclampedColor Boolean Source_Unclamped_Color <ring>.unclampedColor Float Unclamped_Color <ring>.unclampedColorInvert Boolean Source_Unclamped_Color_Invert <ring>.sourceSurfaceNormal Boolean Source_Surface_Normal <ring>.surfaceNormal Float Surface_Normal <ring>.surfaceNormalInvert Boolean Source_Surface_Normal_Invert <ring>.sourceWhole Boolean Source_Whole <ring>.sourceAlpha Boolean Source_Alpha <ring>.alpha Integer <ring>.sourceZBuffer Boolean Source_Z_Buffer <ring>.zHi Float Z_Hi <ring>.zLo Float Z_Lo <ring>.filterAll Boolean <ring>.filterEdge Boolean <ring>.filterPerimeterAlpha Boolean Filter_Perimeter_Alpha

default: undefined default: false

-- alias: -- alias:

default: undefined default: false default: true default: true default: false default: false default: 1 default: false default: 1 default: false default: 1.0 default: false default: false default: 0.0 default: false default: false default: false default: 0 default: false default: 1000.0 default: 0.0 default: true default: false default: false

-- alias: -- alias: -- alias: -- alias: -- alias: -- alias: -- animatable; alias: -- alias: -- animatable; alias: -- alias: -- animatable; alias: -- alias: -- alias: -- animatable; alias: -- alias: -- alias: -- alias: -- animatable -- alias: -- animatable; alias: -- animatable; alias: -- alias: Filter_All -- alias: Filter_Edge -- alias:

Lens_Effects - Ring

1375

<ring>.filterPerimeter Filter_Perimeter <ring>.filterBrightness Filter_Brightness <ring>.brightness Bright <ring>.brightnessInvert Filter_Brightness_Invert <ring>.filterHue <ring>.hueRange Hue_Range <ring>.hue <ring>.applyNoise Apply_Additional_Effects <ring>.noiseMap <ring>.radial_density <ring>.radialDensity Radial_Density_Map <ring>.useRadialDensity Apply_Radial_Density_Map <ring.radial_falloff>.curve_1

Boolean Boolean Integer Boolean Boolean Integer Color Boolean TextureMap SubAnim TextureMap Boolean

default: false default: false default: 0 default: false default: false default: 0

-- alias: -- alias: -- animatable; alias: -- alias: -- alias: Filter_Hue -- animatable; alias:

default: (color 255 0 0) -- animatable default: false -- alias: default: undefined default: undefined default: false -- alias: Noise_Map -- alias: -- alias:

SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<ring.circular_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<ring.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<ring.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. Note: The le.addRing <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for ring elements is ring. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

1376

Chapter 11

3ds max Objects

See also
Lens_Effects : RenderEffect (p. 1357) Value Common Properties, Operators, and Methods (p. 714)

Lens_Effects - Star
Constructor:
le.addStar <Lens_Effects>

Properties:
<star>.elementName String <star>.on Boolean <star>.size Float <star>.intensity Float <star>.width Float <star>.angle Float <star>.taper Float <star>.sharp Float Sharpness <star>.quantity Integer <star>.objectsHide Boolean <star>.occlusion Float <star>.squeeze Boolean <star>.colorSource Float Source_Color <star>.centerColor Color alias: Center_Color <star>.edgeColor Color animatable; alias: Edge_Color <star>.radialMtl TextureMap Radial_Material <star>.useRadialMtl Boolean Apply_Radial_Color_Map <star>.radial_falloff SubAnim <star>.radialMap TextureMap Radial_Falloff_Map <star>.useRadialMap Boolean Apply_Radial_Falloff_Map <star>.circularColorMix Float Circular_Color_Mix <star>.leftSectionColor Color alias: Left_Section_Color <star>.centerSectionColor Color animatable; alias: Center_Section_Color <star>.rightSectionColor Color alias: Right_Section_Color <star>.circularMtl TextureMap Circular_Material default: default: default: default: default: default: default: default: default: default: default: default: default: Star true 200.0 20.0 8.0 0.0 0.5 9.5 6 false 50.0 false 100.0 -- alias: Name ------animatable animatable animatable animatable animatable animatable; alias:

-- animatable -- alias: Object_Hide -- animatable -- animatable; alias:

default: (color 0 0 255) -- animatable; default: (color 255 255 255) -default: undefined default: false -- alias: -- alias:

default: undefined default: false default: 0.0

-- alias: -- alias: -- animatable; alias:

default: (color 0 0 255) -- animatable; default: (color 255 255 255) -default: (color 0 0 255) -- animatable; default: undefined -- alias:

Lens_Effects - Star

1377

<star>.useCircularMtl Boolean Apply_Circular_Color_Map <star>.circular_falloff SubAnim <star>.circularMap TextureMap Circular_Falloff_Map <star>.useCircularMap Boolean Apply_Circular_Falloff_Map <star>.radial_size SubAnim <star>.radialSizeMap TextureMap Radial_Size_Map <star>.useRadialSizeMap Boolean Apply_Radial_Size_Map <star>.applyLights Boolean Apply_to_Lights <star>.applyImage Boolean Apply_to_Image <star>.applyImageCenters Boolean Apply_to_Image_Centers <star>.sourceObjectID Boolean Source_Object_ID <star>.objectID Integer Object_ID <star>.sourceEffectsID Boolean Source_Effects_ID <star>.effectsID Integer Effects_ID <star>.sourceUnclampedColor Boolean Source_Unclamped_Color <star>.unclampedColor Float Unclamped_Color <star>.unclampedColorInvert Boolean Source_Unclamped_Color_Invert <star>.sourceSurfaceNormal Boolean Source_Surface_Normal <star>.surfaceNormal Float Surface_Normal <star>.surfaceNormalInvert Boolean Source_Surface_Normal_Invert <star>.sourceWhole Boolean Source_Whole <star>.sourceAlpha Boolean Source_Alpha <star>.alpha Integer <star>.sourceZBuffer Boolean Source_Z_Buffer <star>.zHi Float Z_Hi <star>.zLo Float Z_Lo <star>.filterAll Boolean <star>.filterEdge Boolean

default: false

-- alias:

default: undefined default: false

-- alias: -- alias:

default: undefined default: false default: true default: true default: false default: false default: 1 default: false default: 1 default: false default: 1.0 default: false default: false default: 0.0 default: false default: false default: false default: 0 default: false default: 1000.0 default: 0.0 default: true default: false

-- alias: -- alias: -- alias: -- alias: -- alias: -- alias: -- animatable; alias: -- alias: -- animatable; alias: -- alias: -- animatable; alias: -- alias: -- alias: -- animatable; alias: -- alias: -- alias: -- alias: -- animatable -- alias: -- animatable; alias: -- animatable; alias: -- alias: Filter_All -- alias: Filter_Edge

1378

Chapter 11

3ds max Objects

<star>.filterPerimeterAlpha Filter_Perimeter_Alpha <star>.filterPerimeter Filter_Perimeter <star>.filterBrightness Filter_Brightness <star>.brightness Bright <star>.brightnessInvert Filter_Brightness_Invert <star>.filterHue <star>.hueRange Hue_Range <star>.hue <star>.applyNoise Apply_Additional_Effects <star>.noiseMap <star>.radial_density <star>.radialDensity Radial_Density_Map <star>.useRadialDensity Apply_Radial_Density_Map <star.radial_falloff>.curve_1

Boolean Boolean Boolean Integer Boolean Boolean Integer Color Boolean TextureMap SubAnim TextureMap Boolean

default: false default: false default: false default: 0 default: false default: false default: 0

-- alias: -- alias: -- alias: -- animatable; alias: -- alias: -- alias: Filter_Hue -- animatable; alias:

default: (color 255 0 0) -- animatable default: false -- alias: default: undefined default: undefined default: false -- alias: Noise_Map -- alias: -- alias:

SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<star.circular_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<star.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<star.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. Note: The le.addStar <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for star elements is star. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

Lens_Effects - Streak

1379

See also
Lens_Effects : RenderEffect (p. 1357) Value Common Properties, Operators, and Methods (p. 714)

Lens_Effects - Streak
Constructor:
le.addStreak <Lens_Effects>

Properties:
<streak>.elementName String <streak>.on Boolean <streak>.size Float <streak>.intensity Float <streak>.width Float <streak>.angle Float <streak>.taper Float <streak>.sharp Float alias: Sharpness <streak>.objectsHide Boolean Object_Hide <streak>.occlusion Float <streak>.squeeze Boolean <streak>.colorSource Float alias: Source_Color <streak>.centerColor Color alias: Center_Color <streak>.edgeColor Color animatable; alias: Edge_Color <streak>.radialMtl TextureMap Radial_Material <streak>.useRadialMtl Boolean Apply_Radial_Color_Map <streak>.radial_falloff SubAnim <streak>.radialMap TextureMap Radial_Falloff_Map <streak>.useRadialMap Boolean Apply_Radial_Falloff_Map <streak>.circularColorMix Float alias: Circular_Color_Mix <streak>.quadrant1Color Color alias: Left_Section_Color <streak>.quadrant2Color Color animatable; alias: Center_Section_Color <streak>.quadrant3Color Color alias: Right_Section_Color <streak>.circularMtl TextureMap Circular_Material default: default: default: default: default: default: default: default: Streak true 50.0 30.0 2.0 0.0 0.5 9.8 -- alias: Name ------animatable animatable animatable animatable animatable animatable;

default: false default: 100.0 default: false default: 100.0

-- alias: -- animatable -- animatable;

default: (color 0 0 255) -- animatable; default: (color 255 255 255) -default: undefined default: false -- alias: -- alias:

default: undefined default: false default: 50.0

-- alias: -- alias: -- animatable;

default: (color 0 0 0) -- animatable; default: (color 255 255 255) -default: (color 0 0 0) -- animatable; default: undefined -- alias:

1380

Chapter 11

3ds max Objects

<streak>.useCircularMtl Apply_Circular_Color_Map <streak>.circular_falloff <streak>.circularMap Circular_Falloff_Map <streak>.useCircularMap Apply_Circular_Falloff_Map <streak>.radial_size <streak>.radialSizeMap Radial_Size_Map <streak>.useRadialSizeMap Apply_Radial_Size_Map <streak>.applyLights Apply_to_Lights <streak>.applyImage Apply_to_Image <streak>.applyImageCenters Apply_to_Image_Centers <streak>.sourceObjectID Source_Object_ID <streak>.objectID alias: Object_ID <streak>.sourceEffectsID Source_Effects_ID <streak>.effectsID alias: Effects_ID <streak>.sourceUnclampedColor Source_Unclamped_Color <streak>.unclampedColor alias: Unclamped_Color <streak>.unclampedColorInvert Source_Unclamped_Color_Invert <streak>.sourceSurfaceNormal Source_Surface_Normal <streak>.surfaceNormal alias: Surface_Normal <streak>.surfaceNormalInvert Source_Surface_Normal_Invert <streak>.sourceWhole Source_Whole <streak>.sourceAlpha Source_Alpha <streak>.alpha <streak>.sourceZBuffer Source_Z_Buffer <streak>.zHi alias: Z_Hi <streak>.zLo alias: Z_Lo <streak>.filterAll Filter_All

Boolean SubAnim TextureMap Boolean SubAnim TextureMap Boolean Boolean Boolean Boolean Boolean Integer Boolean Integer Boolean Float Boolean Boolean Float Boolean Boolean Boolean Integer Boolean Float Float Boolean

default: false

-- alias:

default: undefined default: false

-- alias: -- alias:

default: undefined default: false default: true default: true default: false default: false default: 1 default: false default: 1 default: false default: 1.0 default: false default: false default: 0.0 default: false default: false default: false default: 0 default: false default: 1000.0 default: 0.0 default: true

-- alias: -- alias: -- alias: -- alias: -- alias: -- alias: -- animatable; -- alias: -- animatable; -- alias: -- animatable; -- alias: -- alias: -- animatable; -- alias: -- alias: -- alias: -- animatable -- alias: -- animatable; -- animatable; -- alias:

Lens_Effects - Streak

1381

<streak>.filterEdge Filter_Edge <streak>.filterPerimeterAlpha Filter_Perimeter_Alpha <streak>.filterPerimeter Filter_Perimeter <streak>.filterBrightness Filter_Brightness <streak>.brightness alias: Bright <streak>.brightnessInvert Filter_Brightness_Invert <streak>.filterHue Filter_Hue <streak>.hueRange alias: Hue_Range <streak>.hue <streak>.applyNoise Apply_Additional_Effects <streak>.noiseMap <streak>.radial_density <streak>.radialDensity Radial_Density_Map <streak>.useRadialDensity Apply_Radial_Density_Map <streak.radial_falloff>.curve_1

Boolean Boolean Boolean Boolean Integer Boolean Boolean Integer Color Boolean TextureMap SubAnim TextureMap Boolean

default: false default: false default: false default: false default: 0 default: false default: false default: 0

-- alias: -- alias: -- alias: -- alias: -- animatable; -- alias: -- alias: -- animatable;

default: (color 255 0 0) -- animatable default: false -- alias: default: undefined default: undefined default: false -- alias: Noise_Map -- alias: -- alias:

SubAnim

The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<streak.circular_falloff>.curve_1 SubAnim

The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<streak.radial_size>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
<streak.radial_density>.curve_1 SubAnim

The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.

1382

Chapter 11

3ds max Objects

Note: The le.addStreak <Lens_Effects> method returns true if the addition was successful, false if it failed. Once the element has been added, it can be accessed as a property of the lens_effects value. The name of this property for streak elements is streak. If more than one element of the same type is added, only the first is accessible using the property name. You will need to access the remaining elements as subAnims of the lens_effects value. The subAnim names are the same as the property names. The elements start at subAnim 7.

See also
Lens_Effects : RenderEffect (p. 1357) Value Common Properties, Operators, and Methods (p. 714)

Track View Nodes

You can access and modify controllers in the Global Tracks and Video Post sections in Track View, and create new named global tracks. Among other things, these can be used to provide keyframeable parameters in your scripted utilities. There are also methods associated with the Track View window. These methods are described in the Track View (p. 1609) topic. MAXTVNode : Value is the class whose instances represent track view global track nodes. Each MAXTVNode can contain any number of MAXTVNodes or animation controllers. The MAXTVNodes and controllers within a MAXTVNode are shown as properties of the MAXTVNode so you navigate through the nesting using property access. A MAXTVNode itself does not store animation data, but rather acts as a container that can store one or more MAXTVNode or animation controller. There are three track view nodes you can access through global variables: the root node to which you can add new custom tracks; the existing Global Tracks node which provides access to the global track controllers; and the Video Post tracks node which provides access to any video post controllers. These nodes are also accessible as properties on the root node. Constructor:
trackViewNodes

Global variable containing the top-level World, or root, node in Track View. This variable is read-only.
globalTracks

Global variable containing the top-level Global Tracks node in Track View. This variable is read-only.
videoPostTracks

Global variable containing the top-level Video Post Track View node. This variable is readonly. This variable contains the value undefined in 3D Studio VIZ.

Lens_Effects - Streak

1383

newTrackViewNode [ <maxtvnode> ] <name_string> [ #hidden ]

if the <maxtvnode> argument is supplied, adds a sub-track node to it. If not, creates a new top-level track in the Track View. If the optional #hidden flag is supplied, the node is not visible in the Track View. Properties:
<maxtvnode>.name String

the track view node name as it appears in Track View The sub-tracks and sub-controllers for a track view node are also shown as properties of the track view node. For example, the additional default properties for global trackViewNodes are:
TrackViewNodes.Global_Tracks TrackViewNodes.Video_Post MAXTVNode MAXTVNode

And the additional default properties for global globalTracks are:

GlobalTracks.float GlobalTracks.point3 GlobalTracks.position GlobalTracks.rotation GlobalTracks.scale GlobalTracks.Block_Control float_list controller point3_list controller position_list controller rotation_list controller scale_list controller block_control controller

Methods:
deleteTrackViewNode [ <parent_maxtvnode> ] <maxtvnode>

deletes the given node from the supplied parent, or the top-level if the parent is not specified
addTrackViewController <maxtvnode> <controller> <name>

adds the sub-controller to the given Track View node. The

deleteTrackViewController <maxtvnode> <controller>

deletes the controller from the given Track View node

See also
Value Common Properties, Operators, and Methods (p. 714)

1384

Chapter 11

3ds max Objects

Examples: -- access a video post track

videoPost.glow.size = 5

-- set up some visible tracks for some keyframeable parameters in a rollout panel
my_tracks = newTrackViewNode Grinner happy_ctrl = bezier_position() addTrackViewController my_tracks happy_ctrl Happy ... -- plant keyframes in rollout spinner handler if the animate button is on rollout grinner ... ( ... on happy changed val do ( ... happy_ctrl.value = [x, y, z] ... ) ... )

-- add a new float controller to the global tracks float controller list:
globalTracks.float.controller.available.controller = bezier_float()

Working with NURBS

This topic mirrors almost one-for-one on the NURBS API in the 3ds max SDK, so an understanding of one will help with the other. The following topics provide you with information about the NURBS classes and how to work with them: Working with the NURBS Classes (p. 1385) Overview of the Principal NURBS Classes (p. 1386) Using the NURBS Classes and Functions to Create and Modify 3ds max NURBS Models (p. 1389) The NURBS Classes (p. 1401)

Working with the NURBS Classes

1385

Working with the NURBS Classes

Unlike other parts of MAXScript that let you script 3ds max scene objects directly, the NURBS family of classes provides an indirect means of working with 3ds max NURBS objects. They allow you to build an idealized structure representing 3ds max NURBS objects and then use this structure to either create new or add to scene NURBS objects or to access certain parts of existing scene objects. The structure is made up of instances of the MAXScript NURBS classes, listed in the NURBS Classes (p. 1401) topic. The main class for this is NURBSSet. It is the structure that corresponds to a scene NURBS object and contains a collection of NURBS items such as curves, surfaces, dependent surfaces, points, and so on, which are themselves instances of the other MAXScript NURBS classes. You construct a NURBSSet object describing a NURBS object and then have it be instantiated as a real scene object. Conversely, you can ask for a NURBSSet to be created that corresponds to a given scene NURBS object and use it to examine the component NURBS items and to modify certain properties directly on the scene object it describes. Parameter Validity The 3ds max NURBS SDK methods and the corresponding MAXScript methods and properties perform very little parameter validation. As a result, passing invalid parameters to the functions or accessing invalid ranges will generate Assertion Failures easily. In most cases 3ds max will not crash if Retry or Ignore is selected. An example of this is: 1. 2. Create a CV surface and select it. Enter in MAXScript:
s = getnurbsset $ #relational obj = getobject s 1 tess = getviewtess obj #displacement

This is invalid because the viewport does not support displacement approximation, only the production renderer does. Therefore, this will generate an Assertion Failure.

1386

Chapter 11

3ds max Objects

NURBSIds and Indexes An important concept to understand when working with NURBSSets and the other NURBS classes, is the way you identify component items in the set. Before a NURBSet is instantiated as a scene NURBS object, the individual curves and points and surfaces are identified by an index number. As you append objects to the set they are assigned successive indexes, starting at 1. When you want to refer to a particular item, for example to specify the parent surfaces in a blend surface, you use this index. Once an object has been added to a NURBSSet, its index can determined through the .index property. This is a read-only property. However, once a NURBSet is associated with a scene object, either by being instantiated or because it was directly created from an existing scene object, this index is no longer valid. Instead, a different number, called a NURBSId, is assigned to each item and you must use that Id when referring to items from then on. The NURBSId of any item in an instantiated NURBSSet can be obtained through the .NURBSId property on that object. These identifiers, indexes or NURBSIds, are used in many places to specify the parent objects for other dependent objects. Often, these are specified using the .parent or .parentID properties on a dependent object. You must be sure to use the correct property depending on whether the containing NURBSSet has been associated with a scene object or not: .parent for non-associated NURBSSets, .parentID for associated NURBSSets. Remember that indexes used in .parent settings are 1-based.

Overview of the Principal NURBS Classes

The diagram below shows the inheritance tree of the principal classes in the NURBS family. The base classes are shown at the top, and the inheritance hierarchy proceeds toward the bottom and to the right. NURBSObject (p. 1402) is the main base class, with NURBSPoint (p. 1403), NURBSControlVertex (p. 1409), NURBSCurve (p. 1409), NURBSSurface (p. 1425), NURBSCVCurve (p. 1412), and NURBSPointCurve (p. 1418) also functioning as base classes. Several additional classes are used with NURBS objects, but are not part of the NURBS hierarchy. These classes are the NURBSDisplay (p. 1447), NURBSSelection (p. 1448), NURBSSet (p. 1450), NURBSSurfaceApproximation (p. 1453), and NURBSTextureSurface (p. 1455) classes.

Overview of the Principal NURBS Classes

1387

NURBS Class Hierarchy

The NURBSObject class is the base NURBS class. It provides a set of properties that are common to the other classes such as getting and setting the name of the item. It also has a NURBSId property which is an ID used to specify a particular object in communication between the NURBS classes.

1388

Chapter 11

3ds max Objects

The NURBSSet class is the class used when developers want to create 3ds max NURBS objects, or retrieve data from existing 3ds max NURBS objects. The NURBSSet acts as a container for the other objects. This class contains a table of the various NURBSObject derived entities (points, curves, surfaces) used to make up the set. Additionally it has two fuse tables: one for fuse curves and one for fuse surfaces. These are used to allow the CVs in the curves or surfaces to be stitched or fused together so that if one curve or surface moves the other moves with it. This class also has the surfaceapproximation properties that control the objects tessellation into triangle meshes for use in the viewports and the production renderer. The NURBSPoint classes describe a point in 3D space. Depending on the specific class, points can be either independent or dependent. Independent points are those that dont rely on other objects to define their location. Dependent points are related to the objects they depend on such that the relationship established initially remains if the point, curve or surface moves. For example, a point can be created such that it always remains a certain distance from another point. The options are XYZ-relative, along a normal, or along a tangent (or set of tangents for a surface-dependent constrained point). The NURBSControlVertex class defines a Control Vertex of a NURBS Curve or NURBS Surface. This class shares may of the same properties as a NURBSPoint and has the added property of a rational weight. The weight value of a CV is rational. That is, it is relative to other CVs in the curve or surface. Changing the weight of all CVs at once has no effect, because this doesnt change the ratio between weights. The NURBSCurve classes describe the properties of NURBS curves. As with the NURBSPoint classes, depending on the specific class, curves can be either independent or dependent. Independent curves are those that dont rely on other objects to define their location. A dependent curve is an object that depends on one or more other objects to define what it is. For example, a Blend Curve depends on the two parent curves that it blends between when it was created (as well as on its two tension parameters). The NURBSSurface classes describe the properties of NURBS surfaces. As with the NURBSPoint and NURBSCurve classes, depending on the specific class, surfaces can be either independent or dependent. Independent surfaces are those that dont rely on other objects to define their location. Dependent surfaces are surface sub-objects whose geometry depends on other surfaces or curves in the NURBS model. When you change the geometry of the original parent surface or curve, the dependent surface changes as well.

Creating New NURBS Objects

1389

Using the NURBS Classes and Functions to Create and Modify 3ds max NURBS Models
For NURBS objects in the scene, 3ds max uses a different internal representation of NURBS objects than the MAXScript and SDK classes do. These MAXScript and SDK classes are simply a means to access these internal 3ds max NURBS objects and allow them to be manipulated. The object used in communication between the internal 3ds max NURBS objects and the classes in MAXScript available to work with these objects is the NURBSSet (p. 1450). There are also two functions used in this communication. The first is the constructor NURBSNode() and the second is a node method, getNURBSSet(). How these are used is described in the following topics: Creating New NURBS Objects (p. 1389) Modifying Existing NURBS Objects (p. 1390) Parameter Ranges for Curves and Surfaces (p. 1391) Materials Assignment and Texture Coordinates (p. 1391) Creating NURBS Scene Objects (p. 1392) Creating NURBSCVSurface Values (p. 1394) NURBS Node Properties and Methods (p. 1397)

Creating New NURBS Objects

The NURBS classes can be used to create new NURBS scene objects. This is done by adding the objects (points, curves and surfaces) to an item called a NURBSSet and passing it to the function NURBSNode(). The NURBSSet is a container for the objects that define each element in the scene NURBS object. The function NURBSNode() makes an internal 3ds max NURBS object from the specifications in the set. The function NURBSNode() is documented in the Creating NURBS Scene Objects (p. 1392) topic. As an example, consider the following code fragment that creates a NURBSCVCurve object (with NURBSControlVertex sub-objects) and puts it in the scene: Script:
-- create an empty NURBSSet object nset = NURBSSet () -- create a new NURBSCVCurve and set the knots and CVs c = NURBSCVCurve name:CV Curve order:4 numCVs:4 numKnots:8 for k in 1 to 4 do ( setKnot c k 0; setKnot c (k+4) 1 ) cv = NURBSControlVertex [0, 0, 50] setCV c 1 cv cv.pos = [-100, 0, 50] setCV c 2 cv cv.pos = [-100, 100, 50] setCV c 3 cv cv.pos = [0, 100, 50] setCV c 4 cv

1390

Chapter 11

3ds max Objects

-- add the NURBSCVCurve object to the set appendObject nset c -- create the NURBS object from the NURBSSet n = NURBSNode nset name:nurbs01 pos:[10,0,0]

Note that the NURBSSet supplied to the NURBSNode() function will be modified by that function to be a relational representative for the newly created scene node which you can then use to modify the scene object -- you dont have to re-extract a fresh relational NURBSSet.

Modifying Existing NURBS Objects

The classes can also be used to modify the properties of existing NURBS objects in the scene. To gain access to an internal 3ds max NURBS object you must have the data copied into a NURBSSet. This is done using the node method getNURBSSet(). You can then use the methods of the NURBSSet to access the objects. For example, the following sample code attempts to grab the first NURBS sub-object from the first node in the current selection set. It then checks if its a blend surface and if so adjust one of the tension parameters.
-- get the first node in selection node = selection[1]; -- make sure creation has been completed on the node stopCreating node -- get the nurbs set for it getSet = getNURBSSet node #relational -- extract the first obj, check class & set tension obj = getObject getSet 1 if classOf obj == NURBSBlendSurface then obj.tension1 = 2.0

The kinds of modification you can perform in this way are limited to changing those parameters and properties that do not alter the structure of the NURBS scene object -- you can modify point and CV positions, CV weights, dependent object parameters such as offsets and extrude amounts, etc. You cannot add or delete objects, change the number of CVs or knots or parent curves, etc. To do this kind of structural modification, use the appendObject(), setObject(), and removeObject() functions defined in the NURBSSet : Value (p. 1450) topic and the addNURBSSet(), breakSurface(), and similar functions defined in the NURBS Node Properties and Methods (p. 1397) topic. The stopCreating() method is used to ensure that the specified node is fully created. This method is primarily used to ensure that a NURBS scene objects is fully created, which it will not be until the creation is stopped. The NURBSSet returned for a NURBS scene object will not be complete if the object is still in creation mode. This method will also deactivated any activated object create buttons in the Create panel. There are other global functions that may be used to modify NURBS scene objects. These functions are documented in the NURBS Node Properties and Methods (p. 1397) topic. For instance, developers

Parameter Ranges for Curves and Surfaces

1391

can use the function breakSurface() to take an existing NURBS surface and break it into two separate surfaces. Non-relational NURBSSets You can also use the getNURBSSet() function in a non-relational mode, but not supplying the #relational argument, to retrieve a flattened version of the NURBSSet in which all dependent surfaces, such as blends and offsets and lofts are represented as independent curves and surfaces and there is no live connection back to the scene object from which the NURBSSet was derived. You might use this to get a simplified version of the NURBS scene object for an export script, for example if the destination system does not support relational objects. You can also use a non-relational NURBSSet derived in this way as the basis for creating other scene objects, perhaps modifying or adding to the set and then re-instantiating it with the NURBSNode() function.

Parameter Ranges for Curves and Surfaces

Methods that deal with points in the parameter space of a curve work with arguments in U. Methods that deal with points in the parameter space of surfaces deal with arguments in U and V. For example, setting the property <NURBSSurfConstPoint>.uParam sets the position of a dependent point in the parent surfaces U parameter space. The valid U and V values that may be passed to this method must be obtained by referencing the <NURBSSurface> properties .uParameterRangeMin, .uParameterRangeMax, .vParameterRangeMin, and .vParameterRangeMax on the parent surface. This retrieves the minimum and maximum values for U and V that may be used. For curves there are similar properties for getting the valid range for U. Developers should be aware that a curve or surface needs to be instantiated in the 3ds max data base before it is okay to call these methods (for example by calling NURBSNode()). Prior to the object existing in the data base these calls will fail. Generally, when CV curves and surfaces are created, the valid parameter range is known because they were specified in the beginning and ending knot values. In cases where they are not known, one can instantiate a NURBSSet that has just the base curves or surfaces. Once instantiated, the parameter range properties can be interrogated. Then one can build the rest of the parametric model by making additions and/or modifications to the already instantiated object. The node method addNURBSSet() makes this easy to do.

Materials Assignment and Texture Coordinates

Materials and NURBS Each NURBS surface has its own material ID. If you assign a Multi-SubObject material you can apply a different material to each surface in a NURBS object by setting the <NURBSSurface> property .MatID. Texture Coordinates and NURBS Texture coordinates are assigned to each of the four corners of a NURBS surface. On the standard 3ds max primitives for example most are assigned to use (0,0) to (1,1) across the surface. Some

1392

Chapter 11

3ds max Objects

primitives, such as the Prism, dont use (0,0) to (1,1) because of the way they wrap. Developers may of course assign any values using the API. The <NURBSSurface> method to do this is setTextureUVs().

Creating NURBS Scene Objects

The following functions create new nodes in the 3ds max scene. The main function is NURBSNode() which takes an arbitrary NURBSSet and instantiates a NURBS object in the scene based on the definition in the NURBSSet. The other two functions are shorthand ways of creating lathe and extrude NURBS surfaces based on existing shapes in the scene.
NURBSNode <nurbsset> {node_creation_parameters}

Takes a NURBSSet object and creates a 3ds max NURBS object in the scene corresponding to the definitions in that NURBSSet. After the function call, the supplied NURBSSet becomes an active representative for the new scene node, all the NURBSId properties are filled-in and you can modify the scene object by modifying the properties of the NURBSSet component objects. Any of the standard <node> constructor keyword arguments can be added, such as .name, .prefix, .pos, .rotation, .wireColor, etc. See the Node (p. 820) class topic for details.
NURBSLatheNode <curve> <axis> <sweep> [capStart:<boolean>] [capEnd:<boolean>] [capType:<integer>] [weldCore:<boolean>] [flipNormals:<boolean>] [mapCoords:<boolean>] [segs:<integer>] [matIDs:<boolean>] [shapeIDs:<boolean>] {node_creation_parameters} \ \ \ \ \

This function generates a NURBS object based on the specified lathe (surface of revolution) definition and returns a pointer to it. This is used by the lathe modifier.
curve <node>

The shape object to revolve. Note that if the curve pointed to is a bezier spline then capping wont work properly.
axis sweep capStart: <Matrix3> <float> <boolean>

This specifies the axis of revolution. The angle for the surface of revolution in degrees. Specifies if the surface should be capped at the beginning: true to cap; false to leave open.
capEnd: <boolean>

Specifies if the surface should be capped at the ending: true to cap; false to leave open.
capType: weldCore: <integer> <boolean>

This parameter is not currently used and the value specified is ignored. true to collapse any coincident vertices at the center of the surface; otherwise false.

Creating NURBS Scene Objects

1393

flipNormals: mapCoords: segs: matIDs: shapeIDs:

<boolean> <boolean> <integer> <boolean> <boolean>

true to invert the orientation of surface normals; otherwise false. true to generate mapping coordinates; otherwise false. The number of segments in the surface of revolution. If true special material IDs are assigned to the surfaces and caps. If true shape IDs are used. When on, this function uses the material ID values assigned to segments in the spline to be lathed, or curve sub-objects in the NURBS curve to be lathed. This is available only when matIds is true.
NURBSExtrudeNode <shape> <amount> [capStart:<boolean>] \ [capEnd:<boolean>] [capType:<integer>] \ [mapCoords:<boolean>] [matIDs:<boolean>] \ [shapeIDs:<boolean>] {node_creation_parameters}

This function generates a NURBS object based on the specified extrusion definition and returns a pointer to it. This is used by the extrude modifier.
shape <node>

The shape node to extrude. Note that if the shape pointed to is a bezier spline then capping wont work properly.
amount capStart: <float> <boolean>

Specifies the height of the extrusion. Specifies if the surface should be capped at the beginning: true to cap; false to leave open.
capEnd: <boolean>

Specifies if the surface should be capped at the ending: true to cap; false to leave open.
capType: matIDs: shapeIDs: <integer> <boolean> <boolean>

This parameter is not currently used and the value specified is ignored. If true, special material IDs are assigned to the surfaces and caps. If true shape IDs are used. When on, this function uses the material ID values assigned to segments in the spline to be extruded, or curve sub-objects in the NURBS curve to be extruded. This is available only when matIds is true.

1394

Chapter 11

3ds max Objects

Creating NURBSCVSurface Values

The following functions provide shorthand ways to construct NURBSCVSurface values that you can then add to a NURBSSet for creation in the scene.
MakeNURBSLatheSurface <curve> <origin> <north> <start> <end>

This function generates a NURBS surface of revolution given an input curve, origin, up axis, and start and end angles. The output of this function is a NURBS Surface. Note that this is a CV surface that matches the definition, not a relational surface.
curve origin north start end <NURBSCurve> <point3> <point3> <float> <float>

This is the NURBS curve that is revolved. Specifies the origin of the revolution. This is the axis that specified the up direction. This is the start angle of the revolution in radians. This is the end angle of the revolution in radians.
MakeNURBSSphereSurface <radius> <center> <north_axis> <ref_axis> \ <startU> <endU> <startV> <endV> [open:<boolean>]

This function generates a NURBS sphere. The output of this function is a NURBS Surface. Note that this is a CV surface that matches the definition, not a relational surface.
radius center north_axis ref_Axis <float> <Point3> <Point3> <Point3>

The radius of the sphere. The center point of origin of the sphere. This specifies the up axis. Use (Point3 0 0 1) for the Z axis for example. This is the direction of the seam. The sphere primitive uses (Point3 0 -1 0) as this value. The northAxis and refAxis must be perpendicular to one another.
startU endU startV endV open: <float> <float> <float> <float> <boolean>

The start angle for the sphere in the U direction, specified in radians. The end angle for the sphere in the U direction, specified in radians. The start angle for the sphere in the V direction, specified in radians. The end angle for the sphere in the V direction, specified in radians. If true, the surface is closed; otherwise the surface is not closed. Defaults to false.

Creating NURBSCVSurface Values

1395

MakeNURBSCylinderSurface <radius> <height> <origin> <sym_axis> \ <ref_axis> <start> <end> [open:<boolean>]

This function generates a NURBS cylinder. The output of this function is a NURBS Surface. Note that this is a CV surface that matches the definition, not a relational surface.
radius height origin sym_Axis ref_Axis <float> <float> <Point3> <Point3> <Point3>

The radius of the cylinder. The height of the cylinder. The origin of the cylinder. The axis of symmetry. The standard cylinder primitive specifies (Point3 0 0 1). This is the direction of the seam. The standard cylinder primitive specifies (Point3 0 1 0). The symAxis and refAxis must be perpendicular to one another.
start end open: <float> <float>

The start angle in radians. The end angle in radians.

<boolean> \

If true, the surface is closed; otherwise the surface is not closed. Defaults to false.
MakeNURBSConeSurface <radius1> <radius2> <height> <origin> <sym_axis> <ref_axis> <start> <end> [open:<boolean>]

This function generates a NURBS cone surface. The output of this function is a NURBS Surface. Note that this is a CV surface that matches the definition, not a relational surface.
radius1 radius2 height origin sym_Axis ref_Axis <float> <float> <float> <Point3> <Point3> <Point3>

One of the radii of the cone. The other radius of the cone. The height of the cone. The origin of the cone. The axis of symmetry. This is the direction of the seam. The symAxis and refAxis must be perpendicular to one another.

1396

Chapter 11

3ds max Objects

start end open:

<float> <float>

The start angle in radians. The end angle in radians.

<boolean> \ \

If true, the surface is closed; otherwise the surface is not closed. Defaults to false.
MakeNURBSTorusSurface <majorRad> <minorRad> <origin> <sym_axis> <ref_axis> <startU> <endU> <startV> <endV> [open:<boolean>]

This function generates a NURBS torus surface. The output of this function is a NURBS Surface. Note that this is a CV surface that matches the definition, not a relational surface. Note: This surface is not closed surface.
majorRad minorRad origin sym_Axis ref_Axis <float> <float> <Point3> <Point3> <Point3>

This is the radius of the entire donut shape. The is the radius of the tube. The origin of the cone. The axis of symmetry. This is the direction of the seam. The symAxis and refAxis must be perpendicular to one another.
startU endU startV endV open: <float> <float> <float> <float> <boolean>

The start angle of the torus in the U direction. The end angle of the torus in the U direction. The start angle of the torus in the V direction. The end angle of the torus in the V direction. If true, the surface is closed; otherwise the surface is not closed. Defaults to false.

NURBS Node Properties and Methods

1397

NURBS Node Properties and Methods

Properties: There are several properties on <node> objects that give access to sub-object selections in NURBS objects:
<node>.selectedCurveCVs <node>.selectedCurves <node>.selectedImports <node>.selectedPoints <node>.selectedSurfaces <node>.selectedSurfCVs <node>.curveCVs <node>.curves <node>.imports <node>.surfaces <node>.surfCVs <node>.points

These all return a NURBSSelection Value (p. 1448), and enable sub-object manipulation in a manner similar to that provided for Editable Meshes. Methods: The following NURBS-related methods operate on scene nodes:
getNURBSSet <node> [#relational]

This function is used to retrieve a NURBSSet that corresponds to the specified NURBS scene node. This allows access the internal objects inside a 3ds max editable NURBS object. If the optional #relational parameter is not supplied, the returned NURBSSet will contain only independent curves and surfaces, all dependent objects will be decomposed into corresponding independent objects. So for example, if you pass an object that has a relational model (perhaps two CV surfaces and a dependent blend surface) it will decompose them into three CV surfaces. This will be the CV surfaces that represent the two surfaces and the blend, but you wont have the blend relational data. If the #relational argument is supplied, you get back two CV surfaces and a NURBS blend surface and the NURBSSet is an active representative for the scene object -- any changes you make to the properties of its constituent NURBSObjects will be reflected directly in the source scene object.
addNURBSSet <node> <nurbsSet>

This function adds the supplied NURBSSet to the specified NURBS scene object, creating subobjects within the scene node corresponding to the definitions in the NURBSSet. After the function call, the supplied NURBSSet becomes an active representative for the new scene node subobjects, all the NURBSId properties are filled-in and you can modify the associated scene sub-object by modifying the properties of the NURBSSet component objects.

1398

Chapter 11

3ds max Objects

transform <node> <nurbsId_or_Id_array> <matrix3>

Transforms the specified sub-objects by the matrix supplied in the nodes local space. The sub-objects to be transformed are identified by their NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.
breakCurve <node> <nurbsId> <u_param>

Breaks the specified sub-object curve at the parametric point along the curve defined by the <u_param> float argument. The sub-object to be broken is identified by its NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.
breakSurface <node> <nurbsId> (#U | #V) <u_or_v_param>

Breaks the specified sub-object surface at the parametric point defined by the <u_or_v_param> argument in the u or v direction depending on whether #U or #V is supplied for the third argument. The sub-object to be broken is identified by its NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.
joinCurves <node> <nurbsId1> <nurbsId2> <tolerance_float> [flip1:<boolean>] [flip2:<boolean>] \

Joins two curve sub-objects in the specified scene node and makes a single curve out of them. That is, the endpoints of the two curve objects are connected by new segments, and the two original curves are replaced by a single curve. The supplied tolerance is a distance in 3ds max units. If the gap between the curves you are joining is greater than this value, this function creates the join by first creating a blend curve and then joining the three parts. If the gap is less than this value, or if the curves are overlapping or coincident, no blend is created. Creating a blend and then joining the three curves into a single curve is the better technique. The result matches the parent curves well. Without the blend step, the resulting curve can deviate from the parent curves, in order to maintain smoothness. (The amount of deviation depends on how far from tangent the two input curves were at the join.) A problem arises when there is a gap but it is too small. In this case, this function generates the blend but because there isnt enough room for it, the resulting curve has a loop in it. To avoid this loop, set this parameter higher than the gap distance. If you the tolerance to 0.0, the function chooses a value to use for the tolerance. The sub-objects to be joined are identified by their NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.

NURBS Node Properties and Methods

1399

joinSurfaces <node> <nurbsId1> <nurbsId2> <edge1_integer> \ <edge2_integer> <tolerance_float>

Joins two surface sub-objects in the specified scene node and makes a single surface from them. The specified edges of the two surface objects are connected by a new surface, and the two original surfaces are replaced by a single surface. The edges are identified by edge index numbers. The tolerance is a distance in 3ds max units. If the gap between the surfaces you are joining is greater than this value, this function creates the join by first creating a blend surface. If the gap is less than this value, or if the surfaces are overlapping or coincident, 3ds max doesnt create the blend. Creating a blend and then joining the three surfaces into a single surface is the better technique. The result matches the parent surfaces well. Without the blend step, the resulting surface can deviate from the parent surfaces, in order to maintain smoothness. (The amount of deviation depends on how far from tangent the two input surfaces were at the join.) A problem arises when there is a gap but it is too small. In this case, this function generates the blend but because there isnt enough room for it, the resulting surface has a loop in it. To avoid this loop, set the tolerance parameter higher than the gap distance. If you set the tolerance to 0.0, the function chooses a value to use for the tolerance. The sub-objects to be joined are identified by their NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.
makeIndependent <node> <nurbsId>

This function takes a dependent sub-object (fillet, offset, blend, etc.) and turns it into a CV variant of itself such that it is independent (no longer dependent on a parent). The sub-object to be made independent is identified by its NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.
setViewApproximation <node> <surfaceApproximation> setRenderApproximation <node> <surfaceApproximation> setSurfaceDisplay <node> <nurbsdisplay>

These methods work NURBS curve and surface scene nodes. They take instances of the NURBSSurfaceApproximation (p. 1453) and NURBSDisplay (p. 1447) classes and set the display or curve/surface approximation settings of the given NURBS scene node to those specified in the approximation or display control instance.

1400

Chapter 11

3ds max Objects

Associated Methods:
canConvertTo <node> <class>

Allows you to test whether a given node is convertible into a given class. Returns true or false. For example:
if canConvertTo $foo NURBSSurface then ...

The kinds of classes you can convert objects to are the generic editable forms including Mesh, SplineShape, NURBSCurve, NURBSSurface, etc.
convertTo <node> <class> -- mapped

This function is a general form of the existing specific conversion functions such as convertToMesh(), convertToSplineShape(), etc. For example, convertToSplineShape() can be written:
convertTo $circle01 SplineShape

If the conversion is not supported, the function returns the value undefined.
convertToNURBSSurface <node> convertToNURBSCurve <node> -- mapped -- mapped

These functions work on those primitive geometry and shape classes that support conversion to NURBS (such as boxes, spheres, circles, lines, etc.). If an object does not support conversion, the function returns undefined.
isPointSelected <node> <point_index>

Returns true is the specified point is selected, false if not. The definition of a point varies depending on the object type. For meshes, it is the mesh vertex. For a spline, it is the knot. For NURBS objects, it is the vertex or control point.
pointSelection <node> <point_index>

Returns a floating point weighted point selection if the object supports it. Most object types just return 1.0 if the point is selected and 0.0 if not. Only NURBS objects currently support weighted point selection.
stopCreating <node>

This method stops the creation of the current object, if any. This method is primarily used to ensure that a NURBS scene objects is fully created, which it will not be until the creation is stopped. The NURBSSet returned for a NURBS scene object will not be complete if the object is still in creation mode. This method will also deactivated any activated object create buttons in the Create panel.

NURBS Node Properties and Methods

1401

The NURBS Classes

The following topics describe all of the NURBS classes: NURBSObject (p. 1402) NURBSPoint : NURBSObject (p. 1403) NURBSCurveConstPoint : NURBSPoint (p. 1403) NURBSCurveIntersectPoint : NURBSPoint (p. 1404) NURBSCurveSurfaceIntersectPoint : NURBSPoint (p. 1405) NURBSIndependentPoint : NURBSPoint (p. 1406) NURBSPointConstPoint : NURBSPoint (p. 1407) NURBSSurfConstPoint : NURBSPoint (p. 1407) NURBSControlVertex : NURBSObject (p. 1409) NURBSCurve : NURBSObject (p. 1409) NURBSBlendCurve : NURBSCurve (p. 1410) NURBSChamferCurve : NURBSCurve (p. 1411) NURBSCVCurve : NURBSCurve (p. 1412) NURBSCurveOnSurface : NURBSCVCurve (p. 1414) NURBSFilletCurve : NURBSCurve (p. 1415) NURBSIsoCurve : NURBSCurve (p. 1416) NURBSMirrorCurve : NURBSCurve (p. 1417) NURBSOffsetCurve : NURBSCurve (p. 1417) NURBSPointCurve : NURBSCurve (p. 1418) NURBSPointCurveOnSurface : NURBSPointCurve (p. 1419) NURBSProjectNormalCurve : NURBSCurve (p. 1420) NURBSProjectVectorCurve : NURBSCurve (p. 1421) NURBSSurfaceEdgeCurve : NURBSCurve (p. 1422) NURBSSurfaceNormalCurve : NURBSCurve (p. 1422) NURBSSurfSurfIntersectionCurve : NURBSCurve (p. 1423) NURBSXFormCurve : NURBSCurve (p. 1424) NURBSSurface : NURBSObject (p. 1425) NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSBlendSurface : NURBSSurface (p. 1430) NURBSCapSurface : NURBSSurface (p. 1432) NURBSCVSurface : NURBSSurface (p. 1433)

1402

Chapter 11

3ds max Objects

NURBSExtrudeSurface : NURBSSurface (p. 1435) NURBSFilletSurface : NURBSSurface (p. 1436) NURBSLatheSurface : NURBSSurface (p. 1437) NURBSMirrorSurface : NURBSSurface (p. 1437) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSNBlendSurface : NURBSSurface (p. 1439) NURBSOffsetSurface : NURBSSurface (p. 1440) NURBSPointSurface : NURBSSurface (p. 1441) NURBSRuledSurface : NURBSSurface (p. 1442) NURBSULoftSurface : NURBSSurface (p. 1443) NURBSUVLoftSurface : NURBSSurface (p. 1444) NURBSXFormSurface : NURBSSurface (p. 1445) NURBSTexturePoint : NURBSObject (p. 1446) NURBSDisplay : Value (p. 1447) NURBSSelection : Value (p. 1448) NURBSSet : Value (p. 1450) NURBSSurfaceApproximation : Value (p. 1453) NURBSTextureSurface : Value (p. 1455)

NURBSObject Values
This is the parent class for all the NURBS classes and so is not directly constructable. Properties: Because this is a parent class, all the NURBS classes except NURBSSet have the following properties:
<nurbsobject>.name <nurbsobject>.index : string : integer, read-only

The name of the NURBS object Only valid after a NURBSSet is instantiated via NURBSNode() or if the NURBS object is part of a non-relational NURBSSet.
<nurbsobject>.nurbsID : integer, read-only

Only valid after a NURBSSet is instantiated via NURBSNode() or if the NURBS object is part of a relational NURBSSet extracted using getNURBSSet().
<nurbsobject>.selected : boolean

Indicates whether the sub-object in a relational NURBSSet is selected in the NURBS modifier panel in the 3ds max user interface. You can force the selection and deselection of objects by setting this property to true or false.

NURBSPoint : NURBSObject

1403

See also
Value Common Properties, Operators, and Methods (p. 714)

NURBSPoint Classes
NURBSPoint : NURBSObject
This is the parent class for all the NURBS point classes and so is not directly constructable. The class describes a point in 3D space. Properties: All NURBS point classes have the following properties. These properties are both gettable and settable for independent points, and read-only for dependent points. They are always given in the parent NURBS node local coordinate system.
<nurbspoint>.pos <nurbspoint>.x <nurbspoint>.y <nurbspoint>.z : : : : point3 float float float

See also
NURBSPoint (p. 1403) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSCurveConstPoint : NURBSPoint
This class defines a dependent point that lies on a curve or relative to it. The point can either be on the curve or off the curve. If it is on the curve, the U Position is the only control of its location. The U Position specifies a location along the curve (based on the curves local U axis). There are four ways to specify the displacement of the points location relative to the U position: OnObject - the point is actually on the surface of the object. Offset - the point is moved according to a relative (object space) X,Y,Z location. Normal - the point is moved along the direction of the curves normal. (Negative values move it opposite to the normal.) Tangent - the point is moved along the tangent of the U Position. If the value is positive its the tangent that heads in the direction of increasing U value; if negative its the tangent that heads in the direction of decreasing U value.

1404

Chapter 11

3ds max Objects

Constructors:
NURBSCurveConstPoint [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbscurveconstpoint>.parent <nurbscurveconstpoint>.parentID : integer : integer : float : #onObject, #offset, #normal, #tangent : point3 : float : float

The parent curve by NURBSet index. The parent curve by NURBSId.

<nurbscurveconstpoint>.uParam <nurbscurveconstpoint>.type <nurbscurveconstpoint>.offset

Parametric point along the parent curve. Specifies the transform relationship between the point and the curve. Offset vector if an offset type.
<nurbscurveconstpoint>.normal <nurbscurveconstpoint>.uTangent

Distance along the normal if a normal type. Distance along the curve tangent if a tangent type.
<nurbscurveconstpoint>.trimCurve : boolean

If true, trims parent curve at the point.

<nurbscurveconstpoint>.flipTrim : boolean

If true the curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.

See also
NURBSPoint (p. 1403) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSCurveIntersectPoint : NURBSPoint
This class defines a dependent point at the intersection of two curves. Constructors:
NURBSCurveIntersectPoint [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

NURBSCurveSurfaceIntersectPoint : NURBSPoint

1405

Properties:
<nurbscurveintersectpoint>.parent1 : integer : integer : integer : integer : boolean : boolean : boolean

The 1st parent curve by NURBSet index.

<nurbscurveintersectpoint>.parent1ID

The 1st parent curve by NURBSId.

<nurbscurveintersectpoint>.parent2 <nurbscurveintersectpoint>.parent2ID

The 2nd parent curve by NURBSet index. The 2nd parent curve by NURBSId.
<nurbscurveintersectpoint>.trimCurve1 <nurbscurveintersectpoint>.trimCurve2 <nurbscurveintersectpoint>.flipTrim1

If true, trim the 1st parent curve at the intersection. If true, trim the 2nd parent curve at the intersection. If true the 1st parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.
<nurbscurveintersectpoint>.flipTrim2 : boolean

If true the 2nd parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.

See also
NURBSPoint (p. 1403) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSCurveSurfaceIntersectPoint : NURBSPoint
This class defines a dependent point at the intersection of a curve and a surface. Constructors:
NURBSCurveSurfaceIntersectPoint [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbscurvesurfaceintersectpoint>.parent1 : integer : integer : integer

The parent surface by NURBSet index.

<nurbscurvesurfaceintersectpoint>.parent1ID

The parent surface by NURBSId.

<nurbscurvesurfaceintersectpoint>.parent2

The parent curve by NURBSet index.

1406

Chapter 11

3ds max Objects

<nurbscurvesurfaceintersectpoint>.parent2ID

: integer : boolean : boolean

The parent curve by NURBSId.

<nurbscurvesurfaceintersectpoint>.trimCurve

If true, trims parent curve at the point.

<nurbscurvesurfaceintersectpoint>.flipTrim

If true the curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.
<nurbscurvesurfaceintersectpoint>.seed : float

The seed location is a U position along the length of the parent curve.

See also
NURBSPoint (p. 1403) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSIndependentPoint : NURBSPoint
This class defines an independent, free-standing point. Constructors:
NURBSIndependentPoint <point3> getObject <nurbsset> <index> getPoint <nurbspointsurface> <index> getPoint <nurbspointcurve> <index> getPoint <nurbspointcurveonsurface> <index>

Operators:
<nurbsindependentpoint> == <nurbsindependentpoint> <nurbsindependentpoint> != <nurbsindependentpoint>

Properties: There are no additional properties for NURBSIndependentPoint.

See also
NURBSPoint (p. 1403) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSPointConstPoint : NURBSPoint

1407

NURBSPointConstPoint : NURBSPoint
This class defines a dependent point that lies at a point or relative to it. It is a point constrained relative to another point. This can be a point used to define a point surface or point curve, it can be a trim point, or just a point in space. There are two ways to specify the displacement of the points location relative to the U position: OnObject - the point is actually at the parent. Offset - the point is moved according to a relative (object space) X,Y,Z location.
NURBSPointConstPoint [<property>:<val>]...

Constructors: Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbspointconstpoint>.parent <nurbspointconstpoint>.parentID : integer : integer : #onObject, #offset : point3

The parent point by NURBSet index. The parent point by NURBSId.

<nurbspointconstpoint>.type <nurbspointconstpoint>.offset

Offset vector if an offset type.

See also
NURBSPoint (p. 1403) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSSurfConstPoint : NURBSPoint
This class defines a dependent point on a surface or related to it. There are four ways to specify the displacement of the points location relative to the UV position: OnObject - the point is actually on the surface of the object. Offset - the point is offset some distance (specified in object space) from the surface of the object. Normal - the point is offset along the direction of the surfaces normal. (Negative values move it opposite to the normal.) Tangent - the point is offset some U and/or V distance along the tangent from the surface. If the value is positive its the tangent that heads in the direction of increasing parameter value; if negative its the tangent that heads in the direction of decreasing parameter value.

1408

Chapter 11

3ds max Objects

Constructors:
NURBSSurfConstPoint [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbssurfconstpoint>.parent <nurbssurfconstpoint>.parentID : integer : integer : #onObject, #offset, #normal, #tangent : float : float : point3 : float : float : float

The parent surface by NURBSet index. The parent surface by NURBSId.

<nurbssurfconstpoint>.type <nurbssurfconstpoint>.uParam <nurbssurfconstpoint>.vParam <nurbssurfconstpoint>.offset

Parametric position along u direction. Parametric position along v direction. Offset vector if an offset type.
<nurbssurfconstpoint>.normal <nurbssurfconstpoint>.uTangent <nurbssurfconstpoint>.vTangent

Distance along the normal if a normal type. Distance along the u tangent if a tangent type. Distance along the v tangent if a tangent type.

See also
NURBSPoint (p. 1403) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSControlVertex : NURBSObject

1409

NURBSControlVertex Class
NURBSControlVertex : NURBSObject
This class defines an independent Control Vertex of a NURBS Curve or NURBS Surface. This class shares may of the same properties as a NURBSPoint and has the added property of a rational weight. The weight value of a CV is rational. That is, it is relative to other CVs in the curve or surface. Changing the weight of all CVs at once has no effect, because this doesnt change the ratio between weights. Constructors:
NURBSControlVertex <point3> [<weight_float>] getCV <nurbscvcurve> <index> getCV <nurbscvsurface> <u_index> <v_index>

Operators:
<nurbscontrolvertex> == <nurbscontrolvertex> <nurbscontrolvertex> != <nurbscontrolvertex>

Properties:
<nurbscontrolvertex>.weight : float

The weight of the control vertex. This is a value greater than zero. Larger values cause the CV to have a greater effect, thus the curve or surface will try to pass closer to the CV.

See also
NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSCurve Classes
NURBSCurve : NURBSObject
This is the parent class for all the NURBS curve classes and so is not directly constructable. The class describes the common properties of all NURBS curves. This includes its open/closed state, and number of trim points. The evalPos() and evalTangent() methods are used to compute points and tangents on the curve. Properties: All NURBS curve classes have the following properties:
<nurbscurve>.isClosed <nurbscurve>.numTrimPoints : boolean, read-only : integer, read-only

true if the curve is closed, false if open. The number of trim points in the curve.

1410

Chapter 11

3ds max Objects

<nurbscurve>.parameterRangeMin <nurbscurve>.parameterRangeMax

: float, read-only : float, read-only

Contains the minimum and maximum valid values for <u_parm> in the methods associated with NURBS Curves.
<nurbscurve>.matID : integer

The material ID assigned to the curve. Methods: All NURBS curve classes have the following methods:
evalPos <nurbscurve> <u_param>

Returns the position in space of the given parametric point along the curve.
evalTangent <nurbscurve> <u_param>

Returns the tangent vector at the given parametric point along the curve.

See also
NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSBlendCurve : NURBSCurve
This class defines a dependent Blend curve. A Blend curve connects the end of one curve to the end of another, blending the curvature of the parents to create a smooth curve between them. Constructors:
NURBSBlendCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsblendcurve>.parent1 <nurbsblendcurve>.parent1ID <nurbsblendcurve>.parent2 <nurbsblendcurve>.parent2ID <nurbsblendcurve>.flip1 <nurbsblendcurve>.flip2 : integer : integer : integer : integer : boolean : boolean

The 1st parent curve by NURBSet index. The 1st parent curve by NURBSId. The 2nd parent curve by NURBSet index. The 2nd parent curve by NURBSId. true to use the end of 1st parent curve; false to use the beginning, defaults to false. true to use the end of 2nd parent curve; false to use the beginning, defaults to false.

NURBSChamferCurve : NURBSCurve

1411

<nurbsblendcurve>.tension1 <nurbsblendcurve>.tension2

: float : float

The tension value for the 1st parent curve. The tension value for the 2nd parent curve.

See also
NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSChamferCurve : NURBSCurve
This class defines a dependent Chamfer curve. A Chamfer is a curve that creates a straight line corner between two parent curves. Constructors:
NURBSChamferCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbschamfercurve>.parent1 <nurbschamfercurve>.parent1ID <nurbschamfercurve>.parent2 <nurbschamfercurve>.parent2ID <nurbschamfercurve>.length1 : integer : integer : integer : integer : float

The 1st parent curve by NURBSet index. The 1st parent curve by NURBSId. The 2nd parent curve by NURBSet index. The 2nd parent curve by NURBSId. The length for 1st parent curve back from the end that defines the beginning of the chamfer.
<nurbschamfercurve>.length2 : float

The length for 2nd parent curve back from the end that defines the beginning of the chamfer.
<nurbschamfercurve>.flip1 <nurbschamfercurve>.flip2 <nurbschamfercurve>.trim1 : boolean : boolean : boolean

true to use the end of 1st parent curve; false to use the beginning, defaults to false. true to use the end of 2nd parent curve; false to use the beginning, defaults to false. Sets whether 1st parent curve is trimmed. true if the curve is trimmed; otherwise false.

1412

Chapter 11

3ds max Objects

<nurbschamfercurve>.trim2 <nurbschamfercurve>.flipTrim1

: boolean : boolean

Sets whether 2nd parent curve is trimmed. true if the curve is trimmed; otherwise false. If true the 1st parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.
<nurbschamfercurve>.flipTrim2 : boolean

If true the 2nd parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.

See also
NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSCVCurve : NURBSCurve
This class defines an independent NURBS CV Curve. The position and weight of the control vertices (CVs) controls the shape of the curve. Unlike spline vertices, CVs dont necessarily lie on the curve they define. The CVs define a control lattice which surrounds the curve. Constructors:
NURBSCVCurve [<property>:<val>] [closed:<boolean>]...

Any of the objects properties may be set via optional keyword arguments on the constructor. If closed:true is specified, the curve is created as a closed curve, otherwise it is an open curve.
getObject <nurbsset> <index>

Properties:
<nurbscvcurve>.order : integer

The order of the curve. This is one more than the degree of polynomial of any segment of the curve. All curves have a degree. The degree of a curve is the highest exponent in the equation used to represent it. A linear equation is degree 1, a quadratic equation degree 2. NURBS curves typically are represented by cubic equations and have a degree of 3.
<nurbscvcurve>.numKnots : integer

The number of knots in the curve. If this value is changed, the previous knot data is NOT maintained. Because they are generated mathematically, NURBS curves have a parameter space in addition to the 3D geometric space in which they are displayed. Specifically, an array of values called knots specifies the extent of influence of each control vertex (CV) on the curve or surface.
<nurbscvcurve>.numCVs : integer

The number of control vertices in the curve. If this value is changed, the previous control vertex data is NOT maintained.

NURBSCVCurve : NURBSCurve

1413

<nurbscvcurve>.transform

: matrix3

The transformation matrix for the NURBSCVCurve. This controls the relative position of the item within a NURBSSet.
<nurbscvcurve>.endsOverlap : boolean, read-only

true if the ends of the curve overlap even though the curve may not be closed (that is, the tangents match at the ends), false otherwise.
<nurbscvcurve>.autoParam : #notAutomatic, #autoCentripetal, #autoUniform

#notAutomatic, #autoCentripetal, and #autoUniform correspond to the Automatic Reparam options in the CV Curve rollouts: none, chord length and uniform, respectively. Defaults to #notAutomatic. Methods:
close <nurbscvcurve>

Forces the curve to be closed.

getKnot <nurbscvcurve> <index> setKnot <nurbscvcurve> <index> <float>

Get and set the indexed knots value, indexes are 1-based. Knots are a mathematical construct that helps define the span of control of CVs and blending functions that define NURBS Curves and Surfaces. The knots are an array of values that determines the parameterization of a curve. Values in the knot vector are nondecreasing. The knots specify the region of influence of the CVs on the curve. It is a way of partitioning the parameter space up into different segments. A B-spline curve or a NURBS curve is a curve that is defined by a series of segments. On each one of the segments the curve is like a polynomial, or in the case of a rational one, its like the ratio of polynomials. The knot vector describes how to partition the parameter space of the curve up for each of the different pieces of the polynomial.
getCV <nurbscvcurve> <cv_index>

Get the indexed CV as a NURBSControlVertex, indexes are 1-based.

setCV <nurbscvcurve> <cv_index> <NURBSControlVertex>

Sets the indexed CV to the given NURBSControlVertex, indexes are 1-based.

refine <nurbscvcurve> <u_param>

Add a new, interpolated CV at the given parametric point along the curve.
reparameterize <nurbscvcurve> (#centripetal | #uniform)

Reparameterizes the curve by chord length (#centripetal) or uniform (#uniform) uniform parameterization. Note: CV curves and surfaces must obey the relationship that order + number of CVs = number of knots. If this is not the case in most cases no object will be created and in some cases an assertion fault might be generated.

1414

Chapter 11

3ds max Objects

See also
NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSCurveOnSurface : NURBSCVCurve
This class defines a dependent Curve-on-Surface CV curve. These curves can be used for trimming the surface they lie on. Constructors:
NURBSCurveOnSurface [<property>:<val>] [closed:<boolean>]...

Any of the objects properties may be set via optional keyword arguments on the constructor. If closed:true is specified, the curve is created as a closed curve, otherwise it is an open curve.
getObject <nurbsset> <index>

Properties:
<nurbscurveonsurface>.parent <nurbscurveonsurface>.parentID : integer : integer : boolean : boolean

The parent surface by NURBSet index. The parent surface by NURBSId.

<nurbscurveonsurface>.trim <nurbscurveonsurface>.flipTrim

If true, trims parent surface at the curve. The state of the trim flip toggle. This controls which portion of the surface is trimmed. Note: The values for CVs for a NURBSCurveOnSurface are values in the parameter space of the surface, not in 3D space. CV surfaces are normally parameterized from 0 to 1, so all the CV values should have values from 0 to 1. Point surfaces are chord-length parameterized, which means that the CV parameter range is about the same as the size of the surface. In most cases, NURBSCurveOnSurfaces work better when point surfaces are used. You may have problems generating NURBSCurveOnSurfaces on CV surfaces. NURBSPointCurveOnSurfaces on CV surfaces are typically easier to work with.

NURBSFilletCurve : NURBSCurve

1415

See Also
NURBSCVCurve (p. 1412) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSFilletCurve : NURBSCurve
This class defines a dependent Fillet curve. A Fillet is a curve that creates a circular arc corner between two parent curves. Constructors:
NURBSFilletCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsfilletcurve>.parent1 : integer

The 1st parent curve by NURBSet index.

<nurbsfilletcurve>.parent1ID : integer

The 1st parent curve by NURBSId.

<nurbsfilletcurve>.parent2 : integer

The 2nd parent curve by NURBSet index.

<nurbsfilletcurve>.parent2ID : integer

The 2nd parent curve by NURBSId.

<nurbsfilletcurve>.radius : float : boolean : boolean : boolean : boolean

The radius of the fillet.

<nurbsfilletcurve>.flip1 <nurbsfilletcurve>.flip2 <nurbsfilletcurve>.trim1 <nurbsfilletcurve>.trim2

true to use the end of 1st parent curve; false to use the beginning, defaults to false. true to use the end of 2nd parent curve; false to use the beginning, defaults to false. Sets whether 1st parent curve is trimmed. true if the curve is trimmed; otherwise false. Sets whether 2nd parent curve is trimmed. true if the curve is trimmed; otherwise false.
<nurbsfilletcurve>.flipTrim1 : boolean

If true the 1st parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.
<nurbsfilletcurve>.flipTrim2 : boolean

If true the 2nd parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.

1416

Chapter 11

3ds max Objects

See also
NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSIsoCurve : NURBSCurve
This class defines a dependent Iso (isoparametric) curve. U and V Iso curves are dependent curves created along lines of constant parameter value of a NURBS surface. Constructors:
NURBSIsoCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsisocurve>.parent <nurbsisocurve>.parentID <nurbsisocurve>.dir <nurbsisocurve>.parameter : integer : integer : #U, #V : float

The parent surface by NURBSet index. The parent surface by NURBSId. The direction of the iso curve, either #U or #V. The parametric position in the range of 0.0 to 1.0 in the given direction on the surface at which the iso line will sit.
<nurbsisocurve>.trim <nurbsisocurve>.flipTrim <nurbsisocurve>.seed : boolean : boolean : point2

If true, trims parent surface at the curve. The state of the trim flip toggle. This controls which portion of the surface is trimmed. The seed location is a UV position on the parent surface.

See also
NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSMirrorCurve : NURBSCurve

1417

NURBSMirrorCurve : NURBSCurve
This class defines a dependent Mirror curve. A Mirror curve is similar to a mirror object that you create using the Mirror tool (on the 3ds max toolbar) or the Mirror modifier. It is the original curve reflected about one or two axes. Constructors:
NURBSMirrorCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsmirrorcurve>.parent <nurbsmirrorcurve>.parentID : integer : integer : #X, #Y, #Z, #XY, #XZ, #YZ : float : matrix3

The parent curve by NURBSet index. The parent curve by NURBSId.

<nurbsmirrorcurve>.axis <nurbsmirrorcurve>.distance

The axis or axes of reflection for the curve. The mirror offset distance.
<nurbsmirrorcurve>.transform

This is an additional transformation applied to the axis specification. This corresponds to the gizmo the user may use interactively to alter the location of the mirror axis. This is exactly equivalent to setting the transform on the gizmo of a mirror modifier.

See also
NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSOffsetCurve : NURBSCurve
This class defines a dependent Offset curve. An Offset curve is offset from the original, parent curve. It lies in the same plane as its parent, and is normal to the original. Constructors:
NURBSOffsetCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

1418

Chapter 11

3ds max Objects

Properties:
<nurbsoffsetcurve>.parent <nurbsoffsetcurve>.parentID <nurbsoffsetcurve>.distance : integer : integer : float

The parent curve by NURBSet index. The parent curve by NURBSId. The distance of the offset curve from the parent.

See also
NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSPointCurve : NURBSCurve
This class defines an independent curve that uses points to describe its shape. All the points lie on the curve itself. Constructors:
NURBSPointCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbspointcurve>.numPoints : integer

The number of points in the point curve. If this value is changed, the previous point data is not maintained.
<nurbspointcurve>.closed <nurbspointcurve>.transform : boolean : matrix3

true if the curve is closed, false if open. The transformation matrix for the NURBSPointCurve. This controls the relative position of the item within a NURBSSet. Methods:
close <nurbspointcurve>

Closes the curve.

getPoint <nurbspointcurve> <index>

Get the indexed curve point as a NURBSIndependentPoint

setPoint <nurbspointcurve> <index> <nurbs_independent_pt>

Set the indexed point to the given NURBSIndependentPoint

refine <nurbspointcurve> <u_param>

Adds a new, interpolated point at the given parametric position along the curve.

NURBSPointCurveOnSurface : NURBSPointCurve

1419

See also
NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSPointCurveOnSurface : NURBSPointCurve
This class defines a dependent Curve-on-Surface Point curve. These curves can be used for trimming the surface they lie on. Constructors:
NURBSPointCurveOnSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbspointcurveonsurface>.parent : integer : integer : boolean : boolean

The parent surface by NURBSet index.

<nurbspointcurveonsurface>.parentID

The parent surface by NURBSId.

<nurbspointcurveonsurface>.trim <nurbspointcurveonsurface>.flipTrim

If true, trims parent surface at the curve. The state of the trim flip toggle. This controls which portion of the surface is trimmed.

See also
NURBSPointCurve (p. 1418) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

1420

Chapter 11

3ds max Objects

NURBSProjectNormalCurve : NURBSCurve
This class defines a dependent Normal Projected curve. A Normal Projected curve lies on a surface. It is based on an existing curve, which is projected onto the surface in the direction of the surfaces normals. Constructors:
NURBSProjectNormalCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsprojectnormalcurve>.parent1 : integer : integer : integer : integer : boolean : boolean : point2

The parent surface by NURBSet index.

<nurbsprojectnormalcurve>.parent1ID

The parent surface by NURBSId.

<nurbsprojectnormalcurve>.parent2

The parent curve by NURBSet index.

<nurbsprojectnormalcurve>.parent2ID

The parent curve by NURBSId.

<nurbsprojectnormalcurve>.trim <nurbsprojectnormalcurve>.flipTrim <nurbsprojectnormalcurve>.seed

If true, trims parent surface at the curve. The state of the trim flip toggle. This controls which portion of the surface is trimmed. The seed location is a UV position on the parent surface.

See also
NURBSPointCurve (p. 1418) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSProjectVectorCurve : NURBSCurve

1421

NURBSProjectVectorCurve : NURBSCurve
This class defines a dependent Vector Projected curve. A Vector Projected curve lies on a surface. This is almost the same as a Normal Projected curve, except that the projection from the existing curve to the surface is in the direction of a vector that you can control. Constructors:
NURBSProjectVectorCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsprojectvectorcurve>.parent1 : integer : integer : integer : integer : boolean : boolean : point2 : point3

The parent surface by NURBSet index.

<nurbsprojectvectorcurve>.parent1ID

The parent surface by NURBSId.

<nurbsprojectvectorcurve>.parent2

The parent curve by NURBSet index.

<nurbsprojectvectorcurve>.parent2ID

The parent curve by NURBSId.

<nurbsprojectvectorcurve>.trim <nurbsprojectvectorcurve>.flipTrim <nurbsprojectvectorcurve>.seed <nurbsprojectvectorcurve>.pVec

If true, trims parent surface at the curve. The state of the trim flip toggle. This controls which portion of the surface is trimmed. The seed location is a UV position on the parent surface. The projection vector.

See also
NURBSPointCurve (p. 1418) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

1422

Chapter 11

3ds max Objects

NURBSSurfaceEdgeCurve : NURBSCurve
This class defines a dependent Surface Edge curve. Constructors:
NURBSSurfaceEdgeCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbssurfaceedgecurve>.parent : integer : integer : Point2

The parent surface by NURBSet index.

<nurbssurfaceedgecurve>.parentID

The parent surface by NURBSId.

<nurbssurfaceedgecurve>.seed

The seed location is a UV position on the parent surface.

See also
NURBSPointCurve (p. 1418) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSSurfaceNormalCurve : NURBSCurve
This class defines a dependent Surface Normal curve. This is a curve created at a specified distance from a surface and normal to it. Constructors:
NURBSSurfaceNormalCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbssurfacenormalcurve>.parent : integer : integer : float

The parent curve by NURBSet index.

<nurbssurfacenormalcurve>.parentID

The parent curve by NURBSId.

<nurbssurfacenormalcurve>.distance

The distance along the normal from the surface to the curve.

NURBSSurfSurfIntersectionCurve : NURBSCurve

1423

Note: The parent curve must have one of the following types: surface-surface intersection, U iso, V iso, normal projected, vector projected, CV curve on surface, or point curve on surface.

See also
NURBSPointCurve (p. 1418) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSSurfSurfIntersectionCurve : NURBSCurve
This class defines a dependent Surface-Surface Intersection curve. Constructors:
NURBSSurfSurfIntersectionCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbssurfsurfintersectioncurve>.parent1 : integer : integer : integer : integer : boolean : boolean : boolean

The 1st parent surface by NURBSet index.

<nurbssurfsurfintersectioncurve>.parent1ID

The 1st parent surface by NURBSId.

<nurbssurfsurfintersectioncurve>.parent2

The 2nd parent surface by NURBSet index.

<nurbssurfsurfintersectioncurve>.parent2ID

The 2nd parent surface by NURBSId.

<nurbssurfsurfintersectioncurve>.trimCurve1 <nurbssurfsurfintersectioncurve>.trimCurve2 <nurbssurfsurfintersectioncurve>.flipTrim1

If true, trim the 1st parent surface at the intersection. If true, trim the 2nd parent surface at the intersection. If true the 1st parent surface is trimmed from the point towards low parameter space. If false the surface is trimmed from the point towards high parameter space.
<nurbssurfsurfintersectioncurve>.flipTrim2 : boolean

If true the 2nd parent surface is trimmed from the point towards low parameter space. If false the surface is trimmed from the point towards high parameter space.
<nurbssurfsurfintersectioncurve>.seed : point2

The seed location is a UV position on the parent surface.

1424

Chapter 11

3ds max Objects

See also
NURBSPointCurve (p. 1418) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSXFormCurve : NURBSCurve
This class defines a dependent Transform (XForm) curve. A Transform curve is a copy of the original curve with a different position, rotation, or scale. Constructors:
NURBSXFormCurve [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsxformcurve>.parent <nurbsxformcurve>.parentID <nurbsxformcurve>.transform : integer : integer : matrix3

The parent curve by NURBSet index. The parent curve by NURBSId. The offset transformation matrix for the NURBSCVCurve. This controls the relative position of the item to the parent curve.

See also
NURBSPointCurve (p. 1418) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSSurface : NURBSObject

1425

NURBSSurface Classes
NURBSSurface : NURBSObject
This is the parent class for all the NURBS surface classes and so is not directly constructable. The class describes the common properties of all NURBS surfaces. This includes its material ID, texture/tiling options, renderable state, and open/closed state, and normal inverted state. The evalPos(), evalUTangent(), and evalVTangent() methods are used to compute points and tangents on the surface. Properties: All NURBS surface classes have the following properties.
<nurbssurface>.renderable <nurbssurface>.flipNormals : boolean : boolean

Specifies whether the surface is renderable. true if the surface is renderable, false if not. Specifies whether all the surfaces surface normals are flipped. true if the surface normals are to be flipped, false if not.
<nurbssurface>.generateUVs1 : boolean

If true, enables the generation of UV mapping coordinates for UVW channel 1. See the getGenerateUVs() and setGenerateUVs() methods for generalized mapping channel access.
<nurbssurface>.generateUVs2 : boolean

If true, enables the generation of UV mapping coordinates for UVW channel 2. See the getGenerateUVs() and setGenerateUVs() methods for generalized mapping channel access.
<nurbssurface>.matID : integer : boolean, read-only : boolean, read-only : float, read-only : float, read-only

The material ID of the surface.

<nurbssurface>.closedInU <nurbssurface>.closedInV <nurbssurface>.uParameterRangeMin <nurbssurface>.uParameterRangeMax

true if the surface is closed in the U direction, false if open. true if the surface is closed in the V direction, false if open.*

Contains the minimum and maximum valid values for <u_parm> in the methods associated with NURBS Surfaces.
<nurbssurface>.vParameterRangeMin <nurbssurface>.vParameterRangeMax : float, read-only : float, read-only

Contains the minimum and maximum valid values for <v_param> in the methods associated with NURBS Surfaces.

1426

Chapter 11

3ds max Objects

<nurbssurface>.textureSurface1 <nurbssurface>.textureSurface2

: NURBSTextureSurface : NURBSTextureSurface

Used to get and set the texture surfaces for the two mapping channels. These properties take and return instances of the NURBSTextureSurface class. .textureSurface1 accesses mapping channel 1 and .textureSurface2 accesses mapping channel 2. See NURBSTextureSurface : Value (p. 1455). See the getTextureSurface() and setTextureSurface() methods for generalized mapping channel access. It is not possible to assign texture surfaces to NURBS objects present in the scene. You can create new NURBSSets and the texture surface is used when you call createNURBSObject(). However, if you do a getNURBSSet() and assign a NURBSTextureSurface to these properties, nothing happens. Methods: All NURBS surface classes have the following methods:
evalPos <nurbssurface> <u_param> <v_param>

Returns the coordinates in space of the point at the given U and V parametric position on the surface.
evalUTangent <nurbssurface> <u_param> <v_param>

Returns the U tangent vector of the surface at the given U and V parametric position on the surface.
evalVTangent <nurbssurface> <u_param> <v_param>

Returns the V tangent vector of the surface at the given U and V parametric position on the surface.
getTiling <nurbssurface> [channel:<index>] setTiling <nurbssurface> <ut> <vt> [channel:<index>]

These methods get and set the tiling factor on the surface in the u and v directions. These methods return or take a point2 value, with u tiling in the x component and v tiling in the y component of the point2. The optional channel keyword argument can be used to select the mapping channel which defaults to 1.
getTilingOffset <nurbssurface> [channel:<index>] setTilingOffset <nurbssurface> <uo> <vo> [channel:<index>]

These methods get and set the tiling offset on the surface for the selected channel. These methods return or take a point2 value, with u offset in the x component and v offset in the y component of the point2. The optional channel keyword argument can be used to select the mapping channel which defaults to 1.
getGenerateUVs <nurbssurface> <channel_index> setGenerateUVs <nurbssurface> <channel_index> <boolean>

These methods get and set whether the generation of UV mapping coordinates for the selected channel is enabled.

NURBS1RailSweepSurface : NURBSSurface

1427

getTextureUVs <nurbssurface> <index> [channel:<index>] setTextureUVs <nurbssurface> <index> <point2> [channel:<index>]

These methods get and set the texture UV as a point2 value for the indexed coordinate and selected channel. The 1-based index of the texture coordinate must be >= 1 and <= 4. The optional channel keyword argument can be used to select the mapping channel which defaults to 1.
getTextureSurface <nurbssurface> <channel_index> setTextureSurface <nurbssurface> <channel_index> <NURBSTextureSurface>

These methods get and set texture surfaces for the selected channel. These methods return or take an instance of the NURBSTextureSurface class. See NURBSTextureSurface : Value (p. 1455).
getProdTess setProdTess getViewTess setViewTess <nurbssurface> <nurbssurface> <nurbssurface> <nurbssurface> <tessType_name> <tessType_name> <NURBSSurfaceApproximation> <tessType_name> <tessType_name> <NURBSSurfaceApproximation>

These methods get and set renderer and viewport NURBSSurfaceApproximation values for individual surfaces, where <tessType_name> is one of #surface, #displacement, or #curve corresponding to the 3 kinds of tessellation that can be controlled on a surface.
clearProdTess <nurbssurface> <tessType_name> clearViewTess <nurbssurface> <tessType_name>

Resets the surface approximation settings for the surface for the given tessellation type, where <tessType_name> is one of #surface, #displacement, or #curve corresponding to the 3 kinds of tessellation that can be controlled on a surface.

See also
NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBS1RailSweepSurface : NURBSSurface
This class defines a dependent 1-Rail Sweep surface. A 1-Rail Sweep surface uses at least two curves. One curve, the rail, defines one edge of the surface. The other curves define the surfaces cross sections. The cross-section curves should intersect the rail curve. If the cross sections dont intersect the rail, the resulting surface is unpredictable. Constructors:
NURBS1RailSweepSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbs1railsweepsurface>.rail : integer

The parent rail curve by NURBSet index.

1428

Chapter 11

3ds max Objects

<nurbs1railsweepsurface>.railID

: integer : integer : boolean : matrix3

The parent rail curve by NURBSId.

<nurbs1railsweepsurface>.numCurves

The number of cross-section curves.

<nurbs1railsweepsurface>.parallel <nurbs1railsweepsurface>.axisTM

If true, ensures that the sweep surfaces normal is parallel to the rail. The axis of the sweep. Methods:
appendCurve <nurbs1railsweepsurface> <curve> [flip:<boolean>] [startPoint:<float>]

Adds a curve to the end of the list of cross-section curves by specifying the index in the NURBSSet. If flip:true is specified, the cross-section curve is reversed. startPoint specifies the start point on the parent curve. startPoint is applicable only if the parent is a closed curve.
appendCurveByID <nurbs1railsweepsurface> <curveID> [flip:<boolean>] [startPoint:<float>]

Adds a curve to the end of the list of cross-section curves by specifying the NURBSId. If flip:true is specified, the cross-section curve is reversed. startPoint specifies the start point on the parent curve. startPoint is applicable only if the parent is a closed curve.
getCurve <nurbs1railsweepsurface> <index> setCurve <nurbs1railsweepsurface> <index> <curve>

Get or set the indexed cross-section curve by NURBSSet index.

getCurveID <nurbs1railsweepsurface> <index> setCurveByID <nurbs1railsweepsurface> <index> <curveID>

Get or set the indexed cross-section curve by NURBSId.

getFlip <nurbs1railsweepsurface> <index> setFlip <nurbs1railsweepsurface> <index> <boolean>

Get or set whether the indexed cross-section curve is reversed.

getCurveStartPoint <nurbs1railsweepsurface> <index> setCurveStartPoint <nurbs1railsweepsurface> <index> <float>

Get or set the start point of the indexed cross-section curve on the parent curve. The start point is applicable only if the parent is a closed curve.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBS2RailSweepSurface : NURBSSurface

1429

NURBS2RailSweepSurface : NURBSSurface
This class defines a dependent 2-Rail Sweep surface. A 2-Rail Sweep surface uses at least three curves. Two curves, the rails, define the two edges of the surface. The other curves define the surfaces cross sections. A 2-Rail Sweep surface is similar to a 1-Rail sweep. The additional rail gives you more control over the shape of the surface. Constructors:
NURBS2RailSweepSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbs2railsweepsurface>.rail1 <nurbs2railsweepsurface>.rail1ID : integer : integer : integer : integer : integer : boolean

The 1st parent rail curve by NURBSet index. The 1st parent rail curve by NURBSId.
<nurbs2railsweepsurface>.rail2 <nurbs2railsweepsurface>.rail2ID <nurbs2railsweepsurface>.numCurves

The 2nd parent rail curve by NURBSet index. The 2nd parent rail curve by NURBSId. The number of cross-section curves.
<nurbs2railsweepsurface>.parallel

If false, the rail curves define a ruled surface, and the cross sections describe lofting from this base ruled surface. If true, each cross section is associated with its best fitting plane. This plane moves along the rails and parallel to them. If the rails are curved, the plane can rotate. If the spacing between the rails changes, the section scales or stretches. In either case, the surface is blended from section to section along its entire length. Methods:
appendCurve <nurbs2railsweepsurface> <curve> [flip:<boolean>] [startPoint:<float>]

Adds a curve to the end of the list of cross-section curves by specifying the index in the NURBSSet. If flip:true is specified, the cross-section curve is reversed. startPoint specifies the start point on the parent curve. startPoint is applicable only if the parent is a closed curve.
appendCurveByID <nurbs2railsweepsurface> <curveID> [flip:<boolean>] [startPoint:<float>]

Adds a curve to the end of the list of cross-section curves by specifying the NURBSId. If flip:true is specified, the cross-section curve is reversed. startPoint specifies the start point on the parent curve. startPoint is applicable only if the parent is a closed curve.

1430

Chapter 11

3ds max Objects

getCurve <nurbs2railsweepsurface> <index> setCurve <nurbs2railsweepsurface> <index> <curve>

Get or set the indexed cross-section curve by NURBSSet index.

getCurveID <nurbs2railsweepsurface> <index> setCurveByID <nurbs2railsweepsurface> <index> <curveID>

Get or set the indexed cross-section curve by NURBSId.

getFlip <nurbs2railsweepsurface> <index> setFlip <nurbs2railsweepsurface> <index> <boolean>

Get or set whether the indexed cross-section curve is reversed.

getCurveStartPoint <nurbs2railsweepsurface> <index> setCurveStartPoint <nurbs2railsweepsurface> <index> <float>

Get or set the start point of the indexed cross-section curve on the parent curve. The start point is applicable only if the parent is a closed curve.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSBlendSurface : NURBSSurface
This class defines a dependent Blend surface. A Blend surface connects the edge of one surface to the edge of another, blending the curvature of the parents to create a smooth surface between them. You can also blend from a surface to a curve, or from a curve to a curve. Constructors:
NURBSBlendSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsblendsurface>.parent1 : integer : integer : integer : integer

The 1st parent by NURBSet index.

<nurbsblendsurface>.parent1ID

The 1st parent by NURBSId.

<nurbsblendsurface>.parent2

The 2nd parent by NURBSet index.

<nurbsblendsurface>.parent2ID

The 2nd parent by NURBSId.

NURBSBlendSurface : NURBSSurface

1431

<nurbsblendsurface>.edge1

: integer

Which edge of the 1st parent surface is used for the blend. The propertys value is one of the following:
1: 2: 3: 4: The The The The low U edge high U edge low V edge high V edge : integer : boolean

<nurbsblendsurface>.edge2 <nurbsblendsurface>.flip1

Which edge of the 2nd parent surface is used for the blend. Controls the matching of parent surface normals when creating the Blend surface. For example, normally when you create a Blend surface between two parent surfaces you dont want a bow tie surface (one with the ends rotated 180 degrees so it crosses on itself in the middle). If you simply match the parent normals youll occasionally get a bow tie surface. To prevent this you use this property to set a state indicating that one or the other should be flipped before its used. In this way, when the blend is created, a bow tie wont occur. If true, the 1st parents surface normal will be matched; if false the 1st parents surface normal will not be matched.
<nurbsblendsurface>.flip2 : boolean

If true, the 2nd parents surface normal will be matched; if false the 2nd parents surface normal will not be matched.
<nurbsblendsurface>.tension1 : float : float : float : float

The tension value for the 1st parent.

<nurbsblendsurface>.tension2

The tension value for the 2nd parent.

<nurbsblendsurface>.curveStartPoint1 <nurbsblendsurface>.curveStartPoint2

Adjusts the position of the start point at the two edges of the blend. Adjusting the start points can help eliminate unwanted twists or buckles in the surface. These values are not applicable if the edges or curves are not closed. Methods:
getParent <nurbsblendsurface> <index> setParent <nurbsblendsurface> <index> <curve>

Get or set a parent by NURBSSet index. <index> = 1 - parent 1; 2 - parent 2.

getParentID <nurbsblendsurface> <index> setParentID <nurbsblendsurface> <index> <curveID>

Get or set a parent by NURBSId. <index> = 1 - parent 1; 2 - parent 2.

getEdge <nurbsblendsurface> <index> setEdge <nurbsblendsurface> <index> <edge>

Get or set which edge of the parent surface is used for the blend. <index> = 1 - parent 1; 2 - parent 2. See the edge1 property description for the <edge> value description.

1432

Chapter 11

3ds max Objects

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSCapSurface : NURBSSurface
This class defines a dependent Cap surface. A Cap surface is a surface that caps a closed curve or the edge of a closed surface. Caps are especially useful with extruded surfaces. Constructors:
NURBSCapSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbscapsurface>.parent <nurbscapsurface>.parentID <nurbscapsurface>.edge : integer : integer : integer

The parent curve or surface by NURBSet index. The parent curve or surface by NURBSId. Which edge of the parent surface is capped. This value is not applicable if the parent is a curve. The propertys value is one of the following:
1: 2: 3: 4: The The The The low U edge high U edge low V edge high V edge : integer

<nurbscapsurface>.curveStartPoint

The start point on the parent curve. This value is only applicable if the parent is a curve.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSCVSurface : NURBSSurface

1433

NURBSCVSurface : NURBSSurface
This class defines an independent surface that uses control vertices (CVs) to describe its shape. The CVs define a control lattice which surrounds the surface. Constructors:
NURBSCVSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbscvsurface>.uOrder <nurbscvsurface>.vOrder <nurbscvsurface>.numUKnots <nurbscvsurface>.numVKnots : integer : integer : integer : integer

The order of the surface in the U and V directions.

The number of knots in the surface in the U and V directions. If this value is changed, the previous knot data is NOT maintained. Because they are generated mathematically, NURBS surfaces have a parameter space in addition to the 3D geometric space in which they are displayed. Specifically, an array of values called knots specifies the extent of influence of each control vertex (CV) on the surface.
<nurbscvsurface>.numCVs : point2

The number of control vertices for the surface in the U and V directions. If this value is changed, the previous control vertex data is NOT maintained.
<nurbscvsurface>.transform : matrix3

The transformation matrix for the NURBSCVSurface. This controls the relative position of the item within a NURBSSet.
<nurbscvsurface>.uEdgesOverlap : boolean, read-only <nurbscvsurface>.vEdgesOverlap : boolean, read-only

true if the edges of the surface overlap in U and/or V even though the surface may not be closed (that is, the tangents match at the edges), false otherwise.
<nurbscvsurface>.autoParam : #notAutomatic, #autoCentripetal, #autoUniform

#notAutomatic, #autoCentripetal, and #autoUniform correspond to the Automatic Reparam options in the CV Surface rollouts: none, chord length and uniform, respectively. Defaults to #notAutomatic.

1434

Chapter 11

3ds max Objects

<nurbscvsurface>.rigid

: boolean

true if the surface is rigid; otherwise false. The only editing allowed on a rigid surface is to transform it at the Surface sub-object level. You cant move a rigid surfaces points or CVs, or change the number of points or CVs. Rigid surfaces reduce the amount of memory used by the NURBS model. Making surfaces rigid improves performance, especially for large and complex models. When a surface is rigid, you cant see its points or CVs when you are at the Point or Surface CV sub-object levels. If the model has no nonrigid surfaces and no point curves, the Point and Surface CV sub-object levels arent available at all. Methods:
closeU <nurbscvsurface>

Closes the surface in the U direction.

closeV <nurbscvsurface>

Closes the surface in the V direction.

getUKnot <nurbscvsurface> <u_index>

Get the indexed U-direction knot; knot indexes are 1-based.

setUKnot <nurbscvsurface> <u_index> <float>

Sets the indexed U-direction knot to the given value; knot indexes are 1-based.
getVKnot <nurbscvsurface> <v_index>

Get the indexed V-direction knot; knot indexes are 1-based.

setVKnot <nurbscvsurface> <v_index> <float>

Get the indexed V-direction knot to the given value; knot indexes are 1-based.
getCV <nurbscvsurface> <u_index> <v_index>

Get the CV at the given U and V index as a NURBSControlVertex; CV indexes are 1-based.
setCV <nurbscvsurface> <u_index> <v_index> <NURBSControlVertex>

Sets the CV at the given U and V index to the supplied NURBSControlVertex; CV indexes are 1-based.
refineU <nurbscvsurface> <v_param>

Adds new row of interpolated CVs in the U direction on the surface at the given parametric V point.
refineV <nurbscvsurface> <u_param>

Adds new column of interpolated CVs in the V direction on the surface at the given parametric U point.
refine <nurbscvsurface> <u_param> <v_param>

Adds a new row and column of interpolated CVs on the surface at the given parametric UV position.
reparameterize <nurbscvsurface> (#centripetal | #uniform)

Reparameterizes the surface by chord length (#centripetal) or uniform (#uniform) uniform parameterization.

NURBSExtrudeSurface : NURBSSurface

1435

Note: CV curves and surfaces must obey the relationship that order + number of CVs = number of knots. If this is not the case in most cases no object will be created and in some cases an assertion fault might be generated.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSExtrudeSurface : NURBSSurface
This class defines a dependent Extrude surface. An Extrude surface is extruded from a curve subobject. It is similar to a surface created with the Extrude modifier. The advantage is that an extrude sub-object is part of the NURBS model, so you can use it to construct other curve and surface subobjects. Constructors:
NURBSExtrudeSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsextrudesurface>.parent : integer : integer : float : matrix3 : float

The parent curve by NURBSet index.

<nurbsextrudesurface>.parentID

The parent curve by NURBSId.

<nurbsextrudesurface>.distance

The length of extrusion.

<nurbsextrudesurface>.axisTM

The extrusion axis.

<nurbsextrudesurface>.curveStartPoint

The start point on the parent curve. This value is only applicable if the curve is closed.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

1436

Chapter 11

3ds max Objects

NURBSFilletSurface : NURBSSurface
This class defines a dependent Fillet surface. A Fillet surface is a rounded corner surface connecting the edges of two other surfaces. Constructors:
NURBSFilletSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsfilletsurface>.cubic : boolean

If true, the radius is always linear. If false, the radius is treated as a cubic function, allowing it to change based on the parent surfaces geometry. Methods:
getParent <nurbsfilletsurface> <index> setParent <nurbsfilletsurface> <index> <curve>

Get or set a parent surface by NURBSSet index. <index> = 1 - parent 1; 2 - parent 2.

setParentID <nurbsfilletsurface> <index> <curveID> getParentID <nurbsfilletsurface> <index>

Get or set a parent surface by NURBSId. <index> = 1 - parent 1; 2 - parent 2.

getSeed <nurbsfilletsurface> <index> setSeed <nurbsfilletsurface> <index> <point2>

The UV location of the seed value on a parent surface. <index> = 1 - parent 1; 2 - parent 2.
getRadius <nurbsfilletsurface> <index> setRadius <nurbsfilletsurface> <index> <float>

Get or set the radius of the fillet surface. <index> = 1 - start radius; 2 - end radius.
getTrimSurface <nurbsfilletsurface> <index> setTrimSurface <nurbsfilletsurface> <index> <bool>

Get or set whether to trim a parents surface. If true, trims the parent surface at the intersection. <index> = 1 - parent 1; 2 - parent 2.
getFlipTrim <nurbsfilletsurface> <index> setFlipTrim <nurbsfilletsurface> <index> <bool>

Get or set the direction to trim a parents surface. If true the parent surface is trimmed from the point towards low parameter space. If false the surface is trimmed from the point towards high parameter space. <index> = 1 - parent 1; 2 - parent 2.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSLatheSurface : NURBSSurface

1437

NURBSLatheSurface : NURBSSurface
This class defines a dependent Lathe surface. A Lathe surface is generated from a curve sub-object. It is similar to a surface created with the Lathe modifier. The advantage is that a lathe sub-object is part of the NURBS model, so you can use it to construct other curve and surface sub-objects. Constructors:
NURBSLatheSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbslathesurface>.parent : integer : integer : matrix3 : float : float

The parent curve by NURBSet index.

<nurbslathesurface>.parentID

The parent curve by NURBSId.

<nurbslathesurface>.axisTM <nurbslathesurface>.sweep

The axis system for the surface of revolution. The angle of the revolution in degrees.
<nurbsextrudesurface>.curveStartPoint

The start point on the parent curve. This value is only applicable if the curve is closed.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSMirrorSurface : NURBSSurface
This class defines a dependent Mirror surface. A Mirror surface is similar to a mirror object that you create using the Mirror tool (on the 3ds max toolbar) or the Mirror modifier. It is the original surface reflected about one or two axes. Constructors:
NURBSMirrorSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

1438

Chapter 11

3ds max Objects

Properties:
<nurbsmirrorsurface>.parent <nurbsmirrorsurface>.parentID : integer : integer : #X, #Y, #Z, #XY, #XZ, #YZ : float

The parent curve by NURBSet index. The parent curve by NURBSId.

<nurbsmirrorsurface>.axis <nurbsmirrorsurface>.distance

The axis or axes of reflection for the surface. The offset from the center of the local coordinate system for the mirror object that moves the mirror, in the direction specified by the mirror axis.
<nurbsmirrorsurface>.transform : matrix3

This is an additional transformation applied to the axis specification. This corresponds to the gizmo the user may use interactively to alter the location of the mirror axis. This is exactly equivalent to setting the transform on the gizmo of a mirror modifier.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSMultiCurveTrimSurface : NURBSSurface
This class defines a dependent Multicurve Trim surface which is a surface that is trimmed by multiple curves forming a loop. Constructors:
NURBSMultiCurveTrimSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsmulticurvetrimsurface>.surfaceParent : Integer : Integer : Integer : Boolean

The parent surface by NURBSet index.

<nurbsmulticurvetrimsurface>.surfaceParentID

The parent surface by NURBSId.

<nurbsmulticurvetrimsurface>.numCurves

The number of curves used for the trim loop.

<nurbsmulticurvetrimsurface>.flipTrim

The state of the trim flip toggle. This controls which portion of the surface is trimmed. Methods:

NURBSNBlendSurface : NURBSSurface

1439

getParent <nurbsmulticurvetrimsurface> <index>

Gets the NURBSSet index of the indexed trim loop.

setParent <nurbsmulticurvetrimsurface> <index> <curve>

Sets the indexed trim loop to the curve specified by the NURBSSet index.
getParentID <nurbsmulticurvetrimsurface> <index>

Gets the NURBSId of the indexed trim loop.

setParentID <nurbsmulticurvetrimsurface> <index> <curveID>

Sets the indexed curve in the trim loop to the curve specified by the NURBSId.
appendCurve <nurbsmulticurvetrimsurface> <curve>

Adds a curve to the end of the list of curves comprising the trim loop by specifying the NURBSSet index.
appendCurveByID <nurbsmulticurvetrimsurface> <curveID>

Adds a curve to the end of the list of curves comprising the trim loop by specifying the NURBSId.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSNBlendSurface : NURBSSurface
This class defines a dependent Multisided Blend surface. A Multisided Blend surface is a surface that fills in the edges defined by three or four other curve or surfaces. Unlike a regular, two-sided Blend surface, the curves or surfaces edges must form a closed loop (that is, sequence head to tail, and the ends must match). That is, they must completely surround the opening the Multisided Blend will cover. Constructors:
NURBSNBlendSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties: There are no additional properties for NURBSNBlendSurface. Methods:

getParent <nurbsnblendsurface> <index>

Returns the NURBSSet index of the indexed curve or surface.

setParent <nurbsnblendsurface> <index> <curve>

Sets the specified parent curve or surface by NURBSSet index as the indexed edge for the surface.

1440

Chapter 11

3ds max Objects

getParentID <nurbsnblendsurface> <index>

Returns the NURBSId of the indexed curve or surface.

setParentID <nurbsnblendsurface> <index> <curveID>

Sets the specified parent curve or surface by NURBSId as the indexed edge for the surface.
getEdge <nurbsnblendsurface> <index> setEdge <nurbsnblendsurface> <index> <edge>

Get or set which edge of the indexed parent surface is used for the blend. The edge is only applicable if the parent is a surface. the <edge> value is one of the following:
1: 2: 3: 4: The The The The low U edge high U edge low V edge high V edge

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSOffsetSurface : NURBSSurface
This class defines a dependent Offset surface. An Offset surface is offset a specified distance from the original along the parent surfaces normals. Constructors:
NURBSOffsetSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsoffsetsurface>.parent <nurbsoffsetsurface>.parentID : integer : integer : float

The parent surface by NURBSet index. The parent surface by NURBSId.

<nurbsoffsetsurface>.distance

The distance of the offset surface from the parent surface.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSPointSurface : NURBSSurface

1441

NURBSPointSurface : NURBSSurface
This class defines an independent surface that uses points to describe its shape. Constructors:
NURBSPointSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbspointsurface>.numPoints : point2

The number of points in the point surface in the U and V directions. If this value is changed, the previous point data is not maintained.
<nurbspointsurface>.transform : matrix3

The transformation matrix for the NURBSPointSurface. This controls the relative position of the item within a NURBSSet.
<nurbspointsurface>.closedU <nurbspointsurface>.closedV : boolean : boolean

true if the surface is closed in the U direction, false if open. true if the surface is closed in the V direction, false if open. Methods:
closeU <nurbspointsurface>

Close the curve in U.

closeV <nurbspointsurface>

Close the curve in V.

getPoint <nurbspointsurface> <u_index> <v_index>

Get the indexed surface point as a NURBSIndependentPoint; point indexes are 1-based.
setPoint <nurbspointsurface> <u_index> <v_index> <NURBSIndependentPoint>

Get the indexed surface point to the given NURBSIndependentPoint; point indexes are 1-based.
refineU <nurbspointsurface> <v_param>

Add new row of interpolated points in the U direction on the surface at the given parametric V point.
refineV <nurbspointsurface> <u_param>

Add new column of interpolated points in the V direction on the surface at the given parametric U point.
refine <nurbspointsurface> <u_param> <v_param>

Add a new row and column of interpolated points on the surface at the given parametric UV position.

1442

Chapter 11

3ds max Objects

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSRuledSurface : NURBSSurface
This class defines a dependent Ruled surface. A Ruled surface is generated from two curve subobjects. It lets you use curves to design the two opposite borders of a surface. Constructors:
NURBSRuledSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsruledsurface>.parent1 <nurbsruledsurface>.parent1ID : integer : integer : integer : integer : boolean

The 1st parent curve by NURBSet index. The 1st parent curve by NURBSId.
<nurbsruledsurface>.parent2 <nurbsruledsurface>.parent2ID

The 2nd parent curve by NURBSet index. The 2nd parent curve by NURBSId.
<nurbsruledsurface>.flip1

Controls the matching of parent curve direction when creating the Ruled surface. For example, normally when you create a Ruled surface between two parent curves you dont want a bow tie surface (one with the ends rotated 180 degrees so it crosses on itself in the middle). If you simply match the parent direction youll get a bow tie surface. To prevent this you use this property to set a state indicating that one or the other should be flipped before its used. In this way, when the ruled surface is created, a bow tie wont occur. If true, the 1st parents curve direction will be flipped; if false the 1st parents curve direction will not be flipped.
<nurbsruledsurface>.flip2 : boolean

If true, the 2nd parents curve direction will be flipped; if false the 2nd parents curve direction will not be flipped.
<nurbsruledsurface>.curveStartPoint1 <nurbsruledsurface>.curveStartPoint2 : float : float

The start point on the 1st parent curve. This value is only applicable if the curve is closed. The start point on the 2nd parent curve. This value is only applicable if the curve is closed.

NURBSULoftSurface : NURBSSurface

1443

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSULoftSurface : NURBSSurface
This class defines a dependent U Loft surface. A U Loft surface interpolates a surface across multiple curve sub-objects. The curves become U-axis contours of the surface. Constructors:
NURBSUloftSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsuloftsurface>.numCurves : integer

The number of curves used by the U Loft. Methods:

getCurve <nurbsuloftsurface> <index>

Gets the NURBSSet index of the indexed U Loft curve; curve indexes are 1-based.
setCurve <nurbsuloftsurface> <index> <curve>

Sets the indexed U Loft curve to the curve specified by the NURBSSet index.
getCurveID <nurbsuloftsurface> <index>

Gets the NURBSId of the indexed U Loft curve in the loft; curve indexes are 1-based.
setCurveByID <nurbsuloftsurface> <index> <curveID>

Sets the indexed U Loft curve to the curve specified by the NURBSId.
appendCurve <nurbsuloftsurface> <curve> [flip:<boolean>] [startPoint:<float>] \ [tension:<float>] [useTangent:<boolean>] [flipTangent:<boolean>]

Adds a curve to the end of the list of U Loft curves by specifying the NURBSSet index. If flip:true is specified, the interpretation of the start and end of the curve to be reversed. startPoint: specifies the start point on the curve. This value is only applicable if the curve is closed. tension: specifies the tension of the curve. If useTangent:true is specified and the curve is a curve on surface, causes the U Loft to use the tangency of the surface. This can help blend a loft smoothly onto a surface. If flipTangent:true is specified, the tangent is flipped for the curve.
appendCurveByID <nurbsuloftsurface> <curveID> [flip:<boolean>] [startPoint:<float>] \ [tension:<float>] [useTangent:<boolean>] [flipTangent:<boolean>]

Adds a curve to the end of the list of U Loft curves by specifying the NURBSId.

1444

Chapter 11

3ds max Objects

getFlip <nurbsuloftsurface> <index> setFlip <nurbsuloftsurface> <index> <boolean>

Get or set the flip state of the indexed U Loft curve; true causes the interpretation of the start and end of the curve to be reversed, used to control twisting in the loft.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSUVLoftSurface : NURBSSurface
This class defines a dependent UV Loft Surface. This surface is similar to the U Loft surface, but has a set of curves in the V dimension as well as the U dimension. Constructors:
NURBSUVLoftSurface [<property>:<val>]...

any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsuvloftsurface>.numUCurves <nurbsuvloftsurface>.numVCurves : integer : integer

The number of curves in the U direction used by the UV Loft. The number of curves in the V direction used by the UV Loft. Methods:
getUCurve <nurbsuvloftsurface> <index>

Gets the NURBSSet index of the U direction indexed UV Loft curve; curve indexes are 1based.
setUCurve <nurbsuvloftsurface> <index> <curve>

Sets the indexed UV Loft curve in the U direction to the curve specified by the NURBSSet index.
getUCurveID <nurbsuvloftsurface> <index>

Gets the NURBSId of the U direction indexed UV Loft curve in the loft; curve indexes are 1-based.
setUCurveByID <nurbsuvloftsurface> <index> <curveID>

Sets the indexed UV Loft curve in the U direction to the curve specified by the NURBSId.
getVCurve <nurbsuvloftsurface> <index>

Gets the NURBSSet index of the V direction indexed UV Loft curve; curve indexes are 1based.

NURBSXFormSurface : NURBSSurface

1445

setVCurve <nurbsuvloftsurface> <index> <curve>

Sets the indexed UV Loft curve in the V direction to the curve specified by the NURBSSet index.
getVCurveID <nurbsuvloftsurface> <index>

Gets the NURBSId of the V direction indexed UV Loft curve in the loft; curve indexes are 1-based.
setVCurveByID <nurbsuvloftsurface> <index> <curveID>

Sets the indexed UV Loft curve in the V direction to the curve specified by the NURBSId.
appendUCurve <nurbsuvloftsurface> <curve>

Adds a curve to the end of the list of U direction UV Loft curves by specifying the NURBSId.
appendUCurveByID <nurbsuvloftsurface> <curveID>

Adds a curve to the end of the list of U direction UV Loft curves by specifying the NURBSSet index.
appendVCurve <nurbsuvloftsurface> <curve>

Adds a curve to the end of the list of V direction UV Loft curves by specifying the NURBSSet index.
appendVCurveByID <nurbsuvloftsurface> <curveID>

Adds a curve to the end of the list of V direction UV Loft curves by specifying the NURBSId.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSXFormSurface : NURBSSurface
This class defines a dependent Transform (XForm) surface. A Transform surface is a copy of the original surface with a different position, rotation, or scale. Constructors:
NURBSXFormSurface [<property>:<val>]...

any of the objects properties may be set via optional keyword arguments on the constructor.
getObject <nurbsset> <index>

Properties:
<nurbsxformsurface>.parent <nurbsxformsurface>.parentID : integer : integer

The parent surface by NURBSet index. The parent surface by NURBSId.

1446

Chapter 11

3ds max Objects

<nurbsxformsurface>.transform

: matrix3

The offset transformation matrix for the NURBSXFormSurface. This controls the relative position of the item to the parent surface.

See also
NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSTexturePoint Class
NURBSTexturePoint : NURBSObject
This class defines a single texture vertex in a NURBS texture surface. Constructors:
NURBSTexturePoint <point2> [indices:<point2>]

Create a NURBSTexturePoint with the specified UV coordinate. If indices: is specified, it sets the ordering the texture point in the texture surface.
getPoint <NURBSTextureSurface> <u_index> <v_index>

Properties:
<nurbstexturepoint>.pos : point2

The UV coordinate of the texture point. Methods:

setIndices <nurbstexturepoint> <u_index> <v_index>

Sets the ordering the texture point in the texture surface.

See also
NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)

NURBSDisplay : Value

1447

NURBS Associated Classes

NURBSDisplay : Value
This class corresponds to the NURBS display control checkboxes in the General NURBS rollout panel. You can exert control over the display levels in a NURBS object by either assigning NURBSDisplay values to the .display property of a NURBSSet value or using the setSurfaceDisplay() node function. See NURBS Node Properties and Methods (p. 1397). Constructors:
NURBSDisplay [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
<nurbsset>.display

Properties:
<nurbsdisplay>.displayCurves <nurbsdisplay>.displaySurfaces <nurbsdisplay>.displayLattices <nurbsdisplay>.displaySurfCVLattices <nurbsdisplay>.displayCurveCVLattices <nurbsdisplay>.displayDependents <nurbsdisplay>.displayTrimming <nurbsdisplay>.degradeOnMove <nurbsdisplay>.displayShadedLattice : boolean : boolean : boolean : boolean : boolean : boolean : boolean : boolean : boolean

true if curves are displayed; otherwise false. true if surfaces are displayed; otherwise false. true if lattices are displayed; otherwise false. true if surface CV lattices are displayed; otherwise false. true if curve CV lattices are displayed; otherwise false. true if dependent sub-objects are displayed; otherwise false. true if surface trimming is displayed; otherwise false. true if the surface may degrade while transforming it; otherwise false. true if the NURBS surfaces appear as shaded lattices in shaded viewports and wireframe viewports display the surfaces lattice without shading. false if NURBS surfaces display as tessellated meshes in shaded viewport and wireframe viewports surfaces display as either iso curves or wire meshes.

See also
Value Common Properties, Operators, and Methods (p. 714)

1448

Chapter 11

3ds max Objects

NURBSSelection : Value
An NURBSSelection represents a set of NURBS sub-objects for a scene NURBS node as a virtual array. As such, you can access a sub-object by index, iterate over the sub-objects, and apply mapped functions to the sub-objects. The NURBSSelection array is dynamic, i.e., its contents will change as the sub-objects of the NURBS node change. NURBSSelection values are mappable. Constructors:
<node>.selectedCurveCVs <node>.selectedCurves <node>.selectedImports <node>.selectedPoints <node>.selectedSurfaces <node>.selectedSurfCVs <node>.curveCVs <node>.curves <node>.imports <node>.surfaces <node>.surfCVs <node>.points

-------

read-only read-only read-only read-only read-only read-only

Properties:
<nurbsselection>.count <nurbsselection>.selSetNames : Integer, read-only : Array of names, read-only

Returns the number of sub-objects in the NURBSSelection array. Returns an array of names of the current named selection sets corresponding to the NURBSSelection level for the object the NURBSSelection is associated with. The following property is present for singleton selections (of the form $foo.curveCVs[n]):
<nurbsselection>.index : Integer, read-only

Returns the index of the selected sub-object in the NURBS object, e.g.,
$foo.selectedcurveCVs[2].index

returns the curve CV index of the 2nd curve CV in the current selection. Note that iterating over a selection yields singleton selections in the loop body:
sCVs = for i in $foo.selectedcurveCVs collect i.index

sCVs contains selected curve CVs as array Operators:

<node>.selectedCurveCVs <node>.selectedCurves <node>.selectedImports <node>.selectedPoints <node>.selectedSurfaces <node>.selectedSurfCVs = = = = = = (<array> (<array> (<array> (<array> (<array> (<array> | | | | | | <bitarray>) <bitarray>) <bitarray>) <bitarray>) <bitarray>) <bitarray>)

Selects the specified sub-objects.

<nurbsselection>[<integer>]

Retrieves the indexed sub-object as a singleton NURBSSelection. Index starts at 1

NURBSSelection : Value

1449

<nurbsselection>[(<integer_array> | <bitarray>)]

Retrieves the indexed sub-objects as a NURBSSelection. Index starts at 1.

<nurbsselection>[(<#name> | <string>)]

Retrieves the sub-object level named selection set, where the name of the named selection set can be specified as a name or string value.
<nurbsselection>[(<#name> | <string>)] = (<nurbsselection> | <integer_array> | <bitarray>)

Sets the sub-object level named selection set to the specified edges. The name of the named selection set can be specified as a name or string value, and the edges can be specified as an array, bitArray, or a NURBSSelection from the same object and of the same sub-object level. Methods:
move <nurbsselection> <point3>

Moves the sub-objects in the NURBSSelection.

rotate <nurbsselection> <quat_or_other_rotation_form>

Rotates the sub-objects in the NURBSSelection.

scale <nurbsselection> <point3>

Scales the sub-objects in the NURBSSelection.

select <nurbsselection>

Selects the sub-objects in the NURBSSelection.

deselect <nurbsselection>

Deselects the sub-objects in the NURBSSelection.

delete <nurbsselection>

Deletes the sub-objects in the NURBSSelection.

append <nurbsselection> (<nurbsselection> | <integer>)

Appends the sub-objects(s) to the NURBSSelection.

findItem <nurbsselection> (<nurbsselection[<integer>] | <integer>)

Returns the selection index of the matching item or 0 if not found. The item is selection index or singleton NURBSSelection. Examples:
$foo.surfCVs[#baz] -- retrieves the surf CV selection named baz move $foo.curves[#bar] [0,0,10] -- moves the bar curve selection 10 in Z move $foo.selectedSurfCVs [0,0,10] -- moves the current surface CV selection 10 in Z coordsys local scale $foo.surfaces[#baz] [2,2,2] select $foo.curveCVs[#(1,2,3,4,5)] -- select the specified curve CVs deselect $foo.curves -- deselect all curves delete $foo.points[#{1..31, 40..50}] -- delete the specified points $foo.curveCVs[#fred] = $foo.selectedCurveCVs - snapshot the selected curve CVs

See also
Value Common Properties, Operators, and Methods (p. 714)

1450

Chapter 11

3ds max Objects

NURBSSet : Value
This is the class used to create NURBS objects, or retrieve data from existing NURBS objects. The NURBSSet acts as a container for the other objects. This class contains a table of the various NURBSObject derived entities (points, curves, surfaces) used to make up the set. Additionally it has two fuse tables: one for fuse curves and one for fuse surfaces. These are used to allow the CVs in the curves or surfaces to be stitched or fused together so that if one curve or surface moves the other moves with it. This class also has the surface-approximation properties that control the objects tessellation into triangle meshes for use in the viewports and the production renderer. NURBSSet values are mappable. Constructors:
NURBSSet [<property>:<val>]...

any of the objects properties may be set via optional keyword arguments on the constructor
getNURBSSet <node> [#relational]

This function is used to retrieve a NURBSSet that corresponds to the specified NURBS scene node. This allows access the internal objects inside a 3ds max editable NURBS object. If the optional #relational parameter is not supplied, the returned NURBSSet will contain only independent curves and surfaces, all dependent objects will be decomposed into corresponding independent objects. So for example, if you pass an object that has a relational model (perhaps two CV surfaces and a dependent blend surface) it will decompose them into three CV surfaces. This will be the CV surfaces that represent the two surfaces and the blend, but you wont have the blend relational data. If the #relational argument is supplied, you get back two CV surfaces and a NURBS blend surface and the NURBSSet is an active representative for the scene object -- any changes you make to the properties of its constituent NURBSObjects will be reflected directly in the source scene object. Properties:
<nurbsset>.numObjects <nurbsset>.count : integer, read-only : integer, read-only

The number of internal objects in the NURBSSet. The following properties control the surface approximation tessellation. There are dual sets of properties, one for controlling viewport tessellation, the other for controlling renderer tessellation. The properties correspond directly to the surface approximation controls in the NURBS surface modifier panel. See NURBSSurfaceApproximation (p. 1453) for a description of these properties.
<nurbsset>.viewConfig <nurbsset>.viewIsoULines <nurbsset>.viewIsoVLines <nurbsset>.viewMeshUSteps <nurbsset>.viewMeshVSteps <nurbsset>.viewMeshApproxType : : : : : : #isoOnly, #isoAndMesh, #meshOnly integer integer integer integer #parametric, #spatial, #curvature,

NURBSSet : Value

1451

<nurbsset>.viewSpacialEdge <nurbsset>.viewCurvatureAngle <nurbsset>.viewCurvatureDistance <nurbsset>.viewViewDependent <nurbsset>.renderConfig

: : : : : : : : : : : : : : : : :

#regular, #spatialAndCurvature float float float boolean #isoOnly, #isoAndMesh, #meshOnly, #regular, #spatialAndCurvature integer integer integer integer #parametric, #spatial, #curvature, #regular, #spatialAndCurvature float float float boolean

<nurbsset>.renderIsoULines <nurbsset>.renderIsoVLines <nurbsset>.renderMeshUSteps <nurbsset>.renderMeshVSteps <nurbsset>.renderMeshApproxType

<nurbsset>.renderSpacialEdge <nurbsset>.renderCurvatureAngle <nurbsset>.renderCurvatureDistance <nurbsset>.renderViewDependent <nurbsset>.display

: NURBSDisplay

Takes and returns instances of the NURBSDisplay (p. 1447) class that controls visibility of various components of a NURBS objects display in the viewports.
<nurbsset>.viewApproximation <nurbsset>.renderApproximation : NURBSSurfaceApproximation : NURBSSurfaceApproximation

These properties are used to access and control surface approximation using the NURBSSurfaceApproximation (p. 1453) class, instances of which encapsulate all the approximation settings for either viewports or rendering. You can construct a surface approximation setup in one of these instances and use it to set the surface approximation for many objects.
<nurbsset>.merge : float

Controls the tessellation of surface sub-objects whose edges are joined or very nearly joined. When input to a modifier as Mesh Select which requires a mesh, and when NURBS surfaces are tessellated for production rendering, by default 3ds max adjusts the tessellation of adjoining surfaces to match each other in terms of the number of faces along the edges. The merge value controls how this is done. If merge is zero, adjoining faces are unchanged. Increasing the value of merge increases the distance 3ds max uses to calculate how edges should match, guaranteeing no gaps between the surfaces when they are rendered. Operators:
<nurbsset>[<index>] <nurbsset>[<index>] = <nurbsobj>

The sub-objects in a NURBSSet can be accessed using the standard MAXScript array indexing operator, []. This is equivalent to using the getObject() and setObject() methods described below.

1452

Chapter 11

3ds max Objects

Methods:
appendObject <nurbsset> <nurbsobj>

Appends the given NURBSObject (instances of any of the subclasses of NURBSObject and their subclasses, all the points, curves, surfaces) as a new sub-object to the NURBSSet. The new sub-object receives the next available index.
setObject <nurbsset> <index> <nurbsobj>

Set the indexed sub-object to the given NURBSObject; indexes are 1-based. You use this function to replace a previously appended object.
getObject <nurbsset> (<index> | <NURBSSelection>)

Retrieves the indexed sub-object or the set of sub-objects specified by the NURBSSelection from the NURBSSet; sub-object indexes are 1-based. If the NURBSSelection specifies no sub-objects, undefined is returned. If one sub-object is specified, a value of that subobjects class is returned. If multiple sub-objects are specified, a NURBSSet value is returned.
removeObject <nurbsset> <index>

Removes the given sub-object from the NURBSSet. The indexes of all the remaining higher-indexed sub-objects are renumbered down.
disconnect <nurbsset>

Disconnect a relational NURBS set from its scene object, turning it into a non-relational set.
deleteObjects <nurbsset>

This method deletes all the NURBSObjects in a NURBSSet, and frees its memory.
getProdTess setProdTess getViewTess setViewTess <nurbsset> <nurbsset> <nurbsset> <nurbsset> <tessType_name> <tessType_name> <NURBSSurfaceApproximation> <tessType_name> <tessType_name> <NURBSSurfaceApproximation>

These methods get and set renderer and viewport NURBSSurfaceApproximation values for individual surfaces, where <tessType_name> is one of #surface, #displacement, or #curve corresponding to the 3 kinds of tessellation that can be controlled on a surface.
clearProdTess <nurbsset> <tessType_name> clearViewTess <nurbsset> <tessType_name>

Resets the surface approximation settings for the surfaces in the NURBSet for the given tessellation type, where <tessType_name> is one of #surface, #displacement, or #curve corresponding to the 3 kinds of tessellation that can be controlled on a surface.

See also
Value Common Properties, Operators, and Methods (p. 714)

NURBSSurfaceApproximation : Value

1453

NURBSSurfaceApproximation : Value
Instances of this class contain a complete surface approximation setting that can be used to set the approximation for NURBS objects described by NURBSSet values or directly in existing NURBS scene node. You use the setViewApproximation() and setRenderApproximation() functions on existing scene nodes and the .viewApproximation and .renderApproximation properties on NURBSSet values. Constructors:
NURBSSurfaceApproximation [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
<nurbsset>.viewApproximation <nurbsset>.renderApproximation

Properties:
<nurbssurfaceapproximation>.config : #isoOnly, #isoAndMesh, #meshOnly

This property determines what is displayed in the interactive or scanline renderer. If #isoOnly is specified, only Iso lines are displayed. Iso (parametric) lines are similar to contour lines. The lines show where the NURBS surface has a constant U or V value or both. Iso line representations can be less crowded and easier to visualize than wire mesh representations. If #isoAndMesh is specified, Iso lines and the mesh are displayed. When chosen, wireframe viewports display iso line representations of the surface, and shaded viewports display the shaded surface. If #meshOnly is specified, just the mesh is displayed. When chosen, wireframe viewports display the surface as a wire mesh, and shaded viewports display the shaded surface. In wireframe viewports, this option lets you see the curve approximation used for viewports.
<nurbssurfaceapproximation>.isoULines : integer

This is used with the ISO line display. This is the number of additional interior iso lines in U (there are always lines along the outer edges).
<nurbssurfaceapproximation>.isoVLines : integer

This is used with the ISO line display. This is the number of additional interior iso lines in V (there are always lines along the outer edges).
<nurbssurfaceapproximation>.meshUSteps : integer

This is used for parametric tessellation. This is the number of tessellations in U. This is the number of sub-divisions for a knot span for the surface.
<nurbssurfaceapproximation>.meshVSteps : integer

This is used for parametric tessellation. This is the number of tessellations in V. This is the number of sub-divisions for a knot span for the surface.

1454

Chapter 11

3ds max Objects

<nurbssurfaceapproximation>.meshApproxType

: #parametric, #spatial, #curvature, : #regular, #spatialAndCurvature

This property controls the type of surface tessellation. If #parametric is specified, parametric tessellation is performed. This provides for a fixed number of meshUSteps by meshVSteps tessellations. There are meshUSteps times meshVSteps quadrilaterals and each one is split up into two triangles. If #spatial is specified, spatial tessellation is performed. This uses spacialEdge as its parameter. This specifies that the size of the tessellation will be the spacialEdge length. In view dependent tessellation spacialEdge is specified in pixels. If #curvature is specified, view dependent tessellation is performed. This uses the curvatureAngle and curvatureDistance property values. If #regular is specified, a fixed, regular tessellation across the surface is performed. If #spatialAndCurvature is specified, a tessellation method which combines the spatial and curvature methods is used. This uses the spacialEdge, curvatureAngle, and curvatureDistance property values.
<nurbssurfaceapproximation>.spacialEdge : float

This is the length of an edge to use in spatial (#spatial) tessellation. In view dependent tessellation this is specified in pixels. If not in view dependent tessellation this is a percentage of the bounding box diagonal length.
<nurbssurfaceapproximation>.curvatureAngle : float

This is used in curvature dependent tessellation (#curvature). If 0.0 is specified this is ignored. If specified this ensures that no two adjacent face normals exceed this angle between them. This value is specified in radians.
<nurbssurfaceapproximation>.curvatureDistance : float

This is used in curvature dependent tessellation (#curvature). If 0.0 is specified this is ignored. This specifies a distance that cannot be exceeded between a vertex on the mesh and the mathematical surface. This is defined as a percentage of the diagonal of the bounding box of the individual surface in object space. For instance if this was set to 1.0, the allowable error in generating a tessellation would be 1% of the bounding box diagonal distance of the surface. This would be 1/100 (1%) of the diagonal distance of the bounding box. In this way if an object is scaled the tessellation remains the same. Additionally, if you have an object with a big surface and a little surface, the smaller surface will get tessellated more finely because its own bounding box is used. This prevents the smaller surface from just becoming a single triangle for example.
<nurbssurfaceapproximation>.viewDependent : boolean

Specifies if this is view dependent tessellation. If true this will tessellate less finely the farther away from the camera the object is. If false the tessellation does not change based on distance from the camera.

See also
Value Common Properties, Operators, and Methods (p. 714)

NURBSTextureSurface : Value

1455

NURBSTextureSurface : Value
This class contains an editable texture coordinate surface corresponding to the editable texture surface in NURBS surfaces. You can create and apply them to any NURBSSurface value or retrieve existing texture surfaces using the getTextureSurface() and setTextureSurface() methods to access any of the 99 texture channels for a NURBS surface. 3ds max uses the texture surface to control how materials are mapped. In effect, changing the texture surface stretches or otherwise changes the UV coordinates for the surface, altering the mapping. This is a 2D (not 3D) surface that lives in the parameter space of the corresponding NURBSSurface which controls the texture mapping used by the NURBSSurface. It is not possible to assign texture surfaces to NURBS objects that are present in the scene. You can create new NURBSSets and the texture surface is used when you call createNURBSObject(). However, if you do a getNURBSSet() and assign a NURBSTextureSurface to a texture channel for a NURBS surface, nothing happens. Constructors:
NURBSTextureSurface [<property>:<val>]...

Any of the objects properties may be set via optional keyword arguments on the constructor.
getTextureSurface <nurbssurface> <channel_index> <nurbssurface>.textureSurface1 <nurbssurface>.textureSurface2

Provides backward compatibility for scripts written for 3ds max R2.5. Get and set the texture surfaces for the first two texture channels. Properties:
<nurbstexturesurface>.type : #default, #userDefined, #projected : integer : integer : integer -- read-only : integer -- read-only : point2

The type of texture surface.

<nurbstexturesurface>.parent <nurbstexturesurface>.parentID

The parent surface by NURBSet index. The parent surface by NURBSId.

<nurbstexturesurface>.numUPoints <nurbstexturesurface>.numVPoints <nurbstexturesurface>.numPoints

The number of U and V points. Methods:

getPoint <nurbstexturesurface> <u_index> <v_index> setPoint <nurbstexturesurface> <u_index> <v_index> <texturepoint>

Get or set a NURBSTexturePoint value for the texture point at the U and V index of the texture surface.

1456

Chapter 11

3ds max Objects

Associated Methods:
setTextureSurface <nurbssurface> <channel_index> <NURBSTextureSurface>

This method sets the texture surface for the selected channel. Note: The NURBSTextureSurface class has been updated to correspond to the new texture surface mechanism in 3ds max 4, and has different properties and methods that were defined in 3ds max R3.

See also
NURBSSurface (p. 1425) Value Common Properties, Operators, and Methods (p. 714)

Biped and Physique

The following topics describe the MAXScript access to Biped systems and the Physique modifier: Biped : System (p. 1456) Physique : Modifier (p. 1458) Biped-Related Classes (p. 1457) PhyContextExport Values (p. 1458) PhyRigidVertex Values (p. 1459) PhyBlendingRigidVertex Values (p. 1459) BipedExportInterface Values (p. 1458) The following is an example of accessing Physique data: Script:
phy = GetPhyContextExport $ $.physique format Physique Export Interface\n for v=1 to phy.numVerts do ( vx = GetVertexInterface phy v p = GetOffsetVector vx -format \tVertex # % assigned to %\t (v-1) (GetNode vx).name format %\n (if (classOf vx) == PhyRigidVertex then RIGID_TYPE) format \tOffset X: % Offset Y :% Offset Z: %\n p.x p.y p.z )

Biped : System
Constructor: Biped systems are nor creatable by MAXScript. Properties: There are no properties associated with Physique.

Biped-Related Classes

1457

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

Biped-Related Classes
The following classes associated with Biped systems. Instances of these classes are not creatable by MAXScript. Geometry:
Biped_Object : GeometryClass

This class represents the each object within the biped system.

See also
Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Controllers:
Vertical_Horizontal_Turn : Matrix3Controller

This class represents the transform controller for the root object within the biped system.
BipSlave_Control : Matrix3Controller

This class represents the transform controller for each object within the biped system. If the object does not have a transform controller (that is, it is a slave of another object in the biped), a value of undefined is returned.
Footsteps : Matrix3Controller

This class represents both the transform controller for the footsteps and the footstep object.

See also
Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1458

Chapter 11

3ds max Objects

BipedExportInterface Values
The BipedExportInterface class is an interface into a Biped. Constructor:
getBipedExportInterface <biped_node>

Returns an instance of BipedExportInterface class. The biped_node can be any node associated with the Biped system, including the footprints. Methods:
setNonUniformScale <BipedExportInterface> <boolean>

Biped-based bone systems created prior to character studio version R2.1 have non-uniform scaling on the nodes that make up the biped object. This scaling can cause difficulties when exporting the biped. This function removes or restores the non-uniform scaling on a biped object. If <boolean> is true the non-uniform scaling will be set, and false will remove it. All non-uniform scaling information has been removed from new bipeds created with version R2.1 or greater of character studio, and this method is not required for exporting these bipeds.

Physique : Modifier
Constructor:
physique ...

Properties: There are no properties associated with Physique.

See also
Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

PhyContextExport Values
The PhyContextExport class is an interface into the physique vertex data. It can be used to retrieve vertex data of the modifier. Currently it only supports rigid vertices (blended and non-blended). You can use convertToRigid() to convert all vertices into rigid. Constructor:
getPhyContextExport <node> <physique_modifier>

Returns an instance of PhyContextExport class. Properties:

<GetPhyContextExport>.numVerts

Returns the number vertices in the object. This property is read-only.

PhyRigidVertex Values

1459

Methods:
convertToRigid <PhyContextExport> <boolean>

Converts all vertices into rigid vertices. If a true value is passed then getVertexInterface() converts a deformable vertex into a rigid vertex and returns the vertex. If a false value is passed then getVertexInterface() returns undefined for a deformable vertex.
allowBlending <PhyContextExport> <boolean>

If a true value is passed then getVertexInterface() returns a PhyBlendingRigidVertex, if a vertex is blended, otherwise undefined.
getVertexInterface <PhyContextExport> <index_integer>

Returns the vertex given the vertex index. The vertex can be either PhyRigidVertex or PhyBlendingRigidVertex.

See also
PhyRigidVertex Values (p. 1459) PhyBlendingRigidVertex Values (p. 1459)

PhyRigidVertex Values
The PhyRigidVertex class representing a rigid vertex in a Physique modifier. A rigid vertex can be linked to only one node. Constructor:
getVertexInterface <PhyContextExport> <index_integer>

Returns the vertex given the vertex index. The vertex can be either PhyRigidVertex or PhyBlendingRigidVertex. Methods:
getNode <PhyRigidVertex>

Returns the node the vertex is linked to.

getOffsetVector <PhyRigidVertex>

Returns the coordinates of the vertex in the local coordinates of associated node.

PhyBlendingRigidVertex Values
The PhyBlendingRigidVertex class representing a blended vertex in a Physique modifier. A blended vertex can be linked to multiple nodes. Constructor:
getVertexInterface <PhyContextExport> <index_integer>

Returns the vertex given the vertex index. The vertex can be either PhyRigidVertex or PhyBlendingRigidVertex.

1460

Chapter 11

3ds max Objects

Properties:
<PhyBlendingRigidVertex>.numNodes

Returns the number of nodes the vertex is linked to. This property is read-only. Methods:
getNode <PhyBlendingRigidVertex> <index_integer>

Returns the indexed node the vertex is linked to.

getOffsetVector <PhyBlendingRigidVertex> <index_integer>

Returns the coordinates of the vertex in the local coordinates of indexed node.
getWeight <PhyBlendingRigidVertex> <index_integer>

Returns the weight of the indexed node on the vertex.

Missing Object Classes

The following classes are used to represent objects in the scene for which the plug-in defining the object class is missing. An example of this is if you load a scene containing a Biped, but you do not have the character studio plugins, the biped objects will be retained in the scene, and the objects class will be shown as the appropriate missing object class. These classes are not creatable by MAXScript and do not have any properties or methods.
Missing_Atmospheric

Standin for missing Atmospheric class objects.

Missing_Camera

Standin for missing Camera class objects.

Missing_Float_Control

Standin for missing Float controller class objects.

Missing_GeomObject

Standin for missing Geometry object class objects.

Missing_Helper

Standin for missing Helper object class objects.

Missing_Light

Standin for missing Light object class objects.

Missing_Matrix3_Control

Standin for missing Matrix3 controller class objects.

Missing_Morph_Control

Standin for missing Morph controller class objects.

Missing_Mtl

Standin for missing Material class objects.

Missing_OSM

Standin for missing Object Space Modifier class objects.

Missing_Point3_Control

Standin for missing Point3 controller class objects.

Missing_Position_Control

Standin for missing Position controller class objects.

PhyBlendingRigidVertex Values

1461

Missing_RefTarget

Standin for missing Reference Target class objects.

Missing_Render_Effect

Standin for missing Render Effect class objects.

Missing_Rotation_Control

Standin for missing Rotation controller class objects.

Missing_Scale_Control

Standin for missing Scale controller class objects.

Missing_Shape

Standin for missing Shape class objects.

Missing_System

Standin for missing System class objects.

Missing_TextureMap

Standin for missing TextureMap class objects.

Missing_UVGen

Standin for missing UVGen class objects.

Missing_WSM

Standin for missing World Space Modifier class objects.

Missing_WSM_Object

Standin for missing World Space Modifier Object class objects.

Missing_XYZGen

Standin for missing XYZGen class objects.

Scripting Vertex and Control Point Animation

You can add animation to vertices in editable meshes, spline shapes and FFD modifiers using the animateVertex() method. Its syntax is:
animateVertex <node_or_ffd_modifier> <vertex_spec>

Animates one or more vertex, knot, or control point, where <vertex_spec> is one of
<index> <index_array> #all #selected -- not applicable for FFD modifiers

For FFD modifiers, the animateAll() method will animate all the control points, and is equivalent to animateVertex <ffd_modifier> #all. Its syntax is:
animateAll <ffd_modifier>

Animates all control points. The animateVertex() and animateAll() methods effectively assign controllers to editable meshes, spline shapes and FFD modifiers which make them appear as animatables in the Track View, allowing further scripting of these vertex animation controllers.

1462

Chapter 11

3ds max Objects

Examples:
animateVertex $line01 2 animateVertex $box01 #(2,3,4,5) animateAll $box01.ffd_3x3x3

These animateVertex() method only work on editable meshes, spline shapes and FFD modifiers and will report an error if applied to other types of objects. You can use the functions convertToMesh() and convertToSplineShape() to convert existing geometry into the needed forms. Note that Line objects are SplineShapes already and dont need conversion. The vertices to be animated are specified by index number, with the keyword #all to animate all vertices or control points, or #selected to animate the currently selected vertices. The #selected keyword is not applicable to FFD modifiers. In the case of SplineShapes, the vertex index numbers are interpreted in a special way to accommodate tangent handles and multiple curves, as follows: Each SplineShape vertex has three indexes, one for each in-tangent handle, vertex, and outtangent handle, in that order. The indexes run consecutively through each curve in a multi-curve shape, with the index number for the first in-tangent handle of a curve starting after the index of the last out-tangent handle in the prior curve.

See also Class and Object Inspector Functions (p. 799) for details on accessing the vertices, tangents, or control points. For information about scripting FFD control placement within FFD lattice space, see also the getModContextBBoxMin() and getModContextBBoxMin() functions, as described in the Modifier Common Properties, Operators, and Methods (p. 1096) topic. For editable meshes and spline shapes, the controller values assigned to the vertices, knots, and tangent handles is in object space. See the Using Node Transform Properties (p. 843) topic for information on converting between world space to object space.

Chapter 12:

Creating MAXScript Tools

Scripted Utilities
MAXScript provides a set of classes and functions and some special syntax to allow you to construct custom rollouts that can be incorporated into the existing 3ds max user interface. You typically use custom rollouts to provide a point-and-click interface to a tool that you have written or want to write in MAXScript, so users of your tool dont have to work with it at the script level. There are two places in the 3ds max user interface where you can install scripted rollouts: In the Utilities panel. You use the utility definition construct in MAXScript to define and install scripted utilities. Once installed, they appear in the Utilities list at the bottom of the MAXScript rollout. If the user selects a utility in this list, its rollout(s) appear below the MAXScript rollout and functions just like a plug-in utility. In special modeless rollout floater windows that you can create with the newRolloutFloater() function. These windows appear on the desktop and function in a way similar to the Material Editor and the Selection floater in 3ds max. You can click to alternate between them and the main 3ds max user interface. You create individual rollout(s) for these windows using the rollout definition construct in MAXScript and install them in a rollout floater window using the addRollout()function.

Choosing which place is best for your scripted rollouts depends on a number of factors. It is best to keep them in the Utilities panel if possible, as that maximizes the use of the screen and is consistent with the 3ds max user interface conventions. However sometimes it is useful to have them in a modeless window if the user of your tool needs to move between the various command panels while using the tool. In some cases, you might want to provide a float me button on a scripted Utility rollout, similar to the Color Clipboard utility, so the user can choose to display the rollouts in a rollout floater window or in the Utilities panel. The following topics provide information about scripting utility panels and rollout floater windows: Scripted Utility Panels (p. 1464) Utility Clauses (p. 1466) Managing Multiple Rollouts in a Scripted Utility (p. 1468)

1464

Chapter 12

Creating MAXScript Tools

Rollout Clauses (p. 1470) Utility and Rollout Properties, Methods, and Event Handlers (p. 1474) Rollout User-Interface Controls (p. 1481) Visibility of Locals, Functions, Structures and User-Interface Items in Rollout Code (p. 1478) Accessing Locals and Other Items in a Rollout from External Code (p. 1480) Rollout Floater Windows (p. 1477)

Scripted Utility Panels

A scripted utility panel is created using the utility definition construct in MAXScript. The top-level syntax is as follows:
utility <var_name> <description_string> [ rolledUp:<boolean> ] [ silentErrors:<boolean> ] ( <utility_body> )

The <var_name> is the name of an automatically created global variable to hold the value that represents the scripted utility panel. The <description_string> is a string which is used as the description for the utility in the Utilities list in the MAXScript rollout. The optional rolledUp: parameter specifies whether the utility rollout is initially rolled up. If set to true, the utility rollout is initially rolled up. The default value is false. The optional silentErrors: parameter controls whether MAXScript runtime error messages are displayed while executing the scripted utility. If this parameter is set to false, error messages are displayed to Listener and possibly to a pop-up error dialog, and continued execution of the utility is terminated. If this parameter is set to true, error messages will not be displayed, and continued execution of the utility is permitted. Setting this parameter to true is useful for distributed scripted plug-ins that may confuse the user with MAXScript error messages. The default value is false. The <utility_body> is inside the required parentheses and is a sequence of clauses that defines the user-interface items that will appear in the utility, along with functions and event handlers that process user interactions, as defined in detail in the Utility Clauses (p. 1466) topic. Here is a short example that implements a utility for spreading the positions of the objects in the current selection. It installs a Spread objects entry in the Utilities list. When opened, the Spread objects rollout has three check boxes and one spread amount spinner. The spread spinner event handler is called whenever the user adjusts the spinner, and the event handler expression computes a new position for the objects in the selection, testing the state of each check box to control the spread.

Scripted Utility Panels

1465

Script:
utility spread Spread objects -- define the utility name and description string ( local last_amt = 0 -- define and initialize local variable -checkbox x Spread in x -- create 3 checkboxes checkbox y Spread in y checkbox z Spread in z spinner spread Spread amount: range:[-1000,1000,0] -- create a spinner -on spread changed amt do -- when spinner value changes... ( delta = amt - last_amt -- calculate difference in current and previous for obj in selection do -- values for each selected object ( -- calculate new position based on current position and selection center p = obj.pos + normalize (obj.pos - selection.center) * delta if x.checked then obj.pos.x = p.x -- if checkbox x checked, apply X position if y.checked then obj.pos.y = p.y -- if checkbox y checked, apply Y position if z.checked then obj.pos.z = p.z -- if checkbox z checked, apply Z position ) last_amt = amt -- store spinner value as previous value ) -- end of on spread changed ) -- end of utility definition

The Utilities panel rollout created by the previous script looks like the following figure. The Close button is automatically created by MAXScript in the utility rollout, and closes the rollout.

Spread objects rollout

Evaluating a utility definition does several things. It creates a new value which is an instance of the Rollout class and contains the utility definition. It assigns this value to the named global variable and installs the utility description in the Utilities list in the MAXScript rollout. At this point, the user can select the utility from the Utilities list and the utilitys rollout(s) will open. Note: If a scripted utility already exists with the same description, the old rollout(s) is replaced with the new one(s), even if it is currently open in the Utilities panel. This allows you to incrementally develop a utility. Each time you modify and evaluate its definition, the old version is replaced with the new one.

1466

Chapter 12

Creating MAXScript Tools

Utility Clauses
The <utility_body> of a scripted utility definition is composed of a sequence of utility clauses as follows:
<utility_body> ::= { <utility_clause> }+

where
<utility_clause> ::= <rollout_clause> | <nested_rollout>

A <utility_clause> can contain one or more instances of <rollout_clause> or <nested_rollout>. A nested rollout is basically another self-contained rollout definition which can be used to construct scripted utilities with multiple rollouts or populate rollout floater windows that may be associated with the utility. A <nested_rollout> is defined as follows:
rollout <var_name> <description_string> [ rolledUp:<boolean> ] [ silentErrors:<boolean> ] ( <rollout_body> )

where
<rollout_body> ::= { <utility_clause> }+

In other words, a rollout definition is identical to a utility definition except its description string is not displayed in the Utilities list in the MAXScript rollout. In fact, a utility can just be considered a special case of a rollout, and both are instances of the Rollout class. As an example, consider the following script. In this script, line 1 defines the start of the utility, and the utility body is lines 2 through 42. The following line ranges are utility clauses: 3 (a rollout clause), 5 to 9 (a nested rollout), 11 to 30 (a nested rollout), 32 to 35 (a rollout clause), and 37 to 40 (a rollout clause). Script:
utility MyUtil My Utility ( local pot -rollout bout About My Utility ( button aboutMU About width:45 height:20 on aboutMU pressed do messagebox My First Utility\nby ME\nVersion .1 \ title:About My Utility )--end rollout bout -rollout creator The Teapot ( group Object Creator ( button tea Teapot spinner rad Radius range:[10,50,20] type:#integer spinner seg Segments range:[4,32,12] type:#integer scale:1 )

Utility Clauses

1467

-on tea pressed do ( pot=teapot radius:rad.value pot.name=TestPot pot.segs=seg.value ) -- end on tea pressed -on rad changed value do pot.radius=value -on seg changed value do pot.segs=seg.value -) -on MyUtil open do ( addRollout bout addRollout creator ) -- end on MyUtil open -on MyUtil close do ( removeRollout bout removeRollout creator ) -- end on MyUtil close -)--end utility MyUtil -- end rollout creator

The Utilities panel rollouts created by the previous script look like the following:

Multiple rollouts defined in a utility

You can also define rollouts outside utility definitions when you want to add them to a rollout floater window that may not be associated with a scripted utility. This is described more fully in the Rollout Floater Windows (p. 1477) topic.

1468

Chapter 12

Creating MAXScript Tools

A value is created for a utility or rollout when the script defining the utility or rollout is executed. In general, the lifetime of a utility value is the entire 3ds max session, unless a new utility with the same name is executed. The lifetime of a rollout defined in a utility is the lifetime of the utility value. The lifetime of a rollout defined outside a utility is the lifetime of the context the rollout was defined in. For more information, see the Scope of Variables (p. 646) topic.

Managing Multiple Rollouts in a Scripted Utility

MAXScript includes support for managing multiple rollouts in one utility, which is useful in large scripted utilities that would be unwieldy in one rollout. There is one main rollout defined by the user-interface items in the utility definition itself. The other rollouts are defined as nested rollouts within the body of the utility definition. These other rollouts can be added to and removed from the Utilities panel under script control. You define extra rollouts with the rollout clause inside a utility definition:
utility foo name ( local ... spinner ... ... rollout baz name ( local ... checkbox .. on ... ) ... )

Such nested rollouts can contain anything a utility definition can contain with the exception of further nested rollouts. Nested rollouts are not automatically opened or closed when the parent utility rollout opens and closes. You need to explicitly do this in the open and close handlers or other handlers or functions in the utility. There are two new functions for this:
addRollout <rollout> [ rolledUp:<boolean> ] removeRollout <rollout>

The rolledUp: parameter on the addRollout() function specifies whether the rollout is added in a rolled-up state. This defaults to false, so the rollout is added fully opened. The nested rollouts are arranged in the order of addRollout() calls, so take care in sequencing these to ensure the order you want. The nested rollouts do not automatically get removed when the main utility rollout is closed. You must make sure they are explicitly removed, typically in the close handler for the main utility.

Managing Multiple Rollouts in a Scripted Utility

1469

To always open and close extra rollouts when the main utility is opened and closed, place addRollout() and removeRollout() calls in the main utility open and close handlers. For example:
on foo open do ( ... addRollout panel_1 addRollout panel_2 rolledUp:true ... ) on foo close do ( ... removeRollout panel_1 removeRollout panel_2 ... )

Calling removeRollout() on an already closed rollout is OK and does nothing. If, during utility development, you forget to close a nested rollout, closing the entire MAXScript utility will remove any remaining open scripted rollouts. Because these rollout definitions are nested within a utility, all the locals, functions, and other items in the utility are visible to nested rollouts, following the standard nested scoping in MAXScript. This means you can reach out and access the utilitys locals, user-interface control items, and functions. Conversely, user-interface control items and locals in nested rollouts are exposed as properties of that rollout, so code in the main utility or other rollouts can reach in and access them. In the following example, the spinner bar change handler looks at the state of a check box in the nested rollout baz:
utility foo name ( local ... spinner bar ... ... rollout baz name ( local ... checkbox baz_enable ... on ... ) ... on bar changed val do if baz.baz_enable.checked == true then ...

1470

Chapter 12

Creating MAXScript Tools

Rollout Clauses
Rollout clauses define the components of a rollout (utilities are considered a special case of rollouts) and can be one of four basic things: Local variables, functions, or structure definitions are variables, functions, and structures whose scope is the rollout. These locals will exist as long as the rollout value exists. The rollout value will exist until a new value is assigned to the rollouts variable name. Local variables are particularly useful for storing working data associated with the rollout such as picked objects or arrays of generated objects. The visibility of locals, and accessing rollout locals from external code, are described in the Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code (p. 1478) and Accessing Locals and Other Items in a Rollout from External Code (p. 1480) topics. Mouse tools are used to perform a set of actions based on mouse clicks in the 3ds max viewports, and are described in the Scripted Mouse Tools (p. 1531) topic. User-interface control items are elements displayed in the rollout, such as buttons, spinners, and list boxes. Event handlers are special kinds of functions associated with particular user-interface control items. Event handlers specify the processing you want to occur when a user interacts with a userinterface item. For example pressing a button or adjusting a spinner. These user actions generate named events and the optional event handler you supply for that event is called when the user action occurs. For example, if you press a button named DoIt, the on DoIt pressed event handler expression is executed.
<rollout_clause> ::= <local_variable_decl> <local_function_decl> <local_struct_decl> <mousetool> <user_interface_item> <item_group> <event_handler> | | | | | |

Formally, the syntax of a <rollout_clause> is defined as follows:

Locals: A <local_variable_decl>, <local_function_decl>, and <local_struct_decl> are exactly the same as local variable, function, and structure definitions in MAXScript:
<local_variable_decl> ::= local <decl> { , <decl> } <decl> ::= <name> [ = <expr> ] -- optional initial value <local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr> <local_struct_decl> <member> ::= struct <name> ( <member> { , <member> } ) ::= ( <name> [ = <expr> ] | <local_function_decl> )

Rollout Clauses

1471

Examples of the previous (in order) are:

local numSelected local numSelected = 0 fn onlyOneSelected = (selection.count == 1) struct parents (mother=, father=)

Global variables cannot be declared as a rollout clause, however they can be declared within event handler scripts. If you need to ensure that a variable name references a global variable, declare the variable name as global immediately before defining the utility in your script. When writing scripts, it is good programming practice to explicitly declare your local and global variables. Implicit declaration is provided as a short-hand, typically used when working in the Listener interactively or developing short scripts. When developing extended scripts, explicitly declaring variables can reduce errors and improve readability of the code. It is also recommend that you declare as local all variables unless you really want them to be global variables. The reasons for this are described in the Scope of Variables (p. 646) topic. User-Interface Items A <user_interface_item> defines an individual button, check box, spinner, or other userinterface control item that will appear in the rollout. These user-interface control items are described in the Rollout User-Interface Controls (p. 1481) topic. An <item_group> is used to place a sequence of user-interface items in a labeled box in the rollout, so you can organize large rollouts into meaningful groups. Its syntax is:
group <group_label_string> ( { <user_interface_item> } )

The use of group is shown in the following script:

Utility Infinity Game Utilities ( group Lighting ( label label1d Number of Day lights: across:2 offset:[10,0] label label2d 0 offset:[10,0] label label1n Number of Night lights: across:2 offset:[13,0] label label2n 0 offset:[10,0] label label3 Radiobuttons WhichOn Active Lights: labels:#(Day,Night) ) group Scene Data Dump ( Button scenedump Dump Scene Data ) group Exclusions/Inclusions ( Button DispExcl Unhide Exclusions&Inclusions )

1472

Chapter 12

Creating MAXScript Tools

group Camera Mattes ( radiobuttons CamMatte labels:#(None,1,2,3,4) columns:3 ) Button resetb Reset )

The Utilities panel rollout which the previous script generates looks like the following figure.

Game Utilities rollout using group user-interface item

Event Handlers: An <event_handler> is a special function definition local to a utility or rollout that you provide to handle the processing you want to occur when a user performs an action on a user-interface item. For example, event handlers are called when the user presses a button or adjusts a spinner, opens or closes the utility or rollout, or resizes or moves a rollout floater window. These user actions generate named events and any event handler you supply for that event is called when the action occurs. The syntax for defining an event handler is as follows:
on <item_name> <event_name> [ <argument> ] do <expr>

Rollout Clauses

1473

The <item_name> specifies the name of the item to which this handler is connected. The <event_name> specifies the type of event to be handled and the optional <argument> is used to pass various values to the handler. The possible events you can specify depend on the item type. These events include:
pressed changed picked entered selected resized moved open close

The available events and the arguments passed are defined in the description for each user-interface item type, as listed in the Rollout User-Interface Controls (p. 1481) topic. The available events and the arguments passed for utilities and rollouts are described in the Utility and Rollout Properties, Methods, and Event Handlers (p. 1474) topic. You can access and invoke the event handler functions in a scripted rollout by referring to the handlers as properties on the user-interface items. The event handler functions are accessed as sub-properties of the item, using the event name as the sub-property name. For example, if a scripted rollout had a check box item named foo, and an on foo changed event handler was defined, you could invoke the handler as follows:
foo.changed true -- call foos changed handler function, passing argument of true

Or, if a scripted rollout had a button item named apply, and an on apply pressed event handler was defined, you could invoke the handler as follows:
apply.pressed() -- call applys pressed handler function, no argument.

You can access an event handler function as a sub-property of the item. For example,
ApplyPressedEH = apply.pressed

stores a copy of the on apply pressed event handler function value to variable ApplyPressedEH. The event handler functions can only be read in this way. You cannot set the handler function to another user-defined function.

1474

Chapter 12

Creating MAXScript Tools

Utility and Rollout Properties, Methods, and Event Handlers

Properties: Several properties are available for scripted utilities and rollouts which provide control over whether a rollout is open and the rollout scroll state. These properties are:
<rollout_or_utility>.open Boolean

Indicates whether the rollout is in an open or rolled-up state. If true, the rollout is open, false it is rolled up. You can assign true or false to this property to open or roll up the rollout.
<rollout_or_utility>.scrollPos Integer

This property is, strictly speaking, a property of the entire collection of rollouts in a rollout floater window or the Utilities panel, and gives the scroll position for the rollout set when opened in a panel that is too small to show all the rollouts. It can be accessed as a property on any rollout currently present in a rollout floater window or the Utilities panel. You can implement a form of rollout state save and restore for your scripted rollouts by recording the open state of all rollouts and the scrollPos of the entire panel during close handler processing, and then reset the values in the open handler. Methods: Several methods are available for opening and closing utilities, and adding and removing rollouts in the Utilities panel. These methods are:
openUtility <utility>

Opens the utilitys main rollout in the Utilities panel. This is equivalent to selecting the utility from the Utilities list in MAXScripts Utilities panel rollout.
closeUtility <utility>

Closes the utilitys main rollout in the Utilities panel. This is equivalent to clicking the Close button in this rollout.
addRollout <rollout> [ rolledUp:<boolean> ]

Adds the rollout to the Utilities panel. The rolledUp: parameter on the addRollout() function specifies whether the rollout is added in a rolled-up state. This defaults to false, so the rollout is added fully opened. The extra rollouts are arranged in the order of addRollout() calls, so take care in sequencing these to ensure the order you want.
removeRollout <rollout>

Removes the rollout from the Utilities panel. See the Managing Multiple Rollouts in a Scripted Utility (p. 1468) topic for more information on the addRollout() and removeRollout() methods.

Utility and Rollout Properties, Methods, and Event Handlers

1475

Event Handlers: In addition to the event handlers you specify for particular user-interface items in a rollout, you can define handler functions that are called when an entire rollout is first opened (open) or explicitly closed (close) by the user. These event handlers are useful for initialization code or for cleaning up when a rollout closes, and are necessary when managing multiple rollouts in one scripted utility. If a rollout floater window is resized or moved, an event handler (resized or moved, respectively) is called on the first rollout in the rollout floater window. An additional event handler (oktoclose) is called to verify that it is OK to close a rollout. The syntax is as follows:
on <rollout_or_utility> open do <expr>

Called when the rollout or utility is opened.

on <rollout_or_utility> close do <expr>

Called when the rollout or utility is closed.

on <rollout_or_utility> oktoclose do <expr>

Called when the user clicks the rollouts Close button so the script writer can decide whether to allow the close to proceed. If the expression evaluates to the value true, the rollout is allowed to close. If the expression evaluates to the value false, the action attempting the close is ignored and the rollout or utility is left open.
on <rollout> resized <arg> do <expr>

Called on first rollout in a rollout floater window when it is resized either by the user or by a script changing the size property of the rollout floater window. Changing the rollout floater window size in the resized event handler expression will not cause the resized event handler to be called again. The value of <arg> is the current width and height of the rollout floater window. For example:
global my_rof_size ... on my_rollout resized size do ( my_rof_size = size -- save the new window size ) on <rollout> moved <arg> do <expr>

Called on first rollout in a rollout floater window when it is moved either by the user or by a script changing the pos property of the rollout floater window. The value of <arg> is the current position of the rollout floater window on the screen in pixels.

1476

Chapter 12

Creating MAXScript Tools

The following example keeps a log file of its actions, and uses the rollout open and close handlers to open and close the log file:
utility frab Optimal Frabulator ( local log spinner frab_x ... button do_it Enfrabulate now ... on do_it pressed do ( frabulate selection format selection frabbed at %\n localTime to:log ) on frab open do log = createFile frabulator.log on frab close do close log )

In the following example the utility will not close unless the OK To Close check button is pressed: Script:
utility ui_oktoclose OKToClose Test ( checkbutton a2 OK To Close on ui_oktoclose oktoclose do a2.state )

In the following example the on a resized event handler is called when the rollout floater window is resized. Because the event is generated only for the first rollout in a rollout floater window, the on b resized event handler is never called. Script:
rollout a Rollout A ( button a1 a1 on a resized val do (format A: %\n val) ) -rollout b Rollout B ( button b1 b1 on b resized val do (format B: %\n val) ) -rof=newrolloutfloater test 200 200 addrollout a rof addrollout b rof rof.size=[300,300]

Rollout Floater Windows

1477

Rollout Floater Windows

MAXScript lets you create modeless dialog windows and populate them with rollouts defined using global rollout definitions or utility rollout definitions. The user can resize a rollout floater window vertically by dragging on the lower window edge. There are two functions and a special class in support of this, as follows:
newRolloutFloater <title_string> <width_integer> <height_integer> \ [<top_integer> <left_integer>]

Creates and opens a new rollout floater window with the title and width and height given. If you dont supply top and left coordinates, the window will open centered in the screen. The width of the 3ds max command panel is 218, in case you want to duplicate its width for precisely accommodating Utilities panel rollouts. This method returns a RolloutFloater value to which you add rollouts.
closeRolloutFloater <rolloutFloater>

Closes the rollout floater window. The user can also do this by clicking the close box on the window. Once closed, the window is no longer usable. All the close handlers in the rollout floater windows rollouts are called and they are released for use in other rollout floater windows or scripted utilities. The existing functions for adding and removing rollouts to the Utilities panel are extended to work with rollout floater windows:
addRollout <rollout> [ <rolloutFloater> ] [ rolledUp:<boolean> ]

If the optional second argument is specified, it must be a RolloutFloater value as returned from the newRolloutFloater() function. The rollout specified by the first argument is appended after any rollouts previously in the window.
removeRollout <rollout> [ <rolloutFloater> ]

Removes the rollout from the given rollout floater window. In both functions above, if the optional <rolloutFloater> is not supplied the rollout is added to, or removed from, the Utilities panel, as described in the Managing Multiple Rollouts in a Scripted Utility (p. 1468) topic. Rollout floater windows have the following properties:
<rolloutFloater>.size Point2

The current size of the rollout floater window in pixels. The first component of the Point2 is the width, the second the height. This property is read/write.
<rolloutFloater>.pos Point2

The current screen position of the rollout floater window in pixels. This property is read/ write. When a rollout floater window is resized, either by the user or by a script changing the size property, a resized event is generated for the first rollout in the rollout floater window. Likewise, when a rollout floater window is moved, either by the user or by a script changing the pos property, a moved event is generated for the first rollout in the rollout floater window. The event handler for

1478

Chapter 12

Creating MAXScript Tools

the resized and moved events are described in the Utility and Rollout properties, Methods, and Event Handlers (p. 1474) topic. Example:
rollout grin Grin Control ( slider happy Happy orient:#vertical across:5 slider sad Sad orient:#vertical slider oo OO orient #vertical slider ee EE orient #vertical slider oh OH orient:#vertical on happy changed val do object.xform1.center = ... on sad changed val do object.xform2.gizmo.rotation = ... ... ) gw = newRolloutFloater Grinning 300 220 addRollout grin gw

Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code

The ordering of user-interface items and functions and sub-rollouts in a utility is important when referencing other items and rollouts in handler or local function code. Specifically, you can only reference a user-interface item or rollout or function in a handler or other function if that item or rollout or function has been defined earlier in the utility. A recommended ordering can help ensure this:
local variables structs user-interface items nested rollouts functions event handlers

In some situations, cross-referencing means theres no way to order definitions and still pre-define everything. To remedy this, MAXScript lets you pre-declare local rollouts and functions, so code that comes before the function or rollout definition will see the correct object. You do this by declaring such rollouts and functions as uninitialized locals. In the following example, there are two rollouts, ro1 and ro2, that each want to reference items within the other. By pre-declaring them as locals in the main utility, this cross-referencing is possible:

Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code

1479

utility foo name ( local ro1, ro2, ... -- declare local rollouts ... rollout ro1 name ( local ... checkbox enable ... on ... do ro2.enable.checked = false ) ... rollout ro2 name1 ( local ... checkbox enable ... on ... do ro1.enable.checked = true ) ... )

As a general rule, it is recommended that all local variable names be explicitly declared as locals at their outermost scope. This will prevent any conflicts from occurring if another script has declared the same variable name as a global variable. While functions, structures definitions, and rollouts will always be local to the utility they are defined in (even if they have the same name as a global variable), declaring these as local will ensure the variables are defined, even if the order in which they are defined is changed. Heres an example showing these declarations:
utility foo Object Frabulator ( -- local variables local target_obj -- local functions local prop_name -- local rollouts local setup fn prop_name obj name = for c in obj.children do c.name = name + _ + c.name checkbutton setup_btn Setup edittext name_box New name: -- use a checkbutton to dynamically control presence of panels on setup_btn changed state do if state then addRollout setup else removeRollout setup on foo close do removeRollout setup rollout setup Setup fraber (

-- always close rollouts -- local panel

1480

Chapter 12

Creating MAXScript Tools

label hello pickbutton pick_tgt Pick object on pick_tgt picked obj do ( target_obj = obj -- access utility local name_box.text = obj.name -- access utility item prop_name obj obj.name -- call utility local fn ) ) )

Accessing Locals and Other Items in a Rollout from External Code

The local components defined in a scripted utility or rollout are accessible to external code as properties of the utility or rollout object. Recall that the rollout object is assigned to a new global variable (or local variable if a nested rollout) named on the utility or rollout definition. Example:
utility foo Object Frabulator ( local var1, var2, ... ... checkbox enable Enable frabber ... rollout setup Setup frabber ( local var3 button doit Execute ... on doit pressed do ... ) function frab a b = ... ... on enable changed state do ... ... )

-- local panel

The example defines the utility and places the utility object in a global variable named foo. You can access components in the utility from the Listener or other code as properties of that object, using the name of the variable or item as the property name. Any event-handler functions supplied for user-interface items can also be accessed as sub-properties of the item, using the event name as the property name. For example:
print foo.var1 if foo.enable then ... foo.enable = false foo.enable.changed false foo.frab $box01 $box02 foo.setup.var3=10 foo.setup.doit.pressed() setup rollout -------get foos local variable, var1 test foos enabled checkbox set it call its changed handler function call its frab function set foos setup rollout local variable, var3 call changed handler function for doit button in

Rollout User-Interface Controls Common Properties

1481

The local variables, functions, and structures in scripted utilities and rollouts are initialized as soon as the utility or rollout is first defined, rather than when the utility or rollout is first displayed. This allows other code to use local functions and set local values at any time after definition.

Rollout User-Interface Controls

There are 16 types of user-interface control items that you can choose from to construct your rollout. They all share the same overall syntax:
<item_type> <name> [ <label_string> ] [ <parameters> ]

The item types correspond to the types of user-interface control items you see in typical 3ds max rollouts. The types of user-interface control items are described in the Rollout User-Interface Control Types (p. 1484) topic. The <name> is used to name an automatically constructed rollout local variable that will hold the value representing the control item, and is used to associate event handler functions with the control item. The optional <label_string> is used as a caption, item label, or text content depending on the control item type, as described in the topics for each type. The optional <parameters> is a sequence of keyword arguments used to set options or influence layout for the control item. The exact parameters that each control item type supports is also defined in the topics for each type. There are properties associated with each of the user-interface control item types. The properties that are common to all user-interface control item types are described in the Rollout User-Interface Controls Common Properties (p. 1481) topic. Properties that are unique to a user-interface control item type are defined in the topics for each type. As you define a sequence of control items, MAXScript will by default automatically lay them out in the rollout, one below the other in the order they are defined. You can override this layout or make adjustments to it using special layout parameters defined in the Rollout User-Interface Controls Common Layout Parameters (p. 1483) topic.

Rollout User-Interface Controls Common Properties

All defined user-interface controls have a local variable constructed for them in the rollout and a value representing the control is placed in that variable. These values typically contain state information relevant to the item, such as if a check box is checked, the current spinner value, the items in a list box, and so on. This information is made available to you as various named properties on the item values. You use standard MAXScript property access to read and set these values, for example:
frab_x.enabled = true

enable the frab_x spinner

foo.text = Dont do it

set foo button text

first_item = baz.items[1]

get item list from listbox baz

1482

Chapter 12

Creating MAXScript Tools

$bar.pos.x = x_spinner.value

get current value from spinner x_spinner All of the user-interface common properties except for caption (the label string value is used as the caption) can be specified as parameters when the user-interface item is constructed. For example:
button foo Press Me! enabled:false

The following properties are common to all user-interface items:

<ui_item>.caption String

The meaning of this property varies depending on the specific user-interface item type. If the user-interface item has a caption, this property contains the caption string. For the various types of buttons, it is the text inside the button. The default value of the caption is the label string specified in the item definition.
<ui_item>.text String

For all the user-interface items except edittext and combobox, the text property is an alias of the caption property. For edittext and combobox user-interface items, it is the text in the edit box. The default text property value for edittext user-interface items is a null string (). The default text property value for combobox user-interface items is the selected items text.
<ui_item>.enabled Boolean default: true

Sets whether the item is enabled for interaction when the rollout is initially opened. Disabled items appear unavailable in the rollout. All items are enabled by default, so you typically use this parameter to disable those items that should not initially be available to the user. For example, you might have some spinners that change the properties on a scene object that should not be changed until the user has picked the object, typically with a pickbutton in the rollout. You would disable the spinner in its definition, as in the following example, and enable it once the user picked an object.
spinner frab_x Frabulate x-axis: range:[0,100,0] enabled:false ... frab_x.enabled=true <ui_item>.pos Point2 default: varies

This forces the user-interface item to a fixed [x,y] pixel position in the rollout, with [0,0] at the top-left corner. Notes: Due to limitations in 3ds max, you cannot specify a node using a Pickbutton in the Create panel, for example in a scripted Geometry plugin. The work-around is to only enable the Pickbutton when the object is open in the Modify Panel.

See also
Rollout User-Interface Controls (p. 1481) Rollout User-Interface Controls Common Layout Parameters (p. 1483)

Rollout User-Interface Controls Common Layout Parameters

1483

Rollout User-Interface Controls Common Layout Parameters

The layout of user-interface items defined in a utility or rollout is, by default, handled by MAXScript. It places each successive interface item down the rollout, one below the other, horizontally and vertically aligning them to match the layout conventions in the built-in 3ds max command panels. For the most part, this works well, particularly for rollouts displayed in the Utilities panel, because there is usually just enough room for one item across. In some cases, you may want to adjust or override the automatic layout and for this there are a number of definition-line layout parameters you can use. The user-interface element <parameters> that can be supplied in the item definition varies with the item type and is defined in each types topic, for example spinner ranges, check box initial states, list box contents, and so on. There is, however, a set of common layout parameters that you can specify on any user-interface item. Except for the pos parameter, these parameters are not properties of the user-interface item and cannot be accessed or changed by a script. The common layout parameters for all user-interface items are:
align:#left align:#center align:#right

Aligns the user-interface item to the left, center, or right in the rollout. Default varies by type.
offset: <point2> default: [0,0]

Specifies an [x,y] offset in pixels relative to automatic placement. This is applied after all other layout parameters are applied, and can be used to adjust them.
width: <number> default: varies

Forces the user-interface item to a specified width in pixels. Useful with buttons, for example, which otherwise self-size to their text label. Specifying an explicit width always overrides any widths computed from the text or caption properties. For example, if a spinner is given a fixed width that is too small for both label and spinner, it always aligns things to show the spinner and so might push the text out of view.
height: <number> default: varies by type

Forces the user-interface item to a specified height, typically in pixels. This lets you override the default setting height for user-interface items. For example
button foo Stop width:75 height:25

makes a nice big stop button. For comboBox, dropdownList and listBox user-interface items, the height is in text rows. To have a comboBox exactly display N items, set height to N+2. To have a dropdownList exactly display N items in the list, set height to N+2. To have a listBox exactly display N items, set height to N. Height has no affect on spinner and slider user-interface items.

1484

Chapter 12

Creating MAXScript Tools

across: <number>

default: 1

Causes this and following <number>-1 items to be laid out horizontally rather than vertically. The <number> given defines how many items to arrange horizontally. Layout then reverts to normal vertical placement. This parameter effectively divides the utility into the given number of equal-width columns and places items within them using the normal alignment for each item. The other layout parameters can be used with the across: parameter to control layout within the items column.
pos: <point2> default: varies

This forces the user-interface item to a fixed [x,y] pixel position in the rollout, with [0,0] at the top-left corner. Examples:
button foo foo align:#right

normal alignment is center

button baz baz align:#right offset:[0,6]

align right and bump this button down a bit

radiobuttons btn1 Size: labels:#(Big, Bigger, ...) columns:3

three columns of buttons

checkbutton b1 yes across:3 checkbutton b2 no checkbutton b3 maybe

put b1, b2, b3 across

spinner s1 Length: align:#left

normal alignment is right

See also
Rollout User-Interface Controls (p. 1481) Rollout User-Interface Controls Common Properties (p. 1481)

Rollout User-Interface Control Types

There are 17 types of user-interface controls you can choose from to construct your rollout. The user-interface control types are: bitmap (p. 1487) button (p. 1488) checkbox (p. 1489) checkbutton (p. 1490) colorpicker (p. 1492) combobox (p. 1493) dropdownlist (p. 1494) edittext (p. 1496) label (p. 1497)

Rollout User-Interface Controls Common Layout Parameters

1485

listbox (p. 1497) mapbutton (p. 1499) materialbutton (p. 1500) multilistbox (p. 1502) pickbutton (p. 1504) progressbar (p. 1505) radiobuttons (p. 1506) slider (p. 1507) spinner (p. 1509) timer (p. 1512) The following script will display all of the user-interface types in the Utilities panel: Script:
utility ui_items ui items ( bitmap a1 bitmap:(bitmap 50 50) button a2 button checkbox a3 checkbox checkbutton a4 checkbutton colorpicker a5 colorpicker: combobox a6 combobox: items:#(1 / 2, 1 / 4, 1/8) height:5 dropdownlist a7 dropdownlist: items:#(1 / 2, 1 / 4, 1/8) edittext a8 edittext: label a9 label listbox a10 listbox: items:#(1 / 2, 1 / 4, 1/8) height:3 mapbutton a11 mapButton materialbutton a12 materialbutton pickbutton a13 pickbutton progressbar a14 radiobuttons a15 radiobuttons: labels:#(lbl 1, lbl 2, lbl 3) spinner a16 spinner: slider a17 slider: timer a18 )

1486

Chapter 12

Creating MAXScript Tools

The resulting Utilities panel rollout will appear as:

Utilities rollout showing all user-interface items

Bitmap

1487

Bitmap
A bitmap item is used to place a bitmap image on the rollout. The syntax is:
bitmap <name> [ <caption> ] \ [ fileName:<filename_string> | bitmap:<bitmap> ]

The default alignment of bitmap items is #center. There is no caption or text displayed with bitmap items. Example:
bitmap the_bmp fileName:my_pic.bmp

Parameters:
fileName:

The name of the bitmap file to load and display. The size of the bitmap image in the rollout is the bitmap file image size. The specified file name is searched for in the following directories (in order of search): current MAXScript directory, MAXScript startup directory, MAXScript directory, 3ds max bitmap directories, and then the 3ds max image directory.
bitMap:

You can specify a bitMap: creation parameter in place of the fileName: parameter that is used to specify a bitmap file. This allows you to use an existing bitmap value, such as those generated by a call to the render function. You can set bitmap to an empty image of a specified size by specifying a bitmap value constructor. For example:
bitmap BitmapImage bitmap:(bitmap 50 50)

Properties:
<bitmap>.fileName String

The bitmap item file name as a string. You can change the image at any time by setting this property to a new name, but it will not resize the display area in the rollout; it will always be the size set from the initial image.
<bitmap>.bitmap TextureMap

A write-only property that is used to set the image displayed from a MAXScript bitmap value, as might be derived from functions like render() or selectBitmap(). You can change the image at any time by setting this property to a bitmap value, but it will not resize the display area in the rollout; it will always be the size set from the initial image. Events: -- none --

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

1488

Chapter 12

Creating MAXScript Tools

Button
A button item is used to place a press button on the rollout which the user can click, typically to have some task performed. The syntax is:
button <name> [ <caption> ] [ images:<image_spec_array> ] \ [ toolTip:<string> ]

The default alignment of button items is #center. Example:

button clone Create Clones on clone pressed do ...

Parameters:
images:

An image-specification array for providing bitmap images for the button. If this is specified, the <label> is ignored and the contents of the button are replaced with the bitmaps. The form is:
images:#(<image>, <maskImage>, <count_integer>, \ <enabled_out_image_index>, <enabled_in_image_index>, \ <disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. <count_integer> specifies the number of sub-images in the bitmaps, and the image_index values specify which sub-image in the bitmaps is to be used for each of the four button states. For example:
bm1 = render camera:$cam01 outputSize:[80,60]. ... button foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use the rendered image as the button image, and

button decay images:#(dcybtns.bmp, dcymask.bmp, 6, 1, 4, 1, 4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out and in states of the button, respectively. See also the Image Buttons (p. 1513) topic.
toolTip:

Provides text for a tooltip for the button; no tooltip if unsupplied.

Checkbox

1489

Properties:
<button>.images Array

Sets the image-specification array for the button. For example:

-- re-render, update button bm1 = render() foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

This property is write-only. Events:

on <button> pressed do <expr>

Called when the user clicks the button.

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Checkbox
A checkbox item is used to place a check box on the rollout. The user can click to successively switch between states. The syntax is:
checkbox <name> [ <caption> ] [ checked:<boolean> ]

The default alignment of checkbox items is #left. Example:

checkbox frab_enable Enable frabing on frab_enable changed state do ... ... if frab_enable.checked then frabulate master_obj ...

Parameters:
checked:

Initial state of the check box, defaults to false (unchecked). Properties:

<checkbox>.checked <checkbox>.state Boolean Boolean

The state of the check box, on (true) or off (false). Synonym for .checked

1490

Chapter 12

Creating MAXScript Tools

Events:
on <checkbox> changed <arg> do <expr>

Called when the user clicks the check box to check or uncheck it. The <arg> argument contains the new state of the check box, on (true) or off (false).

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Checkbutton
A checkbutton item is used to place a press button on the rollout that has two states, on and off, just like a check box. The user can click to successively switch between states. The syntax is:
checkbutton <name> [ <caption> ] [ [ [ [ highlightColor:<color> ] toolTip:<string> ] checked:<boolean> ] images:<image_spec_array> \ \ \ ]

The default alignment of checkbutton items is #center. Example:

checkbutton setup Setup checked:true tooltip:Opens setup panels on setup changed state do if state == on then openRollout setup_pan else closeRollout setup_pan

Parameters:
checked:

Initial state of the check button, defaults to off.

highlightColor:

The background color of the check button in its pressed (or on) state, defaults to a lightgray wash in keeping with 3ds max user-interface conventions.
toolTip:

Provides text for a tooltip for the check button; no tooltip if unsupplied.

Checkbutton

1491

images:

An image-specification array for providing bitmap images for the check button. If this is specified, the <label> is ignored and the contents of the check button are replaced with the bitmaps. The form is:
images:#(<image>, <maskImage>, <count_integer>, \ <enabled_out_image_index>, <enabled_in_image_index>, \ <disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. <count_integer> specifies the number of sub-images in the bitmaps, and the image_index values specify which sub-image in the bitmaps is to be used for each of the four check button states. For example:
bm1 = render camera:$cam01 outputSize:[80,60] ... checkbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the check button image, and

checkbutton decay images:#(dcybtns.bmp, dcymask.bmp, 6, 1, 4, 1, 4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out and in states of the check button, respectively. See also the Image Buttons (p. 1513) topic. Properties:
<checkbutton>.checked <checkbutton>.state Boolean Boolean Array

The state of the check button, on (true) or off (false). Synonym for .checked
<checkbutton>.images

Sets the image-specification array for the check button. For example:
-- re-render, update button bm1 = render() foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

This property is write-only. Events:

on <checkbutton> changed <arg> do <expr>

Called when the user clicks the check button to change its state; the <arg> argument contains the new state of the check button, on (true) or off (false).

1492

Chapter 12

Creating MAXScript Tools

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Colorpicker
A colorpicker item is used to place a 3ds max color selection swatch on the rollout. The user can click the swatch to display a Color Selector dialog or drag colors to or from it. The syntax is:
colorpicker <name> [ <caption> ] [ color:<color> ] \ [ fieldWidth:<number> ] [ height:<number> ] \ [ title:<string> ]

The default alignment of colorpicker items is #left. Exampl:e

colorpicker foo Wire color: color:[0,0,255] on foo changed new_col do selection.wirecolor = new_col

Parameters:
color:

Initial color of the swatch. Defaults to blue.

title:

The title displayed on the Color Selector dialog. Defaults to Choose a color.
fieldWidth:

The width in pixels of the swatch. Defaults to 40.

height:

The height in pixels of the swatch. Defaults to 16. Properties:

<colorpicker>.color Color

The current swatch color. Events:

on <colorpicker> changed <arg> do <expr>

Called when the user selects a new color in the open Color Selector dialog for this swatch or drops a new color on it. The <arg> argument contains the new color.

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Combobox

1493

Combobox
A combobox item is used to place a combo box list in the rollout. This is a variant of the drop-down list in which the list is always fully displayed in the rollout with an additional edit-text box at the top of the list where the current selection is placed and may be edited. The user can scroll the list or click to select an item in the list. The syntax is:
combobox <name> [ <caption> ] [ items:<array_of_strings> ] [ selection:<number> ] [ height:<number> ] \

The default alignment of combobox items is #left. Example:

combobox scale_cb Scale items:#(1 / 2, 1 / 4, 1/8, 1/16) on scale_cb selected i do format You selected %\n! scale_cb.items[i] scale_cb.selected = new item text

Parameters:
text:

The text string in the edit box.

items:

The array of text strings that are the items in the list
selection:

The 1-based number of the currently selected item in the list. Defaults to 1.
height:

The overall height of the combobox in number of item lines. Defaults to 10 lines. To have a combobox display exactly N items in the list, set height to N+2. Properties:
<combobox>.caption <combobox>.text String String Array Integer

The text of the optional caption above the combo box. The text in the edit box.
<combobox>.items

The item string array.

<combobox>.selection

The currently selected item number, 1-based. If the items list is an empty array, this value is 0.
<combobox>.selected String

The text of the currently selected item. Can be used to replace individual items without resetting the entire items array. If the items list is an empty array, this value is undefined.

1494

Chapter 12

Creating MAXScript Tools

Events:
on <combobox> selected <arg> do <expr>

Called when the user selects an item in the combo box list. The <arg> argument contains the new current selection item number.
on <combobox> doubleClicked <arg> do <expr>

Called when the user double-clicks an item in the list. Note that the on selected handler is always called on single clicks and on the first click of a double-click. The <arg> argument contains the number of the item double-clicked. For example
combobox foo items:#(...) on foo doubleClicked sel do ... on <combobox> entered <arg> do <expr>

Called when the user changes the text in the edit box then changes the focus away from the edit box. This handler is not called if the user presses ENTER. The <arg> argument contains the new text in the edit box.
on <combobox> changed <arg> do <expr>

Called for each individual character change the user performs in the edit box. This handler is not called when the user presses ENTER or changes the focus away from the edit box. The <arg> argument contains the new text in the edit box.

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Dropdownlist
A dropdownlist item is used to place a drop-down list in the rollout. The user can click open the list and scroll or click again to select an item in the list. The syntax is:
dropdownlist <name> [ <caption> ] [ items:<array_of_strings> ] \ [ selection:<number> ] [ height:<number> ]

The default alignment of dropdownList items is #left. Example:

dropdownlist scale_dd Scale items:#(1 / 2, 1 / 4, 1/8, 1/16) on scale_dd selected i do format You selected %\n! scale_dd.items[i]

Dropdownlist

1495

Parameters:
items:

The array of text strings that are the items in the list.
selection:

The 1-based number of the currently selected item in the list. Defaults to 1.
height:

The overall height of the dropdownlist in number of item lines. Defaults to 10 lines. To have a dropdownlist exactly display N items in the list, set height to N+2. Properties:
<dropdownlist>.items Array Integer

The item string array.

<dropdownlist>.selection

The currently selected item number, 1-based. If the items list is an empty array, this value is 0.
<dropdownlist>.selected String

The text of the currently selected item. Can be set to replace individual items without resetting the entire items array. If the items list is an empty array, this value is undefined. Events:
on <dropdownlist> selected <arg> do <expr>

Called when the user selects an item in the drop-down list. The <arg> argument contains the new current selection item number. Example:
rollout test t ( dropdownlist dd dd items:#(1,2,3,4,5,6,7,8,9,10) height:6 label l L ) rof=newrolloutfloater A 200 200 addrollout test rof

you will get 5 items in the dropdown list. Change height to 5, and you get 3.

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

1496

Chapter 12

Creating MAXScript Tools

Edittext
An edittext item is used to place an editable text field where the user can type and edit text. The syntax is:
edittext <name> [ <caption> ] [ text:<string> ] \ [ fieldWidth:<integer> ] [bold:<boolean> ]

The default alignment of edittext items is #left. Example:

edittext prefix_txt Name prefix: fieldWidth:70 on prefix_txt entered text do ... ... new_obj = copy master pos:[x,y,z] prefix:prefix_txt.text ...

Parameters:
text:

The text string in the edit box.

fieldWidth:

The width in pixels of the edit box. By default, the width is set to be from just after the caption text to the right margin of the rollout.
bold:

If set to true, the text string in the edit box is displayed in bold format, if set to false, in normal, non-bold format. The default value is false. Properties:
<edittext>.text String String Boolean

The text in the edit box.

<edittext>.caption <edittext>.bold

The text of the optional caption next to the edit box. If true, the text is displayed in bold format, if false, in normal, non-bold format. Events:
on <edittext> changed <arg> do <expr>

Called each time the user changes the text in the edit box; the <arg> argument contains the new text in the edit box.
on <edittext> entered <arg> do <expr>

Called when the user enters text in the edit box and then presses ENTER or TAB to move the cursor out of the field. The <arg> argument contains the new text in the edit box. If you enter a string in the edit box and then press ENTER, the on changed handler is called once per character and once for the ENTER. The on entered handler is just called once, for the ENTER.

Label

1497

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Label
A label item is used to place static text on the rollout, perhaps a label for another item or a text message. The syntax is:
label <name> [ <string> ]

The default alignment of label items is #center. Example:

label lab1 Please choose an object:

Properties: No additional properties for label. Events: -- none --

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Listbox
A listbox item is used to place a list box in the rollout. This is another variant of the drop-down list in which the list is always fully displayed in the rollout. Unlike combobox, it has no edit-text field at the top and it is just a simple scrollable list. The user can scroll the list or click to select an item. The syntax is:
listbox <name> [ <caption> ] [ items:<array_of_strings> ] \ [ selection:<number> ] [ height:<number> ]

The default alignment of listbox items is #left. Example:

listbox selns items:obj_name_array on selns selected i do copy obj_array[i] pos:[rand_x, rand_y, rand_z] selns.selection = 2

1498

Chapter 12

Creating MAXScript Tools

Parameters:
items:

The array of text strings that are the items in the list.
selection:

The 1-based number of the currently selected item in the list. The default selection value is 1.
height:

The overall height of the listbox in number of item lines. Defaults to 10 lines. To have a listBox display exactly N items, set height to N. Properties:
<listbox>.items String Integer

The item string array.

<listbox>.selection

The currently selected item number, 1-based. If the items list is an empty array, this value is 0.
<listbox>.selected String

The text of the currently selected item. Can be used to replace individual items with resetting the entire items array. If the items list is an empty array, this value is undefined. Events:
on <listbox> selected <arg> do <expr>

Called when the user selects an item in the list. The <arg> argument contains the new current selection item number.
on <listbox> doubleClicked <arg> do <expr>

Called when the user double-clicks on an item in the list. Note that the on selected handler is always called on single clicks and on the first click of a double-click. The <arg> argument contains the number of the item double-clicked. For example,
listbox foo items:#(...) on foo doubleClicked sel do ...

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Mapbutton

1499

Mapbutton
A mapbutton item is used to place a button in the rollout that will display the 3ds max Material/ Map Browser dialog when clicked. Only texture maps will be displayed in the Material/Map Browser dialog. The syntax is:
mapbutton <name> [ <caption> ] [ map:<texturemap> ] \ [ images:<image_spec_array> ] [ toolTip:<string> ]

The default alignment of mapbutton items is #center. Example:

label mapbutton sbm_lbl Background Map: choosemap <<none>> tooltip:Select Background Map

on choosemap picked texmap do ( environmentmap = texmap choosemap.text=classof texmap as string )

Parameters:
map:

The initial textureMap value returned by the map property before the user has selected a texture map using the mapbutton. Defaults to undefined.
images:

An image-specification array for providing bitmap images for the mapbutton. If this is specified, the <label> is ignored and the contents of the mapbutton are replaced with the bitmaps. The form is:
images:#(<image>, <maskImage>, <count_integer>, \ <enabled_out_image_index>, <enabled_in_image_index>, \ <disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. <count_integer> specifies the number of sub-images in the bitmaps, and the image_index values specify which sub-image in the bitmaps is to be used for each of the four mapbutton states. For example:
bm1 = render camera:$cam01 outputSize:[80,60] ... mapbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the mapbutton image, and

mapbutton decay images:#(dcybtns.bmp, dcymask.bmp, 6, 1, 4, 1, 4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out and in states of the mapbutton, respectively. See also the Image Buttons (p. 1513) topic.

1500

Chapter 12

Creating MAXScript Tools

toolTip:

Provides text for a tooltip for the mapbutton. No tooltip if unsupplied. Properties:
<mapbutton>.map TextureMap

The current textureMap value for the mapbutton, or the textureMap value specified by the map parameter if the user has not yet selected a texture map.
<mapbutton>.images Array

Sets the image-specification array for the mapbutton. For example:

-- re-render, update button bm1 = render() foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

This property is write-only. Events:

on <mapbutton> picked <arg> do <expr>

Called when the user selects a texture map from the Material/Map Browser dialog while in the mapbutton pick command mode. The <arg> argument contains the selected textureMap value. The handler is not called if the user cancels out of the Material/Map Browser dialog. Notes: When a mapButton or materialButton is used in a rollout in a scripted material or textureMap plug-in, and so turn up the Material Editor, it behaves with the same functionality as sub-map and sub-material buttons do in other materials and maps. This includes supporting drag-and-drop with instance/copy, and opening sub-maps/materials if they have been assigned.

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Materialbutton
A materialbutton item is used to place a button in the rollout that will display the 3ds max Material/ Map Browser dialog when clicked. Only materials will be displayed in the Material/Map Browser dialog. The syntax is:
materialbutton <name> [ <caption> ] [ material:<material> ] \ [ images:<image_spec_array> ] \ [ toolTip:<string> ]

The default alignment of materialbutton items is #center.

Materialbutton

1501

Example:
label materialbutton smtl_lbl Set selected objects material to: choosemtl Pick Material

on choosemtl picked mtl do ( print mtl if $ != undefined do $.material=mtl )

Parameters:
material:

The initial material value returned by the material property before the user has selected a material using the materialbutton. Defaults to undefined.
images:

An image-specification array for providing bitmap images for the materialbutton. If this is specified, the <label> is ignored and the contents of the materialbutton are replaced with the bitmaps. The form is:
images:#(<image>, <maskImage>, <count_integer>, \ <enabled_out_image_index>, <enabled_in_image_index>, \ <disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file name string or a MAXScript bitmap value. <count_integer> specifies the number of sub-images in the bitmaps, and the image_index values specify which sub-image in the bitmaps is to be used for each of the four materialbutton states. For example:
bm1 = render camera:$cam01 outputSize:[80,60] ... materialbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the materialbutton image, and

materialbutton decay images:#(dcybtns.bmp, dcymask.bmp, 6, 1, 4, 1,4)

would use sub-images 1 and 4 of bitmaps dcybtns.bmp and dcymask.bmp for the out and in states of the materialbutton, respectively. See also the Image Buttons (p. 1513) topic.
toolTip:

Provides text for a tooltip for the materialbutton. No tooltip if unsupplied.

1502

Chapter 12

Creating MAXScript Tools

Properties:
<materialbutton>.material Material

The current material value for the materialbutton, or the material value specified by the material parameter if the user has not yet selected a material.
<materialbutton>.images Array

Sets the image-specification array for the materialbutton. For example:

-- re-render, update button bm1 = render() foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

This property is write-only. Events:

on <materialbutton> picked <arg> do <expr>

Called when the user selects a material from the Material/Map Browser dialog while in the materialbutton pick command mode. The <arg> argument contains the selected material value. The handler is not called if the user cancels out of the Material/Map Browser dialog. Notes: When a mapButton or materialButton is used in a rollout in a scripted material or textureMap plug-in, and so turn up the Material Editor, it behaves with the same functionality as sub-map and sub-material buttons do in other materials and maps. This includes supporting drag-and-drop with instance/copy, and opening sub-maps/materials if they have been assigned.

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

MultiListBox
A MultiListBox item is used to place a list box in the rollout. This is a variant of the ListBox in which multiple items in the list can be selected. The syntax is:
MultiListBox <name> [ <caption> ] [ items:<array_of_strings> ] \ [ selection:{<bitarray> | <number_array> | <number>} ] \ [ height:<number> ]

The default alignment of MultiListBox items is #left.

MultiListBox

1503

Example:
rollout test test (MultiListBox mlb MultiListBox items:#(A,B,C) selection:#(1,3) on mlb selected val do format selected: % - %\n val mlb.selection[val] on mlb doubleclicked val do format doubleclicked: % - %\n val mlb.selection[val] on mlb selectionEnd do format selectionEnd: %\n mlb.selection ) rof=newrolloutfloater tester 200 300 addrollout test rof test.mlb.items test.mlb.selection=1 test.mlb.selection=#(1,3) test.mlb.selection=#{}

Parameters:
items:

The array of text strings that are the items in the list.
selection:

A BitArray signifying the currently selected items in the list. The default selection value is #{}.
height:

The overall height of the MultiListBox in number of item lines. Defaults to 10 lines. To have a MultiListBox display exactly N items, set height to N. Properties:
<listbox>.items Array of Strings BitArray

The item string array.

<listbox>.selection

The currently selected items. When setting the selection via a script, the selection can be specified as a BitArray, Array of numbers, or a number. If the items list is an empty array, this value is 0. Events:
on <listbox> selected <arg> do <expr>

Called when the user selects or deselects an item in the list. The <arg> argument contains the index of the item that was selected or deselected. Since multiple items can be selected or deselected at once, this handler is called for each item in the list, starting from the top of the list, whose selection has changed.
on <listbox> doubleClicked <arg> do <expr>

Called when the user double-clicks on an item in the list. Note that the on selected handler is always called on single clicks and on the first click of a double-click. The <arg> argument contains the number of the item double-clicked.
on <listbox> selectionEnd do <expr>

Called when the user selects or deselects an item in the list, but after all the calls to the on selected handler have been made.

1504

Chapter 12

Creating MAXScript Tools

Notes: There isnt a way to deselect all the items in the list by clicking in the list somewhere. To clear the list selection you will need a Clear Selection button that sets selection=#{}.

Pickbutton
A pickbutton item is used to place a scene object-picker button on the rollout. It operates like a normal pick button in the 3ds max user interface, turning light-green when pressed and causing an object-pick mode to be entered. The user can then choose a scene object by clicking on it. The pick mode exits and the button returns to its unpressed state. The user can right-click to cancel the pick mode. The syntax is:
pickbutton <name> [ <caption> ] [ message:<string> ] \ [ filter:<function> ] [ toolTip:<string> ]

The default alignment of pickbutton items is #center. Example:

fn foo_filt obj = findString obj.name foo == 1 pickbutton chooseit Select master object filter:foo_filt on chooseit picked obj do ( master = obj chooseit.text = obj.name )

Parameters:
message:

The optional text to be displayed in the 3ds max status line while in the pick mode. Default is no message.
filter:

The optional filter function that will be called to test the eligibility of the scene object under the cursor for picking. It must be a function of one argument, which will be the object under test, and return true if the object is eligible or false if not. For example, the following filter function allows only objects whose names begin with foo to be pickable:
fn foo_filt obj = findString obj.name foo == 1

Default is no filtering.
toolTip:

Provides text for a tooltip for the button. No tooltip if unsupplied. Properties:
<pickbutton>.object Node

The last object picked using the pickbutton, undefined if no object has been picked. This property is read-only.

ProgressBar

1505

Events:
on <pickbutton> picked <arg> do <expr>

Called when the user selects an object in the scene while in the pickbutton pick mode. The <arg> argument contains the selected object. The handler is not called if the user cancels out of the pick mode.

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

ProgressBar
A progressBar item is used to place a progress bar on the rollout. The syntax is:
progressBar <name> [ value:<number> ] [ color:<color> ] \ [ orient:<name> ]

The default alignment of progressBar items is #left. Example:

button doit Process Scene progressbar doit_prog color:red on doit pressed do ( for i = 1 to objArray.count do ( doit_prog.value = 100.*i/objArray.count ... ) doit_prog.value = 0 )

Parameters:
value:

The initial progress percentage value (0 100). The default value is 0. This is an Integer value.
color:

The color of the progress bar. The default color value is [30,10,190].
orient:

Specifies whether the progress bar should fill from left to right (orient:#horizontal) or bottom to top (orient:#vertical). Default value is #horizontal.

1506

Chapter 12

Creating MAXScript Tools

Properties:
<progressbar>.value <progressbar>.color Integer Color Name

The progress bar complete percentage (0 100). The color of the progress bar.
<progressbar>.orient

The orientation of the progress bar fill: #horizontal - left to right; #vertical - bottom to top. Events:
on <progressbar> clicked <arg> do <expr>

Called when user clicks on the progress bar. The <arg> argument contains the percentage value at the clicked point.

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Radiobuttons
A radiobuttons item is used to place a set of radio buttons on the rollout, only one of which can be checked at a time. The user can click different buttons in the set to change states. The syntax is:
radiobuttons <name> [ <caption> ] labels:<array_of_strings> \ [ default:<number> ] [ columns:<number> ]

The default alignment of radiobuttons items is #center. Example:

radiobuttons copy_type labels:#(copy, instance, reference) radiobuttons which_obj labels:obj_name_array -- computed label array on copy_type changed state do ... ... copyfn = case copy_type.state of ( 1: copy 2: instance 3: reference ) ...

Slider

1507

Parameters:
labels:

An array of strings that specifies the number of radio buttons and the text label for each one.
default:

The number of the radio button initially selected. Default is 1.

columns:

Number of columns across in which to arrange the buttons. By default, MAXScript will attempt to lay out all the radio buttons side-by-side on one line, and if they wont fit, vertically in a single column. You can force the layout system to array the buttons in multiple columns using this parameter. Each column is given the same width, which is the width of the widest label in all columns and it left-adjusts the radio buttons in these columns. Properties:
<radiobuttons>.state Integer

The 1-based number of the currently selected radio button in the order specified in the labels: array. Events:
on <radiobuttons> changed <arg> do <expr>

Called when the user clicks one of the radio buttons in the set. The <arg> argument contains the new state of the radio buttons array, which is the 1-based number of the newly selected button.

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Slider
A slider item is used to place a slider on the rollout, as an alternative to a spinner. The user can drag the sliders pointer around to set its value. The syntax is:
slider <name> [ <caption> ] [ range:[min,max,val] ] \ [ type:#float ] [ ticks:10 ] \ [ orient:#horizontal ]

The default alignment of slider items is #center.

1508

Chapter 12

Creating MAXScript Tools

Example:
slider tilt Head tilt orient:#vertical ticks:0 range:[-30,30,0] on tilt changed val do $head.bend.angle = val

Parameters:
range:

A Point3 value containing the minimum, maximum and initial values for the slider in the x, y, and z components, respectively. Defaults to [0,100,0].
type:

The type of the slider, #float or #integer. Defaults to #float.

orient:

The layout orientation of the slider in the rollout, either #vertical or #horizontal. Defaults to #horizontal.
ticks:

Specifies how many ticks to place along the slider bar. No ticks are drawn if you specify ticks:0. Defaults to 10. Properties:
<slider>.range <slider>.value <slider>.ticks Point3 Float Integer

The current range and value for the slider, as a Point3 like the range: parameter. The current value of the slider. The number of ticks along the slider. Events:
on <slider> changed <arg> do <expr>

Called when the user moves the slider pointer. The <arg> argument contains the new value of the slider.
on <slider> buttondown do <expr>

Called when the user first clicks the slider.

on <slider> buttonup do <expr>

Called when the user releases the slider. The buttonDown and buttonUp events effectively notify you of the start and end of a slider twiddle, allowing you to perform some setup for the adjustment. A typical use for this is to bring scene nodes that are being modified in the on <slider> changed handler into the foreground plane to speed up screen redraw. For example:
spinner foo height: on foo buttonDown do flagForeground $baz...* true on foo buttonUp do flagForeground $baz...* false

Spinner

1509

Notes: If you are using a slider to interactive adjust a property of an on-screen object, you can improve the interactive speed by moving the object to the foreground plane. Objects placed in the foreground plane are redrawn individually and so interactive changes to them are much faster. An object is moved to the foreground or background plane using the flagForeground() method:
flagForeground <node> <boolean> -- mapped

The boolean argument puts the scene node(s) into the foreground plane if true, or into the background plane if false. You should be judicious in putting objects in the foreground plane, because putting too many objects in the foreground plane reduces the foreground planes effectiveness. Remember to return objects to the background plane when you dont need to interactively control them any more.

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Spinner
A spinner item is used to place a 3ds max value spinner on the rollout. The user can drag the spinner arrows or type values into the spinner edit field. The syntax is:
spinner <name> [ <caption> ] [ range:[min,max,val] ] \ [ type:<name> ] [ scale:<float> ] \ [ fieldWidth:<integer> ] [ controller:<controller> ]

The default alignment of spinner items is #right. Example:

spinner frab_amt Frab %: range:[0,100,10] type:#integer spinner ball_radius Ball radius controller:$ball.radius.controller on frab_amt changed val do frabulate selection val

Parameters:
range:

A Point3 value containing the minimum, maximum, and initial values for the spinner in the x, y, and z components, respectively. Defaults to [0,100,0].
type:

The type of the spinner: #float, #integer, or #worldunits. Defaults to #float. If type is #worldunits, the value is displayed in the current 3ds max display units, but the value is always in internal system units.

1510

Chapter 12

Creating MAXScript Tools

scale:

The scale of the spinner specifies the smallest value increment. Defaults to 0.1 for floats, 1 for integers.
fieldwidth:

The width in pixels of the spinner text-edit field. By default, the spinner is placed so the left edge of the edit field is exactly in the center of the rollout and right edge is placed at the right margin. You can control how wide the field is using this parameter.
controller:

Links the spinner to the specified controller. This lets you establish a direct link between the spinner and the controller. Changes to the spinner will automatically update the controller (and its controlled objects). Changes to the controller automatically update the spinner. For example, say you have a sphere called $ball with a float controller already assigned to its radius, then the following code:
utility foo foo ( spinner ball_radius Ball radius range:[0,1000,1] \ controller:$ball.radius.controller )

sets up a spinner that automatically affects and tracks the radius of the scene node $ball. Any changes to the spinner update $balls radius. Any other changes to $balls radius, say in the Modify panel or because of animation, will update the spinner. Note that this links to controllers, so the specified controller must already exist before creating the spinner user-interface item. You can either specify a controller already assigned to the parameter you want to link to, or you can create the controller in your script and then assign that controller to the parameter of interest. For example:
utility foo foo ( local myController=bezier_float() spinner ball_radius Ball radius range:[0,1000,1] \ controller:myController button apply Apply Radius Controller on apply pressed do ( animate off at time 0 $ball.radius=myController.value $ball.radius.controller=myController ) )

Properties:
<spinner>.range <spinner>.value Point3 Float

The current range and value for the spinner, as a Point3 like the range: parameter. The current value of the spinner.

Spinner

1511

Events:
on <spinner> changed <arg> do <expr>

Called when the user spins the spinner, or when the user enters a value in the spinner field then presses ENTER or presses TAB to move the cursor out of the field. The <arg> argument contains the new value of the spinner.
on <spinner> entered do <expr>

Called when the user types a number into a spinners edit field and then presses ENTER or presses TAB to move the cursor out of the field. The on <spinner> changed handler, if supplied, has already been called at this point and the spinners value property is up to date.
on <spinner> buttondown do <expr>

Called when the user first clicks the spinner.

on <spinner> buttonup do <expr>

Called when the user releases the spinner. The buttonDown and buttonUp events effectively notify you of the start and end of a spinner twiddle, allowing you to perform some setup for the adjustment. A typical use for this is to bring scene nodes that are being modified in the on <spinner> changed handler into the foreground plane to speed up screen redraw. For example:
spinner foo height: on foo buttonDown do flagForeground $baz...* true on foo buttonUp do flagForeground $baz...* false

Notes: If you are using a spinner to interactive adjust a property of an on-screen object, you can improve the interactive speed by moving the object to the foreground plane. Objects placed in the foreground plane are redrawn individually and so interactive changes to them are much faster. An object is moved to the foreground or background plane using the flagForeground() method:
flagForeground <node> <boolean> -- mapped

The boolean argument puts the scene node(s) into the foreground plane if true, or into the background plane if false. You should be judicious in putting objects in the foreground plane, because putting too many objects in the foreground plane reduces the foreground planes effectiveness. Remember to return objects to the background plane when you dont need to interactively control them any more.

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

1512

Chapter 12

Creating MAXScript Tools

Timer
A timer item generates tick events at set intervals. Timer is unlike the remainder of the user-interface items as it is not a visible control. Timer lets the user interface react, animate, or change without user interaction, such as having animations playing on the rollout, checking for certain conditions or events before continuing, displaying nag/splash screens, and so on. The syntax is:
timer <name> [ interval:<number> ] [ active:<boolean> ]

Example:
utility test test1 ( timer clock testClock interval:400 label test 1 on clock tick do ( valUp = (test.text as integer)+1 test.text = valUp as string ) )

Parameters:
interval:

An integer value specifying the time in milliseconds between tick events. Default value 1000 (1 second).
active:

Specifies whether the timer emits tick events. Default value true. Properties:
<timer>.interval <timer>.active Integer Boolean

Integer value specifying the time in milliseconds between tick events. Specifies whether the timer emits tick events (true) or not (false). When first set to true, the first tick event is generated in interval milliseconds. Events:
on <timer> tick do <expr>

Called when timer ticks.

See also
Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)

Timer

1513

Image Buttons
Four rollout user-interface item types, button, checkbutton, mapbutton, and materialbutton, can be either simple text buttons containing text labels or image buttons inside of which bitmaps can be displayed instead of text. The images to be displayed in these buttons are specified using the definition-line parameter images:. The parameter form is:
images:#(<image>, <maskImage>, <count_integer>, \ <enabled_out_image_index>, <enabled_in_image_index>, \ <disabled_out_image_index>, <disabled_in_image_index>)

where <image> and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. <count_integer> specifies the number of sub-images in the bitmaps, and the image_index values specify which sub-image in the bitmaps is to be used for each of the four button states. For example:
bm1 = render camera:$cam01 outputSize:[80,60] ... checkbutton foo images:#(bm1, undefined, 1, 1, 1, 1, 1)

would use a rendering as the button image. If the image or maskImage is specified as a file name, the bitmap file is searched for in the following directories (in order of search): current MAXScript directory, MAXScript startup directory, MAXScript directory, 3ds max bitmap directories, and then the 3ds max image directory. There are four images that can be specified, one for each of the possible button states, enabled-out, enabled-in, disabled-out, and disabled-in. These images are taken from a single bitmap file or MAXScript bitmap value in which a number of images are stored side-by-side. This bitmap, containing one or more images to use for the button, is called the imagelist. All the sub-images in such an imagelist are taken to be the same width and you specify which image is used for which state by providing an image-index into the bitmap. This means you can store the images for all the states of many buttons in one file, specifying different indexes for the different buttons. You can also specify a black-and-white mask image used to mask the image display into the buttons. It is given in the same imagelist form and the mask image indexes must be the same as the images they correspond to. Black pixels in the mask let the corresponding image pixel show; white pixels hide corresponding image pixels and show the default background color for the button. If there is no mask file, supply the value undefined for the mask file name. Bitmap files without full path names are searched for in the Startup scripts directory, then the scripts directory, then the 3ds max images directory, then the 3ds max executables directory, and then the directories in the PATHS environment variable. You can change the images in a button by setting the .images property of these user-interface items. For example:
-- re-render, update button bm1 = render camera:$cam01 outputSize:[80,60] foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)

1514

Chapter 12

Creating MAXScript Tools

Example:
checkbutton decay images:#(dcybtns.bmp, dcymask.bmp, 6, 1, 4, 1, 4)

In this example, the images are in a file dcybtns.bmp and the masks in dcymask.bmp. These bitmap files each have six images across and the out-state is image 1 and the in-state is image 4. Both enabled and disabled here are given as the same image, presumably because this particular button will never be disabled.

Scripted Right-Click Menus

MAXScript provides a set of classes and functions and some special syntax to allow you to construct custom right-click menus that can be incorporated into the existing 3ds max user interface. You typically use right-click menus to provide quick access to a selection of tools you have written in MAXScript. These tools would typically have no user interface, however you can create dialogs or rollout floater windows in a right-click menu to display a user interface. A scripted right-click menu is created using the RCMenu definition construct in MAXScript, and then you register the right-click menu with 3ds max. The top-level definition syntax is as follows:
rcmenu <var_name> ( <rcmenu_body> )

where: <var_name> is the name of an automatically created global variable to hold the rcmenu value that represents the right-click menu. <rcmenu_body> is enclosed in the required parentheses and is a sequence of clauses that define the menu items that will appear in the utility, along with functions and event handlers that process user interactions. These clauses are defined in detail in the RCMenu Clauses (p. 1515) topic. The following methods let you register and unregister scripted right-click menus:
registerRightClickMenu <rcmenu>

registers the specified right-click menu

unRegisterRightClickMenu <rcmenu>

unregisters the specified right-click menu

unRegisterAllRightClickMenus()

unregisters all right-click menus Example: The following script adds two items to the right-click menu: Cast Shadows and Receive Shadows. These items will be enabled only if one object is selected. If enabled, the items will be checked or unchecked based on the current state of the selected object. Choosing a menu item will flip the state of the corresponding object property.

RCMenu Clauses

1515

Script:
rcmenu MyRCmenu ( menuItem mi_cs Cast Shadows checked:false menuItem mi_rs Receive Shadows checked:false -on MyRCmenu open do ( local sel = (selection.count == 1) --- Enable if only one object is selected mi_cs.enabled = mi_rs.enabled = sel --- Set check state of items if sel do ( mi_cs.checked = $.castShadows mi_rs.checked = $.receiveShadows ) ) --- set up event handlers for items on mi_cs picked do $.castShadows = (not $.castShadows) on mi_rs picked do $.receiveShadows = (not $.receiveShadows) ) -- register the rcmenu registerRightClickMenu MyRCmenu

You can register as many scripted right-click menus as you like. Each scripted right-click menu registered is appended to the right-click menu window. If a scripted right-click menu with the same name is registered twice, the old one is over written by the new one. If a runtime error occurs while executing a scripted right-click menu, an error message is displayed in Listener. The right-click menu will not be disabled.

RCMenu Clauses
The <rcmenu_body> of a right-click menu definition is made up of a sequence of scripted right-click menu clauses as follows:
<rcmenu_body> ::= { <rcmenu_clause> }+

Scripted right-click menu clauses define the components of a scripted right-click menu and can be one of three basic things: Local variables, functions or structure definitions are variables, functions, and structures whose scope is the scripted right-click menu. These locals will exist as long as the scripted right-click menu value exists. The scripted right-click menu value will exist until the scripted right-click menu value is redefined or deleted. Local variables are particularly useful for storing working data associated with the right-click menu such as picked objects. User-interface items are displayed in the right-click menu, such as menu items, separators, and submenus.

1516

Chapter 12

Creating MAXScript Tools

Event handlers are special kinds of functions that are associated with particular user-interface items. Event handlers specify the processing you want to occur when a user interacts with an user-interface item, for example pressing a menu item or opening a submenu. These user actions generate named events and the optional event handler you supply for that event is called when the user action occurs.

The visibility of locals, and accessing scripted right-click menu locals from external code, are the same as described for utility rollouts, and described in the Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code (p. 1478) and Accessing Locals and Other Items in a Rollout from External Code (p. 1480) topics. In both utility rollouts and scripted right-click menus, the name given to a user-interface item is used to name an automatically constructed local variable that will hold the value representing the item. It is also used to associate event handler functions with the item. One difference between the scoping of these variables is that they are local to the rollout in utility rollouts, and local to the scripted right-click menu in scripted right-click menus. This means that all user-interface items in a scripted right-click menu must have a unique name within the scripted right-click menu, even for those items present in a subMenu. Formally, the syntax of a <rcmenu_clause> is defined as follows:
<rcmenu_clause> ::= <local_variable_decl> <local_function_decl> <local_struct_decl> <user_interface_item> <event_handler> | | | |

Locals: A <local_variable_decl>, <local_function_decl>, and <local_struct_decl> are exactly the same as local variable, function, and structure definitions in MAXScript:
<local_variable_decl> ::= local <decl> { , <decl> } <decl> ::= <name> [ = <expr> ] -- optional initial value <local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr> <local_struct_decl> <member> ::= struct <name> ( <member> { , <member> } ) ::= ( <name> [ = <expr> ] | <local_function_decl> )

Examples of the above (in order) are:

local numSelected local numSelected = 0 fn onlyOneSelected = selection.count == 1 struct parents (mother=, father=)

Global variables cannot be declared as a scripted right-click menu clause, however they can be declared within event-handler scripts. If you need to ensure that a variable name references a global variable, declare the variable name as global immediately before defining the right-click menu in your script.

RCMenu Clauses

1517

When writing scripts, it is good programming practice to explicitly declare your local and global variables. Implicit declaration is provided as a short-hand, typically used when working in the Listener interactively or developing short scripts. When developing extended scripts, explicitly declaring variables can reduce errors and improve readability of the code. It is also recommend that you declare as local all variables unless you really want them to be global variables. The reasons for this are described in the Scope of Variables (p. 646) topic. User-Interface Items: A <user_interface_item> defines an individual menu item, separator, or submenu user-interface item that will appear in the right-click menu. These user-interface items are described in the RCMenu User-Interface Items (p. 1518) topic. Event Handlers: An <event_handler> is a special function definition local to a scripted right-click menu that you provide to handle the processing you want to occur when a user clicks on a menu item. This user action generates a named event and any event handler you supply for that event is called when the action occurs. The syntax for defining a handler is as follows:
on <item_name> <event_name> do <expr>

The <item_name> specifies the name of the item for which this handler is connected. The <event_name> specifies the type of event to be handled. There is only one type of user-interface item event:
picked

The picked handler expression is executed when a menu item is picked from the right-click menu. Any MAXScript action like creating a object, adding a modifier, and so on can be performed in this expression. In addition to the event handlers you specify for particular menu items in a right-click menu, you can define a handler function that is called when the entire right-click menu is first opened by the user. This event handler is useful for initialization code. The syntax for this event handler is as follows:
on <rcmenu> open do <expr>

See also
Scripted Right-Click Menus (p. 1514)

1518

Chapter 12

Creating MAXScript Tools

RCMenu User-Interface Items

There are three types of user-interface items you can use to construct your scripted right-click menu. The user-interface control types are: menuItem (p. 1518) separator (p. 1519) subMenu (p. 1520)

menuItem
A menuItem is used to place a pickable item in the right-click menu. The syntax for a menuItem is:
menuItem <name> <label> [ checked:<boolean> ] [ enabled:<boolean> ] [ filter:<function> ]

Parameters:
name:

Used to refer to when writing an event handler.

label:

The string that appears in the right-click menu.

checked:

Specifies if a check mark appears before the label in the right-click menu. If true the item is checked, otherwise the item is unchecked.
enabled:

Specifies if the item is enabled for interaction when the right-click menu is opened. If true the item is enabled, otherwise the item is disabled and appears unavailable.
filter:

A function that returns a Boolean value. The filter function is evaluated when the right-click menu is first opened. If the filter function returns true the menuItem appears in the menu, otherwise it is not displayed. Properties:
<menuitem>.text <menuitem>.checked String Boolean

The string that appears in the right-click menu. Specifies if a check-mark appears before the label in the right-click menu. If true the item is checked, otherwise the item is unchecked.
<menuitem>.enabled Boolean

Specifies if the item is enabled for interaction when the right-click menu is opened. If true the item is enabled, otherwise the item is disabled and appears as unavailable. Events:
on <menuitem> picked do <expr>

Called when the user clicks the menu item.

separator

1519

Example: Script:
rcmenu RCmenuRenderable ( fn onlyOneSelected = selection.count == 1 -- define filter function menuItem mi_r Renderable filter: onlyOneSelected -- display if only 1 object selected on RCmenuRenderable open do -- perform following on rcmenu open ( if selection.count == 1 then -- if only one object selected... ( mi_r.text = $.name + | + Renderable -- change text of menu item if isKindOf $ Shape then -- if shape set renderable property to $.renderable=$.renderable -- itself to get shape and node renderable -- properties the same mi_r.checked=$.renderable -- turn on menu item check if renderable ) ) on mi_r picked do $.renderable = not $.renderable -- when menu item picked, flip renderable value ) -registerRightClickMenu RcmenuRenderable -- register the rcmenu

See also
RCMenu Clauses (p. 1515) Scripted Right-Click Menus (p. 1514)

separator
A separator is used to place a separator line in the right-click menu, and is normally used to group menu items. The syntax for a separator is:
separator <name> [ filter:<function> ]

Parameters:
name:

Used to name an automatically constructed local variable that will hold the value representing the separator.
filter:

A function that returns a Boolean value. The filter function is evaluated when the rightclick menu is first opened. If the filter function returns true the separator appears in the menu, otherwise it is not displayed. Example: Script:
rcmenu MyRCmenu ( fn flt_objects = ($ != undefined) -- objects filter -menuItem mi_cs Cast Shadows checked:false

1520

Chapter 12

Creating MAXScript Tools

menuItem --

mi_rs

Receive Shadows

checked:false

-- add only if one or more objects are selected separator sep1 filter:flt_objects menuItem mi_st Scale Twice filter:flt_objects menuItem mi_sh Scale Half filter:flt_objects --- event handlers would go here... ) registerRightClickMenu MyRcmenu -- register the rcmenu

See also
RCMenu Clauses (p. 1515) Scripted Right-Click Menus (p. 1514)

subMenu
A subMenu is used to place an item in the right-click menu that, if the cursor is placed on, opens a submenu containing additional user-interface items. The syntax for a subMenu is:
subMenu <label> [ filter:<function> ] ( <submenu_body> )

The <submenu_body> of a subMenu definition is made up of a sequence of RCMenu clauses as follows:

<submenu_body> ::= { <rcmenu_clause> }+

Parameters:
label:

The string that appears in the right-click menu.

filter:

A function that returns a Boolean value. The filter function is evaluated when the right-click menu is first opened. If the filter function returns true the subMenu appears in the menu, otherwise it is not displayed. Example: Script:
rcmenu MyRCmenu ( fn flt_objects = ($ != undefined) -- objects filter fn flt_shapes = (isKindOf $ Shape) -- shapes filter -menuItem mi_cs Cast Shadows checked:false menuItem mi_rs Receive Shadows checked:false -separator sep2 filter:flt_objects -subMenu Modifiers filter:flt_objects -- begin subMenu ( -- Add common objects

subMenu

1521

menuItem menuItem --

mi_bend Bend mi_twist Twist

-- Add shape only modifiers separator sep3 filter:flt_shapes subMenu Shape filter:flt_shapes -- begin nested subMenu ( menuItem mi_extrude Extrude menuItem mi_EditSpline Edit Spline ) ) -- event handlers would go here... ) registerRightClickMenu MyRcmenu -- register the rcmenu

See also
RCMenu Clauses (p. 1515) Scripted Right-Click Menus (p. 1514)

Defining Macro Scripts

Macro Scripts are scripts that are associated with toolbar buttons and are executed when the corresponding toolbar button is clicked. Macro Scripts have to be defined with the macroScript definition construct and can then be associated with a toolbar button by right-clicking a Shortcut toolbar or Tab and choosing Customize. The Customize User-Interface dialog is displayed, which has a radio button above the list box that lets you choose from either Command shortcuts or Macro Scripts. Macro Scripts are essentially pieces of MAXScript code that have a name and category, and optionally a tooltip and icon. Macro Scripts do not automatically create user-interface items. If you want a Macro Script to display a dialog, you will need to create a rollout floater window and rollout(s) as described in the Rollout Floater Windows (p. 1477) topic, and create and install the user-interface items in the rollout(s) as described in the Rollout User-Interface Controls (p. 1481) topic. Define a Macro Script using the following syntax:
macroScript <name> [ [ [ [ [ ( <macro_script_body> category:<string> ] buttonText:<string> ] toolTip:<string> ] icon:#(<string>, <index>) | icon:<string> ] silentErrors:<boolean> ] )

1522

Chapter 12

Creating MAXScript Tools

For example:
macroScript Free_Camera category:Cameras tooltip:Free Camera Icon:#(Cameras,2) ( StartObjectCreation FreeCamera ) macroScript Target_Camera category:Cameras tooltip:Targeted Camera Icon:#(Cameras,1) ( StartObjectCreation TargetCamera )

After MAXScript evaluates a macroScript construct, the Macro Script definition will show up in the Macro Scripts list in the Customize User-Interface dialog. The following figure shows a Customize User Interface dialog containing the previous two Macro Scripts.

subMenu

1523

<name> is the name shown in the Customize User-Interface dialog. Unlike other similar constructs (Scripted Utilities, Functions, and right-click menus), macroScript does not create a variable with this name. Rather, Macro Scripts are stored as pointers into files, as described below. The category: argument specifies in which category in the Customize User-Interface dialog the Macro Script name will be listed. The use of categories is intended to help you organize your Macro Scripts into groupings so that the Macro Script names are less likely to clash. If you do not specify a category, a default category of unknown is used. The toolTip: argument specifies the tooltip for the button. If no tooltip is specified, no tooltip is displayed for the button. The buttonText: argument specifies the text that will appear in the button, and the icon: argument specifies the icon that will appear in the button. You can choose in the Customize User Interface dialog whether the buttonText or icon appears in the button. If no buttonText: argument is specified, the Macro Script name is used as the buttonText. The icon: argument specifies the icon bitmap file and the icon image within the icon bitmap file. The icon bitmap file must be located in the current 3ds max user-interface directory. Icon bitmap files have a base name, such as MyToolbar, followed by a suffix, such as _24i.bmp, that specifies the individual icon size and icon bitmap file type. The icon: argument string is just the base name, with no extensions present. This base name is the name shown in the Image Group list in the Customize User-Interface dialog. Each icon bitmap file can have any number of individual icons, lined up side-by-side in the file. If the icon bitmap file contains multiple icons, <index> specifies which icon in the icon bitmap file to use. The left-most icon has an <index> of 1. The 3ds max internal icons (Image Group Internal in the Customize User-Interface dialog) are not stored in an icon file, and are referenced by using an empty string as the icon: argument. So, the icon: argument can be either a two-element array containing the icon bitmap files base name as a string and the icons index in that file, or just a base name string, with the index 1 assumed. For example:
macroScript Box category:Objects tooltip:Box icon:#(standard, 1) -- use first icon in standard ( StartObjectCreation Box ) macroScript Sphere category:Objects tooltip:Sphere icon:#(, 2) -- use second icon in internal icons ( StartObjectCreation Sphere ) macroScript Cone category:Objects tooltip:Cone icon:myicon -- use first icon in myicon ( StartObjectCreation Cone )

See the Creating Icon Bitmap Files (p. 1530) topic for more information.

1524

Chapter 12

Creating MAXScript Tools

The silentErrors: parameter gives control over whether MAXScript runtime error messages are displayed while executing the Macro Script. If this parameter is set to true, error messages will not be displayed. This may be useful for distributed Macro Scripts that may confuse the user with MAXScript error messages. The default value is false. The <macro_script_body> is any valid MAXScript expression, and can contain global and local variables, functions, and structure definitions. The <macro_script_body> is compiled in its own local scope, and the locals are only visible inside the scope of the Macro Script. Macro Script locals are heap-based locals, which are slightly different from normal (stack-based) locals. Normal locals are visible in the current scope and have a lifetime of one execution of that scope. Heap-based locals are also visible only in the current scope, but have a lifetime equal to the lifetime of the top-level expression where they are defined. A Macro Scripts locals are created the first time you execute the Macro Script, initialized to a value of undefined, or to their specified initialization value. These values are stored in a separate memory stack. On entry to each function (or top level script) in the Macro Script, a frame in the memory stack is marked and when the function (or top level script) exits, all of the values in the frame are freed from the memory. Because a Macro Scripts name is not created as a variable, you cannot access a Macro Scripts locals outside the scope of the Macro Script. So, for example, you can create a rollout in a Macro Script, and the rollouts event handlers can access the locals defined in the Macro Script because the rollout is executing within the scope of the Macro Script. However, you cannot access the Macro Scripts locals from another utility or from the Listener, because they are not executing within the scope of the Macro Script. See the Scope of Variables (p. 646) topic for more information. When you execute a macroScript definition, the return value is an integer Macro Script ID value. MAXScript internally stores information about each Macro Script in an array, and the returned Macro Script ID value is the array index for that Macro Script. The information stored for each Macro Script consists of the file in which that Macro Script is defined and a pointer into that file specifying where the Macro Script definition begins. The Macro Script definition is only compiled when you first press a toolbar button that contains the script, or execute the Macro Script using the macros.run() method. There are five ways a Macro Script can be defined: The default user-interface directory and its subdirectories will be automatically scanned at startup for files of type .mcr, which will be parsed for Macro Script definitions. A Macro Script definition is executed in an Editor window, in a script file that you execute, or in a startup script file. If you evaluate a Macro Script definition in the Listener window, a file will automatically be created to contain the Macro Script definition. This file is stored in the MacroScripts directory under the current user-interface directory. MAXScript supports text drag onto toolbars to create Macro Script buttons. You can select and drag text from any text window, such as Listener window panes or Editor windows, onto any visible toolbar. The cursor changes to an arrow with + sign when it is OK to drop the text. If you drop it, a Macro Script button is added to the toolbar with the dropped text as the body of the Macro Script. The classic case here would be to drag some text from the Macro Recorder pane in

subMenu

1525

the Listener window onto a toolbar to make a button that does the sequence of events just recorded. Remember that tabbed elements on the Shelf are toolbars and can accept dropped text. MAXScript will automatically enclose the text in a Macro Script definition with a Macro Script name of DragAndDrop-MacroN, where N is a number that will make the Macro Script name unique. The category will be DragAndDrop and no tooltip is specified. As with Macro Scripts defined in the Listener window, a file will automatically be created to contain the Macro Script definition. This file is stored in the MacroScripts directory under the current user-interface directory. A Macro Script can be defined using the macros.new() method described next. As with Macro Scripts defined in the Listener window, a file will automatically be created to contain the Macro Script definition. This file is stored in the MacroScripts directory under the current user-interface directory.

If you move or delete a file that contains a Macro Script definition that has been loaded, and try to execute the Macro Script, you will get an error message. Further, if you edit a file containing Macro Script definitions, take care to save and re-evaluate the entire file so any other Macro Scripts defined in that file will have their file pointer updated. If you dont do this, you may get an error message saying the currently loaded definition no longer matches its file. If you reevaluate a Macro Script definition, any button using that Macro Script will see any changes you make. Any macroScript definition evaluated in MAXScript or created by dropping text onto a toolbar has a separate definition .mcr file created in the MacroScripts directory under the current user-interface directory (typically UI\MacroScripts). The name of the file is <category_name>-<macro_name>.mcr, for example,
DragAndDrop-Macro12.mcr NURBS-Map_Updater.mcr for macroScript Macro12 category:DragAndDrop for macroScript Map_Updater category:NURBS

If you evaluate a macroScript definition in the Listener or drop text on a toolbar, its recorded definition file is this backing file in UI\MacroScripts. This definition file is the one that gets opened if you hit Edit Macro Script in the CUI customize menus or dialogs. For macroScript definitions evaluated in Listener, this means the same definition will be updated each time you evaluate it, rather than having separate backing file for each evaluation. If you evaluate macroScript definitions in a .ms or .mcr file that does not already reside in the UI\MacroScripts directory, a copy for each will be placed in a separate file in UI\MacroScripts, but the recorded definition file will be the original source file, so that hitting Edit Macro Script will go to that file. This means that if any buttons containing such macroScript definitions are added to toolbars in the startup.cui file, the backing .mcr file in UI\MacroScripts will be used as its definition at the next 3ds max startup. When you start 3ds max, the macroScript definitions will taken from the backing files in UI\MacroScripts. If these Macro Scripts are also defined in MAXScript startup script files, they will be re-defined at MAXScript startup and so the definition file of record will be updated to point to the script file.

1526

Chapter 12

Creating MAXScript Tools

MAXScript provides several methods that allow you to access and run Macro Scripts from within a script. These Macro Script functions are in a structure package named macros. The Macro Script methods are:
macros.load [ <path_name_string> ]

Loads all of the Macro Script definition (.mcr) files in the current user-interface directory path, or in directory path specified by <path_name_string>. This method does not change the current user-interface directory path. You can get the current user-interface directory path with the function:
local ui_dir = cui.getDir () macros.new <name_string> <category_string> <toolTip_string> \ <buttonText_string> <body_string>

Creates a new Macro Script with the specified name and category. A file will automatically be created to contain the definition. This file is stored in the current user-interface directory. Returns an integer Macro Script ID value that uniquely identifies the new Macro Script.
macros.run <category_string> <name_string> macros.run <macro_id_integer>

Executes the specified Macro Script. The Macro Script is identified by either its category and name, or by its unique Macro Script ID value.
macros.edit <category_string> <name_string> macros.edit <macro_id_integer>

These methods will open the Macro Script definition (.mcr) file that defines the specified Macro Script in a script Editor window. The Macro Script is identified by either its category and name, or by its unique Macro Script ID value. For example:
macros.load f:/gametools/macros macros.edit objects box macros.run 132 macros.run modifiers bend

Examples: The following Macro Script will save the active viewports image to a bitmap file. Script:
MacroScript GrabViewport category:Tools tooltip:Grab Viewport ( ----------------------------------------------------------------------GRABVIEWPORT MACROSCRIPT --Created:3/23/99 --Edited:4/28/99 --by Borislav Petrov --bobo@email.archlab.tuwien.ac.at ----------------------------------------------------------------------Snapshot Active Viewport to Bitmap --Filename in format: --VPGRAB_MaxFileName_ViewportName_CurentFrame.ImageFormatExtension

subMenu

1527

-----------------------------------------------------------------------Init Variables local grab_bmp --bitmap to put the snapshot into local bmp_name --name of the bitmap to save local get_viewport_name --viewport name local gac,gct,mfn --variables to hold ActiveCamera, CurrentTime, MaxFileName ---Start Macro grab_bmp = gw.getViewportDib() --get the viewport bitmap into variable get_viewport_name = viewport.GetType() --get viewport name gvn = get_viewport_name as string --convert viewport name to string gvn = substring gvn 6 (gvn.count-5) --cut the string if gvn == camera then --if the remaining string is camera ( gac = getActiveCamera() --get the camera gvn = gac.name --get the name of the camera ) mfn = MaxFileName --get max file name if mfn == then --if there is no name mfn = Untitled --use Untitled else mfn = getFileNameFile mfn --use the file name without .MAX extension gct = SliderTime as string --get current frame time -bmp_name = VPGRAB_+ mfn +_ +gvn + _ + gct --build the output file name ---Display file save dialog bmp_name = getSaveFileName caption:Save Viewport to: filename:bmp_name \ types:BMP(*.bmp)|*.bmp|TIFF(*.tif)|*.tif|JPG(*.jpg)|*.jpg|TGA(*.tga)|*.tga| -if bmp_name != undefined then --if user has confirmed / entered a valid name ( grab_bmp.filename = bmp_name --set output name to the one entered in the save file dialog save grab_bmp --save the bitmap display grab_bmp --display the bitmap in a VFB ) )--end of script

The following Macro Script allows you to render directly to the RAMPlayer. This Macro Script shows the use of rollouts and rollout floater windows in Macro Scripts. Script:
-- MacroScript to Render to RamPlayer -- Author: Alexander Bicalho --**************************************************************** -- MODIFY THIS AT YOUR OWN RISK -- This utility will allow you to render directly to the RamPlayer -MacroScript RAM_Render category:Tools tooltip:Render to Ram ( -- declare local variables and define some functions local get_names existFile

1528

Chapter 12

Creating MAXScript Tools

function get_names name a = append a name function existFile fname = (getfiles fname).count != 0 --- create the rollout definition rollout r_size Render Parameters ( local p = 95 local p2 = p+78 group Time Output ( radiobuttons r_time columns:1 align:#left \ labels:#(Single,Active Time Segment,Range:) spinner nth Every Nth Frame: pos:[215,24] fieldwidth:50 \ type:#integer range:[0,10000,1] enabled:false spinner r_from fieldwidth:60 pos:[75,56] type:#integer \ range:[0,10000,1] enabled:false spinner r_to To: fieldwidth:60 pos:[152,56] type:#integer \ range:[0,10000,100] enabled:false ) group Render Size ( spinner rw Width fieldwidth:60 pos:[15,p+08] \ type:#integer range:[0,10000,320] spinner rh Height fieldwidth:60 pos:[12,p+32] \ type:#integer range:[0,10000,240] spinner aspect Aspect fieldwidth:60 pos:[10,p+56] \ type:#float range:[0,20,1.0] button s160 160x120 pos:[125,p+06] width:75 height:19 button s256 256x243 pos:[125,p+30] width:75 height:19 button s320 320x240 pos:[205,p+06] width:75 height:19 button s512 512x486 pos:[205,p+30] width:75 height:19 button s640 640x480 pos:[285,p+06] width:75 height:19 button s720 720x486 pos:[285,p+30] width:75 height:19 button conf_render Configure pos:[125,p+54] width:115 height:19 button wipe Purge Files pos:[245,p+54] width:115 height:19 button go Render pos:[125,p+78] width:235 height:19 ) label abt0 Render to RAM pos:[8,p2+31] label abt1 Version 0.2a pos:[8,p2+46] label abt2 Alexander Esppeschit Bicalho pos:[225,p2+31] label abt3 abicalho@brasilmail.com pos:[249,p2+46] --- define the rollout event handlers on wipe pressed do ( local tempfilename_a = (getdir #image) + \\ramplayertemp_a.avi local tempfilename_b = (getdir #image) + \\ramplayertemp_b.avi if existfile tempfilename_a then deletefile tempfilename_a if existfile tempfilename_b then deletefile tempfilename_b ) -on r_time changed state do ( case state of ( 1: nth.enabled = r_from.enabled = r_to.enabled = false 2: ( nth.enabled = true

subMenu

1529

r_from.enabled = r_to.enabled = false ) 3: nth.enabled = r_from.enabled = r_to.enabled = true ) ) -on on on on on on -on conf_render pressed do (max render scene) -on go pressed do ( local tempfilename_a = (getdir #image) + \\ramplayertemp_a.avi local tempfilename_b = (getdir #image) + \\ramplayertemp_b.avi if existfile tempfilename_b then ( deletefile tempfilename_a copyfile tempfilename_b tempfilename_a tempfilename = tempfilename_b ) else ( if existfile tempfilename_a then tempfilename = tempfilename_b else ( tempfilename = tempfilename_a tempfilename_b = ) ) case r_time.state of ( 1: render outputheight:rh.value outputwidth:rw.value \ pixelaspect:aspect.value \ outputfile:tempfilename vfb:off 2: render outputheight:rh.value outputwidth:rw.value \ pixelaspect:aspect.value \ outputfile:tempfilename vfb:off \ nthframe:nth.value framerange:#active 3: render outputheight:rh.value outputwidth:rw.value \ pixelaspect:aspect.value \ outputfile:tempfilename vfb:off \ nthframe:nth.value fromframe:r_from.value \ toframe:r_to.value ) ramplayer tempfilename_a tempfilename_b closerolloutfloater r_dialogue ) -- end of on go pressed ) -- end of rollout r_size --- close the old rollout floater if it exists s160 s320 s256 s512 s640 s720 pressed pressed pressed pressed pressed pressed do do do do do do (rw.value=160; (rw.value=320; (rw.value=256; (rw.value=512; (rw.value=640; (rw.value=720; rh.value=120; rh.value=240; rh.value=243; rh.value=486; rh.value=480; rh.value=486; aspect.value=1.0) aspect.value=1.0) aspect.value=1.266) aspect.value=1.266) aspect.value=1.0) aspect.value=0.9)

1530

Chapter 12

Creating MAXScript Tools

try(closerolloutfloater r_dialogue);catch() -- put up new rollout floater and add rollout to it. r_dialogue = newrolloutfloater Render to RAM 400 300 addrollout r_size r_dialogue -- end of Macro Script, rollout takes over... )

Creating Icon Bitmap Files

An icon bitmap file can have any number of individual icons, which are lined up side-by-side in the file. If you are creating icon bitmap files, these files must meet the following requirements: Icon bitmap files must be .bmp files. The icon bitmap files are actually groups of files. For each icon bitmap file group there needs to be at least two image files: one containing 16x15 pixel images ending in _16i.bmp, and another containing 24x24 pixel images ending in _24i.bmp. For example, these files would be myicons_16i.bmp and myicons_24i.bmp. All icon images in an icon bitmap file must be the same size, as defined by the file name suffix. Each icon bitmap file group must contain similar icon images in the same order. This allows a single index to locate the desired bitmap, independent of which button size option the user has chosen. If monochrome, Windows-compatible masks are available, they need to be stored in files ending in _16m.bmp and _24m.bmp. For example, these files would be myicons_16m.bmp and myicons_24m.bmp. If 8-bit alpha channel data is available, it needs to be stored in _XXa.bmp files if the alpha is not premultiplied, and in _XXp.bmp files if the alpha is premultiplied, where XX is either 16 or 24. For example, these files would be myicons_16a.bmp and myicons_24a.bmp. If the mask channel bitmap files are present, they are used. If the mask channel bitmap files are not present, then the alpha channel bitmap files are used. If neither the mask nor alpha channel data bitmap files are present, then the color of the upper-left pixel is deemed the transparent color, and a mask is generated automatically for the image bitmaps.

If you wish to generate icons via calls to render() in MAXScript, make sure you use the naming conventions previously described and place the .bmp files in the current 3ds max user-interface directory. You can get the current user-interface directory path with the function:
local ui_dir = cui.getDir ()

Creating Icon Bitmap Files

1531

Scripted Mouse Tools

Scripted Mouse Tools are used to perform a set of actions based on mouse clicks in the 3ds max viewports. Tools are useful for scripted object creation plug-ins, as described in the Scripted Plug-ins (p. 1538) topic. Heres a simple example: Script:
tool foo ( local b on mousePoint clickno do if clickno == 1 then b = box pos:worldPoint else #stop on mouseMove clickno do b.pos = worldPoint )

This tool allows the user to click in a viewport at which point a box is created. Dragging the mouse positions the box and releasing the mouse button stops the tool. Youd start this tool by executing:
startTool foo

The syntax for tools is similar to that for utility definition constructs. They have local variables, functions, and event handlers, but tools have no user-interface items. A tool is created using the tool definition construct in MAXScript. The top-level syntax is as follows:
tool <tool_name> [ prompt:<string> ] [ numPoints:<number> ] ( <tool_body> )

where: <tool_name> is the name of an automatically created variable to hold the value that represents the tool. The scope of this variable is the current MAXScript scope. This value is also returned as a result of the tool declaration. The class of this value is MouseTool. The optional prompt keyword argument specifies the prompt string displayed in the 3ds max Prompt Line while the tool is executing. The optional numPoints keyword argument specifies the maximum number of points (mouse clicks) the tool will use. If the tool is still executing when you reach the numPoints number of mouse clicks, the tool will stop and return a value of #stop. <tool_body> is enclosed in the required parentheses and is a sequence of clauses that define the functions and event handlers that process mouse clicks. These clauses are defined in detail in the Mouse Tool Clauses (p. 1532) topic. The following method invokes a tool:
startTool <tool_name> [ prompt:<string> ] [ snap:#3D|#2D ] \ [ numPoints:<number> ]

where: <tool_name> is the tool name used in a tool definition.

1532

Chapter 12

Creating MAXScript Tools

The optional prompt keyword argument specifies the prompt string displayed in the 3ds max Prompt Line while the tool is executing. If specified, this string overrides the prompt string specified in the tool definition. The optional snap keyword argument specifies the upper limit on snapping. specifying a snap parameter does not turn on snap, only the user can turn it on in the interface. When 2.5D or 3D snapping is turned on by the user, the snap parameter restricts snapping to the specified level. The optional numPoints keyword argument specifies the maximum number of points (mouse clicks) the tool will use. If specified, this value overrides the number of points specified in the tool definition. The return value from startTool() will be either #stop if a called change handler returns the value #stop or the numPoints value is reached, or #abort if the user aborts the tool using a right-click or presses the ESC key. A currently executing tool can also be aborted using the following method:
stopTool <tool_name>

where: <tool_name> is the tool name used in a tool definition. This method would typically be called in a callback function or change handler (see the Change Handlers and Callbacks (p. 1649) topic), or in a timer event handler in a rollout (see the Timer (p. 1512) topic).

Mouse Tool Clauses

The <tool_body> of a mouse tool definition is made up of a sequence of tool clauses as follows:
<tool_body> ::= { <tool_clause> }+

Tool clauses define the components of a tool and can be one of two basic things: Local variables, functions or structure definitions are variables, functions, and structures whose scope is the tool. The <tool_body> is compiled in its own local scope and the locals are only visible inside the scope of the tool. Tool locals are heap-based locals, which are slightly different from normal (stack-based) locals. Normal locals are visible in the current scope and have a lifetime of one execution of that scope. Heap-based locals are also visible only in the current scope, but have a lifetime equal to the lifetime of the top-level expression where they are defined. A tools locals are created the first time you execute the tool and are kept permanently in the heap (unless and until you redefine the tool). This means things like rollouts created in a tool that live beyond the simple execution of the tool can refer to these locals and the locals will still exist. Each time you execute a tool, its local variables are initialized to a value of undefined, or to their specified initialization value. For example, you can create a rollout in a tool, and the rollouts event handlers can access the locals defined in the tool because the rollout is executing within the scope of the tool. You cannot access the tools locals from another utility

Mouse Tool Clauses

1533

or from Listener, because they are not executing within the scope of the tool. See the Scope of Variables (p. 646) topic for more information. Event handlers are special kinds of functions associated with particular events. Event handlers specify the processing you want to occur when a user clicks or moves a mouse, right-clicks, or starts or stops the tool. These actions generate named events and the optional event handler you supply for that event is called when the action occurs.
<tool_clause> ::= <local_variable_decl> | <local_function_decl> | <local_struct_decl> | <event_handler>

Formally, the syntax of a <tool_clause> is defined as follows:

Locals: A <local_variable_decl>, <local_function_decl>, and <local_struct_decl> are exactly the same as local variable, function, and structure definitions in MAXScript:
<local_variable_decl> ::= local <decl> { , <decl> } <decl> ::= <name> [ = <expr> ] -- optional initial value <local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr> <local_struct_decl> <member> ::= struct <name> ( <member> { , <member> } ) ::= ( <name> [ = <expr> ] | <local_function_decl> )

Global variables cannot be declared as a tool clause, however they can be declared within event handler scripts. If you need to ensure a variable name references a global variable, declare the variable name as global immediately before defining the tool in your script. When writing scripts, it is good programming practice to explicitly declare your local and global variables. Implicit declaration is provided as a short-hand, typically used when working in the Listener interactively or developing short scripts. When developing extended scripts, explicitly declaring variables can reduce errors and improve readability of the code. It is also recommend that you declare as local all variables unless you really want them to be global variables. The reasons for this are described in the Scope of Variables (p. 646) topic. Within the functions and event handlers of a tool, 13 pre-defined locals variables are always accessible. Each one holds a useful value relating to the mouse action that just occurred:
viewPoint worldPoint worldDist Point2 Point3 Point3

The current mouse position in viewport pixel coordinates. The current mouse position projected on the active grid in world coordinates. The distance in X, Y, and Z from the previous click point to the current click point in world coordinates.
worldAngle Point3

The angles around the world X, Y, and Z axes from the previous click point to the current click point in world coordinates.

1534

Chapter 12

Creating MAXScript Tools

gridPoint

Point3

The current mouse position projected on the active grid in the coordinate system of the active grid. If the active grid is the home grid, the coordinate system is the home grid plane active in the current viewport (that is, the construction plane). See the discussion of grid versus world values below.
gridDist Point3

The distance in X, Y, and Z from the previous click point to the current click point in the coordinate system of the active grid. If the active grid is the home grid, the coordinate system is the home grid plane active in the current viewport (that is, the construction plane). See the discussion of grid versus world values below.
gridAngle Point3

The angles around the world X, Y, and Z axes from the previous click point to the current click point in the coordinate system of the active grid. If the active grid is the home grid, the coordinate system is the home grid plane active in the current viewport (that is, the construction plane). See the discussion of grid versus world values below.
shiftKey ctrlKey altKey lButton mButton rButton Boolean Boolean Boolean Boolean Boolean Boolean

true if SHIFT key was down. true if CTRL key was down. true if ALT key was down. true if left mouse button was down. true if middle mouse button was down. true if right mouse button was down. When a create mouse tool is used in a level 5 scripted plug-in, an additional local variable is accessible:
nodeTM Matrix3

Provides read/write access to the transform of the node currently being created. This value is in the current grid coordinate system. See the Scripted Plug-ins (p. 1538) topic for more information. When writing SimpleObject scripted plug-ins, you should always use the gridPoint, gridDist, and gridAngle values rather than corresponding world values, as object-creation in SimpleObject scripted plug-ins is managed in the active grid coordinate system. For gridDist, the .X and .Y components are the delta X and Y between the previous clicked point and the current mouse point in the plane of the current grid. The .Z component is a projection from the current Y screen coordinates onto a Z-vector (in the grid coordinate system) based at the last point clicked on the grid, such that the .Z value is the projected height up the Z-vector. For nonorthogonal viewports this is as expected, but for orthogonal viewports (in which you are always

Mouse Tool Clauses

1535

dragging in the XY plane of the grid), this is always the same as gridDist.y. If you are using the gridDist value to build the portion of an object on the grid, or determine the distance on the current grid from the last point, you want to use only the .X and .Y components. For example,
side1Len = gridDist.x side2Len = gridDist.y dist=length [gridDist.x,gridDist.y]

If you are specifying the height off of the current grid, you would typically use the .Z component. For example,
height = gridDist.z

For worldDist, the behavior is similar to that for gridDist, however the projected component is dependent on the construction plane of the viewport. For the Top, Bottom, and non-orthogonal viewports, the projected height is contained in the .Z component. For Left and Right viewports, the projected height is contained in the .X component. For Front and Back viewports, the projected height is contained in the .Y component. When you create a node in the 3ds max user-interface, the local Z axis of the node is perpendicular to the construction plane. When you create a node using MAXScript, by default the local Z axis of the node points along the direction of the world Z axis. If you create a node in a tool (other than in a SimpleObject scripted plug-in), you must take into account the construction plane orientation if you want to duplicate 3ds maxs behavior when creating a node. The easiest way to do this is to create the node in a coordsys grid context and specify the position of the node during creation in grid coordinate space. An example of this is shown in the following script. Script:
tool PointCreator ( local p, createpoint -- define a function to perform actual node creation. Setting coordsys to -- grid in order for the alignment of the nodes local Z axis to be -- perpendicular to the construction grid fn createpoint = in coordsys grid p=point pos:gridPoint --- set up so that a node is created on a mouse button down, move node -- drag, release node at mouse button up. --- if clickno == 1, then we are at first mouse click, which is a mouse -- button down. If clickno != 1, at following mouse button up. on mousePoint clickno do ( if clickno == 1 then createPoint() -- if p == undefined, then clicked twice without mouse movement -- (double clicked). No point object present, so just ignore this click. else if p != undefined do (p.pos=worldPoint;p=undefined) ) --- if p != undefined, we are moving a previously created node -- if p == undefined, and left mouse button is down, create a node on mouseMove clickno do

1536

Chapter 12

Creating MAXScript Tools

( if

p != undefined then p.pos=worldPoint else if lbutton do createPoint()

) ) -- start the tool. No exit condition defined, so right-click to exit. startTool PointCreator

Event Handlers: An <event_handler> is a special function definition local to a tool that you provide to handle the processing you want to occur when a user clicks in a viewport, right-clicks, or starts or stops the tool. Each user action generates a named event and any event handler you supply for that event is called when the action occurs. The available event handlers are:
on start do <expr>

Called when the tool starts.

on end do <expr>

Called when the tool ends.

on freeMove do <expr>

Called when the mouse moves prior to the first click.

on mousePoint <arg> do <expr>

Called for each mouse click, parameter arg contains the number of the click.
on mouseMove <arg> do <expr>

Called when the mouse moves anytime after the first click.
on mouseAbort <arg> do <expr>

Called when the user right-clicks to cancel or presses the ESC key. The <arg> parameter on each of the mouse event handlers lets you know which mouse click you are in. Mouse clicks are actually only the mouse click release, except for the initial mouse click. If you do a mouse click, drag, release, move, click, drag, and release, the on mousePoint event handler is called three times: the first click, the first release, and the second release, with <arg> values of 1, 2, and 3, respectively. The mouse click counter is incremented after processing the on mousePoint event handler, so the <arg> parameter for the mouseMove and mouseAbort event handlers specify the click count for the next mouse click. In the previous example, when you drag between the first click and first release, the <arg> value for a mouseMove event handler will have a value of 2. During the following move, click, and drag it will have a value of 3. The following script simply demonstrates when the various event handlers are called. Simply run this script and drag in the viewports. Right-click or press the ESC key to stop the tools execution.

Mouse Tool Clauses

1537

Script:
tool foo ( on freeMove do print Free Moving on mousePoint clickno do format Point: %\n clickno on mouseAbort clickno do format Abort: %\n clickno on mouseMove clickno do format Moving: %\n clickno on start do print Starting on end do print Ending ) startTool foo prompt:Hello!

All of the mouse action event handlers may return the special value #stop which causes the tool to stop. In the following mousePoint event handler example, the first click creates the box and the release (second click) terminates the tool.
on mousePoint clickno do if clickno == 1 then b = box pos:worldPoint else #stop

Example: The following script implements the following functions: on mouse click three spot lights are created at the mouse point. While holding the mouse button down, drag the mouse to position the classical key, back and fill light positions. During this drag, holding down the SHIFT key will flip the fill light side. Release the mouse button and move the mouse to change the elevation of the lights. Click the mouse button when the lights are at the correct height. The back light is raised 1.5 times the key lights height, and the fill light is raised 0.75 times the key lights height. To start this tool, youd say:
startTool three_lights

and then drag in one of the viewports. Script:

tool three_lights ( local key, fill, back, targ -on mousePoint click do coordsys grid ( if click == 1 then -- create key, back & fill lights at mousedown ( targ=targetobject pos:gridPoint key = targetspot pos:gridPoint name:key target:targ back = targetspot pos:gridPoint name:back target:targ fill = targetspot pos:gridPoint name:fill target:targ ) if click == 3 then #stop ) -on mouseMove click do ( if click == 2 then -- drag out & round on x-y plane ( coordsys grid key.pos = gridPoint

1538

Chapter 12

Creating MAXScript Tools

coordsys targ back.pos = - key.pos local p = if shiftKey then 90 else -90 coordsys targ fill.pos = key.pos * ((eulerangles 0 0 p) as quat) ) else if click == 3 then -- drag up to elevate lights ( in coordsys targ ( local Z = gridDist.z key.pos.z = Z back.pos.z = Z * 1.5 fill.pos.z = Z * 0.5 ) ) ) )

See also
Scripted Mouse Tools (p. 1531)

Scripted Plug-ins
MAXScript supports several levels of scripted plug-ins, as follows: The scripted plug-in appears in the user interface as a new class but does not allow instances of itself in the scene. It lets you define a mouse tool that creates other objects in the scene, but once youve finished creation, there is no instance of the class left in the scene to modify or save. Examples of this currently in 3ds max are the System classes such as RingArray. The scripted plug-in extends an existing plug-in, either adding to or replacing the command panel parameter rollouts for the existing plug-in. For example, you might create a new glass material which extends StandardMaterial and provides a custom, presumably smaller, Material Editor rollout that just has glass parameters which set up and modify various properties in the underlying material plug-in as appropriate. Or, you want to create a new light type that is actually a system of coordinated lights, that also has a controlling dummy object created. This controlling dummy keeps track of the lights in the system and has a Create/Modify panel rollout that allows coordinated manipulation of the system. In this case, youd create a new helper plug-in that extends Dummy, has locals to store the lights, and define a rollout. You would also create a new light plug-in with a create tool that builds the system. The scripted plug-in is given a unique and permanent class ID value by the script writer and so can be instanced in the scene and stored in scene files. All 3ds max plug-ins have a unique class ID and 3ds max uses this class ID to associate stored scene objects with the code that handles them each time you open a scene file, hence it has to be unique and permanent. In the level 1 scripted plug-in above, MAXScript allocates a temporary class ID that is not permanent across executions of 3ds max and thus prevents instancing in the scene. The scripted plug-in defines one or more parameter blocks, containing directly animatable parameters that are saved to and restored from scene files. These are the permanent parameters for the plug-in and are distinct from the local variables in the example above which only live during creation.

Mouse Tool Clauses

1539

A parameter block can be associated with a rollout in the scripted plug-in that provides a user interface for the parameters in the parameter block. When associated in this way, the parameters are wired to their spinners and checkboxes, etc., and both update automatically as the other changes. The general form for a scripted plug-in is:
plugin <superclass> <varname> {keyword:val} ( <plugin_body> )

where: <superclass> is one of the currently-supported plug-in superclasses:

Geometry SimpleObject Shape Light Helper Modifier SimpleMod Material TextureMap RenderEffect Atmospheric

<varname> is the name that will be given to the global variable that contains this plug-in class. This class value is just like a normal plug-in class (like box, sphere, etc.) and you can create an instance of the plug-in in MAXScript by applying the class value. {keyword:val} is an optional sequence of keyword/value pairs defining options for the plug-in. These pairs are:
name:<string>

The optional name: parameter specifies the name of the plug-in as seen in the 3ds max user-interface. For example, if the superclass of the plug-in is geometry or light, this name would be displayed on the plug-ins button in the Create panel; if the superclass of the plug-in is modifier, this name would be displayed on the plugins button in the Modify panel; and if the superclass of the plug-in is material or textureMap, this name would be displayed in the Material/Map Browser. The default name is the plug-ins <varname>.
category:<string>

The optional category: parameter specifies in which object category (access via the object category list) the plug-in will appear in. This parameter is applicable only to plug-ins that appear in the Create panel. The default category in Standard. Note that there is a fixed number of buttons available in the Create panel for each category. If a button for your plug-in does not show up in the appropriate Create panel, you may need to make a new category for it.

1540

Chapter 12

Creating MAXScript Tools

classID:#(<integer>,<integer>)

You supply the classID:#(<integer>,<integer>) parameter if you want the plug-in to be creatable and storable in the scene. This ID becomes the permanent ID for the class and is used by 3ds max to identify objects as they are saved and loaded in the scene. You dont need to supply a class ID value if the plug-in is to be like a System object that only creates other types of objects in the scene. The class ID is basically a pair of numbers, chosen randomly so that (hopefully) they wont conflict with another plug-in. MAXScript provides a method to generate a fresh random class ID each time you run it:
genClassID()

This method generates a random class ID similar to #(0x9b7ea231, 0xb6db86ef), and prints it to Listener. You can just cut and paste this class ID into your script to use the generated ID.
extends:<maxClass>

The extends:<maxClass> parameter is supplied if you want to base your plug-in on an existing plug-in. This basically lets you add a new class that works internally exactly like the one you are extending, but with an expanded or replaced user interface. The class you specify must have the same superclass as specified in the scripted plug-in header. Current limitations prevent certain plug-ins from being extended, in particular those with custom creation managers. These include target lights and cameras and all the System plug-ins. You can tell if a plug-in is not extendable if your new rollouts do not appear. When you create an object of scripted plug-in that extends another, MAXScript also creates an internal object of the extends: plug-in and passes most of 3ds maxs interaction with your plug-in onto the internal object. This is called delegation and the internal extends: plug-in object is the delegate. The delegate is visible in your plugins objects in Track View and you can access the delegate in your scripts to control it as needed. See the locals section below for more information. The delegate is not shown in TV if replaceUI:true is specified.
replaceUI:<boolean>

The replaceUI: parameter is used only when extends: is supplied to indicate whether the rollouts in your plug-in should add-to or replace the extended plug-ins rollouts. The default is false, which means your rollouts will be appended at the end of the extended plug-ins. Another current limitation when extending plug-ins whose objects are created in the Create panel only allows user interface replacement in the Modifier panel; the original plug-ins rollouts are always displayed along with the scripted rollouts in the Create panel.
version:<integer>

The optional version: parameter specifies the version number of the scripted plugin. The value assigned to this parameter is used when updating the scripted plug-in definition. The default value for this parameter is 1. See the Updating Scripted Plug-ins (p. 1553) topic for more information on this parameter.

Mouse Tool Clauses

1541

invisible:<boolean>

The optional invisible: parameter gives control over whether the plug-in is visible in the Create panel Object Type rollout or in the Material/Map Browser, etc. This is useful for component or controlling objects created as part of a group, say in a Systemstyle plug-in that should not be creatable on their own. Set this parameter to true to hide the plug-in.
silentErrors:<boolean>

The optional silentErrors: parameter gives control over whether MAXScript runtime error messages are displayed when executing handlers in the scripted plug-in. If this parameter is set to true, error messages will not be displayed. This may be useful for distributed scripted plug-ins that may confuse the user with MAXScript error messages. <plugin_body> is enclosed in the required parentheses and is a sequence of clauses that define the local variables and functions, parameters, user-interface items, and event handlers that define the plug-in. These clauses are defined in detail in the Scripted Plug-in Clauses (p. 1542) topic. If you load a scene file that uses a level 3 or higher scripted plug-in, and you have not defined that scripted plug-in, a Missing DLL dialog will be displayed after the load, indicating the definition for the scripted plug-in is missing. The file will then load using a standin for the object with the missing definition, just as it would for other objects missing their DLL definitions. 3ds max treats scripted plug-ins as it does C++ plugins, requiring the definition to be in place, either in a script file in the plugins directory when 3ds max starts, or having been defined by running some script prior to loading the file.

See also
Scripted Plug-in Clauses Scripted Plug-in Methods Updating Scripted Plug-ins Scripted Geometry Plug-ins Scripted SimpleObject Plug-ins Scripted Shape Plug-ins Scripted Light Plug-ins Scripted Helper Plug-ins Scripted Modifier Plug-ins Scripted SimpleMod Plug-ins Scripted Material Plug-ins Scripted TextureMap Plug-ins Scripted RenderEffect Plug-ins Scripted Atmospheric Plug-ins

1542

Chapter 12

Creating MAXScript Tools

Scripted Plug-in Clauses

The various optional clauses inside the plug-in body are similar to those for scripted utilities and tools. There is an additional scripted plug-in specific clause <parameters> for defining scenesavable and Track View visible parameters for the plug-in. The <plugin_body> of a scripted plug-in definition is made up of a sequence of plug-in clauses as follows:
<plugin_body> ::= { <plugin_clause> }+

Plug-in clauses define the components of a scripted plug-in and can be one of five basic things: Local variables, functions or structure definitions are variables, functions, and structures whose scope is the plug-in. These locals will exist as long as the instance of the plug-in exists. The visibility of locals, and accessing scripted plug-in locals from external code, are described in the Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code (p. 1478) and Accessing Locals and Other Items in a Rollout from External Code (p. 1480) topics. Parameter blocks define a set of parameters for the plug-in, which are like plug-in local variables, but are directly animatable and are saved to and restored from scene files. You can also associate each parameter with appropriate user-interface elements in one of the plug-ins rollouts. When associated in this way, the parameters are wired to their spinners and checkboxes, etc., and both update automatically as the other changes, so you dont have to write any user-interface event handlers for them. These parameters correspond to the visible parameters you see in other 3ds max plug-ins. Mouse tools are used to perform a set of actions based on mouse clicks in the 3ds max viewports, and are described in the Scripted Mouse Tools (p. 1531) topic. Rollouts can be displayed for the scripted plug-in. For scripted plug-ins that extend an existing plug-in, these rollouts can be displayed in addition to or replace the existing plug-ins rollouts. Rollout definitions are described in the Utility Clauses (p. 1466) topic. Event handlers are special kinds of functions associated with particular events. Event handlers specify the processing you want to occur when a user creates an instance of the scripted plug-in or when 3ds max calls the scripted plug-in. These actions generate named events and the optional event handler you supply for that event is called when the action occurs.
<plugin_clause> ::= <local_variable_decl> <local_function_decl> <local_struct_decl> <parameters> <tools> <rollouts> <event_handler> | | | | | |

Formally, the syntax of a <plugin_clause> is defined as follows:

Scripted Plug-in Clauses

1543

Locals: A <local_variable_decl>, <local_function_decl>, and <local_struct_decl> are exactly the same as local variable, function, and structure definitions in MAXScript:
<local_variable_decl> ::= local <decl> { , <decl> } <decl> ::= <name> [ = <expr> ] -- optional initial value <local_function_decl> ::= [ mapped ](function | fn) <name> { <argument> } = <expr> <local_struct_decl> <member> ::= struct <name> ( <member> { , <member> } ) ::= ( <name> [ = <expr> ] | <local_function_decl> )

Global variables cannot be declared as a plug-in clause, however they can be declared within event handler scripts. If you need to ensure a variable name references a global variable, declare the variable name as global immediately before defining the plug-in in your script. When writing scripts, it is good programming practice to explicitly declare your local and global variables. Implicit declaration is provided as a short-hand, typically used when working in the Listener interactively or developing short scripts. When developing extended scripts, explicitly declaring variables can reduce errors and improve readability of the code. It is also recommend that you declare as local all variables unless you really want them to be global variables. The reasons for this are described in the Scope of Variables (p. 646) topic. Plug-in locals are attached to plug-in objects, and each new instance of the scripted plug-in has its own local storage area. When you reference a plug-in local in a plug-in function or handler, it accesses the local storage of the currently active object, for example, the object currently open in the command panel. Plug-in local storage is not permanent across scene saves and loads (unlike <parameters>). You can provide initial values for locals, as elsewhere in MAXScript, and the locals are re-initialized when a saved scripted plug-in object is loaded again as part of a scene file open. You can also do this by hand in a create event handler if you supply one in the plug-in. Plug-in locals are accessible to script code outside a plug-in as a normal property on the object, but note that they may be hidden by parameters or other common object properties if they have the same name. When accessing a property on a scripted plug-in object, MAXScript first looks in the common properties (such as .pos, .scale, .parent, etc. on a node), then in the parameters, and then in the locals for a property name match. There are three predefined local variables accessible in all scripted plug-ins:
version

Yields the current version of the object as an Integer value.

this

Yields the instance of the scripted plug-in.

delegate

Yields the instance of the plug-in you are extending in an extends: plug-in.

1544

Chapter 12

Creating MAXScript Tools

The version local variable contains the version number specified in the scripted plug-in definition. See the Updating Scripted Plug-ins (p. 1553) topic for more information on this variable. The this local variable always contains the MAXScript value corresponding to the current instance of the scripted plug-in. This variable provides a guaranteed way of accessing parameters on the new object within plug-in code (in case there are locals or globals with the same name), and it is a way of referencing the plug-in in case you want to store it to a variable. The delegate local variable contains the MAXScript value corresponding to the instance of the plug-in being extended. To access common properties or subAnim properties in the instance of the plug-in being extended, you need to do so via the delegate local variable. For example,
delegate.width = thisWidth

inside a plug-in function or handler would set the .width property in the instance of the plug-in being extended. The delegate local variable in a scripted plug-in that creates a scene object does not contain the node itself, but a the BaseObject of that node. As such, you can not access the node level properties of the object being created. An exception to this is the nodes transform, which is exposed to the scripted plug-in through a local variable called nodeTM. This variable is described in the applicable scripted plug-in type topics. If the extends: parameter is not supplied for a plug-in, delegate returns undefined. As well as local variables, you can define local functions and local structures, just as you can with scripted utilities and rollouts. Parameters: You can define one or more parameter blocks in a scripted plug-in. A parameter block has the form:
parameters <name> [type:#class] [rollout:<name>] ( { <param_defs> }+ { <event_handler> } )

A parameter block defines a set of parameters for the plug-in, which are like plug-in local variables, but are directly animatable and are saved to and restored from scene files. You can also associate each parameter with appropriate user-interface elements in one of the plug-ins rollouts. When associated in this way, the parameters are wired to their spinners and checkboxes, etc., and both update automatically as the other changes, so you dont have to write any user-interface event handlers for them. These parameters correspond to the visible parameters you see in other 3ds max plug-ins. Parameters in the parameter block do not participate in 3ds maxs undo system, therefore changes to the parameter values are not undoable. The <name> you give to a parameter block becomes permanently associated with the parameter block and is used by MAXScript to connect to the right parameter block in a plug-in object that is being loaded from a scene file. This becomes important as you modify a plug-in script and yet there are still objects corresponding to the old definition in other files. When the old-version object is loaded, MAXScript attempts to convert it to the new definition, using the current parameter block definition as a guide. In order to properly do this, each parameter in a parameter block is also given

Scripted Plug-in Clauses

1545

a permanent name. So, if you have existing objects of your plug-in in other files, dont go randomly changing parameter block names or they wont be loadable. The optional type:#class specifies that the parameters in the parameter block are class parameters. This means that there is one copy of each parameter for the *all* the objects of this plugin class; they all share the parameter. Examples of existing class parameters are the creation type and type-in parameters in a typical geometry primitive. The optional rollout:<name> specifies a rollout definition elsewhere in the plug-in body to use as the user-interface rollout for the parameter blocks parameters. A limitation of the internal parameter block mechanism requires that each parameter block be associated with a separate rollout and each rollout be associated with only one parameter block. This means that each rollout you want to have in the plug-ins user interface must have its own separate parameter block. The <param_defs> are definitions for each parameter in the parameter block. They have the form:
<name> type:<#name> [tabSize:<integer>] [tabSizeVariable:<boolean>] \ [default:<operand>] [animatable:<boolean>] \ [subAnim:<boolean>] [ui:<ui_def>]

The <name> is permanently associated with the parameter in the same sense as parameter block names. They are used to connect to the right parameter when loading objects of the scripted plugin and allow you to make certain changes to a script and yet still be able to load old version objects. So, as with parameter block names, dont change or re-use parameter names if you have scene files with old version objects you want to get at. The type:<#name> parameter is required and defines the parameter type. It can be one of the following:
#float #integer #color #point3 #boolean #angle #percent #worldUnits #string #filename #colorChannel #time #radiobtnIndex #material #texturemap #bitmap #node #maxObject animatable animatable animatable animatable animatable animatable animatable animatable

animatable animatable

1546

Chapter 12

Creating MAXScript Tools

or one of the following types which are arrays of the above base types:
#floatTab #intTab #colorTab #point3Tab #boolTab #angleTab #percentTab #worldUnitsTab #stringTab #filenameTab #colorChannelTab #timeTab #radiobtnIndexTab #materialTab #texturemapTab #bitmapTab #nodeTab #maxObjectTab

#worldUnits and #worldUnitsTab specify that a parameter holds a world distance value, kept internally as a system units float. For example:
parameters main rollout:params ( height type:#worldUnits ui:heightSpin )

Note that this doesnt cause any spinner display to be automatically shown in current display units, you need to also specify type:#worldUnits on the associated rollout spinner definition. #node and #nodeTab are used to store references to nodes. The nodes stored in these parameters cannot create a circular dependency. If, for example, you were creating a scripted helper, and set the helper as a target or parent of a camera, you can not store the camera node in a #node or #nodeTab parameter. Likewise, if you created a scripted modifier or material, and store a node in a #node or #nodeTab parameter, you cannot apply the modifier or material to that node.

Scripted Plug-in Clauses

1547

The various xxTab parameter types allow you to store an array of values having the corresponding type. The initial size of the array is specified using the tabSize: specifier. If tabSizeVariable:true is specified, the size of the array will be automatically expanded when you assign to an higher array index. For example:
parameters main rollout:params ( mapAmounts type:#floatTab tabSize:4 tabSizeVariable:true \ ui:(map1Amount, map2Amount, map3Amount) )

defines an array parameter containing 4 float elements (defined by the tabSize: parameter). You can associate a separate rollout element with each array parameter element. These parameters appear as arrays when accessed in plug-in handler code, for example:
a = mapAmounts[i]

Since tabSizeVariable:true was specified, the following will automatically increase the array size to 10:
mapAmounts[10] = a

You can also increase or decrease the array size by assigning a value to the .count property. Each element in an array parameter whose base type is a number of some kind (floatTab, intTab, percentTab, etc.) is independently and automatically animatable, unless you specify animatable:false. You can get at and assign individual controllers via the .controller property. For example:
c = mapAmounts[i].controller

The optional parameter default:<operand> specifies a initial default value for the parameter. The <operand> expression has to be convertible by MAXScript to the base type of the parameter. The optional parameter animatable:<boolean> specifies whether the parameter is animatable and hence visible in the track view. Only those base types marked as animatable in the above type list can be specified as animatable. Defaults to true. The optional parameter subAnim:<boolean> can be specified for the 3ds max object types: #node, #material, #textureMap, and #maxObject. If specified as true, the 3ds max object is made visible as a sub-object track in track view. Defaults to false. The optional parameter ui:<ui_def> is used to specify which user-interface element in the parameter blocks associated rollout is to be linked to this parameter. When so linked, the handling of user actions for these elements are automatic and they also update automatically to follow any changes to the parameter caused by animation, scripts, etc. For example, in the following, the parameter block named main is associated with the rollout named params. The parameters height and spread are then linked with the spinners named height and spread in that rollout:

1548

Chapter 12

Creating MAXScript Tools

parameters ( key fill back height spread

main rollout:params type:#node subAnim:true type:#node subAnim:true type:#node subAnim:true type:#float animatable:true default:10 ui:height type:#float animatable:true default:10 ui:spread

on height set val do ( key.pos.z = val back.pos.z = val * 1.5 fill.pos.z = val * 0.5 ) ) rollout params Light Parameters ( spinner height Height spinner spread Spread )

Once this is done, the parameter and spinner are linked, such that changes in one are reflected immediately and automatically in the other. Further, if the parameter is animated, the spinner will show red keyframe highlights when the time slider is positioned at a keyframe for that parameter, as with other 3ds max plug-ins. The kinds of user-interface items that can be linked to particular parameter types is limited to the following sensible combinations:
Parameter type #integer #float #time #color #angle #percent #colorChannel #boolean #node #textureMap #material #worldUnits Rollout user-interface item spinner, slider, radioButtons, checkbox, checkbutton spinner, slider spinner, slider colorpicker spinner, slider spinner, slider spinner, slider checkbox, checkbutton pickButton mapButton materialButton spinner, slider

Parameter Event Handlers: Two event handlers are associated with parameters. These handlers are called when a parameter is assigned a value, or when the parameter value is retrieved.
on <name> set <arg> do <expr>

A set handler can be supplied for any of the parameters in the block and it will be called whenever the parameter is updated, either through an associated rollout user-interface item or directly, especially via MAXScript property assignment. In general, the way you would code change handlers is to supply set handlers for parameters, rather than on <item> change handlers for spinners and checkboxes, etc. in the rollout definition. A set

Scripted Plug-in Clauses

1549

handler in used in the previous example to update the light positions when the height parameter value changes. The set handlers are also called when an instance is created or loaded so that common dependent actions can be taken, such as setting up other dependent system object or delegate properties. If a parameter is animated and has a set handler supplied, the handler will be called whenever the 3ds max time changes, say by dragging the time slider around or within an animation rendering.
on <name> get <arg> do <expr>

A get handler can be supplied for any of the parameters in the block and it will be called whenever the parameter value is retrieved. This will occur when the user interface updates itself, a script accesses the parameter, a viewport is redraw, a render occurs. In all these cases, the animated value is retrieved one or more times. The get handler is called with a single argument which is the current value stored in the paramblock (or underlying controller if the parameter is animated). The currentTime variable is set to the time at which the value is being retrieved and not necessarily the current slider time, since you can ask a parameter for its value for any specified time. If you implement the get handler, you must return a value, and that value is returned as the value of the parameter to the value requester. If you dont want to modify the value, but just monitor accesses, return the argument. You can also compute and return any value of the appropriate type. Tools: Plug-ins can define local mouse tools. Although you can have any number of local tools and start them as needed, you would typically supply a single tool with the reserved name create. This is taken to be the create tool for objects created in the Create panel and is invoked automatically when you create scripted plug-in objects. Tool definitions are described in the Scripted Mouse Tools (p. 1531) topic. Creatable scene scripted plug-ins (scripted plug-ins that are not invisible, temporary, or extend another plug-in) require a create tool. A create tool, if present on a non-temporary extending plug-in, will override the delegates create tool. The animate state is implicitly turned off while the create tool is executed. A local variable nodeTM is accessible within the create tool. This variable contains a Matrix3 values. This value is in the active grid coordinate system. This variable allows the create tool to set the transform of the node currently being created. Also, within the create tool you should use the gridX values rather than worldX values in all cases, since object-creation is managed in the active grid coordinate system. Rollouts: Plug-ins can define local rollouts. These have the same syntax as local rollouts in scripted utilities. Unlike utility local rollouts, these rollouts are automatically opened as appropriate for the plug-in type (in the command panel or Material Editor, etc.).

1550

Chapter 12

Creating MAXScript Tools

Note that rollout local variables only live as long as the rollout is open in the user interface. It gets opened and closed each time it is displayed and so the rollout open and close events are signalled at this time. If you want to load any spinners or other user-interface elements from the currently editing plug-in object, supply an on <rollout> open event handler to pick up these values. Rollout definitions are described in the Utility Clauses (p. 1466) topic. Event Handlers: As with mouse tools, scripted plug-ins respond to certain actions in 3ds max by implementing handler functions. All types of scripted plug-ins support the following event handlers. You can use these event handlers to perform any extra initialization needed, such as loading up plug-in local variables or initializing properties of the plug-ins delegate.
on create do <expr>

The create event handler that is called whenever an instance of a scripted plug-in is created in a scene file. The animate state is implicitly turned off while the create event handler expression is executed.
on load do <expr>

The load event handler that is called whenever an instance of a scripted plug-in is loaded from a scene file. The animate state is implicitly turned off while the load event handler expression is executed.
on update do <expr>

The update event handler that is called whenever an instance of a scripted plug-in is present in the scene file, and the definition of the scripted plug-in is changed (i.e., if you define a scripted plug-in, create an instance of the plug-in object in the scene, and then change and execute the script defining the scripted plug-in, the update event handler defined in the new definition of the scripted plug-in script is called for each instance of the plug-in object in the scene). See the Updating Scripted Plug-ins topic for more information. Specific classes of scripted plug-ins implement additional event handlers, and are described with description of the scripted plug-in type. Runtime errors in certain event handlers cause the plug-in to be disabled until it is re-defined. When disabled, none of the plug-in event handlers are called. For example, errors in the map event handler expression in SimpleMods and the buildMesh event handler expression in SimpleObject disable the plug-in, since they are called so frequently. You will need to correct any problems and re-evaluate the plug-in definition again to re-enable the plug-in event handlers.

See also
Scripted Plug-ins (p. 1538)

Scripted Plug-in Methods

1551

Scripted Plug-in Methods

The addPluginRollouts() is used within scripted plug-in create tools, specifically for level 1 plug-ins that dont create instances of themselves in the scene but might create other objects within their create tool. This method lets you install rollouts for a specified object in the Create panel, typically one of the objects being created in the create tool, so that its parameters can be adjusted directly during creation. The form is:
addPluginRollouts <obj>

In the following example, a variation of the three light mouse tool example presented in the Mouse Tool Clauses (p. 1532) topic is set into permanent, editable classes. It defines two new classes. The helper class lightMaster is used as a master object for the light system. The light class threeLights is what you create to layout the initial system. It also creates a lightMaster and sets its parameters to point at the lights. The lightMaster rollout allows subsequent editing of the system in the Modifier panel, and storing the lights in a parameter block makes the setup persistent over scene saves and loads. Script:
plugin helper lightMaster name:Light Master classID:#(12345,54321) extends:Dummy replaceUI:true invisible:true ( parameters main rollout:params ( key type:#node subAnim:true fill type:#node subAnim:true back type:#node subAnim:true height type:#worldUnits default:0 ui:height spread type:#worldUnits default:0 ui:spread angle type:#angle default:90 ui:angle --- check value of key since lights dont exist at initial creation on height set val do if key != undefined then coordsys key.target ( key.pos.z = val back.pos.z = val * 1.5 fill.pos.z = val * 0.5 ) -on spread set val do if key != undefined then coordsys key.target ( -- compute normal vector pointing at key in the targets XY plane -- (kuv) and reposition everything based on that and the current -- spread and angle values local kuv = normalize ([key.pos.x, key.pos.y, 0]) key.pos = [kuv.x * spread, kuv.y * spread, height] back.pos = [kuv.x * -spread, kuv.y * -spread, height * 1.5] -- position fill by placing it under the key and then rotating in -- about the target

1552

Chapter 12

Creating MAXScript Tools

fill.pos = [kuv.x * spread, kuv.y * spread, height * 0.5] about key.target rotate fill angle z_axis ) -on angle set val do if key != undefined then coordsys key.target ( fill.pos = [key.pos.x, key.pos.y, height * 0.5] about key.target rotate fill angle z_axis ) ) -rollout params Light Parameters ( spinner height Height type:#worldUnits range:[-1e32, 1e32, 0] spinner spread Spread type:#worldUnits range:[0, 1e32, 0] spinner angle Angle range:[-180, 180, 30] -on params open do flagForeGround #(key, back, fill) true on params close do if key != undefined and back != undefined and fill != undefined then flagForeGround #(key, back, fill) false ) ) -plugin light threeLights name:Three Lights ( local master -tool create ( on mousePoint click do ( if click == 1 then -- create key, back & fill lights at mousedown ( coordsys grid ( master = lightMaster pos:gridPoint master.dummy.boxsize = [10,10,10] in master ( local targObj=targetobject pos:gridPoint master.key = targetspot pos:gridPoint name:key \ target:targObj master.back = targetspot pos:gridPoint name:back \ target:targObj master.fill = targetspot pos:gridPoint name:fill \ target:targObj ) ) addPluginRollouts master ) if click == 3 then ( select master master = undefined #stop ) ) --

Updating Scripted Plug-ins

1553

on mouseMove click do ( if click == 2 then -- drag out & round on x-y plane ( -- place the key on the grid then set the spread and the -- on set spread handler will -- move the lights to the correct heights master.key.pos = worldPoint master.spread = distance master.key master.key.target ) else if click == 3 then -- drag up to elevate lights master.height = gridDist.z ) -on mouseAbort click do ( if master != undefined then ( if master.fill != undefined then delete master.fill if master.back != undefined then delete master.back if master.key != undefined then delete master.key delete master ) ) ) )

See also
Scripted Plug-ins (p. 1538)

Updating Scripted Plug-ins

MAXScript allows you to redefine scripted plug-ins while working in 3ds max, and have old instances in the current scene and in scenes you load automatically updated to the new definition. This ability to redefine scripted plug-ins is called schema-migration. MAXScript does this roughly by matching the names of local variables, parameter blocks and parameters between the old version instances and the new definition. It keeps any variables, parameter blocks and parameters of the same name, drops anything missing in the new definition and creates new variables, blocks and parameters as needed, filling them in with default values. There are some limitations on the kinds of change that can be supported. Specifically: Parameter blocks that were per-instance cannot be made per-class and vice versa. Parameters cannot change type across redefinitions. Parameters cannot not move from one parameter block to another across redefinitions

This same mechanism is used to update old versions of scripted plug-in objects stored in scene files. Remember that this only works properly if the classID: specified in the scripted plug-in definition that was in force when the scene was saved is the same as the current classID: in the definition since 3ds max depends upon this classID to match up objects in the scene file and their class definitions.

1554

Chapter 12

Creating MAXScript Tools

You can specify an update event handler in a scripted plug-in and it will be called whenever the object is updated by this schema migration mechanism. To make this more useful, MAXScript supports a version number on scripted plug-ins. The version for any particular instance of the plugin can be accessed via the version special local variable in any plug-in local function or handler. When the update event handler is called during a schema-migration, the old version number is still in force, but is updated to the current version number immediately after update. For example:
plugin helper lightMaster name:Light Master classID:#(12345,54321) extends:Dummy invisible:true replaceUI:true version:3 -- set current version to 3 ( parameters main rollout:params ... on update do ( if version == 1 then ... ) ... )

-- do something special for v1 instances

Note that you only need to use this explicit version access and update scheme if you want to do some special manual conversion over-and-above the automatic migration described above. Finally, if there are no existing instances of the plug-in, either in the current scene or in other scenes that you care about keeping, you can simply delete them and make whatever changes you like the scripted plug-in definition. The above version update considerations come into play only when you wish to support old version objects of your scripted plug-in.

See also
Scripted Plug-ins (p. 1538)

Scripted Geometry Plug-ins

1555

Scripted Geometry Plug-ins

A scripted Geometry plug-in is declared by specifying the <superclass> as geometry. Scripted Geometry plug-ins require a create tool unless they are invisible, temporary, or extend another plug-in. If the plug-in extends another plug-in, and a create tool is specified, it will override the delegates create tool. Script:
plugin geometry foo_plugin_def name:FooBar category:Scripted Primitives ( local boxes, clickAt tool create ( on mousePoint click do ( clickAt = worldPoint boxes = for i in 1 to 10 collect box pos:([i*20,0,0] + clickAt) #stop ) ) -rollout frab Parameters ( spinner frab Frabulate range:[-1000,1000,20] on frab changed val do for i in 1 to 10 do boxes[i].pos = [i*val,0,0] + clickAt ) )

This adds a new geometry category with one button to the Create panel. Pressing the FooBar button starts a mouse command mode that creates a row of 10 boxes where you click and adds a rollout to the command panel with one spinner that lets you adjust the separation of the boxes. This is very similar to a System object like the RingArray, except it lives in the Geometry tab. This is the simplest type of scripted of plug-in; it has no specific scene object and no storable parameters. In the tool handlers, you can set the delegate properties as needed. For example: Script:
plugin geometry Cuboid name:Cuboid classID:#(0x133067, 0x54374) category:Scripted Primitives extends:Box ( fn fmax val1 val2 = if val1 > val2 then val1 else val2 tool create ( on mousePoint click do case click of ( 1: nodeTM.translation = gridPoint 2: #stop ) -on mouseMove click do if click == 2 then

1556

Chapter 12

Creating MAXScript Tools

delegate.width = delegate.length = delegate.height = 2 * fmax (abs gridDist.x) (abs gridDist.y) ) )

See also
Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)

Scripted SimpleObject Plug-ins

A SimpleObject is a kind of geometry primitive object that is defined by a tri-mesh, such as box, sphere, cone, and so on. In other words, all the Standard and Extended primitives in 3ds max. In scripting a SimpleObject plug-in, you supply a handler for building this mesh and 3ds max automatically handles scene display, hit-testing, ray intersection, rendering, modifier applicability, etc. A scripted SimpleObject plug-in is declared by specifying the <superclass> as simpleObject. Scripted SimpleObject plug-ins require a create tool. A SimpleObject plug-in must not perform any scene related actions such as creating scene nodes or building modifier stacks. It should basically only be adjusting its parameters in the mouse tool handlers and constructing a mesh in the buildMesh handler. Attempting to create scene nodes or applying modifiers in a SimpleObject plug-in will cause all kinds off strange interactions with the in-progress scene node creation. A SimpleObject plug-in has a predefined local variable mesh. This variable contains the underlying mesh of the object being created. The mesh local variable is accessible in any of the plug-ins handlers, but is typically only built in the buildMesh handler. You can either modify the existing TriMesh value in place, using the TriMesh methods, or construct a new TriMesh value and assign it to the mesh plug-in local variable. The TriMesh methods and properties are described in the Editable Mesh (p. 1041) topic. Script:
plugin simpleObject tower_plugin_def name:Tower classID:#(145345,543211) category:Scripted Primitives ( parameters main rollout:params ( height type:#worldUnits ui:height default:0 width type:#worldUnits ui:width default:0 depth type:#worldUnits ui:depth default:0 ) -rollout params Two Faces Parameters

Scripted SimpleObject Plug-ins

1557

spinner height Height type:#worldunits range:[-1000,1000,0] spinner width Width type:#worldunits range:[-1000,1000,0] spinner depth Depth type:#worldunits range:[-1000,1000,0]

) -on buildMesh do ( setMesh mesh \ verts:#([0,0,0],[width,0,0],[width,depth,0],[0,depth,0]) \ faces:#([3,2,1], [1,4,3]) extrudeFace mesh #(1,2) (height * 0.5) 40 dir:#common extrudeFace mesh #(1,2) (height * 0.5) 50 dir:#common ) -tool create ( on mousePoint click do case click of ( 1: nodeTM.translation = gridPoint 3: #stop ) on mouseMove click do case click of ( 2: (width = gridDist.x; depth = gridDist.y) 3: height = gridDist.z ) ) )

In this script a new primitive called Tower is defined. It constructs a (very) simple tower form; the first drag sets the base and the second drag sets the height. It contains three animatable rollout parameters, height, width and depth, that set the objects basic bounds. The key components here are the create tool and the on buildMesh handler and they work together in a fairly simple way. The create tool sets the values of the parameters and the on buildMesh handler constructs a mesh based on those parameter values. The create tool can also access and set the position of the node that is being created to contain the new object through the Matrix3 value in the pre-defined mouse tool local variable nodeTM. In this case, the position portion of the nodes TM is set to the initial mouse down world position. The on mouseMove handler sets the width and depth during click 2 and the height during click 3. The on buildMesh handler constructs the desired mesh in the TriMesh value in the pre-defined plug-in local variable mesh. Typically, it does this by building the mesh from scratch each time the handler is called. In the example above, the mesh is initially set to a simple, two-face rectangular plane (via setMesh()) and then the 2 faces are extruded up and scaled-down twice to get the simple tower. The mesh plug-in local variable is accessible in any of the plug-ins handlers, but is typically only built in the on buildMesh handler. You can either modify the existing TriMesh value in place using the TriMesh methods, or construct a new TriMesh value and assign it to the mesh plug-in local variable. The TriMesh created must be valid or a 3ds max crash may occur. All face, vertex, material ID, and texture vertex arrays allocated must be filled in the handler.

1558

Chapter 12

Creating MAXScript Tools

There are three additional event handlers that may be implemented for a scripted SimpleObject:
on OKtoDisplay do <boolean_expr>

If the OKtoDisplay event handler is implemented, <boolean_expr> should return true or false depending on whether it is OK to display the current mesh. This is useful in situations where a mesh might be in some degenerate state for particular parameter settings and so should not be displayed in the viewports. The default implementation is true. Note, empty meshes are OK to display.
on hasUVW do <boolean_expr>

If the hasUVW event handler is implemented, <boolean_expr> should return true or false depending on whether UVW coordinates are present on the mesh. In many primitive objects, a Generate Mapping Coords checkbox is provided for the user to control UVW coordinate generation and the hasUVW handler expression would return the state of this checkbox. The default implementation returns true or false depending on whether the mesh has texture vertices present or not. At present, only a single map channel is supported.
on setGenUVW <onOff> do <expr>

The setGenUVW event handler is called when 3ds max wants the plug-in to automatically generate mapping coordinates, as happens when you first render an object that has a material applied, but not mapping coordinates. It is called with a switch argument <onOff> which is true or false to turn on or off the mapping coordinates. If your plugin is managing mapping coordinates, it should implement this handler and generate mapping coordinates when called with a true argument. For example:
on setGenUVW onOff do ( genMapCoords = onOff if genMapCoords and gen_mapping_coords() )

where gen_mapping_coords() is a function that applies mapping coordinates to the mesh, returning true if the mapping was successful, false if not. Heres another example that creates a mesh by first building other temporary objects and using mesh booleans to build the final mesh: Script:
plugin simpleObject squareTube name:SquareTube classID:#(63445,55332) category:Scripted Primitives ( local box1, box2 -parameters main rollout:params ( length type:#worldUnits ui:length default:1E-3 width type:#worldUnits ui:width default:1E-3 height type:#worldUnits ui:height default:1E-3 ) --

Scripted SimpleObject Plug-ins

1559

rollout params SquareTube ( spinner height Height type:#worldUnits range:[1E-3,1E9,1E-3] spinner width Width type:#worldUnits range:[1E-3,1E9,1E-3] spinner length Length type:#worldUnits range:[-1E9,1E9,1E-3] ) -on buildMesh do ( if box1 == undefined then (box1 = createInstance box; box2 = createInstance box) box1.height = height; box2.height = height box1.width = width; box2.width = width * 2 box1.length = length; box2.length = length * 2 mesh = box2.mesh - box1.mesh ) -tool create ( on mousePoint click do case click of ( 1: nodeTM.translation = gridPoint 3: #stop ) on mouseMove click do case click of ( 2: (width = abs gridDist.x; length = abs gridDist.y) 3: height = gridDist.z ) ) )

In this example, the parameters and rollouts are handled in a similar manner to the first example, but the buildMesh handler generates the mesh in an indirect way. The final object is in the form of a rectangular pipe, a box with a box hole through the middle. Two plug-in locals (box1 and box2) are made to contain Box base objects whose size parameters are set according to the plug-ins parameters, box2 is the outer box, box1 is the hole. The final mesh is made by boolean subtraction of box1 from box2. In this case, a separate new mesh is created and assigned to the mesh plug-in local variable, in contrast to the first example which modified the objects original mesh directly. Either technique is OK. The createInstance() method is used to directly create the box base objects. This method creates the geometry associated with the specified object, but does not create a node. This method is used since SimpleObject plug-in must not perform any scene related actions such as creating scene nodes or building modifier stacks.

1560

Chapter 12

Creating MAXScript Tools

See also
Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)

Scripted Shape Plug-ins

Scripted Shape plug-ins can only extend existing Shape plug-ins. A scripted Shape plug-in is declared by specifying the <superclass> as shape. If a create tool is specified, it will override the delegates create tool. Script:
plugin shape Extended_Rect name:Rectangle2 classID:#(0x133067, 0x54375) extends:rectangle version:1 category:Splines ( fn fmax val1 val2 = if val1 > val2 then val1 else val2 tool create ( local startPoint on mousePoint click do case click of ( 1: startPoint = nodeTM.translation = gridPoint 3: #stop ) -on mouseMove click do case click of ( 2: ( delegate.width= abs gridDist.x delegate.length= abs gridDist.y nodeTM.translation = startpoint + gridDist/2. ) 3: delegate.corner_radius = fmax 0 -gridDist.x ) ) )

See also
Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)

Scripted Light Plug-ins

1561

Scripted Light Plug-ins

Scripted Light plug-ins can only extend existing Light plug-ins. A scripted Light plug-in is declared by specifying the <superclass> as light. If a create tool is specified, it will override the delegates create tool. Current limitations prevent certain plug-ins from being extended, in particular those with custom creation managers. These include target light plug-ins. You can tell if a plug-in is not extendable if your new rollouts do not appear. An example of a scripted Light plug-in is shown in the Three Lights example in the Scripted Plug-in Methods (p. 1551) topic.

See also
Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)

Scripted Helper Plug-ins

Scripted Helper plug-ins can only extend existing Helper plug-ins. A scripted Helper plug-in is declared by specifying the <superclass> as helper. If a create tool is specified, it will override the delegates create tool. An example of a scripted Helper plug-in is shown in the Three Lights example in the Scripted Plug-in Methods (p. 1551) topic.

See also
Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)

1562

Chapter 12

Creating MAXScript Tools

Scripted Modifier Plug-ins

Scripted Modifier plug-ins can only extend existing Modifier plug-ins. A scripted Modifier plug-in is declared by specifying the <superclass> as modifier. The Modify panel actually creates a fresh instance of every modifier when it is to be shown in the More... list or the buttons in the Modifiers rollout. This will cause the create handler to be called for a scripted Modifier plug-in. No special handling in the create handler is required for this case. Script:
plugin modifier myMod name:Supa Mod classID:#(685325,452281) extends:Bend replaceUI:true version:1 ( parameters main rollout:params ( bendamt type:#float animatable:true ui:bendamt default:0.0 on bendamt set val do delegate.angle = val ) -rollout params SupaCheka Parameters ( spinner bendamt Bendiness: ) )

Script:
plugin modifier NSpline name:Normal. Spline classID:#(0x133067, 0x54374) extends:normalize_spline replaceUI:true version:1 ( parameters main rollout:params ( seglen type:#float animatable:true ui:seglen default:20 on seglen set val do delegate.length = val ) -rollout params Parameters ( spinner seglen Seg Length: range:[0.01,1e9,20] ) )

See also
Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)

Scripted SimpleMod Plug-ins

1563

Scripted SimpleMod Plug-ins

A SimpleMod plug-in is a deformation-type modifier that moves vertices around but does not change topology (adding or deleting vertices, faces, surfaces, lines, etc.) Examples of similar 3ds max modifiers are Bend, Stretch, and Taper. These kinds of modifiers require only a single map handler to be provided for moving vertices around and they automatically supply 3D box deformation gizmo and center sub-objects. A scripted Modifier plug-in is declared by specifying the <superclass> as modifier. Script:
plugin simpleMod saddle name:SaddleDeform classID:#(685325,452281) version:1 ( parameters main rollout:params ( amount type:#integer ui:amtSpin default:20 ) -rollout params Saddle Parameters ( spinner amtSpin Amount: type:#integer range:[0,1000,20] ) -on map i p do ( p.z += amount * sin((p.x * 22.5/extent.x) * (p.y * 22.5/extent.y)) p ) )

This script defines a new SimpleMod plug-in named SaddleDeform. It applies a saddle-type deformation to an object, curving up 2 opposite corners and curving down the other two opposite corners (try it on a plane object to see this best). There is a single parameter spinner, amount that specifies how much deformation to apply. The key component of a SimpleMod plug-in is the map handler. Its form is:
on map <index> <point> do <expr>

This event handler is called once for every point in the object (or current point selection in the object) being modified. These points may be mesh vertices, spline vertices, NURBS CVs, and so on. The <index> argument gives the number of the point, but this index may not correspond to a vertex number in a mesh or a spline. The <point> argument supplied to the map handler gives the current object-space coordinates of the point as a Point3. The function should modify the supplied point value as appropriate and return it as the result of the map handler call. In the example above, the map handler applies a Z-coordinate deformation, using the equation z = sin(x * y), so that all the points retain their X and Y coordinates and the Z is moved up or down so as to follow the saddle function. Note that all coordinates are object-local. The <index> value is 1-based, however the scripted plug-in is called with a <index> value of 0 to signal that this particular map call is being used by the gizmo bounding box drawing code to compute points in the gizmo box to draw. This occurs hit testing is performed on the object the

1564

Chapter 12

Creating MAXScript Tools

SimpleMod modifier is applied to and the gizmo bounding box is displayed. This will be the case if the object is selected, the Modifier panel is active, and the SimpleMod modifier is selected in the objects modifier stack. It is basically up to the object being modified to decide what index value to pass. For meshes, for example, it is the actual mesh vertex index. For patches, it is the control points first all in one sequence, followed by the in and out vectors for each control point in control point order. For splines, it is control point, in vector, out vector in control point sequence within the curve sequence. This ordering may change in future versions of 3ds max. Since the map handler can be called many times, even on simple objects, it is highly recommended that you minimize the number of values that are created in the map handler. This will reduce the need for garbage collection to be run. If you need several local variables in the map handler, it is recommended that you declare one or more Point2 or Point3 values in the scripted plug-in definition, and then store values to the component values of the Point2 or Point3 values. This will prevent new local variables from being allocated in the map handler. You should not try to access the object being modified from within the map handler as this will attempt to evaluate the scripted modifier again. This will result in an infinite loop and hang 3ds max. There are also three pre-defined plug-in locals you can access in the map handler, as follows:
min max center extent ----the the the the modifier modifier modifier modifier contexts contexts contexts contexts bounding bounding bounding bounding box box box box min coordinate max coordinate center coordinate extent or size

In the example above, the map handler use the extent pre-defined local variable to compute a scaling for the saddle function, so that it gets a 1/8th cycle of the function (22.5 degrees) across the whole object. These bounding box locals relate to the modifiers context, either the whole object or group of objects if applied to a scene node selection, or sub-object selection if there is a sub-object selection modifier below it on the stack (such as a Mesh Select). You can also use some other built-in capabilities of SimpleMod to implement modifier limits as in Bend and Taper. To do this, implement handlers for the following (you must implement all if you implement any):
on modLimitZMin do <expr> on modLimitZMax do <expr> on modLimitAxis do <expr>

If called, the on modLimitZMin and on modLimitZMax handler expressions must evaluate to float values corresponding to the minimum and maximum limits and the on modLimitAxis handler expression must return #x, #y or #z to specify the limit axis. The MAXScript global variable currentTime contains the time at which these values should be computed, although, normally, simple access to parameter values will yield the correct currentTime value automatically. The simplest way to implement these handlers is to maintain limit parameters and associated spinners and checkboxes, and simply pass these parameter values back.

Scripted Material Plug-ins

1565

The Modify panel actually creates a fresh instance of every modifier when it is to be shown in the More... list or the buttons in the Modifiers rollout. This will cause the create handler to be called for a scripted SimpleMod plug-in. No special handling in the create handler is required for this case.

See also
Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)

Scripted Material Plug-ins

Scripted Material plug-ins can only extend existing Material plug-ins. A scriptable Material plug-in is declared by specifying the <superclass> as material. A scripted Material plug-in must have at least one rollout defined. In a scripted Material plug-in, Material and Map buttons that are associated with a parameter in a parameter block do not call the buttons picked event handler. Instead, you should link the button to a parameter in a parameter block, and use the set handler for the parameter. Script:
-- this is a level 3 plug-in, the beginnings of a custom glass material. -- It extends Standard material and replaces its UI with a single -- rollout with 2 spinners and a color picker plugin material myGlass name:Supa Glass classID:#(695425,446581) extends:Standard replaceUI:true version:1 ( parameters main rollout:params ( trans type:#float default:27 ui:trans refrac type:#float default:1.5 ui:refrac col type:#color default:blue ui:col -on trans set val do delegate.opacity = val on refrac set val do delegate.ior = val on col set val do delegate.diffuse_color = val ) -rollout params Glass Parameters ( spinner trans Transparency: fieldwidth:45 offset:[-90,0] spinner refrac Index of Refraction: fieldwidth:45 offset:[-90,0] colorpicker col Base color: align:#center ) -on create do

1566

Chapter 12

Creating MAXScript Tools

( ) )

-- setup initial material delegate.opacityFalloff = 75

See also
Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)

Scripted TextureMap Plug-ins

Scripted TextureMap plug-ins can only extend existing TextureMap plug-ins. A scriptable TextureMap plug-in is declared by specifying the <superclass> as textureMap. A scripted TextureMap plug-in must have at least one rollout defined. In a scripted TextureMap plug-in, Material and Map buttons that are associated with a parameter in a parameter block do not call the buttons picked event handler. Instead, you should link the button to a parameter in a parameter block, and use the set handler for the parameter.

See also
Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)

Scripted RenderEffect Plug-ins

A scriptable RenderEffect plug-in can be declared by specifying the <superclass> as RenderEffect and by declaring an apply event handler. When declared, the render effect can be seen in Render Effects > Add dialog.
on apply <bitmap> do <expr>

When the scripted effect is added as one of the rendering effects and Update Scene or Update Effect buttons are pressed, the apply event handler is called and passed a bitmap which can be modified with any changes the render effect wants to make. The bitmap you are given is the current rendered image that has had all of the prior effects in the render effects list applied to it. You modify this bitmap in place, typically by using the

Scripted RenderEffect Plug-ins

1567

getPixel() and setPixel() functions. This modified bitmap is then passed onto the next render effect in the list or to the render output if it is the last effect. To allow scripted Effects to take advantage of the g-buffer channel access, the following handlers are present:
on channelsRequired do <expr>

The handler expression must evaluate to an array of the g-buffer channel names that are required. The g-buffer channel names are:
#zDepth #matID #objectID #UVCoords #normal #unClamped #coverage #node #shaderColor #shaderTransparency #velocity #weight on preApply <bitmap> do <expr>

The preApply handler allows the scripted effect to analyze the incoming render bitmap and its channels in order to precondition the delegates effect processing. So, you might add an on channelsRequired do to add #node and #coverage channels to the renderers bitmap, and an on preApply bm do to get the #node channel out as a mask and then set it into a delegates mask parameter to limit an effect to a given object. You cannot call render() in a scriptable RenderEffect plug-in, as this would cause the RenderEffect to be recursively called. Heres a simple example that extends the Blur effect to add another rollout that has a node picker button. If you pick a node it generates a channel mask and uses that to limit the blur to that object: Script:
plugin RenderEffect myBlurFX name:Super Blur FX classID:#(6545,456581) extends:Blur version:1 ( local tx = bitmaptexture (), cm, g_channels = #(#node, #coverage) rollout params SupaFX Parameters ( label nn align:#center pickbutton nodepick Pick Node ) -parameters main rollout:params ( thenode type:#node ui:nodepick on thenode set nd do params.nn.text = if nd == undefined then else nd.name

1568

Chapter 12

Creating MAXScript Tools

) -on channelsRequired do g_channels -on preApply map do if theNode != undefined then ( if cm == undefined then ( cm = getChannelAsMask map #node node:theNode \ fileName:(scriptsPath + __fxtmp.bmp) save cm tx.bitmap = cm ) else getChannelAsMask map #node node:theNode to:cm ) -on create do ( delegate.selMaskActive = true delegate.selImageActive = false delegate.selMaskMap = tx ) )

Script:
plugin renderEffect myColorBalanceFx name:Super Color Balance FX classID:#(64425,45761) extends:Color_Balance version:1 ( parameters main rollout:params ( redness type:#integer animatable:true ui:redness default:0.0 on redness set val do delegate.red = val ) -rollout params Super Color Balance Parameters ( spinner redness Redness: type:#integer range:[-100,100,0] ) )

Script:
plugin renderEffect Negative name:Negative classID:#(0xb7aa794c, 0xc3bd78ab) ( parameters main rollout:params ( Color type:#color default:blue ui:Color ) -rollout params Negative Parameters ( colorpicker Color Base color: align:#center ) -on apply bmp do ( for h=0 to (bmp.height-1) do

Scripted Atmospheric Plug-ins

1569

local sline = getPixels bmp [0,h] bmp.width for i=1 to sline.count do sline[i] = Color - sline[i] setPixels bmp [0,h] sline

) ) )

See also
Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)

Scripted Atmospheric Plug-ins

Scripted Atmospheric plug-ins can only extend existing Atmospheric plug-ins. A scriptable Atmospheric plug-in is declared by specifying the <superclass> as atmospheric. Script:
plugin atmospheric myFogEnv name:Super Fog Env classID:#(64433,27761) extends:Fog version:1 replaceUI:true ( parameters main rollout:params ( fogcol type:#color animatable:true ui:col on fogcol set val do delegate.fog_color = val ) -rollout params Super Fog Parameters ( colorpicker col Fog Color ) -on create do delegate.fog_type = 1 )

See also
Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)

1570

Chapter 12

Creating MAXScript Tools

Chapter 13:

Interacting with the 3ds max User Interface

Command Panels
The following methods are used to get or set which command panel is active:
setCommandPanelTaskMode mode:<panel_name>

Sets the specified command panel as active. The valid panel_name values are:
#create #modify #hierarchy #motion #display #utility ------Create Panel Modify Panel Hierarchy Panel Motion Panel Display Panel Utility Panel

getCommandPanelTaskMode()

Returns the current command panel as a name value. The name values correspond to the panel_name values for SetCommandPanelTaskMode(). The following 3ds max system global variables are associated with the command panel:
cui.commandPanelOpen

Lets you get and set whether the command panel is displayed. A Boolean value - true if the command panel is displayed, false if not displayed. This global variable is not available in 3ds max. Specific methods and 3ds max global variables are associated with the Create and Modify panels. These methods and global variables are described in the following topics: Create Panel (p. 1572) Modify Panel (p. 1572)

1572

Chapter 13

Interacting with the 3ds max User Interface

Create Panel
The startObjectCreation() method is used to simulate the user finding a Create Panel button for a given object class and pressing that button, putting 3ds max into create mode for that object class. The form is:
startObjectCreation <scene_object_class>

For example:
startObjectCreation box startObjectCreation targetSpot

This method simply opens up the Create Panel at the right tab and category and depresses the appropriate object button. This method is primarily intended for use in macroScripts, but can be used in generalized scripts. Script execution will continue immediately after entering the create mode, and you must ensure that the script does not interfere with the object creation.

Modify Panel
The following methods are associated with the Modify panel:
enableShowEndRes <boolean>

If the boolean parameter is true, allows the Show End Result On/Off Toggle icon to remain pressed in. If false, the Show End Result On/Off Toggle icon will return to the off state after being pressed. This method must be used in true/false pairs, as its effect is sticky when selecting other objects or modifiers, or when switching away from and back to the Modify panel.
IsSubSelEnabled()

Returns true if the user is allowed to enter Sub-Object mode, false otherwise.
enableSubObjSel <boolean>

If the boolean parameter is true, allows the user to enter Sub-Object mode for those objects/modifiers that have Sub-Object modes defined. If false, the Sub-Object button is disabled. This method must be used in true/false pairs, as its effect is sticky when selecting other objects or modifiers, or when switching away from and back to the Modify panel.
modPanel.addModToSelection <modifier>

Applies a modifier to the current selection opened in the Modify panel. It should be used in place of addModifier() in places where the target is a selection or group or where you have the stack open at a particular place in the Modify panel with a sub-object selection active and you want the modifier applied to that selection. addModifier() adds the modifier separately to each object in the selection or group and does not honor the current active sub-object selection in all cases. The Modify panel must be open on the selection you want to apply the modifier to, otherwise the function does nothing.

Modify Panel

1573

modPanel.getCurrentObject()

Returns the modifier or base object currently selected in the Modify panel stack. If the Modify panel is not open, this function returns undefined.
modPanel.getModifierIndex <node> <modifier>

Returns the index of the given modifier in the modifier stack for the given node. This index corresponds to the modifiers position in the <node>.modifiers array. This function returns undefined if the given modifier is not in the nodes modifier stack.
modPanel.setCurrentObject < modifier | node | node_baseobject >

Sets the specified object in the current modifier stack to be the active object in the modifier stack. The Modify panel must be open on the object containing the modifier or base object to be selected, otherwise the function does nothing. Examples:
modPanel.addModToSelection (bend()) selection modPanel.getModifierIndex $ foo modPanel.setCurrentObject $ modPanel.setCurrentObject $.baseObject modPanel.setCurrentObject $.taper modPanel.setCurrentObject $.modifiers[3] modPanel.setCurrentObject foo -- apply bend modifier to current ------returns open on same as open on open on open on index of modifier foo base object above taper modifier in object 3rd modifier foo object or modifier

The following 3ds max system global variables are associated with the Modify panel:
numSubObjectLevels

Lets you get the number of sub-object levels supported by the object or modifier currently selected in the modifier stack. If the Modify panel is not open or no objects are selected, the global contains the value undefined.
subObjectLevel

Lets you get and set the sub-object level in the Modify panel if it is open. An Integer value of zero or greater up to the number of sub-object levels supported by the currently open modifier, typically in the order shown in the Sub-Object drop-down list. A subObjectLevel of 0 means sub-object mode is off. If the Modify panel is not open or sub-object level setting not permitted in the current modifier, the global contains the value undefined. For example:
b=box() em=edit_mesh() addModifier $box01 em max modify mode select $box01 print subObjectLevel subObjectLevel = 2 showEndResult -------create a box create an Edit Mesh modifier add edit mesh mod open mod panel select object box01 print the current subobject level set sub-object level to Edge

Lets you get and set the state of the Show End Result Toggle icon in the Modify panel. A Boolean Value true if Show End Result is on, false if off.

1574

Chapter 13

Interacting with the 3ds max User Interface

Main Toolbar
The following methods are associated with 3ds maxs main toolbar:
enableUndo <boolean>

Enables or disables the Undo icon.

hitByNameDlg()

Opens the standard 3ds max Select By Name dialog allowing users to select objects. Returns false if the user cancels out of the Select by Name dialog, true otherwise.
toolMode.uniformScale()

Set scale mode to Uniform Scale.

toolMode.nonUniformScale()

Set scale mode to Non-uniform Scale.

toolMode.squashScale()

Set scale mode to Squash.

enableRefCoordSys <boolean>

Enables or disables the Reference Coordinate System drop-down list.

toolMode.coordsys <mode_name>

Sets the Reference Coordinate System. Valid <mode_name> values are:

#view #screen #world #parent #local #grid getRefCoordSys() setRefCoordSys <mode_name>

Get and set the Reference Coordinate System. Valid <mode_name> values are:
#hybrid #screen #world #parent #local #object ------View Screen World Parent Local Pick object or Grid not valid for setRefCoordSys()

enableCoordCenter <boolean>

Enables or disables the Coordinate System Center icon.

getCoordCenter() setCoordCenter <name>

Get and set the Coordinate System Center. Valid <name> values are:
#local -- Use Pivot Point Center #selection -- Use Selection Center #system -- Use Transform Coordinate Center

Modify Panel

1575

toolMode.transformCenter()

Sets Coordinate System Center to Transform Coordinate System.

toolMode.selectionCenter()

Sets Coordinate System Center to Selection Center.

toolMode.pivotCenter()

Sets Coordinate System Center to Pivot Point Center.

getNumAxis()

This method reflects the Coordinate System Center state. If it is set to Pivot Point Center then this method returns #individual otherwise #all.
setToolBtnState <name> <boolean>

Set the specified tool buttons on or off. This method does not put into the mode, it just changes the state of the tool button. This method does not change the state of any button other than the specified button. The valid <name> values are:
#move #rotate #nuscale #uscale #squash #select ------Move button on/off Rotate button on/off Scale button on/off doesnt change scale type Scale button on/off doesnt change scale type Scale button on/off doesnt change scale type Select button on/off

getToolbtnState <name>

Returns whether the specified tool button is on or off as a <boolean> value. Valid name values are:
#select #move #rotate #uscale-- returns true if any of the scale button states is on #nuscale-- returns true if any of the scale button states is on #squash-- returns true if any of the scale button states is on

The following methods deal with the Named Selection Set drop-down list. These methods are not intended for casual usage.
clearCurSelSet()

Clears the edit field of the Named Selection Set drop-down list. Does not deselect the currently selected objects.
clearSubSelSets()

Clears the named selections from the Named Selection Set drop-down list. The named selection sets still exist, they just dont show in the drop-down list. This command can be dangerous to use unless you are in Sub-Object mode in the Modify panel, as there is not a direct method to rebuild the Named Selection Set list. When in Sub-Object mode in the Modify panel, the namedSelSetListChanged() method will rebuild the list.
namedSelSetListChanged()

When in Sub-Object mode in the Modify panel, this method will rebuild the named selection set list.

1576

Chapter 13

Interacting with the 3ds max User Interface

setCurNamedSelSet <string>

Sets the edit field of the Named Selection Set drop-down list to the specified string. This method not change the current selection set or add the specified string to the named selection set list.
appendSubSelSet <string>

Appends the specified string to the Named Selection Set drop-down list. This method not change the current selection set. Modifiers in 3ds max use this method to add sub-object named selection sets to the Named Selection Set drop-down list. This is done whenever the selection level changes. The following 3ds max system global variables are associated with the main toolbar:
preferences.constantReferenceSystem

Lets you get and set whether to use a constant Reference System for the Move, Rotate, and Scale tools. A Boolean value - true if Constant is on, false if off. This variable matches the Constant check box in Customize menu > Preferences > General > Reference Coordinate System.
toolmode.commandmode

Get/set the 3ds max command mode. The return value when getting the command mode is a <name> value if the command mode is a recognized command mode, otherwise the return value is an integer value. The recognized command modes are:
#SELECT #MOVE #ROTATE #NUSCALE #USCALE #SQUASH #VIEWPORT #HIERARCHY #CREATE #MODIFY #MOTION #ANIMATION #CAMERA #NULL #DISPLAY #SPOTLIGHT #PICK

When setting the 3ds max command mode, only the following command modes are valid:
#SELECT #MOVE #ROTATE #NUSCALE #USCALE #SQUASH

Prompt Line

1577

toolmode.axisConstraints

Get/set the 3ds max axis constraints. The axis constraints values are:
#X #Y #Z #XY #YZ #ZX

Status Bar
The methods and 3ds max global variables associated with 3ds maxs Status Bar are described in the following topics: Prompt Line (p. 1577) Coordinate Display (p. 1578) Progress Bar Display (p. 1578) Status Bar Buttons (p. 1579)

Prompt Line
The following methods are associated with 3ds maxs Status Bar Prompt Line:
displayTempPrompt <string> <milliseconds_integer>

Displays the specified string on the Prompt Line for the specified number of milliseconds. After the time elapses, the string is popped from the stack. This may be used to put up a temporary error message for example. Control is returned to MAXScript immediately after the call, that is, MAXScript execution continues even while the temporary prompt is displayed.
removeTempPrompt()

Removes the temporary prompt immediately.

replacePrompt()

Replaces the string on the top of the prompt stack.

pushPrompt <string>

Pushes the currently displayed prompt onto the prompt stack, and displays the specified string as the prompt.
popPrompt()

Pops the currently displayed prompt off the prompt stack. The previous prompt will be restored.

1578

Chapter 13

Interacting with the 3ds max User Interface

Coordinate Display
The following methods are associated with 3ds max s Status Bar Coordinate Display:
disableStatusXYZ()

Disables mouse tracking and display of coordinates to the X, Y, Z status boxes.

enableStatusXYZ()

Enables mouse tracking and display of coordinates to the X, Y, Z status boxes.

setStatusXYZ <format_name> <point3>

Displays the component values of the Point3 value in the X, Y, Z status boxes. The format of the displayed values is controlled by format_name. The valid format_name types are:
#universe

display point3 as position in current units

#scale

display point3 as percentages a point3 component value of 1 displays as 100%

#angle

display point3 as angles point3 component values are in radians

#other

display point3 as straight floating point values. Note: Using a <format_name> value of #other for setStatusXYZ() does not correctly display the specified point3 value. The X and Y component values are displayed in the Y and Z status boxes, and the X status box is blank.

Progress Bar Display

This group of functions let you display a progress bar for operations that may be time consuming, similar to the progress bar 3ds max uses for IK, Preview Rendering and Reduce Key computations. The functions are:
progressStart caption

Initially displays the progress bar with the caption given.

progressUpdate <percent>

Updates the bar display to show the given percentage complete (in the range 0-100). This function also checks to see if the user has clicked the Cancel button in the progress bar and returns true if the computation should continue and false if the user has requested a cancel. You can also call getProgressCancel(), described below, to check the cancel status, which is a low overhead function and so may be called more frequently than progressUpdate().
progressEnd()

Signals the end of the operation and removes the progress bar display.

Status Bar Buttons

1579

getProgressCancel()

A low-overhead function that checks whether the user has canceled the operation via the Cancel button in the progress bar. You may want to call this function frequently within deep loops in your code to reduce cancel latency for the user, because you should only call progressUpdate() as needed to show significant progress bar changes to keep overhead low. The getProgressCancel() function, as well as progressUpdate(), displays a confirmation dialog if the use hits the cancel button and returns the cancel status from that confirmation. Unlike progressUpdate(), this function returns true if the user has made a confirmed cancel request and false otherwise.
setProgressCancel <boolean>

Sets or clears the Cancel flag for the progress bar. By passing a value of true, the Cancel flag is set and will be detected by progressUpdate() and getProgressCancel(). By passing a value of false, the Cancel flag is cleared if set. The following 3ds max system global variable is associated with the Progress Bar display:
escapeEnable

Lets you get and set a Boolean value defining whether ESC key interrupt detection is on or off. Setting enableEscape to false turns ESC key interrupt detection off, setting it to true turns it on again. This variable is useful when used in conjunction with a Progress Bar. You can set enableEscape to false when you dont want the user to be able to interrupt a script running a long computation and you have set up a progress bar with its own Cancel button.

Status Bar Buttons

The following methods are associated with the buttons in 3ds maxs Status Bar:
getCrossing()

Returns whether Crossing Selection (true) or Window Selection (false) is set.

getPluginKeysEnabled() setPluginKeysEnabled <boolean>

Get and set whether Plug-in Keyboard Shortcuts are enabled (true) or disabled (false).
getSnapState()

Returns the Snap toggle state - on (true) or off (false).

getSnapMode()

Returns the current snap type as a string ABSOLUTE or RELATIVE.

isSelectionFrozen()

Returns true if the node selection is frozen, false if not frozen

freezeSelection()

Freezes the node selection

thawSelection()

Thaws the node selection.

1580

Chapter 13

Interacting with the 3ds max User Interface

The following 3ds max system global variables are associated with the Status Bar buttons. These global variables are not available in 3ds max.
snapMode.active

Lets you get and set a Boolean value defining the Snap toggle state - on (true) or off (false). This global variable is not available in 3ds max.
snapMode.type

Lets you get and set a Name value defining whether 2D (#2D), 2.5D (#2_5D), or 3D (#3D) is the current snap type. This global variable is not available in 3ds max.

Time Control
The following methods and 3ds max system global variables are associated with the 3ds max Time Controls:
animButtonEnabled

A Boolean value that specifies whether the user can change the state of the Animate button. If set to false, the user can not change the Animate button state. If set to true, the user can change the Animate button state. A script can change the state of the Animate button using animButtonState regardless of the animButtonEnabled value.
animButtonState

Lets you to get and set the state of the Animate button. A Boolean value - true if Animate is on, false if Animate is off.
sliderTime

Lets you get and set a Time value that defines the time associated with the 3ds max time slider. Two functions are provided for starting and stopping the 3ds max animation playback, which are essentially equivalent to pressing the Play button in the 3ds max user interface. The functions are:
playAnimation [ #selOnly ] stopAnimation()

If you specify the optional argument, #selOnly, to playAnimation()only the currently selected objects are animated. There is an important restriction to understand when using these functions: Calling playAnimation() is a thread-blocking call internally in 3ds max and does not return until the playback is stopped by the user clicking the Stop Play button or another thread executing a stopAnimation(). The only way to achieve the latter in MAXScript currently is to call stopAnimation() from a scripted rollout panel handler such as a button press handler or from a scripted controller script. If you invoke playAnimation() in code run from the Listener, you will not be able to invoke stopAnimation() from the Listener, because the Listener is blocked inside the playAnimation() call. Also see the Time Configuration Dialog (p. 1616) topic for methods for setting options in the Time Configuration dialog.

Accessing Active Viewport Info, Type, and Transforms

1581

Trackbar
The following methods are associated with the Trackbar:
trackbar.getPreviousKeyTime()

gets the previous key time. If no previous key is present, returns undefined. For example:
at time sliderTime trackbar.getPreviousKeyTime() trackbar.getNextKeyTime()

gets the next key time. If no next key is present, returns undefined. The following 3ds max system global variables are associated with the Trackbar:
trackbar.filter Name

get and set the filter specifying which types of keys to show in the Trackbar. The valid values are: #all, #TMOnly, #currentTM, #object, and #mat.
trackbar.visible Boolean

get and set whether the trackbar is visible - true if the trackbar is visible, false if invisible

Viewports
Accessing Active Viewport Info, Type, and Transforms
The following 3ds max system global variables are associated with the viewports:
viewport.activeViewport

Lets you get and set the index of the active viewport. If you change the currently active viewport to a 2D view, this variable will contain the value 0.
viewport.numViews

Contains the number of 3D viewports in the current viewport layout. This variable is readonly. This variable does not reflect any 2D (Track View, Schematic View, Listener, and so on) views in the viewport layout. So, for example, if viewport.getLayout() returns #layout_4 and this variable contains the value 2, you know that two of the viewports contain 2D views. MAXScript currently does not allow you to access 2D view viewports. The following methods are used to access active viewport information and transforms:
viewport.getLayout() viewport.setLayout <view_layout_name>

Gets or sets the viewport layout, where <view_layout_name> specifies the viewport layout configuration. When setting the layout, the view shown in each viewport is based on the configuration set in Customize > Viewport Configuration > Layout. The list of valid <view_layout_name> values below uses the following syntax:
# is the total number of viewports. V = vertical split H = horizontal split L/R = left/right placement T/B = top/bottom placement

1582

Chapter 13

Interacting with the 3ds max User Interface

The valid <view_layout_name> values are:

#layout_1 #layout_2v #layout_2h #layout_2ht #layout_2hb #layout_3vl #layout_3vr #layout_3ht #layout_3hb #layout_4 #layout_4vl #layout_4vr #layout_4ht #layout_4hb ------------1 2 2 2 2 3 3 3 3 4 4 4 4 4 viewport viewports, viewports, viewports, viewports, viewports, viewports, viewports, viewports, viewports, viewports, viewports, viewports, viewports, vertical split, both same size horizontal split, both same size horizontal split, top smaller horizontal split, top larger 2 on left, 1 on right 1 on left, 2 on right 2 on top, 1 on bottom 1 on top, 2 on bottom all same size 3 on left, 1 on right 1 on left, 3 on right 3 on top, 1 on bottom 1 on top, 3 on bottom

viewport.getType() viewport.setType <name>

Get and set the view type for the current viewport. Valid <name> values are:
#view_top #view_bottom #view_right #view_left #view_front #view_back #view_persp_user #view_iso_user #view_camera #view_spot #view_shape #view_track #view_grid -------------Top Bottom Right Left Front Back Perspective User Camera Light Shape Track View Grid

Notes: If the current viewport is an extended viewport (that is, a Track View, Asset Manager, or MAXScript Listener viewport), getType() will return undefined. If a Camera or Light viewport is specified with setType(), and there is not exactly one camera or light selected, a dialog will be displayed for the user to select the camera or light to use. viewport.setType returns a boolean - true if successful, false if not. Can also get a return value of #view_none. If none of the viewports have focus, a value of false is returned from viewport.getType.

Accessing Active Viewport Info, Type, and Transforms

1583

Example:
viewport.setType #view_track -- no viewport is active after this command viewport.getType() - will return false viewport.ResetAllViews()

This function will reset all viewports in Max to the default layout.
getActiveCamera() viewport.getCamera()

Returns the camera node associated with the active view if any, undefined if none.
viewport.setCamera <camera_node>

Sets the active viewport to a Camera view, using the specified camera.
getViewTM() viewport.getTM() viewport.setTM <matrix3>

Get or set the active view screen-to-world transform matrix for non-orthographic (perspective and isometric user views) viewports. This is the affine camera or viewport matrix. setTM only operates on Perspective viewports, and returns a value of true if the view transform matrix was successfully set, false otherwise. The following function returns as a Ray value the eye location and direction for the active viewport. The viewport needs to be a non-orthographic viewport. Script:
fn getViewDirectionRay = ( -- The affine TM transforms from world coords to view coords -- so we need the inverse of this matrix local coordSysTM = Inverse(getViewTM()) -- The Z axis of this matrix is the view direction. local viewDir = -coordSysTM.row3 -- get the view position from this matrix local viewPt = coordSysTM.row4 return ray viewPt viewDir ) getViewFOV()

Returns the Field of View for the active viewport. If the viewport is an orthographic viewport, a value of 57.2958 degrees (1 radian) is returned.
getViewSize()

Returns the active view size as point2 in pixels.

getScreenScaleFactor <point3>

Returns the active view scale factor, giving the width in world-space units at the points distance from the view space origin.
mapScreenToWorldRay <pixel_coord_point2>

Returns a Ray value in world space through the given viewport pixel coordinates in the current active view, and perpendicular to the viewport plane.

1584

Chapter 13

Interacting with the 3ds max User Interface

mapScreenToView <pixel_coord_point2> <depth_float> \ [ <viewport_size_point2> ]

Returns a 3D point in the view coordinate space. Given a point in the active viewport screen (in viewport pixel coordinates), and a depth in view coordinates, this method maps the point into view coordinates. If <viewport_size_point2> is supplied, the specified viewport size is used instead of the actual viewport size.
mapScreenToCP <pixel_coord_point2> [ <viewport_size_point2> ]

Maps viewport pixel coordinates in the current active view to the construction plane in world coordinates. If <viewport_size_point2> is supplied, the specified viewport size is used instead of the actual viewport size.
getCPTM()

Construction-plane-to-world transform matrix.

gw.nonScalingObjectSize()

The value returned from this method may be used as a scale factor that will counteract the viewport zoom. For example, lights, cameras, and tape helper objects use this factor so the size of the node in the scene remains constant when the viewport is zoomed in and out. This value is affected by the Non-Scaling Object Size spinner in the Viewport Preferences dialog, so the user has some control over this as well.
gw.getPointOnCP <pixel_coord_point2>

Returns a point in world space on the current construction plane based on the specified screen coordinate.
gw.getCPDisp <base_point3> <dir_point3> \ <start_pixel_coord_point2> <end_pixel_coord_point2>

This method returns a length in world space given a start screen point (<start_pixel_coord_point2>), an end screen point (<end_pixel_coord_point2>), a base point (<base_point3>) and a direction vector (<dir_point3>). For example, when creating a cylinder, the user clicks the mouse down to define the center point of the cylinder (base), then drags out a radius. They then drag out a height for the cylinder. This method is used to return intermediate and final heights for the cylinder based on the initial base point, the direction vector (the Z axis), the start mouse point, and the current point the user is interactively adjusting.
gw.getVPWorldWidth <point3>

Returns the viewport screen width factor in world space at a point in world space.
gw.mapCPToWorld <point3>

Returns the corresponding world space point given a point on the construction plane. For example, if you use gw.getPointOnCP() to convert a screen coordinate to a point on the construction plane, you could then call this method to convert that point on the construction plane to a world space point.
gw.IsPerspView()

Returns true if the active viewport is a perspective view; otherwise returns false.
gw.getFocalDist()

Returns the focal distance of an active perspective view.

Accessing Active Viewport Info, Type, and Transforms

1585

gw.snapPoint <pixel_coord_point2> [ snapType:<snapType_name> ]

Given a 2D screen coordinate, this method returns a 3D point on the current construction plane based on the current snap settings and the optional snapType parameter. The valid <snapType_name> values are:
#in3d

Snap to all points.

#inPlane

Snap only to points on the construction plane.

#unSelObjs

Ignore selected nodes when considering snap points.

#selObjs

Ignore unselected nodes when considering snap points.

#unSelSubobj

Ignore selected sub-object geometry when considering snap points.

#selSubobj

Ignore unselected sub-object geometry when considering snap points.

#force3d

Override user settings to force snap in 3D.

gw.snapLength <length_float>

This method snaps the length to the nearest snap increment and returns the snapped distance.
units.formatValue <float>

Returns a <string> value representing the <float> in the current unit scale. This method can cause a string overflow, especially when the units are set to miles or kilometers. If an overflow occurs a run-time error is thrown.
units.decodeValue <string>

Parses <string> using the current unit settings and returns a <float>. A run-time error is thrown if an error occurs in the parsing of the string. Refreshing the Viewports The following methods force the viewports to redraw, or control when the viewports are redrawn.
redrawViews()

Causes the 3ds max viewports to be immediately redrawn in an optimal way, such that only those parts of the view that have changed are redrawn. This is different from forcing a redraw with the max view redraw command or one of the following methods which redraw the entire scene in all views.

1586

Chapter 13

Interacting with the 3ds max User Interface

completeRedraw() forceCompleteRedraw [ doDisabled:<boolean> ]

Calling this method will cause all the viewports to be completely redrawn. This method literally forces everything (every object, every screen rectangle, every view) to be marked invalid and then the whole scene is regenerated. The individual object pipeline caches are not flushed, however. This routine is guaranteed to be slow. If the optional doDisabled: boolean argument for ForceCompleteRedraw is true, disabled viewports will also be redrawn.
disableSceneRedraw()

Turns viewport scene redraw off (disables it). All calls to DisableSceneRedraw()/ EnableSceneRedraw() must be in pairs, since an internal counter is used in 3ds max to actually do the redraw enable/disable action.
enableSceneRedraw()

Turns viewport scene redraw on (enables it). All calls to DisableSceneRedraw()/ EnableSceneRedraw() must be in pairs, since an internal counter is used in 3ds max to actually do the redraw enable/disable action.
isSceneRedrawDisabled()

Returns true if scene redraw is disabled, false if it is enabled.

nodeInvalRect <node>

Invalidates the rectangle in the viewports that the node is occupying. Rectangles flagged as invalid will be updated on the next screen redraw.

Viewport Background Images

The following methods provide access to the values in the Viewport Background dialog.
getBkgFrameNum <time>

Returns the viewport background image frame displayed at the specified time. Returns a value of 1 if no frame is to be used for specified time.
getBkgImageAnimate() setBkgImageAnimate <boolean>

Get and set whether Animate Background is on (true), or off (false).

getBkgImageAspect() setBkgImageAspect <name>

Get and set the background image Aspect Ratio option. Valid <name> values are:
#view #bitmap #output -- Match Viewport -- Match Bitmap -- Match Rendering Output

Viewport Grids

1587

getBkgORType <start_end_integer> setBkgORType <start_end_integer> <name>

Get and set the background image Start Processing and End Procession options. <start_end_integer> = 0 Start Processing; 1 End Processing Valid <name> values are:
#blank -- Blank Before Start/After End #hold -- Hold Before Start/After End #loop -- Loop After End getBkgRangeVal()

Get the background image Use Frame range as a Point2 value. The first component of the Point2 value is the Start Frame, the second component is the End Frame.
setBkgFrameRange <point3>

Set the background image Use Frame range and step value. First component of <point3> is Start Frame, second component is End Frame, and third component is Step Frame.
getBkgStartTime() setBkgStartTime <time>

Get and set the background image Start At frame.

getBkgSyncFrame() setBkgSyncFrame <integer>

Get and set the background image Synch Start To Frame frame. The following 3ds max system global variable is associated with the Viewport Background dialog:
backgroundImageFileName

Lets you get and set a String value that defines the viewport background image bitmap file name. It contains the corresponding bitmap file name set in the Viewport Background dialog.

Viewport Grids
The following methods control the display and spacing of grid lines in the viewports.
getGridSpacing()

Returns the spacing between grid lines in units.

getGridMajorLines()

Returns the number of grid lines between major grid lines. The following 3ds max system global variable is associated with the Viewport grids:
activeGrid

Contains the currently active grid. If the home grid is active, returns the value undefined. You can assign a grid node object to this variable to make it the currently active grid.

1588

Chapter 13

Interacting with the 3ds max User Interface

Mouse Cursors
The following methods control the mouse cursor.
setWaitCursor() setArrowCursor()

These functions can be used to display the system wait cursor during some prolonged computation and then replace it with the normal cursor. You might want to do this instead of putting up a 3ds max progress bar, which may be too heavy-weight in some situations. Note that in some cases, 3ds max may itself restore the arrow cursor underneath this one (for example, with loadMAXFile()), and you may need to redisplay it after such calls.
setSysCur <name>

Sets the current system cursor to one of the standard 3ds max cursors. Valid <name> values are:
#move #rotate #uscale #nuscale #squash #select #arrow

Note: setSysCur #squash shows the non-uniform scale cursor. The following 3ds max system global variables are associated with the mouse:
mouse.mode

A read only variable to get the mouse mode as an <integer> value. Return values are: 0 Idle; 1 - Point; 2 - Move
mouse.buttonStates

A read only variable to get the state of the mouse buttons as a 3 element <bitArray>. The order of the bits is: #{Left, Middle, Right} Note: right mouse button state not always correct. If you right click to bring up a rightclick menu and then click in the viewport to dismiss the menu, the right mouse button is still reported as down.
mouse.pos

A read only variable to get the mouse position in the currently active viewport as a <point2> value. The coordinates are in pixel values. If the currently active viewport is a 2D view (Track View, Schematic View, Listener, etc.), the coordinates are in the first non-2D viewport.

Picking Points in the Viewports

1589

Picking Points in the Viewports

pickPoint [ prompt:<string> ] [ snap:#2D|#3D ] \ [ rubberBand:<start_point3> ] \ [ mouseMoveCallback:fn | #(fn,arg) ] \ [ terminators:#(<string>,<string>,...) ]

The pickPoint() function lets the user pick a 3D point in a 3ds max viewport or type in a 3D point in the Listener. When called, the function puts 3ds max into a special pointpicking command mode and the cursor changes to a cross-hair. The user can either click in one of 3ds maxs viewports or type a 3D point into the Listener and the function returns that point as a MAXScript Point3 value in world-space coordinates. The function takes an optional prompt: string argument which it prints in the Listener as a prompt message. There is also an optional snap: keyword argument that controls viewport point picking if Snap is turned on in the 3ds max interface. If #3D is specified, the cursor snaps to points anywhere in 3D space, if #2D is specified (the default), the cursor only snaps on the current active grid construction plane. If Snap is off in the 3ds max interface, the clicked point is always taken to be on the current active grid construction plane. The user can either press the ESC key or click the right mouse button at any time to abort the point picking and the function immediately returns the special MAXScript value #escape if the escape key is pressed or #rightClick if the right mouse button is clicked. You can get the pickPoint() function to display a rubberbanding dashed line during point input by supplying the optional keyword argument rubberBand:<start_point3>. If you include this on a call to pickPoint(), it rubberbands a dashed line from the specified start point to follow the mouse. You would use it in a chain of point picks by specifying the last picked point as the rubberBand: start point for each successive pick. The start point given to rubberBand: should be in world coordinates. You can also set up a mouse move callback function for tracking free mouse moves during point input. The optional keyword argument for this is mouseMoveCallback: and it has two forms:
mouseMoveCallback:fn mouseMoveCallback:#(fn, arg)

The second form allows you to supply an argument value that is sent to the callback function each time it is called. The fn you supply should take one argument in the first form above and two in the second. When the callback function is called, the first argument it gets is always the current world coordinates of the mouse and the second if given is the arg you supplied. You can use a callback function to implement a more sophisticated form of rubberbanding, for example by adjusting a splines vertex or a boxs height to follow the mouse. If you do this, make sure you call any needed update() mesh or spline functions.

1590

Chapter 13

Interacting with the 3ds max User Interface

The pickPoint() function allows coordinates to be entered either by clicking in a 3ds max viewport or by typing numbers into the MAXScript Listener window. The user can enter coordinates in one of several forms (based on the command line input syntax for AutoCAD), as follows:
x, y, z

explicit point in current construction plane coordinates

x, y

point on the construction plane (cp)

d

point d units away in mouse direction from last point

@ x, y, z

relative, offset to last input point

@ x, y

on cp, relative to last points projection on cp

d < a

polar on cp, distance from cp origin at a angle from x-axis

@ d < a

relative polar on cp, centered on last point

d < a1 < a2

spherical on cp, d from cp origin at a1 from x and a2 angle from xy-plane

@ d < a1 < a2

relative spherical There can be zero or more white space characters before and between numbers and metacharacters. Note that these typed-coordinates are always interpreted as relative to the current active grid construction plane and that coordinates returned by pickPoint() are always in world-space. Keyboard input by the user that is not in one of the expected coordinate input forms is returned as a String value so the author can handle the error gracefully or permit other kinds of input to be parsed by the script. You can test for these return conditions using the classOf() function, for example:
p = pickPoint() case of ( (p == undefined): (p == #rightClick): (classOf p == Point3): (classOf p == String): )

... ... ... ...

-----

user user user user

pressed clicked entered keyed a

escape RMB a point non-point

The terminators: keyword argument expects an array of 1 or more strings each of 1 or more characters. When supplied, this list of strings specifies a set of keyboard input terminating character sequences. If any one of them is typed at the end of some input, the

Picking Points in the Viewports

1591

pickPoint() function returns immediately without waiting for an ENTER to be typed. In all cases when the terminators: keyword argument is supplied, the pickPoint() function returns a two-element array--the first element is the input point, the second element is the terminating string, or undefined if the point was input with a mouse click or terminated with ENTER. This allows the user to type in a point terminated by a terminator string, or just type the terminator string. In the second case, the first element in the result array is the value undefined. You can inspect the second element in the array to see what terminator, if any, the user actually typed. For example,
pp = pickPoint prompt:foo: terminators:#( , a, oo) if pp[2] == a then ...

Often, the pickPoint() function will be used repeatedly within a script to request multiple points, such as successive vertices in a line. You may need to use the new function, redrawViews(), to force a viewport update as you gradually construct new scene objects this way. MAXScript normally delays viewport redraw until the script finishes running.
pickOffsetDistance [ prompt:<string> ] [ pt2Prompt:<string> ] \ [ errPrompt:<string> ] [ snap:#2D|#3D ] \ [ keyword:<string> ]

This function issues the prompt message, if any, to Listener and waits for the user to either click in a viewport (which determines a point exactly like the pickPoint() function), to type in a number ended by ENTER (which determines a number), or to type all or the beginning of the keyword ended by ENTER. If the user types the keyword, the function returns true. If the user types a number, the function returns its value. If the user clicks a point, the function issues the pt2Prompt message, if any, to Listener and waits for a second point to be clicked, and then returns the world-space distance between the two points. If the user types something which is not a number and does not match the keyword, the function issues the errPrompt message, if any, otherwise the prompt message, if any, and waits for the user to try again.

1592

Chapter 13

Interacting with the 3ds max User Interface

Viewport Drawing Methods

The methods documented in this topic provide low-level access to 3ds maxs graphics system. These methods are available for scripts to do any graphics work not possible using the standard high-level graphics methods. These methods are for use in the existing 3ds max viewports, and only work on the active viewport. Note that these methods typically are not for casual use, as they are not intended to be a high level graphics library. For example, many steps are required to display a single lit polygon. These methods are optimized for speed, and not at all for script programmer ease of use. The methods described in this topic actually operate on graphic windows. While graphic windows are not the same as viewports, they are related to one another. Each viewport has its own graphics window, and the contents of the viewport display can be thought of as a snapshot of the graphics window contents. Since writing to display memory a relatively slow operation, 3ds max writes instead to the graphics window, and then when all the writes have been finished, it redraws the viewports with the graphics window contents. Graphics Driver Configuration and Support Methods
gw.getDriverString()

This method returns a string identifying the graphics driver (and includes manufacturer info if available)
gw.querySupport <feature_name>

Determines if the driver supports the specified feature. The valid <feature_name> values are:
#txtCorrect

This is used to enable or gray-out the perspective correction right-click viewport menu option.
#geomAccel

This is used to indicate to 3ds max (and the mesh class in particular) that the driver wants to handle all of the 3D data natively. In this case, meshes are rendered by passing 3D world space data and letting the driver transform, clip, and light the vertices. If this returns false, then the mesh class handles all transforms, clipping and lighting calculations and then calls the hPolygon or hPolyline 2 1 / 2D calls for the driver to rasterize. (Primitives that are actually clipped are still sent to the polygon/polyline methods.) Currently, only the OpenGL driver returns true to this query, but other drivers have been developed that return true, and the HEIDI and D3D drivers may change in the future.
#triStrips

If this returns true, then 3ds max will try to stripify meshes before calling the rendering methods. Currently, the drivers just return the user preference that is set in the driver configuration dialog. This preference defaults to true.

Viewport Drawing Methods

1593

#dualPlanes

If a driver has dual-planes support it returns true. The standard 3ds max OpenGL display driver only returns true for this if the underlying display driver has implemented a custom OpenGL extension that allows 3ds max to handle this efficiently.
#swapModel

This returns true if 3ds max has to redraw the whole scene any time the viewports are exposed.
#incrUpdate

This returns true if the driver can update a rectangular subset of the viewport without trashing the image outside that rectangle. This is true for most drivers that blit the viewport region and false for those that do page-flipping in the hardware. For OpenGL, this is true if the display driver implements the Microsoft glSwapRectHintWIN extension.
#passDecal

This is true if the driver can handle decalling with only one pass. Currently, this is true for OpenGL, but false for HEIDI and D3D.
#driverConfig

This is true if the driver has a configuration dialog. This is true for all three of 3ds maxs standard drivers.
#texturedBkg

This is true if the viewport background is implemented as a textured rectangle, and false if it is a blitted bitmap.
#virtualVpts

This is true if the driver allows viewports to be made larger than the physical window they are attached to. Currently, this is only true for OpenGL.
#paintDoesBlit

This is true if WM_PAINT messages result in a blit of the backbuffer (as opposed to a page-flipping swap). This allows 3ds max to do quick damage region repair, and works together with the #swapModel flag.
#wireframeStrips

This is true if the driver wants 3ds max to send down wireframe models using triangle strips instead of a bundle of 2-point segments. This is only used by the OpenGL driver, and it is there as a user-choosable performance-accuracy tradeoff (since the strips are faster and are back-culled, but they display hidden edges as though they are visible).

1594

Chapter 13

Interacting with the 3ds max User Interface

Window and Viewport Transformation Methods

gw.isPerspectiveView()

Returns true if the view is in perspective projection; otherwise false (orthographic projection).
gw.setTransform <matrix3>

Sets the active viewports graphics window transformation matrix to the specified matrix3 value, and updates the modeling coordinates to normalized projection coordinates matrix. This routine also back-transforms each light and the eye point so that lighting can be done in modeling coordinates. This method may be used to set a matrix that transforms the point passed to the drawing methods (like gw.text(), gw.marker(), gw.polyline() or gw.polygon()). Normally these methods expect world coordinates. However if this matrix is set to an objects transformation matrix you can pass coordinates in the objects space coordinates and they will be transformed into world space (and then put into screen space when they are drawn). If however this is set to the identity matrix, you would pass world space coordinates. You can set this matrix to the objects transform matrix using the following code:
gw.setTransform node.transform

For world-to-screen space conversions by the methods gw.text(), gw.marker(), gw.polyline() or gw.polygon(), etc, a developer must explicitly set this matrix to the identity matrix. This is because the graphics window may have a non-identity transform matrix already in place from a previous operation.
gw.getFlipped()

Returns true if the determinant of the current transform is positive, false if negative. Position, Size, and Depth Clipping Methods
gw.setPos <x_integer> <y_integer> <w_integer> <h_integer>

Sets the size and position of the graphics window. The coordinates are all Windows coordinates in the space of the graphics windows parent window. All coordinates are in Windows format, with the origin in the upper left. x - Specifies the left graphics window origin; y - Specifies the top graphics window origin; w - Specifies the graphics window width; h - Specifies the graphics window height.
gw.getWinSizeX()

This method gets the current window size in X.

gw.getWinSizeY()

This method gets the current window size in Y.

gw.getWinDepth()

This method returns the z-buffer depth (in bits). Note: this method does not return the proper Z depth value in 3ds max and VIZ R3.
gw.getHitherCoord()

This method returns the largest device Z value.

Viewport Drawing Methods

1595

gw.getYonCoord()

This method returns the smallest device Z value. Note: this method does not return the proper Z depth value in 3ds max and VIZ R3. DIB (Device-Independent Bitmap) Methods
gw.getViewportDib()

This method returns the active viewports graphics window image as a Bitmap value. The size of the bitmap is the same size as the viewport. Script:
MacroScript GrabViewport category:Tools tooltip:Grab Viewport ( ----------------------------------------------------------------------GRABVIEWPORT MACROSCRIPT --Created:3/23/99 --Edited:4/28/99 --by Borislav Petrov --bobo@email.archlab.tuwien.ac.at ----------------------------------------------------------------------Snapshot Active Viewport to Bitmap --Filename in format: --VPGRAB_MaxFileName_ViewportName_CurentFrame.ImageFormatExtension -----------------------------------------------------------------------Init Variables local grab_bmp --bitmap to put the snapshot into local bmp_name --name of the bitmap to save local get_viewport_name --viewport name local gac,gct,mfn --variables to hold ActiveCamera, CurrentTime, MaxFileName ---Start Macro grab_bmp = gw.getViewportDib() --get the viewport bitmap into variable get_viewport_name = viewport.GetType() --get viewport name gvn = get_viewport_name as string --convert viewport name to string gvn = substring gvn 6 (gvn.count-5) --cut the string if gvn == camera then --if the remaining string is camera ( gac = getActiveCamera() --get the camera gvn = gac.name --get the name of the camera ) mfn = MaxFileName --get max file name if mfn == then --if there is no name mfn = Untitled --use Untitled else mfn = getFileNameFile mfn --use the file name without .MAX extension gct = SliderTime as string --get current frame time -bmp_name = VPGRAB_+ mfn +_ +gvn + _ + gct --build the output file name ---Display file save dialog bmp_name = getSaveFileName caption:Save Viewport to: filename:bmp_name \ types:BMP(*.bmp)|*.bmp|TIFF(*.tif)|*.tif|JPG(*.jpg)|*.jpg|TGA(*.tga)|*.tga|

1596

Chapter 13

Interacting with the 3ds max User Interface

-if bmp_name != undefined then ( grab_bmp.filename = bmp_name file dialog save grab_bmp display grab_bmp ) -)--end of script

--if user has confirmed / entered a valid name --set output name to the one entered in the save --save the bitmap --display the bitmap in a VFB

Drawing Setup
gw.resetUpdateRect()

This method resets the update rectangle. The update rectangle is the region of the screen that needs to be updated to reflect items that have changed. When the system is done rendering items, the goal is to only update the region of the viewport that has actually been altered. This method sets the update rectangle (the region that will be blitted to the display) to a special empty value. This way when gw.enlargeUpdateRect() is later called, the Box2 region passed will be used as the region.
gw.enlargeUpdateRect ( <Box2> | #whole )

This method enlarges the update rectangle to include the Box2 value passed. If #whole is specified, the whole viewport will later be updated
gw.getUpdateRect()

This method retrieves the current update rectangle as a Box2 value. Returns a special an Box2 empty value if no region of the viewport needs to be updated.
gw.setRndLimits <render_limits_name_array>

Sets the rendering limits used by primitive calls. Setting the rendering limits is used in communication between the various parts of 3ds max that handle the display of objects. For example, setting this limit to #polyEdges and then drawing a polygon wont result in a polygon drawn with edges. It only sets a flag that indicates the edge should be drawn. What happens is as follows. Inside the upper level 3ds max , part of the code knows that polygon edges have been turned on. However this is not related through the object oriented architecture to the part of 3ds max that does the actual drawing. When 3ds max goes to draw objects it will see that the polygon edge flag is on. This tells it to do two drawing passes -- one to draw the polygon, then it calls outlinePass() call with true, draws a bunch of edges, then calls outlinePass() with false. Thus, the drawing routine is responsible for looking at the flags and drawing appropriately. This method is only responsible setting the limit which can later be checked. <render_limits_name_array> specifies the rendering limits used by the viewport as an array of <render_limits_name> values. The valid <render_limits_name> values are:
#allEdges

All edges of the item are shown (including hidden ones).

#boxMode

Objects are shown using their bounding box.

Viewport Drawing Methods

1597

#backcull

Backface culling is used. Entities whose surface normal face away from the view direction are not drawn.
#colorVerts

This turns on color-per-vertex display.

#flat

Flat (facet) shading mode.

#illum

This indicates that you have colors per vertex in your polygons and that they should be used. If you had colors per vertex but this flag was not set, the colors would be ignored.
#lighting

This is the same as setting #illum and #specular.

#noAtts

No attributes are specified.

#perspCorrect

In this mode textures are corrected for perspective display.

#pick

This indicates hit testing will be performed (not rendering).

#polyEdges

This mode causes polygon edges (Edged Faces) to be on.

#shadeCverts

This modifies #colorVerts. If set, lighting is enabled and the vertex colors are used to modulate the colors that result from lighting. If off, the colors on each vertex are used directly to shade the triangle. When 3ds max uses #shadeCverts mode, it puts a white diffuse-only material on the object so that it appears that the colors are shaded without distortion. Described further, when #shadeCverts is OFF, then the vertex colors are used directly. This is equivalent to saying that they are modulated by a pure white selfilluminated material. When #shadeCverts is ON, the diffuse white material is illuminated by the scene lighting, resulting in shades ranging from black to white, with most vertices being some shade of pure gray. When the vertex colors are modulated by the material color, they get multiplied (in general) by a number less than 1, which makes them appear darker. The RGB components of the colors are modulated uniformly, so that there is no shift from, say, red to green. That would happen if the underlying material was not evenly weighted (that is, a pure gray lying between black and white). Said another way, only the intensity of the vertex colors is changed when shading is on, not luminance, chrominance, etc.

1598

Chapter 13

Interacting with the 3ds max User Interface

#specular

This enables specular highlight display.

#texture

This enables texture display.

#twoSided

Faces are displayed regardless of their surface normal orientation.

#vertTicks

This mode is really a pseudo-mode, in that it doesnt actually cause the graphics drivers to do anything differently, but rather is tested by the Mesh class, which sends down vertex markers (+) if the mode is on.
#wireframe

Wireframe rendering mode.

#zBuffer

When coordinates are specified for drawing primitives they have x, y, and z values. Sometimes when drawing entities in the viewports it is desirable to ignore the z values. For example in the 3ds max viewports the text that display the type of viewport (Front, Left, and so on) are drawn without z values. So are the arc-rotate circle control and the axis tripods. These items are drawn without this flag being set so they always show up in front.
gw.getRndLimits()

Retrieves the rendering limits used by primitive calls as an array of names. See gw.setRndLimits() for a list of the returned name values.
gw.getRndMode()

Returns the current rendering mode used by the viewport as an array of names. This is a subset of the rendering limit, in that any limits imposed by the rendering limit are forced onto the current mode. See gw.setRndLimits() for a list of the returned name values.
gw.setSkipCount <skip_count_integer>

Sets the number of triangles skipped when the viewport is set as a Fast View Display viewport. To disable fastview, specify 1. Since triangles are handed down to graphics driver one at a time, it is up to the code that feeds triangles to the graphics driver to skip the specified number of triangles. The mesh rendering in 3ds max uses the skip count in this way. <skip_count_integer> specifies that every n-th triangle should be drawn. If set to 2, every other triangle should be drawn.
gw.getSkipCount()

Returns the current skip count setting.

Viewport Drawing Methods

1599

The following is an example of using the above functions:

-- Get the current rendering limits lim = gw.getRndLimits() -- Add another limit append lim #polyEdges -- Set the new rendering limits gw.setRndLimits lim -- Get back the rendering limits to check gw.getRndLimits() -- Get back the rendering mode to check gw.getRndMode()

Light and Camera Methods

gw.getMaxLights()

Returns the maximum number of lights that may be used by the interactive renderer. Coordinate Transformation Methods The following methods map points from the graphic windows current transform to device space. If the graphic windows transform is set to the identity matrix then the mapping is done from points specified in world space. Otherwise the points given are transformed by the graphic windows transform, and are then considered to be in world space. Thus, to get a world-space to screen-space conversion, you need to set the graphic windows transform to the identity with:
gw.setTransform(Matrix3 1) gw.hTransPoint <point3>

This method converts the point3 coordinate to a h format device coordinate. Each component of the return value is in integer format in the native device coordinates for the graphics driver. For HEIDI and OpenGL, the origin is at the lower left. For Direct3D the origin is at the upper left.
gw.wTransPoint <point3>

This method converts the point3 coordinate to a w format device coordinate. Each component of the return value is in integer format with the origin at the upper left.
gw.transPoint <point3>

This method converts the point3 coordinate to a h floating point coordinate. Each component of the return value is in float format with the origin at the upper left. This is just a helper routine to avoid building up round-off error. 3ds max uses it just for IK.

1600

Chapter 13

Interacting with the 3ds max User Interface

Drawing Methods Methods that start with h take integer device coordinates with the origin at the lower-left. Methods that start with w in front take Windows device coordinates with the origin at the upper left. These h and w routines perform NO clipping unless otherwise noted. Drawing outside the allowable region is likely to cause 3ds max to crash. These coordinate systems are left-handed. Methods that dont start with h or w map points from the graphic windows current transform to device space. This coordinate system is right-handed. If the graphic windows transform is set to the identity matrix then the mapping is done from points specified in world space. Otherwise the points given are transformed by the graphic windows transform, and are then considered to be in world space. Thus, to get a world-space to screen-space conversion, you need to set the graphic windows transform to the identity with:
gw.setTransform(Matrix3 1)

After completing any drawing to the graphics window with the methods described in this section, you need to call gw.updateScreen() to update the viewport display.
gw.updateScreen()

Updates the viewport display to display any text, markers, polylines, polygons, or tristrips written to the graphics window via the methods described below.
gw.text <point3> <string> [ color:<color> ] gw.hText <point3> <string> [ color:<color> ] gw.wText <point3> <string> [ color:<color> ]

Draws 2D fixed font annotation string text to the specified location using the specified (optional) color. If the color is not specified, a default color of red is used. Note: This routine DOES perform clipping of the text if it is off the screen.
gw.Marker <point3> <marker_name> [ color:<color> ] gw.hMarker <point3> <marker_name> [ color:<color> ] gw.wMarker <point3> <marker_name> [ color:<color> ]

Draws a marker at the specified location. This is can be paired with pickpoint() to quickly show where the user has clicked. These markers are temporary and will be erased whenever the viewports are updated. If the color is not specified, a default color of red is used. The valid <marker_name> types are:
#point #hollowBox #plusSign #asterisk #xMarker #bigBox #circle #triangle #diamond #smallHollowBox #smallCircle #smallTriangle #smallDiamond

Viewport Drawing Methods

1601

The following is an example that creates an instance of all types of markers, spaced equally:
arr = #(point,hollowBox,plusSign,asterisk,xMarker, bigBox,circle,triangle,diamond,smallHollowBox, smallCircle,smallTriangle,smallDiamond ) for i=1 to arr.count do gw.hMarker [100, (50 + i*10), 50](arr[i] as name) gw.enlargeUpdateRect #whole gw.updateScreen() gw.Polyline <vertex_point3_array> <isClosed_boolean> \ [ rgb:<color_array> ] gw.hPolyline <vertex_point3_array> <isClosed_boolean> \ [ rgb:<color_array> ] gw.wPolyline <vertex_point3_array> <isClosed_boolean> \ [ rgb:<color_array> ]

This method draws a multi-segment polyline. Each value in <vertex_point3_array> is a vertex on the polyline. If <isClosed_boolean> is true, the first point is connected to the last point, that is, the polyline is closed. If false, the polyline is left open. If the optional rgb color array is specified, and shade mode is set to smooth, the polyline will be drawn Gourand shaded. This is how 3ds max draws lit wireframes for instance. If the optional rgb color array is not specified, the line is drawn with the line color specified via gw.setColor(). The number of elements in <color_array> must be the same as in <vertex_point3_array>.
gw.Polygon <vertex_point3_array> <color_array> \ <uvw_point3_array> gw.hPolygon <vertex_point3_array> <color_array> \ <uvw_point3_array> gw.wPolygon <vertex_point3_array> <color_array> \ <uvw_point3_array>

This method draws a multi-point polygon. Each value in <vertex_point3_array> is a vertex on the polygon. <color_array> specifies the color at each vertex. The rendering mode (set via gw.setRndLimits()) must include #illum for the color values to be used. <uvw_point3_array> specifies the UVW coordinates at each. The rendering mode must include #texture for the UVW coordinates to be used. The number of elements in each array must be identical.
gw.hTriStrip <vertex_point3_array> <color_array> \ <uvw_point3_array> gw.wTriStrip <vertex_point3_array> <color_array> \ <uvw_point3_array>

This method is used for drawing a series of triangles specified as strips. It takes a count of 3 or more, and builds triangles in a strip. This sends a lot less data and the underlying graphics library has to set up a lot less data since it can use the previous information to

1602

Chapter 13

Interacting with the 3ds max User Interface

start the rasterization. This results in a significant speed increase. This routine does no clipping so all the vertices passed must be within view. The parameters are the same as for the gw.Polygon(). However, how the <vertex_point3_array> is handled is different. After the first two vertices, each new vertex is used to create a new triangle. For instance, to draw a quad, the first three vertices specify the first triangle and the next one is combined with the previous two to complete the square The following is an example of using the above functions: Script:
-- Draw some primitives gw.hPolyline #([300,50,16], [300,200,8], [450,250,4]) true -gw.hPolygon #([200,100,16], [280,100,8], [250,200,4]) \ #(red, blue, green) \ #([1.0,.5,0], [0.5,0.5,0], [0,0,0.5]) -gw.hTriStrip #([50,50,0], [175,100,0], [25,100,0], [150,250,0]) \ #(red, blue, green, white) \ #([1.0,.5,0], [0.5,0.5,0], [0,0,0.5], [0.5,1,0]) --- Update the viewports gw.enlargeUpdateRect #whole gw.updateScreen() gw.setColor <type_name> <color_value>

Sets the RGB color used for the specified drawing type. The valid <type_name> values are:
#line #fill #text #clear ----line drawing color polygon fill color text drawing color The color that the viewport is cleared to when you call gw.clearScreen()

gw.clearScreen <Box2> [ useBkg:<boolean> ]

Clears the specified rectangular region of the screen. If the optional useBkg parameter is set to false, the region is set to the clear color (see gw.setColor() above). If true, the background should be used to fill the cleared area. The default useBkg value is false.

Miscellaneous Viewport Methods and System Globals

1603

Miscellaneous Viewport Methods and System Globals

createPreview()

Creates a viewport preview using the current values in the Make Preview dialog.
getVPortBGColor() setVPortBGColor()

Get and set the viewport background color as a Color value.

isCPEdgeOnInView()

This method returns true if the construction plane is head on in the current viewport. For example if the construction plane was XY and you were looking from the Front view, this method would return true. This is used for example during object creation because this process doesnt work very well when the view is head on.
axisTripodLocked()

This method returns true if the axis tripods are locked, that is, they wont move when you move an object or sub-object, false otherwise.
lockAxisTripods <boolean>

If <boolean> is true, this method locks the axis tripods so that they will not be updated. If false, the axis tripods will be updated. Note: In certain cases, the lockAxisTripods() method can cause multiple Assertion Failures. This occurs when one or more objects are selected, lockAxisTripods true is executed, and then the objects are deselected.
flashNodes <node_array>

This method is used to flash a group of nodes. This is usually used as a confirmation of some operation (for example as an indication of the completion of a pick node operation.) The nodes are briefly erased and then redrawn in the viewport to flash them. Note: The flashNodes() method does not redraw the viewports after displaying the specified nodes as white wireframes. To properly redraw the viewports, call the forceCompleteredraw() method immediately after calling flashNodes(). The following 3ds max system global variables are applicable to the viewports:
displaySafeFrames

Lets you get and set whether Show Safe Frames is on for the active viewport. A Boolean value - true if Show Safe Frames is on, false if off.
preferences.useLargeVertexDots

Lets you get and set whether to use small or large dots when representing vertices as dots. A Boolean value set to true if you when using dots to represent vertices and a large size is desired. The value of this variable only has effect when UseVertexDots is set to true. This variable contains the corresponding value set in the Viewports page of Customize > Preferences.
preferences.useTransformGizmos

Lets you get and set whether to use the Transform Gizmos. A Boolean value - true if on, false if off. This variable contains the corresponding value set in the Viewports page of Customize > Preferences.

1604

Chapter 13

Interacting with the 3ds max User Interface

preferences.useVertexDots

Lets you get and set whether to represent vertices as dots. A Boolean value set to true when you want to use dots as the representation of the vertices in a mesh. If set to false, ticks will be used. This variable contains the corresponding value set in the Viewports page of Customize > Preferences.

3ds max User Interface Colors

The following methods are used to get and set the 3ds max user interface colors.
GetUIColor <index_integer>

Returns a Point3 value corresponding to the color value used for drawing the specified item type in the 3ds max viewports. Each component of the Point3 value is in a range of 0 to 1, corresponding to a color component value of 0 to 255. See the list of <index_integer> values below.
GetDefaultUIColor <index_integer>

Returns a Point3 value corresponding to the default color used for drawing the specified item type in the 3ds max user interface. Each component of the Point3 value is in a range of 0 to 1, corresponding to a color component value of 0 to 255. The values returned are not affected by the users color selections or those set by SetUIColor(). See the list of <index_integer> values below.
SetUIColor <index_integer> <point3>

Sets the color value used for drawing the specified item type in the 3ds max viewports. Each component of the Point3 value is in a range of 0 to 1, corresponding to a color component value of 0 to 255. See the list of <index_integer> values below. The valid <index_integer> values and the corresponding item type are as follow:
0 1 2 3 4 5 6 7 8 9 10 11 12 14 15 16 17 18 19 20 21 COLOR_SELECTION COLOR_SUBSELECTION COLOR_FREEZE COLOR_GRID COLOR_GRID_INTENS COLOR_SF_LIVE COLOR_SF_ACTION COLOR_SF_TITLE COLOR_VP_LABELS COLOR_VP_INACTIVE COLOR_ARCBALL COLOR_ARCBALL_HILITE COLOR_ANIM_BUTTON COLOR_LINK_LINES COLOR_TRAJECTORY COLOR_ACTIVE_AXIS COLOR_INACTIVE_AXIS COLOR_SPACE_WARPS COLOR_DUMMY_OBJ COLOR_POINT_OBJ COLOR_POINT_AXES Main UI Main UI Main UI Grids Grids Main UI Main UI Main UI Main UI Main UI Main UI Main UI Main UI Gizmos & Gizmos & Gizmos & Gizmos & Objects Objects Objects Objects Selection Subselection Freeze Grid Grid Intensity Safe Frame Live Safe Frame Action Safe Frame Title Viewport Label Inactive Viewport Label Arcball Arcball Highlight Animate Button Bones and Link Lines Trajectory Active Axis Inactive Axis Space Warp Dummy Object Point Object Point Axis

Apparatuses Apparatuses Apparatuses Apparatuses

Miscellaneous Viewport Methods and System Globals

1605

22 24 25 26 27 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74

COLOR_TAPE_OBJ COLOR_GIZMOS COLOR_SEL_GIZMOS COLOR_SPLINE_VECS COLOR_SPLINE_HANDLES COLOR_PARTICLE_EM COLOR_CAMERA_OBJ COLOR_CAMERA_CONE COLOR_CAMERA_HORIZ COLOR_NEAR_RANGE COLOR_FAR_RANGE COLOR_LIGHT_OBJ COLOR_TARGET_LINE COLOR_HOTSPOT COLOR_FALLOFF COLOR_START_RANGE COLOR_END_RANGE COLOR_VIEWPORT_BKG COLOR_TRAJ_TICS_1 COLOR_TRAJ_TICS_2 COLOR_TRAJ_TICS_3 COLOR_GHOST_BEFORE COLOR_GHOST_AFTER COLOR_12FIELD_GRID COLOR_START_RANGE1 COLOR_END_RANGE1 COLOR_CAMERA_CLIP COLOR_NURBS_CV COLOR_NURBS_LATTICE COLOR_NURBS_CP COLOR_NURBS_FP COLOR_NURBS_DEP COLOR_NURBS_ERROR COLOR_NURBS_HILITE COLOR_NURBS_FUSE COLOR_END_EFFECTOR COLOR_END_EFFECTOR_STRING COLOR_JOINT_LIMIT_SEL COLOR_JOINT_LIMIT_UNSEL COLOR_IK_TERMINATOR COLOR_SF_USER COLOR_VERT_TICKS COLOR_XRAY COLOR_GROUP_OBJ COLOR_MANIPULATOR_X COLOR_MANIPULATOR_Y COLOR_MANIPULATOR_Z COLOR_MANIPULATOR_ACTIVE COLOR_VPT_CLIPPING COLOR_DECAY_RADIUS COLOR_VERT_NUMBERS

Objects Gizmos & Gizmos & Main UI Main UI Gizmos & Objects Gizmos & Gizmos & Gizmos & Gizmos & Objects Gizmos & Gizmos & Gizmos & Gizmos & Gizmos & Main UI Gizmos & Gizmos & Gizmos & Main UI Main UI Main UI Gizmos & Gizmos & Gizmos & Main UI Main UI Main UI Main UI Main UI Main UI Main UI Main UI Gizmos & Gizmos & Gizmos & Gizmos & Gizmos & Main UI Main UI Main UI Objects Gizmos & Gizmos & Gizmos & Gizmos & Main UI Gizmos & Main UI

Apparatuses Apparatuses

Apparatuses Apparatuses Apparatuses Apparatuses Apparatuses Apparatuses Apparatuses Apparatuses Apparatuses Apparatuses Apparatuses Apparatuses Apparatuses

Apparatuses Apparatuses Apparatuses

Apparatuses Apparatuses Apparatuses Apparatuses Apparatuses

Apparatuses Apparatuses Apparatuses Apparatuses Apparatuses

Tape Object Gizmos Selected Gizmos Spline Vectors Spline Handles Particle Emitter Camera Object Camera Cone Camera Horizon Camera Near Range Camera Far Range Light Object Target Line Light Hotspot Light Falloff Light Far Start Light Far End Viewport Background Trajectory Frames 1 Trajectory Frames 2 Trajectory Frames 3 Ghost (Before) Ghost (After) 12-Field Grid Light Near Start Light Near End Camera Clip NURBS Control Vertex NURBS Lattice NURBS Con Point NURBS Fit Point NURBS Dep Object NURBS Error Object NURBS Hilite NURBS Fuse End Effector End Effector String Selected Joint Limits Joint Limits IK Terminator Safe Frame User Vertex Ticks See Through Group Object Transform Gizmo X Transform Gizmo Y Transform Gizmo Z Active Transform Gizmo Viewport Clipping Light Decay Start Vertex Numbers

1606

Chapter 13

Interacting with the 3ds max User Interface

75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103

COLOR_CROSSHAIR_CURSOR COLOR_SV_WINBK COLOR_SV_NODEBK COLOR_SV_SELNODEBK COLOR_SV_NODE_HIGHLIGHT COLOR_SV_MATERIAL_HIGHLIGHT COLOR_SV_MODIFIER_HIGHLIGHT COLOR_SV_PLUGIN_HIGHLIGHT COLOR_SV_SUBANIM_LINE COLOR_SV_CHILD_LINE COLOR_SV_FRAME COLOR_SV_SELTEXT COLOR_SV_TEXT COLOR_UNSEL_TAB COLOR_ATMOS_APPARATUS COLOR_SUBSELECTION_HARD COLOR_SUBSELECTION_MEDIUM COLOR_SUBSELECTION_SOFT COLOR_SV_UNFOLD_BUTTON COLOR_SV_GEOMOBJECT_BK COLOR_SV_LIGHT_BK COLOR_SV_CAMERA_BK COLOR_SV_SHAPE_BK COLOR_SV_HELPER_BK COLOR_SV_SYSTEM_BK COLOR_SV_CONTROLLER_BK COLOR_SV_MODIFIER_BK COLOR_SV_MATERIAL_BK COLOR_SV_MAP_BK

Main UI Other Views Other Views Other Views Other Views Other Views Other Views Other Views Other Views Other Views Other Views Other Views Other Views Main UI Gizmos & Apparatuses Main UI Main UI Main UI Other Views Other Views Other Views Other Views Other Views Other Views Other Views Other Views Other Views Other Views Other Views

Cross Hair Cursor SV Window Bkg SV Node Bkg SV Selected Node Bkg SV Node Highlight SV Material Highlight SV Modifier Highlight SV Plugin Highlight SV Sub-Anim Line SV Child Line SV Frame SV Selected Label SV Label Unselected Tabs Atmospheric Apparatuses SubSelection Hard SubSelection Medium SubSelection Soft SV Unfold Children Button SV Geometry Node Bkg SV Light Node Bkg SV Camera Node Bkg SV Shape Node Bkg SV Helper Node Bkg SV System Node Bkg SV Controller Node Bkg SV Modifier Node Bkg SV Material Node Bkg SV Map Node Bkg

Material Editor
The following functions are specific to materials and the use of materials with the Material Editor:
getMeditMaterial <slot_index>

you can get the materials in the material editor slots 1 through 24. For example:
foo = getMeditMaterial 3 setMeditMaterial <slot_index> <material>

complements the getMeditMaterial function allowing you to place a material into the numbered material editor slots. Accepts either materials or texture maps as <material>.
loadDefaultMatLib()

Loads the default 3ds max material library file.

loadMaterialLibrary <filename_string>

Loads the named 3ds max material library file, which becomes the current material library. If the file name does not have a fully specified directory path, the function searches through all the currently configured bitmap paths. Returns true if the loads succeeds, false if it fails.

Miscellaneous Viewport Methods and System Globals

1607

saveMaterialLibrary <filename_string>

Saves the current material library into the named file. Returns true if the save succeeds, false if it fails.
fileOpenMatLib()

This method displays the File Open dialog and allows the user to select a material library to load.
fileSaveAsMatLib()

Displays the standard Save File As dialog to allow the user to save the current material library.
fileSaveMatLib()

If the current material library has been saved previously (has been named) this method saves the material library to the same file. Otherwise it displays the standard Save File As dialog to allow the user to save the current material library.
getMatLibFileName()

Returns the current material library file name as a String value.

renderMap <textureMap> [ [ [ [ [ [ into:<bitmap> ] size:<point2> ] filename:<string> ] scale:<float> ] filter:<boolean> ] display:<boolean> ] \ \ \ \ \

provides access to the Render Map function available in the Material Editor. The function returns a Bitmap value containing a rendering of the given texture map. If you specify the optional into: argument, the function renders the map into the supplied bitmap, taking size and other attributes from the existing bitmap. If you dont, a new bitmap value is created using the size: and fileName: arguments in its creation. If the into: and size: parameters are not specified, the default size in [200,200]. The scale: argument is a scale factor applied to 3D TextureMaps. This is the scale of the surface in 3d space that is mapped to UV and controls how much of the texture appears in the bitmap representation. If the filter: argument is true, the bitmap is filtered. It is quite a bit slower to rescale bitmaps with filtering on. Defaults to false. If the display: argument is true, the resulting bitmap is displayed using the virtual frame buffer; otherwise it is not. Defaults to false. Example:
rm = renderMap $foo.material.diffuseMap size:[640,480] \ fileName:foodif.bmp save rm close rm

The above will render a map to a bitmap and save it as a .bmp file.

1608

Chapter 13

Interacting with the 3ds max User Interface

showTextureMap <material> <texmap> <boolean>

This provides control over the visibility of textures in the shaded viewport. You specify the material containing the texture map, the texture map in that material to be controlled and a boolean to turn the display on or off, for example: Example:
showTextureMap $foo.material $foo.material.diffuseMap on tm = checker() mat = standardMaterial diffuseMap:tm mm = multimaterial() mm[1] = mat $box01.material = mm showTextureMap mm[1] tm on

Note that for multimaterials, you need to specify the appropriate sub-material (using [] indexing, for example). The following 3ds max system global variables are applicable to the Material Editor:
currentMaterialLibrary

Contains a virtual array of materials and root level maps corresponding to the currently opened material library. You can get library materials via array indexing and iterate over them in a for loop. The array can be indexed by number, or by name or string to select by material name. This variable is read-only. See the MaterialLibrary Values (p. 795) topic for more information.
meditMaterials

Contains a virtual array of materials and root level maps corresponding to the slots in the material editor. You can access material editor materials and root level maps via array indexing and iterate over them in a for loop. The array can be indexed by number to specify slot number or name or string to select by material and root level map name. For example:
$foo.material = meditMaterials[1] meditMaterials[foo mat].diffuse = red for m in meditMaterials do print m.diffuseMap meditMaterials[1]=standard() print meditMaterials.count -- number of slots

This variable is read-only, but the elements (the materials in the slots) are assignable. See the MaterialLibrary Values (p. 795) topic for more information.
sceneMaterials

Contains a virtual array of materials and root level maps corresponding to the materials and root level maps present in the scene. You can get scene materials and root level maps via array indexing and iterate over them in a for loop. The array can be indexed by number, or by name or string to select by material or root level map name. This variable is read-only. See the MaterialLibrary Values (p. 795) topic for more information.

Miscellaneous Viewport Methods and System Globals

1609

Track View
The Track View window functions are in a structure package named trackView. These functions operate on named Track Views, and in many cases you identify the Track View window by this name. The Track View functions are:
trackView.open <name_string>

Opens an existing Track View with the specified name, or creates a new Track View with specified name. Returns the value true.
trackView.zoomSelected <name_string>

Zoom the named Track View on the currently selected object. The World track must be expanded for this function to operate. The Object track will automatically be expanded if is closed. The hierarchy display is scrolled such that the selected objects track is placed at the top of the window. If multiple objects are selected, the first object in the hierarchy that is selected will be placed at the top of the window. If there are no selected objects, no operation occurs. This method will return true, except when the named Track View does not exist or is not open, when it returns false.
trackView.close <name_string>

Closes the named Track View. This method will return true, except when the named Track View does not exist or is not open, when it returns false.
trackView.numTrackViews()

Returns the number of named Track Views defined

trackView.getTrackViewName <index_integer>

Returns the name of the indexed Track View as a String. Index values are 1-based.
trackView.setFilter name_string {<filter_flag_name>} [#noRedraw] trackView.clearFilter name_string {<filter_flag_name>} [#noRedraw]

These methods allow you to set and clear display filters flags to control what is visible in a named Track View. This method will return true, except when the named Track View does not exist or is not open, when it returns false. You can supply as many filter flags as desired per call. The valid filter flag names are:
#all #default #selectedObjects #selectedTracks #animatedTracks #spacewarpBindings #modifiedObjects #transforms #baseObjects #positionX #positionY #positionZ #rotationX #rotationY #rotationZ #scaleX -- set or clear all flags -- set default view flags

1610

Chapter 13

Interacting with the 3ds max User Interface

#scaleY #scaleZ #red #green #blue #controllerTypes #noteTracks #sound #materialsMaps #materialParameters #visibilityTracks #hideGeometry #hideShapes #hideLights #hideCameras #hideHelpers #hideSpacewarps #visibleObjects #position #rotation #scale #curveX #curveY #curveZ #staticValues #hierarchy #objects

The following 3ds max system global variables are applicable to Track View:
globalTracks

Contains a MAXTVNode value that defines the top-level Global Tracks node in Track View. See Track View Nodes (p. 1382). This variable is read-only.
trackViewNodes

Contains a MAXTVNode value that defines top-level World node in Track View. See Track View Nodes (p. 1382). This variable is read-only.
videoPostTracks

Contains a MAXTVNode value that defines the top-level Video Post Track View node. See Track View Nodes (p. 1382). This variable is read-only. This variable contains the value undefined in 3D Studio VIZ.

Miscellaneous Viewport Methods and System Globals

1611

Render Scene Dialog

Note: Changing the render scene dialog settings via the scripter should be done with the actual render scene dialog in a closed state. Leaving the dialog open will make the attempted scripter modifications non-sticky. The following methods get and set options in the Render Scene dialog:
getRendApertureWidth()

Get the Aperture Width in millimeters for the current renderer.

getRendImageAspect()

Get the Image Aspect Ratio for the current renderer.

getUseDraftRenderer()

Returns true if the Draft renderer is the default renderer, false if the Production renderer is the default renderer.
SetUseDraftRenderer <boolean>

Specifies which renderer is active -- draft or production. Pass true to use the draft renderer and false to use the production renderer. The following 3ds max system global variables are applicable to the Render Scene dialog:
renderer

Lets you switch between the draft and production renderers and test which one is active. A Name value that accepts and contains the values #draft or #production, for example:
if renderer == #draft then ... renderer = #production render camera:c ... renderDisplacements

Lets you get and set whether to perform displacement mapping during a render. A Boolean value - true if displacement mapping is to be performed, false if not.
renderEffects

Lets you get and set whether to perform Render Effects after a scene render. A Boolean value - true if Render Effects are to be performed, false if not.
renderHeight

Lets you get and set an Integer value that defines the output size height for the active renderer.
renderPixelAspect

Lets you get and set an Integer value that defines the output pixel aspect for the active renderer.
renderWidth

Lets you get and set an Integer value that defines the output size width for the active renderer.

1612

Chapter 13

Interacting with the 3ds max User Interface

rendOutputFilename

Lets you get and set a String value that defines the output file name for the active renderer. It contains the corresponding value set in the Render Scene dialog. If this global variable is set to then Save File check box in the Render Scene dialog is unchecked.
skipRenderedFrames

Lets you get and set whether to skip rendered frames during a render. A Boolean Value true if rendered frames are to be skipped, false if not. Note: The following globals should not be used if the Render Scene dialog is open. These globals do not update the dialog if it is open, and closing the dialog or rendering from the dialog will cause the displayed settings to be stored and used.
rendTimeType -- integer

Get/set the type of time range to be rendered. One of the following values: 1 - A single frame. 2 - The active time segment. 3 - The user specified range. 4 - The user specified frame pickup string (for example 1,3,5-12).
rendStart -- time

Get/set the renderers start time setting.

rendEnd -- time

Get/set the renderers end time setting.

rendNThFrame -- integer

Get/set the renderers n-th frame setting. Minimum value = 1

rendShowVFB -- boolean

Get/set the state of the renderers show virtual frame buffer flag. TRUE = on; FALSE = off
rendSaveFile -- boolean

Get/set the state of the renderers save file flag. TRUE = on; FALSE = off
rendUseDevice -- boolean

Get/set the state of the renderers use device flag. TRUE = on; FALSE = off
rendUseNet -- boolean

Get/set the state of the renderers use net flag. TRUE = on; FALSE = off
rendFieldRender -- boolean

Get/set the renderers field render flag. TRUE = on; FALSE = off
rendColorCheck -- boolean

Get/set the renderers color check flag. TRUE = on; FALSE = off
rendSuperBlack -- boolean

Get/set the renderers super black flag. TRUE = on; FALSE = off
rendHidden -- boolean

Get/set the renderers render hidden objects flag. TRUE = on; FALSE = off
rendForce2Side -- boolean

Get/set the renderers force two-sided flag. TRUE = on; FALSE = off

Miscellaneous Viewport Methods and System Globals

1613

rendAtmosphere -- boolean

Get/set the renderers uses atmospheric effects flag. TRUE = on; FALSE = off
rendDitherTrue -- boolean

Get/set the renderers dither true color flag. TRUE = on; FALSE = off
rendDither256 -- boolean

Get/set the renderers dither 256 color flag. TRUE = on; FALSE = off
rendMultiThread -- boolean

Get/set the renderers multi-threaded flag. TRUE = on; FALSE = off

rendNThSerial -- boolean

Get/set the output file sequencing nth serial numbering setting. TRUE = on; FALSE = off
rendVidCorrectMethod -- integer

Get/set the video color check method. One of the following values: 1 = FLAG 2 = SCALE_LUMA 3 = SCALE_SAT
rendFieldOrder -- integer

Get/set the rendering field order. One of the following values: 1 is Even 2 is Odd
rendNTSC_PAL -- integer

Get/set the video color check NTSC or PAL setting. One of the following values: 1 is NTSC 2 is PAL
rendSuperBlackThresh -- integer

Get/set the super black threshold setting. Range 0 to 255.

rendFileNumberBase -- integer

Get/set the File Number Base in the Common Parameters rollup of the Render Scene dialog.
rendPickupFrames -- string

Get/set the Frames string in the Common Parameters rollup of the Render Scene dialog. The following 3ds max system global variables are applicable to the Renderer, but corresponds to the Gbuffer Layers Maximum Number parameter in the Rendering page of the Preference Settings dialog:
preferences.maximumGBufferLayers

Lets you get and set an Integer value that specifies the maximum number of g-buffer layers generated during a render.

1614

Chapter 13

Interacting with the 3ds max User Interface

The following 3ds max system global variables are specific to 3ds maxs default scanline A-Buffer renderer. These variables return undefined if the current renderer is not 3ds maxs default scanline A-Buffer renderer.
scanlineRender.antiAliasFilter

Lets you get and set the anti-aliasing filter. For a list of all of the anti-aliasing filters you can say:
showClass *:filter*

For example:
scanlineRender.antiAliasFilter = quadratic()

The anti-aliasing filters and their parameters are described in the 3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters (p. 1614) topic.
scanlineRender.antiAliasFilterSize

Contains a float value that defines the anti-aliasing filter size.

scanlineRender.enablePixelSampler

Lets you enables and disables global super sampling. A Boolean value - true if Disable all Samplers is off, false if on. Note: Changing the render scene dialog settings via the scripter should be done with the actual render scene dialog in a closed state. Leaving the dialog open will make the attempted scripter modifications non-sticky.

3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters

The following Filter class values are available as 3ds max Scanline A-Buffer renderer anti-aliasing filters. The renderer anti-aliasing filter is accessed using the following 3ds max system global variable:
scanlineRender.antiAliasFilter

Lets you get and set the anti-aliasing filter. For a list of all of the anti-aliasing filters you can say:
showClass *:filter*

For example:
scanlineRender.antiAliasFilter = quadratic()

Constructors and Properties:

Area: Area() Blackman: Blackman()

3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters

1615

Blendfilter: Blendfilter ... <Blendfilter>.Blend Catmull_Rom: Catmull_Rom() Cook_Variable: Cook_Variable() Cubic: Cubic()

Float

default: 0.3

Mitchell_Netravali: Mitchell_Netravali ... <Mitchell_Netravali>.Blur <Mitchell_Netravali>.Ringing

Float Float

default: 0.3333 default: 0.3333

Plate_Match_MAX_R2: (3ds max only) Plate_Match_MAX_R2() Plate_Match_VIZ_R2: (3D Studio VIZ only) Plate_Match_VIZ_R2() Quadratic: Quadratic() Sharp_Quadratic: Sharp_Quadratic() Soften: Soften() Video: Video()

Schematic View
The Schematic View window functions are in a structure package named schematicView. These functions operate on named Schematic Views, and in many cases you identify the Schematic View window by this name. The Schematic View functions are:
schematicView.open <name_string>

Opens an existing Schematic View with the specified name, or creates a new Schematic View with specified name. Returns the value true.
schematicView.zoomSelected <name_string>

Zooms the named Schematic View on the currently selected objects. The display is zoomed such that all of the selected objects are displayed. If there are no selected objects, no operation occurs. This method will return true, except when the named Schematic View does not exist or is not open, when it returns false.

1616

Chapter 13

Interacting with the 3ds max User Interface

schematicView.close <name_string>

Closes the named Schematic View. This method will return true, except when the named Schematic View does not exist or is not open, when it returns false.
schematicView.numSchematicViews()

Returns the number of named Schematic Views defined

schematicView.getSchematicViewName <index_integer>

Returns the name of the indexed Schematic View as a String. Index values are 1-based.

Time Configuration Dialog

The following methods get and set options in the Time Configuration dialog:
getKeyStepsPos() setKeyStepsPos <boolean>

Get and set whether to jump to next position key when Key Mode Toggle is on.
getKeyStepsRot() setKeyStepsRot <boolean>

Get and set whether to jump to next rotation key when Key Mode Toggle is on.
getKeyStepsScale() setKeyStepsScale <boolean>

Get and set whether to jump to next scale key when Key Mode Toggle is on.
getKeyStepsSelOnly() setKeyStepsSelOnly <boolean>

Get and set whether to use Selected Objects Only when Key Mode Toggle is on.
getKeyStepsUseTrans() setKeyStepsUseTrans <boolean>

Get and set whether to Use Current Transform when Key Mode Toggle is on. The following 3ds max system global variables are applicable to the Time Configuration dialog:
animationRange

Lets you get and set an Interval value that defines the start and end of the current active animation range. It contains the corresponding values set in the Time Configuration dialog.
frameRate

Lets you get and set an Integer value that defines the current scene frame rate in framesper-second. It contains the corresponding value set in the Time Configuration dialog.
playActiveOnly

Lets you get and set whether to playback the active viewport only. It contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Active Viewport Only is on, false if off.
realTimePlayback

Lets you get and set whether to playback in real time mode. It contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Real Time is on, false if off.

3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters

1617

timeConfiguration.playActiveOnly

Lets you get and set whether to playback the active viewport only. It contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Active Viewport Only is on, false if off.
timeConfiguration.playbackSpeed

Get/set viewport playback speed as an indexed <integer>. The valid values for theinteger are: 1 - 1 / 4x, 2 - 1 / 2x, 3 - 1x, 4 - 2x, 5 - 4x.
timeConfiguration.realTimePlayback

Lets you get and set whether to playback in real time mode. It contains the corresponding value set in the Time Configuration dialog. A Boolean value - true if Real Time is on, false if off.
timeConfiguration.useTrackBar

Lets you get and set the state of the Time Configuration dialog Key Steps / Use TrackBar check box. A Boolean Value true if checked, false if not.

RAMPlayer
The following method is associated with the RAMPlayer:
RAMPlayer <filename1_string> <filename2_string>

Opens RAMPlayer with filename1 as Channel A and filename2 as Channel B. You can pass a null string () as a filename string, in which case no file is loaded into that channel.

Track View Pick Dialog

The Track View Pick dialog displays the hierarchy for the 3ds max scene in a manner similar to what is seen in Track View. The user can select one or more items from this dialog. The following method displays the Track View Pick dialog:
trackView.pickTrackDlg [#multiple]

This method brings up the Track View Pick dialog and returns a TrackViewPick value when the user selects a track and clicks Ok, or undefined if the user clicks Cancel. If the optional argument #multiple is passed, multiple tracks can be picked in the dialog and an array of TrackViewPick values is returned instead of single value. TrackViewPick : Value Instances of the TrackViewPick class store the result of a selection from the Track View Pick dialog. A TrackViewPick value has the following properties:
<trackViewPick>.name <trackViewPick>.anim <trackViewPick>.client : string : subAnim : MAXWrapper

The name of the picked item as shown in the Track View Pick dialog. The subAnim for the item the user picked. The owner of the subAnim for the item the user picked. If the owner is a subclass of MAXWrapper, the MAXWrapper value for the owner is returned, otherwise a value of undefined is returned.

1618

Chapter 13

Interacting with the 3ds max User Interface

<trackViewPick>.subNum

: integer

The subAnim index for anim in client. Here is an example:

-- Create a sphere and apply a bend modifier and execute tvp=trackview.pickTrackDlg() -- pick objects->Sphere01->Modified object->Bend->Angle tvp.anim -- returns SubAnim:Angle tvp.client -- returns Bend:Bend tvp.subNum -- returns 3 tvp.name -- returns Angle tvp.client[tvp.subNum] -- returns SubAnim:Angle

Picking Scene Nodes

Picking Scene Nodes By Hit
pickObject [ message:<string> ] [ prompt:<string> ] \ [count:n|#multiple] [ filter:fn ] \ [ select:<boolean> ]

The pickObject() function lets the user pick one or more scene objects in the 3ds max viewports. It takes several optional keyword arguments. The message: argument takes a string value which is displayed in the status bar prompt line. The prompt: argument takes a string value which is displayed in the Listener window. The count: argument takes either a positive integer or the symbol #multiple to specify how many objects are to be picked (default is 1). If the count specified is greater than 1 or the value #multiple, an array is returned containing the picked objects. The symbol #multiple indicates that any number of objects can be selected and the user terminates the selection with a right mouse click or, if the Listener window has focus, any character key of the keyboard. If the ESC key is pressed while the Listener windows has focus, an #escape value will be returned. If the ESC key is pressed while a viewport has focus, selection is terminated and the selection result is returned. If #multiple was specified, and no objects had been selected when the selection was terminated, an empty array is returned. If #multiple was not specified, and an object had not been selected when the selection was terminated, a value of undefined is returned.

Picking Scene Nodes by Name

1619

The filter: function takes a MAXScript function of one argument that is called whenever the cursor is over an object in the scene and is passed that object under the cursor. It returns true if the object is eligible for picking, or false if not. Typically, the function would contain some object class testing, for example:
fn shapeFilt o = superClassOf o == Shape

which you could use like this:

pickObject prompt:enter a shape filter:shapeFilt

The optional keyword argument select: controls whether the picked objects become the new current selection in the 3ds max scene. If you supply true for that argument, the current selection is replaced with the objects that you pick. The default is false in which case the picker doesnt affect the selection set.

Picking Scene Nodes by Name

You can use the selectByName() function to open the standard 3ds max Select By Name dialog allowing users to pick objects which are then returned as an array of MAXScript node values. The form is:
selectByName [ title:<string> ] [ buttonText:<string> ] [ filter:<fn>] [ showHidden:<boolean> ] [ single:<boolean>] \ \

The optional keyword arguments are interpreted as follows: title:string specifies the dialog window title. buttonText:string lets you specify the label text in the accept button in the dialog. The default value is Select. filter:<fn> lets you specify a filter function that determines which objects should be displayed in the list. This is similar to the filter functions elsewhere in MAXScript. The function you supply should take one argument, which the current object being tested for inclusion and the function should return true for include, false for exclude. If you dont specify a filter, all objects are displayed. For example, the following function limits the choices to shape objects:
fn shape_filt obj = isKindOf obj Shape

showHidden:<boolean> controls whether hidden and frozen objects are eligible for display. The default value is false. single:<boolean> controls whether single or multiple objects may be selected in the selector. The default is false, meaning multiple objects may be selected, and they are returned in an array. If single:true is specified, a single object may be selected and is returned directly, not in an array. If the user cancels out of the dialog, the function returns the value undefined.

1620

Chapter 13

Interacting with the 3ds max User Interface

Picking Scene Nodes By Region

The following methods allow you to pick one or more objects based on their position in the viewports. All coordinates used in these methods are in Windows format, with the origin in the upper left. The gw.getWinSizeX() and gw.getWinSizeY() methods can be used to determine the size of the viewport in pixels. The objects to picked are filtered based on the Selection Filter specified in the 3ds max main toolbar.
boxPickNode <box2> [crossing:<boolean>]

Returns an array of the nodes within the specified rectangular region. The <box2> value specifies the corner in pixel values within the active viewport. If the crossing: parameter value is true, an object only partially in the region will be picked. If false, the object must be completely within the region to be picked. The default crossing: value is true. For example:
boxPickNode (box2 [0,0] [1000,1000]) circlePickNode <box2> [crossing:<boolean>]

Returns an array of the nodes within the specified circular region. The <box2> value specifies the center of the circle and a point on the circle in pixel values within the active viewport. If the crossing: parameter value is true, an object only partially in the region will be picked. If false, the object must be completely within the region to be picked. The default crossing: value is true. The [left, bottom] and [right, top] components of the box2 parameter value correspond to the center and radius points, respectively. The box2 parameter value needs to be set up in a specific manner, as shown in the following script:
vpCenter = (point2 (gw.getWinSizeX()) (_gw.getWinSizeY()))/2 vpQuarter = point2 (vpCenter.x/2) vpCenter.y circleRegion = box2 0 0 0 0 -- initialize circleRegion to a box2 value circleRegion.left = vpCenter.x -- the center of the circle circleRegion.bottom = vpCenter.y circleRegion.right = vpCenter.x/2 -- a point on the circle circleRegion.top = vpCenter.y for obj in (circlePickNode circleRegion crossing:false) do print obj.name

will print the names of all nodes completely within a circular region, where the center of the circle is the center of the viewport and the point on the circle is located one quarter of the distance from the edge to the center of the viewport.
fencePickNode <point2_array> [crossing:<boolean>]

Returns an array of the nodes within the specified fenced region. The fenced area is defined by the array of point2 values. The default crossing: value is true.

Picking Scene Nodes By Region

1621

Miscellaneous Dialogs
For methods associated with the Render Effects dialog, see the RenderEffect : MAXWrapper (p. 1347) topic. For methods associated with the Render Environment dialog, see the Atmospheric : MAXWrapper (p. 1337) topic.
exclusionListDlg()

Displays the Exclude/Include dialog used for Lights, and returns an array of the node names moved into the Include/Exclude list.
configureBitmapPaths()

This method puts up the Configure Bitmap Paths dialog to let the user configure the bitmap loading paths. Returns false if the user cancels out of the Configure Bitmap Paths dialog, true otherwise.
materialBrowseDlg [#mats] [#maps] [#incNone] [#instanceOnly]

This method puts up the Material/Map Browser. This method returns undefined if no Material or TextureMap is picked, otherwise a copy or instance of the Material or TextureMap is returned. The definition of the parameters are:
#mats

Display Materials only.

#maps

Display TextureMaps only.

#incNone

Include None as a Material and TextureMap.

#instanceOnly

If the selected Material or TextureMap already exists, the returned value contains an instance. Otherwise a dialog is displayed for the user to specify Copy or Instance. If neither #mats or #maps is specified, both Materials and TextureMaps are displayed. If both are specified, TextureMaps are displayed.
mtlBrowser.browseFrom [#mtlLibrary | #mtlEditor | #activeSlot | #selected | #scene | #new]

Lets you set the Browse From: source for the modeless material browser.
nodeColorPicker()

This method displays the Object Color picker dialog, and returns the selected color as a Color value.
OSnap()

This method displays the Grid and Snap Settings dialog.

USetup()

This method displays the Units Setup dialog.

1622

Chapter 13

Interacting with the 3ds max User Interface

MAXScript Message and Query Dialogs

These functions let you display a message box or a yes/no query dialogs from within MAXScript.
messageBox <message_string> [ title:<window_title_string> ] \ [ beep:<boolean> ]

displays a modal message box containing the message string and an OK button. The message box window title an be set with the title: keyword parameter. You can control whether a beep is made with the beep: keyword parameter, which defaults to true.
queryBox <message_string> [ title:<window_title_string> ] \ [ beep:<boolean> ]

displays a modal message box similar to the one that the messageBox() function creates, except it contains a Yes and a No button. The queryBox() function returns true if the user clicks Yes and false if the user clicks No.
yesNoCancelBox <message_string> [ title:<window_title_string> ] \ [ beep:<boolean> ]

displays a modal message box similar to the one that the messageBox() function creates, except it contains a Yes, a No, and a Cancel button. The yesNoCancelBox() function returns #yes, #no or #cancel depending on which button the user clicked to dismiss the message box. Examples:
messageBox You shouldnt have done that if queryBox Do you want to continue? beep:false then ...

Notes: In some cases, MAXScript statements occurring after a statement containing one of the above dialog function calls may be executed before they are supposed to be. For example, if your execute: Script:
for _t=0 to 3 do ( messagebox Press Me format _t= %\n _t ) print Should print last

Listener will show: Output:

_t= 0 Should print last Should print last _t= 1 _t= 2 _t= 3

And the MessageBox will be displayed 4 times, once each time before the value of _t is printed to Listener.

Picking Scene Nodes By Region

1623

The reason for this is that Listener is looking for expressions to compile and run in a background thread. In the above example there are 2 expressions the for loop expression and the final print expression. The messageBox() function goes on waiting for and processing UI events in the main UI thread, but the compiler has already compiled ahead and scheduled the print Should print last. To prevent this out-of-order execution, you need to bracket the script in parenthesis. This will force the sequencing to be correct because the script would now contain a single expression rather than two.

Keyboard Entry
The following are keyboard input functions for doing simple interactivity directly in the Listener or Mini Listener. All keyboard input functions take input from Mini Listener if Listener is closed, but if it is open, input will always be taken from Listener.
getKBValue [ prompt:<string> ]

The getKBValue() function lets the user enter a MAXScript value into the Listener. The optional prompt: keyword argument takes a string that is displayed in the Listener as a prompt message. Any valid MAXScript expression can be entered into the Listener and is evaluated to become the result of the getKBValue() function. Expressions include the literals for integer, float, string, name, array, point2, point3, and scene object pathnames, or they can be expressions involving math operations and functions, script supplied functions, global variables, etc. You can test the type of value returned using MAXScripts classOf function. Example:
v = getKBValue prompt:Enter object count: if classOf v != integer then print Value entered must be an integer

The user can abort the entry by pressing the ESC key in which case the function returns the special value #escape.
getKBLine [ prompt:<string> ] getKBChar [ prompt:<string> ]

These functions let the user type characters into the Listener that are returned as a MAXScript string. getKBLine() returns all the characters up until the user presses ENTER, getKBChar() returns each character immediately as it is entered. The user can abort the entry by pressing the ESC key in which case the function returns the special value #undefined.
getKBPoint [ prompt:<string> ]

This function lets the user type in a 3D point in the syntax supported by the pickPoint() function. See the pickPoint() description above for details about the syntax. The function interprets the 3D point as relative to the current active grid construction plane and returns a Point3 in world-coordinates.

1624

Chapter 13

Interacting with the 3ds max User Interface

The following are system global variables related to the keyboard:

keyboard.shiftPressed keyboard.controlPressed keyboard.altPressed

These variables access the current state of the keyboard shift keys and return true or false depending on the pressed state of the key at the time the variable is read and are read-only variables.

Macro Scripts
The Macro Script functions are in a structure package named macros. These functions allow you to access and run Macro Scripts. See the Defining Macro Scripts (p. 1521) topic for information on creating Macro Scripts. The Macro Script functions are:
macros.load [ <path_name_string> ]

Loads all of the Macro Script definition (.mcr) files in the current UI directory path, or in directory path specified by <path_name_string>. You can get the current UI directory path with the function:
local ui_dir = cui.getDir () macros.new <name_string> <category_string> <toolTip_string> \ <buttonText_string> <body_string>

Creates a new Macro Script with the specified name and category. Returns an Integer Macro Script ID value that uniquely identifies the new Macro Script. See the Defining Macro Scripts (p. 1521) topic for a description of Macro Script definitions.
macros.run <category_string> <name_string> macros.run <macro_id_integer>

Executes the specified Macro Script. The Macro Script is identified by either its category and name, or by its unique Macro Script ID value.
macros.edit <category_string> <name_string> macros.edit <macro_id_integer>

These methods will open the Macro Script definition (.mcr) file that defines the specified Macro Script in a script Editor window. The Macro Script is identified by either its category and name, or by its unique Macro Script ID value. Example:
macros.load f:/gametools/macros macros.edit objects box macros.run 132 macros.run modifiers bend

Picking Scene Nodes By Region

1625

3ds max System Directories

The following methods allow you to access the 3ds max system directories:
GetDir <filetype_name>

Returns as a string the directory specified in the Customize > Configure Paths dialog for the specified file type. The valid <filetype_name> values are:
#autoback #drivers #export #expression #font #help #image #import #matlib #maxroot #maxstart #plugcfg #preview #scene #scripts #sound #startupScripts #ui #vpost

The following functions let you get, add or delete Bitmap and XRef paths, corresponding to the Bitmaps and XRefs tabs in the Configure Paths dialog in 3ds max . Any changes made through these functions are immediately reflected in the 3dsmax.ini file and so are persistent.
mapPaths.add <path_string>

Appends the specified path to the list of Bitmap search paths.

mapPaths.count()

Returns the number of Bitmap search paths defined.

mapPaths.get <index>

Returns the indexed Bitmap search path as a string. The index is 1-based.
mapPaths.delete() <index>

Deletes the indexed Bitmap search path. The index is 1-based.

sysinfo.getSystemMemoryInfo()

Returns a 7 element array containing system memory status data. The array elements contain the following, respectively: percent of memory in use bytes of physical memory free physical memory bytes bytes of paging file

1626

Chapter 13

Interacting with the 3ds max User Interface

free bytes of paging file user bytes of address space free user bytes Example:
( r=sysinfo.getSystemMemoryInfo() for i=2 to 7 do r[i] /= (1024*1024.) format percent of memory in use:\t%\n r[1] format total physical memory:\t% MB\n r[2] format free physical memory:\t% MB\n r[3] format used physical memory:\t% MB\n (r[2]-r[3]) format total paging file size:\t% MB\n r[4] format free paging file size:\t% MB\n r[5] format used paging file size:\t% MB\n (r[4]-r[5]) format total virtual memory:\t% MB\n r[6] format free virtual memory:\t\t% MB\n r[7] format used virtual memory:\t\t% MB\n (r[6]-r[7]) ok )

Returns:
percent of memory in use:0 total physical memory:255.359 MB free physical memory:16.5156 MB used physical memory:238.844 MB total paging file size:1016.3 MB free paging file size:757.898 MB used paging file size:258.398 MB total virtual memory:2047.88 MB free virtual memory:1846.55 MB used virtual memory:201.328 MB OK sysinfo.getMAXMemoryInfo()

Returns a 9 element array containing 3ds max memory status data. The array elements contain the following, respectively: Page Fault Count Peak Working Set Size Working Set Size Quota Peak Paged Pool Usage Quota Paged Pool Usage Quota Peak NonPaged Pool Usage Quota NonPaged Pool Usage Pagefile Usage Peak Pagefile Usage

Picking Scene Nodes By Region

1627

Example:
( r=sysinfo.getMAXMemoryInfo() for i=2 to 9 do r[i] /= (1024*1024.) format Page Fault Count:\t\t\t%\n r[1] format Peak Working Set Size:\t\t% MB\n r[2] format Working Set Size:\t\t\t% MB\n r[3] format Quota Peak Paged Pool Usage:\t% MB\n r[4] format Quota Paged Pool Usage:\t\t% MB\n r[5] format Quota Peak NonPaged Pool Usage:\t% MB\n r[6] format Quota NonPaged Pool Usage:\t\t% MB\n r[7] format Pagefile Usage:\t\t\t% MB\n r[8] format Peak Pagefile Usage:\t\t\t% MB\n r[9] ok )

Returns:
Page Fault Count:32948 Peak Working Set Size:70.3594 MB Working Set Size:70.3594 MB Quota Peak Paged Pool Usage:0.166186 MB Quota Paged Pool Usage:0.161236 MB Quota Peak NonPaged Pool Usage:0.0213509 MB Quota NonPaged Pool Usage:0.0213509 MB Pagefile Usage:58.9023 MB Peak Pagefile Usage:58.9219 MB xrefPaths.add <path_string>

Appends the specified path to the list of XRef search paths.

xrefPaths.count()

Returns the number of XRef search paths defined.

xrefPaths.get <index>

Returns the indexed XRef search path as a string. The index is 1-based.
xrefPaths.delete <index>

Deletes the indexed XRef search path. The index is 1-based.

1628

Chapter 13

Interacting with the 3ds max User Interface

3ds max Scene File Properties

The File Properties can be accessed in MAXScript using the methods described in this topic. The File Properties are organized into three sets. These sets do directly does not correspond to the three pages in File Properties dialog. The three sets are:
#summary

This set contains the Title, Subject, Author, Keywords, Comments fields from the Summary page.
#contents

This set contains the Manager, Company, Category and an array of all headers from the Contents page like General, Mesh Totals etc. Note that the Contents page contents are only update when the file is saved. You can perform a max hold to perform a scene hold, which causes the file to be saved and the Contents page contents to be updated.
#custom

This set contains all the fields from the Custom page. The following methods are used to access the above sets. <set_name> can be any of the values from above.
fileProperties.getNumProperties <set_name>

Returns the number of properties in the given set. For example:

numProps=fileProperties.getNumProperties #summary fileProperties.getPropertyName <set_name> <index>

Returns as a string the property name of the given index. The index is 1-based. For example:
nameProp=fileProperties.getPropertyName #summary 1 fileProperties.getPropertyValue <set_name> <index>

Returns the property value of given index. The value type can be one of the following four types of values currently supported by 3ds max in the File Properties dialog. The values in bracket are the MAXScript equivalent value type. Property Value Types:
Text Date Number Yes or No Headers [String] [String] - contains the date eg:03/23/99 [Integer or Float based on actual value] [Boolean] [Array of strings]

Headers are items like General, Mesh Totals, etc. that appear in contents page. For example, an array of headers from contents page obtained using:
getPropertyValue #contents Headers

will return
#(General, Mesh Totals,)

Picking Scene Nodes By Region

1629

fileProperties.getItems <header_string>

Returns an array of strings containing all the items under the given header. For example,
fileProperties.getItems Mesh Totals

might return
#(Vertices: 488, Faces: 968) fileProperties.findProperty <set_name> <prop_name_string>

Given the set name and property name string, will return the index of the property if found, 0 if not found. For example:
fileProperties.findProperty #custom BoolVal fileProperties.addProperty <set_name> <prop_name_string> \ <prop_value> [#date]

Adds a new property with the property name and property value to the specified set. The property values can be any of the types previously described except an Array as you cannot add anything to contents page. If string containing a date is passed then the optional #date argument has to be passed for it to be added as a date value. For example,
fileProperties.addProperty #custom DateVal 03/23/99 #date

will add a date property named DateVal to the custom page.

fileProperties.deleteProperty <set_name> <prop_name_string>

Delete the property indicated by <prop_name_string> in the specified set. Following is an example of printing all the File Properties in an hierarchial fashion for the current scene. Script:
-- Add some properties fileProperties.addProperty #summary Title Title val fileProperties.addProperty #custom IntVal 30 fileProperties.addProperty #custom FloatVal 30.034 fileProperties.addProperty #custom BoolVal true fileProperties.addProperty #custom DateVal 03/23/99 #date --- Perform a scene hold to update the Contents set. max hold --- Get all properties pages = #(#summary, #contents, #custom) for pg in pages do ( format --- % ---\n (pg as string) for i=1 to (fileProperties.getNumProperties pg) do ( local pname = (fileProperties.getPropertyName pg i) local pval = (fileProperties.getPropertyValue pg i)

1630

Chapter 13

Interacting with the 3ds max User Interface

format \t% : pname if (pname == Headers) then ( format \n for hdr in pval do ( format \t\t%\n hdr local docs = fileProperties.getItems hdr if docs != undefined then for d in docs do format \t\t\t%\n d ) ) else format %\n pval ) )

3ds max Commands

The general syntax for 3ds max commands is:
max <command_name>

MAXScript allows you to invoke 3ds max menu and toolbar commands from within scripts using the max construct. For example:
max max max max file open unhide all hold time play

The keyword max is followed by one or more words that describe the command. The available commands can be displayed using the ? character in a partial max command:
max time ? max sel ? max ? -- show all the time-related commands -- show all the commands with sel in them as a substring -- show all the commands (there are a lot!)

The max command always returns the system value ok.

Picking Scene Nodes By Region

1631

Note: The max spacebar max command appears to do nothing when invoked from the Listener window, because the spacebar command is window-specific and only locks selections in the active window. Because it is the Listener window that is active, 3ds max effectively ignores this command.
3ds max Command Name max ? max accel pan max acthomegrid max activate home grid max activate grid object max adaptive persp grid max adaptive perspective grid toggle max align max align normals max alignnormals max align camera max angle snap toggle max apply ik max array max backface max backface cull toggle max background max background display toggle max bind space warp mode max bindwsm max box mode max box mode selected max box mode toggle max box toggle max configure paths max create mode max customize UI max cycle select max cycle sublevel max cycle subobject level max default lighting toggle max def lgt toggle max delete max display floater max display mode Command description Displays all max commands to listener Activates viewport Pan mode Makes home grid the active grid Makes selected grid the active grid Changes look of grid in non-orthographic viewports. Activates Align mode Activates Align Normals mode Places you in Align Camera mode Toggles Angle Snap toggle Same as clicking Apply IK button in Hierarchy/IK panel Displays Array dialog Toggles Backface Cull for selected objects Displays Viewport Background dialog Activates Bind to Space Warp mode Toggles Display as Box for selected objects Toggles active viewports shading mode to/from Bounding Box Displays Configure Paths dialog Sets Create command mode active Displays Customize User Interface dialog Cycles through Selection Region types Rectangular, Circular, Fence Cycles through sub-object levels. Must be in Modify panel with Sub-Object active. Toggles between default viewport lights and scene lights for viewport rendering Deletes selected objects or sub-objects Displays Display Floater dialog Sets Display command mode active

1632

Chapter 13

Interacting with the 3ds max User Interface

3ds max Command Name max dolly max dolly mode max drawingaids max drawing aids max fetch max file archive max file export selected max file import max file insert tracks max file merge max file new max file open max file preferences max file replace max file save max file saveas max file xref object max file xref scene max fov max freeze inv max freeze selection max fullinteract max grid nudge down max grid nudge up max grid toggle max grids align max group attach max group close max group detach max group group max group open max group ungroup max help about max hide camera toggle max hide command panel toggle

Command description Activates Zoom/Dolly mode Displays Grid and Snap Setting dialog Activates Edit/Fetch displays About to Fetch dialog Activates File/Archive performs a scene file archive operation Activates File/Export Selected displays Select File to Export dialog Activates File/Import displays Select File to Import dialog Activates File/Merge displays Merge Animation dialog Activates File/Merge displays Merge File dialog Activates File/New Activates File/Open displays Open File dialog Activates Customize/Preferences displays Preference Settings dialog Activates File/Replace displays Replace File dialog Activates File/Save Activates File/Save As displays Save File As dialog Activates File/XRef Objects - displays XRef Objects dialog Activates File/XRef Scenes - displays XRef Scenes dialog Activates Region Zoom/FOV/Falloff mode Freezes non-selected objects. Same as clicking Freeze Unselected in Display panel. Freezes selected objects. Same as clicking Freeze Selected in Display panel. No operation Nudges active grid down Nudges active grid up Toggles display of active grid in active viewport Aligns active grid to active viewport Enters Attach Object to Group mode user clicks on group to attach selected objects to the group Closes active group Detaches selected objects from group Groups selected objects displays Group dialog Opens selected group Ungroups objects in selected group Activates Help/About displays the About 3ds max dialog Toggles Camera in Hide by Category rollout in Display panel. Toggles display of command panel

Picking Scene Nodes By Region

1633

3ds max Command Name max hide floating toolbars toggle max hide helper toggle max hide inv max hide light toggle max hide main toolbar toggle max hide object toggle max hide tab panel toggle max hide selection max hide shape toggle max hide system toggle max hide wsm toggle max hierarchy mode max hold max ik terminator max ipan max izoom in max izoom out max key mode max link max load custom UI max lock UI layout max material browser max mirror max modify mode max motion mode max move max mtledit max next mod max override max pancamera max panview max persp max prev mod

Command description Toggles display of floating toolbars Toggles Helpers in Hide by Category rollout in Display panel. Hides un-selected objects. Same as clicking Hide Unselected in Display panel. Toggles Lights in Hide by Category rollout in Display panel. No operation Toggles Geometry in Hide by Category rollout in Display panel. Toggles display of Tab Panel Hides selected objects. Same as clicking Hide Selected in Display panel. Toggles Shapes in Hide by Category rollout in Display panel. Toggles Particle Systems in Hide by Category rollout in Display panel. Toggles Space Warps in Hide by Category rollout in Display panel. Sets Hierarchy command mode active Activates Edit/Hold Toggles Terminator in Hierarchy/IK, Object Parameters rollout Interactive Pan places center of active viewport at current mouse location Interactive Zoom In zooms in active viewport at current mouse location Interactive Zoom Out zooms out active viewport at current mouse location Toggles Key Mode Toggle Activates Link mode Activates Customize/Load Custom UI displays Load UI File dialog Toggles locking of the UI layout Displays the Material/Map Browser dialog Activates Mirror mode displays Mirror dialog Sets Modify command mode active Sets Motion command mode active Activates Select and Move mode Activates Tools/Material Editor displays Material Editor dialog Moves up one level in modifier stack Toggles Degradation Override. Executing this command works on the active window only, so if executed from Listener does nothing. Activates Arc Rotate/Orbit mode Activates Pan/Truck mode Activates Zoom All/Perspective/Hotspot mode Moves down one level in modifier stack

1634

Chapter 13

Interacting with the 3ds max User Interface

3ds max Command Name max preview max properties max quick render max redo max renamepreview max render last max render scene max reset file max revert custom UI max rns max roll max rotate max rotateview max save custom UI as max safeframe toggle max saveplus max scale max scale cycle max select max select all max select by color max select child max select invert max select none max select parent max selection floater max shade selected max show last img max showaxisicon max showhomegrid max snap toggle max spacebar max spacing tool max spinsnap toggle max subobject sel

Command description Activates Rendering/Make Preview displays Make Preview dialog Displays Object Properties dialog Performs Quick Render Performs Redo operation Activates Rendering/Rename Preview displays Save Preview As dialog Performs Render Last Activate Render Scene displays Render Scene dialog Activates File/Reset Activates Customize/Revert to Startup UI displays confirmation dialog Activates Edit/Edit Named Selections displays Edit Named Selection dialog Activates Roll mode active viewport must camera or light viewport Activates Select and Rotate mode Activates Arc Rotate/Orbit mode Activates Customize/Save Custom UI As - displays Save UI File as dialog Toggles viewport Show Safe Frames Activates File/Save As in incremental file naming mode Activates Select and Scale mode Cycles through Scale modes Scale, Non-Uniform Scale, Squash Activates Select mode Activates Edit/Select All selects all objects Activates Edit/Select by Color user then picks object, all objects with same wireframe color selected Selects all 1st level children of currently selected objects Activates Edit/Select Invert Activates Edit/Select None Selects parents of currently selected objects Displays Selection Floater dialog Toggles Views/Shade Selected Displays last rendered image Toggles Views/Show Transform Gizmo Toggles display of home grid Toggles Snap Toggle Toggles Lock Selection Set. Executing this command works on the active window only, so if executed from Listener does nothing. Displays Spacing Tool dialog Toggles Spinner Snap Toggle Toggles Sub-Object button in Modify panel

Picking Scene Nodes By Region

1635

3ds max Command Name max swap layouts max texture correct max time back max time config max time end max time forward max time play max time start max toggle key mode max toggle keyboard shortcuts max toggle ik max toggle sound max tool animmode max tool center max tool dualplanes max tool hlist max tool maximize max tool x max tool xy max tool y max tool z max tool zoom max tool zoomall max tool zoomextents max tool zoomextents all max tool zoomregion max trajectories max treeview max truck max tti max undo max unfreeze all max unfreeze by hit max unfreeze by name

Command description No operation no A/B layout any more Toggles viewport Texture Correction Sets time slider to previous frame or keyframe (Previous Frame/Previous Key) Displays Time Configuration dialog Sets time slider to end frame (Go to End) Sets time slider to next frame or keyframe (Next Frame/Next Key) Plays animation Sets time slider to start frame (Go to Start) No operation Toggles Plug-in Keyboard Shortcut Toggle Toggles IK Toggle Toggles Active in Audio group of Sound Options dialog Taggles Animate button Cycles through transform centers Pivot Point, Selection, Transform Toggles state of Use Dual Planes in Preference Settings dialog, Viewports tab. Activates Select by Name displays Select Objects dialog Maximizes/Minimizes active viewport Activates Restrict to X Activates Restrict to XY Activates Restrict to Y Activates Restrict to Z Activates Zoom/Dolly mode Activates Zoom All Activates Zoom Extents Activates Zoom Extents All Activates Zoom Region/FOV/Falloff mode Toggles trajectory display for selected objects Activates Track View/Open Track View displays Track View dialog Activates Pan/Truck mode Activates Tools/Transform Type-In display Transform Type-In dialog Performs undo operation Unfreezes all objects. Same as clicking Unfreeze All in Display panel. Activates Unfreeze by Hit mode. Same as clicking Unfreeze by Hit in Display panel. Displays Unfreeze Objects dialog. Same as clicking Unfreeze by Name in Display panel.

1636

Chapter 13

Interacting with the 3ds max User Interface

3ds max Command Name max unhide all max unhide by name max unitsetup max unlink max utility mode max videopost max view file max view redo max viewpreview max views redraw max views undo max vpt back max vpt bottom max vpt camera

Command description Unhides all objects. Same as clicking Unhide All in Display panel. Displays Unhide Objects dialog. Same as clicking Unhide by Name in Display panel. Activates Customize/Units Setup displays Units Setup dialog Unlinks selected objects from their parents Sets Utility command mode active Activates Rendering/Video Post displays Video Post dialog Activates File/View File displays View File dialog Performs viewport redo operation Activates Rendering/View Preview displays last preview Redraws all viewports Performs viewport undo operation Sets active viewport to Back Sets active viewport to Bottom Sets active viewport to Camera. If only 1 camera in scene, or a camera is selected, that camera will be used for the viewport. If there is more than one camera, and no cameras are selected, the Select Camera dialog will be displayed. If there is no camera in the scene, a No Camera in Scene warning is displayed. Toggles Disabled state of active viewport Sets active viewport to Front Sets active viewport to Grid Sets active viewport to User Sets active viewport to Left Sets active viewport to Perspective Sets active viewport to Right Sets active viewport to Shape Sets active viewport to Spotlight. If only 1 spotlight/directional light in scene, or a spotlight/directional light is selected, that light will be used for the viewport. If there is more than one spotlight/directional light, and no lights are selected, the Select Light dialog will be displayed. If there is no spotlight/directional light in the scene, a No Light in Scene warning is displayed. Cycles between Restrict to axes X, Y, Z, XY Sets active viewport to Top Sets active viewport to Track View Activates Customize/Viewport Configuration - displays Viewport Configuration dialog Sets active viewport shading mode to Facets + Highlights Sets active viewport shading mode to Wireframe

max vpt disable max vpt front max vpt grid max vpt iso user max vpt left max vpt persp user max vpt right max vpt shape max vpt spot

max vpt tab max vpt top max vpt track max vptconfig max wire facet max wire smooth

Picking Scene Nodes By Region

1637

3ds max Command Name max zoom in 2x max zoom in 2x all max zoom out 2x max zoom out 2x all max zoomext sel max zoomext sel all

Command description Zooms in active viewport by 2x Zooms in all viewports by 2x Zooms out active viewport by 2x Zooms out all viewports by 2x Activates Zoom Extends Selected Activates Zoom Extends All Selected

1638

Chapter 13

Interacting with the 3ds max User Interface

Chapter 14:

File Access

3ds max File Loading and Saving

The following methods are used to load, save, merge, import, and export 3ds max scenes.
loadMaxFile <filename_string>

Returns true if the file was found and loaded successfully.

mergeMAXFile <filename_string> [ <name_array> ] [ #prompt ] \ [ [ #select ] #noRedraw ] \ [ #deleteOldDups | #mergeDups | #skipDups | #promptDups ]

All arguments are optional except the initial file name. The flag arguments can be specified in any order. The arguments details are as follows:
<name_array>

An optional array of names or strings identifying the objects in the source scene file to be merged; all objects are merged if not specified.
#prompt

If specified causes the standard merge dialog to be opened.

#select

If specified causes the newly merged objects to be selected when merged.

#noRedraw

If specified causes the screen redraw to be delayed in case you want to call mergeMAXFile several times and delay the redraw until after the last file merge.
#deleteOldDups

Deletes existing scene objects with the same names as incoming objects, equivalent to a replace.
#mergeDups

Ignore name conflicts, merge anyway resulting in possibly duplicated names.

1640

Chapter 14

File Access

#promptDups

Throw up the duplicates resolution dialog for the user to choose. Returns true if the file was found and loaded successfully. If you dont specify a full path name, the file is looked for in the 3ds max scene directory, then in the 3ds max executable directory, and then in the PATH environment directories.
getMAXSaveFileName filename: <seed_filename_string>

Displays standard 3ds max file save dialog, returns file name or value undefined if canceled.
getMAXOpenFileName filename: <seed_filename_string> dir:<seed_directory_string>

Displays standard 3ds max file open dialog, returns file name or value undefined if canceled.
getMAXFileObjectNames <max_filename_string>

Returns an array of names, one for each of the names of the objects in the given 3ds max file. This provides a way to get a preview list of the objects in another scene file (by name) to set up user selection of the objects to be merged under script control using the mergeMAXFile() function, for example. Example:
p=[1000,1000,1000] for i = 1 to 5 do box pos:(random p -p) -- create some boxes savemaxfile mergetest.max -- save to file for obj in objects do obj.name = _+obj.name -- rename the boxes objects.pos += [0,-1000,0] -- move them off to the side fobj_names = getmaxfileobjectnames mergetest.max -- get the object names from the file deleteitem fobj_names 3 -- delete the third name from the array mergemaxfile mergetest.max fobj_names #select -- merge in the objects and select them selection.count -- should be 4 objects.count -- should be 9 saveMaxFile <filename_string>

Saves the scene to the current 3ds max scene directory if there is no explicit directory path on the supplied file name. If no filename extension is specified, .max is automatically appended to the filename.
holdMaxFile()

Equivalent to the 3ds max Edit > Hold operation.

fetchMaxFile()

Equivalent to the 3ds max Edit > Fetch operation.

importFile <filename_string> [ #noPrompt ]

Lets you import files using any of the import plug-ins that are available. The kind of file imported is determined by the file name suffix such as DFX for .dxf, 3DS DOS for .3ds, etc. The #noPrompt flag prevents any configuration or control dialogs from being displayed in which case the default configuration is used.

Bitmap Files

1641

exportFile <filename_string> [ #noPrompt ]

Lets you export files using any of the export plug-ins that are available. The kind of file exported is determined by the file name suffix such as DFX for .dxf, 3DS DOS for .3ds, etc. The #noPrompt flag prevents any configuration or control dialogs from being displayed in which case the default configuration is used.
saveNodes <node_collection> <filename_string>

Creates a new .max scene file with the given name and stores the node collection to it. The <node_collection> argument can be a single node, an array of nodes you gathered, a wild-card path name, one of the built-in objects sets such as selection or lights, or a <node>.children array. If no filename extension is specified, .max is automatically appended to the filename.
checkForSave()

If the scene has been modified since the last file save (if any), calling this function displays the message box prompting the user that the scene has been modified and requests to save. Function returns false if the user cancels out of the save, true otherwise.

See also
External File Methods (p. 1645) File Name Parsing (p. 1644) Standard Open and Save File Dialogs (p. 1643)

Bitmap Files
The following method is used to collect a list of the bitmap files used in a scene. For the properties and methods associated with bitmap values, including reading and writing bitmap files, see the Bitmap Values (p. 755) topic.
enumerateFiles [ <maxwrapper_obj> ] <function> [ <arg> ] [ #inactive ] [ #videoPost ] [ #render ] [ #missing ] [ #localOnly ] \ \

Lets you run through all the bitmap files currently used in the scene or in an individual object. You can filter this so it just gives you those for video post or the renderer or the ones that are inactive or missing. The enumerator works by calling a function you give it once for each of the file names it finds corresponding to the filters switches and other arguments you set. The only required argument is the <function> argument. The details are:
<maxwrapper_obj>

An optional 3ds max object, such as a node or a material. Supplying this argument causes the enumerator to only consider files associated with this object. See the #localOnly switch for more info.

1642

Chapter 14

File Access

<function>

The function to be called for each file found. It should be a function of one or two arguments, the first one is the string file name supplied by the enumerator. See example below.
<arg>

If specified is passed to the <function> as its second argument by the enumerator. This is useful if you have a general purpose enumerator function that can be conditioned by the argument you pass in on a particular enumeration, or if you want to pass in an array that the found names should be appended to.
#inactive

Include the inactive files.

#videoPost

Include the files used in video post.

#render

Include the files used during rendering.

#missing

include files that are missing in the file system If you dont specify any of the above filter flags, all the files are enumerated.
#localOnly

use in conjunction with the <maxwrapper_obj> argument. If specified, limits the enumeration to those files used directly in the object, if not then any referenced objects are scanned. For example:
function get_names name a = append a name files = #() enumerateFiles get_names files #missing

Example: The following script will print out a sorted list of all the bitmap files used in the current scene file: Script:
( local mapfiles=#() fn addmap mapfile = ( local mapfileN=mapfile as name local index=finditem mapfiles mapfileN if index == 0 do append mapfiles mapfileN ) enumeratefiles addmap sort mapfiles for mapfile in mapfiles do print (mapfile as string) )

XRef Files

1643

By replacing line 8 with

enumeratefiles addmap #missing

only the missing bitmap files will be printed.

See also
External File Methods (p. 1645) File Name Parsing (p. 1644) Standard Open and Save File Dialogs (p. 1643)

XRef Files
See the XRefObject (p. 1037) and XRefScene (p. 1038) topics for information on XRef object and XRef scene files.

Text File Input and Output

See the FileStream Values (p. 763) topic for information on creating, opening, closing, and accessing external text files.

Standard Open and Save File Dialogs

The following methods display the standard 3ds max file open, file save, or folder selection browser dialog:
getOpenFileName [ caption:<title> ] \ [ filename:<seed_filename_string> ] \ [ types:<description1>|<pattern1>|<description2>|<pattern2>|...| ] getSaveFileName [ caption:<title>] \ [ filename:<seed_filename_string> ] \ [ types:<description1>|<pattern1>|<description2>|<pattern2>|...| ]

Both functions return a fully-specified file path name or undefined if the user cancels out. The types: parameter lets you specify custom file types and suffixes for the file type drop-down list in the open and save dialogs. You supply a string for this argument that is formatted in a special way, as follows:
<description1>|<pattern1>|<description2>|<pattern2>|...|

1644

Chapter 14

File Access

In other words, a sequence of file type descriptions and file type patterns each separated by a | vertical bar and terminated by a | vertical bar. For example:
f = getOpenFileName \ types:Data(*.dat)|*.dat|Excel(*.csv)|*.csv|All|*.*|

Specifies three types in the file type drop-down list, the first reading Data(*.dat) and matching *.dat and the second reading Excel(*.csv) and matching *.csv and the third reading All and matching any file. The getSaveFileName() function tests for the pre-existence of the file with the chosen file type suffix added.
getSavePath [ caption:<window_caption_string> ]

This function displays a folder selection browser for the user to select a folder. Returns a string path name for the selected folder or the value undefined if the user presses Cancel in the folder browser.

See also
Filestream Values (p. 763) External File Methods (p. 1645) File Name Parsing (p. 1644)

File Name Parsing

filenameFromPath <filename_string>

Returns the file name and extension of a full file name, useful for labeling file buttons in rollout panels.
getFilenamePath <filename_string>

Returns the directory path part of a full file name.

getFilenameFile <filename_string>

Returns the file name part of a full file name.

getFilenameType <filename_string>

Returns the type extension part of a full file name.

doesFileExist <filename_string>

Returns true if the file exists, false otherwise Examples:

file=g:\\subdir1\\subdir2\\myImage.jpg filenameFromPath file -- returns: myImage.jpg getFilenamePath file -- returns: g:\subdir1\subdir2\ getFilenameFile file -- returns: myImage getFilenameType file -- returns: .jpg

External File Methods

1645

See also
Filestream Values (p. 763) External File Methods (p. 1645) Standard Open and Save File Dialogs (p. 1643)

External File Methods

getFiles <wild_card_filename_string>

Returns an array of file names that match the given wild-card path name. The following example gets an array of all the .max scene files in c:\foo and then loops over the array, opening each file and printing the objects in each:
files = getFiles c:\\foo\\*.max for f in files do (loadMAXFile f; print objects)

getFiles() can also be used to determine if a file exists. For example, the following function will return true if the specified file name exists:
fn existFile fname = (getfiles fname).count != 0 getDirectories <wild_card_directory_name_string>

Returns an array of directory paths that match the given wild-card directory path name.
makeDir <directory_path_string>

Creates a new directory with the given name. Returns true on success, false on failure.
deleteFile <filename_string>

Deletes the named file. Fails if the file is open in MAXScript. Returns true on success, false on failure.
renameFile <old_filename_string> <new_filename_string>

Renames the old file to the new file. This can also be used to move a file between directories. Fails if new file already exists or if the old file is open in MAXScript. Returns true on success, false on failure.
copyFile <existing_filename_string> <new_filename_string>

Copies the existing file to the new file. Fails if the new file already exists, the new file cannot be created, or the existing file is open in MAXScript. Returns true on success, false on failure.

1646

Chapter 14

File Access

getFileAttribute <filename_string> <attribute> setFileAttribute <filename_string> <attribute> <boolean>

Get and set the attributes associated with a file. The get function returns true or false depending on the state of the specified attribute, the set function sets the state of the individual attribute specified (leaving other attributes as they were). The valid <attribute> values are:
#readOnly #hidden #system #directory #archive #temporary #normal getFileModDate <filename_string>

Returns a String value containing the modification date for the specified file, for example 1/29/99 1:52:05 PM.
getFileCreateDate <filename_string>

Returns a String value containing the creation date for the specified file.
getFileVersion <filename_string>

Returns the file and product version for the specified file, or unknown if this data is not specified in the file. This data is typically specified only for executable and application extension (i.e., .dll) files. For example:
GetFileVersion g:\\3dsmax25\3dsmax.exe

returns 2,5,0,0 2,5,0,0 Examples:

for f in getFiles 3dsmax\\maps\\*.jpg do deleteFile f for d in getDirectories D:\\foo\\* do for f in getFiles (d + *.*) do copyFile f (C:\\temp\\ + getFilenameFile f + getFilenameType f) if (getFiles foo.max).count == 0 then print File missing

See also
Filestream Values (p. 763) File Name Parsing (p. 1644) Standard Open and Save File Dialogs (p. 1643)

Encrypted Files

1647

Encrypted Files
encryptFile <in_filename_string> <out_filename_string> <key_integer>

Creates an encrypted copy of the file named by <in_filename_string> using the integer supplied as a key, naming the encrypted file <out_filename_string>.
openEncryptedFile <filename_string> <key_integer>

Opens the encrypted file using the given integer key and returns a FileStream value that you can then do read calls on, exactly as you can on FileStreams returned from the openFile() function. encryptFile() and openEncryptedFile() let you encrypt a text file with your own key and open an encrypted file via a key for reading. Among other things, you can use this to write and read an encrypted file containing a hardware lock ID for doing authorizationbased piracy protection. For example, heres some code that creates an encrypted lock ID file in some authorization process:
f = createFile lock.tmp format % hardwareLockID to:f close f encryptFile lock.tmp lock.dat 5476557 deleteFile lock.tmp

The following code can be used to read and check the lock ID (obviously, all this is only safe if the creation and checking scripts are themselves encrypted):
f = openEncryptedFile lock.dat 5476557 id = readValue f close f if id != hardwareLockID then ( message Lock IDs dont match return 0 )

Accessing INI File Keys

The following methods allow you to read and write key values in .INI files.
getINISetting <filename_string> <section_string> <key_string>

Reads an INI setting from the specified file. Within the file, the section identified by <section_string> is located, and then the key specified by the <key_string> is located. The value assigned to this key is then returned as a string. If the specified file, section, or key is not found, a null string is returned. For example:
GetINISetting c:\\3dsmax2\\3dsmax.ini Directories Scenes

If the specified file, section, or key is not found, a null string is returned.

1648

Chapter 14

File Access

setINISetting <filename_string> <section_string> <key_string> <key_value_string>

Sets an INI setting in the specified file. Returns a value of true if the key value was written to the file, false if the key was not written. Within the file, the section identified by <section_string> is located, and then the key specified by the <key_string> is located. The <key_value_string> is then assigned to this key. For example:
setINISetting c:\\3dsmax2\\3dsmax.ini Directories Scenes c:\\3dsmax\\scenes

If the specified file, section, or key is not found, a new file, section, or key is created. If the specified file is read-only, or the file is open in MAXScript, the key value is not written to the file.

Custom User Interface Files

The following methods provide access to Custom User Interface (CUI) files. The CUI functions are in a structure package named cui.
cui.getDir()

Returns the directory of the currently active CUI file as a string.

cui.getConfigFile()

Returns the currently active CUI file name as a string.

cui.setConfigFile <filename_string>

Sets the currently active CUI file to the specified file name.
cui.saveConfig()

Saves the current CUI configuration data to the active .cui file
cui.saveConfigAs <filename_string>

Saves current CUI configuration data to the specified file. The specified file is made the current CUI file.
cui.loadConfig <filename_string>

Loads the CUI configuration data from supplied file. The specified file is made the current CUI file.

Chapter 15:

Change Handlers and Callbacks

Change Handlers and Callbacks are used to detect when certain types of events occur to scene objects or within 3ds max. Change Handlers are applied to individual MAXWrapper objects and specify an attribute to monitor for that object and an expression to evaluate when that attribute changes. Example attributes that can be monitored are geometry, name, transform, and parameters. Change Handlers are not stored in a 3ds max scene. Callbacks are used to register with 3ds max functions that are called when specific events occur within 3ds max. Events that can be monitored are changes to the time slider time and redrawing of viewports. Callbacks are not stored in a 3ds max scene. MAXScript also provides several methods that automatically tie into 3ds max s Callback system. These methods are used to register and unregister 3ds max scripts that are called for a variety of 3ds max events. These scripts can optionally be saved with the currently-open file and stay permanently with it, running whenever the scene is loaded, until they are explicitly removed. The above are described in more detail in the following topics: Change Handlers and When Constructs (p. 1650) Time Change Callback Mechanism (p. 1654) Viewport Redraw Callback Mechanism (p. 1655) RenderEffect Progress Callback Mechanism (p. 28) General Event Callback Mechanism (p. 29) MAXScript also allows you to register a scripted menu that is invoked when the user performs a right-click in a 3ds max viewport. See the Scripted Right-Click Menus (p. 1514) topic for more information.

1650

Chapter 15

Change Handlers and Callbacks

Change Handlers and When Constructs

Change Handlers are used to detect when certain types of user events are performed on objects in the scene, allowing you to write scripts that respond to user operations like object moves, vertex edits, object deletions, name changes, etc.. Change Handlers are applied to individual MAXWrapper objects and specify an attribute to monitor for that object and an expression to evaluate when that attribute changes. Example attributes that can be monitored are geometry, name, transform, and parameters. Change Handlers are not stored in a 3ds max scene. The ChangeHandler : Value class instances represent change handler setups. ChangeHandler values are created using the when construct. Each time a when construct is executed, it creates and returns a new ChangeHandler instance. You should store this ChangeHandler value in a variable or array so that you can dismiss the handler when it is appropriate to do so. The when construct defines a change handler function for a certain type of event on one or more objects. The system then automatically calls this function whenever the event occurs. The syntax of the when construct has two forms as follows:
when <attribute> <objects> change[s] [ id:<name> ] \ [ handleAt:#redrawViews|#timeChange ] \ [ <object_parameter> ] do <expr> when <objects> deleted [ id:<name> ] \ [ handleAt:#redrawView|#timeChange ] \ [ <object_parameter> ] do <expr> \

In the first form, the <attribute> can be one of:

topology geometry name[s] transform select parameters subAnimStructure controller children

These specify the attribute of the given object(s) to be tracked for change (see below for more details). The second form tracks object deletion by the user or other scripts. For object deletion events, the handler is called after the object is deleted, so you cannot perform any 3ds max operations on it. This is typically used if you have tables or other structures containing MAXScript object values and you want to remove deleted objects from them as the user modifies the scene. In both forms, the <objects> argument can be one of the following: a single 3ds max object, such as a scene node, controller, modifier, or material, etc. one of the object sets, such as selection, or cameras, etc. a wild-card pathname like $foo*. an array of 3ds max objects.

Change Handlers and When Constructs

1651

If more than one object is specified, the handler is called each time the given attribute of any of the objects is signaled as changed by the 3ds max core. The optional id: parameter specifies an ID for one or more handlers as a name literal. The ID name can later be used to delete the handler and, if the same name is given to several handlers, they can be deleted as a group. The optional handleAt: parameter signals that the change handler expression should not be executed immediately upon notification, but delayed until the either the 3ds max viewports are redrawn (#redrawViews) or current 3ds max animation time is changed (#timeChange). Delaying the processing of the change handler expression is highly recommended, as described in the Caution section below. An example usage of the handleAt: parameter is:
when select $ changes id:#foo handleAt:#redrawViews do ...

The optional <object_parameter> lets you specify the name of a parameter variable that will be accessible in the do <expr> and will hold the actual object that has changed. You typically specify this parameter name if the handler will respond to changes in many objects, so you can determine which one has changed. The <expr> can be a single expression or block expression. Examples:
when transform $box01 changes do $box02.pos = $box01.pos + delta when names selection change obj do update_name_table obj when #($foo, $baz, $bar) deleted obj do ( messageBox Warning! deleteItem obj_table (findItem obj_table obj) )

The change attributes are interpreted as follows:

topology

signaled when the topology of an object changes in the Modify panel, such as via a mesh smooth, optimize, or vertex delete.
geometry

signaled when the geometry of an object changes, such as by moving a vertex or via an animated modifier.
name or names

signaled when the name of an object is changed if this occurs because a user edits the name in one of the 3ds max command panels. The handler is called repeatedly with each character that is changed.
transform

signaled when the transform of an object is changed, such as by a move, rotate, or scale.
select

signaled when a scene node moves into or out of the current selection set. You should interrogate the <node>.isSelected property to determine the new state.

1652

Chapter 15

Change Handlers and Callbacks

parameters

signaled when any parameters are changed in the object. This is something of a catch all, because the core signals this event in many situations.
subAnimStructure

signaled when the dynamic subAnim structure changes, such as when a new vertex becomes animated in an editable mesh, or when a new controller is added to a list controller. Also called when subAnims are reassigned, for example, when a material is changed in an object.
controller

signaled when a new controller is assigned to one of the objects tracks.

children

signaled when an object has immediate children added or removed. You can use the following two methods for deleting change handlers:
deleteChangeHandler <change_handler>

deletes specified change handler. change_handler is the value returned by a when construct.
deleteAllChangeHandlers [ id:<name> ]

If optional id: parameter is not specified, deletes all change handlers. If optional id: parameter is specified, deletes all change handlers with the specified id. For example:
deleteAllChangeHandlers id:#foo

For efficiency reasons, you dont want irrelevant change handlers running in the background, so it is essential that you delete those that you no longer need. Special Considerations If a runtime error occurs in the body of a change handler while it is being executed, an error message is displayed and that handler is permanently disabled. If all of the objects being tracked by a change handler are deleted, the change handler is also deleted. The do <expr> change handler code is executed in a special context and not in the context of the code that created it. This means that the <expr> code cannot contain references to local variables in outer code nestings surrounding the when, since those variables are on an execution stack that does not exist at the time the when handler is called. The compiler detects any illegal references to outer locals and generates a compiler message. An important exception to this is utility and rollout panel locals, such as local functions, rollout variables and nested rollouts. You can refer to them in change handler code inside rollout code as they are associated directly with their rollout or utility object. Change handlers are called only for user initiated events, and not for changes resulting from a change in controller values. For example, a change handler on the transform attribute of a node would be called when the user moves the node. If the position of the node is animated, and you play back the animation, the transform attribute change handler is not called.

Change Handlers and When Constructs

1653

If you assign a change handler to an attribute on multiple objects, the change hander is called once per object if that objects attribute changes. For example, if you say:
when select $ changes obj do update_modifier_list obj

function update_modifier_list is called whenever any object is selected or deselected. This is true even if you do an Edit/Select All. In this case, update_modifier_list will be called once for each object currently selected (as the objects are deselected), and then once for all objects in the scene (as the objects are selected). If update_modifier_list is at all processor-intensive, a significant system slowdown can occur. Change handlers are only applied to object already present in the scene. Change handlers are not automatically applied to newly created objects. If you have multiple change handlers defined, the order in which the change handlers are called is somewhat arbitrary. Due to the way that 3ds max internally processes notification signals, the $ form of accessing selected objects is not recommended in a select change handler. To access the selected objects, you should use the selection objectset. This is because $ relies on information that has not yet been set in the selection processing whereas selection uses a different method of accessing selections and the information it uses has been set up.

Caution: The change handler system is based on 3ds maxs internal notification system which essentially drives all animation and interactivity within 3ds max. There are cases when the core sends many, many signals for the same change, so setting up change handlers on many objects that do vast amounts of computing can significantly slow down the system. Strictly speaking, change handlers are supposed to be used to just set dirty flags in a lightweight, order-independent way, and then use Redraw Views or Time Change callbacks to actually cause the triggered processing. You should attempt to use change handlers judiciously, and not, for example, as a simple way to get scripted controllers. If you do find that a desired setup is being flooded with unnecessary signals, you should use the handleAt: to delay the actual processing of the event handler script until a redrawViews or timeChange event occurs.

1654

Chapter 15

Change Handlers and Callbacks

Time Change Callback Mechanism

You can register one or more functions to be called whenever the current 3ds max animation time is changed, such as when the user drags the time slider or plays the animation. The following methods let you register and unregister these callbacks:
registerTimeCallback <fn> unRegisterTimeCallback <fn>

You can register as many functions as you like. Each one is individually called whenever the time changes. The functions you register must take no arguments. They can access the updated current time through the MAXScript system variable currentTime. Example:
fn time_p = print currentTime registerTimeCallback time_p

In the above example, the registered function causes the current time to be printed in the Listener window whenever the user moves the time slider or plays the animation. Special Considerations If a runtime error occurs in a callback function while it is being executed, an error message is displayed and that callback function is permanently disabled. The time callback is not called during rendering, even if multiple frames are rendered. The registered function is executed in a special context and not in the context of the code that created it. This means that the function cannot contain references to local variables in outer code nestings surrounding the function definition since those variables are on an execution stack that does not exist at the time the function is called. An important exception to this is utility and rollout panel locals, such as local functions, rollout variables and nested rollouts. You can refer to them in change handler code inside rollout code as they are associated directly with their rollout or utility object. Note that it is the function value that is being registered, not the function name or global variable. This means that redefining the same-named function after registering it does not change the callback. You either need to unregister, re-define the function and then register it again, or make the registered function an intermediary which calls another function, for example:
fn time_cb = print currentTime fn tcb = time_cb() registerTimeCallback tcb

In this case, the registered callback function, tcb, calls the real call back, time_cb, (by referencing the global variable it is defined in), meaning you can redefine time_cb() as often as you need and the callback will always invoke the latest definition. This is a useful technique to employ while you are developing and debugging a callback. Callback functions remain registered after loading a new file or performing a 3ds max reset.

Viewport Redraw Callback Mechanism

1655

Viewport Redraw Callback Mechanism

You can register one or more functions to be called whenever the 3ds max viewports are redrawn. The following methods let you register and unregister these callbacks:
registerRedrawViewsCallback <fn> unRegisterRedrawViewsCallback <fn>

You can register as many functions as you like. Each one is individually called whenever the viewports are redrawn. The functions you register must take no arguments. Example:
fn redrawviews_p = print Viewports Redrawn registerRedrawViewsCallback redrawviews_p

In the above example, the registered function causes the string Viewports Redrawn to be printed in the Listener window whenever the 3ds max viewports are redrawn. Special Considerations If a runtime error occurs in a callback function while it is being executed, an error message is displayed and that callback function is permanently disabled. The registered function is executed in a special context and not in the context of the code that created it. This means that the function cannot contain references to local variables in outer code nestings surrounding the function definition since those variables are on an execution stack that does not exist at the time the function is called. An important exception to this is utility and rollout panel locals, such as local functions, rollout variables and nested rollouts. You can refer to them in change handler code inside rollout code as they are associated directly with their rollout or utility object. Note that it is the function value that is being registered, not the function name or global variable. This means that redefining the same-named function after registering it does not change the callback. You either need to unregister, re-define the function and then register it again, or make the registered function an intermediary which calls another function, for example:
fn redrawviews_cb = print currentTime fn rvcb = redrawviews_cb() registerRedrawViewsCallback rvcb

In this case, the registered callback function, rvcb, calls the real call back, redrawviews_cb, (by referencing the global variable it is defined in), meaning you can redefine redrawviews_cb() as often as you need and the callback will always invoke the latest definition. This is a useful technique to employ while you are developing and debugging a callback. Callback functions remain registered after loading a new file or performing a 3ds max reset.

1656

Chapter 15

Change Handlers and Callbacks

General Event Callback Mechanism

MAXScript allows you to register callback scripts for all of the notification events supported by 3ds max, such as pre/post scene file open, new, reset, scene file save, pre/post render, selection change, etc. You can specify any number of callback scripts per notification event. Callback scripts can be bundled into IDd sets, and can be deleted individually or all callback scripts in and IDd 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 dont accidentally get copied to a later file. The default for this parameter is false, indicating the script is a global script and is not persistent. For example:
callbacks.addScript #preRender setUpRenderGeom() \ id:#jbwRender

registers a new callback script that will be called just before a render is performed. The script invokes a function (that has presumably already been set up). An unique ID has been assigned to the script for later selective removal.
callbacks.removeScripts [ <callback_type_name> ] [ id:<name> ]

This method is used to unregister and remove one or more callback scripts. Specifying just a callback event type name removes all the callback scripts for that event. Specifying just an id:<name> removes all callback scripts in all events with that ID. Specifying both limits the ID-based removal to the specified event type.

General Event Callback Mechanism

1657

callbacks.show ()

This method lists out the current callback scripts in the Listener window.
callbacks.broadcastCallback <callback_type_name>

This method provides a way for you to simulate one of the events and have all the callback scripts for it executed. Within 3ds max, the #preRenderFrame and #preRenderFrame callbacks can only be called by the renderer. These callbacks can not be called by using this method. The following is a list of valid callback event type names:
#unitsChange

Sent if the user changes the unit setting.

#timeunitsChange

Sent if the user changes the time format setting.

#viewportChange

Sent if the user changes the viewport layout.

#spacemodeChange

Sent if the user changes the reference coordinate system.

#modPanelSelChanged

Sent whenever the Modify panel opens on a new selection, either because the Modify panel was just selected or because a new selection is made in the scene. The notify occurs at a point just prior to panel redraw but after the selection has been established, so that callback functions can modify the panel state without it being overwritten.

System Notifications
#systemPreReset

Sent before 3ds max is reset.

#systemPostReset

Sent after 3ds max is reset.

#postSystemStartup

Sent when the software goes live.

#pluginLoaded

Sent whenever a plug-in is loaded.

#systemPreNew

Sent just before 3ds max is reset.

#systemPostNew

Sent just after 3ds max is reset.

#preSystemShutdown

Sent just before the software enters the shutdown process.

#postSystemShutdown

Sent just before the software finishes the shutdown process.

#colorChanged

Sent when the system is updating its custom colors.

1658

Chapter 15

Change Handlers and Callbacks

File Notifications
#filePreOpen

Sent before a new file is opened.

#filePostOpen

Sent after a new file is opened successfully.

#filePreMerge

Sent before a file is merged.

#filePostMerge

Sent after a file is merged successfully.

#filePreSave

Sent before a file is saved.

#filePostSave

Sent after a file is saved.

Renderer Notifications
#preRender

Sent before rendering is started. This notification is sent out before the renderer creates the render instance objects, which means that you can create nodes and other objects as a response to this event. When rendering multiple frames, this event is sent only once at the beginning of the rendering phase, and not on a per-frame basis. In the #preRender callback, you cant 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 wont occur until the next render session occurs.
#postRender

Sent after rendering has finished. This notification is sent out after the renderer destroys the render instance objects, which means that you can create nodes and other objects as a response to this event. When rendering multiple frames, this event is sent only once at the end of the rendering phase, and not on a per-frame basis.
#preRenderEval

Sent just before the renderer starts evaluating objects.

#preRenderFrame

Sent just before each frame is rendered by the renderer. This notification is sent out after the renderer has taken a snapshot of the scene geometry. At the time of this call the scene cannot be modified. The renderer has already called GetRenderMesh() on all the object instances, and the materials and lights are already updated. If you dont 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 frames time. This notification is not sent out when the renderer is called to update the Material Editor sample spheres, only during output rendering.

General Event Callback Mechanism

1659

#postRenderFrame

Sent just after each frame is rendered by the renderer. The current frame being rendered is set into the MAXScript currentTime context and system global, so any references to other scene object properties will automatically be resolved at the currently rendering frames time. This notification is not sent out when the renderer is called to update the Material Editor sample spheres, only during output rendering.
#renderParamsChanged

Sent whenever the common renderer parameters have changed.

Import/Export Notifications
#preImport

Sent before a file is imported.

#postImport

Sent after a file is imported successfully.

#importFailed

Sent if import fails.

#preExport

Sent before a file is exported.

#postExport

Sent after a file is exported successfully.

#exportFailed

Sent if export fails.

Node Related Notifications

#nodeCreated

Sent when a node is created.

#nodeRenamed

Sent if a scene node is renamed.

#nodeHide

Sent when a node is hidden.

#nodeUnhide

Sent when a node is unhidden.

#nodeFreeze

Sent when a node is frozen.

#nodeUnfreeze

Sent when a node is unfrozen.

#nodeLinked

Sent when a new parent-child link is made.

#nodeUnlinked

Sent when a parent-child link is broken.

1660

Chapter 15

Change Handlers and Callbacks

#nodePreMaterial

Sent just before a node gets a new material

#nodePostMaterial

Sent just after a node gets a new material

#sceneNodeAdded

Sent just after a node is added to the scene.

#selNodesPreDelete

Sent just before selected nodes are deleted.

#selNodesPostDelete

Sent just after selected nodes are deleted.

#nodeMaterialChanged

Sent after the material is changed for the selected nodes.

#nodeWSCacheUpdated

Sent whenever the modifier stack display is reevaluated.

Material Library Notifications

#matLibPreOpen

Sent just before loading a material library.

#matLibPostOpen

Sent just after loading a material library.

#matLibPreSave

Sent just before saving a material library.

#matLibPostSave

Sent just after saving a material library.

#matLibPreMerge

Sent just before merging a material library.

#matLibPostMerge

Sent just after merging a material library.

Asset Browser Notifications

#abPreNavigate

Sent whenever a URL is loaded into the Asset Browser.

VIZ-Only Notifications
#heightMenuChanged

Sent when a user operated the height menu.

#fileLinkPreBind

Sent just before a file link bind.

#fileLinkPostBind

Sent just after a file link bind.

General Event Callback Mechanism

1661

#fileLinkPreDetach

Sent just before a file link detach.

#fileLinkPostDetach

Sent just after a file link detach.

#fileLinkPreReload

Sent just before a file link reload.

#fileLinkPostReload

Sent just after a file link reload.

#fileLinkPreAttach

Sent just before a file link attach.

#fileLinkPostAttach

Sent just after a file link attach.

Other Notifications
#wmEnable

Sent when main window gets an wm_enable (BOOL enabled).

#selectionSetChanged

Sent after the selection set has changed.

#bitmapChanged

Sent after a bitmap is reloaded.

1662

Chapter 15

Change Handlers and Callbacks

Chapter 16:

Miscellaneous Functions

freeSceneBitmaps()

Frees up all the memory used by the image file bitmap caches. This is useful if memory is fragmented with a lot of different bitmaps and you want to have just the ones currently active reloaded.
rescaleWorldUnits <factor> [ #selOnly ]

This method provides functionality similar to that of Rescale World Utility plug-in in 3ds max. <factor> is the factor the objects should be scaled by. If #selOnly is specified then only the selected objects are scaled.
IsNetServer()

Returns true if 3ds max is operating in network rendering mode and false if operating in normal interactive mode.
loadDllsFromDir <directory_path_string> <filename_wildcard_string>

Load all the plug-ins found in the specified directory. The directory_path_string must be terminated with a \. For example:
LoadDllsFromDir f:\\maxsdk\\plugin\\ *.dlc maxVersion()

Returns an Array with three integers like #(3000, 6, 0) with 3ds max release number, max API number, revision number of the SDK.
swap <destination> <destination>

Takes two valid assignment destinations (property, array index, or variable) as arguments and swaps their values. For example:
swap myMaterial.diffuseMap.map1 myMaterial.diffuseMap.map2

1664

Chapter 16

Miscellaneous Functions

Pausing Script Execution

The sleep function lets you pause script execution for a given amount of time. The form is:
sleep <time_in_seconds>

The time argument is a floating point number of seconds to sleep. Note that the sleep time is not guaranteed to be extremely accurate. You can interrupt a sleep with the ESC key which halts all execution or with the SPACE bar which simply causes the sleep function to terminate and the script to continue executing. In both cases, you may need to hold the key down for up to half a second for MAXScript to respond.

Time Stamping
The timeStamp() function gives time-of-day in milliseconds. The form is:
timeStamp()

The function returns the number of milliseconds since 00:00 hours that day. This is useful for timing operations (presuming you are not timing across midnight.) Example:
start = timeStamp() process_mesh() -- do some big job end = timeStamp() format Processing took % seconds\n ((end - start) / 1000.0)

Controlling the Renderer

You can use the render() function to invoke the 3ds max renderer. It can take many optional parameters to control the rendering.
render [ camera: <camera_node> ]

Defaults to active viewport.

[ frame: <number> | #current ]

Defaults to #current.
[ [ [ [ framerange: <interval> | #active ] fromframe: <number> ] toframe: <number> ] nthframe: <number> ]

Defaults to unsupplied, and the frame value controls which frames to render.
[ outputwidth: <number> ]

Defaults to current render width.

Controlling the Renderer

1665

[ outputheight: <number> ]

Defaults to current render height.

[ outputSize: <point2> ]

An alternative way to specify the output size of the rendered image. The point2 value is in the form: [width,height]
[ pixelaspect: <number> ]

Defaults to 1.0.
[ renderhiddenobjects: <boolean> ]

Defaults to current renderer Render Hidden Objects state.

[ superblack: <boolean> ]

Defaults to current renderer Superblack state.

[ force2sided: <boolean> ]

Defaults to current renderer Force 2 Sided state.

[ renderatmosphericeffects: <boolean> ]

Defaults to current renderer Render Atmospheric Effects state.

[ renderfields: <boolean> ]

Defaults to current renderer Render Fields state.

[ fieldorder: #odd | #even ]

Defaults to current renderer preferences Field Order state.

[ outputfile: <string> ]

The frame number is appended to the filename if the file image type is a single image type (.bmp, .jpg, .tga, etc.), and a frame range is being rendered. Defaults to rendering to just the virtual frame buffer.
[ vfb: <boolean> ]

Defaults to current renderer Show VFB state.

[ netrender: <boolean> ]

Defaults to current renderer Net Render state.

[ renderer: #draft | #production]

Allows the selection of draft or production renderer. By default, the currently selected renderer is used.
[ renderType: #normal | #region | #regionCrop | #blowup | #selection ] [ region: #(left,top,right,bottom) ]

Provides control over the type of rendering, corresponding to the Render Type menu in the 3ds max toolbar. If #region or #blowUp is selected, the region: parameter may be used to override the currently set regions for the active viewport, specified as pixel coordinates relative to the top-left corner in the bitmap (VFB). Note that #region and #blowUp can only be selected for an active viewport rendering. An error will be reported if they are specified for a camera rendering. Defaults to #normal.
[ to: <bitmap> ]

Specifies an existing bitmap to render into. The render() function takes image size and other parameter settings from the existing bitmap. If not supplied, a new bitmap is created and returned by the render() function.

1666

Chapter 16

Miscellaneous Functions

[ channels: <array_of_channel_names> ]

Specifies which g-buffer channels should be created during the rendering. For example:
bm = render camera:$cam2 channels:#(#zDepth, #coverage, #objectID)

causes $cam2 to be rendered into a new bitmap that will contain z-depth, pixel coverage and object g-buffer ID channels. The channels: argument must always be an array of channels identifiers, chosen from the following:
#zDepth #matID #objectID #UVCoords #normal #unClamped #coverage #node #shaderColor #shaderTransparency #velocity #weight

Defaults to no g-buffer channels.

[ aperture: <float> ]

Defaults to current renderer Aperture Width value.

[ ditherTrueColor: <boolean> ]

Defaults to current rendering preferences Dither True Color state.

[ ditherPaletted: <boolean> ]

Defaults to current rendering preferences Dither Paletted state.

[ videocolorcheck: <boolean> ]

Defaults to current renderer Video Color Check state.

[ renderPAL: <boolean> ]

Defaults to current rendering preferences Video Color Check NTSC/PAL state. If true, and video color checking is enabled, PAL video color checking is performed.
[ superBlackThreshold: <integer> ]

Defaults to current rendering preferences Super Black Threshold value.

[ maxPixelSize: <float> ]

All correspond to items in the 3ds max Render Scene setup dialogs.

Controlling the Renderer

1667

The following are also available if the 3ds max standard scanline renderer is being used:
[ antiAliasing: <boolean> ]

Defaults to current renderer Anti-Aliasing state.

[ antiAliasFilterSize: <float> ]

Defaults to current renderer Anti-Aliasing Filter Size value.

[ antiAliasFilter: <filter> ]

Defaults to current renderer Anti-Aliasing filter.

[ enablePixelSampler: <boolean> ]

Defaults to the current renderer Global SuperSampling state. This state is true if Disable all Samplers is checked, otherwise false.
[ mapping: <boolean> ]

Defaults to current renderer Mapping state.

[ shadows: <boolean> ]

Defaults to current renderer Shadows state.

[ autoReflect: <boolean> ]

Defaults to current renderer Auto-Reflect/Refract and Mirrors state.

[ forceWireframe: <boolean> ]

Defaults to current renderer Force Wireframe state.

[ wireThickness: <float> ]

Defaults to 1.0.
[ filterMaps: <boolean> ]

Defaults to current renderer Anti-Aliasing Filter Maps state.

[ objectMotionBlur: <boolean> ]

Defaults to current renderer Object Motion Blur Apply state.

[ objectBlurDuration: <float> ]

Defaults to 0.5.
[ objectBlurSamples: <integer> ]

Defaults to 10.
[ objectBlurSubdivisions: <integer> ]

Defaults to 10.
[ imageMotionBlur: <boolean> ]

Defaults to current renderer Image Motion Blur Apply state.

[ imageBlurDuration: <float> ]

Defaults to 0.5.
[ autoReflectLevels: <integer> ]

Defaults to 1. You can invoke the renderer and have it do one or more of four things with the rendered output: Display it in a virtual frame buffer (the default), controlled with the vfb: parameter. Store the rendering in an image file by supplying an outputfile: parameter. The type of image file to be created is determined from the file suffix you specify.

1668

Chapter 16

Miscellaneous Functions

Return the result as a MAXScript Bitmap value that you can perform Bitmap operations on (see the Bitmap Values (p. 755) topic). Store the rendering in an existing MAXScript Bitmap value by supplying the to: parameter. Supplying this parameter causes settings such as height, width, aspect, gamma, file name, etc. to be taken from the supplied bitmap.

Notes: The render() function interruptible mid-frame using the ESC key. Examples:
render camera:$cam01 outputwidth:320 outputheight:240 for c in cameras do render c outputFile:(c.name + .bmp) vfb:off rollout1.image.bitmap = render camera:$cam01 ...

Executing External Commands and Programs

MAXScript provides two methods for executing external programs. DOSCommand() takes a DOS command as a string and send it to the system for execution. It has the form:
DOSCommand <command_string>

Examples:
DOSCommand delete c:\\temp\\foo.dat DOSCommand (copy + source_file + + dest_folder)

You can use this function to launch other programs, for example, or perform such tasks as gathering all the material texture and displacement image files in your scene into one folder. The DOSCommand() function returns an integer which is the status result returned by the executed system command. ShellLaunch() emulates a user double-clicking on a specified file in Windows. It has the form:
ShellLaunch <filename_string> <parameters_string>

Whatever you send to ShellLaunch will be run by the Windows shell automatically, ie:
ShellLaunch E:\\tests\\lookup.html

would launch Netscape/Ie4 with lookup.html. If a file-name extension is not specified in <filename_string>, Windows will search the specified directory for executable files. If no directory is specified, Windows will search the paths in the Path environment variable for the executable file. For example:
shellLaunch e:/program files/ucalc/ucalc

will execute the ucalc.exe file in the specified directory.

Exiting and Resetting 3ds max

1669

The <parameters_string> is passed to the launched application as command line parameters. For example:
shellLaunch e:/t.avi /play /loop

Will launch the application associated with .avi files, and pass /play and /loop as command line parameters.

Exiting and Resetting 3ds max

The quitMAX() function lets you exit 3ds max under script control. This function is typically used in batch processing or render scripts. The function has the form:
quitMAX [ #noPrompt ]

If the #noPrompt optional argument is not specified and there are unsaved changes in the scene, 3ds max will prompt with its standard save changes dialog. Additionally, you can control the scene save and undo states in 3ds max with the following functions:
setSaveRequired <boolean>

lets you set the 3ds max system dirty flag. If this flag is set or there are entries in the Undo buffer, the user is asked if they want to save the scene file on a File > New or File > Reset.
getSaveRequired()

returns true if the 3ds max system dirty flag is set to true or if the Undo buffer is not empty. If the Undo buffer if not empty, this function will still return true, even if you just called setSaveRequired false.
clearUndoBuffer()

empties the Undo buffer, both providing a way to reset the undo state and another way to control the save-changes requester. Normally, if there are entries in the Undo buffer when the scene is closed, 3ds max will prompt with a save-changes requester. In some cases, where you are controlling undo in MAXScript, you may want to force the need for a save-changes prompt. The resetMAXFile() function lets you reset 3ds max under script control. This function is typically used in batch processing or render scripts. The function has the form:
resetMaxFile() [ #noPrompt ]

If the #noPrompt optional argument is not specified and there are unsaved changes in the scene, 3ds max will prompt with its standard save changes dialog.

1670

Chapter 16

Miscellaneous Functions

Chapter 17:

OLE Automation

OLE Server OLE Automation capability is provided in MAXScript that allows 3ds max to act as an OLE Automation server for applications such as Visual Basic, Excel, Paradox, etc. With it, you can publish MAXScript functions that can then be called from OLE Automation clients like VB and Excel to generate models or animations or return data from the current scene, etc. There is an example supplied in the script samples that defines a set of simple business graphing MAXScript functions and an Excel spreadsheet with some Excel VB-scripted menus that will pass a selection of cells across to these MAXScript functions to generate an animated bar chart. This facility has the following features and limitations: It exposes a single server object to which you can attach a list of MAXScript functions that then appear as the methods of that object to an OLE Automation client. Future releases will allow you to construct any number of OLE Automation objects and give them any number of interfaces. It is registered as a separate process, local server supporting multiple use of its exposed object. It does not support in-place activation or object linking and embedding and provides no containers for other OLE objects. In future versions, you will be able to pass rendered images and animations to OLE clients for direct linking and embedding. It supports only the IDispatch form of interface with no accessible type information -- clients need to declare their reference to the 3ds max server object as an untyped generic object. It supports the following method argument and result data types:
integers reals (floats) currency (floats) string boolean empty (an empty spreadsheet cell, for example)

the equivalent MAXScript value for empty is undefined

OLE Objects (interfaces)

1672

Chapter 17

OLE Automation

You need to have 3ds max running and MAXScript activated before OLE Clients can access 3ds max. MAXScript is activated (and the startup.ms script run) when you first access its Utility panel rollout. Alternatively, you can use launch script facilities described in Running Scripts from the Command Line (p. lvii) to establish an OLE server interface as soon as 3ds max runs. You need to have registered 3ds max with Windows as an OLE server using the registration script supplied with this release. See the instructions in the Setting Up MAXScript OLE Automation (p. 1673) for details.

OLE Client With the MAXScript OLE Automation Client system, you can use MAXScript to create OLE Automation (now called Active-X) objects within 3ds max and control the associated OLE Automation Servers servers with MAXScript, such as making an Excel spreadsheet and inserting 3ds max object information directly into cells there. The function createOLEObject() is used for establishing a connection to OLE Auto Servers. The return value of createOLEObject() is an instance of the OLEObject class. For example,
xl = createOLEObject Excel.Sheet

opens a connection to Excel and creates a sheet object and puts it in the variable xl. The single argument to this function is an OLE progID string. You can then access properties and call methods on the new OLE object. For example,
xl.application.name

will return
Microsoft Excel xl.application.visible = true

will make Excel visible on the desktop. You get properties on OLE objects with the dot . notation, just as you do in MAXScript. You also refer to OLE object methods as properties of the OLE object. For example, the Sheet has a method cells which takes a cell coordinate and returns a Cell OLE object.
xlc = xl.application.cells 1 1

puts the top-left-hand cell into xlc. Set its value like this:
xlc.value = 123.45

The server application that was attached with createOLEObject() is released and terminated when the created MAXScript OLE object is eventually garbage-collected. You can explicitly disconnect from an OLE server application with the releaseOLEObject() function. The form is:
releaseOLEObject <ole_object>

The OLE object becomes disabled once releaseOLEObject() has been called on it and further attempts to use it results in a descriptive error message.

Setting Up MAXScript OLE Automation

1673

You can explicitly disconnect from all active OLE server applications with the releaseAllOLEObjects() function. Its form is:
releaseAllOLEObjects()

After calling this function, all existing OLE objects become disabled and any attempt to use them further will generate a runtime error.

Setting Up MAXScript OLE Automation

In order to use the OLE Automation features in MAXScript, you need to register 3ds max as an OLE Automation server in the system registry: 1. 2. Open the Maxscrpt.reg file that ships with 3ds max in Notepad or some other text editor. Edit this registry entry file to make sure it references the correct 3ds max executable. Make sure the last line specifies the correct location for your 3ds max executable. The supplied Maxscrpt.reg file points to c:\3dsmax\3dsmax.exe by default. Save the file and exit the editor. Locate the Maxscrpt.reg registry file in Windows Explorer and double-click it.

3. 4.

This registers 3ds max as an OLE server. You need to do this on all the systems you expect to run 3ds max as an OLE server. For more information, see the following topics: Exposing MAXScript Functions (p. 1673) 3ds max Specific Errors (p. 1674) Running the OLE Demo (p. 1674)

Exposing MAXScript Functions

The list of OLE Automation-callable MAXScript functions is defined using the registerOLEInterface() function. It takes an array of functions to be exposed:
registerOLEInterface <array_of_fns>

For example:
registerOLEInterface #(get_object_count, get_object_name, get_object_position)

Each time you call this function, it replaces the current set of exposed functions with the new set -it does not add to the existing set. The functions you expose should limit themselves to passing and returning only the following data types: integers, reals (floats), currency, string, boolean and empty (undefined).

1674

Chapter 17

OLE Automation

3ds max Specific Errors

There are two errors that may be reported to OLE clients when calling exposed MAXScript functions that are specific to 3ds max: #512 -- an exception or interrupt occurred while running the called function #513 -- the called function attempted to return an unsupported data type

Running the OLE Demo

The example supplied consists of 2 files: ole.ms -- a MAXScript script containing a grapher interface oledemo.xls -- an Excel spreadsheet with some data and a VBA script to call the grapher To run the example, make sure youve registered 3ds max as an OLE server as described in the Setting Up MAXScript OLE Automation (p. 1673) topic, start 3ds max and open the ole.ms script file in a script Editor window. Youll see it contains definitions for six functions and a call to registerOLEInterface() to expose some of those functions. Select the whole script and press number pad ENTER to evaluate it. This defines the functions and exposes them through OLE. Start Excel and open the oledemo.xls spreadsheet (in the scripts directory). It contains one worksheet and one module sheet and defines a new Max menu. The worksheet contains some example data to be charted and the module sheet contains the VBA scripts that implement the menu commands in the new 3ds max menu. Bring up the sheet1 worksheet. It contains a table of numbers representing quarterly sales figure for a number of regions. Drag-select all the label and figure cells and choose the Max > Build Animated Chart menu. This opens a connection to 3ds max and passes the selected column labels and figures to the appropriate functions in the exposed interface. It then brings 3ds max to the front which chugs away for a bit building the labeled bar chart and animating the bars over the range of quarters given. Drag the slider to see the bars animate. Business graphs in 3ds max! The Max > Render Movie menu in Excel invokes another of the exposed MAXScript functions that creates and animates a camera in the bar chart scene and then sets off a render to an AVI file. (If you want to interrupt the render, hold down the ESC key until it stops at the beginning of the next frame - currently the MAXScript renderer interface only looks at the ESC key between frames).

Chapter 18:

Trigonometric Functions and Vector Arithmetic

Trigonometric Functions
This topic is a quick review for readers who need a reminder about this area of mathematics. If youre familiar with trigonometry, you can skip this topic. If you find this topic difficult to follow, you might consult a more basic reference on mathematics. Trigonometric functions are principally used to model or describe: The relation between angles in a triangle (hence the name). Rotations about a circle, including locations given in polar coordinates. Cyclical or periodic values, such as sound waves.

The three basic trigonometric functions are derived from an angle rotating about a unit circle.

Trigonometric functions based on the unit circle

1676

Chapter 18

Trigonometric Functions and Vector Arithmetic

The tangent function is undefined for x = 0. Another way to define the target is:

Because XYR defines a right-angled triangle, the relation between the sine and cosine is:

The graphs of the basic trigonometric functions illustrate their cyclical nature.

Graphs of basic trigonometric functions

The sine and cosine functions yield the same values, but the phase differs along the X-axis by ?/2: in other words, 90 degrees. The inverse functions for the trigonometric functions are the arc functionsthe inverse only applies to values of x restricted by ?/2 = X = ?/2. The graphs for these functions appear like the basic trigonometric function graphs, but turned on their sides.

Graphs of basic arc functions

Vector Arithmetic

1677

The hyperbolic functions are based on the exponential constant e instead of on circular measurement. However, they behave similarly to the trigonometric functions and are named for them. The basic hyperbolic functions are:

Graphs of basic hyperbolic functions

Vector Arithmetic
This topic is a quick review for readers who need a reminder about vector arithmetic. If youre familiar with vectors and vector calculations, you can skip this topic. If this topic is difficult to follow, you might consult a more basic reference on mathematics. A vector expresses a length and a direction in a particular space. The vector is expressed as a point; for example, [5, 5, 7]. The length is the distance from the origin to that point, and the direction is similarly from the origin to (and through) the point. In 3ds max, vectors have three values and describe positions in three-dimensional space. They can also represent percent scaling in X, Y, and Z; andmore abstractlydescribe locations in RGB color space.

1678

Chapter 18

Trigonometric Functions and Vector Arithmetic

Unit Vectors and Basic Vectors A unit vector has a length of one. Unit vectors are often used to express direction only. The three basic vectors are unit vectors that describe the three axes (X, Y, and Z) of 3D space.

Basic vectors and the XYZ axes

Adding and Subtracting Vectors Adding two vectors creates a new vector that combines the length and direction of the original two. Vector addition is commutative: V+W = W+V.

Adding two vectors

Subtracting two vectors gives the vector between the two points.

Vector Arithmetic

1679

Subtracting two vectors

Scalar Multiplication and Division Multiplying a vector by a scalar changes the vectors length, as does dividing the vector by a scalar.

Vector Length and Direction The length of a vector is obtained from the Pythagorean theorem.

In MAXScript, the length() function returns this value. The direction of the vector is the vector divided by its length; this gives you a unit vector with the same direction.

The distance between two points is the length of the vector between them.

Subtracting vectors to obtain a distance

1680

Chapter 18

Trigonometric Functions and Vector Arithmetic

Chapter 19:

MAXScript Grammar and Class Hierarchy

MAXScript Grammar
The following is the complete MAXScript grammar in EBNF form. It differs slightly in factoring from the syntax forms given in the online reference, so that all precedence is explicit in the rules. These rules, or syntax definitions, follow the standard EBNF notation (Extended Backus-Naur Form). The rules typically contain a number of characters with special meanings. For example, brackets enclose optional items, such as the minus sign in front of the number. Braces enclose items you can use repeatedly, and bars separate multiple items from which you can choose one. Sometimes, rules are given names so they can be referred to in the documentation or as parts of other rules. The special characters in the rules have the following meaning:
[...] (...|...|...) {...} {...}+ ::= <rule> bold_characters -------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 you can insert what is defined by the named rule characters or token as written

An example of an EBNF form is:

[- ]{<digit>}[.{<digit>}][(e | E)[+ | -]{<digit>}+]

which is interpreted as follows:

Syntax [-]{<digit>} [.{<digit>}] Definition an optional minus sign (the sign), followed by 0 or more digits (the integer part), followed by an optional sequence (the fraction part) comprised of: a period character, followed by 0 or more digits, followed by

1682

Chapter 19

MAXScript Grammar and Class Hierarchy

Syntax [(e | E)[+ | -]{<digit>}+]

Definition 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. ::= ::= { <expr> }+ <simple_expr> <variable_decls> <assignment> <if_expr> <while_loop> <do_loop> <for_loop> <loop_exit> <case_expr> <struct_def> <try_expr> <variable_decls> <function_def> <function_return> <context_expr> <max_command> <utility_def> <rollout_def> <tool_def> <rcmenu_def> <macroscript_def> <plugin_def> ( local | global ) <decl> { , <decl> } persistent global <decl> { , <decl> } <var_name> [ = <expr> ] -- name and optional -- initial value { <alphanumeric> | _ } { <any_char_except_quote> } <destination> <destination> <destination> <destination> <destination> <var_name> <property> <index> = <expr> += <expr> -= <expr> *= <expr> /= <expr>

<program> <expr>

<variable_decls>

::=

<decl>

::=

<var_name>

::=

<assignment>

::=

<destination>

::=

MAXScript Grammar

1683

<if_expr>

::=

if <expr> then <expr> [ else <expr> ] if <expr> do <expr> while <expr> do <expr> do <expr> while <expr> for <name> ( in | = ) <source> (do | collect) <expr> <expr> to <expr> [ by <expr> ] [ where <expr> ] <expr> [ where <expr> ] exit [ with <expr> ] continue case [ <expr> ] of ( { <case_item> } ) <factor> : <expr> default : <expr> struct (<member> { , <member> } ) <name> [ = <expr> ] -- name and optional initial value <function_def> try <expr> catch <expr> [ mapped ] (function | fn) <var_name> { <arg> } = <expr> <var_name> <var_name>: [ <operand> ] return <expr> <context> { , <context> } <expr> [with] animate <logical_expr> at level <operand> at time <operand> in <operand> [in] coordsys ( local | world | parent | <operand> ) about ( pivot | selection | coordsys | <operand> ) [ with ] undo <logical_expr> set <context> utility <var_name> <string> { <var_name>:<operand> } \ ( { <utility_clause> }+ )

<while_loop> <do_loop> <for_loop> <source>

::= ::= ::= ::=

<loop-exit> <loop-continue> <case_expr> <case_item>

::= ::= ::= ::=

<struct_def> <member>

::= ::=

<try_expr> <function_def> <arg>

::= ::= ::=

<function_return> ::= <context_expr> <context> ::= ::=

<set_context> <utility_def>

::= ::=

1684

Chapter 19

MAXScript Grammar and Class Hierarchy

<utility_clause>

::=

<rollout> <rollout_clause> rollout <var_name> <string> { <var_name>:<operand> } \ ( { <rollout_clause> }+ ) local <decl> { , <decl> } <function_def> <struct_def> <mousetool> <item_group> <rollout_item> <rollout_handler> group <string> ( { <rollout_item> } ) on <var_name> <var_name> { <var_name> } do <expr> <item_type> <var_name> [ <string> ] { <var_name>:<operand> } label button edittext combobox dropdownList listbox spinner slider pickbutton radiobuttons checkbox checkbutton colorPicker mapbutton materialbutton progressbar timer bitmap rcmenu <var_name> ( { <rcmenu_clause> }+ ) local <decl> { , <decl> } <function_def> <struct_def> <rcmenu_item> <rcmenu_handler> on <var_name> <var_name> do <expr> <rcmenu_item_type> <var_name> <string> { <var_name>:<operand> }

<rollout_def>

::=

<rollout_clause>

::=

<item_group>

::=

<rollout_handler> ::= <rollout_item> <item_type> ::= ::=

<rcmenu_def> <rcmenu_clause>

::= ::=

<rcmenu_handler> <rcmenu_item>

::= ::=

MAXScript Grammar

1685

<rcmenu_item_type>::=

menuitem separator submenu macroscript <var_name> <string> { <var_name>:<operand> } \ ( <expr_seq> ) tool <var_name> {<var_name>:<operand>} ({ <tool_clause> }+ ) local <decl> { , <decl> } <function_def> <struct_def> <tool_handler> on <var_name> <var_name> { <var_name> } do <expr> plugin <var_name> <var_name> { <var_name>:<operand> } \ ( { <plugin_clause> }+ ) local <decl> { , <decl> } <function_def> <struct_def> <parameters> <mousetool_def> <rollout_def> <plugin_handler>

<macroscript_def> ::=

<mousetool_def> <tool_clause>

::= ::=

<tool_handler> <plugin_def>

::= ::=

<plugin_clause>

::=

<parameters>

::= parameters <var_name> { <var_name>:<operand> } ( { <param_clause> }+ ) ::= { <param_defs> }+ { <param_handler> } <var_name> { <var_name>:<operand> } on <var_name> <var_name> { <var_name> } do <expr> on <var_name> do <expr> <operand> <math_expr> <compare_expr> <logical_expr> <function_call> <expr_seq>

<param_clause>

<param_defs> <param_handler> <plugin_handler> <simple_expr>

::= ::= ::= ::=

1686

Chapter 19

MAXScript Grammar and Class Hierarchy

<math_expr>

::=

<math_operand> addition <math_operand> subtraction <math_operand> multiplication <math_operand> division <math_operand> power <math_operand>

+ <math_operand> -- standard arithmetic - <math_operand> -- standard arithmetic * <math_operand> -- standard arithmetic / <math_operand> -- standard arithmetic ^ <math_operand> -- exponential, raise to the as <class> -- conversion between types

<math_operand>

::=

<operand> <function_call> <math_expr> <logical_operand> or <logical_operand> <logical_operand> and <logical_operand> not <logical_operand> <operand> <compare_expr> <function_call> <logical_expr> <compare_operand> <compare_operand> <compare_operand> <compare_operand> <compare_operand> or equal <compare_operand> <math_expr> <operand> <function_call> <operand> () <operand> { <parameter> } -- up to an end of line or -- lower precedence token <operand> <name>: <operand> <factor> <property> <index> <operand> . <var_name> -- properties and indexes -- left associate == <compare_operand> != <compare_operand> > <compare_operand> < <compare_operand> >= <compare_operand> -----equal not equal greater than less than greater than

<logical_expr>

::=

<logical_operand> ::=

<compare_expr>

::=

<= <compare_operand> -- less than or equal

<compare_operand> ::=

<function_call>

::=

<parameter>

::=

<operand>

::=

<property>

::=

MAXScript Grammar

1687

<index> <factor>

::= ::=

<operand> [ <expr> ] <number> <string> <path_name> <var_name> #<var_name> <array> <bitarray> <point3> <point2> true false on off ok undefined unsupplied - <expr> <expr_seq> ?

-- unary minus -- last Listener result

<expr_seq> <number>

::= ::=

( <expr> { (; | <eol>) <expr> } ) [-]{<digit>}[.{<digit>}[(e | E)[+ | -]{<digit>}+] -- decimal number 0x{<hex_digit>}+ -- hexadecimal number { <any_char_except_quote> | \ | \n | \r | \t | \* | \? | \\ | \% | \x{<hex_digit>}+ } [-]{<decimal_number>[m | s | f | t]}+ -- minutes/sec/ frames/ticks [-]{<digit>}:{<digit>}[.{<digit>}] -- SMPTE mins:secs.frame [-]<decimal_number>n -- active segment normalized time [ <expr>, <expr>, <expr>, <expr> ] [ <expr>, <expr>, <expr> ] [ <expr>, <expr> ] #() #( <expr> { , <expr> } ) #{} #{[<expr> | <expr>..<expr>] { , [<expr> | <expr>..<expr>] } } $<path> | $ [ <objectset> ] [ / ] [ <levels> ] <level_name>

<string>

::=

<time>

::=

<box2> <point3> <point2> <array>

::= ::= ::= ::=

<bitarray>

::=

<path_name> <path>

::= ::=

1688

Chapter 19

MAXScript Grammar and Class Hierarchy

<levels> <level>

::= ::=

<level> { / <level> } <level_name> ... { <alphanumeric> | _ | * | ? | \ } { <any_char_except_single_quote> | \* | \? | \\ }

<level_name>

::=

MAXScript Class Hierarchy

The following is the complete MAXScript class hierarchy. Each class typically inherits the properties, operators, and methods of its parent class.
Value AngleAxis Array ArrayParameter AtmosphericClass BigMatrix BigMatrixRowArray BipedExportInterface BitArray Bitmap BitmapControl BooleanClass Box2 ButtonControl CTBitMap CTMotionTracker ChangeHandler CharStream CheckBoxControl CheckButtonControl Class Color ColorPickerControl ComboBoxControl Control EdgeSelection EditTextControl EffectClass EmptyClass EulerAngles FaceSelection FileStream Float GeomObject GroupEndControl GroupStartControl HashTable Integer

MAXScript Class Hierarchy

1689

Interval LabelControl ListBoxControl MAXClass MAXFilterClass MAXKey MAXKeyArray MAXMeshClass MAXModifierArray MAXNoteKey MAXNoteKeyArray MAXObject MAXRootNode MAXScriptFunction MAXSuperClass MAXTVNode MSPluginClass MapButtonControl MapSupportClass MaterialLibrary Matrix3 MeditMaterialsClass Menuitem ModifierClass MotionTracker MouseTool MtlButtonControl MultiMaterialClass NURBSDisplay NURBSObject NURBSControlVertex NURBSCurve NURBSBlendCurve NURBSCVCurve NURBSCurveOnSurface NURBSChamferCurve NURBSFilletCurve NURBSIsoCurve NURBSMirrorCurve NURBSOffsetCurve NURBSPointCurve NURBSPointCurveOnSurface NURBSProjectNormalCurve NURBSProjectVectorCurve NURBSSurfSurfIntersectionCurve NURBSSurfaceEdgeCurve NURBSSurfaceNormalCurve NURBSXFormCurve NURBSPoint NURBSCurveConstPoint NURBSCurveIntersectPoint

1690

Chapter 19

MAXScript Grammar and Class Hierarchy

NURBSCurveSurfaceIntersectPoint NURBSIndependentPoint NURBSPointConstPoint NURBSSurfConstPoint NURBSSurface NURBS1RailSweepSurface NURBS2RailSweepSurface NURBSBlendSurface NURBSCVSurface NURBSCapSurface NURBSExtrudeSurface NURBSFilletSurface NURBSLatheSurface NURBSMirrorSurface NURBSMultiCurveTrimSurface NURBSNBlendSurface NURBSOffsetSurface NURBSPointSurface NURBSRuledSurface NURBSULoftSurface NURBSUVLoftSurface NURBSXFormSurface NURBSTexturePoint NURBSSelection NURBSSet NURBSSurfaceApproximation NURBSTextureSurface Name NodeChildrenArray NoteTrack Number OLEMethod OLEObject Object OkClass PathName PhyBlendedRigidVertex PhyContextExport PhyRigidVertex PickerControl Point2 Point3 ProgressBar Quat RadioControl Ray RolloutControl RolloutFloater SelectionSet SelectionSetArray Set

MAXScript Class Hierarchy

1691

SliderControl SpinnerControl StandardMaterialClass String StringStream StructDef SubAnim Time Timer TriMesh UndefinedClass UnsuppliedClass UserGeneric VertexSelection WindowStream XRefScene MAXWrapper atmospheric Combustion Fog Missing_Atmospheric RenderEnvironment Volume_Fog Volume_Light filter Area Blackman Blendfilter Catmull_Rom Cook_Variable cubic Mitchell_Netravali Plate_Match_MAX_R2 Plate_Match_VIZ_R2 Quadratic Sharp_Quadratic Soften Video FloatController AudioFloat bezier_float Block Float_Expression float_list Float_Motion_Capture Float_Reactor float_script linear_float LOD_Controller Missing_Float_Control Noise_float

1692

Chapter 19

MAXScript Grammar and Class Hierarchy

On_Off SlaveFloat tcb_float Waveform_Float Layer_Manager MasterBlockController Block_Control Free_Center MasterBlock material Blend compositematerial DoubleSided doubleSidedMat Matte MatteShadow Missing_Mtl Morphermaterial Multimaterial multiSubMaterial NoMaterial RaytraceMaterial Shellac standard Standardmaterial TexOutputClass StandardTextureOutput textureMap Adobe_Photoshop_Plug_In_Filter Adobe_Premiere_Video_Filter bitmapTex Bitmaptexture Bricks Cellular Checker compositeTexture CompositeTexturemap Dent falloff fallofftextureMap FlatMirror Gradient Gradient_Ramp Marble Mask maskTex Missing_TextureMap Mix Noise NoTexture output

MAXScript Class Hierarchy

1693

Paint Particle_Age Particle_MBlur Perlin_Marble Planet Raytrace Reflect_Refract RGB_Multiply RGB_Tint Smoke Speckle Splat Stucco Swirl Thin_Wall_Refraction Vertex_Color Water Wood TopBottom topBottomMat UVGenClass Missing_UVGen StandardUVGen XYZGenClass Missing_XYZGen StandardXYZGen Matrix3Controller IK_ControllerMatrix3Controller Link_Control Link_Transform lookat Missing_Matrix3_Control prs Slave_Control TVDummyControl modifier Affect_Region Bend Bevel Bevel_Profile CameraMap Cap_Holes CrossSection DeleteMesh DeleteSplineModifier Displace Disp_Approx Edit_Mesh Edit_Patch Edit_Spline Extrude

1694

Chapter 19

MAXScript Grammar and Class Hierarchy

Face_Extrude FFDBox FFDCyl FFD_2x2x2 FFD_3x3x3 FFD_4x4x4 FFD_Select Fillet_Chamfer Flex Lathe Lattice Linked_xform MaterialByElement Materialmodifier Melt MeshSmooth Mesh_Select MIrror Missing_OSM Morpher NCurve_Sel Noisemodifier Normalize_Spline Normalmodifier NSurf_Sel optimizeValue ActionPredicate ActiveXControl AngleAxis AngleControl Array ArrayParameter AtmosphericClass AttributeDef Layer_Manager BigMatrix BigMatrixRowArray BinStream BitArray bitmap BitmapControl BooleanClass Box2 ButtonControl ccCurve ccPoint CCRootClass ChangeHandler CharStream CheckBoxControl CheckButtonControl

MAXScript Class Hierarchy

1695

class color ColorPickerControl ComboBoxControl Control CTBitMap CTMotionTracker CurveCtlGeneric CurvePointsArray EdgeSelection EditTextControl EffectClass EmptyClass EulerAngles FaceSelection FileStream float Generic GeomObject GroupBoxControl GroupEndControl GroupStartControl HashTable ImgTag integer Interface InterfaceFunction Interval IObject LabelControl LinkControl ListBoxControl MapButtonControl MappedGeneric MappedPrimitive MapSupportClass MaterialLibrary Matrix3 MAXAKey MAXClass MAXCurveCtl MAXFilterClass MAXKey MAXKeyArray MAXMeshClass mesh MAXModifierArray MAXNoteKey MAXNoteKeyArray MAXObject MAXRefTarg

1696

Chapter 19

MAXScript Grammar and Class Hierarchy

MAXRootNode MAXScriptFunction MAXSuperClass MAXTVNode MeditMaterialsClass menuitem MixinInterface ModifierClass MotionTracker MouseTool MPassCamEffectClass MSComMethod MSCustAttribDef MSDispatch MSPluginClass MtlButtonControl MultiListBoxControl MultiMaterialClass name NodeChildrenArray NodeGeneric NoteTrack Number NURBSDisplay NURBSObject NURBSControlVertex NURBSCurve NURBSBlendCurve NURBSChamferCurve NURBSCVCurve NURBSCurveOnSurface NURBSFilletCurve NURBSIsoCurve NURBSMirrorCurve NURBSOffsetCurve NURBSPointCurve NURBSPointCurveOnSurface NURBSProjectNormalCurve NURBSProjectVectorCurve NURBSSurfaceEdgeCurve NURBSSurfaceNormalCurve NURBSSurfSurfIntersectionCurve NURBSXFormCurve NURBSPoint NURBSCurveConstPoint NURBSCurveIntersectPoint NURBSCurveSurfaceIntersectPoint NURBSIndependentPoint NURBSPointConstPoint NURBSSurfConstPoint NURBSSurface

MAXScript Class Hierarchy

1697

NURBS1RailSweepSurface NURBS2RailSweepSurface NURBSBlendSurface NURBSCapSurface NURBSCVSurface NURBSExtrudeSurface NURBSFilletSurface NURBSLatheSurface NURBSMirrorSurface NURBSMultiCurveTrimSurface NURBSNBlendSurface NURBSOffsetSurface NURBSPointSurface NURBSRuledSurface NURBSULoftSurface NURBSUVLoftSurface NURBSXFormSurface NURBSTexturePoint NURBSSelection NURBSSet NURBSSurfaceApproximation NURBSTextureSurface object OkClass OLEMethod OLEObject PathName PickerControl Point2 point3 Primitive progressBar Quat RadioControl Ray RCMenu RolloutClass RolloutControl RolloutFloater SelectionSet SelectionSetArray Set ObjectSet SliderControl SpinnerControl StandardMaterialClass StaticMethodInterface String StringStream StructDef subAnim

1698

Chapter 19

MAXScript Grammar and Class Hierarchy

TextureClass time Timer TriMesh UndefinedClass UnsuppliedClass UserGeneric ValueRef VertexSelection WindowStream XRefScene MAXWrapper atmospheric Fire_Effect Fog Missing_Atmospheric RenderEnvironment Volume_Fog Volume_Light BitmapIO Autodesk_Animator_Flic AVI BMP bmpio CIN CMB EPS_Image GIF IFL JPEG jpegio pngio Portable_Network_Graphics PSD_I_O QTime rgb RLA RPF Targa tgaio TIF YUV CustAttrib Missing_Custom_Attribute_Plugin filter Area Blackman Blendfilter Catmull_Rom Cook_Variable cubic

MAXScript Class Hierarchy

1699

Filter_kernel_plug_in_not_found Mitchell_Netravali Plate_Match_MAX_R2 Quadratic Sharp_Quadratic Soften Video FloatController AudioFloat bezier_float Block Float_Expression float_list Float_Motion_Capture Float_Reactor float_script Float_Wire FloatList FloatReactor linear_float LOD_Controller Missing_Float_Control Noise_float On_Off SlaveFloat tcb_float Waveform_Float WireFloat GlobalUtilityPlugin MaxRenderer_COM_Server Plugin_Manager IKSolver IKHISolver IKLimb MasterBlockController Block_Control Master_Controller_plugin_not_found MasterBlock MasterList material Blend compositematerial DoubleSided doubleSidedMat Matte MatteShadow Missing_Mtl Morphermaterial Multimaterial multiSubMaterial NoMaterial

1700

Chapter 19

MAXScript Grammar and Class Hierarchy

RaytraceMaterial Shellac standard Standardmaterial TexOutputClass StandardTextureOutput textureMap Adobe_Photoshop_Plug_In_Filter Adobe_Premiere_Video_Filter bitmapTex Bitmaptexture Bricks Cellular cellularTex Checker Combustion compositeTexture CompositeTexturemap Dent dents falloff fallofftextureMap Flat_Mirror flatMirror Gradient Gradient_Ramp Marble Mask maskTex Missing_TextureMap Mix mixTexture Noise NoTexture output Particle_Age Particle_MBlur particleBlur Perlin_Marble perlinMarble Planet Raytrace Reflect_Refract reflectRefract RGB_Multiply RGB_Tint rgbMult rgbTint Smoke Speckle Splat

MAXScript Class Hierarchy

1701

Stucco Swirl Thin_Wall_Refraction thinWallRefraction Vertex_Color Water Wood TopBottom topBottomMat UVGenClass Missing_UVGen StandardUVGen XYZGenClass Missing_XYZGen StandardXYZGen Matrix3Controller IK_ControllerMatrix3Controller IKChainControl IKControl Link Link_Constraint lookat Missing_Matrix3_Control prs Slave_Control transform_script TVDummyControl modifier Affect_Region Bend BendMod Bevel Bevel_Profile CameraMap Cap_Holes ConvertToPatch CrossSection DeleteMesh DeletePatch DeleteSplineModifier Disp_Approx Displace Edit_Mesh Edit_Patch Edit_Spline Extrude Face_Extrude FFD_2x2x2 FFD_3x3x3 FFD_4x4x4 FFD_Select

1702

Chapter 19

MAXScript Grammar and Class Hierarchy

FFD2x2x2 FFD3x3x3 FFD4x4x4 FFDBox FFDCyl Fillet_Chamfer Flex HSDS_Modifier HSDSObject Lathe Lattice Linked_XForm LinkedXForm MaterialByElement Materialmodifier Melt Mesh_Select MeshSelect meshsmooth MIrror Missing_OSM Morpher MultiRes NCurve_Sel Noisemodifier Normalize_Spl Normalize_Spline Normalmodifier NSurf_Sel optimize Patch_Select PatchDeform PathDeform Point_Cache PointCache Poly_Select Preserve Push Relax Ripple Skew Skin SliceModifier smooth SmoothModifier Spherify SplineSelect Squeeze STL_Check Stretch surface

MAXScript Class Hierarchy

1703

SurfDeform Taper tessellate Trim_Extend Turn_to_Mesh Turn_to_Patch Turn_to_Poly Twist Unwrap_UVW UVW_Xform Uvwmap UVWUnwrap Vertex_Colors VertexPaint Vol__Select VolumeSelect Wave XForm MorphController Barycentric_Morph_Controller Cubic_Morph_Controller Missing_Morph_Control MPassCamEffect Depth_of_FieldMPassCamEffect Motion_BlurMPassCamEffect multiPassDOF multiPassMotionBlur Standin_for_missing_MultiPass_Camera_Effect_Plugin node camera Freecamera Missing_Camera Targetcamera GeometryClass Apollo_Param_Container apolloParamContainer Blizzard BoneGeometry BoneObj Boolean2 Box C_Ext Capsule ChamferBox ChamferCyl Cone Conform Connect ControlContainer CV_Surf Cylinder

1704

Chapter 19

MAXScript Grammar and Class Hierarchy

Damper Editable_mesh Editable_Patch Editable_Poly EditablePolyMesh Gengon GeoSphere Hedra Hose L_Ext Loft LoftObject Mesher meshGrid Missing_GeomObject Morph Nurbs NURBS_Imported_Objects NURBSSurf OilTank OldBoolean PArray particleMesher PCloud Plane Point_Surf Point_SurfGeometry PolyMeshObject Prism Pyramid Quadpatch RingWave RmModel RmModelGeometry Scatter ShapeMerge SlidingDoor SlidingWindow Snow Sphere Spindle Spray Spring SuperSpray Targetobject Teapot Terrain Torus Torus_Knot TriMeshGeometry Tripatch

MAXScript Class Hierarchy

1705

Tube helper Anchor AudioClip Background Billboard Bone BoxGizmo CamPoint Compass Cone_Angle ConeAngleManip CylGizmo Dummy Falloff_Manipulator FalloffManip FogHelper grid Hotspot_Manip HotspotManip IK_Chain_Object IK_Swivel_Manip IKSwivelManip Inline LOD Missing_Helper NavInfo Plane_Angle PlaneAngleManip Point PointHelperObj Position_Manip PositionManip Protractor ProxSensor radiusManip Reactor_Angle_Manip Reactor_Vector_Handle_Manip ReactorAngleManip ReactorVectorHandleManip Rotation_ Rotation_Valuehelper RotationValueManip Slider_Manip SliderManip sliderManipulator Sound SphereGizmo Tape TimeSensor TouchSensor

1706

Chapter 19

MAXScript Grammar and Class Hierarchy

uvwMappingHeightManip uvwMappingLengthManip uvwMappingUTileManip uvwMappingVTileManip uvwMappingWidthManip light Directionallight freeSpot Missing_Light Omnilight TargetDirectionallight targetSpot NodeObject shape Arc Circle CV_Curve CV_Curveshape Donut Ellipse Helix line LinearShape Lines Missing_Shape Ngon NURBSCurveShape Point_Curve Point_Curveshape Rectangle section Simple_Shape Simple_Spline SplineShape Star text SpacewarpObject BendModWSM Bomb CameraMapSpaceWarp ConformSpaceWarp Deflector Drag gravity MapScalerSpaceWarp Missing_WSM_Object Motor Path_Follow PathDeformSpaceWarp PBomb PDynaFlect

MAXScript Class Hierarchy

1707

PDynaflector POmniFlect PSpawnflector PushSpaceWarp SDeflector SDynaFlect SDynaflector SOmniFlect SpaceBend Spacedisplace SpaceFFDBox SpaceFFDCyl SpaceNoise Spaceripple SpaceSkew SpaceStretch SpaceTaper SpaceTwist Spacewave SSpawnflector UDeflector UDynaDeflector UDynaFlect UOmniFlect USpawnDeflector Vortex Wind System Bones Missing_System Ring_Array Sunlight XRefObject ParamBlock ParamBlockParamBlock ParamBlock2 ParamBlock2ParamBlock2 Point3Controller AudioPoint3 bezier_color bezier_point3 Color_RGB Missing_Point3_Control Noise_point3 Point3_Expression point3_list Point3_Motion_Capture Point3_Reactor point3_script Point3_Wire Point3_XYZ

1708

Chapter 19

MAXScript Grammar and Class Hierarchy

Point3List Point3Reactor Point3Spring Slave_Point3 SlavePoint3 SpringPoint3Controller tcb_point3 WirePoint3 PositionController Attachment AudioPosition bezier_position Dynamics_Position_Controller linear_position Missing_Position_Control Noise_position path Path_Constraint Position_Constraint Position_Expression position_list Position_Motion_Capture Position_Reactor position_script Position_Wire Position_XYZ PositionList PositionReactor PositionSpring SlavePos SpringPositionController Sunlight_Slave_Controller Surface_position tcb_position WirePosition QuatController RadiosityEffect Missing_Radiosity ReferenceMaker CurveControl CustAttribContainer Deform_Curve HSUtil Material_Editor MeshCollision Missing_RefMaker MtlBaseLib MtlLib NamedSelSetList NodeNamedSelSet PlanarCollision

MAXScript Class Hierarchy

1709

Scene SphericalCollision StdDualVS Texmaps TexmapsReferenceMaker ReferenceTarget Auto_Secondary_Element Bulge_Angle_Deformer gizmoBulge gizmoJoint gizmoJointMorph Glow_Element Gradient_GradCtlData IK_Controller JAngleData JBinaryData JBoolData JColor3Data JColorData JFlagCtlData JFlagSetData JFloat3Data JFloatData JGradCtlData Joint_Angle_Deformer Joystick_Input_Device JPercent3Data JPercentData JSubtex JWorld3Data JWorldData LZFlare_AutoSec_Base LZFlare_AutoSec_Data LZFlare_Aux_Data LZFlare_Data LZFlare_Glow_Data LZFlare_Inferno_Data LZFlare_ManSec_Base LZFlare_ManSec_Data LZFlare_Prefs_Data LZFlare_Rays_Data LZFlare_Rend_Data LZFlare_Ring_Data LZFlare_Star_Data LZFlare_Streak_Data LZFocus_Data LZGlow_Aux_Data LZGlow_Data LZGlow_Rend_Data LZHilight_Aux_Data LZHilight_Data

1710

Chapter 19

MAXScript Grammar and Class Hierarchy

LZHilight_Rend_Data Manual_Secondary_Element MIDI_Device Missing_RefTarget Morph_Angle_Deformer Mouse_Input_Device Ray_Element Ray_Engine Raytrace_Engine_Global_Parameters Raytrace_Texture_ParamBlock RenderElementMgr Ring_Element Star_Element Streak_Element This_Data TVNode renderEffect blur Brightness_and_Contrast briteCon Color_Balance colorBalance Depth_of_Field DOFEffect File_Output fileOut Film_Grain FilmGrain imageMotionBlur Lens_Effects Missing_Render_Effect Motion_Blur RenderElement Alpha alphaRenderElement Atmosphere atmosphereRenderElement BackgroundRenderElement Beauty beautyRenderElement bgndRenderElement BlendRenderElement clrShadowRenderElement Colored_Shadow Diffuse diffuseRenderElement emissionRenderElement Missing_Render_Element_Plug_in Reflection reflectionRenderElement Refraction

MAXScript Class Hierarchy

1711

refractionRenderElement Self_Illumination ShadowRenderElement Specular specularRenderElement Z_Depth ZRenderElement RendererClass Default_Scanline_Renderer DefaultScanlineRenderer Missing_Renderer VUE_File_Renderer RotationController AudioRotation bezier_rotation Dynamics_Rotation_Controller Euler_XYZ linear_rotation Local_Euler_XYZ LookAt_Constraint Missing_Rotation_Control Noise_rotation Orientation_Constraint rotation_list Rotation_Motion_Capture Rotation_Reactor rotation_script Rotation_Wire RotationList RotationReactor SlaveRotation tcb_rotation WireRotation ScaleController AudioScale bezier_scale linear_scale Missing_Scale_Control Noise_scale Scale_Expression scale_list Scale_Motion_Capture Scale_Reactor scale_script Scale_Wire ScaleList ScaleReactor ScaleXYZ SlaveScale tcb_scale WireScale

1712

Chapter 19

MAXScript Grammar and Class Hierarchy

Shader Anisotropic Blinn Blinn2 BlinnShader Metal Metal2 Missing_Shader_Plug_in Multi_Layer MultiLayer Oren_Nayar_Blinn OrenNayarBlinn Phong Phong2 Strauss Shadow raytraceShadow shadowMap SpacewarpModifier Bombbinding Deflectorbinding Displace_Mesh Displace_NURBS Displacebinding DragMod FFD_Binding Gravitybinding MapScaler Missing_WSM MotorMod Particle_Cache ParticleCache Path_FollowMod PBombMod PDynaFlectMod Point_CacheSpacewarpModifier PointCacheWSM POmniFlectMod PushMod Ripplebinding SDeflectMod SDynaFlectMod SimpleOSMToWSMMod SOmniFlectMod SpaceCameraMap SpaceConform SpacePatchDeform SpacePathDeform SpaceSurfDeform Surface_Mapper UDeflectorMod

MAXScript Class Hierarchy

1713

UDynaFlectMod UOmniFlectMod VortexMod Wavebinding Windbinding ToneOperator Automatic_Exposure_Control AutomaticAdaptiveExposureControl Missing_Exposure_Control UtilityPlugin ASCII_Object_Output Asset_Browser Assign_Vertex_Colors Camera_Match Camera_Tracker collapse Color_Clipboard COM_DCOM_Server_Control Dynamics Follow_Bank IFL_Manager Level_of_Detail Link_Inheritance__Selected MapPath_Editor MAX_File_Finder MAXScript Measure Motion_Capture Polygon_Counter Rescale_World_Units Reset_XForm Resource_Collector Shape_Check Strokes Surface_Approximation UVW_Remove Visual_MAXScript VisualMSUtil

1714

Chapter 19

MAXScript Grammar and Class Hierarchy

Chapter 20:

Using the HTML Help Viewer

Using the HTML Help Viewer

This online information system is a compiled HTML help (.chm) file; you view it using Microsofts HTML Help Viewer, powered by Internet Explorer. The HTML Help Viewer is a three-pane window: The Navigation pane (p. 1717) is on the left side of the window. It contains four navigational tabs, for Contents, Index, Search (p. 1718), and Favorites (p. 1721). The Topic pane is on the right side of the window. It displays the selected help topic, or the default help topic. The toolbar (p. 1721) is the third pane, located below the help window title bar. To link to another topic or a list of other topics, click the colored, underlined words in the Topic pane. If you use a particular help topic often, you can add it to your favorites list (p. 1721). Right-click the Contents or Favorites tab or the Topic pane for shortcut menu commands.

Here are some tips on how to find more information when using the HTML Help Viewer:

See also
Finding Information Fast (p. 1717) Searching for Help Topics (p. 1718) Note: Most of information about using the HTML Help Viewer has been supplied directly by Microsoft. It has been made freely available for inclusion in HTML help projects such as this one. This information has been edited and reformatted to match the Discreet online information systems.

1716

Chapter 20

Using the HTML Help Viewer

Procedures
To find a help topic 1. In the Navigation pane, click one of the following tabs: To browse through a table of contents, click the Contents tab. The table of contents is an expandable list of important topics. To see a list of index entries, click the Index tab, and then type a word or scroll through the list. Topics are often indexed under more than one entry. To locate every occurrence of a word or phrase that may be contained in a help file, click the Search tab, and then type the word. 2. Click the contents entry, index entry, or search results entry to display the corresponding topic.

To copy a help topic 1. 2. 3. 4. 5. In the Topic pane, right-click the topic you want to copy, and then click Select All. Right-click again, and then click Copy. This copies the topic to the Clipboard. Open the document you want to copy the topic to. Position your cursor where you want the information to appear. On the Edit menu, click Paste.

To copy only part of a topic Select the text you want to copy, right-click, and then click Copy.

To print the current help topic Right-click a topic, and then click Print. If you print from the Contents tab (by right-clicking an entry, and then clicking Print) you will see options to print only the current topic, or the current topic and all subtopics. To hide or show the Navigation pane On the toolbar, click Hide or Show to close or display the Navigation pane, which contains the Contents, Index, Search, and Favorites tabs. If you close the Help Viewer with the Navigation pane hidden, it will appear that way when you open the Help Viewer again.

Finding Information Fast

1717

Finding Information Fast

Use the Navigation pane in the Help Window to get to information quickly. It contains tabs that let you use Contents, Index, or Search techniques to get to topics you need.

Contents Tab
The Contents tab displays the main sections of this 3ds max online system as book icons. When you click a book, it expands to show the list of topics contained within it, like chapters in hard-copy books. To go to a topic from the Contents tab 1. 2. 3. Click the Contents tab to display the Table of Contents view. Click the book icon representing the area for which you want information. The page icons for the book expand below representing all the topics for the books feature area. Click the page icon for the topic you want.

Index Tab
The Index is an alphabetical listing of keywords found in each topic. A single keyword may be linked to more than one topic. You may type the first few letters of a subject to jump to an index entry that matches what you are looking for. To go to a topic from the Index tab 1. 2. 3. Click the Index tab to display the Help Index. In the form at the top of the Index, type the subject you want to find, or scroll through the alphabetical list to find the term for which you need information. Click the term, then click Display to see the topic for that term, or double-click the term to see its topic. The topic displays in the right pane and may show links to related topics.

Search Tab
The Search tab summons a full-text search engine that operates on a database of every word in the help system, created when the HTML Help system was compiled. You can use tools on the Search tab to find the help topics (p. 1718) containing any word or phrase.

1718

Chapter 20

Using the HTML Help Viewer

Searching for Help Topics

A basic search consists of the word or phrase you want to find. You can use Boolean, wildcard, and nested expressions. You can also limit the search to previous results, match similar words, or search topic titles only to further define your search. The basic rules for formulating queries are as follows: Searches are not case-sensitive, so you can type your search in uppercase or lowercase characters. You may search for any combination of letters (a through z) and numbers (0 through 9). Punctuation marks such as the period, colon, semicolon, comma, and hyphen are ignored during a search. Group the elements of your search using double quotes (p. 1718) or parentheses (p. 1719) to set apart each element. You cannot search for quotation marks. Note: If you are searching for a file name with an extension, you should group the entire string in double quotes, (filename.ext). Otherwise, the period will break the file name into two separate terms. The default operation between terms is AND, so you will create the logical equivalent to filename AND ext.

Searching for Words or Phrases: Using Wildcards

You can search for words or phrases and use wildcard expressions. Wildcard expressions allow you to search for one or more characters using a question mark or asterisk. The table below describes the results of these different kinds of searches.
Search for A single word A phrase select new operator or new operator Example Results Topics that contain the word select. (You will also find its grammatical variations, such as selector and selection.) Topics that contain the literal phrase new operator and all its grammatical variations. Without the quotation marks, the query is equivalent to specifying new AND operator, which will find topics containing both of the individual words, instead of the phrase. Topics that contain the terms ESC, escape, escalation, and so on. The asterisk cannot be the only character in the term. Topics that contain the terms 80186, 80286, 80386, and so on. The question mark cannot be the only character in the term.

Wildcard expressions esc* or 80?86

Turn on Match Similar Words to include minor grammatical variations for the phrase you search.

Searching for Help Topics

1719

Defining Search Terms: Using Boolean Expressions

The AND, OR, NOT, and NEAR operators enable you to precisely define your search by creating a relationship between search terms. The following table shows how you can use each of these operators. If no operator is specified, AND is used. For example, the query spacing border printing is equivalent to spacing AND border AND printing.
Search for Both terms in the same topic. Either term in a topic. Example dib AND palette raster OR vector Results Topics containing both the words dib and palette. Topics containing either the word raster or the word vector or both. Topics containing the word OLE, but not the word DDE. Topics containing the word user within eight words of the word kernel.

The first term without ole NOT dde the second term. Both terms in the same topic, close together. user NEAR kernel

Note: The |, &, and ! characters dont work as Boolean operators (you must use OR, AND, and NOT).

Using Nested Expressions When Searching

Nested expressions allow you to create complex searches for information. For example, control AND ((active OR dde) NEAR window) finds topics containing the word control along with the words active and window close together, or containing control along with the words dde and window close together. The basic rules for searching help topics using nested expressions are as follows: You can use parentheses to nest expressions within a query. The expressions in parentheses are evaluated before the rest of the query. If a query does not contain a nested expression, it is evaluated from left to right. For example: Control NOT active OR dde finds topics containing the word control without the word active, or topics containing the word dde. On the other hand, control NOT (active OR dde) finds topics containing the word control without either of the words active or dde. You cannot nest expressions more than five levels deep.

Procedures
To go to a topic from the Search tab 1. 2. 3. 4. Click the Search tab, and then type the word or phrase you want to find. Click the Boolean button (to the right of the test field) to add Boolean operators to your search. Click List Topics, choose the topic you want, and then click Display. To sort the topic list alphabetically, click the Title column heading.

1720

Chapter 20

Using the HTML Help Viewer

You can precisely define a search by using wildcard expressions, nested expressions, and Boolean operators. You can request similar word matches, search only the topic titles, or search the results of a previous search. You can set the Help Viewer to highlight all instances of search terms that are found in topic files. Click the Options button, and then click Search Highlight On. To highlight words in searched topics When searching for words in help topics, you can have each occurrence of the word or phrase highlighted in the topics that are found. To highlight all instances of a search word or phrase, click Options on the toolbar, and then click Search Highlight On. To turn off this option, click Options on the toolbar, and then click Search Highlight Off. If you are viewing a long topic, only the first 500 instances of a search word or phrase will be highlighted. To search for words in the titles of HTML files 1. 2. Click the Search tab, type the word or phrase you want to find, and then turn on Search Titles Only. Click List Topics, choose the topic you want, and then click Display. If you use this option, all HTML topic files will be searched, including any that are not listed in the table of contents. To find words similar to your search term This feature enables you to include minor grammatical variations for the phrase you search. For example, a search on the word add will find add, adds, and added. 1. 2. Click the Search tab, type the word or phrase you want to find, and then turn on Match Similar Words. Click List Topics, choose the topic you want, and then click Display. This feature only locates variations of the word with common suffixes. For example, a search on the word add will find added, but it will not find additive. To search only the last group of topics you searched This feature enables you to narrow a search that results in too many topics found. You can search through your results list from previous search by using this option. 1. 2. On the Search tab, turn on Search Previous Results. Click List Topics, choose the topic you want, and then click Display. If you want to search through all of the files in a help system, this check box must be off. If you previously used this feature, the Search tab opens with this check box turned on.

Favorites Tab

1721

To repeat an earlier search Click the down arrow on the text-entry field and choose a previously used search string, and then click List Topics.

Favorites Tab
Use tools on the Favorites tab to create a set of topics you use often; you can name them as you choose.

Procedures
To create a list of favorite help topics 1. 2. Locate the help topic you want to make a favorite topic. Click the Favorites tab, and then click Add.

To return to a favorite topic 1. 2. Click the Favorites tab. Choose the topic, and then click Display.

To rename a topic in the Favorites list Choose the topic, and then enter a new name in the Current topic box.

To remove a favorite topic Choose the topic, and then click Remove.

HTML Help Viewer Toolbar

The Help Viewer toolbar contains the following features. Hide/Show: Click this toggle to hide the Navigation pane when it is displaying, or show it when its hidden. Back/Forward: Click to move to the previously viewed topic, or forward to the following previouslyviewed topic. Print: Prints the current topic (if the Topic pane is active). If the table of contents is active on the Navigation pane, you can choose to print the current topic, or the topic and its subtopics. This is a way of printing a collection of topics. Options menu: Contains the following commands. Hide/Show Tabs: Same as Hide/Show buttons, above. Back/Forward: Same as Back/Forward buttons, above. Home: Displays the main topic of this online system. Stop: Halts display of a topic. Refresh: Redraws the Help Viewer display.

1722

Chapter 20

Using the HTML Help Viewer

Internet Options: Displays a dialog to change Internet Explorer (IE) settings. The 3ds max information systems do not use this feature. Making changes here does not affect these systems, but will alter your IE browser settings. We do not recommend you use this option. Print: Same as the Print button, above. Search Highlight On/Off: Toggles highlighting on and off for each occurance of a word or phrase found with a search.

HTML Help Viewer Right-Click Menus

There are several commands on the shortcut menu that you can use to display information.
Command Right-click in the table of contents, and then click Open All. Right-click in the table of contents, and then click Close All. Description Opens all books or folders in the table of contents. This command only works if the Contents tab is displayed. Closes all books or folders. This command only works if the Contents tab is displayed.

Right-click in the Topic pane, or an entery in the table of Prints the topic. contents, and then click Print. Right-click an entry in the Favorites tab. Choose to display, add, remove, or rename a topic.

Keyboard Shortcuts in the Help Viewer

The following keyboard shortcuts can be used for navigation in the HTML Help Viewer, or the Contents (p. 1723), Index (p. 1723), Search (p. 1723), or Favorites (p. 1724) tabs on the Navigation pane.

Help Viewer
To Close the Help Viewer. Switch between the Help Viewer and other open windows. Display the Options menu. Hide or show the Navigation pane. Print a topic. Move back to the previous topic. Move forward to the next topic (provided you have viewed it just previously). Turn on or off search highlighting. Refresh the topic that appears in the Topic pane (this is useful if you have linked to a Web page). ALT+F4 ALT+TAB ALT+O ALT+O, and then press T ALT+O, and then press P, or right-click in the Topic pane and choose Print. ALT+LEFT ARROW, or ALT+O, and then press B ALT+RIGHT ARROW, or ALT+O, and then press F ALT+O, and then press O F5, or ALT+O, and then press R Press

Keyboard Shortcuts in the Help Viewer

1723

To Return to the home page (help authors can specify a home page for a help system). Switch between the Navigation and Topic panes. Scroll through a topic. Scroll through all the links in a topic or through all the options on a Navigation pane tab. ALT+O, and then press H F6

Press

UP ARROW and DOWN ARROW, or PAGE UP and PAGE DOWN TAB

Contents Tab
To Display the Contents tab. Open and close a book or folder. Choose a topic. Display the selected topic. ALT+C PLUS SIGN and MINUS SIGN, or LEFT ARROW and RIGHT ARROW DOWN ARROW and UP ARROW ENTER Press

Index Tab
To Display the Index tab. Type a keyword to search for. Choose a keyword in the list. Display the associated topic. ALT+N ALT+W, and then type the word UP ARROW and DOWN ARROW ALT+D Press

Search Tab
To Display the Search tab. Type a keyword to search for. Start a search. Choose a topic in the results list. Display the selected topic. Search for a keyword in the result list of a prior search. Search for words similar to the keyword. For example, to find words like running and runs for the keyword run. Only search through topic titles. ALT+S ALT+W, and then type the word ALT+L ALT+T, and then UP ARROW and DOWN ARROW ALT+D ALT+U ALT+M Press

ALT+R

1724

Chapter 20

Using the HTML Help Viewer

Favorites Tab
To Display the Favorites tab. Add the currently displayed topic to the Favorites list. Choose a topic in the Favorites list. Display the selected topic. Remove the selected topic from the list. ALT+I ALT+A ALT+P, and then UP ARROW and DOWN ARROW ALT+D ALT+R Press

Notes:
There are also shortcut menu commands (p. 1722) that can be accessed through the keyboard. Every time you use a shortcut key in the Navigation pane, you lose focus in the Topic pane. To return to the Topic pane, press F6. The Match Similar Words check box, on the Search tab, will be turned on if you used it for your last search.

Chapter 21:

character studio 3 MAXScript Extensions

Biped General Topics

Biped Load and Save Methods
This topic will cover the load and save methods for motion, figure, score, keys, motion capture, and talent files. -- Motion File Access Methods
biped.LoadBipFile <biped_ctrl> <filename>

Load a biped motion file. Motion files include, footsteps, keyframe settings, the biped scale, and the active gravity value (GravAccel). IK Blend values for the keys and Object Space Object information are also loaded.
biped.SaveBipFile <biped_ctrl> <filename>

Save a biped motion file. A .bip file includes footsteps and keyframe data. Biped files store the complete movement and allow you to create libraries of motion. Create your own .bip library by animating the biped and saving a .bip file. Notes: Load/Save a Biped (.BIP) file -- Figure File Access Methods
biped.LoadFigFile <biped_ctrl> <filename>

Load a Figure file. Figure mode must be active to load a Figure file. Figure files allow you to apply the structure of one biped to another. Reload a Figure file if you accidentally lose your biped Figure mode pose; this pose is the biped fitted to a mesh.
biped.SaveFigFile <biped_ctrl> <filename>

Save the structure and position of a biped in Figure mode. After fitting the biped to a mesh in Figure mode, save a figure file. If the biped is accidentally moved in Figure mode, reload this file.

1726

Chapter 21

character studio 3 MAXScript Extensions

Notes: Load/Save a Figure (*.FIG) file -- Score File Access Methods

biped.LoadScoreFile <biped_ctrl> <filename> biped.SaveScoreFile <biped_ctrl> <filename>

Score files are Step files which save footsteps, but dont save body keyframes. They are an ASCII file format that enables developers to write programs that generate step files for biped motion. The online document stp.rtf, provided with character studio in the \cstudio\docs directory, describes the .stp format. Notes: Load/Save a Step (*.STP) file -- Motion Capture File Access Methods
biped.loadMocapFile <biped_ctrl> <file_name> [#prompt]

Load a motion capture (.BIP, .BVH, .CSM) file. If #prompt is specified, the file is not automatically loaded, rather the Motion Capture Conversion Parameters dialog is displayed with the specified file as the motion capture file. -- Talent File Access Methods
biped.adjustTalentPose <biped_ctrl>

After loading a marker file, use Adjust Talent Pose to correct the biped position relative to the markers. Align the biped limbs to the markers then call biped.adjustTalentPose to compute this offset for all the loaded marker data. Note: Calibration controls are only enabled when a marker or .bvh file is imported in its raw form. Do not use key reduction or extract footsteps when you import a marker file for the first time.
biped.saveTalentFigFile <biped_ctrl> <file_name>

After changing the biped scale in Talent Figure mode, save the changes into a .fig file. Use this file in the Motion Capture Conversion Parameters dialog to adjust marker files created by the same actor.
biped.saveTalentPoseFile <biped_ctrl> <file_name>

Save a Talent Pose adjustment as a .cal file. Save a .cal file after adjusting the biped relative to the markers. A .cal file is used for processing marker files that require the same adjustment. A .cal file can be loaded in the Motion Capture Conversion Parameters dialog during marker file importation. -- Layer related methods
biped.collapseAtLayer <biped_ctrl> <index>

Collapses all layers till the specified layer. All underneath should be active for this function to work. Return true if successful, otherwise false.
biped.createLayer <biped_ctrl> <index> <name>

Creates a layer at the specified position, maximum index value can be NumLayers + 1

Biped Creation

1727

biped.deleteLayer <biped_ctrl> <index>

Deletes the specified layer

biped.getCurrentLayer <biped_ctrl>

Returns the position of the currently active layer in the UI

biped.getLayerActive <biped_ctrl> <index>

Returns true if the specified layer is active.

biped.getLayerName <biped_ctrl> <index>

Returns the specified layer name

biped.numLayers <biped_ctrl>

Returns the number of layers

biped.setCurrentLayer <biped_ctrl> <index>

Sets the active layer in the UI to the specified layer

biped.setLayerActive <biped_ctrl> <index> <bool_val>

Sets the specified layer to active/inactive based upon the bool_val passed
biped.setLayerName <biped_ctrl> <index> <name>

Sets the specified layer name to the value passed The following example will create a new Biped, access its Vertical_Horizontal_Turn(Body) controller and load a specific *.Bip file: Script Example:
-- create a new Biped bipObj = biped.createNew 100 100 [0,0,0] -- select bipObj bip = bipObj.transform.controller max motion mode -- File I/O biped.LoadBipFile bip (CSPATH + scripts\\Limploop.bip)

See Also
Biped Creation (p. 1727) Biped Controllers (p. 1735) Biped MaxScript Extensions (p. 1725)

Biped Creation
The following properties and methods are applicable to any created Biped. Constructor:
biped.createNew <height_float> <angle_float> <wpos_point3> . . . <height_float> <angle_float> <wpos_point3> shadow. the height of the Biped to be created angle in degrees world position of the Biped. This is the position of the COM

0( will make the Biped face towards the right.

1728

Chapter 21

character studio 3 MAXScript Extensions

Creation Properties:
<biped>.arms <biped>.neckLinks <biped>.spineLinks <biped>.legLinks <biped>.tailLinks <biped>.ponytail1Links <biped>.ponytail2Links <biped>.fingers <biped>.fingerLinks <biped>.toes <biped>.toeLinks <biped>.ankleAttach Boolean Integer Integer Integer Integer Integer Integer Integer Integer Integer Integer Float Default: True Default: 1 Default: 4 Default: 3 Default: 0 Default: 0 Default: 0 Default: 1 Default: 3 Default: 5 Default: 3 Default: 0.2

Specifies whether or not arms will be generated for the current biped. Specifies the number of links in the biped neck. Specifies the number of links in the biped spine. Specifies the number of links in the biped legs. Specifies the number of links in the biped tail. A value of 0 specifies no tail. Specifies the number of Ponytail links. Specifies the number of Ponytail links. Specifies the number of biped fingers. Sets the number of links per finger. Specifies the number of biped toes. Specifies the number of links per toe. Specifies the right and left ankles point of attachment along the corresponding foot block. The ankles may be placed anywhere along the center line of the foot block from the heel to the toe. A value of 0 places the ankle attachment point at the heel. A value of 1 places the ankle attachment point at the toes.
<biped>.trianglePelvis Boolean Default: True

Select this control to create links from the upper legs to the lowest biped spine object when Physique is applied. Normally, the legs are linked to the biped pelvis object. The pelvis area can be a problem when the mesh is deformed with Physique. Triangle Pelvis creates a more natural spline for mesh deformation.

Biped Display Preferences Access

1729

Notes: Creates a new Biped with the given keyword parameters. All UI limit constraints apply on keyword parameters, example: fingers and fingerLinks parameters are not respected when arms is set to false. The following example will create a Biped with specific non default values and facing the front. Script Example:
bipObj = biped.createNew 100 -90 [0,0,0] arms:true neckLinks:2 \ spineLinks:4 legLinks:4 tailLinks:1 ponyTail1Links:1 \ ponyTail2Links:1 fingers:5 fingerLinks:2 toes:4 \ toesLinks:2 ankleAttach:0.3 trianglePelvis:True

See also
Biped MAXScript Extensions (p. 1725)

Biped Display Preferences Access

Displays the Biped Display Preferences dialog. Method:
biped.displayPrefsDlg <biped_ctrl> <biped_ctrl> Controller which is attached to the transform track of the Biped root objects. A Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller (p. 1736)

The following example will display the Biped Display Preferences dialog: Script Example:
bipObj = biped.createNew 100 100 [0,0,0] select bipObj bip = bipObj.transform.controller -- Display properties biped.displayPrefsDlg bip

See Also
Biped Creation (p. 1727) Biped Controllers (p. 1735) Biped MaxScript Extensions (p. 1725)

1730

Chapter 21

character studio 3 MAXScript Extensions

Biped Sample Scripts

Here are the sample scripts that ship with character studio 3. The custom user interface, CS3Tools.cui, character studio 3 one-touch preset custom keys for rapid animation. It uses the MAXScripts: CS3Customkeys.ms, CS3convertBips.ms and CS3Bip2BonesFloater.ms and CS3CustomKeysPresetFloater.ms. Please see the CS3Tools.cui Tutorial (p. 1825) Tutorial_CSCustomKeys_cui2. An updated ../Cstudio/Docs/Readcsm.ms. -- Fixed frame-off-by-1 bug by making keyframes start at 0 instead of 1, to match biped -- Fixed frame rate interpretation - it was dropping mocap data correctly, but not skipping max frames ../Cstudio/Docs/csmxport.ms -- A script to output a .csm file -- This script assumes that you have set up a .max file containing a biped or bone structure with a set of markers linked to the skeleton. -- The markers you want to record should be contained in a Selection Set titled markers -- The script will output the data at every frame for the entire animation range.

See also
Biped MAXScript Extensions (p. 1725)

biped_object : GeometryClass
This class represents the individual Biped body part and footstep nodes baseobject. Properties:
<biped_object>.rootNode Node Default: Varies -- Read-only

The controller for the biped_object. For the COM, the controller type is Vertical_Horizontal_Turn. For footsteps, the controller type is FootSteps. For the remaining biped body parts, the controller type is BipSlave_Control.

See Also
Vertical_Horizontal_Turn Matrix3 Controller (p. 1736) FootSteps : Matrix3 Controller (p. 1744) BipSlave_Control Controllers (p. 1745)

Biped Layers

1731

Biped Layers
Layer Related Methods
biped.collapseAtLayer <biped_ctrl> <index_integer>

Collapses all layers till the specified layer. All underneath must be active for this function to work. Return true if successful, otherwise false.
biped.createLayer <biped_ctrl> <index_integer> <name_string>

Creates a layer at the specified position, maximum index value can be NumLayers + 1.
biped.deleteLayer <biped_ctrl> <index_integer>

Deletes the specified layer

biped.getCurrentLayer <biped_ctrl>

Returns the position of the currently active layer in the UI.

biped.getLayerActive <biped_ctrl> <index_integer>

Returns true if the specified layer is active.

biped.getLayerName <biped_ctrl> <index_integer>

Returns the specified layer name.

biped.numLayers <biped_ctrl>

Returns the number of layers.

biped.setCurrentLayer <biped_ctrl> <index_integer>

Sets the active layer in the UI to the specified layer.

biped.setLayerActive <biped_ctrl> <index_integer> <boolean_val>

Sets the specified layer to active/inactive based upon the boolean_val passed.
biped.setLayerName <biped_ctrl> <index_integer> <name_string>

Sets the specified layer name to the value passed.

Biped Node Hierarchy

biped.getNode <biped | biped_ctrl> <name | index> [link:<int_link>]

Returns the specified limbnode where the second argument can be a named limb like #larm, #rarm, #lfingers, #rfingers, #lleg, #rleg, #ltoes, #rtoes, #spine, #tail, #head, #pelvis, #footprints, #neck, #pony1, #pony2 or an integer index. . If you dont specify the link argument the top (first) node is returned. The only exception to this is for the biped COM, which does not contain any linked nodes (including itself). If the specified node does not exist, a value of undefined is returned.

1732

Chapter 21

character studio 3 MAXScript Extensions

The top level and their link nodes in character studio 3 are:
Link Nodes in Link Index Order L Clavicle R Clavicle L Finger0 L Finger11 L Finger22 L Finger4 4 R Finger0 R Finger0 R Finger11 R Finger22 R Finger4 5 6 7 L Thigh R Thigh L Toe0 L Thigh R Thigh L Toe0 L Toe11 L Toe22 L Toe4 8 R Toe0 R Toe0 R Toe11 R Toe22 R Toe4 9 10 11 12 13 14 15 16 17 18 19 Spine Tail Head Pelvis Biped COM Biped COM Biped COM Footsteps Neck Ponytail1 Ponytail2 Footsteps Neck Neck4 Ponytail1 Ponytail14 Ponytail2 Ponytail24 Ponytail21 Ponytail22 Ponytail23 Ponytail11 Ponytail12 Ponytail13 Neck1 Neck2 Neck3 Spine Spine4 Tail Tail4 Head Pelvis Tail1 Tail2 Tail3 L UpperArm R UpperArm L Finger01 L Finger12 L Finger3 L Finger41 R Finger01 R Finger12 R Finger3 R Finger41 L Calf R Calf L Toe01 L Toe12 L Toe3 L Toe41 R Toe01 R Toe12 R Toe3 R Toe41 Spine1 L Forearm R Forearm L Finger02 L Finger2 L Finger31 L Finger42 R Finger02 R Finger2 R Finger31 R Finger42 L HorseLink R HorseLink L Toe02 L Toe2 L Toe31 L Toe42 R Toe02 R Toe2 R Toe31 R Toe42 Spine2 Spine3 R Toe1 R Toe21 R Toe32 L Foot R Foot L Toe1 L Toe21 L Toe32 R Finger1 R Finger21 R Finger32 L Hand R Hand L Finger1 L Finger21 L Finger32

Index 1 2 3

Top Level L Clavicle R Clavicle L Finger0

Biped Node Hierarchy

1733

Example:
bipObj = biped.createNew 100 100 [0,0,0] -- create a biped nn = biped.maxNumNodes bipObj nl = biped.maxNumLinks bipObj for i = 1 to nn do ( anode = biped.getNode bipObj i if anode != undefined do ( format % :\t%\n i anode.name for j = 1 to nl do ( alink = biped.getNode bipObj i link:j if alink != undefined do format % : % \t%\n i j alink.name ) ) )

Biped Node Hierarchy related methods:

biped.maxNumNodes <biped | biped_ctrl>

Maximum nodes supported by Biped. In character studio 3, this value is 19. In future versions of character studio, additional top level nodes may be present. See the desrciption of biped.getNode() for a list of the top level nodes.
biped.maxNumLinks <biped | biped_ctrl>

Maximum link nodes supported by Biped. In character studio 3 this value is 16. In future versions of character studio, additional link nodes may be present. See the desrciption of biped.getNode() for a list of the link nodes. There are two levels of nodes in biped hierarchy, the top level ones are: L Clavicle R Clavicle L Thigh R Thigh Head Spine Pelvis Footsteps Neck

1734

Chapter 21

character studio 3 MAXScript Extensions

The rest of the nodes are links just like what you see in the structure rollout. UpperArm L Hand Finger2 Calf Foot ...etc You can get to left hand as follows: biped.getNode $ #lArm link:4 If the link argument is not specified then the top(first) node is returned.

Biped and Crowd Interaction

It is possible to influence clip selection for bipeds during a Crowd solution by using preferred clips. The following biped MAXScript functions allow users to set the biped preferred clip during a crowd solution (p. 1771).
biped.numPrefClips <biped_ctrl>

Returns the number of preferred clips

biped.getPrefClip <biped_ctrl> <index_integer>

Returns the name of the nth preferred clip.

biped.clearPrefClips <biped_ctrl>

Clears the preferred clip list.

biped.addPrefClip <biped_ctrl> <name_string>

Adds the clip to the preferred clip list. returns true if added, false if not added because it was already in the list.
biped.deletePrefClip <biped_ctrl> <name_string>

Deletes the named clip from the preferred clip list. Returns true is successful, false if the clip was not in the list.
biped.isPrefClip <biped_ctrl> <name_string>

Returns true if the clip is in the list, false if not.

biped.getCurrentClip <biped_ctrl>

Returns the name of the currently active clip for this biped - only relevant during a crowd solve.

Biped and Crowd Interaction

1735

The following are examples showing how the crowd system PerFrameFn (p. 1771) can be used to dynamically change the biped preferred clip. Example:
-- changes the preferred clip as a function of frame number. fn PerFrameFn crwd t = ( if (t == 200f) then ( a = $bip100 a = a.transform.controller biped.addprefclip a jog_L45 ))

Example:
-- changes the preferred clip as a function of the current clip. fn PerFrameFn crwd t = ( a = $bip100 a = a.transform.controller if (biped.getcurrentclip a == jog_L135) then biped.addprefclip a jog_L45 )

See Also
Crowd : helper (p. 1771)

Biped Controllers
The Biped controller, referred to as <biped_ctrl> in this documentation, is called the Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller (p. 1736). This is sometimes also called the body controller because it is equivalent to the Bipeds.transform.controller. The Biped footsteps have a controller. It is referred to as <footsteps_ctrl> in this documentation. See Biped Footsteps (p. 1745) for details regarding the FootSteps:Matrix3 Controller. Individual Biped body part objects and the Vertical, Horizontal, and Turning tracks of the Biped Vertical Horizontal Turn(Body):Matrix3_Controller (p. 1736) use the Biped Slave ControllerBiped_Slave_Controller Biped_Slave_Controller. This type of controller is attached to the transform track.

See also
Biped Slave Controller (p. 1745) Biped MAXScript Extensions (p. 1725)

1736

Chapter 21

character studio 3 MAXScript Extensions

Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller

This controller is attached to the transform track of the Biped root objects. Constructor:
biped_ctrl=bipobj.transform.controller

or:
<biped_ctrl>=$bip01.controller

Properties: All the following properties are get/set properties unless specified. -- Structure properties
<biped_ctrl>.rootName where XX is a number String Default: BipXX,

The name of the biped center of mass object. The center of mass (COM) is the root of the biped hierarchy, and is visible as a diamond shaped object in the biped pelvis area. The Root Name is appended to all the links of the biped hierarchy.
<biped_ctrl>.rootNode <biped_ctrl>.arms <biped_ctrl>.neckLinks <biped_ctrl>.spineLinks <biped_ctrl>.legLinks <biped_ctrl>.tailLinks <biped_ctrl>.ponytail1Links Node Boolean Integer Integer Integer Integer Integer Integer Integer Integer Default: Varies Default: True Default: 1 range: 1-5 Default: 4 range: 1-5 Default: 3 range: 3-4 Default: 0 range: 0-5 Default: 0 range: 0-5 Default: 0 range: 0-5 Default: 1 range: 0-5 Default: 3 range: 1-3 -- Read-only

The root node (COM) of the Biped system this biped_ctrl belongs to. Specifies whether or not arms will be generated for the current biped. Specifies the number of links in the biped neck. Specifies the number of links in the biped spine. Specifies the number of links in the biped legs. Specifies the number of links in the biped tail. A value of 0 specifies no tail. Specifies the number of Ponytail links.
<biped_ctrl>.ponytail2Links

Specifies the number of Ponytail links.

<biped_ctrl>.fingers

Specifies the number of biped fingers.

<biped_ctrl>.fingerLinks

Sets the number of links per finger. Note: If the number of fingers is 0, fingerLinks is always equal to 1.
<biped_ctrl>.toes Integer Default: 5 range: 1-5

Specifies the number of biped toes.

Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller

1737

<biped_ctrl>.toeLinks

Integer Float

Default: 3 range: 1-3 Default: 0.2 range: 0-1

Specifies the number of links per toe.

<biped_ctrl>.ankleAttach

Specifies the right and left ankles point of attachment along the corresponding foot block. The ankles may be placed anywhere along the center line of the foot block from the heel to the toe. A value of 0 places the ankle attachment point at the heel. A value of 1 places the ankle attachment point at the toes.
<biped_ctrl>.height Float Boolean Default: Defined at creation Default: True

Sets the height of the current biped.

<biped_ctrl>.trianglePelvis

Select this control to create links from the upper legs to the lowest biped spine object when Physique is applied. Normally, the legs are linked to the biped pelvis object. The pelvis area can be a problem when the mesh is deformed with Physique. Triangle Pelvis creates a more natural spline for mesh deformation. -- Animation properties
<biped_ctrl>.gravAccel Float Default: 5.63855*Body height

Sets the strength of the gravitational acceleration used to calculate the bipeds motion. By default, this parameter is set to accurately simulate Newtonian gravity as found on the Earths surface.
<biped_ctrl>.dynamicsType 0 Biped Dynamics Integer Default: 0 range: 0-1

Keys for the center of mass Balance Factor and Dynamics Blend parameters are set to a value of 1. Biped calculates airborne trajectories and biped balance.
1 Spline Dynamics

Create new center of mass keys using full spline interpolation.

Adapt Locks Group

Lock specified tracks to prevent automatic adjustments being made to those tracks when footsteps are moved in space or edited in time. All the locks except for Time work for footstep editing in space. Time, locks upper body keys when footsteps are edited in time (Track View). Adapt Locks only applies to a Footstep animation not a freeform animation. When you move a footstep in space or adjust footstep timing, Biped automatically adapts existing keyframes to match the new footsteps. Adapt locks allows you to preserve the exact position of already created keys for a selected track. Adapt Locks does not need to be on all the time. For example, if you want to raise all the footsteps along the world Z-axis, without changing the upper body position, turn on Adapt Locks Body Vertical Keys, turn on Footstep mode, select all the footsteps and move them up along the world Zaxis. The footsteps are repositioned, the legs are adapted, but the upper body retains the same motion rather than being raised with the footsteps. Now turn off Adapt Locks Body Vertical Keys, the upper body still retains its original motion.

1738

Chapter 21

character studio 3 MAXScript Extensions

<biped_ctrl>.adaptLockFreeform

Boolean

Default: False

Turn on to prevent adaptation of a freeform period in a footstep animation. The bipeds position during a freeform period will not move if footsteps after the freeform period are moved further away.
<biped_ctrl>.adaptLockHorz <biped_ctrl>.adaptLockTurn <biped_ctrl>.adaptLockVert <biped_ctrl>.adaptLockLLeg Boolean Boolean Boolean Boolean Default: False Default: False Default: False Default: False

Turn on to prevent adaptation of body horizontal keys when footsteps are edited in space. Turn on to prevent adaptation of body turning keys when footsteps are edited in space. Turn on to prevent adaptation of body vertical keys when footsteps are edited in space. Turn on to prevent adaptation of left leg move keys (a leg move key, is a leg key between footsteps) when footsteps are edited in space.
<biped_ctrl>.adaptLockRLeg Boolean Default: False

Turn on to prevent adaptation of right leg move keys (a leg move key, is a leg key between footsteps) when footsteps are edited in space.
<biped_ctrl>.adaptLockTime Boolean Default: False

Use Adapt Locks Time to retain upper body motion while editing footstep duration in Track View. When the duration of a footstep is changed, the biped leg will adapt by re-timing the touch, plant and lift keys. The biped upper body keys will retain their exact motion.

Separate Tracks Group

By default character studio stores a finger, hand, forearm, and upper-arm key in the clavicle track. The toe, foot and calf keys are stored in the thigh track. This optimized approach to key storage works well in most cases. If you need extra tracks, turn them on for a specific biped body part. For example, turn on Arms if you plan on extensive finger-hand animation; if an arm key is deleted, it will not affect the finger-hand keys. Notice that in Track View a transform track is now available for the first link of the thumb (stores all finger keys), hand, forearm, and upper-arm.
<biped_ctrl>.sepArmsTracks Boolean Default: False

Turn on to create separate transform tracks for the finger, hand, forearm and upper-arm. There is one finger track per hand. All finger keys are stored in the Finger0 transform track, the first link of the biped thumb.
<biped_ctrl>.sepLegsTracks <biped_ctrl>.sepPonytail1Tracks <biped_ctrl>.sepPonytail2Tracks Boolean Boolean Boolean Default: False Default: False Default: False

Turn on to create separate toe, foot, and calf transform tracks. Turn on to create separate ponytail 1 transform tracks. Turn on to create separate ponytail 2 transform tracks.

Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller

1739

Note: If the number of pony tail links is 0, you cannot set Separate Ponytail Tracks to true.
<biped_ctrl>.sepNeckTracks <biped_ctrl>.sepTailTracks <biped_ctrl>.sepSpineTracks Boolean Boolean Boolean Default: False Default: True Default: False

Turn on to create separate transform tracks for the neck links. Turn on to create separate transform tracks for each tail link. Turn on to create separate spine transform tracks. -- Modes
<biped_ctrl>.figureMode Boolean -- cannot be in Buffer mode to enter figureMode Default: False

Use Figure mode to fit a biped to the mesh or mesh objects representing your character. Leave Figure Mode on when you attach the mesh to the biped with Physique. Figure mode is also used to scale a biped with a mesh attached, to make biped fit adjustments after Physique is applied, and to correct posture in motion files that need a global posture change.
<biped_ctrl>.footstepMode Boolean Default: False

Create and edit footsteps; generate a walk, run, or jump footstep pattern; edit selected footsteps in space; and append footsteps using parameters available in Footstep mode.
<biped_ctrl>.motionMode Boolean -- cannot be in Buffer mode to enter motionMode Default: False

Create scripts and use editable transitions to combine .bip files together (to create character animation) in Motion Flow mode. After creating a script and editing transitions, use Save Segment on the General rollout to store a script as one long .bip file. Save a .mfe file, this enables you to continue Motion Flow work in progress.
<biped_ctrl>.bufferMode Boolean Default: False

Footsteps are required in the buffer to enter bufferMode. Edit segments of an animation in Buffer mode. Copy footsteps and associated biped keys into the buffer using Copy Footsteps on the Footstep Operation rollout first, then turn on Buffer mode to view and edit the copied segment of your animation. Note: Paste buffered motion back to the original animation repeatedly to create looping motions. Edit footsteps and biped animation that has been copied into the buffer using Copy Footsteps on the Footsteps Operation rollout. The changes can be pasted back by turning off Buffer Mode, turning on Paste Footsteps on the Footstep Operation rollout and overlapping the buffered footsteps with the original footsteps. The buffered motion is spliced into the original animation.

1740

Chapter 21

character studio 3 MAXScript Extensions

<biped_ctrl>.bendLinksMode

Boolean

Default: False

Bend all the biped spine objects naturally by rotating a biped spine object. Bend Links also works for the biped tail and ponytail links.
<biped_ctrl>.rubberBandMode Boolean Default: False

Use this to reposition the biped elbows and knees without moving the biped hands or feet in Figure mode. Reposition the biped center of mass to simulate the physics of wind or weight pushing against the biped. Figure mode must be turned on to enable Rubber Band Mode. Note: Rubber Band mode behaves differently than Non-Uniform Scale. If you Rubber Band the biped thigh, for example, the thigh and biped calf objects scale proportionally to keep the biped foot stationary. Using Non-Uniform Scale, the calf retains its scale and the foot moves.
<biped_ctrl>.scaleStrideMode Boolean Default: True

Footstep stride length and width are scaled to match the stride length and width of the biped figure. scaling occurs automatically when you load a .bip, .stp, or .fig file. When you paste footsteps; or when you scale the bipeds legs or pelvis.
<biped_ctrl>.inPlaceMode Boolean -- cannot be in Figure mode to enter inPlaceMode Default: False

Keep the biped visible in the viewports while the animation plays. Use this for biped key editing or adjusting envelopes with Physique. Prevents XY movement of the biped center of mass during animation playback; motion along the Z-axis is preserved. In Place mode is stored with the 3ds max file.
<biped_ctrl>.inPlaceXMode Boolean -- cannot be in Figure mode to enter inPlaceXMode Default: False

Lock center of mass X-axis motion. Use this for game export where the character stays in place but the swinging motion of the hips and upper body along the Y-axis is preserved.
<biped_ctrl>.inPlaceYMode Boolean -- cannot be in Figure mode to enter inPlaceYMode Default: False

Lock center of mass Y-axis motion. Use this for game export where the character stays in place but the swinging motion of the hips and upper body along the X-axis is preserved. Biped limbs, footsteps, and center of mass keys can be adjusted using In Place mode (when the center of mass is moved on the XY-axes in this mode, the footsteps move). View biped playback without requiring a follow camera. In this viewing mode, visible footsteps slide under the biped. For export to games, this feature is valuable since many game engines intelligently move the characters center of mass laterally according to game play. In Place mode makes it easy to view, tune, and export animation in a manner that is complimentary to game engine playback.

Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller

1741

Note: Trajectories do not display when In Place mode is active. -- Track Selection
<biped_ctrl>.trackSelection 0 - No track selection Integer Default: 0

While a trackSelection value of 0 is a valid return value, setting trackSelection to 0 is meaningless and will not change the current track selection.
1 - Body Horizontal

Turn on to prevent adaptation of body horizontal keys when footsteps are edited in space.
2 - Body Vertical

Turn on to prevent adaptation of body vertical keys when footsteps are edited in space.
3 - Body Rotation

Turn on to prevent adaptation of body turning keys when footsteps are edited in space. -- Display properties
<biped_ctrl>.displayBones Boolean Default: False

Displays biped bones. Bones are represented as yellow lines, which do not render. Selecting Bones is useful for seeing exactly where the joints fall in relation to the biped objects.
<biped_ctrl>.displayObjects Boolean Boolean Default: True Default: True

Displays biped body objects (objects).

<biped_ctrl>.displayFootsteps

Displays biped footsteps in the viewport. Footsteps are represented as green and blue footshaped outlines by default; these are also visible in preview renderings. Turning off the Footsteps button also turns off the footstep numbers and the center of mass shadow.
<biped_ctrl>.displayFSNumbers Boolean Default: True

Displays biped footstep numbers. Footstep numbers specify the order in which the biped will move along the path created by the footsteps. Footstep numbers are displayed in white and do not render, but do appear in preview renderings.
<biped_ctrl>.displayTrajectories Boolean Default: False

Displays trajectories for selected biped limbs. -- Layers

<biped_ctrl>.visibleBefore <biped_ctrl>.visibleAfter <biped_ctrl>.keyHighlight Integer Integer Boolean Default: 1 Default: 0 Default: False

Set the number of preceding layers too display as stick figures. Set the number of succeeding layers too display as stick figures. Display keys by highlighting the stick figures.

1742

Chapter 21

character studio 3 MAXScript Extensions

-- Footstep related properties

<biped_ctrl>.fsAppendState <biped_ctrl>.fsCreateState Boolean Boolean Default: False Default: False

Each new footstep is appended to the end of the bipeds footstep sequence. Set to true to create new states. The first state you add is, by default, the first state in the controller that executes when the simulation is run.
<biped_ctrl>.fsGroundDuration <biped_ctrl>.fsAirDuration Time Time Default: 18f Default: 3f

Specifies the number of frames when the body will be in the air during a run or a jump. Note: If fsGaitMode is #walk, the above 2 parameters are the Walk Footstep and Double Support durations, respectively. If fsGaitMode is #run, the above 2 parameters are the Run Footstep and Airborne durations, respectively. If fsGaitMode is #jump, the above 2 parameters are the 2-Feet down and Airborne durations, respectively.
<biped_ctrl>.fsGaitMode Name Default: #walk

fsGaitMode can be set to any of the three gaits: #walk, #run, #jump

-- Motion Flow properties

<biped_ctrl>.motionFlow MoFlow

Returns an instance of MoFlow. See Biped Motion Flow (p. 1752) section for more details. -- Motion Capture properties
<biped_ctrl>.displayBuffer <biped_ctrl>.displayBufferTraj Boolean Boolean Default: False Default: False

A red stick figure appears, representing the raw motion capture data. Display a trajectory based on the buffered raw motion capture data for any biped body part. Use this in combination with Show/Hide Trajectories on the Display rollout to see how closely the raw and filtered data match.
<biped_ctrl>.talentFigMode Boolean Default: False

Turn on Talent Figure mode to scale the biped relative to the markers. Calibration for the entire marker file takes place when you exit Talent Figure mode. Keyframe adaptation takes place in order to accommodate the new biped scale; because of this, you should adjust the biped scale before adjusting the biped position relative to the markers. Use Rubber Band Mode on the General rollout and Non-Uniform Scale to size the biped in Talent Figure mode. Ideally, you will not need to use this feature. When loading a motion capture file, Biped attempts to extract the appropriate figure scale from the given data. Use Talent Figure mode only if the extracted scale of the biped doesnt match the scale of the original talent. Minor differences in scale will alter the motion.

Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller

1743

Note: Calibration controls are only enabled when a marker or .bvh file is imported in its raw form. Do not use key reduction or extract footsteps when you import a marker file for the first time. -- Object Space Object
<biped_ctrl>.osObject Node Default: Undefined

The Object Space Object for the currently selected body part. The osObject can be specified for the Clavicle or any of its decendents, and the Thigh or any of its decendents. The osObject is undefined for all other body parts. The osObject is normally specified in the IK Key Info rollout. -- SubAnim Properties (as seen in Track View)
<biped_ctrl>.vertical Matrix3 Matrix3 Matrix3 Point3 -- Animatable -- Animatable -- Animatable -- Animatable

The vertical track of controller

<biped_ctrl>.horizontal

The horizontal track of controller

<biped_ctrl>.turning

The turning track of controller

<biped_ctrl>.Ease_Curve Animated over range 0 to 1

Script Example:
bipObj = biped.createNew 100 100 [0,0,0] select bipObj bip = bipObj.transform.controller -- Display properties bip.displayBones = true bip.displayObjects = false bip.displayFootsteps = false bip.displayFSNumbers = false -- Animations properties bip.gravAccel = 700 bip.dynamicsType = 1

See Also
Biped Creation (p. 1727)

1744

Chapter 21

character studio 3 MAXScript Extensions

FootSteps : Matrix3 Controller

Constructor:
<footsteps_ctrl> = $Bip01 Footsteps.transform.controller

or:
<footsteps_ctrl>=$Bip01 Footsteps.controller

Notes: This controller is attached to the transform track of the named Biped footstep object. Properties:
<footsteps_ctrl>.freeFormMode Boolean false - Edit Footsteps true - Edit Free Form (no physics) <footsteps_ctrl>.dispNumType 0 - Start and End Frame 1 - Start Frame 2 - Duration 3 - Double Support <footsteps_ctrl>.dispAirDur Integer Default: False

Default: 0

Boolean

Default: False

Displays the foot air duration. This is the number of frames each foot is in the air in the lower part of each footsteps portion of the track.
<footsteps_ctrl>.dispNoSupport Boolean Default: False

Displays the number of frames when both feet are off the ground, directly above the areas without footsteps.
<footsteps_ctrl>.rootName String Default: Varies

Contains the root name of the Biped using the Foootsteps Controller. Changing the value of this property also changes the root name of the Biped.
<footsteps_ctrl>.rootNode Node Default: Varies -- Read-only

The root node (COM) of the Biped system this footstep_ctrl belongs to. The following example will access the footstep controller, set several values and then display all of its properties. Script Example:
fsCont = $Bip01 Footsteps.transform.controller fsCont.freeFormMode = true fsCont.dispNumType = 3 fsCont.dispAirDur = false fsCont.dispNoSupport = false showProperties fsCont

Biped Slave Controller

1745

See Also
Biped Footprints (p. 1745) Biped Keys (p. 1759)

Biped Slave Controller

Individual Biped body part objects and the Vertical, Horizontal, and Turning tracks of the Biped_Vertical_Horizontal_Turn_Body_Matrix3_Controller (p. 1736) use the Biped_Slave ControllerBiped_Slave_Controller. This type of controller is attached to the transform track.
<bipslave_ctrl>=$Bip01 Pelvis.controller

It is not always possible to get the controller via <biped_object>.transform.controller. The transform track is not exposed for all nodes but it is possible to get the controller via: <biped_object>.controller. Properties:
<bipslave_ctrl>.rootName String Default: Varies

The name of the root node (COM) of the Biped system this bipslave_ctrl belongs to. Note: changing the value of this property also changes the root name of the biped.
<bipslave_ctrl>.rootNode Node Default: Varies -- Read-only

The root node (COM) of the Biped system this bipslave_ctrl belongs to.

See also
Biped MAXScript Extensions (p. 1725)

Biped Footsteps and Footprints

This topic will cover the Bipeds footsteps controller, individual footprints, the multiple footstep creation dialog, as well as obtaining and setting the parameters for multiple footsteps. Biped Footsteps (p. 1744) Biped Footprints (p. 1745)

Biped Footprints
Methods:
biped.addFootprint <biped_ctrl> <matrix3> [append:<boolean>]

Specifies the position and rotation of the footstep. The scale portion of the matrix3 should always be the identity matrix ([1,1,1]). Creates a single footprint for the biped, where matrix3 specifies the position and rotation of the footstep. The scale portion of the matrix3 should always by unity ([1,1,1]). Notes: Creates a single footprint for the Biped.

1746

Chapter 21

character studio 3 MAXScript Extensions

Global Properties:
biped.fsAddSide 0 - Start Right 1 - Start Left Integer Default:0

Notes: For multiple footstep creation, the starting foot needs to be identified. There is a UI radio button in the Multiple Footstep Creation dialog Start Right/Start Left. The biped global property, fsAddSide, exposes access to this UI element. This property also effects the start foot when manually creating footsteps in the viewports and when using biped.addFootprint. If the biped.fsAddSide is 1, a left footstep is created. If 0, a right footstep is created. When you create a footstep in the viewports or by using biped.addFootprint, the value of biped.fsAddSide is flipped, resulting in alternating footsteps being created by default. Methods:
biped.multipleFSDlg <biped_ctrl>

Displays the Multiple Footstep Creation dialog

biped.getMultipleFSParams <gait_type_name>

Returns an instance of MultFprintParams, gait_type_name can be #walk, #run or #jump. For information on MultFprintParams and gait_type_name see Biped MultFprintParams ClassBiped_MultFprintParams_Class. The following example will obtain the MultipleFSParams for a walk cycle, set several of its values and then show all of the properties. Script Example:
walk = biped.getMultipleFSParams #walk walk.numFootsteps = 5 walk.actualStrideWidth = 2.5 walk.paramStrideWidth = 2.5 walk.actualStrideLength1 = .6 walk.paramStrideLength1 = .6 walk.actualStrideHeight1 = .6 walk.cycle1 = 6 walk.actualStrideLength2 = .7 walk.paramStrideLength2 = .7 walk.actualStrideHeight2 = .7 walk.cycle2 = 7 walk.autoTiming = true walk.interpTiming = true walk.alternate = true walk.multiInsertInTime = true showProperties walk

Biped Footprints

1747

Method:
biped.addMultipleFootprints <biped_ctrl> <MultFprintParams>

Create footsteps for a Biped based on the MultFprintParams value

biped.newFootprintKeys <biped_ctrl>

Activates all inactive footsteps. Activation creates default keys for any footsteps that do not have them. If a footstep does not have keys, it is displayed as bright green (right foot) or bright blue (left foot). After keys are created for the footsteps, the footsteps change color to pastel green and pastel blue. Create Biped keys for inactive footsteps on the Biped The following example will create a biped, create 10 footsteps and then have Biped create default keys for the footsteps. Script Example:
-- create a Biped bipObj = biped.createNew 100 100 [0,0,0] -- get the transform controller for the Biped bip = bipObj.transform.controller -- get the multiple footstep parameters interface mfsp=biped.getMultipleFSParams #walk -- set the number of footsteps to 10 mfsp.numFootsteps=10 -- create the inactive footsteps biped.addMultipleFootprints bip mfsp -- create the Biped keys for inactive footsteps biped.newFootprintKeys bip

See Also
Biped Controllers (p. 1735) Biped MultFprintParams Class (p. 1748) Biped MaxScript Extensions (p. 1725) Biped Keys (p. 1759)

1748

Chapter 21

character studio 3 MAXScript Extensions

Biped Class : MultFprintParams

This class represents multiple footstep creation parameters of a Biped. An instance of this class is returned by the biped.getMultipleFSParams <gait_type_name> method, where gait_type_name can be #walk, #run or #jump. Properties: #walk
<MultFprintParams>.alternate Boolean Default:

#run
true true

#jump
true

Footsteps will alternate between right and left. Alternate is always selected when the Walk gait is selected. You can only clear Alternate when Run or Jump gaits are selected.
<MultFprintParams>.numFootsteps <MultFprintParams>.paramStrideWidth Integer Float Default: Default: 4 1.0 4 4 1.0 1.0

Determines the number of new footsteps to be created. Sets the stride width as a percentage of the pelvis width. A value of 1.0 produces a stride width equal to the pelvis width. A value of 3.0 produces a wide, waddling stride. Changes to this setting automatically change the Actual Stride Width. Parametric describes the parameter in terms of biped anatomy, and Actual describes the value in 3ds max units.
<MultFprintParams>.actualStrideWidth Float Default: 0.0 0.0 0.0

Sets the stride width in modeling units. Changes to this setting automatically change the Parametric Stride Width.
<MultFprintParams>.autoTiming Boolean Default: true true true

Sets timing parameters automatically. Auto Timing affects the following timing parameters for the Walk gait: Walk footstep, Double Support: When Auto Timing is selected, these parameters are automatically adjusted to reasonable values. Control the footstep sequence by adjusting the Stride Length and Time to Next Footstep parameters. When Auto Timing is cleared, you can control the footstep sequence by adjusting the gait timing parameters, but you cant change the Time to Next Footstep parameter.
<MultFprintParams>.interpTiming <MultFprintParams>.multiInsertInTime false - Start after last footstep true - Start at current frame Boolean Boolean Default: Default: false false false false false false

Control acceleration or deceleration of the series of footsteps.

Appends the newly created footsteps to the end of the existing footstep sequence. Inserts the newly created footsteps at the current frame after the existing footstep sequence allowing you to make a gap in time before the footsteps start again.
<MultFprintParams>.actualStrideLength1 Float Default: 0.0 0.0 0.0

Sets the stride length for new footsteps in 3ds max units.

Biped Class : MultFprintParams

1749

<MultFprintParams>.paramStrideLength1

Float

Default:

0.75

1.5

2.4

Sets the stride length for the new footsteps as a percentage of the length of the bipeds leg. The default value of 0.75 gives an average stride of normal proportions. A value of 1.0 will produce a stride length equal to the leg length, which makes the biped stretch slightly to reach the next step. A value of 0.0 will make the biped walk in place. A negative stride length will make the biped walk backwards. When a biped walks backwards, it does not simply reverse the forward movement but maintains the correct foot-state sequence with the toe touching the ground first, followed by the heel. Adjusting Parametric Stride Length automatically changes the value for Actual Stride Length.
<MultFprintParams>.actualStrideHeight1 Float Default: 0.0 0.0 0.0

Sets the rise or fall between footsteps. You can use this parameter to create a set of footsteps going up or down a slope or a stairway. The value for Actual Stride Height is the difference in height in units between each of the new footsteps. Positive values step up and negative values step down.
<MultFprintParams>.cycle1 Time <MultFprintParams>.actualStrideLength2 Float Default: Default: 15f 0.0 15f 0.0 15f 0.0

Sets the stride length for new footsteps in 3ds max units. The same rules apply as for Parametric Stride Length. Adjusting Actual Stride Length automatically changes the value for Parametric Stride Length.
<MultFprintParams>.paramStrideLength2 Float Default: 0.75 1.5 2.4

Sets the stride length for the new footsteps as a percentage of the length of the bipeds leg. The default value of 0.75 gives an average stride of normal proportions. A value of 1.0 will produce a stride length equal to the leg length, which makes the biped stretch slightly to reach the next step. A value of 0.0 will make the biped walk in place. A negative stride length will make the biped walk backwards. When a biped walks backwards, it does not simply reverse the forward movement but maintains the correct foot-state sequence with the toe touching the ground first, followed by the heel. Adjusting Parametric Stride Length automatically changes the value for Actual Stride Length.
<MultFprintParams>.actualStrideHeight2 Float Default: 0.0 0.0 0.0

Sets the rise or fall between footsteps. You can use this parameter to create a set of footsteps going up or down a slope or a stairway. The value for Actual Stride Height is the difference in height in units between each of the new footsteps. Positive values step up and negative values step down.
<MultFprintParams>.cycle2 Time Default: 15f 15f 15f

See the biped.addMultipleFootprints method for creating footsteps based on a MultFprintParams, and biped.newFootprintKeys creating the biped keys for the inactive footsteps.

1750

Chapter 21

character studio 3 MAXScript Extensions

Since MultFprintParams is biped independent, the actual stride lengths and heights are not accessible in this class. To convert from a paramStrideWidth value to an actualStrideWidth value, multiply the paramStrideWidth value by the width of the pelvis. Given a biped_ctrl, the pelvis width can be calculated by:
thePelvis = biped.getNode biped_ctrl #pelvis pelvisWidth = in coordsys thePelvis (thePelvis.max- thePelvis.min).z

To convert from a paramStrideLength value to an actualStrideLength value, multiply the paramStrideLength value by the length of the right leg. Given a biped_ctrl, the length of the right leg can be calculated by:
legLength = distance (biped.getNode biped_ctrl #rleg link:1) (biped.getNode biped_ctrl #rleg link:2) -- thigh legLength += distance (biped.getNode biped_ctrl #rleg link:2) (biped.getNode biped_ctrl #rleg link:3) -- calf if ((biped_ctrl.rootnode).controller.leglinks) > 3 do legLength += distance (biped.getNode biped_ctrl #rleg link:3) (biped.getNode biped_ctrl #rleg link:4) horsellink, if present

See Also
Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller (p. 1736) Biped Slave Controller (p. 1745) FootSteps : Matrix3 Controller (p. 1744) Biped Footsteps (p. 1745) Biped MAXScript Extensions (p. 1725)

FootSteps : Matrix3 Controller

Constructor:
<footsteps_ctrl> = $Bip01 Footsteps.transform.controller

or:
<footsteps_ctrl>=$Bip01 Footsteps.controller

Notes: This controller is attached to the transform track of the named Biped footstep object. Properties:
<footsteps_ctrl>.freeFormMode Boolean false - Edit Footsteps true - Edit Free Form (no physics) Default: False

BipedFSKey : MAXObject

1751

<footsteps_ctrl>.dispNumType 0 - Start and End Frame 1 - Start Frame 2 - Duration 3 - Double Support <footsteps_ctrl>.dispAirDur

Integer

Default: 0

Boolean

Default: False

Displays the foot air duration. This is the number of frames each foot is in the air in the lower part of each footsteps portion of the track.
<footsteps_ctrl>.dispNoSupport Boolean Default: False

Displays the number of frames when both feet are off the ground, directly above the areas without footsteps.
<footsteps_ctrl>.rootName String Default: Varies

Contains the root name of the Biped using the Foootsteps Controller. Changing the value of this property also changes the root name of the Biped.
<footsteps_ctrl>.rootNode Node Default: Varies -- Read-only

The root node (COM) of the Biped system this footstep_ctrl belongs to. The following example will access the footstep controller, set several values and then display all of its properties. Script Example:
fsCont = $Bip01 Footsteps.transform.controller fsCont.freeFormMode = true fsCont.dispNumType = 3 fsCont.dispAirDur = false fsCont.dispNoSupport = false showProperties fsCont

See Also
Biped Footprints (p. 1745) Biped Keys (p. 1759)

BipedFSKey : MAXObject
This class represents a Biped footstep in the viewports and trackview. Properties:
<fskey>.time <fskey>.duration Time Time Default: Varies Default: Varies

A value indicating when in time the key occurs. The number of frames in each footstep.

1752

Chapter 21

character studio 3 MAXScript Extensions

<fskey>.selected <fskey>.edgeSel 0 - no edges selected 1 - left edge Selected 2 - right edge selected 3 - both edges Selected <fskey>.active

Boolean Integer

Default: False Default: 0

Boolean Matrix3 Name

Default: True Default: Varies Default: #left or #right

Activate or make inactive the footstep.

<fskey>.transform <fskey>.side Read-only --

See Also
Biped Controllers (p. 1735) Biped Footsteps (p. 1745) Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller (p. 1736) Biped Keys (p. 1759) Biped MAXScript Extensions (p. 1725)

Biped Motion Flow

MoFlow : MaxWrapper (p. 1752) MoFlowScript : MaxWrapper (p. 1754) MoFlowSnippet : MaxWrapper (p. 1755) MoFlowTranInfo : MaxWrapper (p. 1756) MoFlowTransition : MaxWrapper (p. 1758)

MoFlow : MaxWrapper
This class can be used to access features in the Biped Motion Flow panel. An instance of this class is returned by the .motionFlow property of a Biped Body Controller (p. 1736). Properties:
<moflow>.scripts -- Read-only Array Default: #()

An array of motion flow scripts (MoFlowScript values). A Script is a list of clips (.bip files) that are executed sequentially to animate a character.
<moflow>.activeScript MoFlowScript Default:undefined

Get/set which MoFlowScript in scripts array is the active script. If the specified MoFlowScript is not in the scripts array, no action occurs.

MoFlow : MaxWrapper

1753

<moflow>.snippets -- Read-only <moflow>.selSnippets <moflow>.startFrame -- Read-only <moflow>.endFrame -- Read-only

Array

Default: #()

An array of motion flow snippets (MoFlowSnippet values).

BitArray Integer Default: #{} Default: 0

A bitarray specifying the motion flow snippets that are selected in the Motion Flow Graph.

The start frame of currently active motion flow script.

Integer Default: 0

The last frame of currectly active motion flow script. Methods:

loadMoFlowFile <moflow> <file_name> [ quiet:<boolean> ] If quiet:true, which is the default, any warning message dialogs are suppressed.

Load a Motion Flow Editor file (.mfe). Motion Flow Editor files include: Clips: references to biped animation files. Transitions: The names, attributes, and connections between clips. Scripts: different paths through a set of connected clips and transitions.
saveMoFlowFile <moflow> <file_name>

Save a Motion Flow Editor file (.mfe). Load/Save a motion flow (.MFE) file. Note: The location of the referenced .bip files is saved in the .mfe file. If the .bip file cannot be found, the program looks to the motion flow directory specified in \plugcfg\biped.ini. By default, this setting is MoFlowDir=<maxdir>\cstudio\scripts If a referenced .bip file cannot be found in its current location, you will need to move it to the specified Motion Flow directory. You can change the location of this directory at any time by editing your biped.ini file with a text editor. The new directory will be used the next time you restart 3ds max. You can also add multiple search paths to your biped.ini file by repeating the MoFloDir= line multiple times. The program will search the directories in the order they appear and will use the first instance of the file that it finds.
loadSnippetFiles <moflow>

Loads the snippet files whose file names are assigned. This function should be called whenever new snippets are added. Clips represent all or part of a .bip file.
addScript <moflow> <name>

Scripts represent different paths through the clips in the Motion Flow Graph. Creates a new motion flow script with the given name and adds it to the motion flow. Returns the new MoFlowScript.

1754

Chapter 21

character studio 3 MAXScript Extensions

deleteScript <moflow> <MoFlowScript> deleteScript <moflow> <index_integer>

Deletes the specified script. If the second argument is an integer, the script deleted is the indexed script in the motion flows .scripts array.
getScriptIndex <moflow> <MoFlowScript>

Given the script, returns its index in the scripts combobox.

getSnippetIndex <moflow> <MoFlowSnippet>

Given the snippet, returns its index in the in the motion flows .snippets array.
computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]

Computes the global flow network. This function has to be called to update any changes made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true will also include the global motion flow network. Related Methods:
newSnippet <filename> <point2_pos> <redraw:true> <load:true>

Adds a new MoFlowSnippet to the motion flow network, from the given .bip file. <point2_pos> is the position in windows coordinates where the origin is the top left of the snippet in the motion flow graph. Redraw:true will redraw the graph window. Load:true will immediately load the snippet

See also
Biped Controllers (p. 1735) MoFlowScript : MaxWrapper (p. 1754) MoFlowSnippet : MaxWrapper (p. 1755) Biped MAXScript Extensions (p. 1725)

MoFlowScript : MaxWrapper
Constructor:
addScript <moflow> <script_name>

Create a new motion flow script with the given name to the motion flow. Returns the new MoFlowScript. Properties:
<MoFlowScript>.startFrame <MoFlowScript>.snippets <MoFlowScript>.name <MoFlowScript>.startPos <MoFlowScript>.startRot Integer Array String Point3 Float Default: 0f Default: #() Default: Varies Default: [0,0,0] Default: 0 -- Read-only

Array of MoFlowSnippet values defined in the motion flow script

MoFlowScript : MaxWrapper

1755

Methods:
addSnippet < MoFlowScript > < MoFlowSnippet >

Adds the specified MoFlowSnippet to a motion flow script. Returns the MoFlowSnippet value.
insertSnippet < MoFlowScript > < MoFlowSnippet > <index_integer>

Inserts the snippet at the location specified and returns the new script item. Returns the MoFlowSnippet value.
deleteSnippet < MoFlowScript > <index_integer>

Deletes the indexed MoFlowSnippet from the motion flow script. Related Methods:
deleteScript <moflow> <index_integer>

Deletes the indexed MoFlowScript from the motion flow.

computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]

Computes the global flow network. This function has to be called to update any changes made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true will also include the global motion flow network NotesC: Changes to the MoFlowScript property values do not cause an immediate update of the biped. ComputeAnimation must be called on the MoFlow value to recompute the biped motion. Constructor:
newSnippet <moflow> <filename> <point2_pos> <redraw:true> <load:true>

Adds a new MoFlowSnippet to the motion flow network, from the given .bip file. <point2_pos> is the position in windows coordinates where the origin is the top left of the snippet in the motion flow graph. Redraw :true will redraw the graph window. Load:true will immediately load the snippet. Returns the new MoFlowSnippet. Properties:
<MoFlowSnippet>.start Integer Integer String String Point2 Boolean Array Default: 0 Default: Varies Default: Varies Default: Varies Default: Varies Default: True Default: #(MoFlowTransition :

The start frame in the snippet file.

<MoFlowSnippet>.end

The end frame in the snippet file.

<MoFlowSnippet>.clipName <MoFlowSnippet>.fileName <MoFlowSnippet>.pos <MoFlowSnippet>.active <MoFlowSnippet>.transitions [X,X]) read only

The coordinates of the snippet in the Motion Flow Graph.

An array of the transitions defined for the snippet (MoFlowTransition values). The MoFlowTransition values printed show the the from and to MoFlowSnippet names.
<MoFlowSnippet>.randomStartProbability Integer Default: 100

1756

Chapter 21

character studio 3 MAXScript Extensions

Methods:
addTransition <from_MoFlowSnippet > <to_MoFlowSnippet > <bool_optimize>

Adds a new MoFlowTransition to a motion flow Snippet. The optimize parameter acts as the Optimize Selected Transition in the Motion Flow Editor.
deleteTransition < MoFlowSnippet > <index_integer>

Deletes the indexed MoFlowTransition emanating from the MoFlowSnippet.

deleteTransitionTo <from_MoFlowSnippet > <to_MoFlowSnippet >

Deletes the transition thats emanating to the specified snippet. Related Methods:
addSnippet < MoFlowScript > < MoFlowSnippet >

Adds the specified MoFlowSnippet to a motion flow script. Returns the MoFlowSnippet value.
insertSnippet < MoFlowScript > < MoFlowSnippet > <index_integer>

Inserts a snippet at the location specified and returns the new script item. Returns the MoFlowSnippet value.
deleteSnippet < MoFlowScript > <index_integer>

Deletes the indexed MoFlowSnippet from the motion flow script.

loadSnippetFiles <moflow>

Loads all of the snippet files whose file names are assigned. This function should be called whenever new snippets are added.
getSnippetIndex <moflow> <MoFlowSnippet>

Given the snippet, returns its index in the motion flows .snippets array.
computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]

Computes the global flow network. This function has to be called to update any changes made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true will also include the global motion flow network Notes: Changes to the MoFlowSnippet property values do not cause an immediate update of the biped. ComputeAnimation must be called on the MoFlow value to recompute the biped motion.

MoFlowTranInfo : MaxWrapper
Constructor:
addTranInfo < MoFlowTransition >

Adds a new MoFlowTranInfo to the MoFlowTransition and returns the newly created MoFlowTranInfo. Properties:
<MoFlowTranInfo>.length Integer Float Default: 25 Default: 0.0

The transition length in frames.

<MoFlowTranInfo>.angle

The direction of the destination clip

MoFlowTranInfo : MaxWrapper

1757

<MoFlowTranInfo>.easeFrom <MoFlowTranInfo>.easeTo <MoFlowTranInfo>.sourceStart

Float Float Integer Integer Boolean

Default: 0.5 Default: 0.5 Default: Varies Default: Varies Default: True

The start frame for the source clip

<MoFlowTranInfo>.destStart

The start frame for the destination clip

<MoFlowTranInfo>.sourceState

false - Fixed true - Rolling

<MoFlowTranInfo>.destState Boolean Default: True

false Fixed true Rolling

<MoFlowTranInfo>.length Integer String Integer Default: 25 Default: Default: 100

The transition length in frames.

<MoFlowTranInfo>.note <MoFlowTranInfo>.probability

Related Methods:
deleteTranInfo < MoFlowTransition > <index_integer>

Deletes the indexed MoFlowTranInfo from the MoFlowTransition. . If the MoFlowTranInfo is the only MoFlowTranInfo in MoFlowTransition, it is not deleted.
computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]

Computes the global flow network. This function has to be called to update any changes made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true will also include the global motion flow network Notes: Changes to the MoFlowTranInfo property values do not cause an immediate update of the biped. ComputeAnimation must be called on the MoFlow value to recompute the biped motion. The following example will find the transition information from the first clip (snippet) to the next in the first script defined for the Biped motion flow. Script Example:
CSPATH = f:\\3dsmax31_86\\cstudio\\ bipObj = biped.createNew 100 100 [0,0,0] select bipObj max motion mode bip = bipObj.transform.controller -- get the MoFlow value from the biped controller: mf=bip.motionFlow -- go into motion flow mode and load a motion flow file bip.motionmode=true loadMoFlowFile mf (CSPATH + scripts\\4floloop.mfe) --- get the script of interest from the MoFlow: mfs=mf.scripts[1]

1758

Chapter 21

character studio 3 MAXScript Extensions

-- the script items from the script are in mfs.scriptItems. -- get the snippet (snippet_from) from the first script item: snippet_from=mfs.snippets[1].snippet -- get the snippet (snippet_to) from the second script item: snippet_to=mfs.snippets[2].snippet -- search the transitions in snippet_from to find -- the one whose toSnippet property == snippet_to: theTrans=undefined for trans in snippet_from.transitions where (trans.toSnippet == snippet_to) do ( theTrans=trans break ) --get the transition information for the from script item: theTransInfo=theTrans.tranInfos

See also
Biped MAXScript Extensions (p. 1725)

MoFlowTransition : MaxWrapper
Constructor:
addTransition <from_MoFlowSnippet > <to_MoFlowSnippet > <bool_optimize>

Adds a new MoFlowTransition from the from_MoFlowSnippet to the to_MoFlowSnippet if one doesnt already exist. The optimize parameter acts as the Optimize Selected Transition in the Motion Flow Editor. Properties:
<MoFlowTransition>.fromSnippet <MoFlowTransition>.toSnippet <MoFlowTransition>.active <MoFlowTransition>.selected <MoFlowTransition>.tranInfos -- Read-only MoFlowSnippet Default: Varies MoFlowSnippet Default: Varies Boolean Boolean Array Default: True -- Read-only Default: False Default: #(MoFlowTranInfo :[X,X])

Specifies the MoFlowSnippet transitioning from. Specifies the MoFlowSnippet transitioning to. Specifies whether the MoFlowTransition is active. Specifies whether the MoFlowTransition line is selected in the Motion Flow Graph.

Array of motion flow transition info blocks (MoFlowTranInfo values). The element of this array used is determined by the <mfscriptItem>.tranIndex property. Methods:
addTranInfo < MoFlowTransition >

Adds a new MoFlowTranInfo to the MoFlowTransition and returns the newly created MoFlowTranInfo.

MoFlowTransition : MaxWrapper

1759

deleteTranInfo < MoFlowTransition > <index_integer>

Deletes the indexed MoFlowTranInfo from MoFlowTransition. If the MoFlowTranInfo is the only MoFlowTranInfo in MoFlowTransition, it is not deleted. Related Methods:
deleteTransition < MoFlowSnippet > <index_integer>

Deletes the indexed MoFlowTransition emanating from the MoFlowSnippet.

deleteTransitionTo <from_MoFlowSnippet > <to_MoFlowSnippet >

Deletes the transition thats emanating to the specified snippet.

computeAnimation <moflow> [redraw:<true>] [incGlobals:<false>]

Computes the global flow network. This function has to be called to update any changes made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true will also include the global motion flow network Notes: Changes to the MoFlowTransition property values do not cause an immediate update of the biped. ComputeAnimation must be called on the MoFlow value to recompute the biped motion.

See also
Biped MAXScript Extensions (p. 1725)

Biped Keys
All common MAXScript key functions like deleteKey, selectKeys, moveKeys etc. can be used with Biped keys. The exceptions addNewKey and deleteKeys are substituted with the following methods. Method:
biped.addNewKey <biped_controller> <time> [ #select ] <time> Adds a new key to the controller track at the time specified. [ #select ] The new key is also selected if the #select optional argument is specified.

The value for the new key is the interpolated controller value at the specified time. The value for the new key is the interpolated controller value at that time. The new key is also selected if the #select optional argument is specified. addNewKey() will not add a key if a key already exists at the specified time. The return value is the key located at the specified time. Method:
biped.deleteKeys <biped_controller> [ #allKeys ] [ #selection ] [ #allKeys ] [ #selection ]

Deletes either all keys or all selected keys from the controller. If neither #allKeys or #selection is specified, all keys are deleted.

1760

Chapter 21

character studio 3 MAXScript Extensions

Accessing a Biped controller key by index

Accessing a Biped controller key by indexing into the .keys property of the controller returns a type of key that MAXScript does not recognize. To get a Biped controller key by index use the following method: Method:
biped.getKey ( <biped_controller> | <footstep_ctrl> ) <index> <biped_controller> <footstep_ctrl> <index>

Notes: Returns an instance of BipedKey for Biped body controllers and BipedFSKey for footstep controllers. BipedKey and BipedFSKey are defined below. Not all of the Biped elements contain a transform controller. Rather, a controller on an object typically higher in the hierarchy may store the transform key for an element. For example, the transforms for all the fingers on a hand are stored in either the Finger0 or Clavicle transform controller. This depends on whether Separate Tracks for Arms is set to true or false, respectively. The following example will get the first key for each of the subcontrollers of the $Bip01 Vertical_Horizontail_Turn transform controller and show their properties. Additionally, the first key of the $Bip01 Footstep transform controller will have its properties shown. Script Example:
bip = $Bip01.transform.controller -- Obtain the subcontrollers vertCont = bip.vertical.controller horzCont = bip.horizontal.controller turnCont = bip.turning.controller -- Get the first key for each subcontroller vk = biped.getKey vertCont 1 hk = biped.getKey horzCont 1 tk = biped.getKey turnCont 1 -- Show the properties for the individual subcontroller key types showProperties vk showProperties hk showProperties tk -- Obtain the Bipeds Footstep controller fsCont = $Bip01 Footsteps.transform.controller -- Show the Footstep controller properties showProperties fsCont -- Get the first Footstep controller key fk = biped.getkey fsCont 1 showProperties fk

See also
BipedKey : MAXObject (p. 1761)

BipedKey : MAXObject

1761

BipedKey : MAXObject
All Biped vertical, horizontal, turning, and body keys are represented by this class. Properties:
<bipedkey>.time <bipedkey>.selected <bipedkey>.tension Time Boolean Float Default: Varies Default: False Default: 25.0

Enter a value to specify when in time the key occurs.

Controls the amount of curvature in the animation curve. High Tension produces a linear curve. It also has a slight Ease To and Ease From effect. Low Tension produces a very wide, rounded, curve. It also has a slight negative Ease To and Ease From effect.
<bipedkey>.continuity Float Default: 25.0

Controls the tangential property of the curve at the key. The default setting is the only value that produces a smooth animation curve through the key. All other values produce a discontinuity in the animation curve causing an abrupt change in the animation.
<bipedkey>.bias <bipedkey>.easeTo Float Float Default: 25.0 Default: 0.0

Controls where the animation curve occurs with respect to the key. Slows the velocity of the animation curve as it approaches the key. High Ease To causes the animation to decelerate as it approaches the key. The default setting causes no extra deceleration.
<bipedkey>.easeFrom Float Default: 0.0

Slows the velocity of the animation curve as it leaves the key. High Ease From causes the animation to start slow and accelerate as it leaves the key. The default setting causes no change of the animation curve.
<bipedkey>.type Name Default: Varies -- Read-only Contains #vertical, #horizontal, #turning, or #body based on the key type

There are additional properties based on the type of the key:

-- #vertical <vertkey>.z Float Float Default: Varies Default: 1.0

Reposition the selected biped part in z.

<vertkey>.dynamicsBlend

Control the amount of gravity in an airborne period, as in a running or jumping motion. This parameter has no effect on a walking motion where footsteps overlap.
<vertkey>.ballisticTension Float Default: 0.5

Control the amount of spring or tension when the biped lands or takes off from a jump or run step. The change is subtle. A walk cycle will not activate this value. The biped has to be airborne, then the Lift and Touch vertical keys will display a Ballistic Tension value.

1762

Chapter 21

character studio 3 MAXScript Extensions

-- #horizontal <horzkey>.x

Float Float Float

Default: Varies Default: Varies Default: 1.0

Reposition the selected biped part in x.

<horzkey>.y

Reposition the selected biped part in y.

<horzkey>.balanceFactor

Position the bipeds weight anywhere along a line that extends from the center of mass to the bipeds head. A value of 0 places the bipeds weight at the center of mass. A value of 1 places the bipeds weight above the center of mass. A value of 2 places the bipeds weight in the head.
-- #body <bodykey>.ikBlend Float Default: 0.0

Determines how forward kinematics and inverse kinematics are blended to interpolate an intermediate position.
<bodykey>.ikSpace 0 - Body 1 - Object Integer Default: 0

The biped limb is in biped coordinate space. The biped limb is either in World coordinate space or the coordinate space of the selected object. Coordinate space can be blended between keys.
<bodykey>.ikAnkleTension Float Default: 0.0

Adjusts the precedence of the ankle joint over the knee joint. When set to 0, the knee takes precedence. When set to 1, the ankle takes precedence.
<bodykey>.ikJoinedPivot <bodykey>.ikPivotIndex <bodykey>.ikNumPivots <bodykey>.ikPivots Boolean Integer Integer Array Default: True Default: 1

Put the biped foot in the coordinate space of the previous key. Index into <bodykey>.ikPivots array of active (selected) pivot
Default: Varies Read only Deafult: Varies - Array of Point3 values

Number of pivot points in <bodykey>.ikPivots array Array of positions of all the pivot points for the body part Here is an example: Script Example:
k = biped.getKey $bip01 L clavicle.transform.controller 2 showProperties k k.ikBlend = .5 k.ikSpace = 0 k.ikAnkleTension = .8 k.ikJoinedPivot = false k.ikPivotIndex = 8 k.ikNumPivots = 2 k.ikPivots -- to add a new one k = biped.addNewKey $bip01 L clavicle.transform.controller 10f

BipedFSKey : MAXObject

1763

BipedFSKey : MAXObject
This class represents a Biped footstep in the viewports and trackview. Properties:
<fskey>.time <fskey>.duration Time Time Boolean Integer Default: Varies Default: Varies Default: False Default: 0

A value indicating when in time the key occurs. The number of frames in each footstep.
<fskey>.selected <fskey>.edgeSel 0 - no edges selected 1 - left edge Selected 2 - right edge selected 3 - both edges Selected <fskey>.active

Boolean Matrix3 Name

Default: True Default: Varies Default: #left or #right

Activate or make inactive the footstep.

<fskey>.transform <fskey>.side Read-only --

See Also
Biped Controllers (p. 1735) Biped Footsteps (p. 1745) Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller (p. 1736) Biped Keys (p. 1759) Biped MAXScript Extensions (p. 1725)

Biped Motion Capture

All motion capture properties in Biped are global parameters and cannot be varied from Biped to Biped. Hence they are exposed as system globals residing in the mocap struct. Properties:
mocap.fsExtractionMode 0 - None: Freeform Integer Default: 0

No footsteps are extracted.

1 - On

Extract footsteps.
2 - Fit to existing

For motion data that has both footstep motion and flying, swimming, falling, or tumbling motions.

1764

Chapter 21

character studio 3 MAXScript Extensions

mocap.fsConversionMode 0 - No Key Reduction

Integer

Default: 0

Do not reduce keys. Use this on files that are already key reduced or if you want to work with all the data in a raw motion capture file.
1 - Use Key Reduction

Reduce keys for simpler key editing.

2 - Load Buffer Only

Do not apply the data to the biped, load the data to the motion capture buffer only. Use this to either compare your edited version with the original or to paste postures from the motion capture buffer to the biped in the scene.
mocap.upVector 0 - X 1 - Y 2 - Z mocap.scaleFactor -- range: 1+ Float Default: 1.0 Integer Default: 2

Set the vertical axis used in the motion capture data.

Multiply the stored talent size by this value and size the biped accordingly.

-- Footstep Extraction
mocap.fsExtractionTol Float Default: 0.05

Set the sensitivity of footstep extraction. Biped determines if the footstep is there by checking that the foot does not move beyond the distance determined by the Extraction Tolerance value. Smaller numbers are more sensitive and extract more footsteps. Value is a percentage of foot length.
-- range: 0+ mocap.fsSlidingDist Float Default: 0.0

Create a sliding footstep when positional tolerance is reached. This value is a percentage of foot length. By default the foot must slide its own distance (100), before a sliding footstep is created.
-- range: 0+ mocap.fsSlidingAngle Float Default: 0.0

Create a sliding footstep when rotational tolerance is reached. This value is in degrees. If this is set high (360 degrees), the foot must make a complete turn before a sliding footstep is created.
-- range: 0-360

BipedFSKey : MAXObject

1765

mocap.fsUseVerticalTol

Boolean

Default: False

Turn on Z-axis Tolerance. The control filters out footsteps that do not fall within a given range of the ground plane. Use this when filtering motions, such as hopping or pitching a baseball, in which a foot may come off the ground and remain stationary, but its position is not intended as a footstep.
mocap.fsVerticalTol Float Default: 0.5

Value is a percentage of leg length

-- range: 0+ mocap.fsZLevel Float Boolean Default: 0.0 Default: False

Set a Z value (ground).

mocap.fsUseFlatten

Extracted footsteps are moved to Z=0. Use this to flatten out minor differences in the height of the extracted footsteps. -- Load Frames
mocap.startFrame mocap.endFrame mocap.loop Integer Integer Boolean Default: 0 Default:0 Default: False

Start importing at this frame. Default is frame 0, the first frame. Stop importing at this frame. Default is the last frame of the clip. Loop the data by the value set here. This is relative. Succeeding loops start where the previous loop left off. The clips are not blended and may require editing unless the original clip was designed to loop. Use this for clips designed to loop. Note: This often works best if Footstep Extraction is tuned off.
mocap.loopFrameCount -- range: 0+ Integer Default: 0

-- Key Reduction Settings Tolerance: Set the maximum angular or positional deviation for a track. Values are in degrees for rotation tracks. Values are in units of translation for position tracks. Minimum Key Spacing: Set the minimum number of frames between keys. Tolerance is computed first, then Minimum Key Spacing computes further key reduction. A Minimum Key Spacing value of 10 for the head track ensures that no two keys are closer than 10 frames for this track.

1766

Chapter 21

character studio 3 MAXScript Extensions

Set All: Force all tracks to the values set in these fields. Higher values here can determine how much key reduction is possible while preserving the original motion. Filter: Clear to prevent filtering of the motion capture data into a track. If this is cleared, there will be no key reduction for the track.
mocap.allTol -- range: 0+ mocap.allSpacing -- range: 0+ mocap.allFilter mocap.horzTol -- range: 0+ mocap.horzSpacing -- range: 0+ mocap.horzFilter mocap.rotTol -- range: 0+ mocap.rotSpacing -- range: 0+ mocap.rotFilter mocap.vertTol -- range: 0+ mocap.vertSpacing -- range: 0+ mocap.vertFilter mocap.pelvisTol -- range: 0+ Boolean Float Default: True Default: 6.0 Integer Default: 4 Boolean Float Default: True Default: 1.0 Integer Default: 3 Boolean Float Default: True Default: 1.0 Integer Default: 3 Boolean Float Default: False Default: 1.0 Integer Default: 3 Float Default: 0.0

BipedFSKey : MAXObject

1767

mocap.pelvisSpacing -- range: 0+ mocap.pelvisFilter mocap.spineTol -- range: 0+ mocap.spineSpacing -- range: 0+ mocap.spineFilter mocap.neckTol -- range: 0+ mocap.neckSpacing -- range: 0+ mocap.neckFilter mocap.leftArmTol -- range: 0+ mocap.leftArmSpacing -- range: 0+ mocap.leftArmFilter mocap.rightArmTol -- range: 0+ mocap.rightArmSpacing -- range: 0+ mocap.rightArmFilter mocap.leftLegTol -- range: 0+

Integer

Default: 3

Boolean Float

Default: True Default: 6.0

Integer

Default: 3

Boolean Float

Default: True Default: 6.0

Integer

Default: 3

Boolean Float

Default: True Default: 6.0

Integer

Default: 3

Boolean Float

Default: True Default: 6.0

Integer

Default: 3

Boolean Float

Default: True Default: 6.0

1768

Chapter 21

character studio 3 MAXScript Extensions

mocap.leftLegSpacing -- range: 0+ mocap.leftLegFilter mocap.rightLegTol -- range: 0+ mocap.rightLegSpacing -- range: 0+ mocap.rightLegFilter mocap.tailTol -- range: 0+ mocap.tailSpacing -- range: 0+ mocap.tailFilter

Integer

Default: 3

Boolean Float

Default: True Default: 6.0

Integer

Default: 3

Boolean Float

Default: True Default: 6.0

Integer

Default: 3

Boolean

Default: True

-- Limb orientation Angle: Move the knee or Elbow position to create the biped joint key. Point: Rotate the shoulder-elbow-wrist or hip-knee-ankle to create the biped joint key. Auto: Auto reads exact hand and foot positions from the motion capture data, character studio then places the knees and elbows in a natural position. For marker files involving running and walking, this option can clean up the data nearly instantly, regardless of how many markers were used (and where they were placed).
mocap.kneeOrient 0 - angle 1 - point 2 - auto Integer Default: 0

The biped knee hinge joints are perpendicular to the triangles formed by the hip-kneeankle. Resolve errors in the motion capture data that break this rule by using either the angle or point method.

BipedFSKey : MAXObject

1769

mocap.elbowOrient 0 - angle 1 - point 2 - auto

Integer

Default: 0

The biped elbow hinge joints are perpendicular to the triangles formed by the shoulderelbow-wrist. Resolve errors in the motion capture data that break this rule by using either the angle or point method.
mocap.footOrient 0 - angle 1 - auto Integer Default: 0

The biped foot hinge joints are perpendicular to the triangles formed by the hip-kneeankle respectively. Resolve errors in the motion capture data that break this rule by using either the angle or point method.
mocap.handOrient 0 - angle 1 - auto Integer Default: 0

The biped hand hinge joints are perpendicular to the triangles formed by the shoulderelbow-wrist. Resolve errors in the motion capture data that break this rule by using either the angle or point method. -- Talent Definition
mocap.talentFigStrucFile structure file (.fig) mocap.useTalentFigStrucFile String Default: -- figure

A .fig file containing changes made to the biped scale while in Talent Figure mode.
Boolean Default: False

Turn on useTalentFigStrucFile to use the file whose string is defined in mocap.talentFigStrucFile.

mocap.talentPoseAdjFile adjustment file (.cal) mocap.useTalentPoseAdjFile String Default: -- pose

A .cal file containing changes made to the biped while in Adjust Talent Pose mode.
Boolean Default: False

Turn on useTalentPoseAdjFile to use the file whose string is defined in mocap. talentPoseAdjFile.

1770

Chapter 21

character studio 3 MAXScript Extensions

-- Marker Name Files

mocap.markerNameFile marker name file (.mnm) String Default: -- csm

A Marker Name file to map incoming marker names in motion capture files (.bvh or .csm) to the character studio marker naming convention.
mocap.useMarkerNameFile mocap.jointNameFile marker name file (.mnm) Boolean String Default: False Default: -- bvh

When set to true, use the file defined in mocap.markerNameFile.

A Marker Name file to map incoming marker names in motion capture files (.bvh or .csm) to the character studio marker naming convention.
mocap.useJointNameFile Boolean Default: False

When set to true, use the file defined in mocap.jointNameFile. -- Marker Display Options Marker and marker names are displayed around the biped. Discrepencies like the biped elbow position relative to the elbow marker can be spotted and adjusted.
mocap.dispKnownMarkers mocap.dispKnownMarkersType true on all props false on selected props mocap.dispPropMarkers mocap.dispUnKnownMarkers Boolean Boolean Default: False Default: False

Boolean Boolean

Default: False Default: False

-- Load Save Methods

mocap.loadParameters <file_name> mocap.saveParameters <file_name>

Load/Save a motion capture parameter (.MOC) file

Crowd : helper

1771

Crowds
Crowd : helper
Constructor:
crowd ...

Properties:
<crowd>.simStart Integer Integer Integer Boolean Default: 0 Default: 0 Default: 100 Default: False

The first frame of the simulation.

<crowd>.solveStart

The frame at which you begin solving.

<crowd>.solveEnd <Crowd>.deleteKeys

Specifies the last frame considered for the solution. When true, Crowd deletes the keys of active delegates in the range over which the solution takes place.
<Crowd>.saveNthPos <Crowd>.saveNthRot <Crowd>.flashing Hilite_Delegates_During_Assignments <crowd>.vectorScale Integer Integer Boolean Float Default: 1 Default: 1 Default: True Default: 1.0 Alias:

Saves every nth position frame after the solution. Saves every nth rotation frame after the solution.

Globally scales all force and velocity vectors that are displayed during the simulation. Scaling vectors up helps to see them better when they are very small. It does not effect the simulation.
<Crowd>.useScript <Crowd>.functionName Script_Context_Name <Crowd>.script <crowd>.update Update_Display_During_Solve Boolean String Default: False Default: PerFrameFn Alias:

When true, Crowd executes a script at each frame of the solution.

The name of the function to be executed. This name must also be specified in the script.
String Boolean Default: Undefined Default: True Alias:

When true, motion produced during solution of a crowd simulation appears in the viewports.
<Crowd>.updateFrequency Integer Default: 1

How often the display is updated during the solution. If 1, the update occurs every frame. If 2, the update occurs every other frame, and so on.

1772

Chapter 21

character studio 3 MAXScript Extensions

<Crowd>.solveForBipeds

Boolean

Default: False

When on, only biped/delegates are included in the computation. Also, the options to use priorities and backtracking become available. These options are available only for bipedonly computations.
<Crowd>.usePriorities Boolean Default: False

When on, biped/delegates are computed one delegate at a time, in order of their Priority values, from lowest to highest. Also, backtracking becomes available and Step Solve becomes unavailable.
<Crowd>.backtracking Boolean Default: False

Turns on backtracking functionality when solving a crowd simulation that uses bipeds. When Backtracking is on during the solution, in the case of an impending collision between bipeds, the Crowd system will back up the simulation to the beginning of the current clip, and then try a different traversal of the lower-priority delegate/bipeds motion flow graph. If necessary, the system will back up two or more clips.
<crowd>.showCollisions ClearColl <crowd>.whenToShowCollisions Boolean Default: False Alias:

When true the delegates that collide are highlighted in the collision color.
Integer Default: 0

0 only during collisions: Colliding delegates are highlighted only in frames in which they actually collide. 1 always: Colliding delegates are highlighted in frames in which they collide and all subsequent frames.
<crowd>.collisionColor <crowd>.IconSize <crowd>.behaviors Color Default: (color 255 0 0)

The color swatch indicates the color used to highlight colliding delegates.
Float Default: 0.0 ArrayParameter Default: #() ArrayParameter Default: #() ArrayParameter Default: #() ArrayParameter Default: #()

Array of Behavior objects

<crowd>.teams

Array of Team objects

<crowd>.assignments <crowd>.cogcontrols Cognitive_Controllers Alias:

CogControl : MAXObject (p. 1791)

<crowd>.scatter MAXObject Default: Scatter_Parameters Default: ObjAssoc Alias:

CrowdScatter: (p. 1778)

<crowd>.objAssoc MAXRefTarg Object_Delegate_Associations_Parameters

Display the dialog to link any number of delegate-object pairs.

Delegate : Helper

1773

<crowd>.smooth Smoothing_Parameters

MAXRefTarg

Default: Smooth

Alias:

Display the Smoothing dialog to smooth existing animation keys on a solved simulation to create more natural-looking animation
<Crowd>.priority MAXRefTarg Alias: Priority_Parameters See Priority PropertiesCrowd_Priority_Properties. Default: Priority -- Read-only;

See Also
Biped and Crowd Interaction (p. 1734)

Delegate : Helper
The Delegate helper object is a special pyramidal object used in crowd animation. By default, the point of the pyramid indicates the forward direction. The Crowd object controls the delegate or delegates, whose motion can then be imparted to a biped or other object. Constructor:
Delegate ... CrowdDelegate ...

Properties:
<Delegate>.width Float Float Float Color Default: 0.0 Default: 0.0 Default: 0.0 -- world units -- world units -- world units

The width of the Delegate object.

<Delegate>.depth

The depth of the Delegate object.

<Delegate>.height

The height of the Delegate object.

<Delegate>.velocityColor Default: (color 0 0 0)

When showVelocity is true, uses the specified color to draw a vector in the delegates center during the simulation solution. The vector length indicates the delegates relative speed.
<Delegate>.active <Delegate>.showForces Boolean Boolean Default: True Default: True

The delegate object is subject to control by a Crowd object. The forces being applied to a delegate by any applicable behaviors are drawn as vectors whose length indicate the extent of the forces. For example, if the delegate is affected by a Space Warp behavior and a Wander behavior, the vectors (using default colors) are yellow and blue-green, respectively. These vectors are visible only during solution of the crowd simulation.

1774

Chapter 21

character studio 3 MAXScript Extensions

<Delegate>.showVelocity

Boolean

Default: False

Uses the Velocity Color (see above) to draw a vector whose length depicts the delegates relative speed. This vector is visible only during solution of the crowd simulation.
<Delegate>.showCogStates Boolean Default: True

During a solve, a text label appears next to the delegate showing the name of the cognitive controller state or transition that currently directs its behavior, if any.
<Delegate>.xyConstrain Boolean Default: True

The delegate remains at its initial height (position on the world XY axis) throughout the simulation. When off, the delegates height can change during the simulation, for example when seeking an object at a different height.
<Delegate>.useHierBbox Boolean Alias Use_Hierarchy_in_Bounding_Box_Computation Default: True

When true, the Avoid behavior uses the bounding box of the delegate and all of its children to perform its behavior. This bounding box is computed by the Crowd object, is used by the collision detector, and can be accessed by other behaviors.
<Delegate>.averageSpeed world units Float Default: 5.0 -- animatable;

Specifies the delegates baseline velocity in 3ds max units (or the current unit type) per second. This can be modified during the simulation by a variety of factors, such as a linked bipeds built-in speed and Deviation settings in a behavior.
<Delegate>.maxAccel world units <Delegate>.turnDecel Alias: Turn_Deceleration_Weight Float Default: 0.1 -- animatable;

Multiplied times Average Speed to determine the maximum acceleration.

Float Default: 0.3 -- animatable;

Specifies how much a delegate should slow down when turning. The higher this setting, the more the delegate slows down when it reaches the turn angle (see following parameter). A value of 0 specifies no slowdown; a value of 1 tells the delegate to stop. The algorithm computes a value, d, which goes linearly from 0 to (1 - Decel Weight) as the turn angle of the delegate goes from 0 to the Turn Angle specified by the user. The speed of the delegate is then multiplied by d. For example, when the delegate turns at the Turn Angle or greater, its speed will be multiplied by 1 - Decel Weight, slowing it down as much as possible based on this parameter. When the delegate is not turning at all, its speed is not affected by the Decel Weight. When the delegate is turning at half the specified Turn Angle, d = Decel Weight / 2, so its speed will be multiplied by (1 - Decel Weight / 2). As a practical example, take a delegate traveling at 10 units/sec, Decel Weight is set to 0.4, and At Turn Angle is set to 30. When the delegate has turned 15 degrees (half the At Turn Angle), the effective deceleration weight is 0.2. Subtract that quantity from 1 to get 0.8, and then multiply that times the delegates speed to get 8 units per second halfway into the turn. At the full turn (30 degrees), the delegate travels at 6 units per second.

Delegate : Helper

1775

<Delegate>.turnDecelAngle Alias: Turn_Deceleration_Angle

Float

Default: 10.0

-- animatable;

Specifies the turn angle at which Decel Weights full slowdown effect is applied. If the current turn angle is less than At Turn Angle, the algorithm divides the latter by the former, and then divides the Decel Weight setting by the result to derive the effective decel weight.
<Delegate>.inclineDecel Alias: Incline_Deceleration_Weight <Delegate>.inclineDecelAngle Alias: Incline_Deceleration_Angle <Delegate>.declineAccel Alias: Decline_Acceleration_Weight Float Default: 0.1 -- animatable;

Specifies how much the delegate should slow down when moving at an upward slant.
Float Default: 90.0 -- animatable;

Specifies the upward slant angle at which Decel Weights full slowdown effect is applied.
Float Default: 0.1 -- animatable;

Specifies how much the delegate should speed up when moving at a downward slant. See Decel Weight for a full explanation, taking into account that Accel Weight produces a speedup effect rather than a slowdown. Thus, the effective acceleration weight is added to 1, not subtracted from it.
<Delegate>.declineAccelAngle Alias: Decline_Acceleration_Angle <Delegate>.maxTurnVel Alias: Max_Turn_Velocity <Delegate>.maxTurnAccel Alias: Max_Turn_Acceleration Float Default: 90.0 -- animatable;

Specifies the downward slant angle at which Accel Weights full speedup effect is applied.
Float Default: 30.0 -- animatable;

Specifies the maximum number of degrees a delegate can turn.

Float Default: 3.0 -- animatable;

Specifies how much the delegates turn angle can change per frame. If this is not small, the delegates direction might jerk around. It would be allowed to turn suddenly, rather than smoothly.
<Delegate>.maxIncline Alias: Max_Incline_Velocity <Delegate>.maxDecline Alias: Max_Decline_Velocity <Delegate>.maxBank <Delegate>.maxBankVel Alias: Max_Bank_Velocity Float Default: 90.0 -- animatable;

Specifies the maximum number of degrees a delegate can turn upward per frame.
Float Default: 90.0 -- animatable;

Specifies the maximum number of degrees a delegate can turn downward per frame.
Float Float Default: 30.0 Default: 3.0 -- animatable -- animatable;

Specifies the maximum number of degrees a delegate can bank.

Specifies how much the delegates bank angle can change per frame.

1776

Chapter 21

character studio 3 MAXScript Extensions

<Delegate>.bankPerTurn

Float

Default: 1.0

-- animatable

The number of degrees the delegate will bank as a function of the turn angle at the current frame. For example, if Bank per Turn=1, the delegate will bank one degree for every degree it is turning at a given frame.
<Delegate>.useBiped <Delegate>.biped <Delegate>.startFrame <Delegate>.priority Boolean Node Integer Integer Default: False Default: Undefined Default: 0 Default: 0

When true, the delegate is associated with a biped. The biped with which the delegate is associated. The frame at which the associated bipeds first clip will begin to play. Sets the delegate priority, which determines the order of solution in biped/delegate simulations.
<Delegate>.s Integer Default: 0

0 First clip of current script 1 Random start clip

<Delegate>.duration <Delegate>.behaviors Integer ArrayParameter Default: 0 Default: #()

The number of frames the delegate has been in the current state. The behaviors property contains valid values only during a solve. Contains the behaviors being used during the solve.
<Delegate>.weights ArrayParameter Default: #()

The weights property contains valid values only during a solve. Each element contains the weight of the corresponding behavior in the behaviors property value.
<Delegate>.simpos Point3 Default: [0,0,0]

The simpos property contains a valid value only during a solve. Contains the current position of the delegate during the simulation.
<Delegate>.randID Integer Default: 0

A possibly non-unique identifier whose purpose is to be used by behaviors as part of its seed calculation. If more than one delegate has the the same randId then they should have the same random behavior. By defualt, crowd creates unique randIds.
<Delegate>.index Integer Default: -1 -- Read-only

Index used by various behaviors as indices into internal arrays. Before a solve, Crowd makes sure that the delegates who are participating in the solve are given a contiguous set of indices, so that behaviors can set up arrays which use these indices.

Delegate : Helper

1777

Related Delegates Methods:

delegates.isComputing <delegate_node>

Returns a 1 if the delegate is currently active in a crowd solve simulation, it returns a 0 otherwise.
delegates.velocity <delegate_node>

Returns the normalized velocity of the delegate at the current simulation frame as a Point3 value.
delegates.prevVelocity <delegate_node>

Returns the normalized velocity of the delegate at the previous simulation frame as a Point3 value.
delegates.startVelocity <delegate_node> <time>

Returns the normalized velocity of the delegate at the start of the crowd simulation as a Point3 value. Thus the <time> parameter is a time value that should be equal to crowd.simStart.
delegates.speed <delegate_node>

Returns the speed of the delegate at the current simulation frame as a float.
delegates.isAssignmentActive <delegate_node> <assignmentIndex> <time>

Returns a 1 if the delegate is active for a particular crowd assignment at the time specified, if not it returns a 0. The <assignmentIndex> directly corresponds to the index of the assignment in the crowds.assignment array. Note: The functions lineDisplay ,sphereDisplay ,bboxDisplay , and textDisplay are all functions which can be used to draw a graphic primitive for a particular delegate when the crowd simulation is being solved. All of the positional values are in world space. Usually these functions will be used within a scripted behavior to visually demonstrate the behavior. For example, lineDisplay could be used to draw a line that represents the force that the behavior is exerting on that delegate.
delegates.lineDisplay <delegate_node> <startPosition> <endPosition> <color> <vectorScale>

This function will draw a line from the start position to the endPosition with the color specified. <startPosition> is a point3 value. <endPositions> is a point3 value. <color> is a color value. <vectorScale> boolean value. Whether or not to scale the line display by the Crowd.vectorScale value.
delegates.sphereDisplay <delegate_node> <position> <radius> <color>

This function will draw a sphere at the position <position>, with a radius of size <radius>, and a color of <color>. <position> is a point3 value, radius is a float and <color> is a color value.

1778

Chapter 21

character studio 3 MAXScript Extensions

delegates.bboxDisplay <delegate_node> <minPosition> <maxPosition> <color>

This function will draw a bounding box specifed by the two extrema points, <minPosition> and <maxPosition>, with the color specified. <minPosition> and <maxPosition> are point3 values and <color> is a color value.
delegates.textDisplay <delegate_node> <position> <color> <string>

This function will draw the text found in the <string> parameter at the position specified at <position>, with the color found in <color>. <position> is a point3 value, <color> is a color value, and <string> is a string value.
delegates.simTransform <delegate> <time>

Returns the delegates transformation matrix at the specified time as a Matrix3 value. This method returns valid values during a solve. Note: During a Solve, the simulation doesnt set the delegate nodes position and rotation keys until the simulation stops. As such, accessing the delegate nodes position and rotation during the solve will return incorrect results. The position of a delegate during a solve can be accessed via the .simpos property. Delegates cannot be rendered, so the size of the Delegate object is primarily for use in scene setup and for determining bounding box extents.

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

CrowdScatter:
These properties correspond to the Scatter Objects dialog displayed by clicking the Scatter Objects icon. Clone Tab Properties:
<crowd.scatter>.cloneObject Node Integer Integer Default: Undefined Default: 10 Default: 0 Alias

Object in the scene to be cloned.

<crowd.scatter>.numClones

The number of clones to be generated.

<crowd.scatter>.cloneType (0_copy__1_reference__2_instance)

0 - copy 1 - Instance 2 - Reference Specify how the object is cloned. It can be cloned as a copy, an instance, or a reference.

CrowdScatter:

1779

<crowd.scatter>.cloneHierarchy

Boolean

Default: True

When true, all objects linked to the selected object are cloned as well, with the hierarchical structure retained intact for each clone.
<crowd.scatter>.cloneControllers Boolean Default: True

Set true to clone an object when calling Scatter All. The object is cloned and then any specified transforms are applied to the clones. Position Tab Properties:
<crowd.scatter>.positionSpace 0_Grid__1_Box___2_Sphere__3_Surface Integer Default: 0 Alias

0 - On Grid 1 - Inside Box 2 - Inside Sphere 3 - On Surface 4 - In Radial Area Choose position object before selecting the reference object. On Grid distributes the clones over the surface of a grid object. Inside Box and Inside Sphere distribute the clones within the volume of a primitive box or sphere object, respectively.
<crowd.scatter>.positionObject Grid_Box_Sphere_Surface Node Default: Undefined Alias:

An object in the scene to be used as a reference object. Note: You can use only a primitive sphere, a primitive box, or a grid helper object as a reference object. A primitive sphere or box that has been converted to a editable mesh object can t be used as a reference object.
<Crowd.scatter>.surfaceOffset Float Default: 0.0

On Surface specifies a consistent distance above the surface using surface normals for distribution. Available only when .positionSpace is set to On Surface.
<Crowd.scatter>.centerX <Crowd.scatter>.centerY <Crowd.scatter>.centerZ <Crowd.scatter>.radius <Crowd.scatter>.XYPlane Float Float Float Float Boolean Default: 0.0 Default: 0.0 Default: 0.0 Default: 10.0 Default: False

Specifies the X value for the center of the distribution in world coordinates. Specifies the Y value for the center of the distribution in world coordinates. Specifies the Z value for the center of the distribution in world coordinates. Specifies the maximum distance from the center within which clones are to be positioned. Specifies that clones are to be distributed on the world XY plane only, resulting in a disclike array.

1780

Chapter 21

character studio 3 MAXScript Extensions

<crowd.scatter>.childBbox Boolean Default: True Include_childrens__bounding_boxes_in_spacing_calculations

Alias:

When true, all of a hierarchical objects sub-objects are considered when determining spacing. When false, only the selected object is considered.
<crowd.scatter>.spacing Float Bounding_Box_Multiplier_for_Position_Spacing Default: 1.0 Alias:

Specifies the minimum distance between cloned objects. The Spacing setting is multiplied by the size of the objects bounding sphere to determine how close objects can get. If Spacing is left at 1.0, the default, objects normally cannot be positioned within each others bounding spheres. If Spacing is set to 2.0, objects are separated by a distance equal to or greater than the size of the bounding sphere.
<crowd.scatter>.positionSeed Integer Default: 0

Specifies a seed value for randomizing the clones locations. If a scene has more than one crowd, each should use a different seed to avoid having identical configurations. Rotation Tab Properties:
<Crowd.scatter>.forwardAxisSign Boolean Default: True

If true, the forward axis is in the positive direction. If false the forward axis is in the negative direction.
<crowd.scatter>.forwardAxis Integer Default: 1

0-X 1-Y 2-Z Specifies which axis of the cloned objects points forward, for use with the Look At Target option.
<crowd.scatter>.UpAxisSign Boolean Default: True

If true the up axis is in the positive direction. If false the up axis is in the negative direction.
<crowd.scatter>.UpAxis Integer Default: 2

0-X 1-Y 2-Z Axis of the cloned objects points upward; this axis is aligned with the world Z axis. Note: You cannot specify the same axis as Local Forward and Local Up simultaneously. If you choose an axis for one thats already chosen for the other, the software switches the other to a different axis.

CrowdScatter:

1781

<crowd.scatter>.lookFrom

Integer

Default: 0

0 - Look From Self 1 - Look From Selected Object Determines the direction from which the clones look. By default, each clone looks from its own position (Self), so that when several clones are looking at a single target, each is oriented differently. To orient each clone so that its parallel to an imaginary line between two objects (the from object and the to object), choose Selected Object and specify the object with the (None) button.
<crowd.scatter>.lookFromObject <crowds.scatter>.LookTowards Node Integer Default: Undefined Default: 0

An object from which the clones are to look if lookFrom = 1. 0 - Look Toward Self 1 - Look Toward Selected Object Determines the direction toward which the scatter objects look. By default, each object retains its current orientation.
<crowd.scatter>.lookAtTarget <crowd.scatter>.sideDeviation Node Float Default: Undefined Default: 0.0

An object toward which the clones are to look. Sets a maximum deviation angle in degrees for the clones sideways orientation. If clones should look in an objects general direction but may look at a spot to either side of the target, use Sideways Deviation to set the maximum amount by which they can deviate from the calculated angle. The actual deviation amount for each clone is calculated at random, based on the Deviation settings and the Rand Seed setting. Range=0.0 to 180.0.
<crowd.scatter>.upDownDeviation Float Default: 0.0

Sets a maximum deviation angle in degrees for the clones up/down orientation. If clones should look in an objects general direction but may look at a spot above or below the target, use Up/Down Deviation to set the maximum amount by which they can deviate from the calculated angle. The actual deviation amount for each clone is calculated at random, based on the Deviation settings and the Rand Seed setting. Range=0.0 to 180.0.
<crowd.scatter>.rotationSeed Integer Default: 0

Specifies a seed value for randomizing the clones orientations, based on the Deviation settings. If a scene has more than one crowd, each should use a different seed to avoid having identical configurations. Scale Tab Properties: Contains options for scaling object clones. For each scaling axis you can specify alternative forward and up axes, plus a target object toward which the clones will point. In addition, you can specify a source object; when using both source and target objects, the clones are rotated so theyre parallel to the line between the two.
<crowd.scatter>.xScale Float Default: 1.0

Sets scaling on the X axis as a multiplier.

1782

Chapter 21

character studio 3 MAXScript Extensions

<crowd.scatter>.xScaleDeviation

Float

Default: 0.0

Sets the maximum factor for randomization of scaling. For each clone, Deviation is multiplied by a random number between 0.0 and 1.0, and then added to the Scale multiplier.
<crowd.scatter>.matchXtoYscale Boolean Default: False

Lets you use the same scaling as on the Y axis, whether explicit or randomized. When you specify an axis, the parameters group for that axis becomes unavailable.
<crowd.scatter>.matchXtoZscale Boolean Default: False

Lets you use the same scaling as on the Z axis, whether explicit or randomized. When you specify an axis, the parameters group for that axis becomes unavailable.
<crowd.scatter>.yScale Float Float Default: 1.0 Default: 0.0

Sets scaling on the Y axis as a multiplier.

<crowd.scatter>.yScaleDeviation

Sets the maximum factor for randomization of scaling. For each clone, Deviation is multiplied by a random number between 0.0 and 1.0, and then added to the Scale multiplier.
<crowd.scatter>.matchYtoXscale Boolean Default: False

Lets you use the same scaling as on the X axis, whether explicit or randomized. When you specify an axis, the parameters group for that axis becomes unavailable
<crowd.scatter>.matchYtoZscale Boolean Default: False

Lets you use the same scaling as on the Z axis, whether explicit or randomized. When you specify an axis, the parameters group for that axis becomes unavailable
<crowd.scatter>.zScale Float Float Default: 1.0 Default: 0.0

Sets scaling on the Z axis as a multiplier.

<crowd.scatter>.zScaleDeviation

Sets the maximum factor for randomization of scaling. For each clone, Deviation is multiplied by a random number between 0.0 and 1.0, and then added to the Scale multiplier.
<crowd.scatter>.matchZtoXScale Boolean Default: False

Lets you use the same scaling as on the X axis, whether explicit or randomized. When you specify an axis, the parameters group for that axis becomes unavailable.
<crowd.scatter>.matchZtoYScale Boolean Default: False

Lets you use the same scaling as on the Y axis, whether explicit or randomized. When you specify an axis, the parameters group for that axis becomes unavailable.
<crowd.scatter>.scaleSeed Integer Default: 0

Specifies a seed value for randomizing the clones scales, based on the Deviation settings.

CrowdScatter:

1783

All Ops Tab Properties:

<crowd.scatter>.ComputeClones Boolean Default: False

Set true to clone an object when calling Scatter All. The object is cloned, then any specified transforms are applied to the clones. Turning on Clones makes the Select Objects to Transform button unavailable. The object to clone and cloning parameters must be specified on the with .ComputeClone.
<crowd.scatter>.ComputePositions Boolean Default: False

When true and crowds.scatterall is called, the transforms are applied according to the settings in the Position panel.
<crowd.scatter>.ComputeRotations Boolean Default: False

When true and crowds.scatterall is called, the transforms are applied according to the settings in the Rotation panel.
<crowd.scatter>.ComputeScales Boolean Default: False

When true and crowds.scatterall is called, the transforms are applied according to the settings in the Scale panel.
<Crowd.scatter>.IncPosSeed Boolean Default: False

When true, add 1 to the .positionSeed value, and redistributes the objects using the new random seed.
<Crowd.scatter>.IncRotSeed Boolean Default: False

When true, add 1 to the .rotationSeed value, and redistributes the objects using the new random seed.
<Crowd.scatter>.IncSclSeed Boolean Default: False

When true, add 1 to the .scaleSeed value, and redistributes the objects using the new random seed.
<crowd.scatter>.ObjectsToScatter ArrayParameter Default: #()

Objects to be affected by calling crowds.scatterall ObjAssoc Properties: These properties correspond to the Object/Delegate dialog displayed by clicking the Associate Objects with Delegates icon.
<ObjAssoc>.objects ArrayParameter Default: #() ArrayParameter Default: #() Boolean Default: True -- node array -- node array

Array of linked Objects.

<ObjAssoc>.delegates

Array of linked delegates.

<ObjAssoc>.alignScale

When true, Align Objects with Delegates sets each objects absolute scaling factor to that of its corresponding delegates. This is useful if, for example, youve randomized delegates sizes with the Scatter Objects Scale panel, and want the associated objects to match.

1784

Chapter 21

character studio 3 MAXScript Extensions

Smooth Properties: These properties correspond to the Smoothing dialog displayed by clicking the Smooth Paths button in the Solve rollout.
<Crowd.smooth>.objects Alias: Objects_to_Smooth <Crowd.smooth>.filterDelegates Filter_Delegate_Selection ArrayParameter Default: #() -- node array;

Specify which objects positions and/or rotations to smooth.

Boolean Default: True Alias:

When true, the Select dialog opened by the Select Objects to Smooth button shows only delegates. When off, it shows all scene objects.
<Crowd.smooth>.wholeAnim Integer Default: 0

0 - Whole Animation: Smoothes all animation frames. 1 - Animation Segment: Smoothes only the frame ranges specified in the From and To fields.
<Crowd.smooth>.from smooth_from_frame <Crowd.smooth>.to smooth_to_frame <Crowd.smooth>.positions Smooth_positions Integer Default: 0 Alias:

When Animation Segment is chosen, specifies the first animation frame for smoothing.
Integer Default: 0 Alias:

When Animation Segment is chosen, specifies the last animation frame for smoothing.
Boolean Default: True Alias:

When true, selected objects animation paths generated via the simulation are smoothed after the simulation has finished.
<Crowd.smooth>.rotations Smooth_rotations Boolean Default: True Alias:

When true, selected objects rotations generated via the simulation are smoothed after the simulation has finished.

CrowdAssignment : MAXObject
Constructor:
CrowdAssignment ...

Properties:
<crowdassignment>.team CrowdTeam Node MAXObject Default: Undefined Default: Undefined Default: Undefined

A named group of delegates.

<crowdassignment>.delegate <crowdassignment>.behavior

A delegate object. See the CrowdDelegate : Helper (p. 1773) topic. One of the Crowd Behavior (p. 1792) classes.

CrowdTeam : ReferenceTarget

1785

<crowdassignment>.cogcontrol CognitiveController <crowdassignment>.weight animatable

CogControl

Default: Undefined

Alias:

A cognitive controller. See CogControl:MAXObject (p. 1791) for more details.

Float Default: 1.0 --

The relative effect of the assigned behavior or cognitive controller. The higher an assignments weight setting is than others, the more effect it will have. This setting is animatable. Range=0.0 to 1.0.
<crowdassignment>.active : Boolean

When true, the assignment is currently in effect. When false, the assignment has no effect. Default=true. Notes: Normally either the team or the delegate property will contain a value of undefined. If both properties contain a value other than undefined, the assigment is applied to the team. Normally either the cogcontrol or the behavior property will contain a value of undefined. If both properties contain a value other than undefined, the behavior will be used. Do not assign a value other than undefined or a CrowdTeam value to the team property. Do not assign a value other than undefined or a Behavior value to the behavior property. Do not assign a value other than undefined or a CogControl value to the cogcontrol property. Do not assign a node type other than a Delegate node to the delegate property.

See also
CrowdTeam : MAXObject (p. 1785) Crowd Behaviors (p. 1792) CogControl : MAXObject (p. 1791) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

CrowdTeam : ReferenceTarget
Constructor:
CrowdTeam ... CrowdGroup ...

Properties:
<crowdteam>.name <crowdteam>.members of Delegate nodes String Default: CrowdTeam -- array

The default team name is Team followed by number one more than the last added team.
ArrayParameter Default: #()

Participants of the current team.

1786

Chapter 21

character studio 3 MAXScript Extensions

Notes: You can perform the following MAXScript operations

deleteitem <array> <itemnumber> <array> = #(item,item...) <array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.
<CrowdTeam>.members -- array of Delegate nodes

Notes: The following MAXScript operations will cause Crowd to fail, either right away or later: NEVER set a Members ArrayParameter element to undefined. Assigning a non-Delegate node to the Members ArrayParameter.

See also
MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

CrowdState:ReferenceTarget
Constructor:
CrowdState ...

Properties:
<crowdstate>.name String Default: State

The name of the state.

<crowdstate>.behaviors behaviors ArrayParameter Default: #() -- array of

See Notes below. The names of all behaviors associated with the state.
<crowdstate>.weights ArrayParameter Default: #() -- array of floats

See Notes below. Specifies the selected behaviors weight. The higher the weight in relation to other behaviors weights, the more evident the results of the behavior in the state. Default=1.0. Range=0.0 to 1.0.
<crowdstate>.transitions CrowdTransition objects ArrayParameter Default: #() -- array of

See Notes below. Notes: You can perform the following MAXScript operations:
deleteitem <array> <itemnumber> <array> = #(item,item...)

CrowdTransition : MAXObject

1787

<array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.
<CrowdState>.behaviors <CrowdState>.weights <CrowdState>.transitions -- array of behaviors -- array of floats -- array of CrowdTransition objects

If you add or delete elements to the Behaviors ArrayParameter, the corresponding element in the Weights ArrayParameter must be added or deleted.

The following MAXScript operations will cause Crowd to fail, either right away or later: NEVER set Behavior ArrayParameter element to undefined. NEVER set a Behavior ArrayParameter element to anything other than an object of the appropriate type.

See Also
Crowd Behaviors (p. 1792) CrowdTransition : MAXObject (p. 1787) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

CrowdTransition : MAXObject
Constructor:
CrowdTransition ... Transition ...

Properties:
<crowdtransition>.priority Integer Integer Float Float String Default: 0 Default: 25 Default: 0.5 Default: 0.5 Default: transFunc Alias:

Sets the transitions priority.

<crowdtransition>.duration <crowdtransition>.easeIn

The number of frames the software takes to affect the transition between states. Ease in value for the source clip.
<crowdtransition>.easeOut

Ease out value for the destination clip.

<crowdtransition>.functionName Script_Context_Name <crowdtransition>.script <crowdtransition>.from FromState

The name of the MAXScript conditional that specifies when/how the transition is to occur.
String CrowdState Default: Undefined Default: Undefined Alias:

The state that the transition originated from.

1788

Chapter 21

character studio 3 MAXScript Extensions

<crowdtransition>.to ToState

CrowdState

Default: Undefined

Alias:

The state that the transition is destined for. Notes: The <CrowdTransition>.functionName value must match the name of the function defined in <CrowdTransition>.script. The script function is compiled with the function name in global scope. The function name cannot be the same as a MAXScript-defined global variable name. The <CrowdTransition>.script is of the form:
fn transFunc del trans t = ( if t < 50 then 0 else 1 )

where del is the delegate node, trans is the CrowdTransition value, and t is the time value of the frame being evaluated. The 3ds max time context will also be frame being evaluated. The return value must be an integer value. If the return value is 0, the transition is not taken. For any other return value, the transition is taken. The <CrowdTransition>.script is not evaluated for a delegate while the delegate is in transition between states. The following MAXScript operations will cause Crowd to fail, either right away or later: NEVER set the from or to properties to undefined. NEVER set the from or to properties to anything other than a CrowdState object.

See also
CrowdState : MAXObject (p. 1786) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Crowds - Methods
crowds.solve <crowd_node>

Equivalent to clicking Solve in the crowds Solve rollout. .solve starts the solving, based on all other current crowd parameter settings.
crowds.genclones <crowd_node>

Equivalent to clicking Generate Clones in the Scatter Objects dialog, Clone tab, displayed by clicking the Scatter Objects icon. Generates clones based on all other current crowd parameter settings.
crowds.genlocations <crowd_node>

Equivalent to clicking Generate Locations in the Scatter Objects dialog, Position tab, displayed by clicking the Scatter Objects icon. Generates locations based on all other current crowd parameter settings.

Crowds - Methods

1789

crowds.genrotations <crowd_node>

Equivalent to clicking Generate Orientations in the Scatter Objects dialog, Rotation tab, displayed by clicking the Scatter Objects icon. Generates rotations based on all other current crowd parameter settings.
crowds.genscales <crowd_node>

Equivalent to clicking Generate Scales in the Scatter Objects dialog, Scale tab, displayed by clicking the Scatter Objects icon. Generates scales based on all other current crowd parameter settings.
crowds.scatterall <crowd_node>

Equivalent to clicking Scatter button in the Scatter Objects dialog, All Ops tab. Scatters objects based on all other current crowd parameter settings.
crowds.alignObjects <crowd_node>

Equivalent to clicking Align Objects with Delegates in the Object/Delegates dialog displayed by clicking the Associate Objects with Delegates icon. Aligns objects based on all other current crowd parameter settings.
crowds.linkObjects <crowd_node>

Equivalent to clicking Link Objects to Delegates in the Object/Delegates dialog displayed by clicking the Associate Objects with Delegates icon. Links objects based on all other current crowd parameter settings.
crowds.assignControllers <crowd_node>

Equivalent to clicking Assign Delegate Controllers to Objects in the Object/Delegates dialog displayed by clicking the Associate Objects with Delegates icon. Assigns controllers based on all other current crowd parameter settings.
crowds.smooth <crowd_node>

Equivalent to clicking OK in the Smoothing dialog displayed by clicking the Smooth Paths button in the Solve rollout. Smooths objects motions based on all other current crowd parameter settings.
crowds.assignGridProximityPriorities <crowd_node>

Equivalent to clicking Proximity to a Grid/Assign in the Priority rollout. Assigns priorities to the delegates specified in <Crowd.priority>.delegates based on their distance from the grid specified in <Crowd.priority>.grid.
crowds.assignObjectProximityPriorities <crowd_node>

Equivalent to clicking Proximity to an Object/Assign in the Priority rollout. Assigns priorities to the delegates specified in <Crowd.priority>.delegates based on their distance from the object specified in <Crowd.priority>.object.
crowds.assignRandomPriorities <crowd_node>

Equivalent to clicking Assign Random Priorities in the Priority rollout. Assigns random priorities to the delegates specified in <Crowd.priority>.delegates.
crowds.assignUniquePriorities <crowd_node>

Equivalent to clicking Make Priorities Unique in the Priority rollout. Ensures that the priorities of the delegates specified in <Crowd.priority>.delegates are unique. If two delegates share the same priority, one of them will be given a new priority.

1790

Chapter 21

character studio 3 MAXScript Extensions

crowds.incrementPriorities <crowd_node>

Equivalent to clicking Increment Priorities in the Priority rollout. Increments the priorities of the delegates specified in <Crowd.priority>.delegates by the value in <Crowd.priority>.increment. Notes - MAXScript Group: The MAXScript group of the Solve Rollout has a feature to control the execution of a MAXScript script at each frame. Use MAXScript: When on, a user-specified script is executed at each frame during the solution. Default=off. Function Name: The name of the function to be executed. This name must be identical to the one specified in the script. Edit MAXScript: Click this button to open a MAXScript window for displaying and modifying the script. The crowd function needs two parameters defined. The 1st parameter passed in is the current crowd and the 2nd parameter passed in is the solve frame. Here is simple example:
fn g_PerFrameFn current_crowd the_frame_time = ( if the_frame_time == 1f then (_g_mydebugwindow = newScript() format % %\n current_crowd the_frame_time to:_g_mydebugwindow ) )

Notes: You can perform the following MAXScript operations:

deleteitem <array> <itemnumber> <array> = #(item,item...) <array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.
<Crowd>.behaviors <Crowd>.teams <Crowd>.assignments <Crowd>.cogcontrols <Crowd.scatter>.ObjectsToScatter <Crowd.objAssoc>.objects <Crowd.objAssoc>.delegates <Crowd.smooth>.objects -- array of Behavior objects -- array of CrowdTeam objects -- array of Assignment objects -- array of CognotiveController objects -- node array -- node array -- node array -- node array

If you delete a team or a cognitive controller via MAXScript deleteitem $crowd01.teams[1] 1 or deleteitem $crowd01.cogcontrols[1] 1, it may still be referenced by some assignments. Nothing will go wrong, but its a strange thing to do and one probably should not do it.

CogControl : MAXObject

1791

The following MAXScript operations will cause Crowd to fail, either right away or later: NEVER set a Crowd ArrayParameter element to undefined. NEVER set a Crowd ArrayParameter element to to anything other than an object of the appropriate type.

CogControl : MAXObject
Constructor:
CogControl ...

Properties:
<cogcontrol>.name String CrowdState Default: CognitiveControl Default: Undefined

The name of the state diagram.

<cogcontrol>.startState

Set the starting CrowdState (p. 1786). By default the state that executes first in a cognitive controller is the one that was added first.
<cogcontrol>.states CrowdState objects ArrayParameter Default: #() -- array of

All of the states used by this cognitive controller. Notes: You can perform the following MAXScript operations
deleteitem <array> <itemnumber> <array> = #(item,item...) <array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.
<CogControl>.states -- array of CrowdState objects

If you delete a CrowdState (deleteitem $crowd01.cogcontrols[1].states 1), it may still be referenced by either the startState or by a CrowdTransition stored in another CrowdState. The following MAXScript operations will cause Crowd to fail, either right away or later: NEVER set a States ArrayParameter element or the startState to undefined. NEVER set a States ArrayParameter element or the startState to anything other than a CrowdState.

See also
CrowdState:MAXObject (p. 1786) CrowdAssignment : MAXObject (p. 1784) CrowdTeam : MAXObject (p. 1785) CogControl : MAXObject (p. 1791)

1792

Chapter 21

character studio 3 MAXScript Extensions

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

Crowd Priority Properties

<Crowd.priority>.start <Crowd.priority>.delegates <Crowd.priority>.object <Crowd.priority>.grid <Crowd.priority>.increment <Crowd.priority>.showPriorities Integer Default: 0 -node array ArrayParameter Default: #() Node Node Integer Boolean

Default: Undefined Default: Undefined Default: 0 Default: False

See Also
Crowd : helper (p. 1771)

Crowd Behaviors
Avoid_Behavior : MAXObject (p. 1793) Orientation_Behavior : MAXObject (p. 1794) Path_Follow_Behavior : MAXObject (p. 1796) Repel_Behavior : MAXObject (p. 1798) Scripted_Behavior : MAXObject (p. 1799) Seek_Behavior : MAXObject (p. 1807) Space_Warp_Behavior: MAXObject (p. 1809) Speed_Vary_Behavior : MAXObject (p. 1809) Surface_Arrive_Behavior : MAXObject (p. 1811) Surface_Follow_Behavior : MAXObject (p. 1814) Wall_Repel_Behavior : MAXObject (p. 1816) Wall_Seek_Behavior : MAXObject (p. 1817) Wander_Behavior : MAXObject (p. 1819)

Avoid_Behavior : MAXObject

1793

Avoid_Behavior : MAXObject
Constructor:
Avoid_Behavior ... AvoidBehavior ...

Properties:
<Avoid_behavior>.name <Avoid_behavior>.obstacles <Avoid_Behavior>.lookAhead String Default: Avoid

ArrayParameter Default: #() -- node array Integer Default: 30 -- animatable

Any object or objects that the delegates must keep away from. See Notes below. The number of frames in advance of the current frame that the software looks for potential collisions.
<Avoid_behavior>.hardRadius <Avoid_Behavior>.showHardRadius <Avoid_Behavior>.detourAngle Float Boolean Float Default: 1.0 -- animatable Default: False Default: 360.0 -- animatable

Distance from center of the delegate(s), where no penetration should occur. Enables display of a wireframe sphere that depicts the extent of the .hardRadius setting. Maximum necessary turning angle relative to the direction of delegates goal that the delegate will steer to avoid rather than slow down and wait.
<Avoid_Behavior>.brakePressure Float Default: 2.0 -- animatable

Determines how strongly the brakes are applied. Higher values induce more gradual and slower stops, but may cause brakes to pump in order to slow down.
<Avoid_behavior>.repelStrength Float Default: 0.2 -- animatable

Determines the strength of the repelling force; higher values result in greater repulsion force.
<Avoid_behavior>.repelRadius <Avoid_behavior>.repelFalloff Float Float Default: 3.0 Default: 3.0 -- animatable

Distance from hard radius of delegate where repel avoidance is sensed and carried out. Higher values cause the repel to fall off to zero more rapidly with distance, thus focusing its effect closer to the delegates hard radius.
<Avoid_behavior>.vfieldStrength Float Vector_Field_Avoid_Strength -- animatable Default: 1.0 Alias

Higher values result in more severe influence. Delegates will be directed to move perpendicular to the field.
<Avoid_behavior>.vfieldFalloff Vector_Field_Falloff -- animatable Float Default: 8.0 Alias

Higher values cause vector field influence to fall off to zero more rapidly with distance, thus focusing its effect closer to the delegates hard radius.
<Avoid_Behavior>.showRepelRadius Boolean Default: False

When true, displays a wireframe sphere that depicts the extent of the .repelRadius setting.

1794

Chapter 21

character studio 3 MAXScript Extensions

<Avoid_Behavior>.showPotentialCols <Avoid_Behavior>.showRepelActivity

Boolean Boolean

Default: False Default: False

When true, displays a green line from the delegate to the location of a potential collision. When true, displays a white line between the delegate and target when the repel force is in effect.
<Avoid_Behavior>.showLookAhead Boolean Default: False

When true, displays a sphere that shows the current distance used to check for potential collisions.
<Avoid_behavior>.forceColor <Avoid_behavior>.displayForce Color Boolean Default: (color 255 0 0) Default: True

Sets the color used to draw the Avoid force vector during the solution. When true, force exerted on the delegate(s) by the Avoid behavior is drawn in the viewports as a vector during the simulation solution. Notes: You can perform the following MAXScript operations:
deleteitem <array> <itemnumber> <array> = #(item,item...) <array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.
<Avoid_Behavior>.obstacles

The following MAXScript operations will cause Crowd to fail, either right away or later: NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See also
Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Orientation_Behavior : MAXObject
Constructor:
Orientation_Behavior ... OrientationBehavior ...

Properties:
<orientation_behavior>.name String Default: Orientation Default: False

<Orientation_Behavior>.headingRelative Boolean

Orientation_Behavior : MAXObject

1795

<orientation_behavior>.minheading HeadingMin animatable

Float

Default: -180.0 Alias:

The minimum permissible heading. This number should be lower than the Min Heading value. Range=-180 to 180.
<orientation_behavior>.maxheading animatable Float Default: 180.0 HeadingMax

The maximum permissible heading. This number should be higher than the Min Heading value. Range=-180 to 180.
<orientation_behavior>.maxHeadingVel maxHeadingVelocity animatable Float Default: 180.0 Alias:

Specifies how much the delegates heading can change per frame. This controls angular acceleration and deceleration.
<orientation_behavior>.headingresponse Float Default: 1.0 animatable

Determines how quickly the heading follows the direction the object is moving in. A value of 1.0 indicates maximum responsiveness, and will point in the direction the delegate is moving while a lower value means that it is less responsive. Range=0 to 1.
<orientation_behavior>.minpitch animatable Float Default: -180.0 Alias: PitchMin

The minimum number of degrees a delegate can incline or decline. This number should be lower than the Max Pitch value. Range=-180 to 180.
<orientation_behavior>.maxpitch animatable Float Default: 180.0 Alias: PitchMax

The maximum number of degrees a delegate can incline or decline. This number should be higher than the Min Pitch value. Range=-180 to 180.
<orientation_behavior>.maxpitchVel maxPitchVelocity animatable Float Default: 1.0 Alias:

Specifies how much the delegates pitch can change per frame. This controls angular acceleration and deceleration.
<orientation_behavior>.pitchresponse Float Default: 1.0 animatable

Determines how quickly the pitch follows the direction the object is moving in. A value of 1.0 indicates maximum responsiveness while a lower value means that it is less responsive. Range=0 to 1.
<orientation_behavior>.maxbank <orientation_behavior>.maxbankAccel MaxBank_Change animatable Float Float Default: 30.0 animatable Default: 3.0 Alias:

The maximum number of degrees the delegate can bank.

The maximum number of degrees the delegates bank angle can change per frame. This controls angular acceleration and deceleration.
<orientation_behavior>.bankPerTurn Float Default: 1.0 animatable

The number of degrees the delegate will bank as a function of the turn angle at the current frame. For example, if Bank per Turn=1, the delegate will bank one degree for every degree it is turning at a given frame.

1796

Chapter 21

character studio 3 MAXScript Extensions

Notes: If this behavior is active, it controls the orientation of the delegate by allowing the animator to specify limits and responsiveness on the pitch and heading of the object. The animator can limit the min and max values, the rate, and can also set a response value which controls how quickly the pitch or heading follows the direction the object is moving in. A value of 1.0 means its responsive, and will point in the direction the delegate is moving (within the limits), while a lower value means that it is less responsive. It also calculates the roll, which is done using the same parameters that the default behavior does.

See also
Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Path_Follow_Behavior : MAXObject
Constructor:
Path_Follow_Behavior ... PathFollowBehavior ...

Properties:
<path_follow_behavior>.name <path_follow_behavior>.path String Node Default: Path Follow Default: Undefined

A path object. Suitable path objects include splines and NURBS curves. If a path object contains more than one spline or curve, character studio uses the lowest-numbered element (usually the earliest created one).
<path_follow_behavior>.radius Radius_about_Path -- animatable Float Default: 20.0 Alias:

The radial distance from the path within which the delegate stays while traversing the path. Range=0.0 to 99,999.0.
<path_follow_behavior>.awareness Float Default: 0.5 -animatable

Specifies how intelligent the delegate is while traversing this path. A high Awareness setting means that it takes into account the curve of the path while moving and will try to anticipate changes. A low value for Awareness, on the other hand, means that the delegate notices the path only when leaving it. Range=0.0 to 1.0. Note: You can randomize awareness behavior with the Deviation and Seed settings.

Path_Follow_Behavior : MAXObject

1797

<path_follow_behavior>.awareDeviation AwarenessDeviation -- animatable

Float

Default: 0.0 Alias:

Specifies the maximum amount by which Awareness should vary. character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the Awareness setting, and adds the result to Awareness. Range=0.0 to 1.0. Note: You can vary behaviors among different Path Follow behaviors that use the same Awareness and Deviation settings by changing the Seed value.
<path_follow_behavior>.start Integer Default: 0 -animatable

0 - Path Beginning 1 - Path End This setting determines where on the path the delegate begins to follow the path.
<path_follow_behavior>.direction Integer Default: 0 -animatable

0 Forwards: The delegate moves along path vertices in ascending order. 1 Backwards: The delegate moves along path vertices in descending order.
<path_follow_behavior>.endAction Integer Default: 0 -animatable

0 Loop: The delegate loops around the path, even if it isnt closed. If Beginning of Path or End of Path is chosen, it returns to the paths start or end point each time it finishes traversing the path. If Nearest Point is chosen, it returns to an arbitrary point determined by its position and the path shape. 1 Reverse: The delegate reverses direction at the end of the path. Use this choice to simulate a back-and-forth patrol behavior. 2 Continue: The delegate continues moving in the same direction it faced at the end of the path until the simulation ends or its acted upon by another force or behavior.
<path_follow_behavior>.seed <path_follow_behavior>.forceColor <path_follow_behavior>.displayForce Integer Color Boolean Default: 1 -animatable

Specifies a seed value for randomizing Awareness.

Default: (color 0 0 255) Default: True

The color used to draw the Path Follow force vector during the solution. When true, force exerted on the delegate(s) by the Path Follow behavior is drawn in the viewports as a vector during the simulation solution.
<path_follow_behavior>.targetColor <path_follow_behavior>.displayTarget Color Boolean Default: (color 0 0 127.5) Default: True

Sets the color used to draw the target icon. Enables display of the target icon, which appears during the solution when a new interim goal is calculated for the delegate.
<path_follow_behavior>.targetScale Float Default: 5.0 -animatable

The overall size of the target icon.

1798

Chapter 21

character studio 3 MAXScript Extensions

See also
Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Repel_Behavior : MAXObject
Constructor:
Repel_Behavior ... RepelBehavior ...

Properties:
<Repel_Behavior>.name <Repel_Behavior>.repulsionSources String Default: Repel

ArrayParameter Default: #() -- node array Integer Default: 0

See Notes below

<Repel_Behavior>.targetComp

0 Closest Source: Each delegate is repelled by the closest of the assigned sources. Use this to have delegates assigned a single Repel behavior move away from sources in different directions. 1 Average of Sources: All delegates head to a common point determined by averaging all sources locations.
<Repel_Behavior>.repelMethod Integer Default: 0 -- animatable

0 Angle: Applies a force to the delegate based on the angle between the delegates current direction and the direction it would need to take in order to be moving directly away from the source. If the behaviors Weight is set to 1, the delegate will be given a force that points directly away from the source. If Weight is set to .5, the force will bisect the angle between its current direction and the direction opposite that of the source. 1 Force: Always applies a force directly away from the source, but at different magnitudes. If the behaviors Weight is 1, the magnitude of the force will be the average speed. If the Weight is .5, the magnitude of the force will be half the average speed.
<Repel_Behavior>.useRadii Boolean Default: True

When true, the behavior applies only to delegates closer to the target than the Outer Distance value.
<Repel_Behavior>.innerRadius <Repel_Behavior>.outerRadius <Repel_Behavior>.falloff <Repel_Behavior>.forceColor Float Float Float Color Default: 0.0 -- animatable

The distance from the target at which the force is applied at full strength.
Default: 10.0 animatable Default: 2.0 -- animatable Default: (color 255 0 255)

The distance from the target at which the force begins to be applied.

The color used to draw the Repel force vector.

Scripted_Behavior : MAXObject

1799

<Repel_Behavior>.showRadii <Repel_Behavior>.displayForce

Boolean Boolean

Default: True Default: True

When true, the radii are displayed when the force is active. When true, force exerted on the delegate(s) by the Repel behavior is drawn in the viewports as a vector during the simulation solution. If Use Radii is turned on, the radii are also displayed when the force is active. Notes: You can perform the following MAXScript operations:
deleteitem <array> <itemnumber> <array> = #(item,item...) <array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.
<Repel_Behavior>.repulsionSources

The following MAXScript operations will cause Crowd to fail, either right away or later: NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See Also
Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Scripted_Behavior : MAXObject
Introduction to the Crowd System The crowd system works by assembling all of the force vectors (p. 1677) and speeds for a delegate from its active force behaviors. Then based upon the delegates motion parameters, these force vectors (p. 1677) and speeds are averaged and integrated to create a velocity for the delegate. This velocity may then be modified if the delegate has an active constraint behavior or if it has an active default Avoidance behavior. After the velocity is set, if there is an active orientation behavior, it is used to set the orientation of the delegate, otherwise the orientation is calculated from the default delegate parameters. Finally, the velocity is integrated and a new position is calculated. The new position of the delegate isnt set until after all of the forces are calculated for all of the behaviors. For a biped crowd, bipeds work off of goals and not forces when determining which direction they should go in. So, in order to create a force behavior that will work with a Biped, a goal position must be specified. No forces need to be integrated into velocities because the movement of the Biped isnt based upon calculating velocities but rather by selecting clips found in the motion flow graph.

1800

Chapter 21

character studio 3 MAXScript Extensions

Constructor:
Scripted_Behavior ... ScriptedBehavior ...

Properties:
<scripted_behavior>.name <Scripted_Behavior>.scriptContextName Script_Context_Name String String Default: Scripted Default: apply Alias:

The script functions declared in the Edit MaxScript window are declared in a hidden MaxScript context. This textbox specifies the name of the context. Giving a unique name here avoids conflicts between different scripted behaviors.
<Scripted_Behavior>.type Behavior_Type Integer Default: 0 Alias:

One of three behavior types: Force, Constraint, or Orientation. Force: Behaviors of this type force the delegates to move in a particular direction, for example, Seek and Repel. Force behaviors work by returning a force vector (p. 1677) in the direction that the behavior wants the delegate to go in, and in some cases the speed it should be traveling at and the goal at which it is trying to reach. Constraint: Behaviors of this type restrict the position and velocity of a delegate, for example, SurfaceFollow. Constraint behaviors set the velocity and sometimes may even change the delegates position, in order to meet the constraint. You may only have one active constraint behavior per delegate per frame. Orientation: Behaviors of this type affect only the orientation of the delegates, for example Orientation. These behaviors dont work with forces but instead return an orientation that the delegate should be at, represented by a quaternion. Any active orientation behavior will override the default orientation of the delegate. The velocity determines the default orientation. Like a constraint behavior, you may only have one active orientation behavior per delegate per frame. Note: Though there are no avoid behavior types, a force or constraint behavior may be used to create an avoidance behavior. We do recommend though that the default Avoidance behavior be used due to the fact that it is well integrated into the crowd solution pipeline.
<scripted_behavior>.script : string

Scripted_Behavior : MAXObject

1801

Edit MaxScript: This button Edit MaxScript, in the Scripted Behavior Rollout, opens a MAXScript editor window that can be used to enter a scripted behavior script. The editor window is similar to other MaxScript editor window but is slightly customized for scripted behaviors.

The following elements in the File Menu work differently: New: disabled since only one editor per scripted behavior can be open at any time Open: opens a file in the existing editor window. Any existing text will be lost. Evaluate: evaluates the script and saves it into the behaviors paramblock Close: saves into the behaviors paramblock and closes the editor if no errors found

1802

Chapter 21

character studio 3 MAXScript Extensions

Scripted Behavior Syntax: The scripted behavior script is implemented by defining a set of event handlers that get called by the crowd system when solving the simulation. The event handlers are automatically enclosed into a hidden MAXScript context. The name of the context is taken from the dialogs Script Context Name text box or its equivalent .scriptContextName. Event Handlers for Scripted Behaviors:
on execute do <expr>

Called whenever the script is evaluated. All initializing should be done here.
on setupDelegates <delegates> <behavior> do <expr> < delegates> an array of all the delegates after they are ordered participating in the simulation. All delegates listed in the Behavior Assignments pane of the Behavior and Team Assignment dialog are found in this list. < behavior> the current behavior

Called before the simulation starts. Note: All of the delegates are passed in, regardless if they have this behavior assigned, so the behavior knows the max number of delegates that may be used and therefore set up whatever data structures required. Some behaviors need to keep track of parameters on a per delegate basis. This function allows the behavior to set up data structures to get that info. Also that is one of the reasons why the delegate.id is unique, so it can be used to hash or index these data structures. Due to cognitive controllers, you never really know exactly all of the delegates which will be active for a particular behavior.
on display <behavior> <time> do <expr> < behavior> the current behavior < time> current time of the simulation

Called every time the crowd system is redrawn. You can use the low level drawing functions from the gw struct, Viewport Drawing Methods (p. 1592), to have a custom display for the behaviors. Note: This handler gets called a number of times, so the system will slow down if implemented.
on behaviorStarted <delegate> <behavior> <time> do <expr> < delegate> the delegate node the behavior is assigned to < behavior> the current behavior < time> current time of the simulation

Called whenever a behavior becomes active for a particular delegate. This can occur at the beginning of the simulation for an assigned behavior or when a cognitive controller activates the behavior.

Scripted_Behavior : MAXObject

1803

on initAtThisTime <behavior> <time>

This function is called for each behavior at the beginning of the frame.
on applyForce <delegate> <behavior> <time> <numSubSamples> <displayHelpers> <weight> do <expr>

If the behavior type is Force or Orientation, this handler is called every frame to move the delegate.
< delegate> the delegate node the behavior is assigned to < behavior> the current behavior < time> current time of the simulation < numSubSamples> is the number of sub samples required per frame. < displayHelpers> this value is true/false depending on the <Crowd>.update and <Crowd>.updateFrequency, as well as the current frame. If it is true, you should display any helper imagery you want using the display functions available from the delegates structure. For instance, most behaviors display their force if this is true, and pathfollow also displays its target. The delegates.lineDisplay (p. 1773),.sphereDisplay, .bboxDisplay, and .textDisplay are all functions which can be used to draw a graphic primitive for a particular delegate when the crowd simulation is being solved. Please see Viewport Drawing Methods for additional viewport drawing methods.

Note: The graphic window functions gw.* described in Viewport Drawing Methods will not display correctly or at all while in Step Solve.
< weight> this behaviors weight on the delegate

The event handler should return an array of the following type:

#(<int_flags>, <point3_force>, <point3_goal>, <float_speed>, <Speed_Weight_at_the_Goal>) < int_flags> sum of any of the following values: 0 the return value is not used by the crowd system 1 - only force is affected 2 - only goal is affected 4 - only speed is affected

For example, a value of 5, (1+4), indicates that the force and speed are affected.
< point3_force> the force vector (p. 1677) . It should be unit normalized and then multiplied by the delegates average speed. Modify this value, greater or less, to make the force stronger or weaker. < point3_goal> the goal position in world space.

1804

Chapter 21

character studio 3 MAXScript Extensions

< float_speed> the net speed of the delegate. This value should be normalized to the average speed of the delegate. A value of 1.0 means go at the average speed. <Speed_Weight_at_the_Goal> will represent the speed that the delegate should be at when it reaches its goal. This value should be normalized by the average speed of the delegate, so that a value of 1.0 equal its average speed.

Notes: Any behavior that sets the <int_flags> with a speed affected setting should ensure that a valid value is set for <float_speed> and <Speed_Weight_at_the_Goal>. Note that a goal doesnt need to be set for this to work. This is how the SpeedVary behavior works with Biped. It doesnt explicitly set a goal but still modifies the <Speed_Weight_at_the_Goal> value.
on constraint <delegate> <behavior> <time> <numSubSamples> <displayHelpers> <finalSet> <velocity> <speed> <pos> do <expr>

If the behavior type, <Scripted_Behavior>.type, is Constraint, this handler is called at least once every frame to constrain the delegate. The constraint behavior will override any other force behavior, the Avoidance Behavior, plus it will override any acceleration limits, speed limits etc. So it should be used with caution in a simulation. The constraint behavior constrains the position that the delegate is moving towards by changing the current position that the delegate is already at, its current velocity, and its current speed. These values are combined to get the next position, Next_position = Current_Position +Normalized(vel) * Speed. Changing the current position doesnt actually change where it is at though, it just changes the position that is used to calculate its new position. This design allows the constraint to make the objects velocity change abruptly and keep its speed, thus conserving the energy of the delegate.
< delegate> the delegate node the behavior is assigned to < behavior> the current behavior < time> current time of the simulation < numSubSamples> is the number of sub samples required per frame. < displayHelpers> this value is true/false depending on the <Crowd>.update and <Crowd>.updateFrequency, as well as the current frame. If it is true, you should display any helper imagery you want using the display functions available from the delegate. For instance, most behaviors display their force if this is true, and pathfollow also displays its target. The delegates (p. 1773) .lineDisplay, .sphereDisplay, .bboxDisplay, and .textDisplay are all functions which can be used to draw a graphic primitive for a particular delegate when the crowd simulation is being solved. Please see Viewport Drawing Methods for additional viewport drawing methods. < finalSet> whether or not this is the final time this behavior will be called during the current frame.

Scripted_Behavior : MAXObject

1805

Note: In order to handle constraints working correctly within the avoidance system the constraint behavior may be called more than once per frame. When the passed in parameter, finalSet, is true, it will be the last time the constraint function is called for that frame. Currently the constraint behaviors on constraint event handler is called twice per frame. The first call occurs before an existing Avoid_Behavior with the passed in parameter finalSet having a value of false. The second call occurs, after the delegates limits and Avoid_Behavior are applied with the passed in parameter finalSet having a value of true. This evaluation order is done so that the delegates limits and the Avoid_Behavior can affect the changes that the constraint performs. The second call is made to make sure that the constraint is still being met. One reason to check the state of finalSet is if internally something was cached and you didnt want it to change. For example, the Surface_Follow constraint behavior keeps track of which triangle its on and the barycentric coordinates of where its at. The simulation will not change these values until finalSet is true.
< velocity> the current velocity of the delegate at this frame. < speed> the current speed of the delegate at this frame. < pos> the current position of the delegate at this frame.

Note: After the last delegates on constraint has executed for the last frame of the simulation, on setupDelegates delegates behavior do will be called with an empty array #() ReferenceTarget:Scripted_Behavior. This is guarenteed and can be used by written constraint behaviors to clear out any internal caches. The event handler should return an array of the following type:
#(<int_flags>, <point3_velocity>, <point3_pos>, <point3_goal>, <float_speed>) < int_flags> sum of any of the following values: 0 the return value is not used by the crowd system 1 the return value is used by the crowd system < point3_velocity> the velocity. < point3_pos> the modified current position that is used to calculate its new position. In order to meet a constraint this behavior is allowed to modify the current position of a delegate. < point3_goal> the goal position in world space. < float_speed> the net speed of the delegate. This value should be normalized to the average speed of the delegate. on orient <delegate> <behavior> <time> <velocity> do <expr>

1806

Chapter 21

character studio 3 MAXScript Extensions

If the behavior type, <Scripted_Behavior>.type, is Orientation, this handler is called every frame. This handler is always called in conjunction with the applyForce handler.
< delegate> the < behavior> the < time> current < velocity> the delegate node the behavior is assigned to current behavior time of the simulation current velocity of the delegate at this frame.

The event handler should return an array of the following type:

#(<int_flags>, quat_orientation) < int_flags> sum of any of the following values: 0 the return value is not used by the crowd system 1 the return value is used by the crowd system < quat_orientation> the orientation of the delegate in quaternions.

Notes: The purpose of passing the crowd delegate and behavior to all of the event handlers is that you can call persisted global, saved with scene, MAXScript functions that work for more than one crowd simulation. Example: The following is a pair of scripted behaviors called FormationConstraint and FormationOrientation. The FormationOrientation will constrain the orientation to a fixed location, in this case based on the current delegates orientation found at its first rotation keyframe. The entire scripted orientation behavior can be implemented with one event handler:
on orient delegate behavior time vel do ( #(1,delegate.rotation.keys[1].value as quat ) )

The FormationConstraint keeps a team of delegates in a given positional formation while maintaining the pace and direction of a designated leader named FormationLeader. This is similar to a drum major and a marching band or like football blockers running in front of a running back who may dart in any direction. This person dictates how and where the formation will move. This FormationLeader is not using the scripted behavior. This behavior will affect both the position and orientation of the delegate. The orientation is being calculated by the delegates velocity, and the velocity is being set correctly.
on execute do ( print executed ) on constraint delegate behavior time numsubsamples displayHelpers finalSet vel speed pos do ( leader_velocity = delegates.velocity $TheFormationLeader Normalized_Leader_Velocity = normalize (delegates.velocity $TheFormationLeader)

Seek_Behavior : MAXObject

1807

magVel = speed* Normalized_Leader_Velocity temp_dis = (pos + leader_velocity) magVel the_goal = temp_dis + magVel if displayHelpers == true then ( delegates.textDisplay delegate the_goal delegate.wirecolor delegate.name delegates.lineDisplay delegate pos (pos+leader_velocity) delegate.wirecolor true delegates.sphereDisplay delegate (pos+ (leader_velocity * $Crowd01.vectorScale)) 4 delegate.wirecolor ) #(1, Normalized_Leader_Velocity, temp_dis, the_goal, speed) )

See Also
Delegate:Helper (p. 1773) Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) value_common_properties_operators_and_methods

Seek_Behavior : MAXObject
Constructor:
Seek_Behavior ... SeekBehavior ...

Properties:
<seek_behavior>.name <seek_behavior>.targets String Default: Seek -node array

ArrayParameter Default: #()

See Notes below. Specify the object or objects as a stationary or moving target for delegates. Delegates move toward the target during the crowd simulation while turning as necessary.
<seek_behavior>.targetComp Integer Default: 0

0 Closest Source Only: Each delegate seeks the closest of the assigned targets. Use this to have delegates assigned a single Seek behavior move in different directions. 1 Average of Sources: All delegates head to a common point determined by averaging all targets locations.

1808

Chapter 21

character studio 3 MAXScript Extensions

<seek_behavior>.seekMethod

Integer

Default: 0

--

animatable

0 Angle: Applies a force to the delegate based on the angle between the delegates current direction and the direction it would need to take in order to be moving directly towards the goal. If the Weight of the Seek behavior is 1, the delegate will be given a force that points directly towards the goal. If its .5 it will bisect the angle between its current direction and the direction of the goal. 1 Force: Applies a force in the direction of the goal always, but at different magnitudes. If the Weight of the Seek behavior is 1, the magnitude of the force will be the average speed. If the Weight of the Seek behavior is .5, the magnitude of the force will be half the average speed.
<seek_behavior>.forceColor <seek_behavior>.displayForce Color Boolean Default: (color 0 255 0) Default: True

The color used to draw the Seek force vector during the solution. When true, force exerted on the delegate(s) by the Seek behavior is drawn in the viewports as a vector during the simulation solution.
<Seek_Behavior>.useRadii Boolean Default: False

When true, the Seek behavior applies only to delegates less than the Outer Radius distance from the target.
<Seek_Behavior>.showRadii <Seek_Behavior>.innerRadius <Seek_Behavior>.outerRadius <Seek_Behavior>.falloff Boolean Float Float Float Default: True Default: 0.0 Default: 10.0 Default: 2.0 ---animatable animatable animatable

When true, the radii are displayed when the force is active. The distance from the target at which Seek is applied at full strength. The distance from the target at which Seek begins to be applied.

Notes: You can perform the following MAXScript operations:

deleteitem <array> <itemnumber> <array> = #(item,item...) <array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.
<Seek_Behavior>.targets

The following MAXScript operations will cause Crowd to fail, either right away or later: NEVER set a Crowd/Behavior ArrayParameter element to undefined.

Space_Warp_Behavior: MAXObject

1809

See Also
Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Space_Warp_Behavior: MAXObject
Constructor:
Space_Warp_Behavior ... WSMBehavior ...

Properties:
<space_warp_behavior>.name <space_warp_behavior>.spaceWarp <space_warp_behavior>.forceColor <space_warp_behavior>.displayForce String Node Color Boolean Default: Space Warp Default: Undefined Default: (color 255 255 0) Default: True

The color used to draw the Space Warp force vector during the solution. When true, force exerted on the delegate(s) by the Space Warp behavior is drawn in the viewports as a vector during the simulation solution.

See also
Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Speed_Vary_Behavior : MAXObject
Constructor:
Speed_Vary_Behavior ... SpeedVaryBehavior ...

Properties:
<speed_vary_behavior>.name <speed_vary_behavior>.period String Integer Default: Speed Vary Default: 10 -animatable

Specifies how many frames should elapse before a new speed is chosen.

1810

Chapter 21

character studio 3 MAXScript Extensions

<speed_vary_behavior>.period_deviation Float Alias: Period_Deviation

Default: 0.5

--

animatable;

Specifies the maximum amount by which Period should vary. Each time a period ends, character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the Period setting, and adds the result to Period. Range=0.0 to 1.0.
<speed_vary_behavior>.center_speed Alias: Center_Speed Float Default: 1.0 -animatable;

Specifies the speed the delegate should change to. Center is a multiplier: A value of 0.0 means to stop, a value of 1.0 means to move at its average speed, and a value greater than 1.0 means to move faster than its average speed. Range=0.0 to 99,999.0.
<speed_vary_behavior>.speed_deviation Alias: Speed_Deviation Float Default: 0.25 -animatable;

Specifies the maximum amount by which the delegates calculated speed (Average Speed*Center) should vary. Each time a period ends, character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the calculated speed, and adds the result to the calculated speed. Range=0.0 to 99,999.0.
<speed_vary_behavior>.seed Alias: Speed_Vary_Seed <speed_vary_behavior>.accelPeriod Alias: Acceleration_Period Integer Default: 1 -animatable;

Specifies a seed value for randomizing the Wander behavior.

Float Default: 0.5 -animatable;

Specifies the rate at which the delegates speed should change. An acceleration of 1.0 means that the transition to the new speed will proceed as quickly as possible to its new speed, while a value of 0.0 means the transition will take the entire period. Range=0.0 to 1.0.
<speed_vary_behavior>.accelDeviation Alias: Acceleration_Deviation Float Default: 0.5 -animatable;

Specifies the maximum amount by which the delegates calculated speed (Average Speed*Center) should vary. Each time a period ends, character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the calculated speed, and adds the result to the calculated speed. Range=0.0 to 99,999.0.

See also
Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Surface_Arrive_Behavior : MAXObject

1811

Surface_Arrive_Behavior : MAXObject
Constructor:
Surface_Arrive_Behavior ... SurfaceArriveBehavior ...

Properties:
<Surface_Arrive_Behavior>.name <Surface_Arrive_Behavior>.surfaces array String Default: Surface Arrive -- node

ArrayParameter Default: #()

See Notes below

<Surface_Arrive_Behavior>.disableAfterArriving Boolean Default: True

When true, turns off the Surface Arrive behavior after the delegate arrives at the surface.
<Surface_Arrive_Behavior>.rate animatable Float Default: 0.5 --

A multiple of the delegates Max Accel setting that specifies the acceleration with which it will try to arrive. A value of 1.0 uses the full acceleration of the delegate.
<Surface_Arrive_Behavior>.rateDeviation animatable Float Default: 0.0 --

Adds a variation to the to the rate setting.

<Surface_Arrive_Behavior>.speed animatable <Surface_Arrive_Behavior>.speedDeviation animatable Float Default: 0.0 --

The speed at which to arrive and relative to the speed of the target.
Float Default: 0.0 --

Adds a variation to the to the speed setting.

<Surface_Arrive_Behavior>.distance animatable Float Default: 1e+008 --

The maximum radial distance from the target within which the behavior will be active. Until the delegate is within this radius, the behavior will have no influence.
<Surface_Arrive_Behavior>.distanceDeviation animatable Float Default: 0.0 --

Adds a variation to the to the distance setting.

<Surface_Arrive_Behavior>.offset animatable Float Default: 0.0 --

Specifies a consistent distance from the calculated arrival point, based on the surface normal, for the delegate to use.
<Surface_Arrive_Behavior>.facing animatable Boolean Default: False --

When true, the delegate will try to arrive only at points on triangles on the surface that are facing it.

1812

Chapter 21

character studio 3 MAXScript Extensions

<Surface_Arrive_Behavior>.random_closest

Integer Default: 0

0 Random: The software chooses a random point on the target surface as the arrival point. 1 Closest: The software chooses the closest point on the target surface as the arrival point.
<Surface_Arrive_Behavior>.everyFrame animatable Boolean Default: False --

When true, the software chooses arrival points for delegates at every frame. Available only when Closest is chosen.
<Surface_Arrive_Behavior>.displayOffset Boolean Default: False

When true, shows the Offset distance as lines emanating from each vertex in the surface object, perpendicular to the surface.
<Surface_Arrive_Behavior>.height animatable Float Default: 0.0 --

Specifies a distance from the arrival point along its face normal. This is the point that the delegate will go to first before descending to the arrival point.
<Surface_Arrive_Behavior>.heightDeviation animatable Float Default: 0.0 --

Adds random variation to the to the Height setting. See introduction for the formula used to calculate the deviation.
<Surface_Arrive_Behavior>.descentStart animatable Float Default: 0.0 --

Specifies the distance between the delegate and the arrival point at which the descent should start. Note: Be careful that Descent Start is set high enough that the delegate wont overshoot when descending because its speed is too high and deceleration too low, compared to when it should start descending.
<Surface_Arrive_Behavior>.descentstartDeviation Float animatable Default: 0.0 --

Adds a variation to the to the Descent Start setting.

<Surface_Arrive_Behavior>.useNormal Off_This_Normal Boolean Default: False Alias:

When true, use vector specified in the .xNormal, .yNormal, and .zNormal to specify the angle at which the final approach occurs.
<Surface_Arrive_Behavior>.xNormal animatable; Alias: X_Normal <Surface_Arrive_Behavior>.yNormal animatable; Alias: Y_Normal <Surface_Arrive_Behavior>.zNormal animatable; Alias: Z_Normal Float Default: 0.0 --

Specify the final approach X value for the vector in world coordinates.
Float Default: 0.0 --

Specify the final approach Y value for the vector in world coordinates.
Float Default: 1.0 --

Specify the final approach Z value for the vector in world coordinates.

Surface_Arrive_Behavior : MAXObject

1813

<Surface_Arrive_Behavior>.seed animatable <Surface_Arrive_Behavior>.targetColor

Integer

Default: 1

--

Affects the random numbers used to calculate the Deviation settings.

Color Boolean Default: (color 0 0 127.5) Default: True

The color used to draw the target icon.

<Surface_Arrive_Behavior>.displayTarget

When true, displays the target icon which appears during the solution when a new interim goal is calculated for the delegate.
<Surface_Arrive_Behavior>.targetScale animatable Float Default: 5.0 --

Specifies the overall size of the target icon. Methods:

SurfaceArriveBhvr.Getstate <Surface_Arrive_Behavior> <delegate_node>

Returns an integer value giving the state the delegate is in with respect to the Surface_Arrive_Behavior. A return value of -1 means that the delegate isnt active for that state, 0 means that the delegate is outside the distance radius and so isnt arriving, 1 means that the delegate is in the process of arriving, and 2 means that the delegate has arrived. If Disable After Arriving is TRUE, the delegates will never reach state 2. The main purpose of this funtion is so that the State of a delegate as it arrives to a surface can be determined from MAXScript. It can be used for both the cognitive controller transitions as well as the script definable in MotionClips. See the ClipState Dialog and the Cognitive Controller topics in the character studio 3 online reference for more details.
Track View > Global Tracks > Block Control > GlobalClip Properties > Synthesis dialog > State Tab > New State > Edit Properties > ClipState dialog Select a Crowd helper. > Modify panel > Global Clip Controllers rollout > New > Choose GlobalClip object. > Select object in list. > Edit > Synthesis dialog > State Tab > New State > Edit Properties > Clip State dialog Create panel > Helpers > Object Type rollout > Crowd > Setup rollout > Cognitive Controllers Select a Crowd object. > Modify panel > Setup rollout > Cognitive Controllers SurfaceArriveBhvr.getPos <Surface_Arrive_Behavior> <delegate_node>

Returns a Point3 value of the position that the delegate is arriving to at the time the function is called.

1814

Chapter 21

character studio 3 MAXScript Extensions

Notes: You can perform the following MAXScript operations:

deleteitem <array> <itemnumber> <array> = #(item,item...) <array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.
<Surface_Arrive_Behavior>.surfaces

The following MAXScript operations will cause Crowd to fail, either right away or later: NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See Also
Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Surface_Follow_Behavior : MAXObject
Constructor:
Surface_Follow_Behavior ... SurfaceFollowBehavior ...

Properties:
<Surface_Follow_Behavior>.name <Surface_Follow_Behavior>.surfaces String Default: Surface Follow -node array

ArrayParameter Default: #() Default: False

See Notes below.

<Surface_Follow_Behavior>.useProjection Bolean

When true, Surface Follow calculates delegate direction from the specified vector, rather than using the default.
<Surface_Follow_Behavior>.xVector <Surface_Follow_Behavior>.yVector <Surface_Follow_Behavior>.zVector <space_warp_behavior>.targetColor <space_warp_behavior>.displayTarget Float Float Float Color Boolean Default: 0.0 Default: 0.0 Default: 1.0 ---animatable animatable animatable

Specifies the x component of a vector using world coordinates. . Range=-1.0 to 1.0. Specifies the y component of a vector using world coordinates. . Range=-1.0 to 1.0. Specifies the z component of a vector using world coordinates. . Range=-1.0 to 1.0.
Default: (color 0 0 127.5) Default: True

Sets the color used to draw the Surface Follow during the solution. When true, the interim goal for each delegate influenced by the Surface Follow behavior is drawn in the viewports as a wireframe sphere during the simulation solution.

Surface_Follow_Behavior : MAXObject

1815

Notes: If the delegate starts out away from the surface to be followed then the target is most visible before the delegate reaches the surface where the target is positioned along the surface edge. While the delegate is actually following the surface, the target is usually coincident with the delegate because Surface follow sets a new destination only a frame or two ahead.
<space_warp_behavior>.targetScale <Surface_Follow_Behavior>.offset Float Float Default: 5.0 Default: 0.0 -- animatable

Specifies the overall size of the target icon. Specifies the delegates distance above the surface, using the surface normal.
<Surface_Follow_Behavior>.displayOffset Boolean Default: False When true, shows the .offset distance as lines emanating from each vertex in the surface

object, perpendicular to the surface. Notes: You can perform the following MAXScript operations:
deleteitem <array> <itemnumber> <array> = #(item,item...) <array> = append <array> <item>

on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations.
<Surface_Follow_Behavior>.surfaces

The following MAXScript operations will cause Crowd to fail, either right away or later: NEVER set a Crowd/Behavior ArrayParameter element to undefined.

See also
Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

1816

Chapter 21

character studio 3 MAXScript Extensions

Wall_Repel_Behavior : MAXObject
Constructor:
Wall_Repel_Behavior ... WallRepelBehavior ...

Properties:
<Wall_Repel_Behavior>.name String <Wall_Repel_Behavior>.repelGrids ArrayParameter Default: Wall Repel Default: #() -- node array Default: 0 -- animatable

Set the repelling grid.

<Wall_Repel_Behavior>.repelMethod Integer

Determines whether delegate direction as influenced by the behavior is calculated by an angular method or a force method. 0 Angle: Applies a force to the delegate based on the angle between the delegates current direction and the direction it would need to take in order to be moving directly away from the source. If the behaviors Weight is set to 1 the delegate will be given a force that points directly away from the source. If Weight is set to .5, the force will bisect the angle between its current direction and the direction opposite that of the source. 1 Force: Always applies a force directly away from the source, but at different magnitudes. If the behaviors Weight is 1, the magnitude of the force will be the average speed. If the Weight is .5, the magnitude of the force will be half the average speed.
<Wall_Repel_Behavior>.repelDirection Integer Default: 0 -- animatable

Determines whether the grid repels from its positive-axis side, its negative-axis side, or both. 0 Positive Axis: The grid repels only from the positive-axis side. 1 Negative Axis: The grid repels only from the negative-axis side. 2 Both Axes: The grid repels from both sides.
<Wall_Repel_Behavior>.useDistance Boolean Default: True

When true, the behavior applies only to delegates closer to the target than the outerRadius value.
<Wall_Repel_Behavior>.innerDistance <Wall_Repel_Behavior>.outerDistance <Wall_Repel_Behavior>.falloff <Wall_Repel_Behavior>.showDistance Float Float Float Boolean Default: 0.0 Default: 10.0 Default: 2.0 Default: True -- animatable -- animatable -- animatable

The distance from the target at which the force is applied at full strength. The distance from the target at which the force begins to be applied.

Shows the inner and outer distance settings as grids offset from the target grid in the viewports. The .innerDistance grid is light blue, while .outerDistance grid is blue-white.

Wall_Seek_Behavior : MAXObject

1817

<Wall_Repel_Behavior>.gridSpacing

Integer

Default: 500

Specifies the spacing of grid lines used to draw the Inner/Outer Distance grids. The lower the value, the closer the spacing.
<Wall_Repel_Behavior>.gridEnd End_force_at_grid_edges Boolean Default: True Alias:

When true, the force emanates only from the grid object. When off, the force emanates from an imaginary infinite grid created by extending the grid plane in all directions.
<Wall_Repel_Behavior>.forceColor <Wall_Repel_Behavior>.displayForce Color Boolean Default: (color 255 0 255) Default: True

Sets the color used to draw the Wall Repel force during the solution. The force, when activated, is drawn in the viewports as a wireframe rectangle during the simulation solution.

See also
Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Wall_Seek_Behavior : MAXObject
Constructor:
Wall_Seek_Behavior ... WallSeekBehavior ...

Properties:
<Wall_Seek_Behavior>.name <Wall_Seek_Behavior>.seekGrids String ArrayParameter Integer Default: Wall Seek Default: #() Default: 0 -node array

Set the repelling grid.

<Wall_Seek_Behavior>.seekMethod -- animatable

Determines whether delegate direction as influenced by the behavior is calculated by an angular method or a force method. 0 Angle: Applies a force to the delegate based on the angle between the delegates current direction and the direction it would need to take in order to be moving directly toward the target. If the behaviors Weight is set to 1, the delegate will be given a force that points directly away from the target. If Weight is set to .5, the force will bisect the angle between its current direction and the direction opposite that of the target. 1 Force: Always applies a force directly toward the target. If the behaviors Weight is 1, the magnitude of the force will be the average speed. If the Weight is .5, the magnitude of the force will be half the average speed.

1818

Chapter 21

character studio 3 MAXScript Extensions

<Wall_Seek_Behavior>.seekDirection

Integer

Default: 0

-- animatable

Determines whether the grid attracts from its positive-axis side, its negative-axis side, or both. 0 Positive Axis: The grid attracts only from the positive-axis side. 1 Negative Axis: The grid attracts only from the negative-axis side. 2 Both Axes: The grid attracts from both sides.
<Wall_Seek_Behavior>.useDistance Boolean Default: True

When true, the behavior applies only to delegates closer to the target than the Outer Distance value.
<Wall_Seek_Behavior>.innerDistance <Wall_Seek_Behavior>.outerDistance <Wall_Seek_Behavior>.falloff <Wall_Seek_Behavior>.showDistance <Wall_Seek_Behavior>.gridSpacing <Wall_Seek_Behavior>.gridEnd End_force_at_grid_edges Float Float Float Boolean Integer Boolean Default: 0.0 Default: 10.0 Default: 2.0 Default: True Default: 500 Default: True Alias: -- animatable -- animatable -- animatable

The distance from the target at which the force is applied at full strength. The distance from the target at which the force begins to be applied.

When true, the force emanates only from the grid object. When off, the force emanates from an imaginary infinite grid created by extending the grid plane in all directions.
<Wall_Seek_Behavior>.forceColor <Wall_Seek_Behavior>.displayForce Color Boolean Default: (color 255 0 255) Default: True

Sets the color used to draw the Seek force vector during the solution. When true, force exerted on the delegate(s) by the Seek behavior is drawn in the viewports as a vector during the simulation solution. If useRadii is turned on, the radii are also displayed when the force is active.

See also
Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

Wander_Behavior : MAXObject

1819

Wander_Behavior : MAXObject
Constructor:
Wander_Behavior ... WanderBehavior ...

Properties:
<wander_behavior>.name <wander_behavior>.period Alias: Wander_Period <wander_behavior>.periodDeviation Alias: Wander_Period_Deviation String Integer Default: Wander Default: 10 -animatable;

Specifies how many frames should elapse before a new direction is chosen.
Float Default: 0.5 -animatable;

Specifies the maximum amount by which Period should vary. Each time a period ends, character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the Period setting, and adds the result to Period. Range=0.0 to 1.0.
<wander_behavior>.turnAngle Float Default: 0.5 -animatable

Specifies how far to turn when changing direction. A small value means to change direction only by a small amount, while as the value approaches 1.0 it will randomly turn in any direction. Range=0.5 to 1.0.
<wander_behavior>.turnPeriod Float Default: 0.5 -animatable

Specifies how long over the current period it takes to turn. A value of 0.0 means that it will rotate as quickly as possible to face a direction and then travel in that a direction, while a value of 1.0 means it will take the entire period to rotate in that direction. Range=0.5 to 1.0.
<wander_behavior>.turnPeriodDeviation Float Default: 0.5 -animatable

Specifies the maximum amount by which Angle should vary. Each time a period ends, character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the Angle setting, and adds the result to Angle. Range=0.0 to 1.0.
<wander_behavior>.seed <wander_behavior>.forceColor <wander_behavior>.displayForce Integer Color Boolean Default: 1 -animatable

Specifies a seed value for randomizing the Wander behavior.

Default: (color 0 255 255) Default: True

The color used to draw the Wander force vector during the solution. When true, force exerted on the delegate(s) by the Wander behavior is drawn in the viewports as a vector during the simulation solution.

1820

Chapter 21

character studio 3 MAXScript Extensions

See Also
Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)

MotionClips and GlobalMotionClip

globalMotionClipOps globalMotionClipOps( globalMotionClipOps.loadfile const StructDef Struct: Primitive loadfile()

loadfile expects a GlobalMotionClip, then a filename for a *.ant GlobalMotionClip file to load.
globalMotionClipOps.savefile globalMotionClipOps.synthesize Primitive Primitive savefile() synthesize()

savefile expects a GlobalMotionClip, then a filename for the *.ant file to save. synthesize expects a GlobalMotionClip and will synthesize it. Note that the GlobalMotionClip objects are found under the GlobalTracks.Block_Control list controller. So to call savefile, one would call:
GlobalMotionClipOps.savefile GlobalTracks.Block_Control.globalMotionClip__globalObject globalObject.ant

The following classes exist but are not supported.

MotionClipSlaveRotation : RotationController {4306d06,97c6025} MotionClip : FloatController {e937ded,5a002ad2} MotionClipSlavePos : PositionController {18c22740,522802b9} ClipAssignerReferenceTarget : ReferenceTarget {2cb93ce2,33825f4} MotionClipSlaveFloat : FloatController {31822cdf,34c146b} Global_MotionClip : MasterBlockController {37d25755,278c6957} ClipState : ReferenceTarget {455d5a81,3dcb1dc2} ClipAssigner : ReferenceTarget {49f14ffa,33801afd} MasterMotionClip : MasterBlockController {532a2038,6acd39bf} MotionClipSlave_Point3 : Point3Controller {6c95514a,801b4f} MotionClipSlaveScale : ScaleController {71031345,770b4347} MotionClipFloatController : FloatController {7f016988,1f9f0342}

Vector_Field: SpacewarpObject

1821

SpaceWarps
Vector_Field: SpacewarpObject
Constructor:
Vector_Field ... VectorField ...

Properties:
<Vector_Field>.Length Float Default: 0.0 -- world units

Specify the length dimension of the vector field lattice. The lattice should be larger than the vector field object.
<Vector_Field>.Width Float Default: 0.0 -- world units

Specify the width dimension of the vector field lattice. The lattice should be larger than the vector field object.
<Vector_Field>.Height Float Default: 0.0 -- world units

Specify the height dimension of the vector field lattice. The lattice should be larger than the vector field object.
<Vector_Field>.LenSegs Length_Segments Integer Default: 1 Alias:

Specify the resolution of the vector field lattices length segments. The greater the resolution, the higher the accuracy of the simulation.
<Vector_Field>.WidSegs Width_Segments Integer Default: 1 Alias:

Specify the resolution of the vector field lattices width segments. The greater the resolution, the higher the accuracy of the simulation.
<Vector_Field>.HgtSegs Height_Segments Integer Default: 1 Alias:

Specify the resolution of the vector field lattices height segments. The greater the resolution, the higher the accuracy of the simulation.
<Vector_Field>.showLattice Boolean Default: True

Set on to display the vector field lattice as a yellow wireframe box. The vectors are generated at lattice intersections inside the vector field range.
<Vector_Field>.showRange Boolean Default: True

Set on to display the volume about the obstacle object within which vectors are generated as an olive-colored wireframe.
<Vector_Field>.showVectors Boolean Default: False

Set on to display vectors, which appear as blue lines emanating outward from the lattice intersections within the range volume.
<Vector_Field>.showSurfSamps Boolean Default: False

Set on to display short green lines emanating from sample points on the surface of the obstacle object.

1822

Chapter 21

character studio 3 MAXScript Extensions

<Vector_Field>.vecScale

Float

Default: 1.0

-- world units

Scales the vectors so theyre more visible or less obtrusive. This setting does not affect the strength of the vectors only their visibility.
<Vector_Field>.iconSize Float Default: 0.0 -- world units

Adjusts the size of the Vector Field space warp icon. The icon is a pair of crossed doubleheaded arrows. Increase the size for easier viewport selection.
<Vector_Field>.strength world units Float Default: 1.0 -- animatable;

Sets the degree of effect the vectors have on the movement of an object entering the vector field. Changing Strength does not require that you recalculate the vector field.
<Vector_Field>.falloff animatable; world units Float Default: 2.0 --

Determines the rate at which the strength of the vectors falls off with distance from the surface of the object. A value of 0 will make all the vectors the same size. A value greater than 0 will make them get smaller as they get further away. A value less then 0 will make them get larger as they get further away.
<Vector_Field>.direction Integer Default: 1 -- animatabl

Sets whether the force generated by the vectors works parallel or perpendicular to the vector field. Because the vectors are perpendicular to the object surface, and you typically would want delegates to travel parallel to the surface, you would normally use a perpendicular force. 0 Parallel 1 Perpendicular
<Vector_Field>.pull animatable; world units Float Default: 0.0 --

Adjusts objects position relative to the field. Available only when Perpendicular is chosen. Range=-1.0 to 1.0. Objects moving perpendicular to a vector field sometimes tend to drift away from it, due to lack of subsampling. The Pull parameter helps to pull objects back. Pull values greater than 0 create a pulling force towards the source of the vector field vector. Values less than 0 pull the force towards the direction in which the vector fields vector is pointing. A value of 0.0 produces a force perfectly perpendicular to the vector fields vector.
<Vector_Field>.object Vector_Field_Object Node Default: Undefined Alias:

The obstacle object around which the vector field is to be generated. Only primitives and unmodified editable mesh objects can be used as obstacles. The object should be fully enclosed in the Vector Field lattice.
<Vector_Field>.range Float Default: 1.0 -- world units

Determines the volume within which vectors are generated. The Range is represented in viewports as an olive-colored wireframe that starts out the same size and shape as the obstacle object. Increasing the Range setting moves the wireframe away from the obstacle object in the direction of its surface normals.

Vector_Field: SpacewarpObject

1823

Notes: In crowd simulations, the Range outline is where the delegates start to see the obstacle object, and begin to turn to avoid it. If your crowd members are penetrating the obstacle, or even just coming too close to it before turning, increase the Range setting. Also try increasing the Vector Field lattice resolution and/or the Sample Res setting.
<Vector_Field>.resolution Integer Default: 1

Acts as a multiplier of the effective sampling rate used on the obstacle objects surface to calculate vector directions in the field. The basic sampling rate is determined by the program from the size of the lattice and the size of each polygon.
<Vector_Field>.flipFaces Boolean Default: False

Setting to true causes flipped normals to be used during the computation of the vector field. By default, vectors are generated in the same direction as the obstacle objects face normals, so that assuming its face normals point outward, objects move around its exterior in a crowd simulation. However, if you want objects to remain within an objects interior, turn on flipFaces.
<Vector_Field>.blendStart <Vector_Field>.blendFalloff <Vector_Field>.blendWidSegs <Vector_Field>.blendLenSegs <Vector_Field>.blendHgtSegs Float Float Integer Integer Integer Default: 0.0 Default: 2.0 Default: 1 Default: 1 Default: 1 -- world units -- world units

The distance from the object at which blending the vectors starts. The falloff of the blend of the surrounding vectors. The number of adjacent lattice points to blend on the X axis. The number of adjacent lattice points to blend on the Y axis. The number of adjacent lattice points to blend on the Z axis. Methods:
vfields.computeVectors <Vector_Field>

Calculates the vector field using the current Vector Field parameters. Always recalculate the vector field after changing any of the non-display related parameters.
vfields.BlendVectors <Vector_Field>

Blends the vectors for reducing abrupt changes in angles of neighboring vectors. Associated Methods:
bindSpaceWarp <node> <Vector_Field_node>

Associated Binding Modifier:

Vector_Field_Mod

This modifier is automatically created by the bindSpaceWarp() (p. 820)method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.

1824

Chapter 21

character studio 3 MAXScript Extensions

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

Chapter 22:

CS3Tools.cui Tutorial

The CS3Tools Custom User Interface implements several very useful tools. This tutorial will concentrate on the Custom Keys Utility, a custom keys mechanism that gives one-touch access to 6 key frame settings that you use most when animating a Biped. The Custom Keys Utility uses 13 icon buttons. The first 6 are Set custom Biped Keys. The next 6 are Change Preset to current key. The following one is Launch Preset Floater. Once you have stored your favorite custom keys, animation workflow is greatly improved, since you spend little or no time tuning default key frame attributes that dont fit your current characters situation or style. Simply pose your character and click on the custom key icon that fits your current situation.

Overview
Custom Keys are implemented via a new dedicated 3ds max Tool Bar, called character studio Tool. This tool bar is the home base for a growing number of MAXScript-enabled character studio commands. All operations associated with Tool Bars are available. For example, individual icons can be relocated, deleted, and renamed. Tool tips can also be customized, as implied above, to let you annotate each custom key type for rapid recall. Custom Keys are displayed on the character studio Tool Bar as color-coded set key icons, similar to the standard Biped red set key icon in the Biped Motion panel. Each color indicates a specific custom key type. There are two icons for each key type one for setting a key, and second for storing the preset value, based on the currently selected track and key. The second icon used for storing the preset values displays a small black arrow pointing to the center of the icon indicating that a value will be stored. Once you have set your keys as you like them, you may choose to delete the storage icons entirely, to save space. You can also float or re-dock the Custom Key icons to customize access to suit your style and needs. Additionally, you can launch a floating rollout of the same set of custom keys. To use Custom Keys, simply set a Biped key as you normally would using the Biped Motion Panel and set its Key Info settings as you prefer. Next store that key for the currently selected track at the current frame into one of the six preset custom key icons using the set key icons with the black arrows.

1826

Chapter 22

CS3Tools.cui Tutorial

Launching the CS3CustomKeys User Interface

The file named CS3Tools.cui is found in the 3ds max UI directory. Choose Customize -> Load Custom UI-> CS3Tools.cui The user interface is displayed on the left side of the screen made with bitmapped buttons icons. You can also build a Tab Panel from scratch and manually add these icons by selecting from the character studio Tool category of the Customize UI Dialog. See help page Macro Scripts (p. 1624) in the Interacting with the 3ds max User Interface topic and Defining Macro Scripts (p. 1521) in the Creating MAXScript Tools topic for additional details regarding Macro Scripts.

1827

The icon buttons of CS3Tools.cui are displayed in the above image. The bitmaps for the custom ui are installed into the 3ds max UI directory. See the Creating Icon Bitmap Files (p. 1530) topic for more information on creating and customizing icon bitmaps. For access to Custom User Interface (CUI) files via MAXScript, see the help page Custom User Interface Files (p. 1648) in the File Access. Note that the *.cui file format specification is not currently provided.

File Details
character studio 3 ships with the following character studio Tool files: ..\ui\CS3Tools.cui ..\Scripts\Startup\CS3Customkeys.ms ..\Scripts\Startup\CS3CustomKeys-presets.ini ..\Scripts\Startup\CS3convertBips.ms ..\Scripts\Startup\CS3Bip2BonesFloater.ms ..\Stdplugs\stdscripts\CS3CustomKeysPresetFloater.ms Tutorial_Filename_CS3CustomKeysPresetFloater_ms bitmap files: \3ds3.1\Cstudio\ui\Cstudio_16a.bmp, Cstudio_16i.bmp, Cstudio_24a.bmp, and Cstudio_24i.bmp.

Design Details
Custom Keys operate similar to channel buttons on a car radio. Anytime you dial in a set of parameters for a particular Biped key using the standard Biped Key Info rollout, you can store those values in one of the 6 custom key buttons available, by clicking on the associated tool bar icon. All of the standard Biped Key Info parameters are supported, including: ease to, ease from, tension, continuity, bias, IK Blend value, IK body/space setting, and pivot point information. This can be seen by reviewing the struct Biped_key defined in ..\Scripts\Startup\CS3Customkeys.ms. Custom Keys do not store transformation information (like a pose). Only Key Info attributes that affect the interpolation of a Bipeds motion are stored. This allows stylistic settings to be easily transferred from frame to frame and even from Biped to Biped. Each Custom Key is stored in a structure (p. 707) with the name Biped_key. Here is the definition of Biped_key:
struct Biped_key (type, ikblend, ikspace, easefrom, easeto, tension, continuity, bias, ikAnkleTension, balanceFactor, dynamicsBlend, ballisticTension)

Here is the initial Custom Key definition for the buffer Preset Key A. Note that it is global (p. 646) and therefore visible in all running MAXScript code and will hold its value until 3ds max is exited.
Global keya_buffer = Biped_key type:#body ikblend:0.1 ikspace:1 easefrom:0.0 easeto:0.0 tension:25.0 continuity:0.0 bias:25.0 ikAnkleTension:.8 balanceFactor:1 dynamicsBlend:1 ballisticTension:0.5

1828

Chapter 22

CS3Tools.cui Tutorial

The CS3Tools.cui has 13 icon buttons. The first 6 are Set custom Biped Key *. The next 6 are Change Preset * to current key. The last one is Launch Preset Floater. Pressing the 7th icon, Change Preset A to current key, will change the value of the specified Preset A Keys keya_buffer to the value of the currently selected key. This will trigger the execution of the code:
macros.run character studio Tool Change_Preset_Key_A

The line above will be displayed in the MacroRecorder (p. l) if the MacroRecorder is enabled. This macro, Change_Preset_Key_A, is defined in the file \3ds3.1\ui\macroscripts\character studio Tool-Change_Preset_Key_A.mcr and contains:
macroScript Change_Preset_Key_A category:character studio Tool toolTip:Change Preset A to current key Icon:#(cstudio,7) ( keya_buffer = CS3Change_Key_FN keya_buffer CS3Save_presets() )

See help page Macro Scripts (p. 1624) in the Interacting with the 3ds max User Interface topic and Defining Macro Scripts (p. 1521) in the Creating MAXScript Tools topic for additional details on creating and using Macro Scripts. Select the last icon, Launch Preset Floater, in the CS3Tools.cui. The Preset Floater dialog is launched and displayed. There are 6 Change * buttons and 6 Show * buttons. The 6 Change * buttons on the floating rollout perform the same actions as the 6 icon buttons on the CS Custom Key toolbar.

1829

Pressing the Change A button executes the following code from the file ..\Scripts\Startup\CS3CustomKeys.ms
on ChangeA pressed do ( keya_buffer = CS3Change_Key_FN keya_buffer CS3Save_presets() )

Pressing the Show A button will display the current contents of the keya_buffer as seen here:

Note that in both cases of Changing Preset A, the same function CS3Change_Key_FN was called. Additionally, notice that CS3Save_presets() is called anytime that a preset is changed. CS3Save_presets() will save all key values to a file called CS3CustomKeys-presets.ini that can be included in next launch of CS3Customkeys.ms. This is accomplished by Save_presets formating the presets as valid MAXScript code and using the include statement (p. lix) to include the code in CS3Customkeys.ms. The included code redefines the global key_buffers already defined. The file \3ds3.1\Scripts\Startup\CS3Customkeys.ms Tutorial_File_name_CS3Customkeys_ms contains the following functions:
fn fn fn fn fn fn fn Set_One_Key_FN Set_Key_FN CS3Save_Presets CS3Show_key_FN CS3Change_Key_FN ControllerOf RootOf

The functions Change_Key_FN, Save_Presets and Set_Key_FN will be reviewed in more detail below.

1830

Chapter 22

CS3Tools.cui Tutorial

As seen in the above examples of ChangeA, the Change_Key_FN function is called with a single parameter, the particular local_key_buffer, and in the above examples with the keya_buffer. The local_key_buffer will either be returned unmodified or it will be returned modified. The values for easeto, easeFrom, tension, continuity, bias, and ikAnkleTension are stored for all valid keytypes while ikblend and ikspace is stored for only #body keys. For #vertical keys, dynamicsblend and ballistictension are also stored. For #horizontal, balancefactor is also stored. See BipedKey:MAXObject (p. 1761) for more details.

The Change_Key_FN Code

The pseudo code for the Change_Key_FN is as follows:
function Change_Key_FN local_key_buffer if nothing selected return local_key_buffer if more than one selected return local_key_buffer if not of class Biped_Object return local_key_buffer get root node of the biped and controller for this body part If body part is COM and trackselection not vertical, horizontal or turning then print skipped and return local_key_buffer else save controller selection if in figuremode return local_key_buffer if in motion mode return local_key_buffer if in footstepmode return local_key_buffer if save controller selection not undefined then set my_index to getkeyindex my_controller slidertime if a key was found then set my_key to biped.getKey my_controller my_index if (my_key.type equals #body) then ( set local_key_buffer.ikblend to my_key.ikblend set local_key_buffer.ikspace to my_key.ikspace set local_key_buffer.ikAnkleTensio to my_key.ikAnkleTension ) if (my_key.type equals #vertical) then ( set local_key_buffer.dynamicsblend to my_key.dynamicsblend set local_key_buffer.ballistictension to my_key.ballistictension ) if (my_key.type equals #horizontal) then ( set local_key_buffer.balancefactor to my_key.balancefactor ) set local_key_buffer.easefrom to my_key.easeto set local_key_buffer.easeto to my_key.easefrom set local_key_buffer.tension to my_key.tension set local_key_buffer.continuity to my_key.continuity set local_key_buffer.bias to my_key.bias set return modified local_key_buffer

1831

else return local_key_buffer else return local_key_buffer

The actual function can be seen here:

FN CS3Change_Key_FN local_key_buffer = ( if ($selection.count (p. 781) == 0 ) then ( messagebox No object selected.\nPlease select a Biped Object first.\n return local_key_buffer ) if ($selection.count (p. 781) > 1) then ( messagebox There are multiple objects selected.\nPlease select a single Biped Object first. return local_key_buffer ) if ((classof $ (p. 820)) != Biped_Object) then ( messagebox The selected object is not a Biped Object.\n Please select a Biped Object first\n. return local_key_buffer ) my_root = $.controller.rootnode my_controller = $.controller if (my_root == $) then -- user is working on COM ( if (my_controller.trackselection (p. 1736) == 2) then ( my_controller = my_controller.vertical.controller (p. 1736) ) else if (my_controller.trackselection (p. 1736) ==1) then ( my_controller = my_controller.horizontal.controller (p. 1736) ) else if (my_controller.trackselection (p. 1736) == 3) then ( my_controller = my_controller.turning.controller (p. 1736) ) else ( msgtext = + $.name messagebox msgtext + skipped.\n

1832

Chapter 22

CS3Tools.cui Tutorial

return local_key_buffer ) ) if (my_root.transform.controller.figuremode (p. 1736) == true) then ( messagebox Change Preset Key is not supported in Figure Mode.\n Please exit Figure Mode first.\n return local_key_buffer ) if (my_root.transform.controller.motionmode (p. 1736) == true) then ( messagebox Change Preset Key is not supported in Motion Flow Mode.\n Please exit Motion Flow Mode first.\n return local_key_buffer ) if (my_root.transform.controller.footstepmode (p. 1736) == true) then ( messagebox Change Preset Key is not supported in Footstep Mode.\n Please exit Footstep Mode first.\n return local_key_buffer ) if (my_controller != undefined) then ( format Controller: %\n my_controller my_index = getkeyindex (p. 1294) my_controller slidertime (p. 1580) format Key Index = %\n my_index if (my_index>0) then ( my_key = biped.getKey (p. 1761) my_controller my_index format key type is % \n my_key.type if (my_key.type == #body (p. 1761)) then ( local_key_buffer.ikblend = my_key.ikblend (p. 1761) local_key_buffer.ikspace = my_key.ikspace (p. 1761) local_key_buffer.ikAnkleTension = my_key.ikAnkleTension (p. 1761) ) if (my_key.type == #vertical (p. 1761)) then ( local_key_buffer.dynamicsblend = my_key.dynamicsblend (p. 1761) local_key_buffer.ballistictension = my_key.balistictension (p. 1761) ) if (my_key.type == #horizontal (p. 1761)) then ( local_key_buffer.balancefactor = my_key.balancefactor (p. 1761)

--

--

--

1833

) local_key_buffer.easefrom = my_key.easeto (p. 1761) local_key_buffer.easeto = my_key.easefrom (p. 1761) local_key_buffer.tension = my_key.tension (p. 1761) local_key_buffer.continuity = my_key.continuity (p. 1761) local_key_buffer.bias = my_key.bias (p. 1761) return (local_key_buffer) ) else ( messagebox Cannot change this preset because there is no key for the selected track at the current frame.\n Please advance the time slider to a frame where a key exists.\nOr select a track and frame where a key exists.\nOr set a key first.\n return (local_key_buffer) ) ) else ( messagebox There is no controller for the selected track.\nYou may need to enable separate tracks.\n return (local_key_buffer) ) )

CS3Save_Presets Code
-- ************************************************************* -- CS3Save_Presets - save all key values to a .ms file that can be re-read at next launch -- ************************************************************* FN CS3Save_Presets = ( my_path = scriptspath (p. 630) + startup\CS3CustomKeys-presets.ini outfile = createfile (p. 763) my_path format -- This file was created by the CS3 Custom Key Macro \Save_Key_Presets\ to store user-customized presets for Biped custom key macro tools\n to:outfile format -- These values can be editted by hand for existing fields\n\n to:outfile k = keya_buffer format Global keya_buffer easeto:% tension:% continuity:% k.easeto k.tension k.continuity k = keyb_buffer format Global keyb_buffer easeto:% tension:% continuity:% k.easeto k.tension k.continuity k = keyc_buffer

= Biped_key type:% ikblend:% ikspace:% easefrom:% bias:%\n k.type k.ikblend k.ikspace k.easefrom k.bias to:outfile = Biped_key type:% ikblend:% ikspace:% easefrom:% bias:%\n k.type k.ikblend k.ikspace k.easefrom k.bias to:outfile

1834

Chapter 22

CS3Tools.cui Tutorial

format Global keyc_buffer easeto:% tension:% continuity:% k.easeto k.tension k.continuity k = keyd_buffer format Global keyd_buffer easeto:% tension:% continuity:% k.easeto k.tension k.continuity k = keye_buffer format Global keye_buffer easeto:% tension:% continuity:% k.easeto k.tension k.continuity k = keyf_buffer format Global keyf_buffer easeto:% tension:% continuity:% k.easeto k.tension k.continuity close (p. 763) outfile )

= Biped_key type:% ikblend:% ikspace:% easefrom:% bias:%\n k.type k.ikblend k.ikspace k.easefrom k.bias to:outfile = Biped_key type:% ikblend:% ikspace:% easefrom:% bias:%\n k.type k.ikblend k.ikspace k.easefrom k.bias to:outfile = Biped_key type:% ikblend:% ikspace:% easefrom:% bias:%\n k.type k.ikblend k.ikspace k.easefrom k.bias to:outfile = Biped_key type:% ikblend:% ikspace:% easefrom:% bias:%\n k.type k.ikblend k.ikspace k.easefrom k.bias to:outfile

Set_Key_FN Code
The pseudo code for the Set_Key_FN is as follows:
function Set_Key_FN local_key_buffer store state of shift key if nothing selected then return false if one object selected and not a Biped Object then return false if local_key_buffer undefined then return false -process multiple selections independently so that we can -- support key setting of multiple bipeds else for each of the items in the selection ( if current item not a Biped Object then get next item set my_root to the root of the hierarchy if my_root is in figuremode then get the next item if my_root is in motionmode then get the next item if my_root is in footstepmode then get the next item set my_controller to the items controller if hierarchy root is the current item then set my_controller to the current track ( horizontal / vertical / turning) else get the next item if shift key was pressed then ( for each key in my_controller if key is selected set values for key ) else ( add a new key to my_controller at the current time and select the new key get the index of the newly created key if the index is greater than 0 then

1835

get the newly created key if (my_key.type == #body) then ( set my_key.ikblend to local_key_buffer.ikblend set my_key.ikspace to local_key_buffer.ikspace ) set my_key.easeto to local_key_buffer.easefrom set my_key.easefrom to local_key_buffer.easeto set my_key.tension to local_key_buffer.tension set my_key.continuity to local_key_buffer.continuity set my_key.bias to local_key_buffer.bias )

The actual function can be seen here:

FN Set_Key_FN local_key_buffer = ( if (keyboard.shiftpressed) then keyboardshiftpressed_atstart = true else keyboardshiftpressed_atstart = false if ($selection (p. 781).count == 0 ) then ( messagebox There are no objects selected.\nPlease select a Biped Object first.\n return false ) -- Showclass Biped_ reports Biped_Object:GeometryClass{9125,0} if (($selection (p. 781).count == 1) and ((classof $ (p. 820)) != Biped_Object)) then ( messagebox The selected object is not a Biped Object.\nPlease select a Biped Object first\n. return false ) if (local_key_buffer == undefined) then ( messagebox This preset key has not been initialized.\nPlease select a key first, and set its preset\n. return false ) -process multiple selections independently so that we can support key setting of multiple bipeds else for i=1 to $selection (p. 781).count do ( if ((classof (p. 820) $selection[i]) != Biped_Object) then ( msgtext = The selected object + $selection[i].name + is not a Biped Object.\nObject Skipped.\n

1836

Chapter 22

CS3Tools.cui Tutorial

messagebox msgtext continue ) my_root = $selection[i].controller.rootnode if (my_root.transform.controller.figuremode (p. 1736) == true) then ( msgtext = + $selection[i].name + is in Figure Mode.\nSet Key is not supported in Figure Mode.\nPlease exit Figure Mode for this object first.\nObject Skipped.\n messagebox msgtext continue ) if (my_root.transform.controller.motionmode (p. 1736) == true) then ( msgtext = + $selection[i].name + is in Motion Flow Mode.\nSet Key is not supported in Motion Flow Mode.\nPlease exit Motion Flow Mode for this object first.\nObject Skipped.\n messagebox msgtext continue ) if (my_root.transform.controller.footstepmode (p. 1736) == true) then ( msgtext = + $selection[i].name + is in Footstep Mode.\nSet Key is not supported in Footstep Mode.\nPlease exit Footstep Mode for this object first.\nObject Skipped.\n messagebox msgtext continue ) -- find the root controller of this object -- my_controller = (controllerof ($selection[i])) my_controller = $selection[i].controller if (my_root == selection[i) then -- user is working on COM ( if (my_controller.trackselection (p. 1736) == 1) then ( my_controller = my_controller.horizontal.controller (p. 1736) ) else if (my_controller.trackselection (p. 1736) == 2) then ( my_controller = my_controller.vertical.controller (p. 1736) ) else if (my_controller.trackselection (p. 1736) == 3) then ( my_controller = my_controller.turning.controller (p. 1736) )

1837

else ( msgtext = + $selection[i].name messagebox msgtext continue + skipped.\n

) ) -- loop through all keys and call only if a key is selected if (keyboardshiftpressed_atstart == true) then -- user wants to process all selected keys in this track ( found_selected_keys = 0 for temp_index=1 to (numkeys my_controller) do ( if (iskeyselected my_controller temp_index) then ( set_one_key_FN my_controller temp_index local_key_buffer -- set this key to the local key buffer found_selected_keys += 1 ) ) if (found_selected_keys == 0 ) then ( msgtext = Warning: No keys selected.\nNo changes made to + $selection[i].name + . messagebox (msgtext) ) else ( msgtext = Changed + (found_selected_keys as string) + keys in + $selection[i].name + . messagebox (msgtext) ) ) else -- (default) user wants to process just the current key ( temp_index = getkeyindex my_controller slidertime -- format index of key at this frame (temp_index) is %\n temp_index if (temp_index == 0) then -- no key at this frame yet, lets create one... ( biped.addNewKey my_controller slidertime #select temp_index = getkeyindex my_controller slidertime )

1838

Chapter 22

CS3Tools.cui Tutorial

-- temp_index should now indicate the ordinal index of the key for this track, 1st, 2nd, 3rd, etc. -- if it is still zero, then the user has selected a track or mode that prevents adding a key, like footsteps if (temp_index >0) then -- key was created ok ( set_one_key_FN my_controller temp_index local_key_buffer ) else -- addnewkey failed, probably because the footstep track is selected ( msgtext = The selected track + ($selection[i]).name + does not support keys.\n Object Skipped.\n messagebox msgtext ) ) )

return true )

Naming the Buttons

You can name the key button accordingly to help you remember the purpose for that key type: heel down, finger point, hand grab, etc. To change the tooltip for the buttons on the CS3Tools.cui toolbar, right click on the button, choose Edit Button Appearance, modify the text in the Tooltip: text box and choose the OK button.

Extending the Number of Presets

The number of different settings that CS3Tools.cui supports can be extended. Two new macro files (*.mcr) for each new additional custom key, one for Set and one for Change Preset, need to be added to the ..\ui\macroscripts directory and identical macros need to be added to ..\Scripts\Startup\CS3Customkeys.ms as well. Global key*_buffers that matched the number of pairs of new macros added to the CS3Tools.cui need to be inserted into the file ..\Scripts\Startup\CS3Customkeys.ms Tutorial_File_name_CS3Customkeys_ms. Finally, the new macro files (*.mcr) have to be incorprated into the CS3Tools.cui. See help page Macro Scripts (p. 1624) in the Interacting with the 3ds max User Interface topic and Defining Macro Scripts (p. 1521) in the Creating MAXScript Tools topic for additional details.

See Also
Biped MaxScript Extensions (p. 1725) Crowd MaxScript Extensions (p. 1771)

Index

Symbols
character lvii ? symbol xli and output pane xli capturing values xli evaluating code xli

Numerics
2 New Scripted Pug-in Superclasses 162 2D and 3D point literals 665 3D vector for programming xxxii 3ds max 4 MAXScript Online Reference xxxi 3ds max file loading and saving 1639 3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters 1614 3ds max Scene File Properties 1628 3ds max specific errors 1674 3ds max system global variables 630 3ds max-specific classes 808

A
aborting execution lv about context 686 Access to the new node bone properties and methods 23 Accessing AppData 813 accessing active viewport info type and transforms 1581

animatable properties in 3ds max objects 806 INI file keys 1647 locals and other items in a rollout from external code 1480 MAXScript 579 MAXScript classes and properties 799 scripted utilities l subAnims 806 Accessing The Material Editor Active Slot 163 Action Manager 9 ActiveX Controls in MAXScript Rollouts 10 Adapt Link Controller for Constraints 42 Adapted Path Constraint 39 addAndWeld() 1079 adding objects 591 Additional Keyword Parameter On pickObject() 127 Additive_Euler_XYZ - superclass RotationController 262 addKnot() 1079 addNewSpline() 1079 addNewXRefFile() - xrefs 1038 Adobe_Photoshop_Plug_In_Filter - TextureMap 1241 Adobe_Premiere_Video_Filter - TextureMap 1242 AEC Extended Objects Terrain 894 Affect Region Function 127 Affect_Region - Modifier 1103 alert box liii Alpha - superclass MAXObject 262

1840

Index

alphaRenderElement - superclass MAXObject 263 Anchor- Helper 986 Angle UI element 168 AngleAxis Values 741 animate 603 animate context 683 animateVertex() 1041 animation controllers 1288 animation mode xxxii Anti-Aliasing Filters 1614 AppData 813 applying standard transformations 598 ApplyOperation function 54 Apropos and ShowProperties and now Help and Show 128 Arc - Shape 949 arguments - positional and keyword 676 array literals 666 array values 776 ArrayParameter values 770 ASCII editors - opening script files 624 Asset Browser enhancements 22 assigning variables 585 assignment math 671 to variables 643 association rules 672 at 685 at level context 684 at time context 685 Atmosphere - superclass MAXObject 264 atmosphereRenderElement 264, 265 atmospheric - MAXWrapper 1337 atmospheric effects combustion 1339 common properties operators and methods 1338 fog 1342 scripted plug-ins 1569 types 1339 Volume_Fog 1343 Volume_Light 1344 working with 1345 AttachCtrl const StructDef 232 attachment - PositionController 1304

attachment controller keys 1305 attachMultiple() - splineOps 1079 audio controllers 1306 AudioClip - helper 986 auto open listener on output xxxvi auto start MAXScript lvi autoBackup const StructDef 232 auto-load lvi automatic loading lvi Automatic_Exposure_Control - superclass MAXObject 268 AutomaticAdaptiveExposureControl - superclass MAXObject 267 Avoid_Behavior ReferenceTarget 1793 awning - GeometryClass 897 axisTripodLocked() 1603

B
background - Helper 987 BackgroundRenderElement - superclass MAXObject 269 backslash - for line continuation lvii Barycentric_Morph_Controller - MorphController 1306 Barycentric_Morph_Controller Keys 1308 basic data values 717 batch scripts vs. launch scripts lvii bend - modifier 1104 bevel - modifier 1106 Bevel_Profile - Modifier 1108 Bezier controller keys 1310 Bezier controllers 1309 Bezier Keys inTangentLength and outTangentLength 158 bgndRenderElement - superclass MAXObject 270 BiFold - GeometryClass 897 BigMatrix values 748 BigMatrixRowArray values 748 billboard - helper 987 bindKnot() 1079 BinStream for Binary Reading and Writing 128 biped - system 1456 Biped and Crowd Interaction 1734 biped and physique 1456 Biped Classes 1748

Index

1841

Biped Controllers 1735 Biped Creation 1727 Biped Footprints 1745 Biped Footsteps 1745 Biped Keys 1759 Biped Layers 1731 Biped Load and Save 1725 Biped MaxScript Extensions 1725 Biped Motion Flow 1752 Biped MultFprintParams Class 1748 Biped Node Hierarchy 1731 Biped Slave Controller 1745 Biped Vertical_Horizontal_Turn(Body) Matrix3 Controller 1736 biped_object GeometryClass 1730 BipedExportInterface Values 1458 BipedFSKey MAXObject 1751, 1763 BipedKey MAXObject 1761 Biped-Related Classes 1457 bit const StructDef 233 BitArray values 791 bitmap files 1641 rollout user-interface item 1487 texture - TextureMap 1243 values 755 Bitmap Manager Function Published BMM control 161 BitmapTex fnReload and fnCrop 164 bitmapTex interfaces 434 blend - material 1205 BlendRenderElement - superclass MAXObject 271 blizzard - GeometryClass 906 Block - FloatController 1311 block expressions 679 as commands xxxviii executing xxxviii selecting xxxviii Block_Control - MasterBlockController 1311 Block_Control interfaces 435 blur - RenderEffect 1349 BMP I/O Interface 164 BMP interfaces 437 bomb - SpacewarpObject 993 bone - helper 978 Bone Creation 25

Bones - System 991 Boolean - mesh 852 Boolean2 - GeometryClass 887 BooleanClass values 728 boolObj const StructDef 233 box 591 box - GeometryClass 853 box transformations 603 box2 values 750 BoxGizmo - helper 982 brackets balancing in long code xxxviii, xlvi nested xxxviii, xlvi Bricks - TextureMap 1245 Brightness_and_Contrast - RenderEffect 1353 buffers cut/paste xxxviii, xlvi logging xli button 1488 By-Reference parameter passing 129

C
C++-style bracketing comments 131 C_Ext - GeometryClass 854 call stack trace-back liii error messages liii function parameters liii local variables liii callbacks and change handlers 1649 general event 29, 1656 time change 1654 viewport redraw 1655 callbacks const StructDef 233 camera common properties operators and methods 974 FreeCamera 976 TargetCamera 976 camera - Node 974 Camera_Map - modifier 1109 CamPoint - helper 984 Cap_Holes - modifier 1110 Capsule - GeometryClass 855 cascading contexts 688

1842

Index

case/of expression 693 casement - GeometryClass 898 catch 697 Cellular - TextureMap 1247 ChamferBox - GeometryClass 856 ChamferCyl - GeometryClass 857 change handlers 1650 and callbacks 1649 ChangeHandler - value 1650 Changes to Undeclared Implicit Global Variables 163 checkbox 1489 checkbutton 1490 checker - TextureMap 1249 circle - shape 950 class and object inspector functions 799 hierarchy 1688 property inspection 799 Class and Object Inspector Functions 159 class id filter 59 classes and objects in object-oriented programming lxii clauses mouse tool 1532 RCMenu 1515 Rollout 1470 scripted plug-in 1542 Utility 1466 close() 755, 1079 close() - splineOps 1079 clrShadowRenderElement - superclass MAXObject 272 code aborting lv bracket balancing xxxviii, xlvi comments style lvii evaluating in editor windows xlvi evaluating in listener window xlvi evaluation results xli extended blocks xxxvi inserting script files lix layout lvii, 678 line brakes lvii punctuation lvii rules for layout lvii running conflicts lv

saving in editor windows xliv Coercion of bitArray to array and integer arrays to bitArrays 132 CogControl ReferenceTarget 1791 collections 773 ArrayParameter 770 EdgeSelection 790 FaceSelection 788 MAXKeyArray 793 MAXNoteKeyArray 794 ModifierArray 794 NURBSSet 797 SelectionSet 785 Types 775 VertexSelection 786 Color values 729 color coding text - listener window xxxvii Color Manager 35 Color_Balance - RenderEffect 1354 Colored_Shadow - superclass MAXObject 273 colorpicker 1492 combobox 1493 Combustion 38 combustion atmospheric 1339 setting explosion start and end times for 1341 Combustion.coordinates - superclass MAXObject 274 Command line -U MAXScript startup scripts 133 command lines - running scripts lvii command panel switching - macro recorder method l command panels Create 1572 general 1571 Modify 1572 commands aborting multiline lv block expressions xxxviii clear all in listener window xxxviii close in editor windows xlvi copy in editor windows xlvi copy in listener window xxxviii cut in editor windows xlvi

Index

1843

cut in listener window xxxviii delete in editor windows xlvi delete in listener window xxxviii editor xlvi end-of-text xxxviii entering in listener window xxxvi evaluate all in editor windows xlvi executing 3ds max commands 1630 executing in listener window xxxviii executing in MAXScript xxxvii find in editor windows xlvi find in listener window xxxviii find next in editor windows xlvi find next in listener window xxxviii help in editor windows xlvi help in listener window xxxviii indent in editor windows xlvi listener xxxvii menu bar for listener window xxxviii new in editor windows xlvi new script in listener window xxxviii open in editor windows xlvi open script in listener window xxxviii paste in editor windows xlvi paste in listener window xxxviii recording xxxii replace in editor windows xlvi replace in listener window xxxviii run script in listener window xxxviii save as in editor windows xlvi save as in listener window xxxviii save in editor windows xlvi select all in editor windows xlvi select all in listener window xxxviii undo in editor windows xlvi undo in listener window xxxviii unindent in editor windows xlvi using number pad ENTER xlvi comments lvii comparison expressions 673 compass - helper 979 CompositeMaterial - material 1206 CompositeTextureMap - TextureMap 1250 compound objects - geometry 886 conditional statements 607 cone - GeometryClass 858 Cone_Angle - superclass helper 276

ConeAngleManip - superclass helper 277 conform - GeometryClass 889 ConformSpaceWarp - SpacewarpObject 995 connect - GeometryClass 889 Const Generic 195 Const NodeGeneric 209 Const Primitives 213 Const StructDef 231 constructs - compile time lix contents 577 context about 686 animate 683 at level 684 at time 685 cascading 688 coordsys 685 expressions 681 in 684 nested 688 set 689 undo 687 Context Filters 43 continuation lines lvii continue 696 control constructs case/of expression 693 controlling program flow 691 for loop 694 if/then/else 692 loop exit 697 try expression 697 while and do loops 694 control point animation 1461 Controller FloatController Superclass 1301 MasterBlockController Superclass 1301 MorphController Superclass 1302 Point3Controller Superclass 1302 PositionController Superclass 1303 QuatController Superclass 1304 RGB 1335 RotationController Superclass 1303 ScaleController Superclass 1304 XYZ 1335 controller Animation 1288

1844

Index

Attachment 1305 Audio 1306 Barycentric_Morph_Controller 1306 Bezier 1309 Block 1311 Block_Control 1311 common properties operators and methods 1289 Cubic_Morph_Controller 1312 Dynamics 1312 ease and multiplier curve functions 1297 Expression 1313 IK_ControllerMatrix3Controller 1313 key functions 1294 key reducer 1299 Linear 1315 Link_Control 1316 List 1317 LOD_Controller 1319 LookAt 1319 MasterBlock 1320 Matrix3Controller Superclass 1302 Motion Capture 1321 nested object functions 814 Noise 1322 On_Off 1323 out-of-range functions 1296 Path 1324 PositionController 1304 PRS 1325 Reactor 1326 Script return() 1329 Slave 1333 Slave_Control 1333 Superclass Level Types 1300 SurfacePositionController 1334 TCB 1334 time functions 1292 Waveform_Float 1335 Controller Functions for use with Constraint Assignments 42 controlling program flow in scripts 607 controlling the renderer 1664 ConvertToPatch - superclass modifier 278 Coordinate Display 1578

coordinates - macro recorder l coordsys 685 coordsys context 685 copy editor windows command xlvi listener window command xxxviii Core Interfaces 70, 352 Create Panel 1572 CreateDialog 169 createPreview() 1603 creating functions 699 Creating Icon Bitmap Files 1530 creating new NURBS objects 1389 creating NURBS scene objects 1392 creating NURBSCVSurface values 1394 CrossSection - Modifier 1110 Crowd Behaviors 1792 Crowd helper 1771 Crowd Priority Properties 1792 Crowd R3.0 MaxScript Extentions 1771 CrowdAssignment ReferenceTarget 1784 Crowds Methods 1788 CrowdScatter 1778 CrowdState ReferenceTarget 1786 CrowdTeam ReferenceTarget 1785 CrowdTransition ReferenceTarget 1787 CS3Tools.cui Tutorial 1825 Cubic_Morph_Controller - MorphController 1312 Cubic_Morph_Controller Keys 1312 cui const StructDef 234 cursor in bracket balancing xxxviii, xlvi placement in panes xxxvi cursors for drag-and-drop l searching last position xlvi Curve Control 170 custAttributes const StructDef 234 custom functions 614 custom user interface files 1648 Customize The Order of Rollup Pages 185 cut cut/paste buffer xxxviii, xlvi editor windows command xlvi listener window command xxxviii CV_Curve - Shape 964

Index

1845

cycle() - splineOps 1079 CylGizmo - helper 983 cylinder - GeometryClass 859

D
damper - GeometryClass 880 default mode - logging xli defaults - macro recorder l defining custom functions 614 local functions in structures 709 macro scripts 1521 utilities l Definition Constructs Can Include Global Variable Declarations At Top Level 162 definitions lx Definitions for MAXScript internal organization 188 deflector - SpacewarpObject 1024 Delegate Helper 1773 delete editor windows command xlvi listener window command xxxviii delete() 1038 delete() - splineOps 1079 deleteAllXRefs() - xrefs 1038 deleteKnot() 1079 DeleteMesh - Modifier 1111 DeletePatch - superclass modifier 279 deleteSpline() 1079 DeleteSplineModifier - Modifier 1111 Dent - TextureMap 1251 dependent NURBS objects 1386 dependsOn For Scripted Controllers 95 Depth_of_Field - RenderEffect 1354 Dereferencing Operator 133 desktop configuring setups lvi location of windows lvi storing state lvi detach() - splineOps 1079 Detecting Deleted Nodes 133 Diffuse - superclass MAXObject 279 diffuseRenderElement - superclass MAXObject 280 DirectionalLight - Light 970

Disp_Approx - Modifier 1111 Displace - Modifier 1112 Displace_Mesh - SpacewarpModifier 1198 Displace_NURBS - SpacewarpModifier 1198 display() 755 displaySafeFrames 1603 divide() - splineOps 1079 do and while loops 607, 694 do loop exit 697 do/while expression 694 DOF const StructDef 234 DontCollect Value 754 donut - shape 951 door objects - geometry 896 DOS - and listener window xxxvi double-hyphen - for code comments lvii DoubleSided - Material 1207 Drag - superclass SpacewarpObject 149, 281 drag-and-drop editor windows xliv listener window xxxvii using cursor l drawing a box with MAXScript 591 dropdownlist 1494 dummy - helper 979 dynamic properties 805 Dynamics Controllers 1312 dynamics objects - geometry 879 dynamics space warps 1003

E
EdgeSelection values 790 Edit_Mesh - modifier 1114 Edit_Patch - modifier 1115 Edit_Spline - modifier 1115 editable meshes 1041, 1077 editable patches 1041 editable splines 1041 Editable_Mesh - GeometryClass 1041 editor commands xlvi description xliv editor windows xliv and script files xliv creating empty xliv drag-and-drop functions xxxvii

1846

Index

editing text xliv evaluating code xlvi keyboard shortcuts xlvi list of features xliv loading files xliv menu bar commands xlvi opening xxxiv, xliv saving code xliv syntax coloring xlvi edittext 1496 ellipse - shape 953 emissionRenderElement - superclass MAXObject 285 encrypted files 1647 encrypting scripts lx end-of-text aborting xxxviii listener window command xxxviii entering arrays 582 entering information in MAXScript 582 entering numbers 582 entering strings 582 error messages liii call stack trace-back liii embedded liii in alert box liii in listener panes xxxviii in output pane liii logging xli errors - locating in MAXScript liii ESC - aborting execution lv escape lv escapeEnable lv EulerAngles Values 742 evaluating expressions xli example scripts 624 executing external commands 1668 exit - loops 697 exiting 3ds max 1669 explicit scene objects - macro recorder l explode() - splineOps 1079 exposing MAXScript functions 1673 expression blocks 679 case/of 693 catch 697 comparison 673

context 681 for/do for/collect 694 function call 675 function definition 699 if/then/else 692 logical 674 logical - short-circuiting 675 math 670 return 705 simple 669 struct 707 throw 697 try 697 when 1650 while/do 694 expression controllers 1313 expressions 588, 667 determining if complete lvii evaluating xli extended objects - geometry 852 external file methods 1645 extrude - modifier 1115

F
Face_Extrude - modifier 1127 FaceSelection values 788 Fallof2 - TextureMap 1252 FalloffTextureMap - TextureMap 1255 favorites tab (HTML help viewer) 1721 FFD_2x2x2 - Modifier 1121 FFD_3x3x3 - Modifier 1123 FFD_4x4x4 - Modifier 1124 FFD_Box - Modifier 1117 FFD_Cyl - Modifier 1119 FFD_Select - Modifier 1126 file name parsing 1644 file open dialog - opening xxxiv File_Output - RenderEffect 1356 fileIn() lix fileProperties const StructDef 235 files 3ds max file loading and saving 1639 bitmap 1641 custom user interface files 1648 encrypted 1647

Index

1847

external file methods 1645 INI files 1647 loading in editor windows xliv name parsing 1644 searching directories for xliv, lvi standard open and save dialogs 1643 text file input and output 1643 XRef files 1643 FileStream Values 763 Fillet_Chamfer - Modifier 1127 Film_Grain - RenderEffect 1356 filter options - macro recorder l Filters - Anti-Aliasing 1614 find editor windows command xlvi listener window command xxxviii find next editor windows command xlvi listener window command xxxviii findUnresolvedXRefs() - xrefs 1038 Fixed - GeometryClass 899 flagChanged() 1038 flashNodes() 1603 FlatMirror - TextureMap 1255 Flex - modifier 1128 Flex interfaces 438 flexOps const StructDef 235 float_list interfaces 441 Float_Reactor interfaces 443 Float_Wire interfaces 448, 569 FloatController Block 1311 LOD_Controller 1319 On_Off 1323 Waveform_Float 1335 FloatController - MAXWrapper 1301 FloatList - superclass FloatController 286 FloatList interfaces 450 FloatReactor - superclass FloatController 287 FloatReactor interfaces 452 fn function definition 699 fog - atmospheric 1342 FogHelper - helper 987 FootSteps Matrix3 Controller 1745 FootSteps Matrix3 Controller 1744, 1750 for loop 607

exit 697 expression 694 skipping iterations 696 forceUpdate Function 134 FreeCamera - Camera 976 freeform language - defined lvii freeSceneBitmaps() 755 FreeSpot - Light 971 function definition 699 in structures 709 parameters 702 return 705 variables 701 function calls arguments 676 general 675 precedence 677 special notes 678 function libraries lvi

G
garbage collection 655, 656 general event callback mechanism 29, 1656 general node properties 836 general topics lii Gengon - GeometryClass 861 Geometry scripted plug-ins 1555 geometry Awning 897 BiFold 897 Blizzard 906 Boolean2 887 Box 853 C_Ext 854 Capsule 855 Casement 898 ChamferBox 856 ChamferCyl 857 common properties operators and methods 852 Compound Objects 886 Cone 858 Conform 889

1848

Index

Connect 889 Cylinder 859 Damper 880 Doors and Windows 896 Dynamics Objects 879 Editable_Mesh 1041 Fixed 899 Gengon 861 Geosphere 862 Hedra 863 L_Ext 865 Loft 890 Morph 891 NURBS Objects 943 NURBSSurf 943 OilTank 866 OldBoolean 887 PArray 913 Particle Systems 904 Patch 1088 Patch Objects 903 PCloud 923 Pivot 899 Pivoted 900 Plane 867 Point_Surf 943 Prism 868 Projected 901 Pyramid 869 Quadpatch 903 RingWave 870 Scatter 891 ShapeMerge 893 SimpleObject scripted plug-ins 1556 SlidingDoor 901 SlidingWindow 902 Snow 931 Sphere 872 Spindle 873 Spray 933 Spring 883 Standard and Extended Objects 852 SuperSpray 935 TargetObject 874 Teapot 875 Terrain 894 Torus 875

Torus_Knot 877 TriPatch 904 Tube 878 geometry - Node 850 geosphere - GeometryClass 862 getActive 176 getChannel() 755 getChannelAsMask() 755 GetEndTime() - ik 1313 getIndexedPixels() 755 getInVec() 1079 GetIterations() - ik 1313 getKnotPoint() 1079 getKnotSelection() 1079 getKnotType() 1079 getOutVec() 1079 getPixels() 755 GetPosThreshold() - ik 1313 GetRotThreshold() - ik 1313 getSegLengths 1079 getSegmentType() 1079 getSegSelection() 1079 getSplineSelection() 1079 GetStartTime() - ik 1313 getSubAnimName() 806 getSubAnimNames() 806 getTextExtent 175 getXRefFile() - xrefs 1038 global 646 global variables 614 gotoFrame() 755 gradient - TextureMap 1257 Gradient_Ramp - TextureMap 1259 gravity - SpacewarpObject 1003 grid - helper 980 gw const StructDef 235

H
hasProperty() function 135 HD IK controller chains can be assigned to existing hierarchies 73 Hedra - GeometryClass 863 Helix - Shape 954 help about HTML help 1717 contents 1717

Index

1849

editor windows command xlvi index 1717 listener window command xxxviii search 1717 Helper scripted plug-ins 1561 helper Anchor 986 Atmospheric 982 AudioClip 986 Background 987 Billboard 987 Bone 978 BoxGizmo 982 Camera Match 984 CamPoint 984 Compass 979 CylGizmo 983 Dummy 979 FogHelper 987 Grid 980 Inline 984 InlineHelper 988 LOD 985 LODHelper 988 NavInfo 988 Point 980 Protractor 981 ProxSensor 989 Sound 989 SphereGizmo 983 Standard 978 Tape 981 TimeSensor 990 TouchSensor 990 VRML 1.0/VRBL 984 VRML_VRBL 985 VRML97 985 helper - Node 977 hide() - splineOps 1079 hideselectedsegments() 1079 hideselectedsplines() 1079 hideselectedverts() 1079 Hierarchy - MAXScript Class 1688 Hose - superclass GeometryClass 146, 287 HSDS_Modifier - superclass modifier 290 HSDS_Modifier interfaces 453

HSDSObject - superclass modifier 292 HSDSObject interfaces 453 HTML help viewer favorites tab 1721 keyboard shortcuts 1722 right-click menus 1722 searching in 1718 toolbar 1721 using 1715

I
Icon Bitmap Files - Creating 1530 Identifying and Accessing MAXScript Classes and Properties 799 iDrop - drag and drop 62 if/do expression 692 if/then/else expression 607, 692 ik GetEndTime() 1313 GetIterations() 1313 GetPosThreshold() 1313 GetRotThreshold() 1313 GetStartTime() 1313 SetEndTime() 1313 SetIterations() 1313 SetPosThreshold() 1313 SetStartTime() 1313 ik const StructDef 237 IK controller methods 1313 IK_ControllerMatrix3Controller Matrix3Controller 1313 IKChainControl interfaces 453 IKLimb Solver 74 image buttons 1513 imageMotionBlur - superclass renderEffect 294 imageMotionBlur interfaces 454 Improved the Performance of Itterating and Indexing the 135 in context 684 including scripts within scripts lix incrementing 588 independent NURBS object 1386 indexed access to animatable properties in 3ds max objects 806 inheritance lxiii inline - helper 984

1850

Index

InlineHelper - helper 988 insertion point xlii installing - listener window xxxvi instance 1778 interface elements of xxxiv extending xxxii replacing xxxii 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 Interface medit 371 Interface menuMan 372 Interface msZip 378 Interface NetRender 379 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 Interfaces 67 interrupt execution lv intersect() - splineOps 1079 intersection - mesh 852 Interval Values 752 inverse kinematics controller methods 1313 isClosed() 1079 isCPEdgeOnInView() 1603 isValidNode 136 ItrackBar 113

K
keyboard keyboard entry 1623 keyboard const StructDef 237 keyboard shortcuts HTML help viewer 1722 keyboard.escPressed 176 keys Attachment Controller 1305 Barycentric_Morph_Controller 1308 Bezier Controller 1310 Cubic_Morph_Controller 1312 Linear Controller 1315 MAXKey Values 767 On_Off Controller 1323 TCB Controller 1335 keywords keyword arguments 676 reserved 625

L
L_Ext - GeometryClass 865 label 1497 language basic learning requirements xxxiii freeform defined lvii reserved keywords 625 lathe - modifier 1133 lattice - modifier 1135 launch scripts vs. batch scripts lvii layout parameters - rollout user-interface controls 1483 LE const StructDef 237 learning MAXScript 577 the macro recorder 624 walking through a script 623 Lens_Effects - RenderEffect 1357 Light scripted plug-ins 1561 light common properties operators and methods 966 DirectionalLight 970 FreeSpot 971

J
JPEG interfaces 454

Index

1851

Omnilight 972 TargetDirectionalLight 972 TargetSpot 973 light - Node 966 Line - Shape 955 line breaks 580 in MAXScript code lvii invalid lvii line selection margin editor windows xliv listener window xxxvii linear controller keys 1315 linear controllers 1315 Link - superclass Matrix3Controller 294 Link interfaces 455 Link.link_params - superclass MAXObject 295 Link_Constraint - superclass Matrix3Controller 295 Link_Constraint interfaces 455 Link_Constraint.link_params - superclass MAXObject 296 Link_Control - Matrix3Controller 1316 Linked_XForm - Modifier 1136 LinkedXForm - superclass modifier 297 List Controller 143 List Controllers 1317 listbox 1497 ListCtrl const StructDef 238 listener ? symbol xli contents xlii description xxxvi using xxxvii listener window xxxvi aborting code lv and 3D Studio MAX xxxvi and block expressions xxxviii creating editor windows xliv defined xxxvi entering commands xxxvi evaluating code xlvi features of xxxvii installing xxxvi keyboard shortcuts xxxviii logging xli menu bar commands xxxviii opening xxxiv, xxxvi

output xxxiv panes defined xxxvi running scripts xlix similarities to DOS xxxvi literals lxiv 2D and 3D points 665 arrays 666 constants 659 float 660 integer 660 names 657 numbers 660 pathnames 662 strings 660 time 662 loading - automatic lvi loading and running your script file 621 loading other scripts 623 local 646 local variables 614 lockAxisTripods() 1603 LOD - Helper 985 LOD_Controller - FloatController 1319 LODHelper - Helper 988 Loft - GeometryClass 890 log files closing xli creating xli logging capturing output xli capturing text xli default mode xli error messages xli in listener window xli writing data xli logical expressions 674 logsystem const StructDef 239 LookAt - Matrix3Controller 1319 LookAt Constraint 40 LookAt_Constraint - superclass RotationController 297 LookAt_Constraint interfaces 455 loop exit 697 loops 607

1852

Index

M
macro recorder l default options l displaying output l explicit scene objects l filter options l recording user actions l selection-relative scene objects l sub-object sets l using MAXScript commands l macro recorder pane listener window xxxvi, xxxviii macro scripts 1624 creating xxxviii, xliv defining 1521 macros const StructDef 239 macroScript 1521 macroScript Localization Support for CUI and menu files 176 main toolbar 1574 makeFirst() - splineOps 1079 managing multiple rollouts in a scripted utility 1468 manual garbage collection 656 mapbutton 1499 mapKeys() method 144 mapPaths const StructDef 239 mapped function definition 699 MapScaler - SpacewarpModifier 1198 marble - TextureMap 1261 Mask - TextureMap 1262 MasterBlock - MasterBlockController 1320 MasterBlockController Block_Control 1311 MasterBlock 1320 MasterBlockController - MAXWrapper 1301 Material scripted plug-ins 1565 material Blend 1205 common properties operators and methods 1203 CompositeMaterial 1206 DoubleSided 1207 MatteShadow 1208 MorpherMaterial 1209

MultiMaterial 1210 NoMaterial 1212 RayTraceMaterial 1212 Shellac 1233 StandardMaterial 1224 StandardXYZGen 1238 TexOutputClass 1239 TextureMap 1234 TopBottom 1233 Types 1204 UVGenClass 1237 material - MAXWrapper 1203 Material Editor 1606 Material Level Show-in-viewport State 166 materialbutton 1500 MaterialByElement - Modifier 1136 materialID() 1079 MaterialLibrary values 795 MaterialModifier - modifier 1137 materials assignment and texture coordinates 1391 math 588 math assignment 671 math expressions 670 mathematical operations in MAXScript 588 Matrix3 Scripted Controller 96 Matrix3 Values 744 Matrix3Controller IK_ControllerMatrix3Controller 1313 Link_Control 1316 LookAt 1319 MAXWrapper 1302 PRS 1325 Slave_Control 1333 MatteShadow - Material 1208 MAX commands 1630 MAX commands in MAXScript 620 MAX Open & Save Dialogs 177 MAXKey common properties operators and methods 768 values 767 MAXKeyArray Values 793 MAXNoteKey Values 818 MAXNoteKeyArray Values 817 maxOps 87

Index

1853

MAXScript Class Hierarchy 1688 MAXScript commands in macro recorder l MAXScript grammar 1681 MAXScript message and query dialogs 1622 MAXScript overview xxxii MAXScript system globals 640 MAXScript.reg - Registery file 84 MAXScriptFunction List 190 maxscrpt.dsk lvi MAX-specific classes - dynamic properties 805 MAXWrapper AppData 813 Atmospheric 1337 common properties operators and methods 809 Controllers 1288 Material 1203 Modifier 1095 nested controllers 814 nested object properties 815 Node 820 RenderEffect 1347 SpacewarpModifier 1095 MAXWrapper - Value 808 Melt - Modifier 1138 memory allocation 655 Menu and CUI Loading 178 Menu Manager 75 menuItem 1518 menus mouse right-click 1514 right-click in editor windows xlvi right-click in listener window xxxviii merge() 1038 mesh nodeTM 1556 Mesh_Select - modifier 1142 Mesher 82 Mesher - superclass GeometryClass 298 meshop const StructDef 239 meshOps const StructDef 243 MeshSmooth - modifier 1139 meshsmooth - superclass modifier 298 methods lxiv for macro recorder l

scripted plug-in 1551 mini listener - defined xxxvi mirror - modifier 1143 mirrorBoth() - splineOps 1079 mirrorHoriz() - splineOps 1079 mirrorVert() - splineOps 1079 miscellaneous dialogs 1621 functions 1663 viewport methods and system globals 1603 Missing Object Classes 1460 mix - TextureMap 1262 modification 593 color 593 name 593 position 593 scale 593 showClass() 593 size 593 Modifier scripted plug-ins 1562 scripted SimpleMod plug-ins 1563 modifier Affect_Region 1103 Bend 1104 Bevel 1106 Bevel_Profile 1108 Camera_Map 1109 Cap_Holes 1110 change 603 common properties operators and methods 1096 creation 603 CrossSection 1110 DeleteMesh 1111 DeleteSplineModifier 1111 Disp_Approx 1111 Displace 1112 Edit_Mesh 1114 Edit_Patch 1115 Edit_Spline 1115 Extrude 1115 Face_Extrude 1127 FFD_2x2x2 1121 FFD_3x3x3 1123 FFD_4x4x4 1124

1854

Index

FFD_Box 1117 FFD_Cyl 1119 FFD_Select 1126 Fillet_Chamfer 1127 Flex 1128 Lathe 1133 Lattice 1135 Linked_XForm 1136 MaterialByElement 1136 MaterialModifier 1137 Melt 1138 Mesh_Select 1142 MeshSmooth 1139 Mirror 1143 Morpher 1144 NCurve_Sel 1145 NoiseModifier 1145 Normalize_Spline 1146 NormalModifier 1147 NSurf_Sel 1147 Optimize 1148 PatchDeform 1150 PathDeform 1151 Physique 1458 Preserve 1152 Push 1153 Relax 1154 Ripple 1154 Skew 1155 Skin 1157 SliceModifier 1165 Smooth 1166 Spherify 1167 SplineSelect 1167 Squeeze 1167 STL_Check 1169 Stretch 1170 sub-object transform properties 1099 Surface 1171 SurfDeform 1171 Taper 1173 Tessellate 1174 Trim_Extend 1175 Twist 1175 Types 1100 Unwrap_UVW 1176 UVW_Xform 1187

UVWmap 1188 Vertex_Colors 1191 VertexPaint 1191 VolumeSelect 1192 Wave 1194 XForm 1195 Modifier - MAXWrapper 1095 ModifierArray Values 794 Modify panel 1572 modifying existing NURBS objects 1390 modifying the box 593 modPanel const StructDef 244 MoFlowScript MaxWrapper 1754 MoFlowSnippet MaxWrapper 1755 MoFlowTranInfo MaxWrapper 1756 MoFlowTransition MaxWrapper 1758 morph - GeometryClass 891 MorphController Barycentric_Morph_Controller 1306 Cubic_Morph_Controller 1312 MorphController - MAXWrapper 1302 morpher - modifier 1144 MorpherMaterial - material 1209 Motion Capture 1763 motion capture controllers 1321 Motion Flow 1752 Motion_Blur - superclass renderEffect 302 Motion_Blur interfaces 462 MotionClips and GlobalMotionClip 1820 Motor- SpacewarpObject 1004 mouse const StructDef 244 mouse cursors 1588 mouse right-click menus 1514 mouse tools - scripted 1531 mouseTrack() Function 180 move() 598 moveKeys function 145 mtlBrowser 180 mtlBrowser const StructDef 244 Multi/Sub Material 75 Multi-line editText UI items in Scripted Rollouts 108 MultiListBox 1502 MultiMaterial - material 1210 MultiRes - superclass modifier 153, 302

Index

1855

N
Name literals 657 values 727 NavInfo - Helper 988 NCurve_Sel - Modifier 1145 nested contexts 688 nested object controller functions 814 nested object properties 815 nesting brackets xxxviii, xlvi script files lix Network Render iMaxNet 82 New Classes in release 4 259 new script listener window command xxxviii NGon - Shape 957 node Camera 974 common properties operators and methods 820 general properties 836 GeometryClass 850 Helper 977 Light 966 MAXWrapper 820 SpacewarpObject 992 subclasses 849 System 991 transform properties 841 using 843 user-defined properties and methods 848 XRefObject 1037 node - Shape 944 Node Handles 83 Node vertexColorType 83 NodeChildrenArray Values 785 noise - TextureMap 1263 noise controllers 1322 NoiseModifier - modifier 1145 NoMaterial - material 1212 Normalize_Spl - superclass modifier 305 Normalize_Spline - modifier 1146 NormalModifier - modifier 1147 note keys - value 818 note track access 816

Notetrack Values 816 NoTexture - TextureMap 1265 Notify Callbacks for Animate button on and off Transitions 27 NSurf_Sel - modifier 1147 Number literals 660 values 717 numKnots() 1079 numSegments() 1079 numSplines() 1079 NURBS classes 1401 classes - overview 1386 node properties and methods 1397 working with 1384 NURBS Curves - Shapes 964 NURBS Objects NURBSSurf 943 Point_Surf 943 NURBS1RailSweepSurface - NURBSSurface 1427 NURBS2RailSweepSurface - NURBSSurface 1429 NURBSBlendCurve - NURBSCurve 1410 NURBSBlendSurface - NURBSSurface 1430 NURBSCapSurface - NURBSSurface 1432 NURBSChamferCurve - NURBSCurve 1411 NURBSControlVertex - NURBSObject 1409 NURBSCurve NURBSBlendCurve 1410 NURBSChamferCurve 1411 NURBSCurveOnSurface 1414 NURBSCVCurve 1412 NURBSFilletCurve 1415 NURBSMirrorCurve 1417 NURBSOffsetCurve 1417 NURBSPointCurve 1418 NURBSPointCurveOnSurface 1419 NURBSProjectNormalCurve 1420 NURBSProjectVectorCurve 1421 NURBSSurfaceEdgeCurve 1422 NURBSSurfaceNormalCurve 1422 NURBSSurfSurfIntersectionCurve 1423 NURBSXFormCurve 1424 NURBSCurve - NURBSObject 1409 NURBSCurveConstPoint - NURBSPoint 1403 NURBSCurveIntersectPoint - NURBSPoint 1404 NURBSCurveOnSurface - NURBSCVCurve 1414

1856

Index

NURBSCurveSurfaceIntersectPoint - NURBSPoint 1405 NURBSCVCurve NURBSCurveOnSurface 1414 NURBSCVCurve - NURBSCurve 1412 NURBSCVSurface - NURBSSurface 1433 NURBSDisplay - Value 1447 NURBSExtrudeSurface - NURBSSurface 1435 NURBSFilletCurve - NURBSCurve 1415 NURBSFilletSurface - NURBSSurface 1436 NURBSIndependentPoint - NURBSPoint 1406 NURBSIsoCurve - NURBSCurve 1416 NURBSLatheSurface - NURBSSurface 1437 NURBSMirrorCurve - NURBSCurve 1417 NURBSMirrorSurface - NURBSSurface 1437 NURBSMultiCurveTrimSurface - NURBSSurface 1438 NURBSNBlendSurface - NURBSSurface 1439 NURBSObject NURBSControlVertex 1409 NURBSCurve 1409 NURBSPoint 1403 NURBSSurface 1425 NURBSTexturePoint 1446 NURBSObject - Value 1402 NURBSOffsetCurve - NURBSCurve 1417 NURBSOffsetSurface - NURBSSurface 1440 NURBSPoint NURBSCurveConstPoint 1403 NURBSCurveIntersectPoint 1404 NURBSCurveSurfaceIntersectPoint 1405 NURBSIndependentPoint 1406 NURBSPointConstPoint 1407 NURBSSurfConstPoint 1407 NURBSPoint - NURBSObject 1403 NURBSPointConstPoint - NURBSPoint 1407 NURBSPointCurve NURBSPointCurveOnSurface 1419 NURBSPointCurve - NURBSCurve 1418 NURBSPointCurveOnSurface - NURBSPointCurve 1419 NURBSPointSurface - NURBSSurface 1441 NURBSProjectNormalCurve - NURBSCurve 1420 NURBSProjectVectorCurve - NURBSCurve 1421 NURBSRuledSurface - NURBSSurface 1442 NURBSSelection - Value 1448

NURBSSet - Value 1450 NURBSSurf - GeometryClass 943 NURBSSurface NURBS1RailSweepSurface 1427 NURBS2RailSweepSurface 1429 NURBSBlendSurface 1430 NURBSCapSurface 1432 NURBSCVSurface 1433 NURBSExtrudeSurface 1435 NURBSFilletSurface 1436 NURBSLatheSurface 1437 NURBSMirrorSurface 1437 NURBSMultiCurveTrimSurface 1438 NURBSNBlendSurface 1439 NURBSOffsetSurface 1440 NURBSPointSurface 1441 NURBSRuledSurface 1442 NURBSULoftSurface 1443 NURBSUVLoftSurface 1444 NURBSXFormSurface 1445 NURBSSurface - NURBSObject 1425 NURBSSurfaceApproximation - Value 1453 NURBSSurfaceEdgeCurve - NURBSCurve 1422 NURBSSurfaceNormalCurve - NURBSCurve 1422 NURBSSurfConstPoint - NURBSPoint 1407 NURBSSurfSurfIntersectionCurve - NURBSCurve 1423 NURBSTexturePoint - NURBSObject 1446 NURBSTextureSurface - Value 1455 NURBSULoftSurface - NURBSSurface 1443 NURBSUVLoftSurface - NURBSSurface 1444 NURBSXFormCurve - NURBSCurve 1424 NURBSXFormSurface - NURBSSurface 1445

O
object hierarchies time and key functions on 1299 object hierarchy xxxii object path names 662 objects and classes in object-oriented programming lxii property inspection 799 scene xxxii use of xxxiii

Index

1857

ObjectSet values 781 OilTank - GeometryClass 866 Ok value 754 OldBoolean - GeometryClass 887 OLE automation 1671 Omnilight - light 972 on mouse tool event handlers 1531 rolloutfloater event handlers 1474 utility/rollout event handlers 1474 on detachedFromNode For Object Scripted Plug-ins 106 on MAX Objects Now Takes Subanim Names 139 On_Off - FloatController 1323 On_Off controller keys 1323 online reference searching in 1718 using HTML help viewer 1715 open editor windows commands xlvi script listener window command xxxviii open() 1079 openBitMap() 755 opening editor window xxxiv editor windows xliv file open dialog xxxiv listener window xxxiv MAXScript 579 operands 669 operations with strings 588 operators lxiv Optimize - Modifier 1148 options const StructDef 245 Orientation Constraint Controller 40 Orientation_Behavior ReferenceTarget 1794 Orientation_Constraint - superclass RotationController 306 Orientation_Constraint interfaces 462 Other Interfaces 71, 432 Output - TextureMap 1265 output pane error messages liii listener window xxxvi, xxxviii running scripts xlix

use of ? symbol xli overview of the principal NURBS classes 1386

P
Paint - TextureMap 1266 panes cursor placement xxxvi defined in listener window xxxvi editing xxxvi error messages xxxviii executing code xxxvi macro recorder xxxviii, l mini listener xxxvi output xxxviii parameter blocks 1542 parameter ranges for curves and surfaces 1391 Parameter Wiring 85 parameters - functions 702 PArray - GeometryClass 913 particle space warps 1003 particle systems Blizzard 906 common properties operators and methods 905 PArray 913 PCloud 923 Snow 931 Spray 933 SuperSpray 935 particle systems - Geometry 904 Particle_Age - TextureMap 1266 Particle_MBlur - TextureMap 1267 particleMesher - superclass GeometryClass 306 paste editor windows command xlvi listener window command xxxviii patch - GeometryClass 1088 patch const StructDef 245 patch objects Patch 1088 Quadpatch 903 TriPatch 904 patch objects - Geometry 903 Patch_Select - superclass modifier 307 PatchDeform - modifier 1150

1858

Index

Patches 55 patchOps const StructDef 247 path - PositionController 1324 path interfaces 462 Path_Constraint - superclass PositionController 307 Path_Constraint interfaces 468 Path_Follow - SpacewarpObject 1025 Path_Follow_Behavior ReferenceTarget 1796 PathDeform - Modifier 1151 PathName literals 662 values 780 pausing script execution 1664 PBomb - SpacewarpObject 1006 PCloud - GeometryClass 923 PDynaFlect - SpacewarpObject 1019 PDynaflector - superclass SpacewarpObject 309 Perlin_Marble - TextureMap 1268 persistent global variables 651 persistents const StructDef 247 PhyBlendingRigidVertex Values 1459 PhyContextExport Values 1458 PhyRigidVertex Values 1459 physique - modifier 1458 pickbutton 1504 picking points in the viewports 1589 scene nodes by hit 1618 scene nodes by name 1619 scene nodes by region 1620 pivot - GeometryClass 899 pivoted - GeometryClass 900 plane - GeometryClass 867 Plane_Angle - superclass helper 310 PlaneAngleManip - superclass helper 311 planet - TextureMap 1269 Plug In Manager 86 Plugin_Manager interfaces 473 plug-ins defining lvi scripted 1538 point - helper 980 Point Cache Modifier 26 Point_Cache - superclass modifier 314 Point_Cache interfaces 484 Point_CacheSpacewarpModifier - superclass

SpacewarpModifier 315 Point_CacheSpacewarpModifier interfaces 485 Point_Curve - Shape 965 Point_Surf - GeometryClass 943 Point2 literals 665 values 736 Point3 literals 665 values 731 point3_list interfaces 475 Point3_Reactor interfaces 477 Point3_Wire interfaces 477, 570 Point3Controller - MAXWrapper 1302 Point3List - superclass Point3Controller 312 Point3List interfaces 479 Point3Reactor - superclass Point3Controller 312 Point3Reactor interfaces 481 Point3Spring - superclass Point3Controller 313 Point3Spring interfaces 482 PointCache - superclass modifier 316 PointCache interfaces 486 PointCacheWSM - superclass SpacewarpModifier 317 PointCacheWSM interfaces 487 PointHelperObj - superclass helper 318 Poly_Select - superclass modifier 319 polymorphism lxiii, 672 polyop const StructDef 248 polyOps const StructDef 251 POmniFlect - SpacewarpObject 1027 Portable_Network_Graphics interfaces 473 Position Constraint 41 Position_Constraint - superclass PositionController 320 Position_Constraint interfaces 488 position_list interfaces 490 Position_Reactor interfaces 492 Position_Wire interfaces 492 positional arguments 676 PositionController Attachment 1304 Path 1324 SurfacePositionController 1334 PositionController - MAXWrapper 1303 PositionList - superclass PositionController 321

Index

1859

PositionList interfaces 494 PositionReactor - superclass PositionController 321 PositionReactor interfaces 496 PositionSpring - superclass PositionController 321 PositionSpring interfaces 497 precedence function calls and parameters 677 rules 672 predefined global variables 629 preferences auto open listener on output xxxvi useLargeVertexDots 1603 useTransformGizmos 1603 useVertexDots 1603 preferences onst StructDef 252 preserve - modifier 1152 prism - GeometryClass 868 progress bar display 1578 progressBar 1505 progressCB 28, 107 projected - GeometryClass 901 prompt line 1577 properties lxiv dynamic 805 nested objects 815 protractor - helper 981 ProxSensor - helper 989 PRS - Matrix3Controller 1325 PSpawnflector - superclass SpacewarpObject 322 punctuation and symbols 627 in MAXScript code lvii push - modifier 1153 PushSpaceWarp - SpacewarpObject 1008 pyramid - GeometryClass 869

R
radiobuttons 1506 radiusManip interfaces 500 RAMPlayer() 1617 random numbers 588 random() 588 ray values 737 Raytrace - TextureMap 1271 RayTraceMaterial - Material 1212 RCMenu clauses 1515 user-interface items 1518 RCMenu User-Interface Item menuItem 1518 separator 1519 subMenu 1520 Reactor controller 91 reactor controllers 1326 Readable/Writable Checks 135 recorder - macro l recording commands xxxii rectangle - shape 958 reference assignment 653 refineSegment() 1079 Reflect_Refract - TextureMap 1276 Reflection - superclass MAXObject 323 reflectionRenderElement - superclass MAXObject 324 Refraction - superclass MAXObject 326 refractionRenderElement - superclass MAXObject 327 refreshing the viewports 1585 refs const StructDef 252 relax - modifier 1154 Render Element Manager 92 render scene dialog 1611 render() Function Re-entrant 160 RenderEffect Blur 1349 Brightness_and_Contrast 1353 Color_Balance 1354 common properties operators and methods 1347 Depth_of_Field 1354 File_Output 1356 Film_Grain 1356

Q
Quad Menu 90 quadpatch - GeometryClass 903 Quat Values 738 QuatController - MAXWrapper 1304 quitMAX() lvii

1860

Index

Lens_Effects 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 scripted plug-ins 1566 Types 1348 RenderEffect - MAXWrapper 1347 RenderEffect Progress Callback Mechanism 28, 107 RenderElementMgr interfaces 503 Renderer 162 Renderer Anti-Aliasing Filters 1614 Repel_Behavior 1798 replace editor windows command xlvi listener window command xxxviii replacing text - editor windows xliv reserved global variables 628 keywords 625 punctuation 625 symbols 625 variables 625 resetShape() 1079 resetting 3ds max 1669 return expression 705 reverse() 1079 reverse() - splineOps 1079 RGB Controllers 1335 RGB_Multiply - TextureMap 1278 RGB_Tint - TextureMap 1278 right-click menu editor windows xlvi HTML help viewer 1722 listener window xxxviii scripted 1515 right-click menus 1514 RingArray - System 992 RingWave - GeometryClass 870 RingWave - superclass GeometryClass 328 ripple - modifier 1154 Rollout user-interface controls 1481

visibility of locals functions structures and UI items 1478 rollout accessing locals and other items from external code 1480 clauses 1470 event handlers 1474 floater windows 1477 options list of xxxiv properties methods and event handlers 1474 rollout - value 1463 Rollout .Controls Property 187 Rollout Floaters as Extended viewports 186 rollout user-interface controls bitmap 1487 button 1488 checkbox 1489 checkbutton 1490 colorpicker 1492 combobox 1493 Common Layout Parameters 1483 Common Properties 1481 dropdownlist 1494 edittext 1496 image buttons 1513 label 1497 listbox 1497 mapbutton 1499 materialbutton 1500 pickbutton 1504 progressbar 1505 radiobuttons 1506 slider 1507 spinner 1509 timer 1512 Types 1484 RolloutFloater - Value 1477 rollouts closing xxxiv creating new scripts xliv developing l loading lvi reexecuting script l

Index

1861

run script option xlix updating l utilities l Rollup Systems 188 rotate() 598 rotation_list interfaces 505 Rotation_Reactor interfaces 507 Rotation_Wire interfaces 508, 572 RotationController - MAXWrapper 1303 RotationList - superclass RotationController 328 RotationList interfaces 510 RotationReactor - superclass RotationController 328 RotationReactor interfaces 512 RubberBanding in pickObject() Function 136 run script listener window command xxxviii running code aborting lv conflicts with 3D Studio MAX lv running scripts xxxiv, xlix, lvii running the OLE demo 1674 runtime - detecting errors liii

S
Sample Scripts 1730 save as editor windows commands xlvi listener window command xxxviii save() 755 Saving your Commands in a Script File 621 scale() 598 scale_list interfaces 513 Scale_Reactor interfaces 515 Scale_Wire interfaces 515, 574 ScaleController - MAXWrapper 1304 ScaleList - superclass ScaleController 328 ScaleList interfaces 517 ScaleReactor - superclass ScaleController 329 ScaleReactor interfaces 519 scanlineRender const StructDef 252 Scatter - GeometryClass 891 Scene File Properties 1628 Schematic View 1615 schematicView const StructDef 252

scope of variables 646 script controller dialog - aborting code lv script controllers 1329 script files and editor windows xliv example scripts 624 executing content xlix global scope xlix inserting into code lix nesting lix run existing xlix running from the command line lvii saving xliv startup lvi Scripted Cameras 94 Scripted Custom Attributes 45 Scripted Manipulators 97 scripted mouse tool event handlers 1531 scripted mouse tools 1531 scripted plug-ins Atmospheric 1569 clauses 1542 defining 1538 geometry 1555 Helper 1561 Light 1561 Material 1565 methods 1551 Modifier 1562 RenderEffect 1566 Shape 1560 SimpleMod 1563 SimpleObject 1556 TextureMap 1566 updating 1553 scripted plugins events 93 scripted right-click menus 1514 scripted utilities l, 1463 available list of xxxiv defining xxxiv scripted utility panels 1464 Scripted_Behavior ReferenceTarget 1799 scripting vertex and control point animation 1461 scripts and sub-objects l

1862

Index

automatic loading lvi choosing existing xxxiv creating new xliv description of purpose 624 included with 3DS MAX 624 installing as toolbar buttons xxxii interrupt detection lv managing large scripts lix navigating large scripts xlvi new in editor windows xlvi packaging xxxii running xxxiv, xlix runtime errors liii stepping through 624 writing new xxxiv SDeflector - SpacewarpObject 1030 SDynaFlect - SpacewarpObject 1020 SDynaflector - superclass SpacewarpObject 329 searching for help topics 1718 searching text editor windows xliv listener window xxxvii restricting xlvi restrictions xxxviii section - shape 959 section - superclass shape 330 Seek_Behavior ReferenceTarget 1807 select all editor windows command xlvi listener window command xxxviii Select by Name 1619 selectBitMap() 755 selecting text - multiple lines xxxviii Selection Filter 61 selection-relative scene objects l SelectionSet values 785 SelectionSetArray values 783 selectSaveBitMap() 755 Self_Illumination - superclass MAXObject 331 separator 1519 set context 689 SetBackground Method 180 SetDir 136 SetEndTime() - ik 1313 setFirstKnot() 1079 setFirstSpline() 1079

setIndexedPixels() 755 setInVec() 1079 SetIterations() - ik 1313 setKnotPoint() 1079 setKnotSelection() 1079 setKnotType() 1079 setOutVec() 1079 setPixels() 755 setSegmentType() 1079 setSegSelection() 1079 setSilentMode() 755 setSplineSelection() 1079 SetStartTime() - ik 1313 Setting explosion start and end times for Combustion 1341 setting up MAXScript OLE automation 1673 ShadowRenderElement - superclass MAXObject 332 Shape scripted plug-ins 1560 SplineShape 1079 shape Arc 949 Circle 950 common properties operators and methods 945 CV_Curve 964 Donut 951 Ellipse 953 Helix 954 Line 955 NGon 957 Node 944 NURBS Curves 964 Point_Curve 965 Rectangle 958 Section 959 Splines 947 Star 960 Text 962 ShapeMerge - GeometryClass 893 shellac - material 1233 short-circuiting logical expressions 675 Shortcut system replaced 137 showClass() 593 showTextureMap() function 167

Index

1863

silentMode() 755 simple expressions 669 skew - modifier 1155 skin - modifier 1157 skinOps const StructDef 253 skipping loop iterations 696 slave controllers 1333 Slave_Control - Matrix3Controller 1333 SliceModifier - modifier 1165 slider 1507 sliderManipulator - superclass helper 333 sliderManipulator interfaces 520 SlidingDoor - GeometryClass 901 SlidingWindow - GeometryClass 902 smoke - TextureMap 1279 smooth - Modifier 1166 snapMode 182 snapMode const StructDef 254 snow - GeometryClass 931 SOmniFlect - SpacewarpObject 1031 sound - helper 989 source code layout 580 source code layout and continuation lines lvii Space_Warp_Behavior 1809 SpaceBend - SpacewarpObject 1011 SpaceCameraMap - SpacewarpModifier 1199 SpaceDisplace - SpacewarpObject 996 SpaceFFDBox - SpacewarpObject 998 SpaceFFDCyl - SpacewarpObject 999 SpaceNoise - SpacewarpObject 1012 SpacePatchDeform - SpacewarpModifier 1199 SpacePathDeform - SpacewarpModifier 1200 SpaceRipple - SpacewarpObject 1001 spaces and other special characters in pathnames 665 SpaceSkew - SpacewarpObject 1014 SpaceStretch - SpacewarpObject 1015 SpaceSurfDeform - SpacewarpModifier 1201 SpaceTaper - SpacewarpObject 1016 SpaceTwist - SpacewarpObject 1017 Spacewarp Dynamics Interface 1018 Geometric/Deformable 993 Modifier-Based 1011 Particles Only 1024 Spacewarp - particles and dynamics 1003 SpaceWarp Binding SpacewarpModifiers 1196

SpacewarpModifier Displace_Mesh 1198 Displace_NURBS 1198 MapScaler 1198 SpaceCameraMap 1199 SpacePatchDeform 1199 SpacePathDeform 1200 SpaceSurfDeform 1201 SpaceWarp Binding 1196 Surface_Mapper 1202 Types 1100 SpacewarpModifier - MAXWrapper 1095 SpacewarpObject Bomb 993 ConformSpaceWarp 995 Deflector 1024 Gravity 1003 Motor 1004 Path 1025 PBomb 1006 PDynaFlect 1019 POmniFlect 1027 PushSpaceWarp 1008 SDeflector 1030 SDynaFlect 1020 SOmniFlect 1031 SpaceBend 1011 SpaceDisplace 996 SpaceFFDBox 998 SpaceFFDCyl 999 SpaceNoise 1012 SpaceRipple 1001 SpaceSkew 1014 SpaceStretch 1015 SpaceTaper 1016 SpaceTwist 1017 SpaceWave 1002 UDeflector 1033 UDynaFlect 1022 UOmniFlect 1034 Wind 1010 SpacewarpObject - Node 992 SpaceWave - SpacewarpObject 1002 special characters in pathnames 665 special data values 753 special notes about function calls 678 speckle - TextureMap 1280

1864

Index

Specular - superclass MAXObject 334 specularRenderElement - superclass MAXObject 335 Speed_Vary_Behavior ReferenceTarget 1809 sphere - GeometryClass 872 SphereGizmo - helper 983 spherify - modifier 1167 spindle - GeometryClass 873 spinner 1509 Spinner UI Item setKeyBrackets 182 splat - TextureMap 1281 spline common properties operators and methods 947 Shape 947 splineOps attachMultiple() 1079 close() 1079 cycle() 1079 delete() 1079 detach() 1079 divide() 1079 explode() 1079 hide() 1079 intersect() 1079 makeFirst() 1079 mirrorBoth() 1079 mirrorHoriz() 1079 mirrorVert() 1079 reverse() 1079 startAttach() 1079 startBind() 1079 startBreak() 1079 startChamfer() 1079 startConnect() 1079 startCreateLine() 1079 startCrossInsert() 1079 startExtend() 1079 startFillet() 1079 startInsert() 1079 startOutline() 1079 startRefine() 1079 startRefineConnect() 1079 startSubtract() 1079 startTrim() 1079 startUnion() 1079

unbind() 1079 unhideAll() 1079 weld() 1079 splineOps const StructDef 255 SplineSelect - modifier 1167 SplineShape - shape 1079 spray - GeometryClass 933 spring - GeometryClass 883 Spring Controller 109 SpringPoint3Controller - superclass Point3Controller 336 SpringPositionController - superclass PositionController 337 SpringPositionController interfaces 526 squeeze - modifier 1167 SSpawnflector - superclass SpacewarpObject 338 standard objects - geometry 852 standard open and save file dialogs 1643 StandardMaterial - material 1224 StandardXYZGen - material 1238 star - shape 960 startAttach() - splineOps 1079 startBind() - splineOps 1079 startBreak() - splineOps 1079 startChamfer() - splineOps 1079 startConnect() - splineOps 1079 startCreateLine() - splineOps 1079 startCrossInsert() - splineOps 1079 startExtend() - splineOps 1079 startFillet() - splineOps 1079 startInsert() - splineOps 1079 startObjectCreation() 138 startOutline() - splineOps 1079 startRefine() - splineOps 1079 startRefineConnect() - splineOps 1079 startSubtract() - splineOps 1079 startTrim() - splineOps 1079 startUnion() - splineOps 1079 startup MAXScript xxxiv organizing scripts lvi script files lvi scripts directory lvii status bar 1577 status bar buttons 1579 sticky contexts 689

Index

1865

STL_Check - modifier 1169 storing desktop state lvi stream values 763 stretch - modifier 1170 String literals 660 values 722 string operations 588 string variables 585 StringStream values 766 struct 707 structure definition 707 structure definitions 618 structure inherited methods 711 stucco - TextureMap 1282 subAnims 806 sub-expressions displaying values xxxviii line breaks lvii subMenu 1520 sub-object transform properties 1099 subtraction - mesh 852 Sunlight - System 991 Sunlight_Slave_Controller 991 superclasses read-only global variable 139 SuperSpray - GeometryClass 935 surface - modifier 1171 Surface_Arrive_Behavior MAXObject 1811 Surface_Follow_Behavior ReferenceTarget 1814 Surface_Mapper - SpacewarpModifier 1202 SurfacePositionController - PositionController 1334 SurfDeform - modifier 1171 swirl - TextureMap 1283 Symbolic Pathnames 140 symbols 627 syntax lx syntax definitions in this document lx sysInfo const StructDef 255 System Bones 991 RingArray 992 Sunlight 991 system Biped 1456 System - Node 991 system directories 1625

system global variables 630 System Information 141 System Tools 112 systemTools const StructDef 256

T
tape - helper 981 taper - modifier 1173 Targa interfaces 529 TargetCamera - camera 976 TargetDirectionalLight - light 972 TargetObject - GeometryClass 874 TargetSpot - Light 973 TCB controller keys 1335 TCB controllers 1334 teapot - GeometryClass 875 terrain - GeometryClass 894 terrainOps const StructDef 256 tessellate - modifier 1174 TexOutputClass - material 1239 text and editor windows xliv capturing xli color coding xxxvii dragging to toolbars xxxviii editing in listener window xxxviii evaluating selection xxxviii executing current xxxviii in current bracket xxxviii inserting new xxxviii restoring xxxviii restricting search xlvi searching in listener window xxxvii selecting multiple lines xxxviii syntax coloring xlvi text - shape 962 text file input and output 1643 TextureMap Adobe_Photoshop_Plug_In_Filter 1241 Adobe_Premiere_Video_Filter 1242 BitmapTexture 1243 Bricks 1245 Cellular 1247 Checker 1249 common properties operators

1866

Index

and methods 1235 CompositeTextureMap 1250 Dent 1251 Falloff 1252 FalloffTextureMap 1255 FlatMirror 1255 Gradient 1257 Gradient_Ramp 1259 Marble 1261 Mask 1262 Mix 1262 Noise 1263 NoTexture 1265 Output 1265 Paint 1266 Particle_Age 1266 Particle_MBlur 1267 Perlin_Marble 1268 Planet 1269 Raytrace 1271 Reflect_Refract 1276 RGB_Multiply 1278 RGB_Tint 1278 scripted plug-ins 1566 Shared Classes 1236 Smoke 1279 Speckle 1280 Splat 1281 Stucco 1282 Swirl 1283 Thin_Wall_Refraction 1284 Types 1240 Vertex_Color 1285 Water 1286 Wood 1287 TextureMap - Material 1234 The Super Class ID and the Class ID 141 Thin_Wall_Refraction - TextureMap 1284 third-party plug-in classes 808 throw() 697 time change callback 1654 time configuration dialog 1616 time control 1580 time data values 751 time literal 662 time stamping 1664 time values 751

timeConfiguration const StructDef 256 timer 1512 Timer UI element 183 TimeSensor - yelper 990 TimeSlider on/off toggle 183 tokens comments lvii inserting files lix tool clauses 1532 toolbar HTML help viewer 1721 toolbar buttons creating in macro script l installing with scripts xxxii toolMode const StructDef 257 tools scripted mouse 1531 scripting for specific job xxxii selecting in macro recorder l TopBottom - material 1233 torus - GeometryClass 875 Torus_Knot - GeometryClass 877 TouchSensor - Helper 990 trace-back of call stack liii Track View 1609 Track View nodes 1382 Track View Pick Dialog 1617 trackbar 1581 trackbar const StructDef 257 trackView const StructDef 257 Trackviews 114 transform properties - sub-object 1099 transform_script - superclass Matrix3Controller 339 transformation moving 598 rotating 598 scaling 598 transformations 603 trigonometric functions 1675 Trim_Extend - modifier 1175 TriMesh 1041 TriPatch - GeometryClass 904 try expression 697 tube - GeometryClass 878 Turn_to_Mesh - superclass modifier 340

Index

1867

Turn_to_Patch - superclass modifier 342 Turn_to_Poly - superclass modifier 343 twist - modifier 1175 type #integer parameters in scripted plug-in parameter blocks 93 type-free variables 653

U
-U switch (command line) lvii UDeflector - SpacewarpObject 1033 UDynaDeflector - superclass SpacewarpObject 345 UDynaFlect - SpacewarpObject 1022 UI setting - customizing lvi unbind() - splineOps 1079 unBindKnot() 1079 undefined value 753 unDisplay() 755 undo editor windows commands xlvi listener window command xxxviii undo context 687 Undo/Redo Dropdown Labels 184 unhideAll() - splineOps 1079 unhidesegments() 1079 union - mesh 852 units const StructDef 258 unsupplied value 754 Unwrap_UVW - modifier 1176 Unwrap_UVW interfaces 530 UOmniFlect - SpacewarpObject 1034 updateBindList() 1079 updateChangedXRefs() - xrefs 1038 updateShape() 1079 updateXRef() 1038 updating scripted plug-ins 1553 useLargeVertexDots - preferences 1603 user interface colors 1604 user-defined properties - node methods 848 useTransformGizmos - preferences 1603 useVertexDots - preferences 1603 using HTML help viewer 1715 listener xxxvii MAXScript documentation xxxiii using the NURBS classes and functions to create

and modify 3ds max NURBS models 1389 USpawnDeflector - superclass SpacewarpObject 346 utilities defining l list in MAXScript l scripted l displaying xxxiv Utilities Global Utilities and Render Element plug-ins 161 utility clauses 1466 event handlers 1474 managing multiple rollouts 1468 properties methods and event handlers 1474 scripted 1463 scripted utility panels 1464 utility panel xxxiv, l UVGenClass - material 1237 UVW_Xform - modifier 1187 UVWmap - modifier 1188 uvwMappingHeightManip interfaces 551 uvwMappingLengthManip interfaces 555 uvwMappingUTileManip interfaces 558 uvwMappingVTileManip interfaces 562 uvwMappingWidthManip interfaces 565 UVWUnwrap - superclass modifier 347 UVWUnwrap interfaces 568

V
validModifer() function 142 Value NURBSDisplay 1447 NURBSSelection 1448 NURBSSet 1450 NURBSSurfaceApproximation 1453 value Array 776 ArrayParameter 770 BigMatrix 748 BigMatrixRowArray 748 BipedExportInterface 1458 BitArray 791 Bitmap 755

1868

Index

Boolean 728 Box2 750 ChangeHandler 1650 Color 729 common properties operators and methods 714 DontCollect 754 EdgeSelection 790 EulerAngles 742 FaceSelection 788 FileStream 763 general 713 Interval 752 MaterialLibrary 795 Matrix3 744 MAXKey 767 MAXKeyArray 793 MAXNoteKey 818 MAXNoteKeyArray 817 MAXWrapper 808 ModifierArray 794 Name 727 NodeChildrenArray 785 Notetrack 816 NURBSObject 1402 ObjectSet 781 Ok 754 PathName 780 PhyBlendingRigidVertex 1459 PhyContextExport 1458 PhyRigidVertex 1459 Point2 736 Point3 731 Quat 738 Ray 737 RCMenu 1514 Rollout 1463 RolloutFloater 1477 SelectionSet 785 SelectionSetArray 783 String 722 StringStream 766 Time 751 Undefined 753 Unsupplied 754 VertexSelection 786

WindowStream 767 working with 716 XRefScene 1038 variables 585 3ds max system globals 630 and ? symbol xli assignment to 643 functions 701 global scope lix MAXScript system global 640 persistent globals 651 predefined globals 629 reference assignment 653 reserved global 628 scope 643, 646 type free 653 variables - 3ds max system globals preferences.useLargeVertexDots 1603 preferences.useTransformGizmos 1603 preferences.useVertexDots 1603 vector arithmetic 1677 Vector_Field SpacewarpObject 1821 vertex animation 1461 Vertex_Color - TextureMap 1285 Vertex_Colors - modifier 1191 VertexPaint - modifier 1191 VertexSelection values 786 viewport background images 1586 displaying listener windows xxxvi drawing methods 1592 grids 1587 info 1581 redraw callback 1655 refreshing 1585 transforms 1581 type 1581 viewport const StructDef 258 visibility of locals functions structures and userinterface items in rollout code 1478 Visible Class For 142 Visual MAXScript 117 Volume_Fog - atmospheric 1343 Volume_Light - atmospheric 1344 VolumeSelect - modifier 1192 Vortex - superclass SpacewarpObject 156, 347 VRML_VRBL - helper 985

Index

1869

VRML97 - helper 985

XYZ Controllers 1335

W
Wall_Repel_Behavior MAXObject 1816 Wall_Seek_Behavior MAXObject 1817 Wander_Behavior ReferenceTarget 1819 water - TextureMap 1286 wave - modifier 1194 Waveform_Float - FloatController 1335 WAVsound const StructDef 258 weld() - splineOps 1079 What 1 when construct 1650 while loop exit 697 while/do expression 694 wind - SpacewarpObject 1010 window objects - geometry 896 WindowStream values 767 with - loop exit 697 with animate context 683 wood - TextureMap 1287 working with Atmospherics 1345 Editable Meshes 1077 MAXKey Values 769 Note Tracks 818 NURBS 1384 Values 716 working with the NURBS classes 1385

Z
Z_Depth - superclass MAXObject 350 Zip-file Script Packages 122 Zoom to Bounds 184 ZRenderElement - superclass MAXObject 351

X
XForm - Modifier 1195 XRef files 1643 Xref Objects API 120 XRefObject - Node 1037 xrefPaths const StructDef 259 xrefs addNewXRefFile() 1038 attemptUnresolvedXRefs() 1038 deleteAllXRefs() 1038 findUnresolvedXRefs() 1038 getXRefFile() 1038 getXRefFileCount() 1038 updateChangedXRefs() 1038 xrefs const Structdef 259 XRefScene Values 1038

1870

Index