This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!
<param name=”package” value=”file:///G:/iDrop/example.xml”> The XML package file: <package xmlns=”x-schema:http://vizdevel/idrop/idrop-schema.xml”> <proxy defaultsrc=”file:///G:/iDrop/blob.gif”> i-Drop it!
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”: <package xmlns=”x-schema:http://vizdevel/idrop/idrop-schema.xml”> <proxy defaultsrc=”file:///G:/iDrop/blob.gif”> i-Drop Script!
63
64
Chapter 1
|
What’s New in 3ds max 4 MAXScript
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 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
Example: Here is a sample ‘foo.ds’ file. macroScript foo ( on droppable window item return window == #viewport and item != undefined and classOf item == sphere on drop window item do ( item.scale *= 1.2 item.material = meditmaterials[1] ) )
Example Remarks: The droppable handle only allows dropping when the mouse is over a sphere scene node. When dropped, that sphere will be scaled up by 1.2 and be assigned the material currently in slot 1 in the material editor.
Dropping .max files from the Windows desktop Behavior is handled differently depending on whether you drop the file on a viewport or anywhere else in the MAX UI. If you drop a scene file on a viewport, the file is MERGED. If you drop elsewhere, such as on the toolbars or menu bar, the file is OPENED, closing the currently open file. When dropping .max scene files onto a MAX viewport, either from i-drop-enabled web pages or directly from file directories, the Merge/XRef/Cancel pop-up menu that is displayed now includes an Open item, which will perform a complete file open, replacing the currently open scene. Note: Dropping .max scene file anywhere onto the MAX UI outside viewport will automatically perform a scene open.
Dropscripts from Toolbars dragging-and-dropping dropScripts from the MAX toolbars is possible. DropScripts are simply macroScripts with ‘on drop’ and optionally ‘on droppable’ handlers, as defined above. If a macroScript button on a toolbar has an ‘on drop’ handler defined, you can drag that button off the toolbar to initiate dropScript drag-and-drop. Example: Here’s a simple dropScript that applies a newly created brick material to the object that it is dropped on. Note that it also has an ‘on execute’ handler that does the same thing to the current selection. By providing both ‘on drop’ and ‘on execute’ handlers, you can make such a macroScript installable in menus, hotkeys and toolbars or droppable from toolbars, the web, etc.
65
66
Chapter 1
|
What’s New in 3ds max 4 MAXScript
macroScript dropBricks category:”DropScripts” Icon:#(”MAXScript”, 3) ( on droppable window node: return window == #viewport and node != undefined on drop window node: do node.material = standard diffuseMap:(bricks()) showInViewport:true on execute do if selection.count == 1 then $.material = standard diffuseMap:(bricks()) showInViewport:true )
Remarks: Note the use of the newly-added ‘showInViewport’ property on materials.
Drag-and-Drop script files •
You can now drop plain script files of type, .ms, .mse or .mcr, either via i-drop controls or directly from file directories. The script is simply run when it is dropped.
•
dropScripts can now supply an ‘on loaded do ...’ handler which will be called whenever the dropScript is first loaded during a drag-and-drop operation, either from the web or from a file directory. This allows the dropScript to perform any one-time initialization it might require to set up drop, such as loading ancillary files, etc.
Drag-and-drop MAXScript Zip files See also Zip-file Script Packages (p. 122) The OLE-based drag-and-drop system in MAXScript accepts the dropping of MAXScript .mzp zip packages. They can be dropped either from i-drop-enabled web pages or directly from file directories, say from the Windows Explorer or the new MAX Asset Browser. The main use for this feature is to allow script packages to be dropped into MAX and automatically run, particularly packaged dropScripts. But, since the package can contain files of any kind, it is possible to use it to drop any set of files, say a scene file and its maps & other supporting files, or a new plug-in, etc. The mzp.run control file allows you to set up arbitrary distributions of the files in the package using the extract to, copy and move commands. This can be a useful alternative to the current i-drop package-dropping mechanism, which simply places all the downloaded files listed in the i-drop to the MAX downloads directory.
.mzp drop protocol When a .mzp package is dropped, the sequence of events that occurs differs slightly, depending on whether it is dropped via an i-drop control or directly from a file directory. In summary, the i-drop first downloads the package and then extracts it, dropping from a file directory extracts directly from that file. Further, the ‘on droppable’ handler in any dropScript specified in the package is only run if the package is droped via a i-drop, dropping from a file directory is a system-controlled action that doesn’t provide any drag-over callbacks in which to run the ‘on droppable’ test.
Selection Filter
From an i-drop, the .mzp file is first downloaded to the <max>\downloads directory, along with any other files specified in the i-drop XML file, overwriting any files currently there. If the .mzp file is the first file in the i-drop file set, it is the prime dropped file and the following .mzp processing continues. The .mzp file is then extracted to a new temp directory, in the system’s main TEMP directory, and the mzp.run control file is run. If there is no mzp.run file in the package, the first file in the .mzp package is dropped, causing whatever drop protocol is appropriate for that file type. If supplied, a typical mzp.run control file will contain extract to, move and copy commands to control the disposition of the files extracted from the package, say placing any texture files in $maps & scene files in $scenes, etc. During this execution of the mzp.run file after initial load, all copies and moves are performed, and a ‘drop’ command is looked for. The file specified on the drop command is remembered for later drop processing. Any ‘run’ commands are ignored. At this point, the drop file is known, either because it was supplied on a ‘drop’ command in the mzp.run file or because it is the first file in the .mzp package if there was no mzp.run file or drop command. If the drop file is anything other than .ds dropScript file, the drop protocol appropriate to that file is engaged. If it is a .ds dropScript, and the drop is from an i-drop, any ‘on droppable’ handler in the dropscript is repeatedly run as the mouse is moved off MAX’s windows, and the cursor changes to show valid drop targets. If the drag-and-drop is from a file directory, the arrow+ cursor shows, but the ‘on droppable’ handler is NOT called. This is a consequence of the limitations of simple file drag-and-drop in Windows. When the mouse-click is released, the ‘on droppable’ handler is called on the target window and object and if it returns OK or is not supplied, the ‘on drop’ handler is called. This protocol is identical to dropping .ds dropScript files directly, as if they were not inside a .mzp package. Note: You can specify a file type other than a dropScript on the ‘drop’ command, such as an image or scene file. This allows the .mzp drag-and-drop to be used for dropping any kind of package, not just scripts.
See Also Interface: dragAndDrop (p. 362) Zip-file Script Packages (p. 122)
Interfaces Topic: version 4 MAXScript New Features/Interfaces The Function Publishing System, new to 3ds max version 4, is a system that allows plug-ins to publish their major functions and operations in such a way that code outside the plug-in can discover and make inquiries about these functions and is thus able to call them though a common calling mechanism. The whole system is very similar to Window’s COM and OLE Automation systems and share many similar concepts in the architecture. However, the Function Publishing System is not based on COM and OLE but instead is a custom architecture more suited and optimized for MAX. The Function Publishing API serves a number of purposes, which allow 3rd
67
68
Chapter 1
|
What’s New in 3ds max 4 MAXScript
party developers to open up important portions of their plug-ins for use by external sources, allowing for users to extend and control these directly. Note: For complete details on the Function Publishing System, please see the 3ds max sdk help file topic “Function Publishing System”. Interfaces Core Interfaces (p. 70) Other Interfaces (p. 71) Functions are published in one or more Interfaces by a plug-in. Action functions must be published in their own set of interfaces. Each interface is represented by an instance of a class derived from the base class FPInterface. An external system can find out about the interfaces published by calling various query methods on ClassDesc that access these interface definition objects. As well as these enquiry or ‘reflection’ methods, an FPInterface also has the calling methods for actually invoking a particular function in the interface, so that if something has hold of one of your interfaces, it can call any of its published functions. Action Interfaces Action Manager (p. 9) A special kind of interface is the Action Interface. These interfaces only contain UI Action Functions that provide a programmatic way of “pressing” buttons and keys in the UI for a plug-in. Direct dot-notation properties MAXScript exposes properties defined in this way as direct dot-notation properties on the interface. So, were before the Get/SetRadius in the example cylinder mixin would have been accessed as functions Example: r = $cyl01.cylMixin.getRadius() $cyl01.cylMixin.setRadius 23
you now can use: r = $cyl01.cylMixin.radius $cyl01.cylMixin.radius = 23
This is true for all the types of FP interfaces that turn up in MAXScript, static, mixin and core. As a further optimization, MAXScript now effectively promotes all interface methods and properties to the level of the interface, so if individual methods and properties have unique names within all the interfaces of an object or class, you can elide the interface name. The above examples could now be written Example: r = $cyl01.getRadius() $cyl01.setRadius 23
Selection Filter
and: r = $cyl01.radius $cyl01.radius = 23
If there is a naming conflict, you can always include the interface name level to resolve this. Published Functions and MAXScript MAXScript automatically provides access to all functions published by a plug-in via the Function Publishing system. Each plug-in class appears in MAXScript as a MAX class object, which can be used to construct instances of the plug-in, do class tests, etc. If a plug-in publishes interfaces, they are visible in MAXScript as properties on this class object. The internal name for the interface is used as the property name. All the functions in the interface are accessible as named properties on the interface. So, if the above example interfaces were published by EditMesh, the following script fragments would work Example: EditMesh.faceOps.extrude $foo.mesh #{1,2,3} 10
calls the Extrude function in the FaceOps interface on $foo’s mesh, faces 1, 2 and 3, amount 10 units. EditMesh.actions
retrieves and displays the action functions. Each interface is stored as a struct definition in the class object. EditMesh.actions.create()
starts (or stops) the create mode. This would have the side-effect of highlighting/unhighlighting the Create button in the EditMesh rollups. Calls to Action functions in MAXScript return true if the function returns FPS_OK and false otherwise. if EditMesh.actions.create.isChecked() then ...
The predicate functions for an Action Function are available as properties on the action function object itself, as shown. You can determine if a predicate is supplied by asking: if EditMesh.actions.create.isChecked != undefined
Associated Method: getCoreInterfaces()
Returns an array of core interface values.
See Also Core Interfaces (p. 70) Other Interfaces (p. 71) By Reference Parameter Passing (p. 129) Dereferencing Operator (p. 133) Visible Class For ‘&’ Reference Values (p. 142) Action Manager (p. 9) Class and Object Inspector Functions Enhanced (p. 159) Class and Object Inspector Functions (p. 799)
69
70
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Core Interfaces Topic: version 4 MAXScript New Features/Interfaces Interfaces (p. 67) actionMan (p. 353) BoneSys (p. 354) browserMgr (p. 355) cmdPanel (p. 356) colorMan (p. 356) dragAndDrop (p. 362) HDIKSys (p. 365) IKSys (p. 365) manip (p. 366) maxOps (p. 368) medit (p. 371) menuMan (p. 372) msZip (p. 378) netrender (p. 379) NullInterface (p. 409) objXRefs (p. 409) paramWire (p. 410) pluginManager (p. 414) quadMenuSettings (p. 414) rollup (p. 427) SceneExposureControl (p. 427) SceneRadiosity (p. 428) timeSlider (p. 428) trackviews (p. 429)
See Also Other Interfaces (p. 71) Class and Object Inspector Functions (p. 799) Class and Object Inspector Functions Enhanced (p. 159)
Other Interfaces
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)
71
72
Chapter 1
|
What’s New in 3ds max 4 MAXScript
PointCache (p. 486) PointCacheWSM (p. 487) Position Constraint (p. 488) position list (p. 490) Position Reactor (p. 492) Position Wire (p. 492) PositionList (p. 494) PositionReactor (p. 496) PositionSpring (p. 497) radiusManip (p. 500) RenderElementMgr (p. 503) rotation list (p. 505) Rotation Reactor (p. 507) Rotation Wire (p. 508) RotationList (p. 510) RotationReactor (p. 512) scale list (p. 513) Scale Reactor (p. 515) Scale Wire (p. 515) ScaleList (p. 517) ScaleReactor (p. 519) sliderManipulator (p. 520) SpringPoint3Controller (p. 523) SpringPositionController (p. 526) Targa (p. 529) Unwrap UVW (p. 530) uvwMappingHeightManip (p. 551) uvwMappingLengthManip (p. 555) uvwMappingUTileManip (p. 558) uvwMappingVTileManip (p. 562) uvwMappingWidthManip (p. 565) UVWUnwrap (p. 568) Float Wire (p. 448) Point3 Wire (p. 477)
HD IK controller chains can be assigned to existing hierarchies
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>
Parameters <startJoint>
The first node in the new chain, called the ancestor. <endJoint>
The last node in the chain, called the decendent.
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.
73
74
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Note: Both IKControl and IKChainControl can not be instanced.
See Also IKChainControl interfaces: (p. 453) Interface: HDIKSys (p. 365) Interface: IKSys (p. 365) IKLimb Solver (p. 74)
IKLimb Solver Topic: version 4 MAXScript New Features/IK The IK Limb Solver is specifically meant for animating the limbs of human characters; for example, the hip to the ankle, or the shoulder to the wrist. It affects only two bones in a chain. It is an analytical solver that is very fast and accurate in viewports. Note: To use with the IK Limb solver, a bones system must have three bones in the chain. The goal is placed at the pivot point of the third bone, and the IK solution is calculated for the first and second bones. The IK Limb solver works not only with bone hierarchies, but with any linked hierarchy that has three elements, and is set up to model a human limb. The additional requirements are: •
The first joint is “spherical.” That is, it has 3 degrees of freedom.
•
The second joint is “revolute.” That is, it has 1 degree of freedom.
If you attempt to put an IK Limb solver on an inappropriate chain, a warning message informs you that your IK Limb solver assignment has no effect. The IK Limb solver uses the same controls as the HI IK solver, so it follows the model of setting preference angles for joints, and allows for mixing periods of forward and inverse kinematics in the same animation period. It does not use the HD IK Solver methods of damping, precedence, and setting joint limits. The IK Limb solver is provided as part of the Discreet Open Source initiative, so it can be exported directly to a game engine. The joint angles are obtained by computing the transformation (rotation) between the initial chain plane and the target chain plane. The initial chain plane is defined by three unit vectors: 1. shoulder-to-elbow unit vector (at the initial pose) 2. projection of end-effector-axis on a plane perpendicular to the shoulder-to-elbow unit vector (at the initial pose) 3. cross product of the above two. Similarly, the target plane is defined by three analogous vectors at the target pose.
IKLimb Solver
See Also Interface: IKSys (p. 365) Interface: HDIKSys (p. 365) HD IK controller chains can be assigned to existing hierarchies (p. 73) IKChainControl interfaces: (p. 453)
Materials Multi/Sub Material Topic: version 4 MAXScript New Features/Material/Multi/Sub Material Each entry in the Multi/Sub matl interface now has an associated ID. The previous version had the ID being the same as the number of the sub-material in the list. This can be seen here: MultiMaterial : Material (p. 1210)
Menu Manager Topic: version 4 MAXScript New Features/Menu Manager MAXScript has full access to the menu manager and menu creation system. Note: Be very careful when using or testing this API. It makes permanent changes to the menu database, and it is very easy to mess things up quite badly. For example, if you “unRegister” the main menu bar, 3ds max won’t start. Anyone using this API should make a copy of the “..\UI\MaxMenus.mnu” file before running any of the scripts. If anything messes up, just copy the backup version back on to MaxMenu.mnu. There are 4 exposed interfaces to MAXScript: the menu manager, menu objects, quad menu objects and menu items. •
The menu manager is a database of menus and quad menus.
•
The main menubar and all sub-menus are menu objects.
•
A quad menu object holds 4 menu objects, one for each quad.
•
A menu object is a container for menu items.
•
A menu item can be a separator, an action that invokes a macroScript or a sub-menu that pops up a cascading menu.
Menu Manager menuMan.loadMenuFile “file.mnu”
This loads a new menu file with the given name. It looks in the current “UI” directory for the file. It return true if successful, and false if not. menuMan.saveMenuFile “file.mnu”
This saves a new menu file with the given name. It saves it in the current “UI” directory.
75
76
Chapter 1
|
What’s New in 3ds max 4 MAXScript
menuMan.getMenuFile()
Returns the full path to the current menu file. menuMan.updateMenuBar()
This updates the main menu bar with any changes that have been made. This MUST be called after changing anything on the main menu bar. menuMan.registerMenuContext contextId
This call is used to register menu extensions. The “contextId” is a random 32-bit integer. It can be generated using the “genclassid()” (p. 141). This function registers an extension with the menu manager that is remembered permanently. It returns true the first time the extension is registered, and false every time thereafter. This is saved in the MaxMenu.mnu file, so it is sticky from session to session. This is used so that scripts can add items and sub-menus MAX’s main menu bar and quad menus. See the sample scripts below for the proper usage. menuMan.findMenu “menuName”
This function returns the menu with the given name. It returns “undefined” if no menu exists in the menu manager with the given name. This requires the full name of the menu, including and “&” characters that might be in the name. Example: helpMenu = menuMan.findMenu “&Help”
Retrieve 3ds max’s help menu. menuMan.findQuadMenu “qhadMenuName”
This works like “findMenu” but it gets quad menus instead of menus. menuMan.unRegisterMenu menu
This removes a menu from the menu manager. Use extreme caution with this method! If you unregister a menu that is used as a sub-menu, or in a quad menu, or the main menu bar, bad things will result. menuMan.unRegisterQuadMenu quadMenu
This is like “unregisterMenu” but for quad menus. menuMan.createMenu “name”
This creates a new, empty menu with the given name. menuMan.createQuadMenu “name” “quad1Name” “quad2Name” “quad3Name” “quad4Name”
This creates a new, empty quad menu. It contains, 4 empty menus, one for each quad. menuMan.createSubMenuItem “name” subMenu
This creates a new sub-menu item that can be added to a menu. It uses the given “name” and it displays the given sub-menu. menuMan.createSeparatorItem()
This creates a new menu separator that can be added to a menu. menuMan.createActionItem “macroScriptName” “macroScriptCategory”
This creates a new menu item that can be added to a menu. The item is an action that executes the macro script with the given name and category. This returns “undefined” if there is no macroScript with the given name and category.
IKLimb Solver
menuMan.setViewportRightClickMenu which quadMenu
This sets the viewport right click menu to be the given quad menu. The value of “which” can be one of the following: #nonePressed #shiftPressed #altPressed #controlPressed #shiftAndAltPressed #shiftAndControlPressed #controlAndAltPressed #shiftAndAltAndControlPressed
Example: menuMan.setViewportRightClickMenu #nonePressed “Modeling 2”
That sets the default (no keys pressed) quad menu to “Modeling 2”. The menu name must be a quad menu that is listed in the “Quads” customization dialog, and the name must match exactly, including capitalization. menuMan.SetViewportRightClickMenu returns FALSE if you try to set the viewport right-click menu to a menu that is not allowed. menuMan.getViewportRightClickMenu which
Retrieves the quad menu used for right-clicking in the viewport. The “which” parameter can be one of the following: #nonePressed #shiftPressed #altPressed #controlPressed #shiftAndAltPressed #shiftAndControlPressed #controlAndAltPressed #shiftAndAltAndControlPressed menuMan.getMainMenuBar()
Returns the menu being used as MAX’s main menu bar. menuMan.setMainMenuBar menu
Sets the menu being used as MAX’s main menu bar. You must call “menuMan.updateMenuBar()” in order to see the result. menuMan.getShowAllQuads quadMenu
Gets the “show all quads” setting for the given quad menu. menuMan.setShowAllQuads quadMenu value
This sets the “show all quads” flag for the given quad menu. “Value” can be true or false. menuMan.getQuadMenuName quadMenu
This returns the name of the given quad menu. menuMan.setQuadMenuName quadMenu “name”
This sets the name of the give quad menu.
77
78
Chapter 1
|
What’s New in 3ds max 4 MAXScript
menuMan.numMenus()
Returns the total number of menus in registered with the menu manager. menuMan.getMenu index
Retrieves the “index” th menu in the menu manager. This is a 1-based index. menuMan.numQuadMenus()
Returns the total number of quad menus registered with the menu manager. menuMan.getQuadMenu index
Retrieves the “index” th quad menu in the menu manager. This is a 1-based index. Quad Menu objects Quad menu objects have the following functions available: quadMenu.getMenu quadIndex
Retrieves the menu object associated with the 4 quads of the menu. “quadIndex” can take the value 0, 1, 2, or 3. Quad 0 is the lower-right, and they are numbered counter-clockwise from there. quadMenu.trackMenu showAllQuads
This displays the quad menu. If “showAllQuads” is true, then all 4 quads a re shows at once. It is displayed at the current cursor position. Menu Objects Menus are containers for menu items, and have the following functions: menu.setTitle “title”
Sets the title of the menu to the give string. menu.getTitle()
Returns the current title of the menu. menu.numItems()
Returns the number of items the menu holds. menu.getItem index
Retrieves the menu item at the given index. The index is 0-based. menu.addItem menuItem position
This inserts an item in the menu at the given position, which is 0-based. If the position is -1, then the item is appended to the end of the menu. menu.removeItemByPosition position
This removes the item at the given position. menu.removeItem menuItem
This removes the given item from the menu, if it is in the menu.
IKLimb Solver
Menu Item objects A menu item can be a separator, a sub-menu or an action that is connected to a macroScript. The following functions are available for menuItems: menuItem.setTitle “title”
Sets the name associated with the item. menuItem.getTitle()
Returns the name associated with the item. menuItem.setUseCustomTitle value
When value is true, this tells an item that is associated with a macroScript to use the item title when displaying the menu. Otherwise it will use the name of the macro or the “buttontext” of the macroScript. menuItem.getUseCustomTitle()
Returns the current value of the custom title flag. menuItem.setDisplayFlat value
This is for sub-menu items. When value is true, it tells the menu to display the sub-menu in-line, rather than as a cascading sub-menu. menuItem.getDisplayFlat()
Returns the current value for the “display flat” flag. menuItem.getIsSeparator()
Returns true if the item is a separator, and false otherwise. menuItem.getSubMenu()
If the item is a sub-menu item, this returns the menu associated with the sub-menu. Included below is a script that shows how to use the menuMan interface to register menu extensions. This script should go in the “stdplugs\stdscripts” folder. Example: -- Sample menu extension script -- If this script is placed in the “stdplugs\stdscripts” -- folder, then this will add the new items to MAX’s menu bar -- when MAX starts. -- A sample macroScript that we will attach to a menu item macroScript MyTest category:”Menu Test” tooltip:”Test Menu Item” ( on execute do print “Hello World!” )
Example: --------
This example adds a new entry to MAX’s main “Help” menu. Register a menu context. This returns true the first time it is registered, and we can add things to the menu. If it returns false, then the context is already registered, and the items are already in the menu. The number 0x246c6dbe is random, and can be generated using the genClassID() function (p. 141).
79
80
Chapter 1
|
What’s New in 3ds max 4 MAXScript
if menuMan.registerMenuContext 0x246c6dbe then ( -- Get the main menu bar local mainMenuBar = menuMan.getMainMenuBar() -- The help menu is always the last menu. local helpMenuIndex = mainMenuBar.numItems() -- Get the menu item that holds the help menu local helpMenuItem = mainMenuBar.getItem(helpMenuIndex) -- Get the menu from the item local helpMenu = helpMenuItem.getSubMenu() -- create a menu separator item local sepItem = menuMan.createSeparatorItem() -- create a menu items that calls the sample macroScript local testItem = menuMan.createActionItem “MyTest” “Menu Test” -- Add the separator to the end of the help menu. -- the position of -1 means add it to the end. helpMenu.addItem sepItem -1 -- Add the action item to the end of the help menu. helpMenu.addItem testItem -1 -- redraw the menu bar with the new item menuMan.updateMenuBar() )
Example: -- This example adds a new sub-menu to MAX’s main menu bar. -- It adds the menu just before the “Help” menu. if menuMan.registerMenuContext 0x1ee76d8e then ( -- Get the main menu bar local mainMenuBar = menuMan.getMainMenuBar() -- Create a new menu local subMenu = menuMan.createMenu “Test Menu” -- create a menu item that calls the sample macroScript local testItem = menuMan.createActionItem “MyTest” “Menu Test” -- Add the item to the menu subMenu.addItem testItem -1 -- Create a new menu item with the menu as it’s sub-menu local subMenuItem = menuMan.createSubMenuItem “Test Menu” subMenu -- compute the index of the next-to-last menu item in the main menu bar local subMenuIndex = mainMenuBar.numItems() - 1 -- Add the sub-menu just at the second to last slot mainMenuBar.addItem subMenuItem subMenuIndex -- redraw the menu bar with the new item menuMan.updateMenuBar() )
IKLimb Solver
Example: -- This example adds a new command to MAX’s default right-click quad menu if menuMan.registerMenuContext 0x36690115 then ( -- Get the default viewport right-click quad menu local quadMenu = menuMan.getViewportRightClickMenu #nonePressed -- Get the lower-left menu from the quad local menu = quadMenu.getMenu 3 -- create a menu item that calls the sample macroScript local testItem = menuMan.createActionItem “MyTest” “Menu Test” -- Add the item to the menu menu.addItem testItem -1 )
Example: Here are two macroScripts that set and reset two of the right-click menus: macroScript SetQuads category:”Custom UI” tooltip:”Set Quad” ( on execute do ( quadmenu = menuMan.findQuadMenu “Modeling 2” if quadmenu != undefined do menuMan.setViewportRightClickMenu #nonePressed quadmenu quadmenu = menuMan.findQuadMenu “Sample 4x1” menuMan.setViewportRightClickMenu #controlPressed quadmenu ) ) macroScript ResetQuads category:”Custom UI” tooltip:”Reset Quads” ( on execute do ( quadmenu = menuMan.findQuadMenu “Default Viewport Quad” if quadmenu != undefined do menuMan.setViewportRightClickMenu #nonePressed quadmenu quadmenu = menuMan.findQuadMenu “Modeling 1 [Cntrl+RMB]” if quadmenu != undefined do menuMan.setViewportRightClickMenu #controlPressed quadmenu ) )
81
82
Chapter 1
|
What’s New in 3ds max 4 MAXScript
You can display a quad menu like this: menuMan.trackQuadMenu “Default Viewport Quad”
The menu name must be a quad menu that is listed in the “Quads” customization dialog, and the name must match exactly, including capitalization.
See Also Quad Menu (p. 90) Menu and CUI Loading (p. 178) maxOps (p. 87) Interface: quadMenuSettings (p. 414) Interface: menuMan (p. 372) Interface: maxOps (p. 368)
Mesher Topic: version 4 MAXScript New Features/Mesher The Mesher compound object converts procedural objects to mesh objects on a per-frame basis so that you can apply modifiers such as Bend or UVW Map. It can be used with any type of object, but is designed primarily to work with particle systems. Mesher is also useful for low-overhead instancing of objects with complex modifier stacks.
See Also Mesher - superclass: GeometryClass (p. 298) particleMesher - superclass: GeometryClass (p. 306)
Network Render Interface Topic: version 4 MAXScript New Features/Network Render Interface The interface is fully described here: Interface: NetRender (p. 379) Network Rendering is the rendering of animations using more than one computer connected by a network. Large and complex animations take many hours to render, even on the fastest PCs. Network rendering allows you to use the power of other 3ds max enabled computers to speed up the process. Note: For additional details regarding network rendering, please see the topic “Network Rendering” in the 3ds max online reference.
See Also 3D Studio MAX System Globals (p. 630)
IKLimb Solver
Node Handles Topic: version 4 MAXScript New Features/Node Handles A property has been added to a node’s interface called .handle. This can be used to get the unique node handle ID from the node. Usage: id = $Box01.handle-- returns the unique id associated with the node A method in the maxOps interface (p. 368) will return a node associated with a given handle. Usage: node = maxOps.getNodeByHandle -- returns the node associated with the id passed in. Note: It is safer to say $box01.inode.handle than $box01.handle. This is to prevent cases where the baseobject has property called handle, like a teapot, and you get that object’s handle instead of the node handle.
See Also maxOps (p. 87)
Node vertexColorType Topic: version 4 MAXScript New Features/Node vertexColorType In the node interface, the vertexColorType property has been changed to take a symbolic enum. This is the assigned vertex color displayed in viewports. .vertexColorType : enum : Read|Write vertexColorType enums: {#color|#illum|#alpha|#color_plus_illum}
Example: $Sphere01.vertexColorType = #illum
See Also Node : MAXWrapper (p. 820) Node Common Properties, Operators, and Methods (p. 820) Node Handles (p. 83) Class and Object Inspector Functions Enhanced (p. 159) Access to the node bone properties and methods (p. 23)
83
84
Chapter 1
|
What’s New in 3ds max 4 MAXScript
OLE Automation MAXScript.reg - Registery file Topic: version 4 MAXScript New Features/OLE Automation The last line has to be edited to point at your current 3ds max exe location. Save the file as MAXScript.reg. Then just double-click it in Windows Explore to register with the Windows Registery. ;-------- cut here ------------REGEDIT ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; registration info MAX.Application (defaults to MAX.Application.4) HKEY_CLASSES_ROOT\MAX.Application = OLE Automation MAX Application HKEY_CLASSES_ROOT\MAX.Application\Clsid = {7FA22CB1-D26F-11d0-B260-00A0240CEEA3} ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; registration info MAX 4.0 ; (Application Object) HKEY_CLASSES_ROOT\MAX.Application.4 = OLE Automation MAX 4.0 Application HKEY_CLASSES_ROOT\MAX.Application.4\Clsid = {7FA22CB1-D26F-11d0-B260-00A0240CEEA3} HKEY_CLASSES_ROOT\CLSID\{7FA22CB1-D26F-11d0-B260-00A0240CEEA3} = OLE Automation MAX 4.0 Application HKEY_CLASSES_ROOT\CLSID\{7FA22CB1-D26F-11d0-B260-00A0240CEEA3}\ProgID = MAX.Application.4 HKEY_CLASSES_ROOT\CLSID\{7FA22CB1-D26F-11d0-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
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)
85
86
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Plug-In Manager Topic: version 4 MAXScript New Features/Plug In Manager The Plug-in Manager lets you manage plug-ins dynamically without any initialization required. The Plug-in Manager provides a list of all plug-ins found in the 3ds max plug-in directories, including the plug-in description, type (object, helper, modifier, and so on), status (loaded or deferred), size, and path. The Plug-in Manager provides options to load or tag as deferred, any particular plug-in, regardless where they reside on disk. When you start the Plug-in Manager, it scans through all the plug-in paths specified in the plug-in.ini file and lists them in the Plug-in Manager dialog.
Actually there are two different FP interfaces in the plug-in manager, one is a action interface accessed through Plug-in_manager and the other one is a static interface called plug-inManager. You can access the static interface like plug-inManager.show = true
or: plug-inManager.loadClass Flex
Currently there is no way to integrate these into one so. Properties: plug-inManager.visible = true --show plug-inManager.visible = false –hide
Remarks: Show and hide the plug-in manager.
maxOps
Prototype: plug-inManager.loadClass
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
87
88
Chapter 1
|
What’s New in 3ds max 4 MAXScript
maxOps.licenseBehavior the enum values returned are as follows: #licenseBehaviorPermanent - permanent license, or hardware lock #licenseBehaviorExtendable - term license, can be extended #licenseBehaviorNonextendable - term license, cannot be extended
maxOps.licenseDaysLeft Its return value is an integer indicating the number of full days left in the term of the license. A value of 0 means that today is the last day of validity. For permanent licenses, a fixed value is returned indicating greater than 10 years are left. Note: It should be noted that the all copies of 3ds max return a hardwarelockid (p. 630) of “-1” while under the grace period and until they have been authorized. You can check for that number and initiate your own demo mode. maxOps.getNodeByHandleNode_Handles Returns the node associated with the id passed in. maxOps.setSelectionType <method>
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: CloneNodes nodes offset expandHierarchy: cloneType:<enum> actualNodeList:<node array> newNodes:<node array>
maxOps
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)
89
90
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Quad Menu Topic: version 4 MAXScript New Features/Quad Menu When you click the right mouse button anywhere in an active viewport, except on the viewport label, the program displays a Quad menu at the mouse cursor. The quad menu can display up to four quadrant areas with various commands. In the MAXScript listener window, type apropos “quadmenusettings” to see the list of functions available. The Quad menu is set in the startup scripts directory called QuadOptions_Startup.ms. The two right quadrants of the default quad menu display generic commands, which are shared between all objects. The two left quadrants contain context-specific commands, such as mesh tools and light commands. Each of these menus provides convenient access to functions found in the command panel. The quad menu contents depend on what is selected, as well as any customization options you may have selected in the Quads panel of the Customize UI dialog. The menus are set up to display only the commands that are available for the current selection, therefore selecting different types of objects displays different commands in the quadrants. Consequently, if no object is selected, all of the object-specific commands will be hidden. If all of the commands for one quadrant are hidden, the quadrant will not be displayed. Note: PickObject() does not pick objects when launched from a Quad Menu. It will hang and refuses to pick any object. Hit ‘escape’ for emergency exit. PickObject works correctly from a shortcut and toolbar.
See also Interface: quadMenuSettings (p. 414) ApplyOperation function (p. 54) Menu Manager (p. 75) Interface: menuMan (p. 372) Menu and CUI Loading (p. 178)
Reactor controller
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()
91
92
Chapter 1
|
What’s New in 3ds max 4 MAXScript
ct = reactor.reactions.getCount() format “Reactor Statistics: \n------------------------------\n \n” to:ss format “Count : %\n” ct to:ss format “\n” to:ss for i = 0 to ct-1 do ( format “Reaction #: % \n-----------------------------------------------Name : % State: % Value: % Strength: % Influence : % Falloff: % \n\n” (i) (reactor.reactions.getName i) (getReactionState reactor (i+1)) (getReactionValue reactor (i+1)) (reactor.reactions.getStrength i) (reactor.reactions.getInfluence i ) (reactor.reactions.getFalloff i ) to:ss ) print ss
See Also Reactor Controllers (p. 1326) Float Reactor interfaces: (p. 443) Point3 Reactor interfaces: (p. 477) Scale Reactor interfaces: (p. 515) Position Reactor interfaces: (p. 492)
Render Element Manager Topic: version 4 MAXScript New Features/Render Element Manager Rendering to elements lets you separate various information in the rendering into individual image files. This can be useful when you work with some image-processing or special-effects software. You can later do compositing with the element renderings. When you render one or more elements, a normal complete rendering is also generated. In fact, the element renderings are generated during the same rendering pass, so rendering elements costs little extra render time. Rendering to elements is available only when you do production rendering with the default scanline renderer. RenderElementMgr interfaces: (p. 503) This is the interface for the Render Element Manager.
See Also Interface: maxOps (p. 368) Combustion (p. 38)
type:#integer parameters in scripted plug-in parameter blocks
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.
93
94
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also Scripted Plug-ins (p. 1538) type:#integer parameters in scripted plug-in parameter blocks (p. 93) Scripted Cameras (p. 94)
Scripted Cameras Topic: version 4 MAXScript New Features/Scripted Plug-In/Scripted Cameras Scripted camera plug-ins can now be written in MAXScript. At present, you can write either extending camera plug-ins that extend existing MAX cameras or temporary camera plug-ins that can be used to host create tools for a custom camera system. The plug-in superclass for cameras is ‘camera’. An event handler is available to scripted cameras that gives access to the CameraObject::renderApertureChanged callbacks made by the rendering dialog to a camera when the user adjusts parameters that affect render aperture. The new handler is optional. on renderApertureChanged val do ....
The ‘val’ parameter contains the new render aperture value. This typically gets called when you select a new apeture in the Output Size dropdown in the render dialog or adjust a spinner when in Custom mode. There are several cases where this handler is called: •
In the Render Scene dialog, if Image Aspect is unlocked and you change Width, Height, or Pixel Aspect
•
In the Render Scene dialog, if you click on one of the output size preset buttons
•
In the Render Scene dialog, if Image Aspect is locked and you change Width, Height, or Pixel Aspect, or if you change Aperture Width, and then click on either Render or Close
The value being passed into handler is the aperture width. You can get the remaining values via: renderWidth, renderHeight, and RenderPixelAspect global variables. However, what you get for these values are typically the old value, with the exception of the Aperture Width value. The call to the handler is coming from a “InvalidateCameras” method, which is called right before setting the new values. Doesn’t look like any broadcasts are made after the new values are set, and if safe frames isn’t turned on in any viewport, none of the viewports are redrawn. We recommend that if a scripted camera uses this handler, it should cache the old Aperture Width value and test the incoming value against the cached value before proceeding.
dependsOn For Scripted Controllers
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
95
96
Chapter 1
|
What’s New in 3ds max 4 MAXScript
established the first time the controller is evaluated after any script change or recompile. This can be when editing in a controller property box, or after a scene load. You can programmatically force a recompile and reset of the dependents by setting the control script to itself: $foo.pos.controller.script = $foo.pos.controller.script
See Also script controllers (p. 162)
Matrix3 Scripted Controller Topic: version 4 MAXScript New Features/Scripted Plug-In/Scripted Controllers The Transform Script controller contains all of the information contained in a Position/Rotation/ Scale (PRS) controller in one scripted matrix value. Instead of having three separate tracks for position, rotation, and scale, all three values can be simultaneously accessed from one script controller dialog. Because a script defines the transform values, they are easier to animate. The value of the controller script must be a matrix3 value. A matrix3 value is a 4x3 3D transformation matrix. For more information, see the Matrix3 Values topic in the MAXScript reference. The software interprets the text you type into the Script text box as the body of a MAXScript block expression. You can type as many expressions as you want on as many lines as you want, and they are evaluated in turn. The value of the last expression is taken as the controller value. This must yield a matrix3 value for Transform Script controllers. Since the text is inside a block expression, you can declare local variables, which are visible only within the script and are temporary for one evaluation. You can also declare or access global variables that are shared with all other scripts in MAXScript and hold their values from one evaluation to the next. The software with respect to a specific animation time always evaluates a controller. This might be the current time slider or incrementing frame time if an animation is playing, or a rendering is under way. In the case of Script controllers, the time being evaluated is used to establish an automatic “at time” context around the controller script, so any properties you access (outside of other explicit “at time” expressions) yield the correct values for the current controller evaluation time. This means you don’t have to do anything special in your scripts to work at the correct time. You can access the evaluation time, with the standard MAXScript variable, current Time. You can also reference scene property values at other times by using “at time” expressions in your scripts, as in regular MAXScript programming. Example: t=transform_script() t.script = “(matrix3 1)”
Matrix3 Scripted Controller
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
97
98
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Radius Manipulator The radius manipulator is fairly simple, so it makes a good example to describe the scripted manipulator system. The code for the manipulator is included below, followed by a detailed description of how it works. --------------------------------------------------------------------- Generic radius manipulator -- Written by Scott Morrison -- This manipulator sets the radius on any object or modifier with -- a parameter named “radius”. It creates a circle gizmo of the appropriate -- radius centered at the origin in the XY plane. plug-in simpleManipulator radiusManip name:”RadiusManip” invisible:true ( -- Create the green and red colors for the gizmo local g = [0, 1, 0], r = [1, 0, 0] -- This manipulator manipulates any node with a “radius” property on canManipulate target return (findItem (getPropNames target) #radius) != 0 -- Create the manipulator gizmo. -- This is called initially and whenever the manipulator target changes on updateGizmos do ( -- Clear the current gizmo cache this.clearGizmos() -- Set the radius of circle gizmo a little bigger than the target radius giz = manip.makeCircle [0,0,0] (target.radius * 1.01) 28 -- Add the circle to the manipulator this.addGizmoShape giz 0 g r -- return the ToolTip string return node.name + “ radius = “ + target.radius as string ) -- mouseMove is called on every mouse move when dragging the manip -- It needs to convert the mouse position ‘m’ into a new value for the radius on mouseMove m which do ( -- Create the XY plane. -- manip.makePlaneFromNormal takes a normal vector and a point -- and creates a plane passing through the point with the given normal local pl = manip.makePlaneFromNormal z_axis [0, 0, 0], projectedPoint = [0,0,0] -- Compute the hit-ray in local coordinates viewRay = this.getLocalViewRay m -- Intersect the plane with the view ray res = pl.intersect viewRay &projectedPoint
Matrix3 Scripted Controller
-- If the intersection worked, set the radius if (res) then target.radius = (length projectedPoint) / 1.01 ) ) --------------------------------------------------------------------
The header: plug-in simpleManipulator radiusManip name:”RadiusManip” invisible:true
Indicates to MAXScript that this is a scripted manipulator plug-in called “RadiusManip”. The “invisible:true” tells the system not to make a creation button for the manipulator in the create panel. The body: A set of handlers for various events. on canManipulate target return (findItem (getPropNames target) #radius) != 0
“canManipulate” is called on every manipulator, for every node that is selected when the “Manipulate” button is pressed. The “target” parameter is the object that we might potentially manipulate. It is called on the base object, all the modifiers on the object, and transform controllers on the object’s node. Also, if the transform controller is a PRS controller, it calls “canManipulate” on the position, rotation and scale controllers. In the case of the radius manipulator, it can manipulate any object that has a property named “radius”. If you want to create a manipulator that works on a specific object type, say a sphere, you can say: on canManipulate target return classOf target == sphere
There is an alternative handler that may be needed in some cases called “canManipulateNode n”. This is called passing in the each selected node to the handler. This is not normally needed, but available if your manipulator wants to manipulate property of a node other than the ones that are passed as the “target” to “canManipulate”. Note: A Scripted Plug-in should only implement one of these handlers, not both. The next handler is called “updateGizmos,” and this is called whenever a manipulator need to build its gizmos. This happens when the manipulator is created, and whenever the target that it is manipulating changes. When MAXScript creates a manipulator, it sets up some variables that are available inside the calls to its handlers. One of these is called “target” and it is the object, modifier or controller that is being manipulated. Another is called “this” and it is the manipulator itself. It also sets up some constant values that can be used as flags on gizmos. These will be described later. There is also a “node” value available which is the node that owns the target.
99
100
Chapter 1
|
What’s New in 3ds max 4 MAXScript
The first thing every manipulator must to in the “updateGizmos” handler is call “this.clearGizmos()”. This clears any currently cached gizmos. Next it creates a set of gizmos that will be displayed in the viewport. In the case of the radius manipulator, it creates a single circle that represents the radius being manipulated. giz = manip.makeCircle [0,0,0] (target.radius * 1.01) 28
“manip” is a exported set of utility interface functions that manipulators can use. See the “Reference” section below for full details. In this case we are creating a circle, centered at the origin, with radius 1.01 times the radius we are manipulating, and 28 segments. The “1.01” factor was added so that the gizmo will stick out a little bit from the object it is manipulating. If we used the radius directly, then it might not be visible in the viewport, because it co-exists with the object it is manipulating. Note that 3d gizmos are defined in the local coordinate system of the node that owns the manipulator target. The system will automatically compensate if the node is moved, rotated or scaled when displaying or hit-testing the manipulator. Next, we add the gizmo to the manipulator: this.addGizmoShape giz 0 g r
This tells the manipulator to add the shape gizmo to the manipulator, with no special flags values ie. the “0”. All of the the flags will be decribed below. Additionally, the command indicates to use green (“g”) as the unselected color and red (“r”) as the selected color. The selected color is used when the mouse passes over it, and the unselected color is used when the mouse isn’t over it. Finally, this method returns a string value that will be used as the tool tip when the mouse passes over the gizmo. In general, gizmos can be made from meshes, shapes (wire frame), text and markers. The details are covered in the reference section below. The next handler is called “mouseMove m which”. This is called on every mouse movement when the target is being manipulated. The “m” parameter holds the screen coordinates of the mouse location, and the “which” parameter is an index that indicates which gizmo is being dragged. The gizmos are numbered in the order of their creation in “updateGizmos,” starting at 0. The mouseMove handler is usually the trickiest part of the manipulator to implement. It needs to update the value of the parameter being manipulated in such a way that the manipulator gizmo tracks under themouse, if possible. For manipulators that exist in 3d space, this is normally done by computing a “hit-ray,” which is a ray in 3d space that passes through the mouse position, and travels in the direction of the view. This is computed as follows: viewRay = this.getLocalViewRay m
This view ray is then intersected with some plane, and the new parameter value is computed using the intersection point.
Matrix3 Scripted Controller
In the case of the radius manipulator, the plane we use is the XY plane, because the radius circle lies on the XY plane, in local coordinate space. This plane is computed as follows: local pl = manip.makePlaneFromNormal z_axis [0, 0, 0],
This create “pl” which is a plane whose normal is the Z axis, and which passes through the origin ([0,0,0]). To intersect this with the view ray, we use the “intersect” operation on planes: projectedPoint = [0,0,0] res = pl.intersect viewRay &projectedPoint
We set up “projectedPoint” first at the holder of the result of the intersection. The return value “res” is a boolean value that tells us if the intersection worked or not. If it returns true, the intersection worked, if it returns false, it failed. It can fail if the plane is parallel to the view ray. Once we have the intersection point, in “projectedPoint,” then we use that to determine a new value for the radius. In this case we use the distance from the origin (“length projectedPoint”) as the new radius. We scale it by dividing by 1.01 to compensate for the fact that we made the gizmo 1.01 time bigger than the actual radius being manipulated. That’s it! Generally, you will need to use some trigonometry and linear algebra in your “mouseMove” handler. The idea behind direct manipulation is that the gizmo should track directly under the mouse. For a more complicated example of a 3d manipulator, check the code in UVWManip.ms.
Stand-alone Manipulators Stand-alone manipulators, like the 2d slider, require a bit more work. The code in SliderManip.ms will be used for this discussion. The header has a bit more information: plug-in simpleManipulator sliderManipulator name:”Slider” classID:#(0x47db14ef, 0x4e9b5990) category:”Manipulators”
Since stand-alone manipulators can be saved in the MAX file, it needs a class ID (p. 141). See the MAXScript reference for more information about that. It also does not include the “invisible:true” line, which means that the system will create a button for it in the “Create” panel. It will be placed in the “Manipulators” section of the helper create panel. We also need to define a parameter block and rollout UI for the object. This is done in the same way as other scripted plug-ins. Stand-alone manipulators manipulate themselves, so the “canManipulate” handler looks like this: on canManipulate target
return (classOf target) == sliderManipulator
101
102
Chapter 1
|
What’s New in 3ds max 4 MAXScript
We also need to provide a creation tool that handles mouse interaction when creating the manipulator. This is handle exactly like other scripted plug-ins. A stand-alone manipulator also needs some special code in its “updateGizmos” handler. For the slider this looks like: -- If this is not a stand-alone manip, get values from the manip target if (target != undefined) then ( this.value = target.value this.minVal = target.minVal this.maxVal = target.maxVal this.xPos = target.xPos this.yPos = target.yPos this.width = target.width this.hide = target.hide this.sldName = target.sldName this.snapToggle = target.snapToggle this.snapVal = target.snapVal unselColor = greenColor ) else ( unselColor = yellowColor )
The test of “target != undefined” is to see if this if this is a manipulator, or stand-alone object. When the object is stand-alone, the value of “target” is undefined, and it uses the value of the parameters from its own parameter block. It target is defined, then this means it is manipulating. In that case, we want to copy the values of the parameters from the target that we are manipulating.
Reference Scripted manipulators can have the following handlers: on canManipulate target
This returns a value that says whether this manipulator manipulate the given target. on canManipulateNode n
This returns a value that says whether this manipulator manipulate the given node. Note: A manipulator should only implement one of these handlers. on updateGizmos
This is called whenever the manipulator needs to build its gizmos. It returns a string value that is used for the tool tip. If it returns an empty string, no tool tip is displayed. on mouseMove m which
This is called when the user has grabbed a gizmo and is dragging it.
Matrix3 Scripted Controller
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
103
104
Chapter 1
|
What’s New in 3ds max 4 MAXScript
This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the “Z” coordinate is ignored, applies to all but addGizmoMesh. gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport, applies to all but addGizmoMesh. addGizmoMarker markerType position flags unselColor selColor
The creates a gizmo using a marker. The value of the “markerType” parameter can be: #point #hollowBox #plusSign #asterisk #xMarker #bigBox #circle #triangle #diamond #smallHollowBox #smallCircle #smallTriangle #smallDiamond #dot #smallDot
The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by addGizmoShape. addGizmoText text position flags unselColor selColor
This creates a gizmo that is text on the screen. Note that text cannot be hit-tested or grabbed by the mouse. It is used for display purposes only. getLocalViewRay m
This function takes a mouse position and returns the ray that passes through that mouse position in the direction of the view. It is returned in the local coordinates of the node that owns the manipulator target.
The “manip” package “manip” is a value in MAXScript that contains a set of useful interface functions for manipulators. The functions it exports are: manip.makeSphere position radius segments
This returns a mesh sphere with the given position, radius, and segments. manip.makeTorus position radius1 radius2 segments sides
Create a torus mesh with the given values. manip.makeBox position length width height lengthSegs widthSegs heightSegs
Creates a box mesh with the given parameters.
Matrix3 Scripted Controller
manip.makePlaneFromNormal normal point
Creates a Plane object with the given normal that passes through the given point. manip.makeCircle center radius segments
Creates a circle shape in the XY plane with the given parameters. manip.makeGizmoShape()
Creates an empty gizmo shape. See the details of “GizmoShape” below for how to use this.
Plane objects The plane objects returned from “manip.makePlaneFromNormal” have the following functions available: projectedPoint = [0,0,0] plane.intersect ray &intersectionPoint
This intersects the given ray with the plane. It returns true if it succeeds, and false if it doesn’t. If it works, then the intersection point is set in the “intersectionPoint” value, which must be initialized to a Point3 value in advance. plane.mostOrthogonal ray otherPlane
This returns the plane that is most orthogonal to the given ray. This means the plane that is most “square” to the view direction. Sometimes a manipulator might choose between two different planes on which to project a ray. It is usually best to project it to the plane which faces the view ray most directly, and this function determines that. See “UVWManip.ms” for an example of how to use this. plane.getNormal()
Returns the normal of a plane. plane.getPoint()
Return the point that the plane passes through. plane.getPlaneConstant()
Return the value of the plane constant. This is the value of “D” in the equation that defines the plane: Ax + By +Cz + D = 0
GizmoShape objects. A GizmoShape is a shape object that you can use to construct wire-frame gizmos. You can get an empty GizmoShape as follows: local giz = manip.makeGizmoShape()
The functions available are: giz.addPoint point
This adds a new point to the shape. The points are connected by line segments in order to create the wireframe. If you want a closed shape, you have to add the first point again as the last point.
105
106
Chapter 1
|
What’s New in 3ds max 4 MAXScript
giz.startNewLine()
This begins a new line segment in the shape. giz.transform matrix
This transforms the gizmo by the given Matrix3 transform. Note: See the UVWManip.ms for an example of creating 3d gizmos with GizmoShape.
See Also Interface: manip (p. 366) sliderManipulator interfaces: (p. 520) radiusManip interfaces: (p. 500) uvwMappingHeightManip interfaces: (p. 551) uvwMappingLengthManip interfaces: (p. 555) uvwMappingUTileManip interfaces: (p. 558) uvwMappingVTileManip interfaces: (p. 562) uvwMappingWidthManip interfaces: (p. 565) ConeAngleManip - superclass: helper (p. 277) PlaneAngleManip - superclass: helper (p. 311) Scripted Plug-ins (p. 1538) sliderManipulator - superclass: helper (p. 333)
Scripted Objects on detachedFromNode For Object Scripted Plug-ins Topic: version 4 MAXScript New Features/Scripted Plug-In/Scripted Objects There is a handler to scene object scripted plug-ins, on detachedFromNode <node> do ... This is called whenever a node that references a plug-in instance is deleted in the scene. Note that, in the presence of instancing, there may still be other nodes referencing the base object instance.
See Also Scripted Plug-ins (p. 1538)
RenderEffects Progress Callback Mechanism
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 progressCB: do
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>
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 … ( … if progressCB.progress completed total then exit ) … escapeEnable = true … )
107
108
Chapter 1
|
What’s New in 3ds max 4 MAXScript
The progress bar update is done inside the main processing loop and the check for user cancel is done on the same call, causing the loop to exit prematurely in this example.
See Also RenderEffect : MAXWrapper (p. 1347) Scripted RenderEffect Plug-ins (p. 1566) Render Effects Common Properties, Operators, and Methods (p. 1347)
Scripted Rollouts Multi-line editText UI items in Scripted Rollouts Topic: version 4 MAXScript New Features/Scripted Plug-In/Scripted Rollouts Multi-line editText UI items can now be created in scripted rollouts. If an explicit height: parameter is supplied on an editText item definition that specifies a pixel height greater than one line of text, that editText item becomes a multi-line edit box, allowing multiple lines of text to be entered. When in multi-line mode, <enter> keystrokes no longer cause the ‘on entered’ handler to be called, but are inserted into the edit box as new lines. They do, of course, cause ‘on changed’ handlers to be called. These are called on every keystroke. For multi-line editText items, ‘on entered’ handlers are called when the edit box loses keyboard focus, such as if you tab or click out of the edit box.
See Also Edittext (p. 1496) Rollout Floater Windows (p. 1477)
Multi-line editText UI items in Scripted Rollouts
Skin Joint Angle Morph Spring Controller Topic: version 4 MAXScript New Features/Spring Controller The Spring controller adds secondary dynamics effects to any point or object position. The end result is secondary mass/spring dynamics similar to Flex. This constraint adds realism to generally static animations. When you apply Spring to an animated object, its original motion is preserved and secondary, velocity-based dynamics are applied. When you first apply the controller, it constructs a virtual spring between the object’s original position and where it would end up after forces are applied to it. You can adjust spring tension and dampening. Increasing the tension creates a tighter spring, while increasing the dampening smoothes out jitters in the motion. Users have control over the point’s Mass and Drag, the spring’s Tension and Dampening, and other world space constraints. These include being able to add external forces like Wind and Gravity (spacewarps), and being able to constrain the spring effects along a given axis. This way you can add vertical dynamics while controlling the about of effect it has in the horizontal directions. The solution is calculated using a start time and a step size. Solutions are cached once for the last tick calculated, and once per frame. Performance should be the same one each frame as you step forward, and significantly faster after the first pass if nothing changes. Cached values will be used if going backwards in time. The biggest slowdown occurs when animating an object that the controller uses as a force way down the time line since this is a history dependant solver. If a lot of animation is going to occur along a long timeline you can shut off the spring solver by setting steps to 0. Set this back to the desired value when you want the solution recalculated.
Methods Prototype: getMass()
Return Value: Returns the mass. Prototype: setMass mass
Parameters: mass
109
110
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: Sets the mass. The mass of the object to which the Spring controller is applied. Increasing the mass causes the “bouncing” spring motion to become more exaggerated. Prototype: getDrag()
Return Value: Returns the drag. Prototype: setDrag drag
Parameters: 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: getTension springIndex
Parameters: springIndex
Return Value: Gets the tension for the spring corresponding to the index. Prototype: setTension springIndex tension
Parameters: springIndex 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: getDampening springIndex
Parameters: springIndex
Return Value: Gets the dampening for the spring corresponding to the index.
Multi-line editText UI items in Scripted Rollouts
Prototype: setDampening springIndex dampening
Parameters: springIndex 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: addSpring <node>node
Parameters: <node>node
Remarks: Adds the node to the spring list. Return Value: Returns true if successful, false otherwise Prototype: getSpringCount()
Return Value: Returns the number of springs in the spring system. Prototype: removeSpringByIndex springIndex
Parameters: springIndex
Remarks: Removes the spring corresponding to the index. Prototype: removeSpring <node>node
Parameters: <node>node
Remarks: Removes the spring if the node is in the spring list.
111
112
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also PositionSpring interfaces: (p. 497) Point3Spring interfaces: (p. 482) SpringPoint3Controller interfaces: (p. 523) SpringPoint3Controller - superclass: Point3Controller (p. 336) SpringPositionController interfaces: (p. 526) SpringPositionController - superclass: PositionController (p. 337) Flex : Modifier (p. 1128) Flex interfaces: (p. 438) flexOps const StructDef (p. 235)
SubObject Mode System Tools Topic: version 4 MAXScript New Features/System Tools A new global struct called “systemTools” has been added to MAXScript. This group of functions lets you gather various pieces of information about the system that you are using. systemTools.NumberOfProcessors()
Returns the number of processors systemTools.GetScreenWidth()
Returns the screen width including multiple monitors. systemTools.GetScreenHeight()
Returns the screen height including multiple monitors. systemTools.IsWindows98or2000()
Returns true if the OS is Windows98 or Win2000 systemTools.IsWindows9x()
Returns true if the OS is a Win9x flavor systemTools.IsDebugging()
Returns true if running in a debugger
See Also systemTools const StructDef (p. 256) System Information (p. 141) sysInfo const StructDef (p. 255)
Multi-line editText UI items in Scripted Rollouts
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
113
114
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Methods: redraw forceRedraw: forceRedraw default value: false
Indicates if the redraw should be forced Redraws the trackbar. getNextKeyTime()
Gets the next key time. The “at time” context can be used to determine the starting point. 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 name or index
Returns a boolean value indicating if the specified trackview is open. trackviews.isCurrent name or index
Returns a boolean value indicating if the trackview is the last one used or not. trackviews.setCurrent 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 name or index
Deletes the specified trackview. trackviews.close name or index
You can now close a trackview based on it’s index or name. trackviews.open name or index
You can now open a trackview based on it’s index or name. trackviews.getTrackView name or index
This method will get a trackview based on it’s index or name.
Multi-line editText UI items in Scripted Rollouts
Example: showInterface (trackviews.getTrackView 1) trackviews.getAllTrackViews()
Returns an array of trackviews. trackviews.numTrackViews()
Returns the number of trackviews. trackviews.getTrackViewName index
Returns the name of the trackview window based on the index. setName <string>name
Sets the name of the trackview window getNumTracks()
Gets the number of tracks currently displayed in trackview numSelTracks()
Gets the number of selected tracks canAssignController()
Tests to see if all selected tracks are of the same type assignControllerDialog
Invokes the assign controller dialog if canAssignController() assignController <maxObject>controller
Assigns the controller to the selected tracks if canAssignController() is true and the controller is the appropriate type showControllerTypes state
Sets the ShowControllerType property expandTracks()
Expands all tracks zoomSelected()
Zooms to the selected object’s track zoomOnTrack <maxObject>parent subNum
Zooms to the track defined by the parent and the subNum <maxObject>getTrack index
Returns the object belonging to the indexed track <maxObject>getParent 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
Gets the objects belonging to the selected, indexed track <maxObject>getParentOfSelected index
Gets the indexed selected tracks parent object getSelectedSubNum index
Gets the subNum of the selected track getIndex <maxObject>object
Gets the index for the animatable object
115
116
Chapter 1
|
What’s New in 3ds max 4 MAXScript
selectTrackByIndex index clearSelection
Selects tracks by index selectTrack <maxObject>object 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 trackviews.getTrackViewByIndex 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
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
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.
117
118
Chapter 1
•
|
What’s New in 3ds max 4 MAXScript
through 2 new menu items in the Edit menu in script editor windows When accessed through the new script editor Edit menu items, the layout editor is designed for application to rollout definition sections in the active script editor. The “New Rollout” menu item is used to create a rollout definition from scratch. You place the cursor in the edit window where you want the newly-generated rollout code to be inserted and choose Edit>New Rollout. This opens the editor on a blank form to which you can add and arrange and edit rollout items. Choosing File>Save or hitting the Save icon in the layout editor window will cause the script for the rollout to be inserted at that point in the editor window. Subsequent edits and saves while the layout editor is still open cause that inserted code to be updated.
The “Edit Rollout” item (hotkey F2), is used to edit an existing rollout definition in the active script editor. You place the cursor anywhere inside a rollout or utility definition, choose Edit>Edit Rollout (F2), and the layout editor is opened showing that rollout. You can edit and add to the rollout in the layout editor and when you choose File>Save or click the Save icon in the layout editor, the original definition is replaced with new code corresponding to the edited rollout. Subsequent changes and saves while the layout editor is still open cause that code to be updated each time.
Features: •
You can have more than one layout editor open at a time This allows you to cut and paste operations between them. Also, note that cutting and pasting in VMS also copies event code.
•
When opened from a script editor window, the text in that editor window becomes ‘frozen’ while the layout editor is open. The editor window can be brought to the front and scrolled and saved, but any other operation will be ignored and a beep will sound. The editor will ‘unfreeze’ as soon as you close the layout editor.
•
The Edit>Edit Rollout function can be applied to any existing rollout definition. It attempts to parse the definition and open an equivalent editable version in the layout editor. This is a somewhat tricky heuristic and may well fail for certain rollouts until we get the bugs out. MAXScript preserves all the code in the rollout and updates only those parts that correspond to the things you can edit in the layout editor, namely, UI items and their handlers.
•
Code generated by the layout editor always specifies explicit pos: width: and height: parameters for UI items, it does not use align:, offset:, or any of the other auto-layout parameters. This means that any rollout that you edit that uses automatic layout will be transformed into an explicitly-positioned layout when you do the first File>Save. It is quite difficult to preserve the auto-layout parameters under arbitrary edits in the editor and the assumption is that once you start editing a rollout using the layout editor you will continue to do so.
Note: An extreme example of this is the group ( ) construct which is used to nest a set of items in a group box. Nested group ( ) constructs are removed completely by the layout editor and replaced with new groupBox UI items that define an explicitly-sized box around the original items. You can edit and add and nest groupBoxes as needed in the editor.
Multi-line editText UI items in Scripted Rollouts
•
If there is a syntax error in a rollout definition being opened by Edit>Edit Rollout, the syntax error is reported and highlighted and the layout editor does not open - it can only be opened on error free source.
•
When you first edit or create a rollout in the layout editor, it defaults to the standard width for Command Panel rollouts. You can adjust this width in the editor by resizing the outer gray rectangle and the editor emits width: and height: parameters on the generated rollout header. You can edit these numbers in the script editor and they will be honored by the layout editor when you next edit that rollout. For command panel rollouts and other scripted plug-ins, there are now symbolic constants provided that produce the correct width automatically. These are: #cmdPanel #effectsDlg #mtlEditor
so, to set up the rollout for a scripted material (p. 1565), you’d add a width: parameter to the rollout header like this: rollout foo “Frabulation” width:#mtlEditor ( ...
•
You add new UI items by clicking its button in the item toolbar at the bottom and then dragging out a rectangle for it in the main form. You can select an existing item and edit its paramters in the property list on the right. You can select multiple items by fence-dragging or ctrl-clicking and perform various alignments operations, see the Layout menu. A selected item can be deleted by clicking the red X toolbar button. The various panes can be resized or even torn off if you want to customize the editor layout.
•
Axis restriction works by holding the shift down while moving objects. This will restrict movement to the X or Y axis based on the angle of the mouse from its initial position.
•
editText boxes in the editor can now be multi-line, consistent with the mulit-line editText in MAXScript (p. 108).
•
Editing in the Array editor dialog has been rationalized and improved. Clicking on an item in the list box toggles the selection state of it. When items are selected in the list box, changing text in the edit field and hitting enter changes all the selected items to what was in the edit box, this allows for editing of entries in the middle of the list.
•
A new custom item type has been added to the item type toolbar at the bottom of the VisualMS dialog, allowing custom items to be created from scratch in the editor. Its icon appears in the toolbar as a face in profile. When first created, the item class parameter in the parameter list shows as ‘???’ and must be edited to contain the desired custom item type.
•
An ActiveX control rollout item type is available in MAXScript. The icon for it appears in the UI item toolbar at the bottom of the VisualMS dialog, as a dot array with the word OLE superimposed. ActiveX Controls in MAXScript Rollouts (p. 10)
119
120
Chapter 1
|
What’s New in 3ds max 4 MAXScript
•
Editing an existing rollout source that contains any unrecognized UI item types, such as those added from 3rd-party .dlx MAXScript extensions appear in the VisualMS rollout window as new ‘custom’ items, displaying as a rectangle containing the new ‘custom’ type icon. Any definition parameters on are displayed and editable in the parameter list, and overall position and size of the bounding rectangle of the custom type can be edited in the rollout pane.
•
You can de-select everything by clicking in the white space around the main form.
•
The main form always has a black rectangle drawn around it even when deselected. This allows you to see the form if both the background of the application and the form are the same color.
•
Resizing of the main form now snaps to the grid if it is on.
•
The paste command now works much better. Pasted objects are offset by [10,10] pixels, maintain unique names, and then pasting everything is de-selected and the pasted objects get selected.
•
When editing an existing rollout definition that makes use of autmatic layout in VMS for the first time, it is highly recommended that you add a ‘width:n’ parameter to the rollout header first so that the editor can position items correctly.If no width: parameter is supplied, it defaults to Command Panel width which may be too small for floating window rollouts or scripted materials or effects. For rollouts that will appear in a rolloutFloater, you should set the rollout width: equal to the floater window width minus 30.
Example: rollout foo “Frabulation” width:#270 ( ... ) ... rf = newRolloutFloater “Frabo” 300 220 addRollout foo rf
Xref Objects Topic: version 4 MAXScript New Features/Xref Objects An updated function published interface for Xref Objects. Interface: objXRefs (p. 409)
Explicit References A file being xref’d that has a script controller whose script has explicit references ($sphere01, etc.) to objects in the incoming xref file have a potential problem for the script writer. The problem is, the objects in the xref file are invisible to the scripter, and so a script will fail. This is actually a general problem with xrefs, you cannot have scripts of any kind in the file (scripts controllers, param wires, callback scripts, etc.) that depend on explicit scene object references.
Multi-line editText UI items in Scripted Rollouts
The persistent global solution is the only one that is viable at this time. There are two general solutions: 1) associate an owning-scene context with controller scripts, etc., when they come in via xref and use that to anchor pathname searches and other scene-relative references, and 2) have an accessible ‘evaluation context’ for controllers sent as part of the GetValue() call, so we can know what object’s parameter the current GetValue() call is being made for and can therefore get rid of many of the uses of explicit pathnames in the scripts. Currently, MAXScript now fully loads any persistent globals in xref’d and merged files, but does NOT make them persistent in the current scene. As an example of a setup showing how this can be used, imagine a file with 3 spheres that will be xref’d. You need to establish persistent globals for all the scene objects to be referrenced in controller scripts, like this: persistent global s1 = $sphere01, s2 = $sphere02, s3 = $sphere03
this has to be run sometime while the to-be-xrefed scene is the currently open scene. Then in the controller scripts, you’d say something like: global s1, s2 dependsOn s1 s2 (s1.pos + s2.pos) / 2
Note this uses ‘global’ not ‘persistent global’, so you don’t go making them persistent again when they get xref’d into some other scene.
See Also XRef Files (p. 1643) XRefScene Values (p. 1038) XRefObject : Node (p. 1037) xrefs const StructDef (p. 259) xrefPaths const StructDef (p. 259) Interface: objXRefs (p. 409)
121
122
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Zip-file Script Packages Topic: version 4 MAXScript New Features/Zip-file Script Packages This is a new feature in MAXScript that allows a package of related files, perhaps making up a scripted tool, to be bundled and compressed into a single zip format file. This package file can then be run like an ordinary .ms file. Any secondary files, needed by the tool, will be either automatically found in the package or they will be automatically extracted to specified locations prior to running the main tool scripts. The file type for script packages is ‘.mzp’. These files are recognized as executable script files in the following situations: •
auto-loading at MAX startup, in scripts\startups, stdplugs\stdscripts, etc. any .mzp file found is run.
•
choosing the Run Script menu item in the main MAXScript menu, or in the Listener menu, now shows .mzp files as one of the default kinds of executable files in the Open Script dialog and will run it if selected
•
specifying a fileName: parameter when adding a callBack script (p. 29)
•
as executable files inside other .mzp archives, you can nest them if want
•
when using the fileIn 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
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 ““
Describes the package. Normally, a readme file in the package would give extended operating instructions, if they are provided. version
Returns the version number of the package. extract to ““
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 ““
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 ““ to ““
Copies the named file or files (if the 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.
123
124
Chapter 1
|
What’s New in 3ds max 4 MAXScript
File Searches: The following functions will perform searches for files given as relative file names in the current package file: fileIn (p. xlix) include (p. lix) openBitmap (p. 755) editScript
Note: Any saves will not go back into the package, but into the temp extracted file. loadMAXFile mergeMAXFile ... getMAXFileObjectNames importFile ... loadMaterialLibrary
Bitmap Searches: The following UI items will search for named bitmap .bmp files in the package: bitmap fileName: button images: checkButton images:
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 ““ to ““ [noReplace] move ““ to ““ [noReplace] treeCopy ““ to ““ [noReplace] treeMove ““ 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 spec must always be a directory. Any treeCopy/Move replicates the source sub-directories into the directory, making new directories as needed. The 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 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
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 -- 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.
125
126
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Winzip: You can initially create a .mzp with a zip utility such as WinZip. You can then associate that utility with the .mzp type, so simple double-clicking a .mzp file will open it in that editor. You only need to set up this association once, and you can do this in the Windows Explorer by selecting a .mzp file, shift-right-clicking on the selected file and choosing “Open with...” in the popup menu that appears. Scroll the application list that appears to find you desired zip utility and check the “Always use this program ...” checkbox at the bottom of the dialog. msZip Interface: The MAXScript zip package interface (p. 378) has exposed 2 scripter-callable functions: msZip.fileInPackage <mzpFilename> &<exractDirVar>
The ‘fileInPackage’ function is essentially the equivalent of: fileIn <mzpFileName>
and will return true if success or false if there is a failure, or a missing or invalid .mzp file, and it will also return the directory that the package file were extracted to in the pass-by-reference <extractDirVar> argument. Example: local extractDir = ““ if msZip.fileInPackage “foo.mzp” &extractDir then ( -- extractDir contains the extracted-to directory name ... ) msZip.unloadPackage <mzpFilename> &<exractDirVar>
&
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:
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 affectRegionVal
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)
127
128
Chapter 1
|
What’s New in 3ds max 4 MAXScript
“Apropos” and “ShowProperties” and now “Help” and “Show” Topic: Magma MAXScript Language/Object Inspector Functions To make scripting easier to teach and use everyday, a ScriptTool function for “Help” and “Show” has been added. So now typing Help “Box”, will show all the commands using the name BOX. “Show” is the short way of typing ”ShowProperties” Show $
--will show you the properties of the selected object and so on.
See Also Class and Object Inspector Functions (p. 799) Class and Object Inspector Functions Enhanced (p. 159)
BinStream for Binary Reading and Writing Topic: version 4 MAXScript Language Improvements/Language Improvements BinStream fopen <String fileName> <String mode>
Opens a file for reading or writing based on the mode parameter. This can either be “wb” for Writing Binary or “rb” for Reading Binary. The function will return a BinStream value. Boolean FClose
Close a BinStream value. Returns True if it successfully closed the BinStream. Boolean fseek
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
Returns the current file pointer position. Boolean WriteByte [#signed | #unsigned]
Writes a Integer to the file as one byte. Returns True if write was successful. Boolean WriteShort [#signed | #unsigned]
Writes a Integer to the file as two bytes. Returns True if write was successful. Boolean WriteLong [#signed | #unsigned]
Writes a Integer to the file as four bytes. Returns True if write was successful. Boolean WriteFloat
Writes a Float to the file as four bytes. Returns True if write was successful. Boolean WriteString <String>
Writes a string to the file. Returns True if write was successful. Integer ReadByte [#signed | #unsigned]
Read a one byte value and return as an Integer.
By Reference Parameter Passing
Integer ReadShort [#signed | #unsigned]
Read a two byte value and return as an Integer. Integer ReadLong [#signed | #unsigned]
Read a four byte value and return as an Integer. Float ReadFloat
Read a four byte value and return as an Float. String ReadString
Read a string from the file. Example: f=fopen “c:\\test.bin” “wb” WriteString f “String” WriteByte f 64 WriteShort f 128 WriteLong f 256 WriteFloat f 512.0 WriteString f “gnirtS” WriteLong f (ftell f) fclose f f=fopen “c:\\test.bin” “rb” ReadString f ReadByte f ReadShort f ReadLong f ReadFloat f ReadString f ftell f ReadLong f fclose f
See Also FileStream Values (p. 763)
By Reference Parameter Passing Topic: version 4 MAXScript Language Improvements/Language Improvements MAXScript has been extended to support by-reference parameter passing. This allows a reference to be passed to a variable, property, or array element in the caller’s context as a parameter to a function and any assignments to that parameter in the called function will be assigned directly to the caller’s variable, property. or array element. This is often used as a mechanism for passing multiple results back from a function. To define by-reference parameters for a function, you prefix them with an ‘&’ character.
129
130
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Example: function foo x y &z = ( ... z = x * y ... return true )
Declares a function taking three parameters, x, y and z. The &z in the parameter list indicates the z parameter is to be passed by-reference. To call this function, you provide a reference value for the z parameter using the new ‘&‘ reference operator. Example: local var1, var2 ... var1 = foo 2 3 &var2
Calls the foo function with the arguments 2, 3 and &var2. The &var2 is a reference to the var2 local variable. When the function is called, the z parameter in the body is a reference to var2 local in the caller, and the z = x * y
assignment in the body of foo will cause x * y to be assigned to the var2 local in the caller. After var1 = foo 2 3 &var2
var1 will contain true and var2 will contain x * y or 6. Any number of by-reference parameters can be used and they can be keyword parameters if needed: fn foo x y &z: = ...
called like this: var1 = foo 2 3 z:&var2
The ‘&’ reference operator used to supply references in a call can be applied to any 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
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)
131
132
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Coercion of bitArray to array and integer arrays to bitArrays Topic: version 4 MAXScript Language Improvements/Language Improvements Coercion of bitArray to array and integer arrays to bitArrays implemented. as 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: *
-- intersection (”AND” operation)
See Also BitArray Values (p. 791) Value Common Properties, Operators, and Methods (p. 714)
Command line -U MAXScript startup scripts
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:
133
134
Chapter 1
|
What’s New in 3ds max 4 MAXScript
*ref = [10,0,0]
first dereferences the reference in ‘ref’ to $foo.pos and then assigns to that, effectively setting $foo’s position. In order to avoid ambiguity with the ‘*’ multiply operator, the precedence of the ‘*‘ dereferencing operator is set at just lower than the function call and just higher than the ‘as’ coercion operator. This means that if you want to send a dereferenced value into a function as an argument, you must surround the dereferencing with parentheses, as in: foo (*ref) x y z
Remember that reference values can be generated for variables, properties and array elements, as Example: &foo &$box.position.x &valArray[23]
The ‘*’ dereferencing operator is a moderately advanced feature in MAXScript that is often used to allow very general purpose code to be written that uses references instead of actual objects so that it can be applied to different kinds of objects and properties at different times. Nested property access allowed in ‘&’ reference values in MAXScript. This allows constructs like: r = &$foo.pos, and later *r.controller to mean $foo.pos.controller.
See Also By Reference Parameter Passing (p. 129)
forceUpdate Function added to UVWUnwrap Topic: version 4 MAXScript Language Improvements/Language Improvements Unwrap UVW : Modifier (p. 1176) A forceUpdate function added to MAXScript. Right now when the user changes the topology Unwrap resets the mapping. If the forceUpdate is set to true then the mapping will not be reset, but you can’t edit/see any mapping that makes sense. This flag is for advance users that want to lock a mapping and then set the topology back down for maximized viewport speed. forceUpdate(BOOL update)
See Also UVWUnwrap interfaces: (p. 568) Unwrap UVW interfaces: (p. 530)
hasProperty() function
hasProperty() function Topic: version 4 MAXScript Language Improvements/Language Improvements Prototype: hasProperty <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)
135
136
Chapter 1
|
What’s New in 3ds max 4 MAXScript
isValidNode Topic: version 4 MAXScript Language Improvements/Language Improvements isValidNode
Returns true if 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:
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 <string>
Sets the directory specified in string. Replicated in the Customize > Configure Paths dialog for the specified file type.
Shortcut system replaced
The valid values are: #autoback #drivers #export #expression #font #help #image #import #matlib #maxroot #maxstart #plugcfg #preview #scene #scripts #sound #startupScripts #ui #vpost
Returns true if successful, false if not. Does not check to see if <string> is a valid path. Any change made through this function is immediately reflected in the 3dsmax.ini file and so is persistent. Use with caution.
See Also 3ds max System Directories (p. 1625)
Shortcut system replaced Topic: version 4 MAXScript Language Improvements/Language Improvements The “shortcuts” feature in previous versions of MAXScript has been removed. In it’s place you can use macro-recording of actions. To determine how to invoke an action from MAXScript, you should go to the UI customization dialog and put that action on a button, menu or keyboard shortcut. Then turn on macro recording and execute the action. The code that is emitted can be cut and pasted in to your script. If you turn on macro recording and start using the menu, quad menu or toolbar, you’ll see code emitted that looks like this Example: actionMan.executeAction 0 “59225” -- Manipulate Mode
This is code that will execute the same action as pressing the “Manipulate Mode” button. The comment is also generated, and it uses the action’s tool tip. The parameters of “actionMan.executeAction” are the integer ActionTableId of the table the action comes
137
138
Chapter 1
|
What’s New in 3ds max 4 MAXScript
from, and the “persistent id” if the action. Actions exported from core all have persistent ids that are fixed integers as a string. Actions are accessible, all that you need to know are the ActionTableId and the persistent ID in order to invoke the operation. Note: Certain actions emit much better code. If an action is exported using a function published action table, then the code it emits calls that function. For example, if you bring up the “Plug-in Manager” from the customize menu, the code emitted is: Plug-in_Manager.Plug-inMgrAction.show ()
If the action comes from a macro script, which many of our actions do, the code looks like: macros.run “Modifiers” “Bend”
See Also Action Manager (p. 9) Interface: actionMan (p. 353)
startObjectCreation() Topic: version 4 MAXScript Language Improvements/Language Improvements The startObjectCreation() function has been enhanced. startObjectCreation <maxobjclass> [returnNewNodes:] [newNodeCallback:]
The values that can now be supplied to the optional ‘returnNewNodes:’ keyword argument are true, false (the default) or #first. If ‘true’ is supplied, all of the nodes created, up until the current create mode is exited, will be returned in an array. If #first is supplied, only the first node created is returned, immediately after it is created. The function doesn’t wait for the create mode to be exited by the user. The optional ‘newNodeCallback:’ keyword argument can supply a scripted function of one argument to the create mode that is started, such that the function will be called each time a node is created with the new node as its argument. This is similar to supplying pickObject() filter functions, although the return value of the newNodeCallback: function is ignored. Note that the callback function is invoked immediately upon new node creation, *before* any base object is installed in it, so *only* node-related properties can be accessed and changed during this callback. Example: fn setColor n = n.wireColor = red startObjectCreation box newNodeCallback:setColor
would cause all new boxes created in the started create mode to have red wire color. The ‘returnNewNodes:’ and ‘newNodeCallback:’ can both be supplied on the same call; the callback will be called on each node, and they will be returned in an array as the result of the startObjectCreation() function.
Subanim Indexing Operator, [], on MAX Objects Now Takes Subanim Names
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)
139
140
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Symbolic Pathnames Topic: version 4 MAXScript Language Improvements/Language Improvements Support for $ 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
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
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 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.
141
142
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also Scripted Plug-ins (p. 1538) Scripted Custom Attributes (p. 45) Menu Manager (p. 75)
validModifier() function Topic: version 4 MAXScript Language Improvements/Language Improvements The validModifier() function improved so that it will take a modifier class in place of a modifier to preclude the need to create a modifier to do the test. Prototype: validModifier <node_or_node_collection> <mod_or_mod_class>
It is recommended that classes be used in RCMenus and macroScripts using validModifier() to reduce resource usage. Example: if validModifier $ Edit_Mesh then ...
instead of: if validModifier $ (Edit_Mesh()) then ...
The MAXScript isValidModifier function will check if it has been passed a modifier that doesn’t exist at runtime. It returns false in this case. It uses the ClassEntry to determine the InputType() of the modifier.
See Also Node Common Properties, Operators, and Methods (p. 820) Modifier Common Properties, Operators, and Methods (p. 1096)
Visible Class For ‘&’ Reference Values Topic: version 4 MAXScript Language Improvements/Language Improvements Dereferencing Operator (p. 133) In prior releases, the class of a reference value (as returned by the ‘&’ prefix operator) was shown as Value. It is now the class ‘ValueRef’. Example: ref = &foo.name classOf ref -> ValueRef if classOf x == ValueRef then y = *x
Nested property accessing allowed in ‘&’ reference values in MAXScript. This allows constructs like: r = &$foo.pos, and later *r.controller to mean $foo.pos.controller.
List Controller
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
Set active function lst.GetActive()
Get active function lst.active
Get/set active property. lst.cut
Cut the indexed sub-controller lst.paste
Paste clip to index location. lst.delete
Delete the indexed sub-controller. lst.setName <string>
Sets the name of the indexed sub-controller.
143
144
Chapter 1
|
What’s New in 3ds max 4 MAXScript
lst.getName
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> | <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
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 [ #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)
145
146
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Geometry, Modifiers, Space Warps Hose - superclass: GeometryClass Hose - superclass: GeometryClass; super-superclass:node - 27:0 - classID: #(1777953373, 593249034) The Hose object is a flexible object that you can connect between two objects, whereupon it reacts to their movement. It’s similar to Spring, but does not have dynamics properties. You can specify the overall diameter and length of the hose, the number of turns, and the diameter and shape of its “wire”. Constructor: Hose ...
Properties: .End_Placement_Method .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_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. .Segments_Along_Hose integer
Integer
default: 45
--
animatable;
The total number of segments in the hose’s length. Increase this setting for a smooth profile when the hose is curved. Default=16. .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. .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_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. .Round_Hose_Diameter float
Float
The maximum width of the hose at the ends.
default: 0.2
--
animatable;
Hose - superclass: GeometryClass
.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. .Rectangular_Hose_Width float
Float
default: 0.2
--
animatable;
Float
default: 0.2
--
animatable;
Float
default: 0.0
--
animatable;
The width of the hose. .Rectangular_Hose_Depth float
The height of the hose. .Rectangular_Hose_Fillet_Size float
The amount by which the cross-section corners are rounded. For this to be visible, Fillet Segs must be set to 1 or higher. Default=0. .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. .Rectangular_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. .D_Section_Hose_Width float
Float
default: 0.2
--
animatable;
Float
default: 0.2
--
animatable;
Float
default: 0.0
--
animatable;
The width of the hose. .D_Section_Hose_Depth float
The height of the hose. .D_Section_Hose_Fillet_Size float
The amount by which the two cross-section corners opposite the rounded side are rounded. For this to be visible, Fillet Segs must be set to 1 or higher. Default=0. .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. .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. .D_Section_Hose_Section_Rotation Float angle; Controller Scaling: (1 : 57.2958)
default: 0.0
The orientation of the hose along its long axis. Default=0.
--
animatable;
147
148
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.Flex_Section_Enabled
Integer
default: 1
--
integer
When on, lets you set the following four parameters for the central, flexible section of the hose. When off, the hose’s diameter is uniform throughout its length. .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%. .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%. .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 isn’t high enough to support the number of cycles, then not all cycles will appear. Default=10. Tip: To set the appropriate number of segments, first set Cycles, and then increase Segments until the number of visible cycles stops changing. .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%. .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. .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
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: .‘time on’
Integer
default: 0
--
integer; Time_On
The frame numbers at which the space warp becomes active and becomes inactive. .‘time off’ Time_Off
Integer
default: 16000
--
animatable; integer;
The frame numbers at which the space warp becomes active and becomes inactive. .symmetry Damping_Symmetry
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. .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 that’s affected by the damping. .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. .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. .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 that’s affected by the damping.
149
150
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.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. .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. .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 that’s affected by the damping. .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. .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. .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 that’s affected by the damping. Tangential specifies the percentage of particle motion across the body of the Drag icon that’s affected by the damping. .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. .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
.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 that’s affected by the damping. Tangential specifies the percentage of particle motion across the body of the Drag icon that’s affected by the damping. .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. .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. .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 icon’s long axis (Axial) that’s affected by the damping, on a per-frame basis. .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. .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. .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 icon’s long axis (Axial) that’s affected by the damping, on a per-frame basis.
151
152
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.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. .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. .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 icon’s long axis (Axial) that’s affected by the damping, on a per-frame basis. .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. .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. .rangeless .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
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 object’s vertex count as a percentage of the overall number of vertices in the original mesh. Adjusting this setting alters the Count value as well. Note: After you type in a specific percentage, such as 30, you might find that the software changes the value to a slightly lower one, such as 29.971. This is due to the relationship between the overall number of vertices in the model and the percentage calculation. It is not a bug, but simply the closest solution to your request. <MultiRes>.Vertex_Merging
BooleanClass default: false
--
boolean
When on, lets MultiRes merge vertices between discrete elements in a model. For example, if you apply MultiRes to a teapot, which comprises four separate elements, and turn on Vertex Merging, as you adjust the vertex resolution, the separate components will meld together into one contiguous lower-resolution object. To control Vertex Merging, you can set a Merge Threshold. This value determines the 3ds max unit distance within which to merge elements. <MultiRes>.Threshold
Float
default: 0.0
--
float
This spinner value sets the maximum distance in 3ds max units between vertices in order for those vertices to be considered for merging. Once this threshold is achieved, then the vertices between elements will be welded together as the mesh is reduced in complexity. Note: To eliminate only coincident vertices, set Merge Threshold to 0.0. This is similar to the Weld Vertex function.
153
154
Chapter 1
|
What’s New in 3ds max 4 MAXScript
<MultiRes>.Merge_Within
BooleanClass default: false
--
boolean
When on, MultiRes merges the boundaries of adjacent elements and vertices within elements. Many objects can contain multiple groups of vertices that don’t share connectivity. A simple example of this is the Teapot object. It comprises four different elements: the body, the handle, the spout, and the lid. Normally, MultiRes optimizes each discrete element in a mesh on its own. The default behavior of the Vertex Merging option is to merge vertices between elements. Turning on Within Mesh? causes vertices within elements to be merged as well. <MultiRes>.Boundary_Metric
BooleanClass default: false
--
boolean
When on, MultiRes preserves materials assigned to the selected model. The material boundaries defined by Material IDs are retained as long as possible, and are the last to be eliminated at low vertex counts. Default=off. <MultiRes>.Maintain_Base_Vertices
BooleanClass default: false
--
boolean
When on, overrides the MultiRes optimization algorithms and preserves any vertices selected at the MultiRes Vertex sub-object level as “critical” ones. Use this feature to retain critical features of an object or character such as its fingers or claws, or other geometry that might become unrecognizable if reduced too severely. To select vertices for use with this option, use the MultiRes Vertex sub-object level. To access this level, first go to the modifier stack display and click the plus-sign icon next to the MultiRes modifier. This opens up its hierarchy, which consists of the single Vertex 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
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)
155
156
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Vortex - superclass: SpacewarpObject Vortex - superclass: SpacewarpObject; super-superclass:node - 19:0 - classID: #(217851359, 1867456353) The Vortex space warp applies a force to particle systems, spinning them through a whirling vortex, and then moving them down a long, thin spout or vortex well. Vortex is useful for creating black holes, whirlpools, tornadoes, and other funnel-type objects. The space warp settings let you control the vortex shape, the well characteristics, and rate and range of particle capture. The shape of the vortex is also affected by particle system settings, such as speed. Constructor Vortex ...
Properties: .‘time on’
Integer
default: 0
--
integer; Time_On
The frame numbers at which the space warp becomes active and becomes inactive. .‘time off’ integer; Time_Off
Integer
default: 16000
--
animatable;
The frame numbers at which the space warp becomes active and becomes inactive. .axialstrength Axial_Drop_Strength
Float
default: 0.1
--
animatable; float;
Specifies how quickly particles move in the direction of the drop axis. .axialrange float; Axial_Range
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. .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. .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. .rotationstrength Orbital_Speed_Strength
Float
Specifies how quickly the particles rotate.
default: 0.5
--
animatable; float;
Vortex - superclass: SpacewarpObject
.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. .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. .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. .radialstrength Radial_Pull_Strength
Float
default: 0.5
--
animatable; float;
Specifies the distance from the drop axis at which the particles rotate. .radialrange float; Radial_Range
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. .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. .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. .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. .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. .direction
Integer
default: 0
--
radio button number
Determines whether particles rotate clockwise or counterclockwise.
157
158
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.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. .iconsize
Float
default: 10.0
--
float; Icon_Size
Specifies the size of the icon. Example: Vortex ‘time on’:0 ‘time off’:16000 axialstrength:0.1 axialrange:100 axialfalloff:1000 axialdamping:5 rotationstrength:0.5 rotationrange:100 rotationfalloff:1000 rotationdamping:5 radialstrength:0.5 radialrange:100 radialfalloff:1000 radialdamping:5 taperstrength:100 tapershape:1 direction:0 rangeless:on pos:[32.5437,-58.2321,0] isSelected:on iconSize:25.8103
See Also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Keys Bezier Keys inTangentLength and outTangentLength Topic: version 4 MAXScript Language Improvements/Keys There are 2 additional properties in MAXScript for bezier keys .inTangentLength and .outTangentLength. These are the handles’ magnitude in frames. There is a new check box to the key property/Master Point control dialog found in the Motion Panel. It is called Free Handle. When Free Handle is checked, the user can move the horizontal handle where ever s/he feels. Otherwise, s/he is constrained, to prevent discontinuities. Correspondingly, there is a new bezier key property called .freeHandle that implements the functionality described above. Note: There are a fair number of classes that don’t implement the showproperties method. MAXKey is one of them. getPropNames is not implemented for it either.
See Also MAXKey Values (p. 767) MAXKeyArray Values (p. 793) MAXKey Common Properties, Operators, and Methods (p. 768) Working with MAXKey Values (p. 769)
Class and Object Inspector Functions Enhanced
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 , 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
159
160
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.boneFreezeLength : boolean : Read|Write .boneScaleType : enum : Read|Write boneScaleType enums: {#scale|#squash|#none} .stretchTM : matrix3 by value : Read .boneAxis : enum : Read|Write boneAxis enums: {#X|#Y|#Z} .boneAxisFlip : boolean : Read|Write .primaryVisibility : boolean : Read|Write .secondaryVisibility : boolean : Read|Write .applyAtmospherics : boolean : Read|Write .vertexColorType : enum : Read|Write vertexColorType enums: {#color|#illum|#alpha|#color_plus_illum} .showVertexColors : integer : Read|Write .shadeVertexColors : integer : Read|Write .handle : DWORD : Read Methods: setBoneEnable onOff time realignBoneToChild() 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
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)
161
162
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Renderer Topic: version 4 MAXScript Language Improvements/SuperClasses A MAXClass wrapper added for the plug-in renderer superclass so that a renderer instances can be worked with in MAXScript. The new superclass is named “Renderer”.
See Also Controlling the Renderer (p. 1664) Interface: NetRender (p. 379)
2 New Scripted Plug-in Superclasses on apply handlers for scripted RenderEffects Topic: version 4 MAXScript Language Improvements/SuperClasses The 2 new scripted plug-in superclasses are Camera and simpleManipulator. There are several simpleManipulator scripted plug-ins in stdplugs\stdscripts radiusManip.ms, sliderManip.ms, and UVWManip.ms.
See Also Scripted Cameras (p. 94) Scripted Manipulators (p. 97)
Globals and Locals Definition Constructs Can Include Global Variable Declarations At Top Level Topic: version 4 MAXScript Language Improvements/Globals and Locals All the major definition constructs in MAXScript (such as utility, rollout, macroScript, rcmenu, tool, plug-in, etc.) can now include global variable declarations at the top-level within them. Example: rollout foo “foo” ( local a, b = undefined, c global d, e = 3 spinner bar “Bar” checkBox baz “Baz: “ on bar changed do ... )
-- now possible
Changes to Undeclared Implicit Global Variables
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)
163
164
Chapter 1
|
What’s New in 3ds max 4 MAXScript
BitmapTex Reload and viewImage Topic: version 4 MAXScript Language Improvements/Material Editor, Material and Textures In MAXScript the Bitmap texture now has a reload and viewImage function which are identical to what is exposed in the bitmapTex interface.
See Also bitmapTex interfaces: (p. 434) BitmapTexture : TextureMap (p. 1243) BMP, PNG, JPEG and TGA I/O Interfaces (p. 164) Material Editor Access (p. 165) Accessing The Material Editor Active Slot (p. 163) Material Level Show-in-viewport State (p. 166) showTextureMap() function (p. 167)
BMP, PNG, JPEG and TGA I/O Interfaces Topic: version 4 MAXScript Language Improvements/Material Editor, Material and Textures BMP interfaces: (p. 437) This is a function published interface for bmp I/O that provides access to the type of image to be saved. Portable Network Graphics interfaces: (p. 473) This is a function published interface for png I/O that provides access to the type of image to be saved. JPEG interfaces: (p. 454) This is a function published interface for jpeg I/O that provides access to the type of image to be saved. Targa interfaces: (p. 529) This is a function published interface for tga I/O that provides access to the type of image to be saved.
Material Editor Access
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: SetActiveMtlSlot slot forceUpdate
Parameters: slot
The material slot index. forceUpdate
Set this to TRUE to update the slot contents. Remarks: This method allows you to set the active material slot. Prototype: GetActiveMtlSlot()
Return Value: This method returns the index of the active material slot. Prototype: PutMtlToMtlEditor <maxObject>mtl slot
Parameters: <maxObject>mtl
The material you want to put. 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 slot
Parameters: 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.
165
166
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: 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: 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
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> []
If the optional 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 argument. If only a <material> is supplied, its show-in-viewport state will be set by the argument. Example: showTextureMap $foo.material on showTextureMap $foo.material $foo.material.diffusemap off
Note: Mapping coordinates aren’t explicitly enabled for the objects at creation time. When a script is run in the Listener, using ‘showTextureMap’ is indirectly turning mapping coordinates on. This happens during the scene redraw which happens after each line is executed, if needed. If a script is run from a script editor, or if you put parenthesis around a script, no scene redraw is performed until the entire script is run. Since no redraw is performed, no mapping coordinates exist on the object when the script tries to access them. Solutions: explicitly perform a scene redraw [redrawViews()] after ‘showTextureMap’, or explicitly turn on mapping coordinates for the object.
See Also Material Editor (p. 1606) TextureMap Common Properties, Operators, and Methods (p. 1235) Material Level Show-in-viewport State (p. 166) Accessing The Material Editor Active Slot (p. 163) Material Editor Access (p. 165)
167
168
Chapter 1
|
What’s New in 3ds max 4 MAXScript
User Interface Angle UI element Topic: version 4 MAXScript Language Improvements/User Interface The Angle UI element: •
Display of caption string
•
Handling of align layout parameter
•
StartDegrees and startRadians properties - controls the zero degrees position
•
Dir property - either #cw or #ccw (default #ccw)
•
Range property - point3 specifying min, max, and value in degrees.
•
If min and max values are the same sign, click and move in angle UI will give result of correct sign. If min and max are different signs, shift or ctrl click will give negative result, click will give positive result.
Example: rollout test “ Angle Test” ( Angle ang2 “Angle” diameter:40 align:#center range:[-180,180,45] startdegrees:270 dir:#cw ) createdialog test 200 100
See Also Rollout User-Interface Controls (p. 1481) Rollout User-Interface Controls Types (p. 1484) Rollout User-Interface Controls Common Layout Parameters (p. 1483) Rollout User-Interface Controls Common Properties (p. 1481)
CreateDialog
CreateDialog Topic: version 4 MAXScript Language Improvements/User Interface CreateDialog has been enhanced. The prototype is now: CreateDialog [ <width> <position_x> <position_y>] \ [pos:] [width:] [height:] \ [bgcolor:] [fgcolor:] \ [bitmap:] {bmpstyle: \ [menu:] [style:<array>] [modal:]
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:, 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: GetDialogPos
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
Parameters:
The rollout used to build the Dialog to set the position of.
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)
169
170
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Curve Control Topic: version 4 MAXScript Language Improvements/User Interface
You can create CurveControl’s in rollouts by using the following: CurveControl [ ] [ visible: ] [ numCurves: ] \ [ x_range: <point2> ] [ y_range: <point2> ] [ zoomValues: <point2> ]\ [ scrollValues: <point2> ] [ displayModes: ] \ [ commandMode: ]\ [ uiFlags: <array_of_ui_flags> ] \ [ rcmFlags: <array_of_rcm_flags> ] [ asPopup: ]
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,
Properties: <curvecontrol>.visible : Boolean <curvecontrol>.x_range : Point2
#all
Curve Control
<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 represents the active Curve Index. on <curvecontrol> selChanged do <expr>
Sent when a point is selected or deselected. is the number of points, which are selected. on <curvecontrol> ptChanged do <expr>
Sent when a point is changed, is the index of the changed point on <curvecontrol> tangentChanged type do <expr>
Sent when a point’s in or out tangent is changed, is the index of the changed point type is #inTangent or #outTangent, depending on what changed. on <curvecontrol> deleted do <expr>
Sent when a point is deleted, val is the index of the deleted point. on <curvecontrol> reset do <expr>
Sent when a curve is reset ccCurve represents a single curve in a curve control Properties: .animatable : Boolean .color : Color .disabledColor : Color .width : Integer .disabledWidth: Integer .disabledStyle : Name .style : Name
these are the drawing styles for the curves, can be any one of the following #solid, #dash, #dot, #dashDot, #dashDotDot, #null, #insideFrame .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.
171
172
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.numPoints: Integer .points: Array, read-only
Returns a CurvePointsArray Methods: getValue ccCurve [lookup:]
Returns a Point2 isAnimated ccCurve
Returns a Boolean value getSelectedPts ccCurve
Returns a BitArray setSelectedPts [#select] [#deSelect] [#clear] setPoint [checkConstraints:<true>] getPoint insertPoint deletePoint
CurvePointsArray represents an array of curve points. CurvePointValue represents a curve point. CurvePointValue represents a curve point, you create a curve point like: ccPoint \ [bezier:] [corner:] [lock_x:] [lock_y:] \ [select:] [end:] [noXConstraint:]
Properties: .value: Point2 .inTangent: Point2 .outTangent: Point2 .bezier: Boolean .corner: Boolean .lock_x: Boolean .lock_y: Boolean .selected: Boolean .end: Boolean .noXConstraint: Boolean
Example: rollout uTestCurveControl “Curve Control”( -- Curve control Properties local ccProps = #( #visible, #numCurves, #x_range, #y_range, #displayModes, #zoomValues, #scrollValues, #commandMode)
Curve Control
-- Curve properties local curveProps = #( #name, #animatable, #color, #disabledColor, #width, #disabledWidth, #style, #disabledStyle, #numPoints, #lookupTableSize) -- Curve Point properties local cpProps = #( #value, #inTangent, #outTangent, #bezier, #corner, #lock_x, #lock_y, #selected, #end, #noXConstraint) button btn_props “Print Properties” checkBox chk_visible “Visible”checked:true checkBox chk_enable “Enable”checked:true CurveControl cc_test “Curve Control:” height:200 width:400 align:#center numCurves:2 visible:true x_range:[-100,100] y_range:[-100,100] scrollValues:[-100,100] commandMode:#move_xy -- The following parameters default to all flags if not specified --uiFlags:#(#drawBG, #drawgrid, #upperToolbar, #showReset, #scrollBars, #constrainY, #xvalue) rcmFlags:#(#delete) asPopup:false on chk_visible changed state do cc_test.visible = state on chk_enable changed state do cc_test.enabled = state on uTestCurveControl open do ( local colors = #(red, green, blue)
173
174
Chapter 1
|
What’s New in 3ds max 4 MAXScript
local styles = #(#solid, #dash, #dot, #dashDot, #dashDotDot, #null, #insideFrame) local num = cc_test.numCurves -- Initialize curve properties for i=2 to num do ( local crv = cc_test.curves[i] local ci = ((mod (i-1) colors.count)+1) as integer local si = ((mod (i-1) styles.count)+1) as integer crv.name = “Curve” + i as string crv.color = colors[ci] crv.disabledColor = colors[ci]*0.5 crv.style = styles[si] --crv.width = crv.disabledWidth = i crv.numPoints = i*2 local del = (cc_test.x_range.y cc_test.x_range.x)/(crv.numPoints-1) --format “del:%\n” del -- Place intermediate points equally spaced for j=1 to crv.numPoints do ( local cp = crv.points[j] format “% end: % -> “ j cp.end --cp.corner = true cp.value = [cc_test.x_range.x+(j-1)*del, cp.value.y] cp.inTangent = [0.2,0.2] cp.outTangent = [0.2,-0.2] crv.points[j] = cp format “%\n” crv.points[j].end format “value: %\n” crv.points[j].value ) ) ) on btn_props pressed do ( local tab = “\t” -- print the CC properties format “Curve Control Properties\n” for p in ccProps do format (tab + “% : %\n”) (p as string) (getProperty cc_test p) format (tab + “Curves:\n”) tab += “\t” for i=1 to cc_test.numCurves do ( local crv = cc_test.curves[i] -- print each Curve’s properties format (tab + “Curve%\n”) i
getTextExtent
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)
175
176
Chapter 1
|
What’s New in 3ds max 4 MAXScript
isActive Topic: version 4 MAXScript Language Improvements/User Interface Prototype: isActive
Return Value: Returns true if the atmospheric is set to active; false otherwise
See Also Atmospheric Effects Common Properties, Operators, and Methods Prototype: isActive
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
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)
177
178
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Menu and CUI Loading Topic: version 4 MAXScript Language Improvements/User Interface You can now load a menu file in MAXScript as follows: menuMan.loadMenuFile “MaxModelingMenu.mnu”
The full path should not be specified. It will look in the appropriate directories for menu files. The default is the “ui” directory. You can set the main menu in max as follows: menuMan.setMainMenuBar “Menu Bar1”
To restore MAX’s default main menu: menuMan.setMainMenuBar “Main Menu Bar”
The function returns true of it succeeds and false if it can’t find the named menu. You can set the quad right-click menu that MAX uses in the viewports using the following MAXScript: menuMan.setViewportRightClickMenu #nonePressed “Modeling 2”
Sets the default (no keys pressed) quad menu to “Modeling 2”. The menu name must be a quad menu that is listed in the “Quads” customization dialog, and the name must match exactly, including capitalization. For the first parameter, you can use one of the following 8 values: #nonePressed #shiftPressed #altPressed #controlPressed #shiftAndAltPressed #shiftAndControlPressed #controlAndAltPressed #shiftAndAltAndControlPressed
Here are two macroScripts that set and reset two of the right-click menus: Example: macroScript SetQuads category:”Custom UI” tooltip:”Set Quad” ( on execute do ( menuMan.setViewportRightClickMenu #nonePressed “Modeling 2” menuMan.setViewportRightClickMenu #controlPressed “Sample 4x1” ) ) -----------------------------macroScript ResetQuads category:”Custom UI”
Menu and CUI Loading
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)
179
180
Chapter 1
|
What’s New in 3ds max 4 MAXScript
mtlBrowser Topic: version 4 MAXScript Language Improvements/User Interface mtlBrowser const StructDef (p. 244) Prototype: mtlBrowser.browseFrom [#mtlLibrary | #mtlEditor | #activeSlot | #selected | #scene | #new]
Remarks: Lets you set the Browse From: source for the modeless material browser.
See Also Miscellaneous Dialogs (p. 1621)
SetBackground Method Topic: version 4 MAXScript Language Improvements/User Interface Changed SetBackground to take a color in addition to a point3. Prototype: setBackGround []
Remarks: If the time value is not specified, the current MAXScript time is used. Prototype: getBackGround []
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
Parameters: on:<node>
Optionally specifies a scene object to track on. If you don’t supply an object, the mouse tracks on the current active grid. Note that the object surface tracker uses the SDK function IntersectRay() which is not reliably implemented on all object types. Editable meshes always work OK, so you can convertToMesh() if needed. prompt:”msg”
Displays the prompt message in the MAX status line snap:#2D|#3D
Relevant when not tracking on an object surface (no on:<node> specified). If snap mode is on and #2D is supplied, snaps to snap points on grid, if #3D is specified snaps to any near snap point in space. trackCallback:fn|#(fn,arg)
Is where you specify the function to be called as the mouse is dragged over the active grid or object surface. You can specify it is a single function or a function and an argument value in a two element array. The latter form is useful if you have a common callback function for many tasks and want to send in a parameter to control its operation for a particular use. The function you give must be of the following form: fn callback_fn msg ir obj faceNum shift ctrl alt = ...
in other words, a scripted function of 7 arguments. While the tracking is going on, it is called whenever a mouse action occurs, such as a button click or a drag, etc. The ‘msg’ argument is a message code that indicates what kind of action occurred, and can be one of: #freeMove #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 normal’s direction vector. ‘obj’
The object being dragged over or undefined if no on:<node> was supplied. ‘faceNum’
The number of the face the mouse is over if the object being tracked is an editable mesh, undefined otherwise.
181
182
Chapter 1
|
What’s New in 3ds max 4 MAXScript
‘shift’, ‘ctrl’ and ‘alt’
True or false depending on the down or up state of the <shift>, and 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: ...
or via property assignment, <spinner>.setKeyBrackets =
Timer UI element
See Also Spinner (p. 1509) Rollout User-Interface Controls (p. 1481) Rollout User-Interface Controls Types (p. 1484) Rollout User-Interface Controls Common Layout Parameters (p. 1483) Rollout User-Interface Controls Common Properties (p. 1481)
Timer UI element Topic: version 4 MAXScript Language Improvements/User Interface The Timer UI element has been enhanced in the following ways: •
The initial state of timer now respects the timer’s .active parameter.
•
A new .ticks read/write property which is incremented by 1 at each ‘tick’ of the timer.
See Also Timer (p. 1512) Rollout User-Interface Controls (p. 1481) Rollout User-Interface Controls Types (p. 1484) Rollout User-Interface Controls Common Layout Parameters (p. 1483) Rollout User-Interface Controls Common Properties (p. 1481)
TimeSlider on/off toggle Topic: version 4 MAXScript Language Improvements/User Interface There is an interface to turn on/off the timeslider has been added. This is accessed through the scripter in the following way: [void] timeSlider.setVisible [true|false] [bool] timeSlider.isVisible
In the scripter, this is always sticky across sessions.
See Also Interface: timeSlider (p. 428)
183
184
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Undo/Redo Dropdown Labels Topic: version 4 MAXScript Language Improvements/User Interface MAXScript now provides some control over the labels displayed in the MAX undo/redo dropdown list for undoable MAXScript operations. This is an improvement to just displaying “MAXScript” in all cases, as it did in prior versions. Any undoable macroScript execution, such as via a toolbar button, menu item, hotkey or 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
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
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)
185
186
Chapter 1
|
What’s New in 3ds max 4 MAXScript
MAXScript Dialogs and Rollout Floaters as Extended viewports Topic: version 4 MAXScript Language Improvements/User Interface/Command Panels and Rollout Pages The following functions can be used to register and unregister MAXScript dialogs and rollout floaters as extended viewports. registerViewWindow <MAXScript_dialog | rollout_floater>
Registers any MAXScript dialog or rollout floater as an extended viewport. The title of the dialog or floater appears in the viewport right click menu, under Views > Extended menu. When picked the dialog or floater will be displayed in that viewport. If you click anywhere on the outside border, it will pop up the standard views menu. This will let you switch to a different view window. unRegisterViewWindow < MAXScript_dialog | rollout_floater>
Unregisters a dialog or floater as an extended view window. It will throw an error if the dialog or floater is currently displayed in a viewport. Here is a sample script that creates two instances of a Cult3D viewer, found at www.cycore.com, and opens two files from the internet. Install the Cult3d Viewer and execute the script example below. After executing the script right click on any of the viewports and pick “Views > Extended > Cult3D Player” to display the window in the viewport. example: rollout rCult3D “Cult3D Player” ( activeXControl ax1 “{31B7EB4E-8B4B-11D1-A789-00A0CC6651A8}” align:#left setupEvents:false pos:[10,10] activeXControl ax2 “{31B7EB4E-8B4B-11D1-A789-00A0CC6651A8}” align:#left setupEvents:false pos:[10,220] on rCult3D resized size do ( local csz = (size - [20,30])*[1,.5] ax2.pos = [10, csz.y+20] ax1.size = ax2.size = csz ) on rCult3D open do ( ax1.size = ax2.size = [300,200] ax1.LoadCult3D “http://www.cult3d.com/gallery/ecommerce/olympus_on_the_beach.co” ax2.LoadCult3D “http://www.cult3d.com/gallery/ museum/madonna.co” ) ) createDialog rCult3D width:320 height:430 registerViewWindow rCult3D
Rollout .Controls Property
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 .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.
187
188
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also Rollout User-Interface Controls (p. 1481) Rollout User-Interface Controls Types (p. 1484) Rollout User-Interface Controls Common Properties (p. 1481) Rollout User-Interface Controls Common Layout Parameters (p. 1483)
Rollout Systems ‘category’ Mechanism Topic: version 4 MAXScript Language Improvements/User Interface/Command Panels and Rollout Pages You can control the grouping of rollups for a plug-in by supplying a category: 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
Const Class When you say something like “fn test val = ...”, a MAXScriptFunction value is created and stored in variable test. If variable test was passed into another method, for example as a filter function, that method would test the class of the value to make sure it’s a MAXScriptFunction and then call it using apply(). The ‘Const’ preceding the following simply says that it is a value that is created during MAXScript initialization. A Generic is one or more methods with the same name, but defined for different classes. Which method is called depends on the class of the first argument to the method. For example, ‘random’ is declared as a Generic, and there are methods implementing ‘random’ in several classes - Integer, Float, Point3, Color, Quat, etc. When MAXScript sees ‘random v1 v2’ in a script, it looks at the class of v1, and then calls the ‘random’ method for that class. So if v1 were a float, MAXScript would call the Float::random() method. A MappedGeneric is the same as a Generic, but the first argument can be a collection. If it is a collection, the the method is called individually on each member of the collection. For example, ‘deleteTime $box* 10f 10f’ deletes 10f at frame 10 in all keys in all objects named $box*. deleteTime can also be used on controllers, that’s why it is a Generic A NodeGeneric is the same as a MappedGeneric, but its first argument has to be a node or a collection of nodes. But given the definition of Generic, that doesn’t make much sense. If the first argument is a collection, and the method is applied to each member of the collection. Primitives are methods that aren’t class specific. The method is responsible for checking the types of its arguments (if any) and throwing an error if one isn’t correct. There is only one definition of the Primitive. A StructDef is a structure value. If the structure value is created by a script, its class is StructDef. If MAXScript creates the structure during initialization, its class is Const StructDef. So, for example, my meshop methods are defined to exist in a structure called meshop. Since this structure is created during initialization, the class of meshop is Const StructDef. Const Class is just a class that is defined in MAXScript itself. So, for example, BitArray is a Const Class. MAXScript also scans the classes registered with MAX - these classes will be created in MAXScript as Const MAXClass.
189
190
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also MAXScriptFunction List (p. 190) Const Generic (p. 195) Const MappedGeneric (p. 207) Const NodeGeneric (p. 209) Const Primitives (p. 213) Const StructDef (p. 231) Const Class (p. 191)
MAXScriptFunction List AddConstraint
Controller Functions for use with Constraint Assignments (p. 42) Camera Common Properties, Operators, and Methods (p. 974) - in example Scripted Geometry Plug-ins (p. 1555) - in example Scripted Shape Plug-ins (p. 1560) - in example Scripted SimpleObject Plug-ins (p. 1556) - in example The Return Expression (p. 705) - in example Time Values (p. 751)
AddConstraintTargets
Controller Functions for use with Constraint Assignments (p. 42)
AddListController
Controller Functions for use with Constraint Assignments (p. 42)
AddMod ApplyOperation
ApplyOperation function (p. 54)
ChangeSystemColorsAnimateOff ChangeSystemColorsAnimateOn help KindOfRenderElement RElements2cws SaveQuadClr SetActiveController
Controller Functions for use with Constraint Assignments (p. 42)
show
“Apropos” and “ShowProperties” and now “Help” and “Show” (p. 128)
TurnToSeq
See Also Definitions for MAXScript internal organization (p. 188)
Const Class
Const Class ActionPredicate ActiveXControl def AngleAxis AngleControl Array ArrayParameter AtmosphericClass BigMatrix
BigMatrixRowArray
ActiveX Controls in MAXScript Rollouts (p. 10) - in example with
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
191
192
Chapter 1
|
What’s New in 3ds max 4 MAXScript
FileStream float Function Generic GeomObject GroupBoxControl GroupEndControl GroupStartControl HashTable ImgTag integer Interface InterfaceFunction Interval IObject LabelControl LinkControl ListBoxControl MapButtonControl MappedGeneric MappedPrimitive MapSupportClass MaterialLibrary Matrix3 MAXAKey MAXClass MAXCurveCtl MAXFilterClass MAXKey MAXKeyArray MAXMeshClass MAXModifierArray MAXNoteKey MAXNoteKeyArray MAXObject MAXRefTarg MAXRootNode MAXScriptFunction MAXSuperClass MAXTVNode MeditMaterialsClass menuitem MixinInterface ModifierClass MoFlow MoFlowScript MoFlowSnippet MoFlowTranInfo MoFlowTransition MotionTracker MouseTool
Const Class
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
193
194
Chapter 1
|
What’s New in 3ds max 4 MAXScript
NURBSSet NURBSSurface NURBSSurfaceApproximation NURBSSurfaceEdgeCurve NURBSSurfaceNormalCurve NURBSSurfConstPoint NURBSSurfSurfIntersectionCurve NURBSTexturePoint NURBSTextureSurface NURBSULoftSurface NURBSUVLoftSurface NURBSXFormCurve NURBSXFormSurface object ObjectSet OkClass OLEMethod OLEObject PathName PhyBlendedRigidVertex PhyContextExport PhyRigidVertex PickerControl Point2 point3 Primitive progressBar Quat RadioControl Ray RCMenu RolloutClass RolloutControl RolloutFloater SelectionSet SelectionSetArray set SliderControl SpinnerControl StandardMaterialClass StaticMethodInterface String StringStream StructDef subAnim TxtureClass time Timer TriMesh UndefinedClass UnsuppliedClass
Const Generic
UserGeneric value ValueRef VertexSelection WindowStream XRefScene
See Also Definitions for MAXScript internal organization (p. 188)
Const Generic abs
Number Values (p. 717) - in example with def Camera Common Properties, Operators, and Methods (p. 974) - in example Scripted Geometry Plug-ins (p. 1555) - in example Scripted Shape Plug-ins (p. 1560) - in example Scripted SimpleObject Plug-ins (p. 1556) - in example The Return Expression (p. 705) - in example Time Values (p. 751)
addMultiplierCurve
Controller Ease and Multiplier Curve Functions (p. 1297) - in example with def
addNewNoteKey
MAXNoteKeyArray Values (p. 817) - in example MAXNoteKey Values (p. 818) - in example Working with Note Tracks (p. 818) - in example
addNewNoteKey
MAXNoteKeyArray Values (p. 817) - in example MAXNoteKey Values (p. 818) - in example Working with Note Tracks (p. 818) - in example
addPluginRollouts
Scripted Plug-in Methods (p. 1551)
AllowBlending
PhyContextExport Values (p. 1458)
append appendCurve
NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSULoftSurface : NURBSSurface (p. 1443)
appendCurveByID
NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSULoftSurface : NURBSSurface (p. 1443)
appendGizmo
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) Working with Atmospherics (p. 1345) - example
195
196
Chapter 1
|
What’s New in 3ds max 4 MAXScript
appendObject
Modifying Existing NURBS Objects (p. 1390) Creating New NURBS Objects (p. 1389) - in example NURBSSet : Value (p. 1450)
appendUCurve
NURBSUVLoftSurface : NURBSSurface (p. 1444)
appendUCurveByID
NURBSUVLoftSurface : NURBSSurface (p. 1444)
appendVCurve
NURBSUVLoftSurface : NURBSSurface (p. 1444)
appendVCurveByID
NURBSUVLoftSurface : NURBSSurface (p. 1444)
applyEaseCurve
Controller Ease and Multiplier Curve Functions (p. 1297) - in example with def
attach buildTVFaces
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Working with Editable Meshes (p. 1077) - in example
buildVCFaces
Editable_Mesh : GeometryClass and TriMesh : Value (p. 1041)
canConvertTo
Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397)
classOf clear clearAllAppData
Access to MAXWrapper AppData (p. 813)
clearCacheEntry clearProdTess
NURBSSet : Value (p. 1450)
clearViewTess
NURBSSet : Value (p. 1450)
NURBSSurface : NURBSObject (p. 1425) NURBSSurface : NURBSObject (p. 1425) close closeU
NURBSCVSurface : NURBSSurface (p. 1433)
closeV
NURBSCVSurface : NURBSSurface (p. 1433)
NURBSPointSurface : NURBSSurface (p. 1441) NURBSPointSurface : NURBSSurface (p. 1441) collapseface
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
composite Conjugate
Quat Values (p. 738)
contains ConvertToRigid createInstance
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
crop
bgndRenderElement - superclass: MAXObject (p. 270) - in example BitmapTex fnReload and fnCrop (p. 164) bitmapTex interfaces: (p. 434) - in example BitmapTexture : TextureMap (p. 1243)
cross defaultVCFaces
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
deleteAppData
Access to MAXWrapper AppData (p. 813)
deleteface
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
deleteGizmo
Atmospheric Effect Types (p. 1339)
deleteItem deleteKey
Attachment : PositionController (p. 1304) Biped Keys (p. 1759) Controller Key Functions (p. 1294) MAXKeyArray Values (p. 793)
deleteMultiplierCurve
Controller Ease and Multiplier Curve Functions (p. 1297)
deleteNoteKey
MAXNoteKeyArray Values (p. 817)
deleteNoteKeys
MAXNoteKeyArray Values (p. 817)
Working with Note Tracks (p. 818) - in example Working with Note Tracks (p. 818) - in example deleteObjects
NURBSSet : Value (p. 1450)
deleteTracker deletevert
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
deselectKey
Controller Key Functions (p. 1294)
detachFaces detachVerts
-jpr see above
disconnect
Interface: paramWire (p. 410) - in example
displacementToPreset
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
display distance dot empty eof
NURBSCurve : NURBSObject (p. 1409)
evalPos
NURBSSurface : NURBSObject (p. 1425)
evalTangent
NURBSCurve : NURBSObject (p. 1409)
evalUTangent
NURBSSurface : NURBSObject (p. 1425)
evalVTangent
NURBSSurface : NURBSObject (p. 1425)
execute
197
198
Chapter 1
|
What’s New in 3ds max 4 MAXScript
exp
Number Values (p. 717) Mathematical Operations in MAXScript (p. 588) Quat Values (p. 738) - in example with def
exprForMAXObject
Mesher - superclass: GeometryClass (p. 298)
extrudeface
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Scripted SimpleObject Plug-ins (p. 1556)
filepos
FileStream Values (p. 763) StringStream Values (p. 766)
findItem findPattern findString
String Values (p. 722) Function Parameters (p. 702) Pickbutton (p. 1504)
flagChanged flush
XRefScene Values (p. 1038) FileStream Values (p. 763) StringStream Values (p. 766) Turning On the Listener Log (p. xli)
getAfterORT
Controller Out-Of-Range Functions (p. 1296) Controller Key Reducer
getAppData
Access to MAXWrapper AppData (p. 813)
getBeforeORT
Controller Out-Of-Range Functions (p. 1296)
getChannel
Bitmap Values (p. 755)
getChannelAsMask
Bitmap Values (p. 755)
getCurve
NURBS1RailSweepSurface : NURBSSurface (p. 1427)
Scripted RenderEffect Plug-ins (p. 1566) - in example NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSULoftSurface : NURBSSurface (p. 1443) getCurveID
NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSULoftSurface : NURBSSurface (p. 1443)
getCurveStartPoint
NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429)
getCV
NURBSControlVertex : NURBSObject (p. 1409) NURBSCVCurve : NURBSCurve (p. 1412) NURBSCVSurface : NURBSSurface (p. 1433)
getDisplacementMapping
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getEdge
NURBSBlendSurface : NURBSSurface (p. 1430) NURBSNBlendSurface : NURBSSurface (p. 1439)
getEdgeVis
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Const Generic
getface
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getFaceMatID
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getFaceNormal
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getFaceSmoothGroup
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getFlip
NURBS1RailSweepSurface : NURBSSurface (p. 1427)
Working with Editable Meshes (p. 1077)
NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSULoftSurface : NURBSSurface (p. 1443) Path interfaces: (p. 462) Path Constraint interfaces: (p. 468) getFlipTrim
NURBSFilletSurface : NURBSSurface (p. 1436)
getGenerateUVs
NURBSSurface : NURBSObject (p. 1425)
getGizmo
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
getIndexedPixels
Bitmap Values (p. 755)
getKey getKeyIndex
Controller Key Functions (p. 1294)
getKnot
NURBSCVCurve : NURBSCurve (p. 1412)
getModContextBBoxMax
Modifier Common Properties, Operators, and Methods (p. 1096) Modifier Sub-Object Transform Properties (p. 1099) Node Common Properties, Operators, and Methods (p. 820)
getModContextBBoxMin
Modifier Common Properties, Operators, and Methods (p. 1096) Modifier Sub-Object Transform Properties (p. 1099) Node Common Properties, Operators, and Methods (p. 820) Scripting Vertex and Control Point Animation (p. 1461)
getModContextTM
Modifier Common Properties, Operators, and Methods (p. 1096) Modifier Sub-Object Transform Properties (p. 1099) Node Common Properties, Operators, and Methods (p. 820)
getMultiplierValue
Controller Ease and Multiplier Curve Functions (p. 1297)
GetNode
Biped and Physique (p. 1456) - in example
getnormal
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Scripted Manipulators (p. 97)
getNoteKeyIndex
Notetrack Values (p. 816)
getNoteKeyTime
MAXNoteKeyArray Values (p. 817) Notetrack Values (p. 816)
getNumCPVVerts
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getNumFaces
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getNumTVerts
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getNumVerts
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Patches (p. 55)
199
200
Chapter 1
|
getObject
What’s New in 3ds max 4 MAXScript
Patches
GetOffsetVector
Biped and Physique (p. 1456) - in example
getParent
NURBSBlendSurface : NURBSSurface (p. 1430) NURBSFilletSurface : NURBSSurface (p. 1436) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSNBlendSurface : NURBSSurface (p. 1439) Trackviews (p. 114)
getParentID
NURBSBlendSurface : NURBSSurface (p. 1430) NURBSFilletSurface : NURBSSurface (p. 1436) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSNBlendSurface : NURBSSurface (p. 1439)
getPixels
Bitmap Files (p. 1641) Scripted RenderEffect Plug-ins (p. 1566)
getPoint
NURBSIndependentPoint : NURBSPoint (p. 1406) NURBSPointCurve : NURBSCurve (p. 1418) NURBSPointSurface : NURBSSurface (p. 1441) NURBSTexturePoint : NURBSObject (p. 1446) NURBSTextureSurface : Value (p. 1455) Curve Control (p. 170) Scripted Manipulators (p. 97)
getProdTess
NURBSSet : Value (p. 1450) NURBSSurface : NURBSObject (p. 1425)
getPropNames
Class and Object Inspector Functions (p. 799) Array Values (p. 776) - in example ActiveX Controls in MAXScript Rollouts (p. 10) Scripted Manipulators (p. 97) - in example
getRadius
NURBSFilletSurface : NURBSSurface (p. 1436)
getSeed
NURBSFilletSurface : NURBSSurface (p. 1436)
getSplitMesh
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getSubAnim
Indexed Access to Animatable Properties in 3D Studio MAX Objects (p. 806)
getSubAnimName
Indexed Access to Animatable Properties in 3D Studio MAX Objects (p. 806) Subanim Indexing Operator, [], on MAX Objects Now Takes Subanim Names (p. 139)
getSubAnimNames
Indexed Access to Animatable Properties in 3D Studio MAX Objects (p. 806) Subanim Indexing Operator, [], on MAX Objects Now Takes Subanim Names (p. 139)
getSubdivisionDisplacement Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) getTextureSurface
NURBSSurface : NURBSObject (p. 1425) NURBSTextureSurface : Value (p. 1455)
getTextureUVs
NURBSSurface : NURBSObject (p. 1425)
getTiling
NURBSSurface : NURBSObject (p. 1425)
getTilingOffset
NURBSSurface : NURBSObject (p. 1425)
Const Generic
getTimeRange
Controller Time Functions (p. 1292)
getTracker getTrimSurface getTVert
NURBSFilletSurface : NURBSSurface (p. 1436) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Node Common Properties, Operators, and Methods (p. 820) - in example
getTVFace
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Node Common Properties, Operators, and Methods (p. 820) - in example
getUCurve
NURBSUVLoftSurface : NURBSSurface (p. 1444)
getUCurveID
NURBSUVLoftSurface : NURBSSurface (p. 1444)
getUKnot
NURBSCVSurface : NURBSSurface (p. 1433)
getVCFace
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getVCurve
NURBSUVLoftSurface : NURBSSurface (p. 1444)
getVCurveID
NURBSUVLoftSurface : NURBSSurface (p. 1444)
getVert
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Patches (p. 55) Script Controllers (p. 1329) - in example
getvertcolor
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
getVertexInterface
PhyBlendingRigidVertex Values (p. 1459) PhyContextExport Values (p. 1458) PhyRigidVertex Values (p. 1459) Biped and Physique (p. 1456) - in example
getViewTess
NURBSSet : Value (p. 1450)
getVKnot
NURBSCVSurface : NURBSSurface (p. 1433)
getWeight
PhyBlendingRigidVertex Values (p. 1459)
NURBSSurface : NURBSObject (p. 1425)
Class and Object Inspector Functions (p. 159) - in example LookAt Constraint - superclass: RotationController (p. 297) LookAt Constraint interfaces: (p. 455) Orientation Constraint Controller (p. 40) Path Constraint interfaces: (p. 468) Position Constraint (p. 41) Position Constraint interfaces: (p. 488) gotoFrame
Bitmap Values (p. 755)
invalTrack Inverse
Matrix3 Values Matrix3 Values Using Node Transform Properties (p. 843) - in example
invert
BigMatrix Values (p. 748) VolumeSelect : Modifier (p. 1192) Volume Light : Atmospheric (p. 1344) Volume Fog : Atmospheric (p. 1343)
201
202
Chapter 1
|
What’s New in 3ds max 4 MAXScript
isEmpty
Box2 Values (p. 750) Coercion of bitArray to array and integer arrays to bitArrays (p. 132)
isIdentity
Matrix3 Values (p. 744)
isKeySelected
Controller Key Functions (p. 1294)
Quat Values (p. 738) CS3Tools.cui Tutorial (p. 1825) - in example isKindOf
Working with Values (p. 716) ObjectSet Values (p. 781) - in example Structure Inherited Methods (p. 711)
join
BitArray Values (p. 791) Array Values (p. 776)
length LnDif
Quat Values (p. 738)
loadFrames LogN
Quat Values (p. 738)
merge
XRefScene Values (p. 1038) Zip-file Script Packages (p. 122) NURBSSet : Value (p. 1450)
moveKey
Controller Key Functions (p. 1294)
normalize
Quat Values (p. 738) Point3 Values (p. 731) Point2 Values (p. 736) Scripted Plug-in Methods (p. 1551) - in example
numEaseCurves
Controller Ease and Multiplier Curve Functions (p. 1297)
numKeys
Controller Key Functions (p. 1294)
numMultiplierCurves
Controller Ease and Multiplier Curve Functions (p. 1297)
numSelKeys
Controller Key Functions (p. 1294)
perspectiveMatch QCompA
Quat Values (p. 738)
qorthog
Quat Values (p. 738)
random
Number Values (p. 717)
readChar
FileStream Values (p. 763)
Node Common Properties, Operators, and Methods (p. 820) StringStream Values (p. 766) readChars
FileStream Values (p. 763)
readDelimitedString
FileStream Values (p. 763)
StringStream Values (p. 766) StringStream Values (p. 766)
Const Generic
readExpr
MAXScript System Globals (p. 640) Value Common Properties, Operators, and Methods (p. 714) FileStream Values (p. 763) StringStream Values (p. 766)
readLine
FileStream Values (p. 763)
readValue
FileStream Values (p. 763)
StringStream Values (p. 766) StringStream Values (p. 766) Access to MAXWrapper AppData (p. 813) - in example Encrypted Files (p. 1647) - in example MAXScript System Globals (p. 640) Node User-Defined Properties and Methods (p. 848) - in example rectify
Box2 Values (p. 750)
refine
NURBSCVCurve : NURBSCurve (p. 1412) NURBSCVSurface : NURBSSurface (p. 1433) NURBSPointCurve : NURBSCurve (p. 1418) NURBSPointSurface : NURBSSurface (p. 1441)
refineU
NURBSCVSurface : NURBSSurface (p. 1433)
refineV
NURBSCVSurface : NURBSSurface (p. 1433)
removeObject
Modifying Existing NURBS Objects (p. 1390)
NURBSPointSurface : NURBSSurface (p. 1441) NURBSPointSurface : NURBSSurface (p. 1441) NURBSSet : Value (p. 1450) renderMap
Material Editor (p. 1606) TextureMap Common Properties, Operators, and Methods (p. 1235)
reparameterize
NURBSCVCurve : NURBSCurve (p. 1412) NURBSCVSurface : NURBSSurface (p. 1433)
replace
String Literals (p. 660)
resample reset
Curve Control (p. 170) Flex interfaces: (p. 438)
resetZoom save
Bitmap Values (p. 755)
seek
FileStream Values (p. 763) StringStream Values (p. 766)
selectKey
Controller Key Functions (p. 1294)
setAppData
Access to MAXWrapper AppData (p. 813)
setCacheEntry
203
204
Chapter 1
|
What’s New in 3ds max 4 MAXScript
setCurve
NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSULoftSurface : NURBSSurface (p. 1443)
setCurveByID
NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSULoftSurface : NURBSSurface (p. 1443)
setCurveStartPoint
NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429)
setCV
NURBSCVCurve : NURBSCurve (p. 1412) NURBSCVSurface : NURBSSurface (p. 1433) Creating New NURBS Objects (p. 1389) - in example
setDisplacementMapping
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setEdge
NURBSBlendSurface : NURBSSurface (p. 1430)
setEdgeVis
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setface
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
NURBSNBlendSurface : NURBSSurface (p. 1439)
Working with Editable Meshes (p. 1077) – in example setFaceMatID
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setfacenormal
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setFaceSmoothGroup
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setFade setFlip
NURBS1RailSweepSurface : NURBSSurface (p. 1427) NURBS2RailSweepSurface : NURBSSurface (p. 1429) NURBSULoftSurface : NURBSSurface (p. 1443) path interfaces: (p. 462) Path Constraint interfaces: (p. 468)
setFlipTrim
NURBSFilletSurface : NURBSSurface (p. 1436)
setGenerateUVs
NURBSSurface : NURBSObject (p. 1425)
setIndexedPixels
Bitmap Files (p. 1641)
setKnot
NURBSCVCurve : NURBSCurve (p. 1412)
setMesh
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Creating New NURBS Objects (p. 1389) – in example Scripted SimpleObject Plug-ins (p. 1556) – in example SetNonUniformScale
BipedExportInterface Values (p. 1458)
setnormal
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setNumCPVVerts
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setNumFaces
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setNumTVerts
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setNumVerts
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Patches (p. 55)
Const Generic
setObject
NURBSSet : Value (p. 1450)
setParent
NURBSBlendSurface : NURBSSurface (p. 1430)
Modifying Existing NURBS Objects (p. 1390) NURBSFilletSurface : NURBSSurface (p. 1436) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSNBlendSurface : NURBSSurface (p. 1439) setParentID
NURBSBlendSurface : NURBSSurface (p. 1430) NURBSFilletSurface : NURBSSurface (p. 1436) NURBSMultiCurveTrimSurface : NURBSSurface (p. 1438) NURBSNBlendSurface : NURBSSurface (p. 1439)
setPixels
Bitmap Files (p. 1641) Scripted RenderEffect Plug-ins (p. 1566) – in example
setPoint
Curve Control (p. 170) NURBSPointCurve : NURBSCurve (p. 1418) NURBSPointSurface : NURBSSurface (p. 1441) NURBSTextureSurface : Value (p. 1455)
setProdTess
NURBSSet : Value (p. 1450) NURBSSurface : NURBSObject (p. 1425)
setRadius
NURBSFilletSurface : NURBSSurface (p. 1436)
setSeed
NURBSFilletSurface : NURBSSurface (p. 1436)
setSize
BigMatrix Values (p. 748)
setSplitMesh
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setStruct setSubdivisionDisplacement Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) setTextureSurface
NURBSSurface : NURBSObject (p. 1425) NURBSTextureSurface : Value (p. 1455)
setTextureUVs
NURBSSurface : NURBSObject (p. 1425)
setTiling
NURBSSurface : NURBSObject (p. 1425)
setTilingOffset
NURBSSurface : NURBSObject (p. 1425)
Materials Assignment and Texture Coordinates (p. 1391)
setTrimSurface
NURBSFilletSurface : NURBSSurface (p. 1436)
settvert
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setTVFace
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
Working with Editable Meshes (p. 1077) Working with Editable Meshes (p. 1077) setUCurve
NURBSUVLoftSurface : NURBSSurface (p. 1444)
setUCurveByID
NURBSUVLoftSurface : NURBSSurface (p. 1444)
setUKnot
NURBSCVSurface : NURBSSurface (p. 1433)
setVCFace
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setVCurve
NURBSUVLoftSurface : NURBSSurface (p. 1444)
205
206
Chapter 1
|
What’s New in 3ds max 4 MAXScript
setVCurveByID
NURBSUVLoftSurface : NURBSSurface (p. 1444)
setVert
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Patches (p. 55)
setVertColor
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
setViewTess
NURBSSet : Value (p. 1450)
setVKnot
NURBSCVSurface : NURBSSurface (p. 1433)
showInterface
Class and Object Inspector Functions (p. 159)
showInterfaces
Class and Object Inspector Functions (p. 159)
showProperties
“Apropos” and “ShowProperties” and now “Help” and “Show” (p. 128)
NURBSSurface : NURBSObject (p. 1425)
Trackviews (p. 114) List Controller (p. 143) Class and Object Inspector Functions (p. 799) showTrack skipToNextLine
FileStream Values (p. 763) StringStream Values (p. 766)
skipToString
FileStream Values (p. 763) StringStream Values (p. 766)
Slerp
EulerAngles Values (p. 742)
sort
Array Values (p. 776)
sortNoteKeys
MAXNoteKeyArray Values (p. 817)
Quat Values (p. 738)
Working with Note Tracks (p. 818) - in example squad
Quat Values (p. 738)
substring
String Literals (p. 660)
superClassOf
Working with Values (p. 716) Structure Inherited Methods (p. 711) Value Common Properties, Operators, and Methods (p. 714) Picking Scene Nodes By Hit (p. 1618)
supportsTimeOperations
Controller Time Functions (p. 1292)
transform transpose
BigMatrix Values (p. 748)
unDisplay
Bitmap Files (p. 1641)
update updateXRef
XRefObject : Node (p. 1037) XRefScene Values (p. 1038)
XFormMat zoom
Matrix3 Values (p. 744)
Const MappedGeneric
See Also Definitions for MAXScript internal organization (p. 188)
Const MappedGeneric addEaseCurve
Controller Ease and Multiplier Curve Functions (p. 1297) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)
addNewKey
MAXKey Common Properties, Operators, and Methods (p. 768)
deleteEaseCurve
Controller Ease and Multiplier Curve Functions (p. 1297) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)
deleteKeys
MAXKeyArray Values (p. 793) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) Controller Key Functions (p. 1294)
deleteTime
Controller Time Functions (p. 1292) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)
deselectKeys
Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) Controller Key Functions (p. 1294)
enableORTs
Controller Out-Of-Range Functions (p. 1296) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)
Identity
BigMatrix Values (p. 748)
insertTime
Controller Time Functions (p. 1292) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)
mapKeys
mapKeys() method (p. 144)
moveKeys
MAXKeyArray Values (p. 793) Controller Key Functions (p. 1294) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)
Orthogonalize
Matrix3 Values (p. 744)
PreRotate
Matrix3 Values (p. 744)
PreRotateX
Matrix3 Values (p. 744)
PreRotateY
Matrix3 Values (p. 744)
PreRotateZ
Matrix3 Values (p. 744)
PreScale
Matrix3 Values (p. 744)
207
208
Chapter 1
|
What’s New in 3ds max 4 MAXScript
PreTranslate
Matrix3 Values (p. 1299)
print
Value Common Properties, Operators, and Methods (p. 714)
reduceKeys
Controller Key Reducer (p. 1299) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)
reverseTime
Controller Time Functions (p. 1292) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)
RotateX
Matrix3 Values (p. 744)
RotateY
Matrix3 Values (p. 744)
RotateZ
Matrix3 Values (p. 744)
scaleTime
Controller Time Functions (p. 1292) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)
selectKeys
Controller Key Functions (p. 1294) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) Attachment : PositionController (p. 1304)
setAfterORT
Controller Ease and Multiplier Curve Functions (p. 1297) Controller Out-Of-Range Functions (p. 1296) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299)
setBeforeORT
Names (p. 657) Controller Ease and Multiplier Curve Functions (p. 1297) Controller Out-Of-Range Functions (p. 1296) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies
setTimeRange
Controller Time Functions (p. 1292) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies
sortKeys
MAXKeyArray Values (p. 793) Controller Key Functions (p. 1294) Nested Object Controller Functions (p. 814) Time and Key Functions on Object Hierarchies (p. 1299) Working with MAXKey Values (p. 769) Working with Note Tracks (p. 818)
Translate
Matrix3 Values (p. 744) Box2 Values (p. 750)
Zero
Const NodeGeneric
See Also Definitions for MAXScript internal organization (p. 188)
Const NodeGeneric addAndWeld
SplineShape : Shape (p. 1079)
addKnot
SplineShape : Shape (p. 1079)
addModifier addNewSpline
SplineShape : Shape (p. 1079)
addNURBSSet
Modifying Existing NURBS Objects (p. 1390) NURBS Node Properties and Methods (p. 1397) Parameter Ranges for Curves and Surfaces (p. 1391)
bindKnot
SplineShape : Shape (p. 1079)
bindSpaceWarp breakCurve
NURBS Node Properties and Methods (p. 1397)
breakSurface
Modifying Existing NURBS Objects (p. 1390) NURBS Node Properties and Methods (p. 1397)
collapseStack
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Modifier Common Properties, Operators, and Methods (p. 1096) Node Common Properties, Operators, and Methods (p. 820) Patch : GeometryClass (p. 1088)
convertTo
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397) Patch : GeometryClass (p. 1088) Patches (p. 55)
convertToMesh convertToNURBSCurve
Collections (p. 773) Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397)
convertToNURBSSurface
Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397)
convertToPoly convertToSplineShape
Modifier Common Properties, Operators, and Methods (p. 1096) Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397) Scripting Vertex and Control Point Animation (p. 1461) Section : Shape (p. 959) SplineShape : Shape (p. 1079)
copy
209
210
Chapter 1
|
What’s New in 3ds max 4 MAXScript
curveLength
Shape Common Properties, Operators, and Methods (p. 945)
deleteKnot
SplineShape : Shape (p. 1079)
deleteModifier
Modifier Common Properties, Operators, and Methods (p. 1096) Node Common Properties, Operators, and Methods (p. 820)
deleteSpline
SplineShape : Shape (p. 1079) Modifier and SpacewarpModifier Types (p. 1100)
deselect flagForeground
Node Common Properties, Operators, and Methods (p. 820) Scripted Atmospheric Plug-ins (p. 1569) - in example Slider (p. 1507) Spinner (p. 1509)
freeze getEdgeSelection
Edit Mesh : Modifier (p. 1114) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Mesh Select : Modifier (p. 1142) polyop const StructDef (p. 248)
getFaceSelection
Edit Mesh : Modifier (p. 1114) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Mesh Select : Modifier (p. 1142) polyop const StructDef (p. 248)
getInVec
SplineShape : Shape (p. 1079)
getKnotPoint
SplineShape : Shape (p. 1079)
getKnotType
SplineShape : Shape (p. 1079)
getNURBSSet getOutVec
SplineShape : Shape (p. 1079)
getSegmentType
SplineShape : Shape (p. 1079)
getUserProp
Node Common Properties, Operators, and Methods (p. 820) Node User-Defined Properties and Methods (p. 848)
getUserPropBuffer
Node Common Properties, Operators, and Methods (p. 820) Node User-Defined Properties and Methods (p. 848)
getVertSelection
Edit Mesh : Modifier (p. 1114) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) Mesh Select : Modifier (p. 1142) polyop const StructDef (p. 248)
hide hideSelectedSegments hideSelectedSplines hideSelectedVerts instance instanceReplace
Node Common Properties, Operators, and Methods (p. 820)
Const NodeGeneric
intersectRay
mouseTrack() Function (p. 180) Node Common Properties, Operators, and Methods (p. 820)
intersects
Node Common Properties, Operators, and Methods (p. 820)
isClosed
NURBSCurve : NURBSObject (p. 1409)
Scripted Manipulator (p. 97) SplineShape : Shape (p. 1079) isDeleted
Node Common Properties, Operators, and Methods (p. 820) - in example with def PathName Values (p. 780) - in example with def
joinCurves
NURBS Node Properties and Methods (p. 1397)
joinSurfaces
NURBS Node Properties and Methods (p. 1397)
lengthInterp
Shape Common Properties, Operators, and Methods (p. 945)
lengthTangent
Shape Common Properties, Operators, and Methods (p. 945)
lengthToPathParam
Shape Common Properties, Operators, and Methods (p. 945)
makeIndependent
NURBS Node Properties and Methods (p. 1397)
materialID
Bitmap Values (p. 755) MaterialModifier : Modifier (p. 1137) SplineShape : Shape (p. 1079)
move nearestPathParam
Shape Common Properties, Operators, and Methods (p. 945)
numKnots
NURBSCVCurve : NURBSCurve (p. 1412) Creating New NURBS Objects (p. 1389) – in example Shape Common Properties, Operators, and Methods (p. 945) SplineShape : Shape (p. 1079)
numSegments
SplineShape : Shape (p. 1079)
numSplines
SplineShape : Shape (p. 1079)
open particleAge
Particle System Common Properties, Operators, and Methods (p. 905)
particleCount
Particle System Common Properties, Operators, and Methods (p. 905)
particlePos
Particle System Common Properties, Operators, and Methods (p. 905)
particleSize
Particle System Common Properties, Operators, and Methods (p. 905)
particleVelocity
Particle System Common Properties, Operators, and Methods (p. 905)
pathInterp
Particle System Common Properties, Operators, and Methods (p. 905)
pathTangent
Particle System Common Properties, Operators, and Methods (p. 905)
pathToLengthParam
Shape Common Properties, Operators, and Methods (p. 945)
printstack
Node Common Properties, Operators, and Methods (p. 820)
reference referenceReplace
Node Common Properties, Operators, and Methods (p. 820)
refineSegment
SplineShape : Shape (p. 1079)
resetShape
SplineShape : Shape (p. 1079)
211
212
Chapter 1
|
What’s New in 3ds max 4 MAXScript
reverse rotate scale select selectmore
Node Common Properties, Operators, and Methods (p. 820) ObjectSet Values (p. 781) - In Example With Def
setEdgeSelection
polyop const StructDef (p. 248) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) - In Example
setFaceSelection
polyop const StructDef (p. 248) Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) - In Example
setFirstKnot
SplineShape : Shape (p. 1079)
setFirstSpline
SplineShape : Shape (p. 1079)
setInVec
SplineShape : Shape (p. 1079)
setKnotPoint
SplineShape : Shape (p. 1079)
setKnotType
SplineShape : Shape (p. 1079)
setOutVec
SplineShape : Shape (p. 1079)
setRenderApproximation
NURBS Node Properties and Methods (p. 1397)
setSegmentType
SplineShape : Shape (p. 1079)
setSurfaceDisplay
NURBS Node Properties and Methods (p. 1397)
NURBSSurfaceApproximation : Value (p. 1453)
NURBSSurfaceApproximation : Value (p. 1453) setUserProp
Node Common Properties, Operators, and Methods (p. 820) Node User-Defined Properties and Methods (p. 848) - In Example With Def
setUserPropBuffer
Node Common Properties, Operators, and Methods (p. 820) Node User-Defined Properties and Methods (p. 848) - In Example With Def
setVertSelection
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041) - In Example With Def polyop const StructDef (p. 248)
setViewApproximation
NURBS Node Properties and Methods (p. 1397)
snapShot
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
unbindKnot
SplineShape : Shape (p. 1079)
unfreeze
MAX Commands (p. 1630)
NURBSSurfaceApproximation : Value (p. 1453) Node Common Properties, Operators, and Methods (p. 820)
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
updateBindList
SplineShape : Shape (p. 1079)
updateShape
SplineShape : Shape (p. 1079)
See Also Definitions for MAXScript internal organization (p. 188)
Const Primitives All known const Primitives. acos
Number Values (p. 717)
addAtmospheric
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
addEffect
Render Effects Common Properties, Operators, and Methods (p. 1347)
addMorphTarget
Barycentric Morph Controller : MorphController (p. 1306)
addNoteTrack
Notetrack Values (p. 816) Working with Note Tracks (p. 818)
addRollout
Utility Clauses (p. 1466) Managing Multiple Rollouts in a Scripted Utility (p. 1468) Rollout Floater Windows (p. 1477) Scripted Utilities (p. 1463) Utility and Rollout Properties, Methods, and Event Handlers (p. 1474)
addTrackViewController
Track View Nodes (p. 1382)
affectRegionVal
Affect Region Function (p. 127)
amax
Array Values (p. 776)
amin
Array Values (p. 776)
animateAll
Scripting Vertex and Control Point Animation (p. 1461) Modifier Sub-Object Transform Properties (p. 1099)
animateVertex
SplineShape : Shape (p. 1079) Scripting Vertex and Control Point Animation (p. 1461) Modifier Sub-Object Transform Properties (p. 1099)
appendSubSelSet
Main Toolbar (p. 1574)
apropos
Class and Object Inspector Functions (p. 799) “Apropos” and “ShowProperties” and now “Help” and “Show” (p. 128)
arbAxis
Point3 Values (p. 731)
asin
Number Values (p. 717)
assignNewName
Material Common Properties, Operators, and Methods (p. 1203)
atan
Number Values (p. 717)
atan2
Number Values (p. 717)
attachObjects
Node Common Properties, Operators, and Methods (p. 820)
213
214
Chapter 1
|
What’s New in 3ds max 4 MAXScript
averageSelVertCenter
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
averageSelVertNormal
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
axisTripodLocked
Miscellaneous Viewport Methods and System Globals (p. 1603)
boxPickNode
Picking Scene Nodes By Region (p. 1620)
break ceil
Number Values (p. 717)
checkForSave
3ds max File Loading and Saving (p. 1639)
circlePickNode
Picking Scene Nodes By Region (p. 1620)
clearCurSelSet
Main Toolbar (p. 1574)
clearListener
Controlling the Listener Contents and the Insertion Point (p. xlii)
clearNodeSelection
Node Common Properties, Operators, and Methods (p. 820)
clearSelection
ObjectSet Values (p. 781) Node Common Properties, Operators, and Methods (p. 820) Trackviews (p. 114)
ClearSubSelSets
Main Toolbar (p. 1574)
clearUndoBuffer
undo (p. 687)
closelog
Turning On the Listener Log (p. xli)
closeRolloutFloater
Rollout Floater Windows (p. 1477)
Exiting and Resetting 3ds max (p. 1669)
closeUtility
Utility and Rollout Properties, Methods, and Event Handlers (p. 1474)
completeRedraw
Refreshing the Viewports (p. 1585)
configureBitmapPaths
Miscellaneous Dialogs (p. 1621)
conformToShape
FFD 2x2x2 : Modifier (p. 1121) FFD 3x3x3 : Modifier (p. 1123) FFD 4x4x4 : Modifier (p. 1124) FFD Box : Modifier (p. 1117) FFD Cyl : Modifier (p. 1119)
copyFile cos
External File Methods (p. 1645) Trigonometric Functions (p. 1675) Function Variables (p. 701) Number Values (p. 717)
cosh
Mathematical Operations in MAXScript (p. 588) Number Values (p. 717)
CreateDialog
CreateDialog (p. 169)
createfile
FileStream Values (p. 763) Encrypted Files (p. 1647)
createLockKey
Controller Key Functions (p. 1294)
Const Primitives
createMorphObject
Barycentric Morph Controller : MorphController (p. 1306) Barycentric Morph Controller Keys (p. 1308) Morph : GeometryClass (p. 891)
createOLEObject
OLE Automation (p. 1671)
createPreview
Miscellaneous Viewport Methods and System Globals (p. 1603)
createReaction
Reactor Controllers (p. 1326)
degToRad
Number Values (p. 717)
deleteAllChangeHandlers
Change Handlers and When Constructs (p. 1650)
deleteAtmospheric
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
deleteChangeHandler
Change Handlers and When Constructs (p. 1650)
deleteEffect
Render Effects Common Properties, Operators, and Methods (p. 1347)
deleteFile
External File Methods (p. 1645)
deleteMorphTarget
Barycentric Morph Controller : MorphController (p. 1306)
deleteNoteTrack
Notetrack Values (p. 816) Working with Note Tracks (p. 818)
deleteReaction
Reactor Controllers (p. 1326)
deleteTrackViewController
Track View Nodes (p. 1382)
deleteTrackViewNode
Track View Nodes (p. 1382)
dependsOn
dependsOn For Scripted Controllers (p. 95)
deselectHiddenEdges
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
deselectHiddenFaces
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
deselectNode
Node Common Properties, Operators, and Methods (p. 820)
DestroyDialog
CreateDialog (p. 169)
DisableSceneRedraw
Refreshing the Viewports (p. 1585)
disableStatusXYZ
Coordinate Display (p. 1578)
displayControlDialog
Controller Common Properties, Operators, and Methods (p. 1289)
displayTempPrompt
Prompt Line (p. 1577)
doesFileExist
File Name Parsing (p. 1644)
DOSCommand
Executing External Commands (p. 1668)
dumpMAXStrings editAtmosphere
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
editAtmospheric
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
editEffect
Render Effects Common Properties, Operators, and Methods (p. 1347)
enableCoordCenter
Main Toolbar (p. 1574)
enableRefCoordSys
Main Toolbar (p. 1574)
EnableSceneRedraw
Refreshing the Viewports (p. 1585)
enableShowEndRes
Modify Panel (p. 1572)
enableStatusXYZ
Coordinate Display (p. 1578)
215
216
Chapter 1
|
What’s New in 3ds max 4 MAXScript
enableSubObjSel
Modify Panel (p. 1572)
enableUndo
Main Toolbar (p. 1574)
encryptFile
Encrypted Files (p. 1647)
encryptScript
Encrypting Script Files (p. lx)
enumerateFiles
Bitmap Files (p. 1641) BitmapTexture : TextureMap (p. 1243)
eulerToQuat
Quat Values (p. 738) EulerAngles Values (p. 742)
exclusionListDlg
Miscellaneous Dialogs (p. 1621)
explodeGroup
Node Common Properties, Operators, and Methods (p. 820)
exportFile
3ds max File Loading and Saving (p. 1639)
fclose
BinStream for Binary Reading and Writing (p. 128)
fencePickNode
Picking Scene Nodes By Region (p. 1620)
fetchMaxFile
3ds max File Loading and Saving (p. 1639)
filein
Zip-file Script Packages (p. 122) Running Scripts (p. xlix) Including Scripts Within Scripts (p. lix) Creating Functions (p. 699) Encrypting Script Files (p. lx) Symbolic Pathnames (p. 140)
filenameFromPath
File Name Parsing (p. 1644)
fileOpenMatLib
Material Editor (p. 1606) MaterialLibrary Values (p. 795)
fileSaveAsMatLib
Material Editor (p. 1606) MaterialLibrary Values (p. 795)
fileSaveMatLib
Material Editor (p. 1606) MaterialLibrary Values (p. 795)
filterString
String Values (p. 722)
flashNodes
Miscellaneous Viewport Methods and System Globals (p. 1603)
floor
Number Literals (p. 660)
flushlog
Turning On the Listener Log (p. xli)
fopen
BinStream for Binary Reading and Writing (p. 128)
ForceCompleteRedraw
Refreshing the Viewports (p. 1585)
format
StringStream Values (p. 766)
fractalNoise
Color Values (p. 729) Point3 Values (p. 731)
freeSceneBitmaps
Bitmap Values (p. 755) BitmapTexture : TextureMap (p. 1243) Miscellaneous Functions (p. 1663)
Const Primitives
freezeSelection
Status Bar Buttons (p. 1579)
fseek
BinStream for Binary Reading and Writing (p. 128)
ftell
BinStream for Binary Reading and Writing (p. 128)
gc
Manual Garbage Collection (p. 656) Bitmap Values (p. 755)
genClassID
Scripted Plug-ins (p. 1538) Scripted Custom Attributes (p. 45)
getActiveCamera
Accessing Active Viewport Info, Type, and Transforms (p. 1581) Defining Macro Scripts (p. 1521) Viewport Drawing Methods (p. 1592)
getAtmospheric
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
getBackGround
SetBackground Method (p. 180)
getBackGroundController
Working with Atmospherics (p. 1345)
getBipedExportInterface
BipedExportInterface Values (p. 1458)
getBitmapOpenFileName
Bitmap Values (p. 755)
getBitmapSaveFileName
Bitmap Values (p. 755)
getBkgFrameNum
Viewport Background Images (p. 1586)
getBkgImageAnimate
Viewport Background Images (p. 1586)
getBkgImageAspect
Viewport Background Images (p. 1586)
getBkgORType
Viewport Background Images (p. 1586)
getBkgRangeVal
Viewport Background Images (p. 1586)
getBkgStartTime
Viewport Background Images (p. 1586)
getBkgSyncFrame
Viewport Background Images (p. 1586)
Setting explosion start and end times for Combustion (p. 1341)
getCommandPanelTaskMode
Command Panels (p. 1571)
getCoordCenter
Main Toolbar (p. 1574) Node Common Properties, Operators, and Methods (p. 820) – in example
getCoreInterfaces
Interfaces (p. 67)
getCPTM
Accessing Active Viewport Info, Type, and Transforms (p. 1581)
getCrossing
Status Bar Buttons (p. 1579)
getCurNameSelSet getCurrentSelection
Collections (p. 773) ObjectSet Values (p. 781)
getCVertMode
Node Common Properties, Operators, and Methods (p. 820)
GetDefaultUIColor
3ds max User Interface Colors (p. 1604)
GetDialogPos
-jprBuild:
getDimensions
FFD Box : Modifier (p. 1117)
M023-Title:
FFD Cyl : Modifier (p. 1119)
Added Simon Feltman’s CtrlLib classes to MXSAgni
217
218
Chapter 1
|
What’s New in 3ds max 4 MAXScript
GetDir
3ds max System Directories (p. 1625) SetDir (p. 136)
getDirectories
External File Methods (p. 1645)
GetDisplayFilter
Selection Filter (p. 61)
getEffect
Render Effects Common Properties, Operators, and Methods (p. 1347)
getEulerMatAngleRatio
EulerAngles Values (p. 742) Matrix3 Values (p. 744)
getEulerQuatAngleRatio
Quat Values (p. 738) EulerAngles Values (p. 742)
getFileAttribute
External File Methods (p. 1645)
getFileCreateDate
External File Methods (p. 1645)
getFileModDate
External File Methods (p. 1645)
getFilenameFile
Viewport Drawing Methods (p. 1592) File Name Parsing (p. 1644) External File Methods (p. 1645) Defining Macro Scripts (p. 1521)
getFilenamePath
File Name Parsing (p. 1644)
getFilenameType
External File Methods (p. 1645)
getFiles
External File Methods (p. 1645)
getFileVersion
External File Methods (p. 1645)
getGridMajorLines
Viewport Grids (p. 1587)
getGridSpacing
Viewport Grids (p. 1587)
File Name Parsing (p. 1644)
getHashValue
Value Common Properties, Operators, and Methods (p. 714)
getImageBlurMultController
Node Common Properties, Operators, and Methods (p. 820) General Node Properties (p. 836)
getInheritanceFlags
Node Common Properties, Operators, and Methods (p. 820)
getInheritVisibility
Node Common Properties, Operators, and Methods (p. 820)
getINISetting
Accessing INI File Keys (p. 1647)
getKBChar
Keyboard Entry (p. 1623)
getKBLine
Keyboard Entry (p. 1623)
getKBPoint
Keyboard Entry (p. 1623)
getKBValue
Keyboard Entry (p. 1623)
getKeyStepsPos
Time Configuration Dialog (p. 1616)
getKeyStepsRot
Time Configuration Dialog (p. 1616)
getKeyStepsScale
Time Configuration Dialog (p. 1616)
getKeyStepsSelOnly
Time Configuration Dialog (p. 1616)
getKeyStepsUseTrans
Time Configuration Dialog (p. 1616)
getKnotSelection
SplineShape : Shape (p. 1079)
Const Primitives
getListenerSel
Controlling the Listener Contents and the Insertion Point (p. xlii)
getListenerSelText
Controlling the Listener Contents and the Insertion Point (p. xlii)
getMaterialID
SplineShape : Shape (p. 1079)
getMatLibFileName
Material Editor (p. 1606) MaterialLibrary Values (p. 795)
getMAXFileObjectNames
3ds max File Loading and Saving (p. 1639) Zip-file Script Packages (p. 122)
getMAXOpenFileName
MAX Open & Save Dialogs (p. 177)
getMAXSaveFileName
MAX Open & Save Dialogs (p. 177)
getMeditMaterial
Material Common Properties, Operators, and Methods (p. 1203) Material Editor (p. 1606) MaterialLibrary Values (p. 795)
getMKKey
Barycentric Morph Controller : MorphController (p. 1306) Barycentric Morph Controller Keys (p. 1308)
getMKKeyIndex
Barycentric Morph Controller : MorphController (p. 1306)
getMKTargetNames
Barycentric Morph Controller : MorphController (p. 1306)
getMKTargetWeights
Barycentric Morph Controller : MorphController (p. 1306)
getMKTime
Barycentric Morph Controller Keys (p. 1308)
getMKWeight
Barycentric Morph Controller Keys (p. 1308)
getMTLMEditFlags
Material Common Properties, Operators, and Methods (p. 1203)
getMTLMeditObjType
Material Common Properties, Operators, and Methods (p. 1203)
getMTLMeditTiling
Material Common Properties, Operators, and Methods (p. 1203)
getNamedSelSetItem
SelectionSetArray Values (p. 783)
getNamedSelSetItemCount
SelectionSetArray Values (p. 783)
getNamedSelSetName
SelectionSetArray Values (p. 783)
getNodeByName
Node Common Properties, Operators, and Methods (p. 820)
getNoteTrack
Notetrack Values (p. 816) MAXNoteKeyArray Values (p. 817) Working with Note Tracks (p. 818)
getNumAxis
Main Toolbar (p. 1574)
getNumberDisplayFilters
Selection Filter (p. 61)
getNumberSelectFilters
Selection Filter (p. 61)
getNumNamedSelSets
SelectionSetArray Values (p. 783)
getOpenFileName
Standard Open and Save File Dialogs (p. 1643) ActiveX Controls in MAXScript Rollouts (p. 10) – in example
getPatchSteps getPhyContextExport
Patch : GeometryClass (p. 1088) Biped and Physique (p. 1456) PhyContextExport Values (p. 1458)
getPointController
Controller Common Properties, Operators, and Methods (p. 1289)
219
220
Chapter 1
|
What’s New in 3ds max 4 MAXScript
getPointControllers
Controller Common Properties, Operators, and Methods (p. 1289)
getPolygonCount
Node Common Properties, Operators, and Methods (p. 820)
getPosTaskWeight
Node Common Properties, Operators, and Methods (p. 820)
getProgressCancel
Progress Bar Display (p. 1578)
getProperty
Class and Object Inspector Functions (p. 799) Curve Control (p. 170) - in example ActiveX Controls in MAXScript Rollouts (p. 10) - in example
getPropertyController
Class and Object Inspector Functions (p. 799)
getReactionCount
Reactor Controllers (p. 1326)
getReactionFalloff
Reactor Controllers (p. 1326)
getReactionInfluence
Reactor Controllers (p. 1326)
getReactionName
Reactor Controllers (p. 1326)
getReactionState
Reactor controller (p. 91) - in example Reactor Controllers (p. 1326)
getReactionStrength getReactionValue
Reactor Controllers (p. 1326) Reactor controller (p. 91) - in example Reactor Controllers (p. 1326)
getRefCoordSys
Main Toolbar (p. 1574)
getRendApertureWidth
Render Scene Dialog (p. 1611)
getRenderID
Node Common Properties, Operators, and Methods (p. 820)
getRendImageAspect
Render Scene Dialog (p. 1611)
getRotTaskWeight
Node Common Properties, Operators, and Methods (p. 820)
getSaveFileName
Standard Open and Save File Dialogs (p. 1643) Viewport Drawing Methods (p. 1592) - in example Defining Macro Scripts (p. 1521) - in example
getSavePath
Standard Open and Save File Dialogs (p. 1643)
getSaveRequired
Exiting and Resetting 3ds max (p. 1669) undo (p. 687)
getScreenScaleFactor
Accessing Active Viewport Info, Type, and Transforms (p. 1581)
getSegLengths
SplineShape : Shape (p. 1079)
getSegSelection
SplineShape : Shape (p. 1079)
getSelectedReactionNum
Reactor Controllers (p. 1326)
GetSelectFilter
Selection Filter (p. 61)
getShadeCVerts
Node Common Properties, Operators, and Methods (p. 820)
getSnapMode
Status Bar Buttons (p. 1579)
getSnapState
Status Bar Buttons (p. 1579)
getSplineSelection
SplineShape : Shape (p. 1079)
getTaskAxisState
Node Common Properties, Operators, and Methods (p. 820)
getTextExtent
getTextExtent (p. 175)
Const Primitives
GetTMController gettoolbtnstate
Main Toolbar (p. 1574)
getTrajectoryOn
Node Common Properties, Operators, and Methods (p. 820)
getTransformAxis
Node Common Properties, Operators, and Methods (p. 820)
getTransformLockFlags
Node Common Properties, Operators, and Methods (p. 820)
GetUIColor
3ds max User Interface Colors (p. 1604)
getUseDraftRenderer
Render Scene Dialog (p. 1611)
getUseEnvironmentMap
Working with Atmospherics (p. 1345)
getViewFOV
Accessing Active Viewport Info, Type, and Transforms (p. 1581)
getViewSize
Accessing Active Viewport Info, Type, and Transforms (p. 1581)
getViewTM
Accessing Active Viewport Info, Type, and Transforms (p. 1581)
getVisController
General Node Properties (p. 836)
getVPortBGColor
Miscellaneous Viewport Methods and System Globals (p. 1603)
ActiveX Controls in MAXScript Rollouts (p. 10) - in example
Node Common Properties, Operators, and Methods (p. 820) getXYZControllers
XYZ Controllers (p. 1335)
group
Node Common Properties, Operators, and Methods (p. 820)
hasNoteTracks
Notetrack Values (p. 816) Working with Note Tracks (p. 818) - in example
hasProperty
hasProperty() function (p. 135)
HitByNameDlg
Main Toolbar (p. 1574)
holdMaxFile
3ds max File Loading and Saving (p. 1639)
importFile
Zip-file Script Packages (p. 122)
include
Including Scripts Within Scripts (p. lix)
3ds max File Loading and Saving (p. 1639) Symbolic Pathnames (p. 140) insertItem
Array Values (p. 776)
interpCurve3D
SplineShape : Shape (p. 1079)
intersectRayEx
Node Common Properties, Operators, and Methods (p. 820)
invalidateTM
Node Common Properties, Operators, and Methods (p. 820)
invalidateTreeTM
Node Common Properties, Operators, and Methods (p. 820)
invalidateWS
Node Common Properties, Operators, and Methods (p. 820)
isActive isBoneOnly
Node Common Properties, Operators, and Methods (p. 820)
isController
Value Common Properties, Operators, and Methods (p. 714)
isCPEdgeOnInView
Miscellaneous Viewport Methods and System Globals (p. 1603)
isCreatingObject isGroupHead
Node Common Properties, Operators, and Methods (p. 820)
221
222
Chapter 1
|
What’s New in 3ds max 4 MAXScript
isGroupMember
Node Common Properties, Operators, and Methods (p. 820)
IsNetServer
Miscellaneous Functions (p. 1663)
isOpenGroupHead
Node Common Properties, Operators, and Methods (p. 820)
isOpenGroupMember
Node Common Properties, Operators, and Methods (p. 820)
IsPointSelected
Node Common Properties, Operators, and Methods (p. 820) NURBS Node Properties and Methods (p. 1397)
isreadOnly isSceneRedrawDisabled
Refreshing the Viewports (p. 1585)
isSelectionFrozen
Status Bar Buttons (p. 1579)
IsShapeObject
Node Common Properties, Operators, and Methods (p. 820)
isStruct
Value Common Properties, Operators, and Methods (p. 714)
isStructDef
Value Common Properties, Operators, and Methods (p. 714)
IsSubSelEnabled
Modify Panel (p. 1572)
isSurfaceUVClosed
Node Common Properties, Operators, and Methods (p. 820)
LoadDefaultMatLib
Material Editor (p. 1606) MaterialLibrary Values (p. 795)
loadDllsFromDir
Miscellaneous Functions (p. 1663)
loadMaterialLibrary
Material Editor (p. 1606) MaterialLibrary Values (p. 795) Zip-file Script Packages (p. 122)
loadMaxFile
3ds max File Loading and Saving (p. 1639) Zip-file Script Packages (p. 122) Running Scripts from the Command Line (p. lvii) - in example Mouse Cursors (p. 1588) - in example External File Methods (p. 1645) - in example
locals
Visibility of Locals, Functions, Structures and User-Interface Items in Rollout Code (p. 1478) What’s New in MAXScript (p. 1) Viewport Redraw Callback Mechanism (p. 1655) Time Change Callback Mechanism (p. 1654) String Values (p. 722) Scripted Plug-in Clauses (p. 1542) Scripted Custom Attributes (p. 45) Script Controllers (p. 1329) Scope of Variables (p. 646)
lockAxisTripods
Miscellaneous Viewport Methods and System Globals (p. 1603)
log
Number Values (p. 717)
log10
Number Values (p. 717)
makeDir
External File Methods (p. 1645)
MakeNURBSConeSurface
Creating NURBSCVSurface Values (p. 1394)
Const Primitives
MakeNURBSCylinderSurface
Creating NURBSCVSurface Values (p. 1394)
MakeNURBSLatheSurface
Creating NURBSCVSurface Values (p. 1394)
MakeNURBSSphereSurface
Creating NURBSCVSurface Values (p. 1394)
MakeNURBSTorusSurface
Creating NURBSCVSurface Values (p. 1394)
mapScreenToCP
Accessing Active Viewport Info, Type, and Transforms (p. 1581)
mapScreenToView
Accessing Active Viewport Info, Type, and Transforms (p. 1581)
mapScreenToWorldRay
Accessing Active Viewport Info, Type, and Transforms (p. 1581)
matchPattern
String Values (p. 722) ActiveX Controls in MAXScript Rollouts (p. 10) - in example
MaterialBrowseDlg
Miscellaneous Dialogs (p. 1621)
MatrixFromNormal
Matrix3 Values (p. 744) Point3 Values (p. 731)
maxVersion mergeMaxFile
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
MAXScript Message and Query Dialogs (p. 1622)
mirrorIKConstraints
Node Common Properties, Operators, and Methods (p. 820)
mod
MAX Commands (p. 1630)
mouseTrack
mouseTrack() Function (p. 180)
namedSelSetListChanged
Main Toolbar (p. 1574)
newRolloutFloate
Rollout Floater Windows (p. 1477) Scripted Utilities (p. 1463) Curve Control (p. 170) - in example
newScript
WindowStream Values (p. 767) The MAXScript Editor Windows (p. xliv)
newTrackViewNode
Track View Nodes (p. 1382)
nodeColorPicker
Miscellaneous Dialogs (p. 1621)
nodeIKParamsChanged
Node Common Properties, Operators, and Methods (p. 820)
nodeInvalRect
Refreshing the Viewports (p. 1585) Node Common Properties, Operators, and Methods (p. 820) - in example
noise3
Color Values (p. 729) Point3 Values (p. 731)
noise4
Color Values (p. 729) Point3 Values (p. 731)
normtime
Time Values (p. 751)
numMapsUsed
Editable Mesh : GeometryClass and TriMesh : Value (p. 1041)
numNoteTracks
Notetrack Values (p. 816) Working with Note Tracks (p. 818) - in example
223
224
Chapter 1
|
What’s New in 3ds max 4 MAXScript
numSurfaces
Node Common Properties, Operators, and Methods (p. 820)
NURBSExtrudeNode
Creating NURBS Scene Objects (p. 1392)
NURBSLatheNode
Creating NURBS Scene Objects (p. 1392)
NURBSNode
Using the NURBS Classes and Functions to Create and Modify 3ds max NURBS Models (p. 1389)
OkMtlForScene
Interface: medit (p. 371)
OKToBindToNode
Node Common Properties, Operators, and Methods (p. 820)
openBitMap
Bitmap Values (p. 755)
openCTBitMap openEncryptedFile
FileStream Values (p. 763) Encrypted Files (p. 1647)
openfile
Function Parameters (p. 702) - in example
openlog
Turning On the Listener Log (p. xli)
openUtility
Utility and Rollout Properties, Methods, and Event Handlers (p. 1474)
pickObject
startObjectCreation() (p. 138)
FileStream Values (p. 763)
RubberBanding in pickObject() Function (p. 136) Picking Scene Nodes By Hit (p. 1618) pickOffsetDistance
Picking Points in the Viewports (p. 1589)
pickPoint
Keyboard Entry (p. 1623) Picking Points in the Viewports (p. 1589)
playAnimation
Time Control (p. 1580)
pointSelection
NURBS Node Properties and Methods (p. 1397) Node Common Properties, Operators, and Methods (p. 820)
popPrompt
Prompt Line (p. 1577)
popupMenu pow
Number Values (p. 717)
progressEnd
Progress Bar Display (p. 1578)
progressStart
Progress Bar Display (p. 1578)
progressUpdate
Progress Bar Display (p. 1578)
PushPrompt
Prompt Line (p. 1577)
qsort
Array Values (p. 776)
quatToEuler
EulerAngles Values (p. 742) Quat Values (p. 738)
queryBox quitMax
MAXScript Message and Query Dialogs (p. 1622) Running Scripts from the Command Line (p. lvii) Exiting and Resetting 3ds max (p. 1669)
radToDeg
Number Values (p. 717)
Const Primitives
reactTo
Reactor controller (p. 91) Reactor Controllers (p. 1326)
ReadByte
BinStream for Binary Reading and Writing (p. 128)
ReadFloat
BinStream for Binary Reading and Writing (p. 128)
ReadLong
BinStream for Binary Reading and Writing (p. 128)
ReadShort
BinStream for Binary Reading and Writing (p. 128)
ReadString
BinStream for Binary Reading and Writing (p. 128)
redrawViews
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
Exposing MAXScript Functions (p. 1673) Running the OLE Demo (p. 1674)
registerRedrawViewsCallback
Viewport Redraw Callback Mechanism (p. 1655)
registerRightClickMenu
Scripted Right-Click Menus (p. 1514) subMenu (p. 1520) - in example separator (p. 1519) - in example menuItem (p. 1518) - in example
registerSelectFilterCallback
class id filter (p. 59)
registerTimeCallback
Time Change Callback Mechanism (p. 1654)
registerViewWindow
Rollout Floaters as Extended viewports (p. 186)
releaseAllOLEObjects
OLE Automation (p. 1671)
releaseOLEObject
OLE Automation (p. 1671)
removeRollout
Utility and Rollout Properties, Methods, and Event Handlers (p. 1474)
ActiveX Controls in MAXScript Rollouts (p. 10)
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
Prompt Line (p. 1577)
renameFile
External File Methods (p. 1645)
render
Controlling the Renderer (p. 1664) General Event Callback Mechanism (p. 29)
replaceInstances
MAXWrapper Common Properties, Operators, and Methods (p. 809)
replacePrompt
Prompt Line (p. 1577)
rescaleWorldUnits
Miscellaneous Functions (p. 1663)
225
226
Chapter 1
|
What’s New in 3ds max 4 MAXScript
resetLattice
FFD 2x2x2 : Modifier (p. 1121) FFD 3x3x3 : Modifier (p. 1123) FFD 4x4x4 : Modifier (p. 1124) FFD Box : Modifier (p. 1117) FFD Cyl : Modifier (p. 1119)
resetLengthInterp
Shape Common Properties, Operators, and Methods (p. 945)
resetMaxFile
Exiting and Resetting 3ds max (p. 1669)
rotateXMatrix
Matrix3 Values (p. 744)
rotateYMatrix
Matrix3 Values (p. 744)
rotateYPRMatrix
Matrix3 Values (p. 744)
rotateZMatrix
Matrix3 Values (p. 744)
saveMaterialLibrary
Material Editor (p. 1606)
saveMaxFile
3ds max File Loading and Saving (p. 1639)
saveNodes
3ds max File Loading and Saving (p. 1639) SelectionSetArray Values (p. 783)
scaleMatrix
Matrix3 Values (p. 744)
seed
Number Values (p. 717)
selectBitMap
Bitmap Values (p. 755)
selectByName
Picking Scene Nodes by Name (p. 1619)
selectCTBitMap selectReaction
Reactor Controllers (p. 1326)
selectSaveBitMap
Bitmap Values (p. 755)
setActive
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338) Render Effects Common Properties, Operators, and Methods (p. 1347)
setArrowCursor
Mouse Cursors (p. 1588)
setAtmospheric
Atmospheric Effects Common Properties, Operators, and Methods (p. 1338)
setBackGround
Working with Atmospherics (p. 1345) SetBackground Method (p. 180)
setBackGroundController
Working with Atmospherics (p. 1345)
setBkgFrameRange
Viewport Background Images (p. 1586)
setBkgImageAnimate
Viewport Background Images (p. 1586)
setBkgImageAspect
Viewport Background Images (p. 1586)
setBkgORType
Viewport Background Images (p. 1586)
setBkgStartTime
Viewport Background Images (p. 1586)
setBkgSyncFrame
Viewport Background Images (p. 1586)
SetCommandPanelTaskMode
Command Panels (p. 1571)
setCoordCenter
Main Toolbar (p. 1574)
setCurNamedSelSet
Main Toolbar (p. 1574)
setCVertMode
Node Common Properties, Operators, and Methods (p. 820)
Const Primitives
setDimension
FFD Box : Modifier (p. 1117) FFD Cyl : Modifier (p. 1119)
SetDir
SetDir (p. 136)
SetDisplayFilter
Selection Filter (p. 61)
setEffect
Render Effects Common Properties, Operators, and Methods (p. 1347)
setFileAttribute
External File Methods (p. 1645)
setFocus
-jpr M029-SO selection as bitArray, ConvertTo for PolyMesh, SetFocus Minton
setGroupHead
Node Common Properties, Operators, and Methods (p. 820)
setGroupMember
Node Common Properties, Operators, and Methods (p. 820)
setGroupOpen
Node Common Properties, Operators, and Methods (p. 820)
setImageBlurMultController
Node Common Properties, Operators, and Methods (p. 820) General Node Properties (p. 836)
setImageBlurMultiplier
Node Common Properties, Operators, and Methods (p. 820)
setInheritanceFlags
Node Common Properties, Operators, and Methods (p. 820)
setInheritVisibility
Node Common Properties, Operators, and Methods (p. 820)
setINISetting
Accessing INI File Keys (p. 1647)
setKeyStepsPos
Time Configuration Dialog (p. 1616)
setKeyStepsRot
Time Configuration Dialog (p. 1616)
setKeyStepsScale
Time Configuration Dialog (p. 1616)
setKeyStepsSelOnly
Time Configuration Dialog (p. 1616)
setKeyStepsUseTrans
Time Configuration Dialog (p. 1616)
setKnotSelection
SplineShape : Shape (p. 1079)
setListenerSel
Controlling the Listener Contents and the Insertion Point (p. xlii)
setListenerSelText
Controlling the Listener Contents and the Insertion Point (p. xlii)
setMaterialID
SplineShape : Shape (p. 1079)
setMeditMaterial
Material Common Properties, Operators, and Methods (p. 1203) Material Editor (p. 1606) MaterialLibrary Values (p. 795)
setMKTime
Barycentric Morph Controller Keys (p. 1308)
setMKWeight
Barycentric Morph Controller Keys (p. 1308)
setMorphTarget
Barycentric Morph Controller : MorphController (p. 1306)
setMorphTargetName
Barycentric Morph Controller : MorphController (p. 1306)
setMotBlur
Node Common Properties, Operators, and Methods (p. 820)
setMTLMEditFlags
Material Common Properties, Operators, and Methods (p. 1203)
setMTLMeditObjType
Material Common Properties, Operators, and Methods (p. 1203)
setMTLMeditTiling
Material Common Properties, Operators, and Methods (p. 1203)
setOpenSceneScript setPatchSteps
Patch : GeometryClass (p. 1088)
227
228
Chapter 1
|
What’s New in 3ds max 4 MAXScript
setPosTaskWeight
Node Common Properties, Operators, and Methods (p. 820)
setProgressCancel
Progress Bar Display (p. 1578)
setProperty
Class and Object Inspector Functions (p. 799) ActiveX Controls in MAXScript Rollouts (p. 10) - in example
SetPropertyController
Class and Object Inspector Functions (p. 799)
setReactionFalloff
Reactor Controllers (p. 1326)
setReactionInfluence
Reactor Controllers (p. 1326)
setReactionName
Reactor Controllers (p. 1326)
setReactionState
Reactor Controllers (p. 1326)
setReactionStrength
Reactor Controllers (p. 1326)
setReactionValue
Reactor Controllers (p. 1326)
setRefCoordSys
Main Toolbar (p. 1574)
setRenderable
Node Common Properties, Operators, and Methods (p. 820)
setRenderID
Node Common Properties, Operators, and Methods (p. 820)
setRotTaskWeight
Node Common Properties, Operators, and Methods (p. 820)
setSaveRequired
Exiting and Resetting 3ds max (p. 1669) undo (p. 687)
setSaveSceneScript setSegSelection
SplineShape : Shape (p. 1079)
SetSelectFilter
Selection Filter (p. 61)
setShadeCVerts
Node Common Properties, Operators, and Methods (p. 820)
setSilentMode
Bitmap Values (p. 755)
setSplineSelection
SplineShape : Shape (p. 1079)
setStatusXYZ
Coordinate Display (p. 1578)
setSysCur
Mouse Cursors (p. 1588)
setTaskAxisState
Node Common Properties, Operators, and Methods (p. 820)
setToolBtnState
Main Toolbar (p. 1574)
setTrajectoryOn
Node Common Properties, Operators, and Methods (p. 820)
setTransformLockFlags
Node Common Properties, Operators, and Methods (p. 820)
SetUIColor
3ds max User Interface Colors (p. 1604)
setupEvents SetUseDraftRenderer
Render Scene Dialog (p. 1611)
setUseEnvironmentMap
Working with Atmospherics (p. 1345)
setVPortBGColor
Miscellaneous Viewport Methods and System Globals (p. 1603)
setWaitCursor
Mouse Cursors (p. 1588)
ShellLaunch
Executing External Commands (p. 1668)
showAllActiveXControls
ActiveX Controls in MAXScript Rollouts (p. 10)
Const Primitives
showClass
Class and Object Inspector Functions (p. 799)
showEvents
ActiveX Controls in MAXScript Rollouts (p. 10)
showMethods
ActiveX Controls in MAXScript Rollouts (p. 10)
showSource
The MAXScript Editor Windows (p. xliv)
showTextureMap
showTextureMap() function (p. 167)
Dynamic Properties (p. 805)
Creating Functions (p. 699) Material Editor (p. 1606) Node Common Properties, Operators, and Methods (p. 820) - in example TextureMap Common Properties, Operators, and Methods (p. 1235) Working with Editable Meshes (p. 1077) silentMode
Bitmap Values (p. 755)
sin
Number Values (p. 717)
sinh
Number Values (p. 717)
sleep
Pausing Script Execution (p. 1664)
snapshotAsMesh
Node Common Properties, Operators, and Methods (p. 820)
sqrt
Number Values (p. 717)
squadrev
Quat Values (p. 738)
startObjectCreation
Create Panel (p. 1572) Defining Macro Scripts (p. 1521) startObjectCreation() (p. 138)
startTool
Mouse Tool Clauses (p. 1532) Scripted Mouse Tools (p. 1531)
stopAnimation stopCreating
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
Scripted Mouse Tools (p. 1531)
subdivideSegment
SplineShape : Shape (p. 1079)
swap
Miscellaneous Functions (p. 1663)
tan
Number Values (p. 717)
tangentCurve3D
SplineShape : Shape (p. 1079)
tanh
Number Values (p. 717)
thawSelection
Status Bar Buttons (p. 1579)
timeStamp
Time Stamping (p. 1664)
TransMatrix
Matrix3 Values (p. 744) Scripted Manipulator (p. 97) - in example Scripted Manipulators (p. 97) - in example
229
230
Chapter 1
|
What’s New in 3ds max 4 MAXScript
turbulence
Color Values (p. 729) Point3 Values (p. 731)
ungroup
Node Common Properties, Operators, and Methods (p. 820)
uniqueName
Node Common Properties, Operators, and Methods (p. 820)
unregisterAllRightClickMenus
Scripted Right-Click Menus (p. 1514)
unregisterRedrawViewsCallback Viewport Redraw Callback Mechanism (p. 1655) unregisterRightClickMenu
Scripted Right-Click Menus (p. 1514)
unregisterSelectFilterCallback
class id filter (p. 59)
unregisterTimeCallback
Time Change Callback Mechanism (p. 1654)
unRegisterViewWindow
Rollout Floaters as Extended viewports (p. 186)
updateMTLInMedit
Material Common Properties, Operators, and Methods (p. 1203)
updateSurfaceMapper
Surface Mapper : SpacewarpModifier (p. 1202)
validModifier
Node Common Properties, Operators, and Methods (p. 820) validModifer() function (p. 142) Modifier Common Properties, Operators, and Methods (p. 1096)
WriteByte
BinStream for Binary Reading and Writing (p. 128)
WriteFloat
BinStream for Binary Reading and Writing (p. 128)
WriteLong
BinStream for Binary Reading and Writing (p. 128)
WriteShort
BinStream for Binary Reading and Writing (p. 128)
WriteString
BinStream for Binary Reading and Writing (p. 128)
yesNoCancelBox
MAXScript Message and Query Dialogs (p. 1622)
See Also Definitions for MAXScript internal organization (p. 188)
Const StructDef
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)
231
232
Chapter 1
|
What’s New in 3ds max 4 MAXScript
skinOps (p. 253) snapMode (p. 254) splineOps (p. 255) sysInfo (p. 255) systemTools (p. 256) terrainOps (p. 256) timeConfiguration (p. 256) toolMode (p. 257) trackbar (p. 257) trackview (p. 257) units (p. 258) viewport (p. 258) WAVsound (p. 258) xrefPaths (p. 259) xrefs (p. 259)
See Also Definitions for MAXScript internal organization (p. 188)
Const StructDef Pages AttachCtrl const StructDef Attachment : PositionController (p. 1304) AttachCtrl.addNewKey AttachCtrl.getKey
Attachment Controller Keys (p. 1305)
autoBackup const StructDef 3D Studio MAX System Globals (p. 630) autoBackup.enabled autoBackup.time
SystemGlobal:enabled SystemGlobal:time
false 5.0
bit const StructDef
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
233
234
Chapter 1
|
What’s New in 3ds max 4 MAXScript
cui const StructDef 3D Studio MAX System Globals (p. 630) Menu and CUI Loading Command Panels (p. 1571) Custom User Interface Files (p. 1648) cui.commandPanelOpen cui.expertModeOff cui.expertModeOn cui.getConfigFile cui.GetDir cui.getExpertMode cui.loadConfig cui.saveConfig cui.saveConfigAs cui.setConfigFile
SystemGlobal:commandPanelOpen
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
true
fileProperties const StructDef
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
235
236
Chapter 1
|
What’s New in 3ds max 4 MAXScript
gw.GetPointOnCP gw.getRndLimits gw.getRndMode gw.getSkipCount gw.getUpdateRect gw.getViewportDib gw.GetVPWorldWidth gw.getWinDepth gw.getWinSizeX gw.getWinSizeY gw.getYonCoord gw.hMarSker gw.hPolygon gw.hPolyline gw.hText gw.hTransPoint gw.hTriStrip gw.isPerspectiveView gw.IsPerspView gw.MapCPToWorld gw.marker gw.NonScalingObjectSize gw.polygon gw.polyline gw.querySupport gw.resetUpdateRect gw.setColor gw.setPos gw.setRndLimits gw.setSkipCount gw.setTransform gw.SnapLength gw.SnapPoint gw.text gw.transPoint gw.updateScreen gw.wMarker gw.wPolygon gw.wPolyline gw.wText gw.wTransPoint gw.wTriStrip
See Also Accessing Active Viewport Info, Type, and Transforms (p. 1581)
ik const StructDef
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
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
SystemGlobal:altPressed SystemGlobal:controlPressed SystemGlobal:escPressed SystemGlobal:shiftPressed
false false false false
237
238
Chapter 1
|
What’s New in 3ds max 4 MAXScript
LE.deleteLightByName LE.lightIndex LE.lightName LE.load LE.numLights LE.save
LinkCtrl const StructDef Link Control : Matrix3Controller (p. 1316) LinkCtrl.addLink LinkCtrl.deleteLink LinkCtrl.getLinkCount LinkCtrl.getLinkNode LinkCtrl.getLinkTime LinkCtrl.setLinkNode LinkCtrl.setLinkTime
ListCtrl const StructDef List Controller (p. 143) ListCtrl.getActive ListCtrl.getName ListCtrl.setActive ListCtrl.setName
See Also List Controllers (p. 1317)
ListCtrl const StructDef List Controller (p. 143) ListCtrl.getActive ListCtrl.getName ListCtrl.setActive ListCtrl.setName
See Also List Controllers (p. 1317)
logsystem const StructDef
logsystem const StructDef 3D Studio MAX System Globals (p. 630) logsystem.quietMode
SystemGlobal:quietMode
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
false
239
240
Chapter 1
|
What’s New in 3ds max 4 MAXScript
meshop.deleteMapVertSet meshop.deleteVerts meshop.detachFaces meshop.detachVerts meshop.divideEdge meshop.divideEdges meshop.divideFace meshop.divideFaceByEdges meshop.divideFaces meshop.edgeTessellate meshop.explodeAllFaces meshop.explodeFaces meshop.extrudeEdges meshop.extrudeFaces meshop.flipNormals meshop.freeMapChannel meshop.freeMapFaces meshop.freeMapVerts meshop.freeVAlphas meshop.freeVData meshop.freeVertCorners meshop.freeVertWeights meshop.freeVSelectWeights meshop.getAffectBackfacing meshop.getBaryCoords meshop.getBubble meshop.getDisplacementMapping meshop.getEdgesReverseEdge meshop.getEdgesUsingFace meshop.getEdgesUsingVert meshop.getElementsUsingFace meshop.getExtrusionType meshop.getFaceArea meshop.getFaceCenter meshop.getFaceRNormals meshop.getFacesUsingEdge meshop.getFacesUsingVert meshop.getFalloff meshop.getHiddenFaces meshop.getHiddenVerts meshop.getIgnoreBackfacing meshop.getIgnoreVisEdges meshop.getIsoMapVerts meshop.getIsoVerts meshop.getMapFace meshop.getMapFacesUsingMapVert meshop.getMapSupport meshop.getMapVert meshop.getMapVertsUsingMapFace meshop.getNormalSize meshop.getNumCPVVerts
meshop const StructDef
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
241
242
Chapter 1
|
What’s New in 3ds max 4 MAXScript
meshop.moveVert meshop.moveVertsToPlane meshop.optimize meshop.removeDegenerateFaces meshop.removeIllegalFaces meshop.resetVAlphas meshop.resetVertCorners meshop.resetVertWeights meshop.resetVSelectWeights meshop.setAffectBackfacing meshop.setBubble meshop.setDisplacementMapping meshop.setExtrusionType meshop.setFaceAlpha meshop.setFaceColor meshop.setFalloff meshop.setHiddenFaces meshop.setHiddenVerts meshop.setIgnoreBackfacing meshop.setIgnoreVisEdges meshop.setMapFace meshop.setMapSupport meshop.setMapVert meshop.setNormalSize meshop.setNumCPVVerts meshop.setNumFaces meshop.setNumMapFaces meshop.setNumMaps meshop.setNumMapVerts meshop.setNumTVerts meshop.setNumVDataChannels meshop.setNumVerts meshop.setPinch meshop.setPlanarThreshold meshop.setSelByVertex meshop.setShowFNormals meshop.setShowVNormals meshop.setSoftSel meshop.setSplitMesh meshop.setSSEdgeDist meshop.setSSUseEdgeDist meshop.setSubdivisionAngle meshop.setSubdivisionDisplacement meshop.setSubdivisionDistance meshop.setSubdivisionEdge meshop.setSubdivisionMaxLevels meshop.setSubdivisionMaxTriangles meshop.setSubdivisionMethod meshop.setSubdivisionMinLevels meshop.setSubdivisionSteps meshop.setSubdivisionStyle
meshOps const StructDef
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
243
244
Chapter 1
|
What’s New in 3ds max 4 MAXScript
meshOps.startChamfer meshOps.startCreate meshOps.startCut meshOps.startDivide meshOps.startExtrude meshOps.startFlipNormalMode meshOps.startSlicePlane meshOps.startTurn meshOps.startWeldTarget meshOps.tessellate meshOps.unhideAll meshOps.unifyNormal meshOps.viewAlign meshOps.visibleEdge meshOps.weld
modPanel const StructDef Modify Panel (p. 1572) modPanel.addModToSelection modPanel.getCurrentObject modPanel.getModifierIndex modPanel.setCurrentObject
See Also Modifier Common Properties, Operators, and Methods (p. 1096) Modifier : MAXWrapper and SpacewarpModifier : MAXWrapper (p. 1095)
mouse const StructDef Mouse Cursors (p. 1588) mouse.buttonStates mouse.mode mouse.pos mouse.screenpos SystemGlobal:screenpos
mtlBrowser const StructDef Miscellaneous Dialogs (p. 1621) mtlBrowser.browseFrom
See Also mtlBrowser (p. 180)
SystemGlobal:buttonStates SystemGlobal:mode SystemGlobal:pos [657,577]
#{} 0 [106,85]
options const StructDef
options const StructDef MAXScript System Globals (p. 640) options.oldPrintStyles
SystemGlobal:oldPrintStyles
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
false
245
246
Chapter 1
|
What’s New in 3ds max 4 MAXScript
patch.getVertEdges patch.getVertPatches patch.getVertType patch.getVertVecs patch.interpQuadPatch patch.interpTriPatch patch.makeQuadPatch patch.makeTriPatch patch.maxMapChannels patch.patchNormal patch.setAdaptive patch.setMapPatch patch.setMapSupport patch.setMapVert patch.setMeshSteps patch.setMeshStepsRender patch.setMtlID patch.setNumEdges patch.setNumMapPatches patch.setNumMaps patch.setNumMapVerts patch.setNumPatches patch.setNumVecs patch.setNumVerts patch.setPatchMtlID patch.setShowInterior patch.setVec patch.setVert patch.subdivideEdges patch.subdividePatches patch.transform patch.unifyNormals patch.update patch.updatePatchNormals patch.weld2Verts patch.weldEdges patch.weldVerts
See Also Patch Select - superclass: modifier (p. 307) patchOps const StructDef (p. 247)
patchOps const StructDef
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
247
248
Chapter 1
|
What’s New in 3ds max 4 MAXScript
polyop const StructDef polyop.applyUVWMap polyop.attach polyop.autosmooth polyop.breakVerts polyop.capHolesByEdge polyop.capHolesByFace polyop.capHolesByVert polyop.collapseDeadStructs polyop.collapseEdges polyop.collapseFaces polyop.collapseVerts polyop.createEdge polyop.createPolygon polyop.createShape polyop.createVert polyop.cutEdge polyop.cutFace polyop.cutVert polyop.defaultMapFaces polyop.deleteEdges polyop.deleteFaces polyop.deleteIsoVerts polyop.deleteVerts polyop.detachEdges polyop.detachFaces polyop.detachVerts polyop.divideEdge polyop.divideFace polyop.fillInMesh polyop.flipNormals polyop.forceSubdivision polyop.freeEData polyop.freeVData polyop.getBorderFromEdge polyop.getDeadEdges polyop.getDeadFaces polyop.getDeadVerts polyop.getEDataChannelSupport polyop.getEDataValue polyop.getEdgeFaces polyop.getEdgeFlags polyop.getEdgesByFlag polyop.getEdgeSelection polyop.getEdgesUsingFace polyop.getEdgesUsingVert polyop.getEdgeVerts polyop.getEdgeVis polyop.getElementsUsingFace polyop.getFaceArea
polyop const StructDef
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
249
250
Chapter 1
|
What’s New in 3ds max 4 MAXScript
polyop.moveFacesToPlane polyop.moveVert polyop.moveVertsToPlane polyop.propagateFlags polyop.resetEData polyop.resetSlicePlane polyop.resetVData polyop.retriangulate polyop.setDiagonal polyop.setEDataChannelSupport polyop.setEDataValue polyop.setEdgeFlags polyop.setEdgeSelection polyop.setEdgeVis polyop.setFaceColor polyop.setFaceFlags polyop.setFaceMatID polyop.setFaceSelection polyop.setFaceSmoothGroup polyop.setHiddenFaces polyop.setHiddenVerts polyop.setMapFace polyop.setMapSupport polyop.setMapVert polyop.setNumEDataChannels polyop.setNumMapFaces polyop.setNumMaps polyop.setNumMapVerts polyop.setNumVDataChannels polyop.setSlicePlane polyop.setVDataChannelSupport polyop.setVDataValue polyop.setVert polyop.setVertColor polyop.setVertFlags polyop.setVertSelection polyop.slice polyop.splitEdges polyop.tessellateByEdge polyop.tessellateByFace polyop.tessellateByVert polyop.unHideAllFaces polyop.unHideAllVerts polyop.weldEdges polyop.weldEdgesByThreshold polyop.weldVerts polyop.weldVertsByThreshold
polyOps const StructDef
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
251
252
Chapter 1
|
What’s 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
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
Area: 1.5 true
skinOps const StructDef
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
253
254
Chapter 1
|
What’s New in 3ds max 4 MAXScript
skinOps.pasteToSelectedBone skinOps.RemoveBone skinOps.RemoveCrossSection skinOps.ReplaceVertexWeights skinOps.resetAllBones skinOps.resetSelectedBone skinOps.resetSelectedVerts skinOps.saveEnvelope skinOps.SelectBone skinOps.selectCrossSection skinOps.selectEndPoint skinOps.selectGizmo skinOps.selectGizmoType skinOps.selectNextBone skinOps.selectPreviousBone skinOps.selectStartPoint skinOps.SelectVertices skinOps.setBonePropEnvelopeVisible skinOps.setBonePropFalloff skinOps.setBonePropRelative skinOps.SetCrossSectionU skinOps.SetEndPoint skinOps.SetInnerRadius skinOps.SetOuterRadius skinOps.setSelectedBonePropEnvelopeVisible skinOps.setSelectedBonePropFalloff skinOps.setSelectedBonePropRelative skinOps.SetStartPoint skinOps.SetVertexWeights skinOps.ZoomToBone skinOps.ZoomToGizmo
snapMode const StructDef Status Bar Buttons (p. 1579) snapMode.active snapMode.type
SystemGlobal:active SystemGlobal:type
See Also snapMode (p. 182) 3D Studio MAX System Globals (p. 630)
false 3D
splineOps const StructDef
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]
255
256
Chapter 1
|
What’s 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
Admini
SystemGlobal:windowsdir
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
See Also 3D Studio MAX System Globals (p. 630)
SystemGlobal:playActiveOnly SystemGlobal:playbackSpeed SystemGlobal:realTimePlayback SystemGlobal:useTrackBar
true 3 true true
toolMode const StructDef
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
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)
SystemGlobal:filter
all
SystemGlobal:visible
true
257
258
Chapter 1
|
What’s 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
FL feet 660.0
SystemGlobal:DisplayType
Generic
SystemGlobal:MetricType SystemGlobal:SystemScale SystemGlobal:SystemType SystemGlobal:USFrac SystemGlobal:USType
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
4
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
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)
259
260
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Colored Shadow - superclass: MAXObject (p. 273) Combustion.coordinates - superclass: MAXObject (p. 274) Cone Angle - superclass: helper (p. 276) ConeAngleManip - superclass: helper (p. 277) ConvertToPatch - superclass: modifier (p. 278) DeletePatch - superclass: modifier (p. 279) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) Drag - superclass: SpacewarpObject (p. 149) emissionRenderElement - superclass: MAXObject (p. 285) FloatList - superclass: FloatController (p. 286) FloatReactor - superclass: FloatController (p. 287) Hose - superclass: GeometryClass (p. 146) HSDS Modifier - superclass: modifier (p. 290) HSDSObject - superclass: modifier (p. 292) imageMotionBlur - superclass: renderEffect (p. 294) Link - superclass: Matrix3Controller (p. 294) Link.link params - superclass: MAXObject (p. 295) Link Constraint - superclass: Matrix3Controller (p. 295) Link Constraint.link_params - superclass: MAXObject (p. 296) LinkedXForm - superclass: modifier (p. 297) LookAt Constraint - superclass: RotationController (p. 297) Mesher - superclass: GeometryClass (p. 298) meshsmooth - superclass: modifier (p. 298) Motion Blur - superclass: renderEffect (p. 302) MultiRes - superclass: modifier (p. 153) Normalize Spl - superclass: modifier (p. 305) Orientation Constraint - superclass: RotationController (p. 306) particleMesher - superclass: GeometryClass (p. 306) Patch Select - superclass: modifier (p. 307) Path Constraint - superclass: PositionController (p. 307) PDynaflector - superclass: SpacewarpObject (p. 309) Plane Angle - superclass: helper (p. 310) PlaneAngleManip - superclass: helper (p. 311)
New Classes in version 4
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)
261
262
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Turn_to_Mesh - superclass: modifier (p. 340) Turn_to_Patch - superclass: modifier (p. 342) Turn_to_Poly - superclass: modifier (p. 343) UDynaDeflector - superclass: SpacewarpObject (p. 345) USpawnDeflector - superclass: SpacewarpObject (p. 346) UVWUnwrap - superclass: modifier (p. 347) Vortex - superclass: SpacewarpObject (p. 156) Z_Depth - superclass: MAXObject (p. 350) ZRenderElement - superclass: MAXObject (p. 351)
New Classes in version 4 Pages Additive_Euler_XYZ - superclass: RotationController Additive_Euler_XYZ - superclass: RotationController; super-superclass:MAXWrapper 3:3 - classID: #(8226, 0) .additive_x_rotation Float default: 0.0 -animatable; float; Controller Scaling: (1 : 57.2958) .additive_y_rotation Float default: 0.0 -animatable; float; Controller Scaling: (1 : 57.2958) .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: .enabled
BooleanClass
default: true
--
boolean
default: true
--
boolean; FilteringOn
Shows whether the element is enabled. .filterOn
BooleanClass
Shows whether the active antialiasing filter is enabled for the element. .elementName
String
default: “Alpha”
--
string
Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected. .bitmap
UndefinedClass
default: undefined
--
bitmap
alphaRenderElement - superclass: MAXObject
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: .enabled
BooleanClass
default: true
--
default: true
--
boolean
Shows whether the element is enabled. .filterOn boolean; FilteringOn
BooleanClass
Shows whether the active antialiasing filter is enabled for the element. .elementName string
String
default: “Alpha”
--
Shows the name of the currently selected element. You can type in a custom name for the element.
263
264
Chapter 1
|
What’s New in 3ds max 4 MAXScript
This control is unavailable when multiple elements are selected. .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: .enabled
BooleanClass
default: true
--
boolean
default: true
--
boolean;
Shows whether the element is enabled. .filterOn FilteringOn
BooleanClass
Shows whether the active antialiasing filter is enabled for the element. .elementName
String
default: “Atmosphere”
--
string
atmosphereRenderElement - superclass: MAXObject
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. .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: .enabled boolean
BooleanClass
default: true
--
BooleanClass
default: true
--
Shows whether the element is enabled. .filterOn boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element.
265
266
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.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. .bitmap - bitmap
UndefinedClass
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)
default: undefined
-
AutomaticAdaptiveExposureControl - superclass: MAXObject
AutomaticAdaptiveExposureControl - superclass: MAXObject AutomaticAdaptiveExposureControl - superclass: MAXObject; super-superclass:Value - 5:0 - classID: #(2020371114, 1150503387) Constructor: AutomaticAdaptiveExposureControl ...
Properties: .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. .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. .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 eye’s response to dim lighting. In dim lighting, the eye does not perceive colors and sees tones of gray instead. The effect of this setting is not apparent except at very low light levels: below 5.62 candelas. This occurs only if the Physical Scale is less than 5.62, if a light’s Multiplier is less than 0.00017, or both. When Physical Scale is less than 0.00562, the scene is completely gray. .whiteColor Color default: (color 255 255 255) -- animatable; RGB color; Color_Discrimination; Controller Scaling: ([1,1,1] : (color 255 255 255))
267
268
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.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: .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. .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. .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 eye’s response to dim lighting. In dim lighting, the eye does not perceive colors and sees tones of gray instead. The effect of this setting is not apparent except at very low light levels: below 5.62 candelas. This occurs only if the Physical Scale is less than 5.62, if a light’s Multiplier is less
BackgroundRenderElement - superclass: MAXObject
than 0.00017, or both. When Physical Scale is less than 0.00562, the scene is completely gray. .whiteColor Color default: (color 255 255 255) -animatable; RGB color; Color_Discrimination; Controller Scaling: ([1,1,1] : (color 255 255 255)) .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: .enabled boolean
BooleanClass
default: true
--
BooleanClass
default: true
--
Shows whether the element is enabled. .filterOn boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element. .elementName “Background” -- 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. .bitmap bitmap
UndefinedClass
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)
default: undefined
--
269
270
Chapter 1
|
What’s New in 3ds max 4 MAXScript
clrShadowRenderElement - superclass: MAXObject (p. 272) Colored Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)
bgndRenderElement - superclass: MAXObject bgndRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(15, 0) Constructor: bgndRenderElement ...
Properties: .enabled
BooleanClass
default: true
--
boolean
default: true
--
boolean;
Shows whether the element is enabled. .filterOn FilteringOn
BooleanClass
Shows whether the active antialiasing filter is enabled for the element. .elementName string
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. .bitmap bitmap
UndefinedClass
See Also bitmapTex interfaces: (p. 434) Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264)
default: undefined
--
BlendRenderElement - superclass: MAXObject
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: .enabled
BooleanClass
default: true
--
boolean
default: true
--
boolean;
Shows whether the element is enabled. .filterOn FilteringOn
BooleanClass
Shows whether the active antialiasing filter is enabled for the element. .elementName
String
default: “Blend”
--
string
Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected. .bitmap
UndefinedClass
default: undefined
--
bitmap
.atmosphereOn
BooleanClass
default: true
--
boolean
default: true
--
boolean;
When on, include atmospheric effects. Default=on. .shadowOn ShadowsOn
BooleanClass
When on, include shadows. Default=on.
271
272
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.diffuseOn Diffuse_On
BooleanClass
default: true
--
boolean;
--
boolean;
--
boolean;
default: true
--
boolean;
default: true
--
boolean;
default: true
--
boolean;
When on, include the diffuse color component. Default=on. .ambientOn Ambient_On
BooleanClass
default: true
When on, include the ambient color component. Default=on. .specularOn Specular_On
BooleanClass
default: true
When on, include the specular color component. Default=on. .emissionOn Self_Illumination
BooleanClass
When on, include self-illumination. Default=on. .reflectionOn Reflection_On
BooleanClass
When on, include reflections. Default=on. .refractionOn Refraction_On
BooleanClass
When on, include refractions. Default=on.
clrShadowRenderElement - superclass: MAXObject clrShadowRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(14, 0) Constructor: clrShadowRenderElement ...
Properties: .enabled boolean
BooleanClass
default: true
--
BooleanClass
default: true
--
Shows whether the element is enabled. .filterOn boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element. .elementName Shadow” -- string
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. .bitmap bitmap
UndefinedClass
default: undefined
--
Colored_Shadow - superclass: MAXObject
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: .enabled
BooleanClass
default: true
--
boolean
default: true
--
boolean;
Shows whether the element is enabled. .filterOn FilteringOn
BooleanClass
Shows whether the active antialiasing filter is enabled for the element. .elementName string
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. .bitmap
UndefinedClass
default: undefined
--
bitmap
273
274
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)
Combustion.coordinates - superclass: MAXObject Combustion.coordinates - superclass: MAXObject; super-superclass:Value - 16:0 - classID: #(256, 0) Constructor: Combustion.coordinates ...
Properties: .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. .mapping
Integer
default: 0
.mapChannel
Integer
default: 1
.mappingType
Integer
default: 0
.phase Float
default: 0.0
--
animatable; float
Combustion.coordinates - superclass: MAXObject
.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. .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. .U_Tiling float
Float
default: 1.0
--
animatable;
Determines the number of times the map is tiled (repeated) along each axis. .V_Tiling float
Float
default: 1.0
--
animatable;
Determines the number of times the map is tiled (repeated) along each axis. .U_Angle Float angle; Controller Scaling: (1 : 57.2958)
default: 0.0
--
animatable;
--
animatable;
--
animatable;
Rotates the map about the U, V, or W axis (in degrees). .V_Angle Float angle; Controller Scaling: (1 : 57.2958)
default: 0.0
Rotates the map about the U, V, or W axis (in degrees). .W_Angle Float angle; Controller Scaling: (1 : 57.2958)
default: 0.0
Rotates the map about the U, V, or W axis (in degrees). .Noise_Amount float
Float
default: 1.0
--
animatable;
.Noise_Size float
Float
default: 1.0
--
animatable;
.Noise_Levels integer
Integer
default: 1
--
animatable;
.Blur_Offset float
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)
275
276
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Cone_Angle - superclass: helper Cone_Angle - superclass: helper; super-superclass:node - 6:0 - classID: #(629233518, 624568848) Constructor: Cone_Angle ...
Properties: .Origin Point3 .Direction Point3 .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. .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. .UseSquare Use_Square
BooleanClass default: false
--
boolean;
When on, the base of the cone is square or rectangular, rather than circular. Default=off. .Aspect
Float
default: 1.0
--
float
When Use Square is on, adjusts the aspect ratio of the rectangular cone base. Default=1.0.
See Also Scripted Manipulators (p. 97) Interface: manip (p. 366) radiusManip interfaces: (p. 500) ConeAngleManip - superclass: helper (p. 277) PlaneAngleManip - superclass: helper (p. 311) Scripted Plug-ins (p. 1538) sliderManipulator - superclass: helper (p. 333) sliderManipulator interfaces: (p. 520) uvwMappingHeightManip interfaces: (p. 551) uvwMappingLengthManip interfaces: (p. 555) uvwMappingUTileManip interfaces: (p. 558) uvwMappingVTileManip interfaces: (p. 562) uvwMappingWidthManip interfaces: (p. 565)
ConeAngleManip - superclass: helper
ConeAngleManip - superclass: helper ConeAngleManip - superclass: helper; super-superclass:node - 6:0 - classID: #(629233518, 624568848) Constructor: ConeAngleManip ...
Properties: .Origin Point3 .Direction Point3 .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. .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. .UseSquare Use_Square
BooleanClass
default: false
--
boolean;
When on, the base of the cone is square or rectangular, rather than circular. Default=off. .Aspect
Float
default: 1.0
--
float
When Use Square is on, adjusts the aspect ratio of the rectangular cone base. Default=1.0.
See Also Interface: manip (p. 366) sliderManipulator interfaces: (p. 520) radiusManip interfaces: (p. 500) uvwMappingHeightManip interfaces: (p. 551) uvwMappingLengthManip interfaces: (p. 555) uvwMappingUTileManip interfaces: (p. 558) uvwMappingVTileManip interfaces: (p. 562) uvwMappingWidthManip interfaces: (p. 565) ConeAngleManip - superclass: helper (p. 277) PlaneAngleManip - superclass: helper (p. 311) Scripted Plug-ins (p. 1538) sliderManipulator - superclass: helper (p. 333)
277
278
Chapter 1
|
What’s New in 3ds max 4 MAXScript
ConvertToPatch - superclass: modifier ConvertToPatch - superclass: modifier; super-superclass:MAXWrapper - 4:0 - classID: #(1011577041, 590161861) The Turn To Patch modifier lets you apply object conversions in the modifier stack. Using the Turn To Patch modifier, you can fine-tune the conversion process such as turning quads into quad patches. Note: Converting from one object type to another causes a complete caching in the modifier stack. When you have large objects in your scene, this can take up a lot of space. For example, an object that starts as a mesh, converts to a patch, and then back to a mesh takes 3 times as much space as a mesh which just has ordinary modifiers like Bend or UVW Map applied. Note: Converting from one object type to another causes a complete caching in the modifier stack. When you have large objects in your scene, this can take up a lot of space. For example, an object that starts as a mesh, converts to a patch, and then back to a mesh takes 3 times as much space as a mesh which just has ordinary modifiers like Bend or UVW Map applied. Constructor: ConvertToPatch ...
Properties: .quadsToQuads BooleanClass animatable; boolean; Quads_to_Quad_Patches
default: true
--
Turns quad faces in meshes or polymeshes into quad patches. .selectionConversion Selection_Conversion .useSoftSelection Use_Soft_Selection
Integer
default: 0
--
integer;
Integer
default: 1
--
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. .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
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: .enabled
BooleanClass
default: true
--
boolean
default: true
--
boolean;
Shows whether the element is enabled. .filterOn FilteringOn
BooleanClass
Shows whether the active antialiasing filter is enabled for the element. .elementName
String
default: “Diffuse”
--
string
Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected. .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) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285)
--
bitmap
279
280
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)
diffuseRenderElement - superclass: MAXObject diffuseRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(4, 0) Constructor: diffuseRenderElement ...
Properties: .enabled boolean
BooleanClass
default: true
--
BooleanClass
default: true
--
Shows whether the element is enabled. .filterOn boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element. .elementName string
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. .bitmap bitmap
UndefinedClass
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)
default: undefined
--
Drag - superclass: SpacewarpObject
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: .‘time on’
Integer
default: 0
--
integer; Time_On
The frame numbers at which the space warp becomes active and becomes inactive. .‘time off’ Time_Off
Integer
default: 16000
--
animatable; integer;
The frame numbers at which the space warp becomes active and becomes inactive. .symmetry Damping_Symmetry
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. .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 that’s affected by the damping. .rangex
Float
default: 100.0
--
animatable; float; X_Range
281
282
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Sets the thickness of the “range plane,” or the infinite plane perpendicular to the specified axis. Takes effect only when Unlimited Range is turned off. .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. .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 that’s affected by the damping. .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. .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. .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 that’s affected by the damping. .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. .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. .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 that’s affected by the damping. Tangential specifies the percentage of particle motion across the body of the Drag icon that’s affected by the damping.
Drag - superclass: SpacewarpObject
.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. .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. .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 that’s affected by the damping. Tangential specifies the percentage of particle motion across the body of the Drag icon that’s affected by the damping. .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. .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. .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 icon’s long axis (Axial) that’s affected by the damping, on a per-frame basis. .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. .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
283
284
Chapter 1
|
What’s New in 3ds max 4 MAXScript
beyond the Range, it is measured from the center of the icon, and always has a minimum value equal to the Range value. Takes effect only when Unlimited Range is turned off. .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 icon’s long axis (Axial) that’s affected by the damping, on a per-frame basis. .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. .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. .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 icon’s long axis (Axial) that’s affected by the damping, on a per-frame basis. .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. .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. .rangeless .iconsize
BooleanClass Float
Specifies the size of the icon.
default: true default: 10.0
---
boolean; Unlimited_Range float; Icon_Size
emissionRenderElement - superclass: MAXObject
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
--
BooleanClass
default: true
--
Shows whether the element is enabled. <emissionRenderElement>.filterOn boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element. <emissionRenderElement>.elementName Illumination” -- string
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
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)
default: undefined
--
285
286
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Colored Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)
FloatList - superclass: FloatController FloatList - superclass: FloatController; super-superclass:MAXWrapper - 1:1 - classID: #(1263210496, 0) The List controller combines multiple controllers into a single effect. It is a compound controller with tools for managing the order in which its internal controllers are calculated. Controllers are evaluated in a top to bottom order; the controller at the top of the list is evaluated first. When you assign a List controller to a parameter, the current controller is moved one level below the List controller; it becomes the first controller in the list. A second parameter is added below the List controller and is named Available. This is an empty placeholder for the next controller you add to the list. Constructor: ...
Properties: .available Float default: 0.0 Controller Scaling: (1 : 0.0); WeirdScaled (0.0)
See Also FloatList interfaces: (p. 450)
--
animatable; float;
FloatReactor - superclass: FloatController
FloatReactor - superclass: FloatController FloatReactor - superclass: FloatController; super-superclass:MAXWrapper - 0:0 classID: #(1904049439, 306976571)
See Also FloatReactor interfaces: (p. 452)
Hose - superclass: GeometryClass Hose - superclass: GeometryClass; super-superclass:node - 27:0 - classID: #(1777953373, 593249034) The Hose object is a flexible object that you can connect between two objects, whereupon it reacts to their movement. It’s similar to Spring, but does not have dynamics properties. You can specify the overall diameter and length of the hose, the number of turns, and the diameter and shape of its “wire.” Constructor: Hose ...
Properties: .End_Placement_Method .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_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. .Segments_Along_Hose integer
Integer
default: 45
--
animatable;
The total number of segments in the hose’s length. Increase this setting for a smooth profile when the hose is curved. Default=16. .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. .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.
287
288
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.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. .Round_Hose_Diameter float
Float
default: 0.2
--
animatable;
The maximum width of the hose at the ends. .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. .Rectangular_Hose_Width float
Float
default: 0.2
--
animatable;
Float
default: 0.2
--
animatable;
Float
default: 0.0
--
animatable;
The width of the hose. .Rectangular_Hose_Depth float
The height of the hose. .Rectangular_Hose_Fillet_Size float
The amount by which the cross-section corners are rounded. For this to be visible, Fillet Segs must be set to 1 or higher. Default=0. .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. .Rectangular_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. .D_Section_Hose_Width float
Float
default: 0.2
--
animatable;
Float
default: 0.2
--
animatable;
Float
default: 0.0
--
animatable;
The width of the hose. .D_Section_Hose_Depth float
The height of the hose. .D_Section_Hose_Fillet_Size float
The amount by which the two cross-section corners opposite the rounded side are rounded. For this to be visible, Fillet Segs must be set to 1 or higher. Default=0. .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
.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. .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. .Flex_Section_Enabled
Integer
default: 1
--
integer
When on, lets you set the following four parameters for the central, flexible section of the hose. When off, the hose’s diameter is uniform throughout its length. .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%. .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%. .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 isn’t high enough to support the number of cycles, then not all cycles will appear. Default=10. Tip: To set the appropriate number of segments, first set Cycles, and then increase Segments until the number of visible cycles stops changing. .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%. .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. .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.
289
290
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
HSDS_Modifier - superclass: modifier HSDS_Modifier - superclass: modifier; super-superclass:MAXWrapper - 12:0 - classID: #(341062, 28997) Constructor: HSDS_Modifier ...
Properties: .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. .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 don’t share an ID, this field is blank. .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. .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. .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
For best results, use when moving control grid vertices at a level of detail lower than the highest in which the vertex resides. .useEdgeDist Use_Edge_Distance
BooleanClass
default: false
--
boolean;
.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 they’re attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence. Turn off Affect Backfacing when you want to pull faces of a thin object, such as a thin box, but don’t want to affect faces on the other side of the object. Note: Affect Backfacing is not available when editing splines. When using Edit/Editable Mesh, you can also use the keyboard shortcut CTRL+F to toggle Affect Backfacing (while the Keyboard Shortcut Override Toggle button is turned on). .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. .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. .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. .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.
291
292
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.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: .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. .matId
Integer
default: 1
--
integer; Material_Id
Displays the material ID assigned to the current selection. Available only in Polygon and Element sub-object modes. If multiple sub-objects are selected and they don’t share an ID, this field is blank. .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. .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. .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
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. .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. .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 they’re attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence. Turn off Affect Backfacing when you want to pull faces of a thin object, such as a thin box, but don’t want to affect faces on the other side of the object. Note: Affect Backfacing is not available when editing splines. When using Edit/Editable Mesh, you can also use the keyboard shortcut CTRL+F to toggle Affect Backfacing (while the Keyboard Shortcut Override Toggle button is turned on). .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. .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. .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. .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
293
294
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble move the bottom of the curve below the surface, creating a “valley” around the base of the region. Default=0. .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: .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. .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
Constructor: Link ...
Properties: .key_mode .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: .position point3 .rotation quat .scale point3
Point3
default: [0,0,0]
--
Quat
default: (quat 0 0 0 1)
Point3
default: [1,1,1]
--
animatable; --
animatable;
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: .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:
295
296
Chapter 1
|
What’s New in 3ds max 4 MAXScript
No Key Mode: No keys are created any of the objects involved. Key Nodes: Sets keys for some of the objects. Child: Applied keys to the child object only. Parents: Applies keys to both parents and the child object. Key Entire Hierarchy: This applies keyframes to the chosen nodes and their entire hierarchies. Child: Keys the chosen object and the nodes in its hierarchy up to the world. Parents: Keys both parents and the child and all three hierarchies up to the world. .link_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: .position animatable; point3 .rotation animatable; quat .scale animatable; point3
See Also Link_Constraint interfaces: (p. 455) Link_Constraint - superclass: Matrix3Controller (p. 295)
Point3 Quat Point3
default: [0,0,0]
--
default: (quat 0 0 0 1) default: [1,1,1]
--
--
LinkedXForm - superclass: modifier
LinkedXForm - superclass: modifier LinkedXForm - superclass: modifier; super-superclass:MAXWrapper - 1:0 - classID: #(806195, 0) Constructor: LinkedXForm ...
Properties: .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: .relative boolean .lookat_vector_length animatable; float; Vector_Length .set_orientation boolean .target_axis .target_axisFlip boolean .upnode_axis .upnode_world boolean .pickUpNode node; Pick_Upnode .StoUP_axis .StoUP_axisFlip boolean .viewline_length_abs boolean; Viewline_Abs
See Also LookAt Constraint interfaces: (p. 455)
BooleanClass
default: false
--
Float
default: 100.0
--
BooleanClass
default: false
--
Integer BooleanClass
default: 2 -default: false
integer --
Integer BooleanClass
default: 0 -- integer default: true --
UndefinedClass default: undefined Integer BooleanClass
default: 0 -default: false
BooleanClass
default: true
--
integer ---
297
298
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Mesher - superclass: GeometryClass Mesher - superclass: GeometryClass; super-superclass:node - 8:0 - classID: #(998877, 32670) Constructor: Mesher ...
Properties: <Mesher>.pick
UndefinedClass
default: undefined
--
node
Click this button and then select the object to be instanced by the Mesher object. After doing so, the name of the instanced object appears on the button. <Mesher>.renderTimeOnly
BooleanClass
default: false
--
boolean
When on, the Mesher particles do not appear in the viewports, but only when you render the scene. Default=off. <Mesher>.extranodes <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 Mesher’s 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 user’s 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
Selects the Subdivision method to use:
default: 2
--
integer;
meshsmooth - superclass: modifier
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
Integer
default: 0
--
animatable;
Number of smoothing iterations to be applied to the object at render time. <meshsmooth>.useRenderSmoothness Use_Render_Smoothness
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
Float
default: 1.0
--
animatable; float;
Lets you choose a different Smoothness value to be applied to the object at render time. <meshsmooth>.faceType
Integer
default: 1
--
integer; Face_Type
Select the type to operate on during input conversion: 0-Faces 1-Polygons Operate On Faces treats every triangle as a face and smooths across all edges, even invisible edges. Operate On Polygons ignores invisible edges, treating polygons (like the quads making up a box or the cap on a cylinder) as a single face.
299
300
Chapter 1
|
What’s 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 you’d get after an infinite number of iterations. <meshsmooth>.smoothResult Smooth_Output
BooleanClass
default: true
--
boolean;
Applies the same smoothing group to all faces. <meshsmooth>.sepByMats Separate_By_Materials
BooleanClass
default: false
--
boolean;
Prevents the creation of new faces for edges between faces that do not share Material IDs. <meshsmooth>.sepBySmGroups Separate_By_Smoothing_Group
BooleanClass
default: false
--
boolean;
Prevents the creation of new faces at edges between faces that don’t 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 it’s been converted to polygons (if applicable) and before the smoothing occurs. <meshsmooth>.controlLevel
Integer
default: 0
--
integer; Control_Level
Allows you to see the control mesh after one or more iterations and to edit sub-object points and edges at that level. <meshsmooth>.useSoftSel 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
<meshsmooth>.useEdgeDist Use_Edge_Distance
BooleanClass
default: false
--
boolean;
Turn on/off use Edge Distance. <meshsmooth>.edgeDist
Integer
default: 1
--
integer; Edge_Distance
Limits the region affected by the number of edges between the selection and the affected vertices. <meshsmooth>.affectBackfacing 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 they’re attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence. <meshsmooth>.falloff
Float
default: 20.0
--
float
Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry. <meshsmooth>.pinch
Float
default: 0.0
--
float
Raises and lowers the top point of the curve along the vertical axis. Sets the relative “pointedness” of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis. <meshsmooth>.bubble
Float
default: 0.0
--
float
Expands and contracts the curve along the vertical axis. Sets the relative “fullness” of the region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble move the bottom of the curve below the surface, creating a “valley” around the base of the region. <meshsmooth>.reset
Integer
Select reset settings: 0-Reset all levels 1-Reset this level
See Also MeshSmooth : Modifier (p. 1139)
default: 1
--
integer; Update_Options
301
302
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Modifier and SpacewarpModifier Types (p. 1100)
Motion_Blur - superclass: renderEffect Motion_Blur - superclass: renderEffect; super-superclass:MAXWrapper - 2:0 - classID: #(141333203, 1612379012) Constructor: Motion_Blur ...
Properties: <Motion_Blur>.duration float
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
<MultiRes>.Vertex_Percentage animatable; float
Float
default: 100.0
--
The modified object’s vertex count as a percentage of the overall number of vertices in the original mesh. Adjusting this setting alters the Count value as well. Note: After you type in a specific percentage, such as 30, you might find that the software changes the value to a slightly lower one, such as 29.971. This is due to the relationship between the overall number of vertices in the model and the percentage calculation. It is not a bug, but simply the closest solution to your request. <MultiRes>.Vertex_Merging
BooleanClass default: false
--
boolean
When on, lets MultiRes merge vertices between discrete elements in a model. For example, if you apply MultiRes to a teapot, which comprises four separate elements, and turn on Vertex Merging, as you adjust the vertex resolution, the separate components will meld together into one contiguous lower-resolution object. To control Vertex Merging, you can set a Merge Threshold. This value determines the 3ds max unit distance within which to merge elements. <MultiRes>.Threshold
Float
default: 0.0
--
float
This spinner value sets the maximum distance in 3ds max units between vertices in order for those vertices to be considered for merging. Once this threshold is achieved, then the vertices between elements will be welded together as the mesh is reduced in complexity. Note: To eliminate only coincident vertices, set Merge Threshold to 0.0. This is similar to the Weld Vertex function. <MultiRes>.Merge_Within
BooleanClass default: false
--
boolean
When on, MultiRes merges the boundaries of adjacent elements and vertices within elements. Many objects can contain multiple groups of vertices that don’t share connectivity. A simple example of this is the Teapot object. It comprises four different elements: the body, the handle, the spout, and the lid. Normally, MultiRes optimizes each discrete element in a mesh on its own. The default behavior of the Vertex Merging option is to merge vertices between elements. Turning on Within Mesh? causes vertices within elements to be merged as well. <MultiRes>.Boundary_Metric
BooleanClass default: false
--
boolean
When on, MultiRes preserves materials assigned to the selected model. The material boundaries defined by Material IDs are retained as long as possible, and are the last to be eliminated at low vertex counts. Default=off. <MultiRes>.Maintain_Base_Vertices
BooleanClass default: false
--
boolean
When on, overrides the MultiRes optimization algorithms and preserves any vertices selected at the MultiRes Vertex sub-object level as “critical” ones. Use this feature to retain critical features of an object or character such as its fingers or claws, or other geometry that might become unrecognizable if reduced too severely. To select vertices for use with this option, use the MultiRes Vertex sub-object level. To access this level, first go to the modifier stack display and click the plus-sign icon next to the MultiRes modifier. This opens up its hierarchy, which consists of the single Vertex sub-
303
304
Chapter 1
|
What’s New in 3ds max 4 MAXScript
object level. Next, click the Vertex entry. The MultiRes vertices appear on the mesh as blue dots. You can select these using any standard interactive method, but you cannot transform them. Important: After selecting MultiRes sub-object vertices with Maintain Base Vertices turned on, re-generate the mesh before changing the vertex resolution. In the following illustration, the clown started out as a high-resolution mesh. All of the MultiRes vertices in the right half were selected, Maintain Base Vertices was turned on, and then the vertices were reduced. {mrm_clown.bmp} <MultiRes>.Multiple_Normals_Per_Vertex
BooleanClass default: true
--
boolean
When on, lets MultiRes assign multiple normals for each vertex. By default, MultiRes generates a single normal per vertex. If multiple normals are generated, they are applied as the vertex resolution is decreased and increased. When the Multiple Normals Per Vertex option is checked, the MultiRes modifier generates normal updates when the geometry surrounding a vertex changes. You must specify a crease angle in degrees (0.0 - 180.0). The crease angle is the angle between the face normals. It is used to decide when a normal should be shared across an edge between two faces. For example, in a plane defined as a mesh grid of 10 x 10 faces, any two adjacent faces have a crease angle of zero. In a cube, adjacent faces have a crease angle of 90 degrees. In general, crease angles approaching 0 yield smoother shading. Crease angles approaching 180 yield more visible corners. <MultiRes>.Crease_Angle
Float
default: 75.0
--
float
The value of the crease necessary in order to generate multiple normals. Available only when Multiple Normals Per Vertex is on. The optimal crease angle depends on the model; set it interactively and check the viewport and rendered images for shading effects. While use of multiple normals per vertex enables more accurate shading, it can require more internal data. <MultiRes>.Generate
BooleanClass default: false
--
boolean
Applies the current MultiRes settings to the modified object. When you first apply MultiRes to an object, it must initialize its mesh-optimizing algorithm; you are prompted by the modifier to “Generate when ready”. Note: When working with complex meshes, the initial analysis may take a little while. During this time, MultiRes displays a special cursor to indicate it is working. Progress is indicated on this cursor by the movement of the gray area from top to bottom. To cancel this process, press ESC.
Normalize_Spl - superclass: modifier
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: .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
305
306
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Orientation_Constraint - superclass: RotationController Orientation_Constraint - superclass: RotationController; super-superclass:MAXWrapper - 2:0 classID: #(8224, 0) Constructor: Orientation_Constraint ...
Properties: .relative boolean .local_world LocalOrWorld
BooleanClass
default: false
--
Integer
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 Mesher’s particle system will run. Default=0.
Patch_Select - superclass: modifier
<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 user’s choice. <particleMesher>.boundsMin BoundsA <particleMesher>.boundsMax point3; BoundsB
Point3
default: [1,1,1]
Point3
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
307
308
Chapter 1
|
What’s New in 3ds max 4 MAXScript
frame where you want the key set, and adjust the % Along Path spinner to move the object. <Path_Constraint>.follow
BooleanClass
default: false
--
boolean
Aligns the object to the trajectory as it follows the contour. <Path_Constraint>.path node; Path_Constraint
UndefinedClass
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
BooleanClass
default: false
--
boolean
Allows the object to bank (roll) as it negotiates the curves of the spline. <Path_Constraint>.bankAmount animatable; float; Bank_Amount
Float
default: 0.5
--
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
Integer
default: 0
--
integer
Defines which axis of the object is aligned to the trajectory of the path. <Path_Constraint>.axisFlip boolean; Axis_Flip
BooleanClass
default: false
--
BooleanClass
default: false
--
Turn on to flip the direction of the axis <Path_Constraint>.loop
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
See Also Path_Constraint interfaces: (p. 468)
PDynaflector - superclass: SpacewarpObject PDynaflector - superclass: SpacewarpObject; super-superclass:node - 21:0 - classID: #(11824263, 1055795908) Constructor: ...
Properties: .’time on’ Time_On
Integer
.’time off’ Time_Off
Integer
default: 0
--
default: 16000
.affects Float default: 10000.0 Reflects; Controller Scaling: (1 : 100.0) .bounce
Float
animatable; integer;
default: 1.0
--
--
--
animatable; integer;
animatable; percentage;
animatable; float
.bouncevar Float default: 0.0 Bounce_Variation; Controller Scaling: (1 : 100.0)
--
.chaos Float Controller Scaling: (1 : 100.0)
animatable; percentage;
.inheritVelocity Velocity_Inheritance .width .height .mass Particle_Mass
Float Float Float
default: 0.0
Float
--
default: 1.0
default: 0.0
--
default: 0.0 default: 1.0
.’mass units’ Particle_Mass_Units
Integer
.’force in x’ Force_in_X_Direction .’force in y’ Force_in_Y_Direction
animatable; percentage;
animatable; float;
animatable; float
---
--
animatable; float animatable; float;
default: 0
--
radio button number;
Float
default: 0.0
--
animatable; float;
Float
default: 0.0
--
animatable; float;
309
310
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.’force in z’ Force_in_Z_Direction
Float
default: 0.0
--
animatable; float;
.’apply at x’ Apply_at_X_location
Float
default: 0.0
--
animatable; float;
.’apply at y’ Apply_at_Y_location
Float
default: 0.0
--
animatable; float;
.’apply at z’ Apply_at_Z_location
Float
default: 0.0
--
animatable; float;
.number Number_of_Particles
Integer
.friction Float Controller Scaling: (1 : 100.0) .quality Collision_Quality .collider Collision_Quality
Integer
default: 0
--
animatable; 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: .Origin Point3 .NormalVec Point3 .UpVec Point3 .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. .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. .Size
Float
default: 1.0
--
float
The size of the manipulator’s handle, in 3ds max units. Default=1.0.
PlaneAngleManip - superclass: helper
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: .Origin Point3 .NormalVec Point3 Normal_Vector .UpVec Point3 .Angle Float Controller Scaling: (1 : 57.2958)
default: [0,0,0] default: [0,0,1]
---
point3 point3;
default: [0,1,0] default: 0.0 --
-- 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. .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. .Size
Float
default: 1.0
--
float
The size of the manipulator’s handle, in 3ds max units. Default=1.0.
311
312
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also Scripted Manipulators (p. 97) Interface: manip (p. 366) sliderManipulator interfaces: (p. 520) radiusManip interfaces: (p. 500) uvwMappingHeightManip interfaces: (p. 551) uvwMappingLengthManip interfaces: (p. 555) uvwMappingUTileManip interfaces: (p. 558) uvwMappingVTileManip interfaces: (p. 562) uvwMappingWidthManip interfaces: (p. 565) ConeAngleManip - superclass: helper (p. 277) PlaneAngleManip - superclass: helper (p. 311) Scripted Plug-ins (p. 1538) sliderManipulator - superclass: helper (p. 333)
Point3List - superclass: Point3Controller Point3List - superclass: Point3Controller; super-superclass:MAXWrapper - 1:1 - classID: #(1263210497, 0) Constructor: Point3List ...
Properties: .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
Point3Spring - superclass: Point3Controller Point3Spring - superclass: Point3Controller; super-superclass:MAXWrapper - 4:4 - classID: #(327754098, 1754751609) Constructor: Point3Spring ...
Properties: .position .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. .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. .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)
313
314
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Point_Cache - superclass: modifier Point_Cache - superclass: modifier; super-superclass:MAXWrapper - 7:0 - classID: #(567311073, 1221790700) Constructor: Point_Cache ...
Properties: .time .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. .end_time
Float
default: 100.0
--
float
Sets the last frame for recording the vertex animation. .samples .cache_file
Integer UndefinedClass
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. .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. .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
Point_CacheSpacewarpModifier - superclass: SpacewarpModifier Point_CacheSpacewarpModifier - superclass: SpacewarpModifier; super-superclass:MAXWrapper 7:0 - classID: #(567311073, 1221790701) Constructor: Point_CacheSpacewarpModifier ...
Properties: .time float .start_time float
Float
default: 0.0
--
Float
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. .end_time float
Float
default: 100.0
--
Sets the last frame for recording the vertex animation. .samples integer .cache_file undefined -- string
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. .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. .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.
315
316
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also Point Cache Modifier (p. 26) Point_Cache interfaces: (p. 484) Point_Cache - superclass: modifier (p. 314) Point_CacheSpacewarpModifier interfaces: (p. 485)
PointCache - superclass: modifier PointCache - superclass: modifier; super-superclass:MAXWrapper - 7:0 - classID: #(567311073, 1221790700) Constructor: PointCache ...
Properties: .time .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. .end_time
Float
default: 100.0
--
float
Sets the last frame for recording the vertex animation. .samples .cache_file
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. .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
.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: .time .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. .end_time
Float
default: 100.0
--
float
Sets the last frame for recording the vertex animation. .samples .cache_file
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.
317
318
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.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. .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: .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. .centermarker BooleanClass animatable; boolean; Center_Marker
default: false
--
Displays a small X marker at the center of the point object. .axistripod animatable; boolean; Axis_Tripod
BooleanClass
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
.cross animatable; boolean
BooleanClass
default: true
--
BooleanClass
default: false
--
default: false
--
Displays an axis-aligned cross. .box animatable; boolean
Displays a small box at the center of the point object. .constantscreensize BooleanClass animatable; boolean; Constant_Screen_Size
Keeps the size of the point object constant, regardless of how much you zoom in or out. .drawontop animatable; boolean; Draw_On_Top
BooleanClass
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: .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). .softselUseEdgeDistance boolean; Use_Edge_Distance .softselEdgeDist animatable; integer; Edge_Distance
BooleanClass
default: false
Integer
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.
319
320
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.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 they’re attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence. Turn off Affect Backfacing when you want to pull faces of a thin object, such as a thin box, but don’t want to affect faces on the other side of the object. You can also use the keyboard shortcut CTRL+F to toggle Affect Backfacing (while the PlugIn Keyboard Shortcut Toggle button is turned on). .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. .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. .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: .relative
BooleanClass
default: false
--
boolean
PositionList - superclass: PositionController
See Also Position_Constraint interfaces: (p. 488)
PositionList - superclass: PositionController PositionList - superclass: PositionController; super-superclass:MAXWrapper - 1:1 - classID: #(1263210498, 0) Constructor: PositionList ...
Properties: .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: .effectHow number; Abs_Rel .forceNode Force_Nodes; SubAnim .steps .x_effect float
Integer
default: 1
--
ArrayParameter
default: #()
Integer Float
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.
321
322
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.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. .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 .start .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: .‘time on’ Integer default: 0 -- animatable; integer; Time_On .‘time off’ Integer default: 16000 -animatable; integer; Time_Off .affects Float default: 10000.0 -animatable; percentage; Reflects; Controller Scaling: (1 : 100.0) .bounce Float default: 1.0 -- animatable; float .bouncevar Float default: 0.0 -- animatable; percentage; Bounce_Variation; Controller Scaling: (1 : 100.0) .chaos Float default: 0.0 -- animatable; percentage; Controller Scaling: (1 : 100.0)
Reflection - superclass: MAXObject
.inheritVelocity Float default: 1.0 -- animatable; float; Velocity_Inheritance .refracts Float default: 100.0 -animatable; percentage; Controller Scaling: (1 : 100.0) .deceleration Float default: 1.0 -- animatable; float .‘decel var’ Float default: 0.0 -- animatable; percentage; Deceleration_Variation; Controller Scaling: (1 : 100.0) .refraction Float default: 50.0 -animatable; percentage; Distortion; Controller Scaling: (1 : 100.0) .‘refraction var’ Float default: 0.0 -- animatable; percentage; Distortion_Variation; Controller Scaling: (1 : 100.0) .diffusion Float default: 0.0 -- animatable; percentage; Controller Scaling: (1 : 100.0) .‘diffusion var’ Float default: 0.0 -- animatable; percentage; Diffusion_Variation; Controller Scaling: (1 : 100.0) .width Float default: 0.0 -- animatable; float .height Float default: 0.0 -- animatable; float .spawn Float default: 100.0 -animatable; percentage; Spawn_Percentage; Controller Scaling: (1 : 100.0) .‘pass velocity’ Float default: 1.0 -- animatable; float; Pass_Velocity .‘passvel var’ Float default: 0.0 -- animatable; percentage; Pass_Velocity_Variation; Controller Scaling: (1 : 100.0) .friction Float default: 0.0 -- animatable; percentage; Controller Scaling: (1 : 100.0) .quality Integer default: 20 -- animatable; integer; Collision_Quality .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: .enabled
BooleanClass
default: true
--
boolean
default: true
--
boolean;
Shows whether the element is enabled. .filterOn FilteringOn
BooleanClass
Shows whether the active antialiasing filter is enabled for the element.
323
324
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.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. .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: .enabled boolean
Shows whether the element is enabled.
BooleanClass
default: true
--
reflectionRenderElement - superclass: MAXObject
.filterOn boolean; FilteringOn
BooleanClass
default: true
325
--
Shows whether the active antialiasing filter is enabled for the element. .elementName “Reflection” -- 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. .bitmap - bitmap
UndefinedClass
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)
default: undefined
-
326
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Refraction - superclass: MAXObject Refraction - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(7, 0) Constructor: Refraction ...
Properties: .enabled
BooleanClass
default: true
--
boolean
default: true
--
boolean;
Shows whether the element is enabled. .filterOn FilteringOn
BooleanClass
Shows whether the active antialiasing filter is enabled for the element. .elementName
String
default: “Refraction”
--
string
Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected. .bitmap
UndefinedClass
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)
default: undefined
--
bitmap
refractionRenderElement - superclass: MAXObject
327
refractionRenderElement - superclass: MAXObject refractionRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(7, 0) Constructor: refractionRenderElement ...
Properties: .enabled boolean
BooleanClass
default: true
--
BooleanClass
default: true
--
Shows whether the element is enabled. .filterOn boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element. .elementName “Refraction” -- 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. .bitmap - bitmap
UndefinedClass
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)
default: undefined
-
328
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)
RingWave - superclass: GeometryClass RingWave - superclass: GeometryClass; super-superclass:node - 26:0 - classID: #(686038884, 306926354)
RotationList - superclass: RotationController RotationList - superclass: RotationController; super-superclass:MAXWrapper - 1:1 - classID: #(1263210499, 0) Constructor: RotationList ...
Properties: .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
See Also ScaleList interfaces: (p. 517)
Point3
default: [0,0,0]
--
animatable; point3
ScaleReactor - superclass: ScaleController
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
Integer
<SDynaflector>.‘time off’ Time_Off
Integer
default: 0
--
default: 16000
<SDynaflector>.affects Float default: 10000.0 Reflects; Controller Scaling: (1 : 100.0) <SDynaflector>.bounce
Float
animatable; integer;
default: 1.0
--
--
--
animatable; integer;
animatable; percentage;
animatable; float
<SDynaflector>.bouncevar Float default: 0.0 Bounce_Variation; Controller Scaling: (1 : 100.0)
--
<SDynaflector>.chaos Float Controller Scaling: (1 : 100.0)
animatable; percentage;
default: 0.0
<SDynaflector>.inheritVelocity Velocity_Inheritance
Float
<SDynaflector>.radius
default: 0.0
<SDynaflector>.mass Particle_Mass
Float Float
default: 1.0
default: 1.0
<SDynaflector>.‘mass units’ Particle_Mass_Units
Integer
<SDynaflector>.‘force in x’ Force_in_X_Direction
Float
--
animatable; percentage;
---
--
animatable; float;
animatable; float animatable; float;
default: 0
--
radio button number;
default: 0.0
--
animatable; float;
329
330
Chapter 1
|
What’s New in 3ds max 4 MAXScript
<SDynaflector>.‘force in y’ Force_in_Y_Direction
Float
default: 0.0
--
animatable; float;
<SDynaflector>.‘force in z’ Force_in_Z_Direction
Float
default: 0.0
--
animatable; float;
<SDynaflector>.‘apply at x’ Apply_at_X_location
Float
default: 0.0
--
animatable; float;
<SDynaflector>.‘apply at y’ Apply_at_Y_location
Float
default: 0.0
--
animatable; float;
<SDynaflector>.‘apply at z’ Apply_at_Z_location
Float
default: 0.0
--
animatable; float;
<SDynaflector>.number Number_of_Particles
Integer
<SDynaflector>.friction Float Controller Scaling: (1 : 100.0) <SDynaflector>.collider Friction
default: 0
default: 0.0
UndefinedClass
--
animatable; integer;
--
animatable; percentage;
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 won’t “take” if <shape>.useViewportSettings or <shape>.displayRenderMesh is false. This matches the behavior in the UI where the “Viewport” option is disabled in this case.
Self_Illumination - superclass: MAXObject
Self_Illumination - superclass: MAXObject Self_Illumination - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(5, 0) Constructor: Self_Illumination ...
Properties: <Self_Illumination>.enabled
BooleanClass
default: true
--
boolean
default: true
--
boolean;
Shows whether the element is enabled. <Self_Illumination>.filterOn FilteringOn
BooleanClass
Shows whether the active antialiasing filter is enabled for the element. <Self_Illumination>.elementName Illumination” -- string
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)
--
331
332
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)
ShadowRenderElement - superclass: MAXObject ShadowRenderElement - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(8, 0) Constructor: ShadowRenderElement ...
Properties: <ShadowRenderElement>.enabled boolean
BooleanClass
default: true
--
BooleanClass
default: true
--
Shows whether the element is enabled. <ShadowRenderElement>.filterOn boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element. <ShadowRenderElement>.elementName string
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
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)
default: undefined
--
sliderManipulator - superclass: helper
refractionRenderElement - superclass: MAXObject (p. 327) Self_Illumination - superclass: MAXObject (p. 331) Specular - superclass: MAXObject (p. 334) specularRenderElement - superclass: MAXObject (p. 335)
sliderManipulator - superclass: helper sliderManipulator - superclass: helper; super-superclass:node - 10:0 - classID: #(1205540079, 1318803856) Constructor: sliderManipulator ...
Properties: <sliderManipulator>.value
Float
default: 0.0
--
animatable; float
The value of the slider, based on the position of the slidable triangle. Default=0.0. <sliderManipulator>.minVal
Float
default: 0.0
--
animatable; float
The minimum possible value of the slider. Default=0.0. <sliderManipulator>.maxVal
Float
default: 100.0
--
animatable; float
The maximum possible value of the slider. Default=100.0. When the minimum is 0.0 and the maximum is 100.0, the slider Value can represent a percentage. <sliderManipulator>.xPos
Float
default: 0.0
--
float
The slider’s X location in the active viewport. Default=Viewport X location you clicked when you created the slider. <sliderManipulator>.yPos
Float
default: 0.0
--
float
The slider’s Y location in the active viewport. Default=Viewport Y location you clicked when you created the slider. <sliderManipulator>.width
Float
default: 100.0
--
float
--
boolean
The slider’s width, in 3ds max units. Default=100.0. <sliderManipulator>.hide
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
The slider label that appears in viewports. Default=none. <sliderManipulator>.snapToggle BooleanClass default: true
--
boolean
When on, the slider “snaps” to incremental values. When off, Default=on. <sliderManipulator>.snapVal
Float
default: 0.01
--
The increment used by the slider when Snap is on. Default=0.01.
float
333
334
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also Scripted Manipulators (p. 97) Interface: manip (p. 366) radiusManip interfaces: (p. 500) ConeAngleManip - superclass: helper (p. 277) PlaneAngleManip - superclass: helper (p. 311) Scripted Plug-ins (p. 1538) sliderManipulator - superclass: helper (p. 333) sliderManipulator interfaces: (p. 520) uvwMappingHeightManip interfaces: (p. 551) uvwMappingLengthManip interfaces: (p. 555) uvwMappingUTileManip interfaces: (p. 558) uvwMappingVTileManip interfaces: (p. 562) uvwMappingWidthManip interfaces: (p. 565)
Specular - superclass: MAXObject Specular - superclass: MAXObject; super-superclass:Value - 4:0 - classID: #(2, 0) Constructor: Specular ...
Properties: <Specular>.enabled
BooleanClass
default: true
--
boolean
default: true
--
boolean;
Shows whether the element is enabled. <Specular>.filterOn FilteringOn
BooleanClass
Shows whether the active antialiasing filter is enabled for the element. <Specular>.elementName
String
default: “Specular”
--
string
Shows the name of the currently selected element. You can type in a custom name for the element. This control is unavailable when multiple elements are selected. <Specular>.bitmap
UndefinedClass
See Also Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265)
default: undefined
--
bitmap
specularRenderElement - superclass: MAXObject
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
--
BooleanClass
default: true
--
Shows whether the element is enabled. <specularRenderElement>.filterOn boolean; FilteringOn
Shows whether the active antialiasing filter is enabled for the element. <specularRenderElement>.elementName string
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
--
335
336
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also Alpha - superclass: MAXObject (p. 262) alphaRenderElement - superclass: MAXObject (p. 263) Atmosphere - superclass: MAXObject (p. 264) atmosphereRenderElement - superclass: MAXObject (p. 265) BackgroundRenderElement - superclass: MAXObject (p. 269) bgndRenderElement - superclass: MAXObject (p. 270) clrShadowRenderElement - superclass: MAXObject (p. 272) Colored_Shadow - superclass: MAXObject (p. 273) Diffuse - superclass: MAXObject (p. 279) diffuseRenderElement - superclass: MAXObject (p. 280) emissionRenderElement - superclass: MAXObject (p. 285) Reflection - superclass: MAXObject (p. 323) reflectionRenderElement - superclass: MAXObject (p. 324) Refraction - superclass: MAXObject (p. 326) refractionRenderElement - superclass: MAXObject (p. 327) Self_Illumination - superclass: MAXObject (p. 331) ShadowRenderElement - superclass: MAXObject (p. 332) Specular - superclass: MAXObject (p. 334) specularRenderElement_superclass_MAXObject
SpringPoint3Controller - superclass: Point3Controller SpringPoint3Controller - superclass: Point3Controller; super-superclass:MAXWrapper - 4:4 - classID: #(327754098, 1754751609) Constructor: SpringPoint3Controller ...
Properties: <SpringPoint3Controller>.position point3 <SpringPoint3Controller>.x_effect
Point3
default: [0,0,0]
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. <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
<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
default: 1
--
ArrayParameter
default: #()
Integer Float
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
337
338
Chapter 1
|
What’s New in 3ds max 4 MAXScript
<SpringPositionController>.start Start_Frame <SpringPositionController>.position animatable; point3
Integer
default: 0
--
Point3
default: [0,0,0]
integer; --
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
Integer
<SSpawnflector>.‘time off’ integer; Time_Off
Integer
default: 0
--
default: 16000
animatable; integer;
--
animatable;
<SSpawnflector>.affects Float default: 10000.0 Reflects; Controller Scaling: (1 : 100.0)
--
<SSpawnflector>.bounce
animatable; float
Float
default: 1.0
--
animatable; percentage;
<SSpawnflector>.bouncevar Float default: 0.0 Bounce_Variation; Controller Scaling: (1 : 100.0)
--
<SSpawnflector>.chaos Float Controller Scaling: (1 : 100.0)
animatable; percentage;
<SSpawnflector>.inheritVelocity Velocity_Inheritance
default: 0.0
Float
--
default: 1.0
animatable; percentage;
--
animatable; float;
transform_script - superclass: Matrix3Controller
<SSpawnflector>.refracts Float Controller Scaling: (1 : 100.0) <SSpawnflector>.deceleration
default: 100.0
Float
--
default: 1.0
animatable; percentage;
--
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
<SSpawnflector>.spawn Float default: 100.0 Spawn_Percentage; Controller Scaling: (1 : 100.0) <SSpawnflector>.‘pass velocity’ Pass_Velocity
Float
--
animatable; float
--
animatable; percentage;
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
UndefinedClass
--
animatable; percentage;
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.
339
340
Chapter 1
|
What’s New in 3ds max 4 MAXScript
The software interprets the text you type into the Script text box as the body of a MAXScript block expression. You can type as many expressions as you want on as many lines as you want, and they are evaluated in turn. The value of the last expression is taken as the controller value. This must yield a matrix3 value for Transform Script controllers. Since the text is inside a block expression, you can declare local variables which are visible only within the script and are temporary for one evaluation. You can also declare or access global variables that are shared with all other scripts in MAXScript and hold their values from one evaluation to the next. A controller is always evaluated by the software with respect to a specific animation time. This might be the current time slider or incrementing frame time if an animation is playing, or a rendering is under way. In the case of Script controllers, the time being evaluated is used to establish an automatic “at time” context around the controller script, so any properties you access (outside of other explicit “at time” expressions) yield the correct values for the current controller evaluation time. This means you don’t have to do anything special in your scripts to work at the correct time. You can access the evaluation time, with the standard MAXScript variable, current Time. You can also reference scene property values at other times by using “at time” expressions in your scripts, as in regular MAXScript programming. Constructor: transform_script ...
Properties: .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: .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
.selectionConversion Selection_Conversion .useSoftSelection Use_Soft_Selection
Integer
default: 0
BooleanClass
--
integer;
default: true
--
boolean;
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. .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)
341
342
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Turn_to_Patch - superclass: modifier Turn_to_Patch - superclass: modifier; super-superclass:MAXWrapper - 4:0 - classID: #(1011577041, 590161861) Constructor: Turn_to_Patch ...
Properties: .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. .selectionConversion Selection_Conversion .useSoftSelection Use_Soft_Selection
Integer
default: 0
--
integer;
Integer
default: 1
--
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. .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
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: .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 doesn’t go outside the polygon. A polygon is not convex if you can draw a line between vertices and that line lays outside of the polygon. Problems that can occur with non-convex polygons include the fact that changes in the geometry of the input object can result in a different topology for the Turn To Poly result. For instance, in a box, if you drag one of the top corners across the middle of the top face, the box becomes non-convex. Turn To Poly would then see this as two triangles instead of one quad, and the number of points in the result would change. .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. .maxPolySize integer; Max_Polygon_Size
Integer
default: 4
--
animatable;
The maximum number of sides to a polygon. .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. .planarThresh Float default: 15.0 -animatable; angle; Planar_Threshold; Controller Scaling: (1 : 57.2958)
Controls the threshold of the angle between polygonal planes. .removeMidEdgeVertices Remove_Mid_Edge_Vertices
BooleanClass
default: true
--
boolean;
343
344
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.selectionConversion Selection_Conversion .useSoftSelection Use_Soft_Selection
Integer
default: 0
BooleanClass
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 .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
UDynaDeflector - superclass: SpacewarpObject UDynaDeflector - superclass: SpacewarpObject; super-superclass:node - 19:0 - classID: #(1750561194, 1736524989) Constructor: ...
Properties: .’time on’ Time_On
Integer
.’time off’ integer; Time_Off
default: 0
Integer
--
default: 1600000
.affects Float default: 10000.0 Reflects; Controller Scaling: (1 : 100.0) .bounce
Float
animatable; integer;
default: 1.0
--
--
--
animatable;
animatable; percentage;
animatable; float
.bouncevar Float default: 0.0 Bounce_Variation; Controller Scaling: (1 : 100.0)
--
.chaos Float Controller Scaling: (1 : 100.0)
animatable; percentage;
default: 0.0
.friction Float Controller Scaling: (1 : 100.0)
default: 0.0
.inheritVelocity Velocity_Inheritance
Float
.radius
default: 0.0
.mass Particle_Mass
Float Float
--
Integer
.’force in x’ Force_in_X_Direction
animatable; percentage;
default: 1.0
default: 1.0
.’mass units’ Particle_Mass_Units
--
animatable; percentage;
---
--
animatable; float;
animatable; float; Icon_Size animatable; float;
default: 0
--
radio button number;
Float
default: 0.0
--
animatable; float;
.’force in y’ Force_in_Y_Direction
Float
default: 0.0
--
animatable; float;
.’force in z’ Force_in_Z_Direction
Float
default: 0.0
--
animatable; float;
345
346
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.’apply at x’ Apply_at_X_location
Float
default: 0.0
--
animatable; float;
.’apply at y’ Apply_at_Y_location
Float
default: 0.0
--
animatable; float;
.’apply at z’ Apply_at_Z_location
Float
default: 0.0
--
animatable; float;
.number Number_of_Particles .collider Friction
Integer
default: 20
UndefinedClass
--
animatable; integer;
default: undefined
--
max object;
USpawnDeflector - superclass: SpacewarpObject USpawnDeflector - superclass: SpacewarpObject; super-superclass:node - 20:0 - classID: #(436029718, 1434415577) Constructor: ...
Properties: .‘time on’ Time_On
Integer
.‘time off’ integer; Time_Off
default: 0
Integer
--
default: 16000
.affects Float default: 10000.0 percentage; Reflects; Controller Scaling: (1 : 100.0) .bounce
Float
animatable; integer;
default: 1.0
--
--
--
animatable;
animatable;
animatable; float
.bouncevar Float default: 0.0 -- animatable; percentage; Bounce_Variation; Controller Scaling: (1 : 100.0) .chaos Float Controller Scaling: (1 : 100.0) .friction Float Controller Scaling: (1 : 100.0) .inheritVelocity float; Velocity_Inheritance
default: 0.0
--
default: 0.0
Float
animatable; percentage;
--
animatable; percentage;
default: 1.0
.refracts Float default: 100.0 percentage; Controller Scaling: (1 : 100.0)
--
--
animatable;
animatable;
UVWUnwrap - superclass: modifier
.deceleration
Float
default: 1.0
--
animatable; float
.’decel var’ Float default: 0.0 -- animatable; percentage; Deceleration_Variation; Controller Scaling: (1 : 100.0) .refraction Float default: 50.0 percentage; Distortion; Controller Scaling: (1 : 100.0)
--
animatable;
.‘refraction var’ Float default: 0.0 -percentage; Distortion_Variation; Controller Scaling: (1 : 100.0) .diffusion Float default: 0.0 percentage; Controller Scaling: (1 : 100.0)
--
animatable;
.‘diffusion var’ Float default: 0.0 -percentage; Diffusion_Variation; Controller Scaling: (1 : 100.0) .radius Icon_Size
Float
default: 0.0
.spawn Float default: 100.0 Spawn_Percentage; Controller Scaling: (1 : 100.0) .‘pass velocity’ float; Pass_Velocity
Float
--
--
animatable;
animatable;
animatable; float;
animatable; percentage;
default: 1.0
--
animatable;
.‘passvel var’ Float default: 0.0 -- animatable; percentage; Pass_Velocity_Variation; Controller Scaling: (1 : 100.0) .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.
347
348
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Constructor: Vortex ...
Properties: .‘time on’
Integer
default: 0
--
integer; Time_On
The frame numbers at which the space warp becomes active and becomes inactive. .‘time off’ integer; Time_Off
Integer
default: 16000
--
animatable;
The frame numbers at which the space warp becomes active and becomes inactive. .axialstrength Axial_Drop_Strength
Float
default: 0.1
--
animatable; float;
Specifies how quickly particles move in the direction of the drop axis. .axialrange float; Axial_Range
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. .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. .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. .rotationstrength Orbital_Speed_Strength
Float
default: 0.5
--
animatable; float;
Specifies how quickly the particles rotate. .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. .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
.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. .radialstrength Radial_Pull_Strength
Float
default: 0.5
--
animatable; float;
Specifies the distance from the drop axis at which the particles rotate. .radialrange float; Radial_Range
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. .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. .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. .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. .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. .direction
Integer
default: 0
--
radio button number
Determines whether particles rotate clockwise or counterclockwise. .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. .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
349
350
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Z_Depth - superclass: MAXObject Z_Depth - superclass: MAXObject; super-superclass:Value - 6:0 - classID: #(12, 0) Constructor: Z_Depth ...
Properties: .enabled
BooleanClass
default: true
--
boolean
default: true
--
boolean; FilteringOn
Shows whether the element is enabled. .filterOn
BooleanClass
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. .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. .bitmap .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). .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
ZRenderElement - superclass: MAXObject ZRenderElement - superclass: MAXObject; super-superclass:Value - 6:0 - classID: #(12, 0) Constructor: ZRenderElement ...
Properties: .enabled
BooleanClass
default: true
--
boolean
default: true
--
boolean;
Shows whether the element is enabled. .filterOn FilteringOn
BooleanClass
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. .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. .bitmap .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). .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.
351
352
Chapter 1
|
What’s New in 3ds max 4 MAXScript
version 4 MAXScript Interfaces Core Interfaces Topic: version 4 MAXScript New Features/Interfaces Interfaces (p. 67) actionMan (p. 353) BoneSys (p. 354) browserMgr (p. 355) cmdPanel (p. 356) colorMan (p. 356) dragAndDrop (p. 362) HDIKSys (p. 365) IKSys (p. 365) manip (p. 366) maxOps (p. 368) medit (p. 371) menuMan (p. 372) msZip (p. 378) netrender (p. 379) NullInterface (p. 409) objXRefs (p. 409) paramWire (p. 410) pluginManager (p. 414) quadMenuSettings (p. 414) rollup (p. 427) SceneExposureControl (p. 427) SceneRadiosity (p. 428) timeSlider (p. 428) trackviews (p. 429)
See Also Other Interfaces (p. 71) Class and Object Inspector Functions (p. 799) Class and Object Inspector Functions Enhanced (p. 159)
Interface: actionMan
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: executeAction tableId <string>persistentId
Parameters: tableId <string>persistentId
Return Value: True if successful and false otherwise. Prototype: loadKeyboardFile <string>file
Parameters: <string>file
Return Value: True if successful and false otherwise. Prototype: 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)
353
354
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Turning On the Listener Log (p. xli) Listener Commands (p. xxxviii)
Interface: BoneSys Bone Creation (p. 25) Interface: BoneSys Methods: Prototype: <node>createBone <point3>startPos <point3>endPos <point3>zAxis
Parameters: <point3>startPos
The location of the new bone as point3 <point3>endPos
The direction (X axis) of the bone and the bone length as point3 <point3>zAxis
The direction of the Z axis for the new bone node as point3 Return Value: It returns the new bone node that was created. Note: If the Z axis is not perpendicular to the X axis, the Z axis will be made perpendicular. To create a bone chain, call createBone repeatedly with the startPosition set to the value of the previous endPosition. Note that newly created bones are not linked to any parent. So to create a bone chain, the script would also need to link each newly created bone segment to the previous.
See Also Bones : System (p. 991) Core Interfaces (p. 70) Node Common Properties, Operators, and Methods (p. 820) Bone Creation (p. 25) Bone : Helper (p. 978) Skin : Modifier (p. 1157) Access to the new node bone properties and methods (p. 23) Bones_SystemBones_System
Interface: browserMgr
Interface: browserMgr This represents the interface to the Browser Manager. Methods: Prototype: newBrowser <string>rootURL showDirectory showContent showToolbar showMenu
Remarks: This method will create and open a new browser window.
Parameters: <string>rootURL
The string containing the URL. showDirectory
TRUE to show as a directory, otherwise FALSE. showContent
TRUE to show the content window, otherwise FALSE. showToolbar
TRUE to show the browser toolbar, otherwise FALSE. showMenu
TRUE to show the browser menu, otherwise FALSE. Return Value: An interface to a new browsermgr. Prototype: numBrowsers()
Return Value: This method will return the current number of browsers. Prototype: getBrowser index
Remarks: This method allows you to obtain a pointer to a specific browser. Parameters: index
Return Value: An interface to the ith browser.
355
356
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also Asset Browser enhancements (p. 22) iDrop - drag and drop (p. 62) Zip-file Script Packages (p. 122)
Interface: cmdPanel Customize The Order of Rollup Pages (p. 185) Methods: Prototype: 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: SetRollupThreshold threshold
Remarks: Parameters: 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: useStandardWindowsColors()
Interface: colorMan
Return Value: Returns true if the standard windows colors are used and false if custom colors are used. Prototype: setUseStandardWindowsColors 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: onOff
Pass true to use the standard windows color and false to use the custom colors. Prototype: 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: 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.
357
358
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Return Value: TRUE if the load was successful, otherwise FALSE. Prototype: 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: 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
#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.
359
360
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: <string>getCategory <string>color
Parameters: <string>color
The ID of the color. Return Value: Returns the category string of the color whose ID is passed. Prototype: 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: setIconColorScale <enum>type <enum>which 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
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. value
The value runs from 0.0 to 100.0. Prototype: 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: setIconColorInvert <enum>type 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.
361
362
Chapter 1
|
What’s New in 3ds max 4 MAXScript
#enabledIcon
The enabled icons. 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: repaintUI <enum>type
type enums: {#repaintAll|#repaintTrackBar|#repaintTimeBar} Remarks: This method allows you to issue a repaint of the user interface. Parameters: RepaintType type
The type of repaint you wish to issue; #repaintAll, #repaintTrackBar, #repaintTimeBar.
See Also In The MAXSDK Help File: Class IColorManager
Interface: dragAndDrop iDrop - drag and drop (p. 62) The Drag and Drop system is managed through a Core Function Published interface. It provides control over the DnD system, manages handler registration and exposes some useful utility methods for downloading URL’s, simulating drops, etc.
Interface: dragAndDrop
Prototype: globalEnableDragAndDrop onOff
Remarks: This method allows you to globally enable or disable the DnD interface. Parameters: onOff
TRUE to enable, FALSE to disable. Prototype: isEnabled()
Return Value: This method returns TRUE if the global DnD interface is enabled, otherwise FALSE. Prototype: enableDragAndDrop window 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: window A handle to the window you wish to enable or disable DnD for. onOff TRUE to enable, FALSE to disable.
Return Value: True if successful and false otherwise. Prototype: dropPackage window mousePoint 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: window
A handle to the window. If this is set to NULL, the default MAX window is used. mousePoint
The point at which to drop.
363
364
Chapter 1
|
What’s New in 3ds max 4 MAXScript
files
A reference to the local copies of the URL strings. Return Value: TRUE if the drop was successful, otherwise FALSE. Prototype: downloadPackage 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: 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: DownloadUrlToDisk <string>url <string>fileName 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. flags
Return Value: True if successful and false otherwise. Prototype: <node>ImportContextNode()
Return Value: Returns a pointer to the import context node.
Interface: HDIKSys
See Also Zip-file Script Packages (p. 122) iDrop - drag and drop (p. 62)
Interface: HDIKSys Interface: HDIKSys Methods: Prototype: ikChain <node>startJoint <node>endJoint createEndEffector
Parameters: <node>startJoint <node>endJoint createEndEffector
Prototype: 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
365
366
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Interface: manip Scripted Manipulators (p. 97) Properties: .msXYPlane : Interface : Read .msXZPlane : Interface : Read .msYZPlane : Interface : Read
Prototype: <mesh>makeSphere <point3 by value>pos radius segments
Parameters: <point3 by value>pos radius
Specifies the radius of the sphere. 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 radius radius2 segs sides
Parameters: <point3 by value>pos 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. radius2
Sets the radius of the cross-sectional circle. The default is 10 units. This value is replaced each time you create a torus. segs
Sets the number of radial divisions around the torus. By reducing this number, you can create polygonal rings instead of circular ones. 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 l w h lsegs wsegs hsegs
Interface: manip
Parameters: <point3 by value>pos 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. 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. 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. lsegs
Sets the number of divisions along each axis of the object. Can be set before or after creation. By default, each side of the box is a single segment. When you reset these values, the new values become the default during a session. Default=1,1,1. Tip: Increase the Segments settings to give objects extra resolution for being affected by modifiers. For example, if you’re going to bend a box on the Z axis, you might want to set its Height Segments parameter to 4 or more. wsegs
Sets the number of divisions along each axis of the object. Can be set before or after creation. By default, each side of the box is a single segment. When you reset these values, the new values become the default during a session. Default=1,1,1. Tip: Increase the Segments settings to give objects extra resolution for being affected by modifiers. For example, if you’re going to bend a box on the Z axis, you might want to set its Height Segments parameter to 4 or more. hsegs
Sets the number of divisions along each axis of the object. Can be set before or after creation. By default, each side of the box is a single segment. When you reset these values, the new values become the default during a session. Default=1,1,1. Tip: Increase the Segments settings to give objects extra resolution for being affected by modifiers. For example, if you’re going to bend a box on the Z axis, you might want to set its Height Segments parameter to 4 or more. Return Value: Creates a box mesh with the given parameters. Prototype: 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
367
368
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: 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: makeGizmoShape()
Prototype: makeCircle <point3 by value>center radius segments
Parameters: <point3 by value>center radius 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: canImportBitmap <string>fileName
Parameters: <string>fileName
Return Value: True if successful and false otherwise. Prototype: displayActiveCameraViewWithMultiPassEffect()
Remarks: displayActiveCameraViewWithMultiPassEffect - no automatic redraw after invoked
Interface: maxOps
Prototype: setActiveViewportTransparencyDisplay transparencyLevel
Parameters: transparencyLevel
Prototype: loadCUIFile <string>fileName
Parameters: <string>fileName
Return Value: True if successful and false otherwise. Prototype: isFeatureLicensed featureNumber
Parameters: featureNumber
Return Value: True if successful and false otherwise. Prototype: GetCurRenderElementMgr()
Return Value: gets the current render element manager. Prototype: GetRenderElementMgr <enum>
Parameters: {#Production|#Draft}
Return Value: Gets a specific render element manager. Prototype: CollapseNode <node>node noWarning
Remarks: Parameters: <node>node noWarning
Prototype: CollapseNodeTo <node>node modIndex noWarning
Parameters: <node>node modIndex noWarning
369
370
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Return Value: True if successful and false otherwise. Prototype: CloneNodes nodes offset expandHierarchy: cloneType:<enum> actualNodeList:<node array> newNodes:<node array>
Parameters: nodes offset expandHierarchy: 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: setSelectionType auto <enum>method
Parameters: auto method enums: {#window|#crossing|#leftToRight|#rightToLeft}
Return Value: True if successful and false otherwise. Prototype: <maxObject>getNodeByHandle handle
Parameters: handle
Return Value: Return a node associated with a given handle. Prototype: getTrackBar()
Return Value: The interface to a trackbar is returned.
Interface: medit
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: SetActiveMtlSlot slot forceUpdate
Parameters: slot
The material slot index. forceUpdate
Set this to TRUE to update the slot contents. Remarks: This method allows you to set the active material slot. Prototype: GetActiveMtlSlot()
Return Value: This method returns the index of the active material slot. Prototype: PutMtlToMtlEditor <maxObject>mtl slot
Parameters: <maxObject>mtl
The material you want to put. 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 slot
Parameters: 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: OkMtlForScene <material>mtl
371
372
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Parameters: <material>mtl
The pointer to the material. Return Value: Before assigning material to scene, call this to avoid duplicate names. Prototype: 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: 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: 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
Prototype: <string>getMenuFile()
Return Value: This method returns the file name of the currently loaded and active menu file. Prototype: updateMenuBar()
Remarks: This method can be called to update MAX’ main menu bar after adding sub-menu’s or menu items. Prototype: registerMenuContext contextId
Remarks: To add items to MAX’s main menu, the plug-in should check the return value of RegisterMenuContext(), and if it is true, that means that this is the first time it has been registered, and the plug-in can then create new menus, add items to MAX’s main menu and Quad menus. Prototype: findMenu <string>menuName
Remarks: This method will return a pointer to a menu based on its name. Parameters: <string>menuName
The name of the menu to return. Return Value: A pointer to the menu or NULL if the menu wasn’t found. Prototype: findQuadMenu <string>menuName
Remarks: This method will return a pointer to a quad menu based on its name. Parameters: <string>menuName
The name of the menu to return. Return Value: A pointer to the quad menu or NULL if the menu wasn’t found. Prototype: unRegisterMenu menu
Remarks: This method allows you to remove a menu form the mananger.
373
374
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Parameters: menu
Points to the menu to unregister. Return Value: FALSE if the menu was not registered, TRUE if successfully unregistered. Prototype: unRegisterQuadMenu quadMenu
Parameters: quadMenu
Remarks: This is like “unregisterMenu” but for quad menus. Prototype: createMenu <string>name
Parameters: <string>name
Return Value: This creates a new, empty menu with the given name. Prototype: 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: createSubMenuItem <string>name subMenu
Parameters: <string>name 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: createSeparatorItem()
Interface: menuMan
Return Value: This creates a new menu separator that can be added to a menu. Prototype: 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: setViewportRightClickMenu <enum>which 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. menu
A pointer to the quad menu you wish to set. Return Value: TRUE if it was set successfully. Prototype: 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: getMainMenuBar()
375
376
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Return Value: This method returns a pointer to the main menu bar. Prototype: setMainMenuBar menu
Remarks: This method allows you to set the main menu bar. Parameters: menu
A pointer to the menu you wish to set as the main menu bar. Return Value: TRUE if it was set successfully. Prototype: getShowAllQuads quadMenu
Remarks: This method checks if the “Show All Quads” flag is set for a specific QuadMenu. Parameters: 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: setShowAllQuads quadMenu value
Remarks: This method sets the “Show All Quads” flag for a specific QuadMenu. Parameters: quadMenu
A pointer to the QuadMenu you wish to set the flag for. value
TRUE to set the flag to on, FALSE to set the flag off. Prototype: <string>getQuadMenuName quadMenu
Parameters: 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
Prototype: setQuadMenuName quadMenu <string>name
Remarks: This method allows you to set the name of a specific QuadMenu. Parameters: 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: numMenus()
Return Value: Returns the total number of menus in registered with the menu manager. Prototype: getMenu index
Parameters: index
Return Value: Retrieves the “index”th menu in the menu manager. This is a 1-based index. Prototype: numQuadMenus()
Return Value: Returns the total number of quad menus registered with the menu manager. Prototype: getQuadMenu index
Parameters: index
Return Value: Retrieves the “index”th quad menu in the menu manager. This is a 1-based index.
See Also In The MAXSDK Help File Class ImenuManager
See Also Menu Manager (p. 75) Interface: quadMenuSettings (p. 414)
377
378
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Interface: msZip Prototype: fileInPackage <string>fileName 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. extractDir
The directory in which the files were extracted. Return Value: TRUE if the zip package was run, otherwise FALSE. Prototype: unloadPackage <string>fileName extractDir 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. extractDir
The directory in which the files were extracted. 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
Interface: NetRender Methods: Prototype: 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: .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.
379
380
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Example: fn myNetMessage msg =-- NOTE: one string parameter format “Message: %\n” msg m.setcallback #message mymessage -- sets the #message callback to use mymessage() #update myupdate
Called when something has changed, like a job started or finished. Let’s you know when you need to make GetUpdate calls, or other refreshing. Requires a function defined with no parameters. Example: fn myUpdate = job.GetUpdate()--example of what you might do m.setcallback #update myupdate -- sets the #update callback to use myupdate() #managerdown mymanagerdown
Called when the manager shuts down. Requires a function defined with no parameters. Example: fn myManagerDown = format “Manager is dead\n” m.setcallback mymanagerdown mymanagerdown()
-- sets the #managerdown callback to use
#queuecontrol myqueuecontrol
Called whenever queue control changes. Requires a function defined with no parameters. Example: fn myQueueControl = format “Queue control has changed\n” m.setcallback #QueueControl myQueueControl--install the “QueueControl” callback #querycontrol myquerycontrol
Called when you have Queue Control, and another computer wants it, either via the QueueManager, or with the script function .QueryControl(). If you want to keep control, set the value .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 .QueueControl() for more information.
Working with the manager
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: .GetCallback
Remarks: Returns the name of the function used for that particular callback. Returns an empty array if no callback is assigned. Requires 1 argument, can be: #progress
Called anytime a download/upload is underway, including anytime you fetch information about jobs or servers #message
Called when the manager has a text message for the user #update
Called when something has changed, like a job started or finished. Let’s you know when you need to make GetUpdate calls, or other refreshing #managerdown
Called when the manager dies #queuecontrol
Called whenever queue control changes #querycontrol
Called when you have Queue Control, and another computer wants it Prototype: .connect #manual <manager name>|<manager IP address> [port:] or .connect #automatic <subnet mask> [port:]
Remarks: Establishes a connection to the manager, allowing access to job states, server states, editing job settings, etc… .It takes 2 arguments and a 3rd optional argument. You can either connect to a manager manually by specifying the manager name or ip address of the manager as a string, or automatically by specifying the subnet mask and optional port number, eg: m.connect #manual “manager”
-- connects to manager of name “manager”
or: m.connect #manual “192.168.0.1”
or:
-- connects to manager of IP 192.168.0.1
381
382
Chapter 1
|
What’s New in 3ds max 4 MAXScript
m.connect #automatic “255.255.255.0” port:1234 -- automatically connects to manager on subnet 255.255.255.0 at port 1234
in either case, you can specify the optional port number should the manager be using a non default port number. Will return true if connection was succesful. Prototype: .Disconnect()
Remarks: Disconnects the connection established with .connect. Prototype: .Kill()
Remarks: Shutsdown the manager. You must have queue control to do this. Prototype: .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 .setCallback. Prototype: .GetControl()
Remarks: Takes control of the queue. Returns true if control was taken. From that moment on, jobs can be submitted, edited, reprioritized, servers can be removed, until queue control is relinquished. Note: The current queue controller does not get its QueryControl callback triggered. Instead, they just lose the queue control (unless they also have the queue locked lock). You should always precede a call to GetControl() with a call to QueryControl(true), to be sure if it’s OK to do this.
Working with the manager
Prototype: .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: .SetUpdates <true | false>
Remarks: This function’s usage resemebles the Lock() function, in that a boolean value is passed, and you must already have queue control. Setting updates to false will freeze the manager so that it refuses any changes to the queue. It does not affect the callbacks. Fewer Update callbacks will be received, since the job queue is not updating. Use this function when submitting large numbers of changes, and when you want all the changes to take effect at the same time. This will occur when setUpdates is called with a true value. Prototype: .checkoutputvisibility <path>
Takes 1 argument, a pathname defined as a string, ie “c:\\temp”. Remarks: It verifies that the path exists, returns “The system cannot find the path specified. (0x3)” if the path doesn’t exist. Note: Note that the manager checks this output path relative to itself, not to your local machine. Thus if you pass “C:\\” and you have not shared you C drive, it will return OK (because the manager checks its own C drive). Thus you should use a network name when calling this function, like “\\\\mymachine\\share\\”. Also, if the parameter does not end in \\, the functions assumes you’re naming a file (not a directory) and checks whether this file could be created. Always include the \\ at the end if you’re checking whether a directory is accessible.
Properties: The following properties can be used to get information or set certain properties of the manager. Prototype: .connected
Remarks: Returns true if connected to the manager.
383
384
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: .netStatus
Remarks: Returns the status of the manager. Various information about the manager can be gathered through netstatus,see netstatus topic. Prototype: .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: .haveControl
Remarks: True, if you currently have QueueControl. Prototype: .numJobs
Remarks: Returns the number of jobs in the queue. Prototype: .numServers
Remarks: Returns the number of servers. Prototype: .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
Prototype: .getjobs [filter:#suspended | #complete | #waiting | #started | #error | #name | #handle | #index] [key: | | ]
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.
385
386
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: .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: .NewJob file:
Example: job.newJob file:”file.max” --submitting a file job.newJob() --submitting the current scene
Remarks: Creates a new job instance. It requires a valid max file name, ie a max file that exists somewhere on the hard drive or the network. Returns a job definition if the file exists, undefined if the file can’t be found. Note: Jobs can not have maps included, and render element data will not be available for submitted job but render elements will process correctly. These problems are resent when submitting a job from a file, but not when submitting the current scene. Prototype: <job>.GetUpdate()
Remarks: Updates the information about the selected job. Remember this involves a network interaction, so it’s a heavyweight operation Prototype: <job>.SendUpdate()
Remarks: Updates the job in the queue with new job settings. Must have queuecontrol. Use .getcontrol() to get queue control. Remember this involves a network interaction, so it’s a heavyweightoperation Prototype: <job>.Submit() Servers:<array>
Remarks: Submits a new job to be rendered to the queue. Must have queuecontrol. Use .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
Remarks: Suspends the selected job. Must have queuecontrol. Use .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 .getcontrol() to get queue control. Prototype: <job>.Restart()
Remarks: Will restart the job from the beginning. Must have queuecontrol. Use .getcontrol() to get queue control. Prototype: <job>.Delete()
Remarks: Will delete the job from the queue. Must have queuecontrol. Use .getcontrol() to get queue control. Prototype: <job>.AssignServer <server>
Remarks: Assigns a selected server to the job. Must have queuecontrol. Use .getcontrol() to get queue control. Prototype: <job>.SuspendServer <server>
Remarks: Removes a server from the selected job. Must have queuecontrol. Use .getcontrol() to get queue control. Prototype: <job>.GetServerInfo
Remarks: Gets information about a particular server assigned to the job. Requires a server number, 1 based. Prototype: <job>.GetRenderElement
387
388
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: Returns information as a data structure about the nth element in the. The <element> structure is defined below. Returns undefined if no element at the index number, eg: el = jobs[1].getrenderelement 1 -- retrieves the 1st element in the 1st job in the queue. With this you can find out if the element is enabled, if filtering is enabled, if atmosphere is applied, if shadows are applied, the element name and the element output filename. The following are the properties that are valid for an element. Prototype: <element>.enabled
Remarks: Returns true if the element is enabled. Can also set it’s state. Prototype: <element>.filterEnabled
Remarks: Returns true if filtering is enabled. Can also set it’s state. Prototype: <element>.atmosphereApplied
Remarks: Returns true if atmosphere is applied. READ-ONLY Prototype: <element>.shadowsApplied
Remarks: Returns true if shadows are applied. READ-ONLY Prototype: <element>.name
Remarks: Returns the elements name. Name can be changed. Prototype: <element>.output
Remarks: Returns the element’s output file name. Output name and path can be changed, however, changing the filetype will change the extension of the image but not the actual file type, eg: the current output returned is “\\ej4sf\frames\foo_diffuse.tga”, changing the extension to .bmp will just result in the tga file having a .bmp extension instead of the .tga extension. Prototype: <job>.SetRenderElement <element>
Working with jobs
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
Remarks: Returns information, as a data structure, about the nth frame. The index is 1 based. The structure is defined below. Example: fr = getframeinfo 4 -- Returns info about the 4th frame. Read-only
Prototype: .state
Remarks: Returns the state of the frame. The state can be #waiting, #assigned or #complete. Prototype: .index
Remarks: Returns the actual frame number. Read-only Prototype: .serverhandle
Remarks: Returns the serverhandle. Should return undefined when frame hasn’t been rendered yet. Read-only Prototype: .servername
389
390
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: Returns the name of the server that is assigned to that frame. Should return undefined if the frame isn’t assigned yet. Read-only Prototype: .elapsedtime
Remarks: Returns the time it took for the frame to render. Should return undefined if the frame isn’t assigned yet. Read-only Prototype: <job>.GetServerStatusText <server>
Remarks: Returns any messages from the chosen server assigned to the job. Will return an empty string if no messages from the server. Read-only Prototype: <job>.numServers
Remarks: Returns the number of servers assigned to the job. Read-only Prototype: <job>.state
Remarks: Returns the state of the job. This can be #complete, #suspended, #busy or #waiting. Read-only Prototype: <job>.serverPID
Remarks: This function gives low-level information that is intended for internal-use-only. Prototype: <job>.handle
Remarks: Returns the job’s handle. Read-only Many of the following values are read-write, but changes you make to these values will not register with the manager until you call <job>.SendUpdate(). Note that SendUpdate requires queue control (obtained via .getControl) Prototype: <job>.name
Remarks: Returns the name of the job. The name can be changed
Working with jobs
Prototype: <job>.filesize
Remarks: Returns the job’s file size Prototype: <job>.filesizeExtracted
Remarks: Returns the job’s extracted file size. Read-only Prototype: <job>.timeSubmitted
Remarks: Returns the time at which the job was submitted as a string. Prototype: <job>.timeStarted
Remarks: Returns the time at which the job was started as a string. Returns undefined if job hasn’t started. Read-only Prototype: <job>.timeFinished
Remarks: Returns the time at which the job was finished as a sting. Returns undefined if job hasn’t finished. Read-only Prototype: <job>.notifications
Remarks: Returns true if notifications are on. Can be changed Prototype: <job>.notifyFailure
Remarks: Returns true if notified of failures. Can be changed Prototype: <job>.notifyProgress
Remarks: Returns true if notified of progress. Can be changed Prototype: <job>.notifyCompletion
391
392
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: Returns true if notified of progress is on. Can be changed Prototype: <job>.notifyFrameInterval
Remarks: Returns an interval at which notifications occur. Can be changed Prototype: <job>.fromFrame
Remarks: Returns the rendering start frame. Can be changed Prototype: <job>.toFrame
Remarks: Returns the rendering end frame. Can be changed Prototype: <job>.nthFrame
Remarks: Returns the rendering frame interval. Can be changed Prototype: <job>.outputWidth
Remarks: Returns the width of the rendered frame. Can be changed Prototype: <job>.outputHeight
Remarks: Returns the height of the rendered frame. Can be changed Prototype: <job>.numFramesComplete
Remarks: The number of completed frames for the job. Read-only Prototype: <job>.priority
Remarks: Returns the job priority.
Working with jobs
Prototype: <job>.videoPost
Remarks: Returns true if there is a video post sequence. Read-only Prototype: <job>.nonconcurrentDriver
Remarks: Returns true if the output cannot be rendered one frame at a time (like .MOV). Read-only Prototype: <job>.includeMaps
Remarks: Returns true if the job was submitted with include maps on. Can be changed Prototype: <job>.uninterruptibleDriver
Remarks: Returns true if the render can’t be resumed if it was interrupted or suspended. For an.AVI, you cannot render half the file, then finish it later. You need to render the whole thing without interruption. Read-only Prototype: <job>.skipRenderedFrames
Remarks: Returns true if skip rendered frames was set to on when job was submitted. Can be changed Prototype: <job>.useAllServers
Remarks: Returns true if use all servers was set to on when job was submitted. Can be changed Prototype: <job>.suspended
Remarks: Returns true if the job is suspended. Read-only. To suspend the job use <job>.suspend() Prototype: <job>.finished
Remarks: Returns true if the job is finished. Read-only Prototype: <job>.ignoreShare
393
394
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: Returns true if the job was submitted with ignore share on. Can be changed Prototype: <job>.skipOutputTest
Remarks: Returns true if the job was submitted with skip output test on. Can be changed Prototype: <job>.nonSeqFrames
Remarks: Returns true if the job was submitted to render non sequential frames. Can be changed Prototype: <job>.combustionJob
Remarks: Returns false if the job is a max job. Read-only Prototype: <job>.uncompressedFile
Remarks: Returns false if the job file is compressed. Read-only Prototype: <job>.gammaCorrection
Remarks: Returns true if the job was submitted with gamma correction on. Can be changed. Prototype: <job>.gammaValueIn
Remarks: Returns a float value of the incomming gamma value. Can be changed. Prototype: <job>.gammaValueOut
Remarks: Returns a float value of the outgoing gamma value. Can be changed. Prototype: <job>.renderPixelAspect
Remarks: Returns a float value of the render pixel aspect ratio. Can be changed.
Working with jobs
Prototype: <job>.renderCamera
Remarks: Returns a string with the name of the camera view being rendered. Will return an empty string if view being rendered is an non camera view, ie perspective, front, user, etc…Can be changed. Use <job>.getcameras() function to get a list of valid cameras in the scene to change to. Prototype: <job>.renderElements
Remarks: Returns true if a job was submitted with the render elements active. Note that this will return true even there aren’t any elements to be rendered. Can be changed. Prototype: <job>.numSceneObjects
Remarks: Returns the number of objects in the scene as an integer. Read-only Prototype: <job>.numSceneFaces
Remarks: Returns the number of faces in the scene as an integer. Read-only Prototype: <job>.numSceneLights
Remarks: Returns the number of lights in the scene as an integer. Read-only Prototype: <job>.sceneStartTime
Remarks: Returns the scene start time in frames, so if your scene is set to use MM:SS:Ticks, this will still return a value in frames. Prototype: <job>.sceneEndTime
Remarks: Returns the scene end time in frames. Prototype: <job>.videoColorCheck
Remarks: Returns true if the job was submitted with videocolorcheck on. Can be changed.
395
396
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: <job>.force2Sided
Remarks: Returns true if the job was submitted with force 2 sided on. Can be changed. Prototype: <job>.renderHiddenObjects
Remarks: Returns true if the job was submitted with render hidden objects on. Can be changed. Prototype: <job>.renderAtmosphericEffects
Remarks: Returns true if the job was submitted with render render atmospheric effects on. Can be changed. Prototype: <job>.superBlack
Remarks: Returns true if the job was submitted with superblack on. Can be changed. Prototype: <job>.serialNumbering
Remarks: Returns true if nth serial numbering is on this property is accesible through the preferences \ rendering dialog. Prototype: <job>.ditherPaletted
Returns true if Dither Paletted was enabled when the job was submitted. Can be changed. Prototype: <job>.ditherTrueColor
Remarks: Returns true if Dither True Color was enabled when the job was submitted. Can be changed. Prototype: <job>.renderFields
Remarks: Returns true if Render Fields was enabled when the job was submitted. Can be changed. Prototype: <job>.renderDisplacements
Remarks: Returns true if displacements was enabled when the job was submitted. Can be changed.
Working with jobs
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
397
398
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: Returns the name and path of the output file. Can be changed Prototype: <job>.frameOutputGamma
Remarks: Returns the output gamma of the rendered frames. Prototype: <job>.frameOutputDevice
Remarks: Returns the device name if a device is specified at render time. Prototype: <job>.numFrames
Remarks: Returns the total number of frames for the particular job
Working with servers Various functions and properties can be used to access rendering servers. You can use the getservers() function to retrieve an array of all servers managed by the manager. The servers can be filtered in various ways to return an array based on the filter. Note: Do not to call GetJobs() or GetServers() very often, because these are VERY heavyweight methods. Prototype: .GetServers [filter:#idle | #busy | #absent | #suspended | #error | #group | #job | #handle | #index] [key:<string> | | <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
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
399
400
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: Returns the server’s handle. Read-only Prototype: <server>.state
Remarks: Returns the state of the server, this can be #idle, #absent, #busy Prototype: <server>.name
Remarks: Returns the name of the server. Read-only Prototype: <server>.totalFrames
Remarks: Returns the total number of frames rendered by the server. Read-only Prototype: <server>.totalTime
Remarks: Returns the total time that the server has been up. The value returned is in hours. Prototype: <server>.performance
Remarks: Returns the performance index of the server. Read-only Prototype: <server>.AttendedPriority
Remarks: Returns the priority, as an integer, of the server when the user is logged in. 0 = high priority, 1 =
low priority, 2 =
Prototype: <server>.UnattendedPriority
idle. Can be changed.
Working with groups
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: .SizeofGroup
Remarks: Returns the number of servers in the nth group. Prototype: .GetGroupName
Remarks: Returns the name of the nth group.
401
402
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: .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: .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
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
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
403
404
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: Returns the login name of the user logged in on the computer or the login name used by the service. Prototype: <system>.tempDir Remarks: Returns the tempdir for the system. Prototype: <system>.computerName
Remarks: Returns the name of the computer. Prototype: <system>.workdisk
Remarks: Returns the disk where max is setup. Prototype: <system>.Disks
Remarks: Returns a bitarray of which disks exist (1=A, 2=B, 3=C etc.) Prototype: <system>.mac
Remarks: Returns the MAC address of the system’s network card. If the computer is a network server, this is its handle.
Examples: -- ESTABLISHING A CONNECTION -m = netrender.getmanager()--get a NetManager instance --start this session m.connect #manual “nimbus” -- OR m.connect #manual “nimbus” port:1234--specifying a port number -- QUEUE CONTROL ---Get QueueControl using GetControl(); --there is no way to release control, but if wantControl==false --then control will be relinquished to the next client --that requests it if( m.QueryControl #wait ) do --only take control if you have permission m.getcontrol() --takes queue control m.wantControl=true--if another client does QueryControl(), they will get a return value of false m.Lock true--this completely prevents others from getting queue control
Examples:
m.Lock false--others can now get control -- SUBMITTING JOBS -job = m.newjob file:”c:\\share\\test.max” job.suspended = true--jobs can be submitted as suspended job.state--should be unsubmitted job.includeMaps = true --turn on “Include Maps” srv_list = m.getservers() --get the server list to assign to the job job.submit servers:srv_list --specify which servers to use for the job -- job.submit() --this uses all servers for the job -- GETTING JOBS & SERVER OBJECTS -m.SetUpdates false--lock the queue, to make sure nothing changes while you download info j = m.getjobs filter:#suspended--an array of NetJob objects; filters are optinal s = m.getservers filter:#idle--an array of NetServer objects; filters are optinal --see below for other filters... there are many m.SetUpdates true--be sure to unlock the queue! -- WORKING WITH GROUPS -m.creategroup s “myGroup”--takes an array of NetServers and a name num_groups = m.numGroups--total number of groups size_group1 = m.SizeofGroup 1--number of servers in the first group g = m.getservers filter:#group key:1 --an array of the servers for group 1 g = m.getservers filter:#group key:”myGroup”--an array of the servers for group “myGroup” g_name = m.GetGroupName 1--the name of the first group m.deletegroup g_name--delete a group -- WORKING WITH JOBS -job = j[1]--pull a job out of the list jHandle = job.handle--the job’s ID p = job.priority--job’s priority if job.nonSeqFrames==TRUE then frames = job.frames--one of those “1,3,5-12” frame lists else frames = (job.fromFrame as string) + “-” + (job.toFrame as string) --now frames is “0-100” if 0 and 100 are the start/end frames cameraArray = job.GetCameras()--an array of the camera names l = job.GetLog--the entire log, as text l = job.GetLog start:4 numLines:2 --gets the 4th and 5th entries of the log statText = job.GetServerStatusText s[1] --text about a server, regarding this job num_workers = job.numServers--number of servers on this job job.frameOutputName = “d:\\blah.bmp”--change the output name isDevice = job.frameOutputDevice--true if the output is to a device, false otherwise share = job.managerShare--the manager share for this job job.filesize--size of the MAZ file for the job job.filesizeextracted--extracted sisze of the MAZ file for the job -- WORKING WITH SERVERS -srv = s[1]--pull a server out of the list sHandle = srv.Handle--the server’s ID sName = srv.name--the server’s machine name speed = srv.performance--server’s performance index
405
406
Chapter 1
|
What’s New in 3ds max 4 MAXScript
srv.ResetPerformance()--reset the index timeUsed = srv.totalTime--total time spent rendering sjHandle = srv.jobHandle--the handle of the server’s current job, 0 if none sjFrameIndex = srv.jobFrameIndex--the index of the frame the server is rendering --PRACTICAL EXAMPLE; get info about the frame being rendered sjHandle = srv.jobHandle sjIndex = srv.jobFrameIndex sJobs = m.getJobs filter:job key:sjHandle--should be an array with one entry frameInfo = (sJobs[1].getFrameInfo sjIndex)--get info about the current frame frameTime = frameInfo.elapsedTime -- UPDATES FROM MANAGER ---Jobs and Servers support GetUpdate and SendUpdate functions, -- for synchronizing with the manager job.status--should be busy job.Suspend() job.status--still says busy (status value is stale) job.GetUpdate()--download the latest news job.status--now says suspended s[1].GetUpdate()--servers also have Get/SendUpdate -- CALLBACKS --- These are used to listen for messages from the manager, -- They are functions you can define, that will get called when -- the manager has something to say -- There are 6 possible callbacks -- NOTE: you can name these functions anything you want, but they must have correct paramters --NETPROGRESS CALLBACK; Called anytime a download/upload is underway, -- including anytime you fetch information about jobs or servers fn myNetProgress total current =--NOTE: two integer parameters format “Progress: completed % out of %\n” current total --NETMESSAGE CALLBACK; Called when the manager has a text message for the user fn myNetMessage msg =--NOTE: one string parameter format “Message: %\n” msg --UPDATE CALLBACK; Called when something has changed, like a job started or finished -- Let’s you know when you need to make GetUpdate calls, or other refreshing fn myUpdate = job.GetUpdate()--example of what you might do --MANAGERDOWN CALLBACK; Called when the manager dies fn myManagerDown = format “Manager is dead\n” --QUEUECONTROL CALLBACK; Called whenever queue control changes fn myQueueControl = format “Queue control has changed\n” --QUERYCONTROL CALLBACK; Called when you have Queue Control, and another computer wants it fn myQueryControl clientName = (--NOTE: one string parameter format “The computer % wants queue control” clientName m.wantControl = true-- use this to keep queue control
Examples:
m.wantControl = false-- use this to release queue control ) --INSTALLING THE CALLBACKS; after you define the functions, you must give them to the -- manager as follows --NOTE: only one callback of each type is allowed (e.g., you can’t have two “Update” callbacks) m.setcallback #Progress myNetProgress--install the “Progress” callback m.setcallback #MessagemyNetMessage --install the “Message” callback m.setcallback #UpdatemyUpdate--install the “Update” callback m.setcallback #ManagerDown myManagerDown --install the “ManagerDown” callback m.setcallback #QueueControl myQueueControl --install the “QueueControl” callback m.setcallback #QueryControl myQueryControl --install the “QueryControl” callback -- NETSTATUS OBJECTS ---Read-only information about a computer on the network stat = s[1].netStatus--get network info about server 1 stat.boottime--make a query stat.Disks-d = stat.workDisk--which is the disk for net-rendering work? stat.SpaceOnDisk d--megabytes of free space on the workdisk stat.memorySize--computer’s memory in bytes (note: 1 meg = 1048576 bytes) s[1].GetUpdate()--this refreshes the netStatus object stat = m.netStatus--manager also has a NetStatus --NOTE: Manager has no GetUpdate(), you must fetch the NetStatus again to see any changes --To print out the operating system on the machine... --Win95 has a platformID of 1; WinNT has a platformID of 2 --Win2K is indicated by a majorBuild of 5 or more for WinNT --Win98 is indicated by a minorBuild greater than 0 for Win95. --Also, build number and the CSDVersion string are not supported by Win95/98 format “Windows %.%, Build %, %\n” \ stat.majorVersion stat.minorVersion stat.buildNumber stat.CSDVersion -- JOBFRAME OBJECTS -num_frames = job.numFrames() frame = job.getFrameInfo 1 --get info about the 1st frame elapsed_time = frame.ElapsedTime --amount of time frame has been rendering num_rendElems = job.numRenderElements()--number of render elements for render if num_rendElems>0 do ( rendElem = job.GetRenderElement 1--pass the index of the element rendElem.enabled = false--turn off the rend element job.SetRenderElement 1 rendElem--update the job with the new changes job.SendUpdate()--upload the changes ) -- JOBSERVER OBJECTS ---Read-only information about a server, in relation to a particular job j_num_servers = j[1].numServers--how many servers does the job have? js = j[1].GetServerInfo 1--info about the job’s first server sh = js.serverHandle--what’s the server’s handle? sn = js.serverName--what’s the server’s name? isWorker = js.active--whether this server participates in this job js_state = js.state--is the server busy with the job? has an error? etc
407
408
Chapter 1
|
What’s New in 3ds max 4 MAXScript
--Print out some stats format “rendering frame %, completed %, total time % hours\n” \ js.currentFrame js.numFramesComplete js.elapsedTime --ways to get more info about this server... jSrv = m.GetServers filter:#handle key:sh--get the actual server object statText = j[1].GetServerStatusText jSrv[1]--text info from the server about this job -- RENDERELEMENT OBJECTS ---Information about particular render elements for a job n = j[1].numRenderElements--how many render elements for this job? re = j[1].GetRenderElement 1--get the first one re.enabled = false--disable it re.filterEnabled = false--disable filtering re.name = “newName”--change its name useShadows = re.shadowsApplied--are shadows applied? (read-only) useShadows = re.atmosphereApplied--are atmospherics applied (read-only) re.output = “C:\\share\\rendElem1.bmp”--change its output path & name j[1].SetRenderElement 1 re--update the job with the new changes j[1].SendUpdate--upload the changes -- WEEKLY SCHEDULES --- a servers’ weekly schedule is an array of seven BitArrays; -- Each bitArray is a day, each bit is an hour sched = s[1].schedule sched[1][11] = false--sunday 11am, the server will not work sched[1][12] = false -- same for sunday noon s[1].attendedPriority = 60--set the priorities for the server’s schedule s[1].unattendedPriority = 10 s[1].schedule = sched--set the new schedule s[1].schedule --printout to prove the change worked s[1].SendUpdate()--upload the changes to this server --NOTE: a Schedule is just a BitArray and has no GetUpdate, --you must fetch it again from the server to see any changes -- MISCELANEOUS FUNCTIONS -jobList = #( j[3], j[1], j[2] )--make an array of some jobs m.SetJobOrder jobList--rearrange the jobs; e.g. j[3] is now the first in the queue mName = (m.netStatus).computerName --the machine name of the manager -- JOB & SERVER FILTERS -jobServers = m.getservers filter:#Job key:j[1] groupServers = m.getservers filter:#group key:”Clouds” -- ENDING THE SEESION -m.wantControl=true--other clients can now get QueueControl m.disconnect()--end this session -- m.kill()--brings down the manager, (would need queue control)
Interface: NullInterface
Interface: NullInterface Interface: NullInterface Note: Intentionally blank.
Interface: objXRefs Interface: objXRefs Methods: Prototype: <maxObject>addNewXRefObject fname <string>objname proxy
Parameters: fname <string>objname proxy
Prototype: getNumXRefObjects fname
Parameters: fname
Prototype: <maxObject>getXRefObject fname index
Parameters: fname index
Prototype: getNumFiles()
Prototype: getFileName index
Parameters: index
Prototype: reloadFile fname
Parameters: fname
Return Value: True if successful and false otherwise. Prototype: isFileUnresolved fname
409
410
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Parameters: fname
Return Value: True if successful and false otherwise. Prototype: isFileDisabled fname
Parameters: 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: 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: openEditor()
Interface: paramWire
Remarks: This method will open up the parameter wiring dialog on the selected objects with no track selected in either tree view. Prototype: editParams leftParam 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: leftParam
The sub-animatable of the left-hand reference target. rightParam
The sub-animatable of the right-hand reference target. Note: The subanim index operator can also take number indexes. Prototype: editParam 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: 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: editControllers leftController rightController
Remarks: Opens the parameter wiring editor dialog on the two given existing wire controllers. Parameters: leftController
A pointer to the controller for the left-hand wire. rightController
A pointer to the controller for the right-hand wire.
411
412
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: editController controller
Remarks: Opens the parameter wiring editor dialog on the given existing wire controller. Parameters: controller
A pointer to the controller being edited. Example: paramWire.editController $foo.radius.controller
Prototype: connect fromParam 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: fromParam
The sub-animatable to wire from. 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: connect2Way leftParam 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: leftParam
The sub-animatable of the left-hand reference target. rightParam
The sub-animatable of the right-hand reference target.
Interface: paramWire
<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: disconnect controller
Remarks: This method allows you to disconnect a one-way wireController from its current parameter, replacing it with either the wire’s existing animation track or a default controller for the parameter. Parameters: controller
A pointer to the wire controller you wish to disconnect. Return Value: TRUE if the disconnect was successful, otherwise FALSE. Prototype: disconnect2Way leftController rightController
Remarks: This method allows you to disconnect a two-way wire between ‘leftcontroller’ and ‘rightController’. If this is the last two-way wire for either controller, replace it with either the the wire’s existing animation track or a default controller for the parameter. Parameters: leftController
A pointer to the first wire controller you wish to disconnect. 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
413
414
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Interface: pluginManager Interface: pluginManager Properties: .visible : boolean : Read|Write
Remarks: Show and hide the plug-in manager.
Methods: 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. Parameters: 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: ResetDefaults()
Remarks: This method will reset the menu settings to their defaults. Prototype: SetBorderSize borderSize
Interface: quadMenuSettings
Remarks: This method allows you to set the menu border size. Parameters: borderSize
The border size in pixels. Prototype: GetBorderSize()
Return Value: This method returns the menu border size. Prototype: SetHorizontalMarginInPoints horizontalMarginInPoints
Remarks: This method allows you to set the menu’s horizontal margin size. Parameters: horizontalMarginInPoints
The horizontal margin size in points. Prototype: GetHorizontalMarginInPoints()
Return Value: This method returns the menu’s horizontal margin size (in points). Prototype: SetVerticalMarginInPoints verticalMarginInPoints
Remarks: This method allows you to set the menu’s vertical margin size. Parameters: verticalMarginInPoints
The vertical margin size in points. Prototype: GetVerticalMarginInPoints()
Return Value: This method returns the menu’s vertical margin size (in points). Prototype: SetItemFontFace <string>szItemFontFace
Remarks: This method allows you to set the menu item’s font typeface.
415
416
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Parameters: <string>szItemFontFace
A string containing the typeface name. Prototype: <string>GetItemFontFace()
Return Value: This method returns the name of the menu item’s font typeface. Prototype: SetTitleFontFace <string>szTitleFontFace
Remarks: This method allows you to set the menu title’s font typeface. Parameters: <string>szTitleFontFace
A string containing the typeface name. Prototype: <string>GetTitleFontFace()
Return Value: This method returns the name of the menu title’s font typeface. Prototype: SetItemFontSize itemFontSize
Remarks: This method allows you to set the menu item’s font size. Parameters: itemFontSize
The size of the font, in points. Prototype: GetItemFontSize()
Return Value: This method returns the menu item’s font size, in points. Prototype: SetTitleFontSize titleFontSize
Remarks: This method allows you to set the menu title’s font size. Parameters: titleFontSize
The size of the font, in points.
Interface: quadMenuSettings
Prototype: GetTitleFontSize()
Return Value: This method returns the menu title’s font size, in points. Prototype: SetUseUniformItemHeight useUniformItemHeight
Remarks: This method allows you to set the status of a menu item’s uniform height flag. Parameters: useUniformItemHeight
TRUE to set the uniform height flag ON, FALSE to set it to OFF. Prototype: GetUseUniformItemHeight()
Return Value: This method returns TRUE or FALSE if the menu item’s uniform height flag is set or not set, respectively. Prototype: SetOpacity opacity
Remarks: This method allows you to set the menu’s opacity value. Parameters: opacity
The opacity value, ranging from 0.0 – 1.0 where 1 is opaque. Prototype: GetOpacity()
Return Value: This method returns the menu’s opacity value. Prototype: SetDisplayMethod displayMethod
Remarks: This method allows you to set a menu’s display method. Parameters: 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.
417
418
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: GetDisplayMethod()
Return Value: This method returns the menu’s display method, which is either of the following; DM_NORMAL, DM_STRETCH, DM_FADE, DM_NUM_METHODS Prototype: SetAnimatedSteps animatedSteps
Remarks: This method allows you to set the menu’s number of animated steps for the ‘growing’ effect. Parameters: animatedSteps
The number of steps. Prototype: GetAnimatedSteps()
Return Value: This method returns the menu’s number of animated steps used for the ‘growing’ effect. Prototype: SetAnimatedStepTime animatedStepTime
Remarks: This method allows you to set the menu’s animated step time. Parameters: animatedStepTime
The animated step time, in milliseconds. Prototype: GetAnimatedStepTime()
Return Value: This method returns the menu’s animated step time, in milliseconds. Prototype: SetSubMenuPauseTime subMenuPauseTime
Remarks: This method allows you to set the delay before a submenu is displayed. Parameters: subMenuPauseTime
The delay, in milliseconds. Prototype: GetSubMenuPauseTime()
Interface: quadMenuSettings
Return Value: This method returns the delay before a submenu is displayed, in milliseconds. Prototype: SetUseLastExecutedItem useLastSelectedItem
Remarks: This method allows you to set the “last executed item” flag which determines whether to use the menu’s last executed item when the user clicks on the menu’s titlebar. Parameters: useLastSelectedItem
Prototype: GetUseLastExecutedItem()
Return Value: This method returns whether the “last executed item” flag is set (TRUE) or not set (FALSE). The flag determines whether to use the menu’s last executed item when the user clicks on the menu’s titlebar. Prototype: SetRepositionWhenClipped 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: repositionWhenClipped
TRUE to turn repositioning ON, FALSE to turn it OFF. Prototype: 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: SetRemoveRedundantSeparators removeRedundantSeparators
Remarks: This method allows you to set the flag which controls and determines whether the menu should remove redundant separators. Parameters: removeRedundantSeparators
TRUE to turn the flag ON, FALSE to turn it OFF.
419
420
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: 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: SetFirstQuadDisplayed firstQuadDisplayed
Remarks: This method allows you to set the first quad which will be displayed when a quad menu pops up. Parameters: firstQuadDisplayed
The quad index, one of the following; QUAD_ONE, QUAD_TWO, QUAD_THREE, or QUAD_FOUR. Prototype: 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: SetUseUniformQuadWidth useUniformQuadWidth
Remarks: This method allows you to set whether the quad menu has a uniform width. Parameters: useUniformQuadWidth
TRUE to set the uniform width, FALSE to set it to non-uniform. Prototype: 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: SetMirrorQuad mirrorQuad
Remarks: This method allows you to set whether the quad menus are mirrored left to right.
Interface: quadMenuSettings
Parameters: mirrorQuad
TRUE to mirror the menus, otherwise FALSE. Prototype: GetMirrorQuad()
Return Value: This method returns TRUE if the quad menu is mirrored left to right, otherwise FALSE. Prototype: SetMoveCursorOnReposition 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: moveCursorOnReposition
TRUE to move the cursor, otherwise FALSE. Prototype: 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: SetReturnCursorAfterReposition 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: returnCursorAfterReposition
TRUE to set the flag, otherwise FALSE. Prototype: 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: SetInitialCursorLocInBox_0to1 initialCursorLocX initialCursorLocY
421
422
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method allows you to set the initial location of the cursor in the center quad box. Parameters: initialCursorLocX initialCursorLocY
The location of the cursor, as a ratio of the box size, between 0.0 and 1.0. Prototype: 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: 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: SetTitleBarBackgroundColor quad color
Remarks: This method allows you to set the title bar background color for a specific quad. color is In parameter Parameters: quad
The quad (numbered 1 through 4). color
The color to set. Prototype: GetTitleBarBackgroundColor quad
Parameters: 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: SetTitleBarTextColor quad color
Interface: quadMenuSettings
Remarks: This method allows you to set the title bar text color for a specific quad. color is In parameter Parameters: quad
The quad (numbered 1 through 4). color
The color to set. Prototype: GetTitleBarTextColor quad
Parameters: 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: SetItemBackgroundColor quad color
Remarks: This method allows you to set the item background color for a specific quad. color is In parameter Parameters: quad
The quad (numbered 1 through 4). color
The color to set. Prototype: GetItemBackgroundColor quad
Parameters: 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: SetItemTextColor quad color
423
424
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method allows you to set the item text color for a specific quad. color is In parameter Parameters: quad
The quad (numbered 1 through 4). color
The color to set. Prototype: GetItemTextColor quad
Parameters: 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: SetLastExecutedItemTextColor quad color
Remarks: This method allows you to set the last executed item text color for a specific quad. color is In parameter Parameters: quad
The quad (numbered 1 through 4). color
The color to set. Prototype: GetLastExecutedItemTextColor quad
Parameters: 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: SetHighlightedItemBackgroundColor quad color
Remarks: This method allows you to set the highlighted item background color for a specific quad. Color is In parameter.
Interface: quadMenuSettings
Parameters: quad
The quad (numbered 1 through 4). color
The color to set. Prototype: GetHighlightedItemBackgroundColor quad
Parameters: 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: SetHighlightedItemTextColor quad color
Remarks: This method allows you to set the highlighted item text color for a specific quad. color is In parameter Parameters: quad
The quad (numbered 1 through 4). color
The color to set. Prototype: GetHighlightedItemTextColor quad
Parameters: 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: SetBorderColor quad color
Remarks: This method allows you to set the border color for a specific quad. color is In parameter
425
426
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Parameters: quad
The quad (numbered 1 through 4). color
The color to set. Prototype: GetBorderColor quad
Parameters: 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: SetDisabledShadowColor quad color
Remarks: This method allows you to set the disabled shadow color for a specific quad. color is In parameter Parameters: quad
The quad (numbered 1 through 4). color
The color to set. Prototype: GetDisabledShadowColor quad
Parameters: 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: SetDisabledHighlightColor quad color
Interface: rollup
Remarks: This method allows you to set the disabled highlight color for a specific quad. color is In parameter Parameters: quad
The quad (numbered 1 through 4). color
The color to set. Prototype: GetDisabledHighlightColor quad
Parameters: 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
427
428
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Interface: SceneRadiosity Interface: SceneRadiosity Properties: .radiosity : maxObject : Read|Write|Validated by
Methods: Prototype: showPanel()
Remarks: The radiosity panel is disabled from the scriptor when there are no radiosity plugins registered. In this case the SceneRadiosity.showPanel() function published method doesn’t do anything. Prototype: closePanel()
Prototype: minimizePanel()
Interface: timeSlider This represents the interface for the time slider.
Methods: Prototype: setVisible 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: visible
TRUE to set the time slider visible, otherwise FALSE. Prototype: 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
Interface: trackviews Interface: trackviews Properties: .currentTrackView : Interface : Read .lastUsedTrackViewName : string : Read
Methods: Prototype: getTrackView name or index
Parameters: name or index
Return Value: This method will get a trackview based on it’s index or name. Prototype: getAllOpenTrackViews()
Return Value: Returns an array of trackviews. Prototype: numTrackViews()
Return Value: Returns the number of trackviews. Prototype: open name or index
Parameters: name or index
Return Value: Open a trackview based on it’s index or name. Prototype: close name or index
Parameters: name or index
Return Value: Close a trackview based on it’s index or name. Prototype: delete name or index
429
430
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: Parameters: name or index
Prototype: <string>getTrackViewName index
Parameters: index
Return Value: Returns the name of the trackview window based on the index. Prototype: zoomSelected name
Parameters: name
Return Value: Zooms to the selected object’s track Prototype: zoomOn name <maxObject>object subNum
Parameters: name <maxObject>object subNum
Return Value: True if successful and false otherwise. Prototype: setFilter()
Remarks: setFilter has variable number of arguments Return Value: True if successful and false otherwise. Prototype: clearFilter()
Remarks: clearFilter has variable number of arguments Return Value: True if successful and false otherwise. Prototype: pickTrackDlg()
Interface: trackviews
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: isOpen name or index
Parameters: name or index
Return Value: Returns a boolean value indicating if the specified trackview is open. Prototype: openLastUsedTrackView()
Return Value: Opens the current trackview if it has been closed. Prototype: isCurrent name or index
Parameters: name or index
Return Value: Returns a boolean value indicating if the trackview is the last one used or not. Prototype: setCurrent name or index
Parameters: 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)
431
432
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Other Interfaces Topic: version 4 MAXScript New Features/Interfaces Interfaces (p. 67) bitmapTex (p. 434) Block Control (p. 435) BMP (p. 437) Flex interfaces: (p. 438) float list (p. 441) Float Reactor (p. 443) Float Wire interfaces: (p. 448) FloatList (p. 450) FloatReactor (p. 452) HSDS Modifier (p. 453) HSDSObject (p. 453) IKChainControl (p. 453) imageMotionBlur (p. 454) JPEG (p. 454) Link (p. 455) Link Constraint (p. 455) LookAt Constraint (p. 455) Motion Blur (p. 462) Orientation Constraint (p. 462) path (p. 462) Path Constraint (p. 468) Plugin Manager (p. 473) Portable Network Graphics (p. 473) point3 list (p. 475) Point3 Reactor (p. 477) Point3 Wire (p. 477) Point3List (p. 479) Point3Reactor (p. 481) Point3Spring (p. 482) Point Cache (p. 484) Point CacheSpacewarpModifier (p. 485)
Interface: trackviews
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)
433
434
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Rotation Wire (p. 508) Scale Wire (p. 515)
See Also Core Interfaces (p. 70) Class and Object Inspector Functions (p. 799) Class and Object Inspector Functions Enhanced (p. 159)
Other Interface Pages bitmapTex interfaces: bitmapTex interfaces: Interface: bitmapTex Methods: Prototype: reload()
Remarks: Reloads the bitmap file using the same name and path. You don’t need to use the file browser to reload the bitmap after you’ve updated it in your paint program. Clicking reload for any instance of the map updates the map in all sample slots and in the scene. Prototype: viewImage()
Remarks: Displays a Virtual Frame Buffer that shows the bitmap surrounded by a region outline. The region outline has handles at its sides and corners. When cropping is on, dragging the handles changes the size of the crop area. You can also drag within the region area to move it. The VFB editing window has U/V and W/H (width/height) spinners on its toolbar. Use these to adjust the location and size the image or crop area. When Place is turned on, dragging the region area handles changes the scale of the bitmap (hold down CTRL to preserve the bitmap’s aspect ratio), and dragging the image changes its location within the tile area. When Crop is turned on, the UV or XY button at the right of the virtual frame buffer toolbar lets you switch between using UV or XY coordinates in the toolbar spinners. Also, you can zoom out by pressing SHIFT+Z and zoom in by pressing Z.
Block_Control interfaces:
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: getCount()
Remarks: This method returns the number of items that appear in the List controllers list box. Prototype: setActive 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: listIndex
The index of the item to set as the active item. Prototype: getActive()
Remarks: This method returns the index of the currently active item. Prototype: delete listIndex
435
436
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method allows you to delete the indexed sub controller from the list. Parameters: listIndex
The index of the item to delete from the list. Prototype: cut 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: listIndex
The index of the item you wish to cut. Prototype: paste listIndex
Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters: listIndex
The index of the slot to paste into. Prototype: getName listIndex
Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesn’t exist. Parameters: listIndex
The index of the item for which to get the name. Prototype: setName listIndex <string>name
Remarks: This method allows you to set the name of an indexed item. Parameters: listIndex
The index of the item. <string>name
The name to set it to.
BMP interfaces:
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: 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
437
438
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Flex interfaces: Flex interfaces: Interface: flexOps Methods: Prototype: paint()
Prototype: setReference()
Prototype: reset()
Prototype: addForce <node>force
Parameters: <node>force Prototype: removeForce force
Parameters: force
Prototype: numberVertices()
Prototype: selectVertices sel update
Parameters: sel update
Prototype: getSelectedVertices()
Prototype: getVertexWeight index
Parameters: index
Prototype: setVertexWeight indices values
Parameters: indices values
Prototype: setEdgeList sel update
Flex interfaces:
Parameters: sel update
Prototype: getEdgeList()
Prototype: addSpringFromSelection flag addDuplicates
Parameters: flag addDuplicates
Prototype: addSpring indexA indexB flag addDuplicates
Parameters: indexA indexB flag addDuplicates
Prototype: removeAllSprings()
Prototype: addSpringButton()
Prototype: removeSpringButton()
Prototype: optionsButton()
Prototype: createSimpleSoftButton()
Prototype: removeSpringByEnd a
Parameters: a
Prototype: removeSpringByEnds a b
Parameters: a b
439
440
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: removeSpringByIndex index
Parameters: index
Prototype: numberSprings()
Prototype: getSpringGroup index
Parameters: index
Prototype: setSpringGroup index group
Parameters: index group
Prototype: getSpringLength index
Parameters: index
Prototype: setSpringLength index length
Parameters: index length
Prototype: getIndex a b
Parameters: a 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:
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: getCount()
Remarks: This method returns the number of items that appear in the List controllers list box. Prototype: setActive 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: listIndex
The index of the item to set as the active item. Prototype: getActive()
Remarks: This method returns the index of the currently active item. Prototype: delete listIndex
Remarks: This method allows you to delete the indexed sub controller from the list. Parameters: listIndex
The index of the item to delete from the list. Prototype: cut listIndex
Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.
441
442
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Parameters: listIndex
The index of the item you wish to cut. Prototype: paste listIndex
Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters: listIndex
The index of the slot to paste into. Prototype: getName listIndex
Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesn’t exist. Parameters: listIndex
The index of the item for which to get the name. Prototype: setName listIndex <string>name
Remarks: This method allows you to set the name of an indexed item. Parameters: 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:
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: 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: 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: delete index
Parameters: index
Return Value: Returns true is successful and false otherwise.
443
444
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: getCount()
Return Value: Returns the reaction count. Prototype: select index
Parameters: index
Prototype: getSelected()
Return Value: Prototype: setStateToCurrent index
Parameters: 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: setFloatState index state
Parameters: index 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: setVectorState index <point3>state
Parameters: 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:
Return Value: Returns true is successful and false otherwise. Prototype: setRotationState index state
Parameters: index 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: setValueToCurrent index
Parameters: 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: setValueAsFloat index value
Parameters: index 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: setValueAsVector index <point3>value
Parameters: index <point3>value
445
446
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: Set the reaction value to the value passed in. The function you use depends on the type of object or controller you are reacting to. See getType() below. Return Value: Returns true is successful and false otherwise. Prototype: setValueAsQuat index value
Parameters: index 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: setInfluence index influence
Parameters: index influence
Remarks: Sets the influence for the specified reaction. Return Value: Returns true is successful and false otherwise. Prototype: setStrength index strength
Parameters: index strength
Remarks: Sets the strength for the specified reaction. Return Value: Returns true is successful and false otherwise. Prototype: setFalloff index influence
Parameters: index influence
Float Reactor interfaces:
Remarks: Sets the falloff for the specified reaction. Return Value: Prototype: setName index <string>name
Parameters: index <string>name
Remarks: Set the name of the reaction specified by the index. Prototype: <string>getName index
Parameters: index
Return Value: Returns the reaction name. Prototype: getInfluence index
Parameters: index
Return Value: Returns the reaction influence. Prototype: getStrength index
Parameters: index
Return Value: Returns the reaction strength. Prototype: getFalloff index
Parameters: index
Return Value: Returns the reaction falloff. Prototype: <enum>getType() getType enums: { #floatReaction | #positionalReaction | #rotationalReaction | #scaleReaction }
447
448
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Return Value: The type of object you are reacting to. Prototype: getState index
Parameters: 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: getValue index
Parameters: 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
Float_Wire interfaces:
Parameters: index
The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype: getWireSubnum index
Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters: index
The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype: getCoController index
Parameters: index
The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype: <string>getExprText index
Parameters: index
The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype: setExprText index <string>text
Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters: index
The index of the parameter <string>text
The expression you wish to set.
449
450
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also In The MAXSDK Help File Class IBaseWireControl
FloatList interfaces: This class represents the interface to the list controller. Properties: .count : integer : Read .active : index : Read|Write
Methods: Prototype: getCount()
Remarks: This method returns the number of items that appear in the List controllers list box. Prototype: setActive 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: listIndex
The index of the item to set as the active item. Prototype: getActive()
Remarks: This method returns the index of the currently active item. Prototype: delete listIndex
Remarks: This method allows you to delete the indexed sub controller from the list. Parameters: listIndex
The index of the item to delete from the list. Prototype: cut listIndex
FloatList interfaces:
Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later. Parameters: listIndex
The index of the item you wish to cut. Prototype: paste listIndex
Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters: listIndex
The index of the slot to paste into. Prototype: getName listIndex
Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesn’t exist. Parameters: listIndex
The index of the item for which to get the name. Prototype: setName listIndex <string>name
Remarks: This method allows you to set the name of an indexed item. Parameters: listIndex
The index of the item. <string>name
The name to set it to.
See Also In the MAXSDK Help File Class IListControl
451
452
Chapter 1
|
What’s New in 3ds max 4 MAXScript
FloatReactor interfaces: FloatReactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: reactTo <maxObject>object create name:<string> name default value: “scriptCreated”} delete index getCount() select index getSelected() setStateToCurrent index setFloatState index state setVectorState index <point3>state setRotationState index state setValueToCurrent index setValueAsFloat index value setValueAsVector index <point3>value setValueAsQuat index value setInfluence index influence setStrength index strength setFalloff index influence setName index <string>name <string>getName index getInfluence index getStrength index getFalloff index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} getState index getValue index Actions:
HSDS_Modifier interfaces:
HSDS_Modifier interfaces: HSDS_Modifier interfaces: Interface: hsdsOps Properties: methods: subdivide() deletePolygon() hide() showAll() createNamedSelection <string>name activateNamedSelection <string>name addDetail length angle removeDetail length angle Actions:
HSDSObject interfaces: HSDSObject interfaces: Interface: hsdsOps Properties: methods: subdivide() deletePolygon() hide() showAll() createNamedSelection <string>name activateNamedSelection <string>name addDetail length angle removeDetail length angle Actions:
IKChainControl interfaces: IKChainControl interfaces: Interface: Action Properties: methods: snap() -- Action Interface ikSnap() -- Action Interface 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 –
453
454
Chapter 1
|
What’s New in 3ds max 4 MAXScript
imageMotionBlur interfaces: imageMotionBlur interfaces: Interface: ImageMotionBlur Properties: methods: Actions:
JPEG interfaces: This represents the interface for the Bitmap IO JPG format. Interface: ijpegio Methods: Prototype: getQuality()
Return Value: This method returns the quality level of the output image. Prototype: setQuality quality
Remarks: This method allows you to set the quality level of the output image. Parameters: quality The quality level. Prototype: getSmoothing()
Return Value: This method returns the smoothing level of the output image. Prototype: setSmoothing smoothing
Remarks: This method allows you set the smoothing level of the output image. Parameters: smoothing The smoothing level.
Link interfaces:
See Also In The MAXSDK Help File Class IBitmapIO_Jpeg
Link interfaces: Link interfaces: Interface: constraints Properties: methods: <node>getTarget index setTarget <node>target index getFrameNo index time setFrameNo frameNo index time getNumTargets() appendTarget <node>target time DeleteTarget targetNumber Actions:
Link_Constraint interfaces: Link_Constraint interfaces: Interface: constraints Methods: <node>getTarget index setTarget <node>target index getFrameNo index time setFrameNo frameNo index time getNumTargets() appendTarget <node>target time DeleteTarget targetNumber
LookAt_Constraint interfaces: This class is an interface to the LookAt Constraint rotation controller. Interface: constraints Methods: Prototype: <node>getTarget index
Parameters: index
The node number in the Look-At target list to be obtained.
455
456
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method will return a pointer to a node of one of the Look-At nodes that the Look-At constraint controller targets, specified by targetNumber. Prototype: setTarget <node>target index
Parameters: <node>target
Points to the node to follow. 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: getWeight index time
Parameters: index
The node number in the Look-At target list whose weight is to be obtained. 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: setWeight weight index time
Parameters: weight
The weight to set. index
The node number in the Look-At target list whose weight is to be set. time
The time at which the weight is to be set. The weights are animatable.
LookAt_Constraint interfaces:
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: getNumTargets()
Remarks: Returns the number of nodes in the list of nodes to look at. Prototype: appendWeightedTarget <node>target weight
Parameters: <node>target
The node that is to be appended to the current Look-At target list. 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: 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: getRelative()
Remarks: Gets the relative/absolute mode corresponding to the “Keep Initial Offset” checkbox in the UI. Prototype: getUpnodeWorld()
457
458
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: Returns TRUE if the “World” checkbox is on; FALSE if off. Prototype: getStoUpAxisFlip()
Remarks: Returns TRUE if the “selected” axis flip checkbox is on; FALSE if off. Prototype: getTargetAxisFlip()
Remarks: Returns TRUE if the “source” axis flip checkbox is on; FALSE if off. Prototype: getSetOrient()
Remarks: Returns TRUE if the orientation flag is set, FALSE if off. Prototype: 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: 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: 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:
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: setRelative rel
Parameters: rel
TRUE to set the relative flag, otherwise FALSE. Remarks: This method allows you to set the “relative” flag. Prototype: setUpnodeWorld upnode
Parameters: upnode
TRUE to set the world flag, otherwise false. Remarks: This method allows you to set the “World” flag. Prototype: setTargetAxisFlip staxflip
Parameters: staxflip
TRUE to set the source flip axis flag, otherwise FALSE. Remarks: This method allows you to set the “source” flip axis flag. Prototype: setStoUPAxisFlip ssuaflip
Parameters: ssuaflip
TRUE to set the selected axis flip flag, otherwise FALSE. Remarks: This method allows you to set the “selected” axis flip flag. Prototype: setSetOrient ssorient
459
460
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Parameters: ssorient
TRUE to set the orientation flag, otherwise FALSE. Remarks: This method allows you to set the orientation flag. Prototype: setResetOrient()
Remarks: Resets to zero the amount of orientation offset, effected through the “Set Orientation” feature. Prototype: setTargetAxis staxis
Parameters: 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: setUpNodeAxis sunaxis
Parameters: 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: setStoUPAxis ssuaxis
Parameters: 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:
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: 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: SetVLisAbs rel
Parameters: 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: deleteTarget targetNumber
Parameters: 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
461
462
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Motion_Blur interfaces: Motion_Blur interfaces: Interface: ImageMotionBlur Properties: methods: Actions:
Orientation_Constraint interfaces: Orientation_Constraint interfaces: Interface: constraints Properties: methods: <node>getTarget index setTarget <node>target index getWeight index time setWeight weight index time getNumTargets() getlw() appendWeightedTarget <node>target weight deleteNode targetNumber Actions:
path interfaces: path interfaces: This class represents the interface to the Path Position Controller. Interface: constraints Methods: getNumTargets()
Remarks: Returns the number of nodes in the path list. Prototype: <node>getTarget index
Remarks: Gets one of the path nodes that the path controller follows, specified by targetNumber. Parameters: index
The node number in the path list to be obtained. Prototype: setTarget <node>target index
path interfaces:
Prototype: getWeight index 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
The node number in the path list whose weight is to be obtained. time
Prototype: setWeight weight index time
Remarks: Sets the weight of one of the path nodes that the path controller follows, specified by targetNumber. Parameters: weight
The weight to assign. index
The node number in the path list whose weight is to be set. time
Return Value: TRUE if there is more than one path in the list and you are trying to set weight, FALSE otherwise. Prototype: appendWeightedTarget <node>target 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. weight
The weight to be assigned to the newly appended path. Prototype: setFollow isSetFollow
Remarks: This method allows you to set the follow flag. Parameters: isSetFollow
TRUE for on, FALSE for off.
463
464
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: getFollow()
Remarks: This method returns the state of the follow flag. TRUE if on; FALSE if off. Prototype: setBankAmount bankAmount
Remarks: Sets the bank amount parameter. Bank and tracking are scaled in the UI. Parameters: bankAmount
The bank amount. Prototype: getBankAmount()
Remarks: Returns the bank amount setting. See the remarks in SetBankAmount() above. Prototype: SetBank isSetBank
Remarks: Sets the bank parameter to on or off. Parameters: isSetBank
TRUE for on; FALSE for off. Prototype: getBank()
Remarks: Returns the on/off state of the bank parameter. TRUE if on; FALSE if off. Prototype: setTracking tracking
Remarks: Sets the smoothness parameter. Parameters: tracking
The smoothness setting. Prototype: getTracking()
path interfaces:
Remarks: Returns the smoothness setting. See remarks in SetTracking() above. Prototype: setAllowFlip allowFlip
Remarks: Sets the state of the ‘Allow Upside Down’ parameter. Parameters: allowFlip
TRUE for on; FALSE for off. Prototype: getAllowFlip()
Remarks: Returns the state of the ‘Allow Upside Down’ parameter. Return Value: TRUE for on; FALSE for off. Prototype: setConstVel constVel
Remarks: Sets the state of the ‘Constant Velocity’ parameter. Parameters: constVel
TRUE for on; FALSE for off. Prototype: getConstVel()
Remarks: Returns the state of the ‘Constant Velocity’ parameter. Return Value: TRUE for on; FALSE for off. Prototype: setFlip Flip
Remarks: Sets the state of the ‘Flip’ parameter. Parameters: Flip
TRUE for on; FALSE for off.
465
466
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: getFlip()
Remarks: Returns the state of the ‘Flip’ parameter. Return Value: TRUE for on; FALSE for off. Prototype: setAxis isSetFollow
Remarks: Set the state of the axis parameter. Parameters: isSetFollow
The axis setting. One of the following values: 0: X axis. 1: Y axis. 2: Z axis. Prototype: getAxis()
Remarks: Returns the axis setting. Return Value: One of the following values: 0: X axis. 1: Y axis. 2: Z axis. Prototype: setLoop Loop
Remarks: This method allows you to set the state of the loop flag. Parameters: Loop
TRUE for on; FALSE for off. Prototype: getLoop()
Remarks: Returns the state of the loop flag.
path interfaces:
Return Value: TRUE for on; FALSE for off. Prototype: setRelative relative
Remarks: This method allows you to set the state of the relative/absolute flag. Parameters: relative
TRUE to set to relative; FALSE to set to absolute. Prototype: getRelative()
Remarks: Returns the state of the relative/absolute flag. Return Value: TRUE if relative is on; FALSE is off (i.e. absolute). Prototype: deleteTarget targetNumber
Remarks: This method allows you to delete a specified target. Parameters: 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
467
468
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Path_Constraint interfaces: Path_Constraint interfaces: This class represents the interface to the Path Position Controller. Interface: constraints Properties: Methods: Prototype: getNumTargets()
Prototype: <node>getTarget index
Parameters: 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: setTarget <node>target index
Prototype: getWeight index time
Parameters: index
The node number in the path list whose weight is to be obtained. 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: setWeight weight index time
Remarks: Sets the weight of one of the path nodes that the path controller follows, specified by targetNumber. Parameters: index
The node number in the path list whose weight is to be set. weight
The weight to assign. time
Path_Constraint interfaces:
Return Value: TRUE if there is more than one path in the list and you are trying to set weight, FALSE otherwise. Prototype: appendWeightedTarget <node>target 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. weight
The weight to be assigned to the newly appended path. Default: 50.0 Prototype: setFollow isSetFollow
Remarks: This method allows you to set the follow flag. Parameters: isSetFollow
TRUE for on, FALSE for off. Prototype: getFollow()
Return Value: This method returns the state of the follow flag. TRUE if on; FALSE if off. Prototype: setBankAmount 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: bankAmount
The bank amount. Prototype: getBankAmount()
Return Value: Returns the bank amount setting. See the remarks in SetBankAmount() above.
469
470
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: SetBank isSetBank
Remarks: Sets the bank parameter to on or off. Parameters: isSetBank
TRUE for on; FALSE for off. Prototype: getBank()
Return Value: Returns the on/off state of the bank parameter. TRUE if on; FALSE if off. Prototype: setTracking 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: tracking
The smoothness setting. Prototype: getTracking()
Return Value: Returns the smoothness setting. See remarks in SetTracking() above. Prototype: setAllowFlip allowFlip
Remarks: Sets the state of the ‘Allow Upside Down’ parameter. Parameters: allowFlip
TRUE for on; FALSE for off. Prototype: getAllowFlip()
Remarks: Returns the state of the ‘Allow Upside Down’ parameter. Return Value: TRUE for on; FALSE for off.
Path_Constraint interfaces:
Prototype: setConstVel constVel
Remarks: Sets the state of the ‘Constant Velocity’ parameter. Parameters: constVel
TRUE for on; FALSE for off. Prototype: getConstVel()
Remarks: Returns the state of the ‘Constant Velocity’ parameter. Return Value: TRUE for on; FALSE for off. Prototype: setFlip Flip
Remarks: Sets the state of the ‘Flip’ parameter. Parameters: Flip
TRUE for on; FALSE for off. Prototype: getFlip()
Remarks: Returns the state of the ‘Flip’ parameter. Return Value: TRUE for on; FALSE for off. Prototype: setAxis isSetFollow
Remarks: Set the state of the axis parameter. Parameters: isSetFollow
The axis setting. One of the following values: 0: X axis. 1: Y axis. 2: Z axis.
471
472
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: getAxis()
Remarks: Returns the axis setting. Return Value: One of the following values: 0: X axis. 1: Y axis. 2: Z axis. Prototype: setLoop Loop
Remarks: This method allows you to set the state of the loop flag. Parameters: Loop
TRUE for on; FALSE for off. Prototype: getLoop()
Remarks: Returns the state of the loop flag. Return Value: TRUE for on; FALSE for off. Prototype: setRelative relative
Remarks: This method allows you to set the state of the relative/absolute flag. Parameters: relative
TRUE to set to relative; FALSE to set to absolute. Prototype: 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:
Prototype: deleteTarget targetNumber
Remarks: This method allows you to delete a specified target. Parameters: 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: 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.
473
474
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: 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: getAlpha()
Return Value: This method returns TRUE if the alpha flag is set, otherwise FALSE. Prototype: setAlpha useAlpha
Parameters: useAlpha
TRUE to set the alpha flag, otherwise FALSE. Remarks: This method allows you to set the alpha flag. Prototype: getInterlaced()
Return Value: This method returns TRUE if the interlaced flag is set, otherwise FALSE. Prototype: setInterlaced Interlaced
Parameters: 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:
point3_list interfaces: This class represents the interface to the list controller. Interface: list Properties: .count : integer : Read .active : index : Read|Write
Methods: Prototype: getCount()
Remarks: This method returns the number of items that appear in the List controllers list box. Prototype: setActive listIndex
Parameters: 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: getActive()
Remarks: This method returns the index of the currently active item. Prototype: delete listIndex
Parameters: 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: cut listIndex
Parameters: listIndex
The index of the item you wish to cut.
475
476
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later. Prototype: paste listIndex
Parameters: 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: getName listIndex
Parameters: 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: setName listIndex <string>name
Parameters: 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:
Point3_Reactor interfaces: Point3_Reactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: reactTo <maxObject>object create name:<string> name default value: “scriptCreated”} delete index getCount() select index getSelected() setStateToCurrent index setFloatState index state setVectorState index <point3>state setRotationState index state setValueToCurrent index setValueAsFloat index value setValueAsVector index <point3>value setValueAsQuat index value setInfluence index influence setStrength index strength setFalloff index influence setName index <string>name <string>getName index getInfluence index getStrength index getFalloff index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} getState index getValue 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.
477
478
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.isSlave : boolean : Read
This method will return TRUE if the wire is a slave predicate, otherwise it will return FALSE. .isTwoWay : boolean : Read
This method will return TRUE if the wire is a two-way predicate, otherwise it will return FALSE. .slaveAnimation : control : Read|Write
This method returns a pointer to the slave animation controller. This method allows you to set the slave animation controller. Prototype: <maxObject>getWireParent index
Parameters: index
The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype: getWireSubnum index
Parameters: 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: getCoController index
Parameters: index
The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype: <string>getExprText index
Parameters: index
The index of the parameter.
Point3List interfaces:
Return Value: This method returns the expression string of the i-th wire parameter. Prototype: setExprText index <string>text
Parameters: 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: getCount()
Remarks: This method returns the number of items that appear in the List controllers list box. Prototype: setActive 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: listIndex
The index of the item to set as the active item.
479
480
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: getActive()
Remarks: This method returns the index of the currently active item. Prototype: delete listIndex
Remarks: This method allows you to delete the indexed sub controller from the list. Parameters: listIndex
The index of the item to delete from the list. Prototype: cut 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: listIndex
The index of the item you wish to cut. Prototype: paste listIndex
Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters: listIndex
The index of the slot to paste into. Prototype: getName listIndex
Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesn’t exist. Parameters: listIndex
The index of the item for which to get the name. Prototype: setName listIndex <string>name
Point3Reactor interfaces:
Remarks: This method allows you to set the name of an indexed item. Parameters: 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: reactTo <maxObject>object create name:<string> name default value: “scriptCreated”} delete index getCount() select index getSelected() setStateToCurrent index setFloatState index state setVectorState index <point3>state setRotationState index state setValueToCurrent index setValueAsFloat index value setValueAsVector index <point3>value setValueAsQuat index value setInfluence index influence setStrength index strength setFalloff index influence setName index <string>name <string>getName index getInfluence index getStrength index getFalloff index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} getState index
481
482
Chapter 1
|
What’s New in 3ds max 4 MAXScript
getValue index Actions:
Point3Spring interfaces: Interface: Spring Properties: Methods: Prototype: getMass()
Return Value: Returns the mass. Prototype: setMass mass
Parameters: 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: getDrag()
Return Value: Returns the drag. Prototype: setDrag drag
Parameters: 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: getTension springIndex
Parameters: springIndex
Return Value: Gets the tension for the spring corresponding to the index.
Point3Spring interfaces:
Prototype: setTension springIndex tension
Parameters: springIndex 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: getDampening springIndex
Parameters: springIndex
Return Value: Gets the dampening for the spring corresponding to the index. Prototype: setDampening springIndex dampening
Parameters: springIndex 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: addSpring <node>node
Parameters: <node>node
Remarks: Adds the node to the spring list. Return Value: Returns true if successful, false otherwise Prototype: getSpringCount()
483
484
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Return Value: Returns the number of springs in the spring system. Prototype: removeSpringByIndex springIndex
Parameters: springIndex
Remarks: Removes the spring corresponding to the index. Prototype: 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: record()
Remarks: This method will press the Record button in the rollup interface.
Point_CacheSpacewarpModifier interfaces:
Prototype: setCache()
Remarks: This method will press the Set Cache button in the rollup interface. Prototype: enableMods()
Remarks: This method will press the Enable Modifiers Below button in the rollup interface. Prototype: 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: record()
Remarks: This method will press the Record button in the rollup interface. Prototype: setCache()
Remarks: This method will press the Set Cache button in the rollup interface. Prototype: enableMods()
485
486
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method will press the Enable Modifiers Below button in the rollup interface. Prototype: 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: record()
Remarks: This method will press the Record button in the rollup interface. Prototype: setCache()
Remarks: This method will press the Set Cache button in the rollup interface. Prototype: enableMods()
Remarks: This method will press the Enable Modifiers Below button in the rollup interface. Prototype: disableMods()
Remarks: This method will press the Disable Modifiers Below button in the rollup interface.
PointCacheWSM interfaces:
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: record()
Remarks: This method will press the Record button in the rollup interface. Prototype: setCache()
Remarks: This method will press the Set Cache button in the rollup interface. Prototype: enableMods()
Remarks: This method will press the Enable Modifiers Below button in the rollup interface. Prototype: disableMods()
Remarks: This method will press the Disable Modifiers Below button in the rollup interface.
See Also In The MAXSDK Help File Class IPointCacheWSM
487
488
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also Point Cache Modifier (p. 26) Point_Cache - superclass: modifier (p. 314) Point_Cache interfaces: (p. 484) Point_CacheSpacewarpModifier - superclass: SpacewarpModifier (p. 315) Point_CacheSpacewarpModifier_interfaces_
Position_Constraint interfaces: Position_Constraint interfaces: This class represents the interface to the Position Constraint. Interface: constraints Methods: Prototype: getNumTargets()
Remarks: Returns the number of target nodes in the position target list. Prototype: <node>getTarget index
Remarks: Gets one of the position nodes that the position constraint controller targets, specified by targetNumber. Parameters: index
The node number in the position target list to be obtained. Prototype: setTarget <node>target index
Prototype: getWeight index 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
The node number in the position target list to set. time
Position_Constraint interfaces:
Return Value: Returns the position target weight if the targetNumber is relevant, 0.0f otherwise. Prototype: setWeight weight index 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
The node number in the position target list whose weight is to be set. weight
The weight to set. 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: appendTarget <node>target 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. weight
This is the weight that is to be assigned to the newly appended position target. The default weight is 50.0. Prototype: deleteTarget targetNumber
Remarks: This method allows you to delete a specified target. Parameters: targetNumber
The node number in the position target list to delete. Return Value: TRUE if successful, otherwise FALSE.
489
490
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also In The MAXSDK Help File Class IPosConstPosition
position_list interfaces: This class represents the interface to the list controller. Interface: list Properties: .count : integer : Read .active : index : Read|Write
Methods: Prototype: getCount()
Remarks: This method returns the number of items that appear in the List controllers list box. Prototype: setActive 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: listIndex
The index of the item to set as the active item. Prototype: getActive()
Remarks: This method returns the index of the currently active item. Prototype: delete listIndex
Parameters: 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: cut listIndex
position_list interfaces:
Parameters: 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: paste listIndex
Parameters: 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: getName listIndex
Parameters: listIndex
The index of the item for which to get the name. Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesn’t exist. Prototype: setName listIndex <string>name
Parameters: listIndex
The index of the item. <string>name
The name to set it to. Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesn’t exist.
See Also In the MAXSDK Help File Class IListControl
491
492
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Position_Reactor interfaces: Position_Reactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: reactTo <maxObject>object create name:<string> name default value: “scriptCreated”} delete index getCount() select index getSelected() setStateToCurrent index setFloatState index state setVectorState index <point3>state setRotationState index state setValueToCurrent index setValueAsFloat index value setValueAsVector index <point3>value setValueAsQuat index value setInfluence index influence setStrength index strength setFalloff index influence setName index <string>name <string>getName index getInfluence index getStrength index getFalloff index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} getState index getValue 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:
.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
Parameters: index
The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype: getWireSubnum index
Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters: index
The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype: getCoController index
Parameters: index
The index of the controller. Return Value: This method returns a pointer to the i-th CoController.
493
494
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: <string>getExprText index
Parameters: index
The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype: setExprText index <string>text
Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters: 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: getCount()
Remarks: This method returns the number of items that appear in the List controllers list box. Prototype: setActive 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:
Parameters: listIndex
The index of the item to set as the active item. Prototype: getActive()
Remarks: This method returns the index of the currently active item. Prototype: delete listIndex
Remarks: This method allows you to delete the indexed sub controller from the list. Parameters: listIndex
The index of the item to delete from the list. Prototype: cut 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: listIndex
The index of the item you wish to cut. Prototype: paste listIndex
Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters: listIndex
The index of the slot to paste into. Prototype: getName listIndex
Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesn’t exist. Parameters: listIndex
The index of the item for which to get the name.
495
496
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: setName listIndex <string>name
Remarks: This method allows you to set the name of an indexed item. Parameters: 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: reactTo <maxObject>object create name:<string> name default value: “scriptCreated”} delete index getCount() select index getSelected() setStateToCurrent index setFloatState index state setVectorState index <point3>state setRotationState index state setValueToCurrent index setValueAsFloat index value setValueAsVector index <point3>value setValueAsQuat index value setInfluence index influence setStrength index strength setFalloff index influence setName index <string>name <string>getName index getInfluence index getStrength index getFalloff index <enum>getType()
PositionSpring interfaces:
getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} getState index getValue index Actions:
PositionSpring interfaces: Interface: Spring Properties: Methods: Prototype: getMass()
Return Value: Returns the mass. Prototype: setMass mass
Parameters: 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: getDrag()
Return Value: Returns the drag. Prototype: setDrag drag
Parameters: 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: getTension springIndex
Parameters: springIndex
497
498
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Return Value: Gets the tension for the spring corresponding to the index. Prototype: setTension springIndex tension
Parameters: springIndex 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: getDampening springIndex
Parameters: springIndex
Return Value: Gets the dampening for the spring corresponding to the index. Prototype: setDampening springIndex dampening
Parameters: springIndex 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: addSpring <node>node
Parameters: <node>node
Remarks: Adds the node to the spring list. Return Value: Returns true if successful, false otherwise
PositionSpring interfaces:
Prototype: getSpringCount()
Return Value: Returns the number of springs in the spring system. Prototype: removeSpringByIndex springIndex
Parameters: springIndex
Remarks: Removes the spring corresponding to the index. Prototype: 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)
499
500
Chapter 1
|
What’s New in 3ds max 4 MAXScript
radiusManip interfaces: Interface: Manip Properties: .mouseState : enum : Read mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}
Methods: Prototype: clearGizmos()
Remarks: This must be called at the beginning of the “updateGizmos” handler in order to clear the current gizmo cache. Prototype: addGizmoMesh <mesh>mesh flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <mesh>mesh 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: addGizmoShape gizmo flags <point3 by value>unselColor <point3 by value>selColor
Parameters: gizmo flags gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
radiusManip interfaces:
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: addGizmoMarker <enum>marker <point3 by value>position 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. 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.
501
502
Chapter 1
|
What’s New in 3ds max 4 MAXScript
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport. <point3 by value>unselColor <point3 by value>selColor
Remarks: The position is a point in 3d space, or 2d screen space. Prototype: addGizmoText <string>text <point3 by value>position flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <string>text <point3 by value>position 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: 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: updateGizmos t toolTip
Remarks: Parameters: t toolTip
RenderElementMgr interfaces:
RenderElementMgr interfaces: Interface: RenderElementMgr Prototype: AddRenderElement <maxObject>element
Parameters: <maxObject>element
Remarks: Adds a specific element. Return Value: Returns TRUE if Successful, FALSE otherwise Prototype: RemoveRenderElement <maxObject>element
Parameters: <maxObject>element
Remarks: Removes a specific element. Return Value: Returns true is successful and false otherwise. Prototype: RemoveAllRenderElements()
Remarks: Removes all elements in the list. Prototype: NumRenderElements()
Return Value: Returns number of elements in list Prototype: <maxObject>GetRenderElement index
Parameters: index
Return Value: Returns a specific element, index is 0 based. Prototype: SetElementsActive active
Parameters: active
503
504
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: Sets a boolean indicating elements are active, ie. will be created during a render. Prototype: GetElementsActive()
Return Value: Gets a boolean indicating elements are active, ie. will be created during a render. Prototype: SetDisplayElements display
Parameters: display
Remarks: Sets boolean indicating elements will be displayed after they are created. Prototype: GetDisplayElements()
Return Value: Gets boolean indicating elements will be displayed after they are created. Prototype: SetCombustionOutputEnabled enabled
Parameters: enabled
Remarks: Enables or disables output to combustion .cws file. Prototype: GetCombustionOutputEnabled()
Return Value: Gets boolean indicating enabled output to combustion .cws file. Prototype: 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:
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: getCount()
505
506
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method returns the number of items that appear in the List controllers list box. Prototype: setActive 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: listIndex
The index of the item to set as the active item. Prototype: getActive()
Remarks: This method returns the index of the currently active item. Prototype: delete listIndex
Remarks: This method allows you to delete the indexed sub controller from the list. Parameters: listIndex
The index of the item to delete from the list. Prototype: cut 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: listIndex
The index of the item you wish to cut. Prototype: paste listIndex
Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters: listIndex
The index of the slot to paste into.
Rotation_Reactor interfaces:
Prototype: getName listIndex
Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesn’t exist. Parameters: listIndex
The index of the item for which to get the name. Prototype: setName listIndex <string>name
Remarks: This method allows you to set the name of an indexed item. Parameters: 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: reactTo <maxObject>object create name:<string> name default value: “scriptCreated”} delete index getCount() select index getSelected() setStateToCurrent index setFloatState index state setVectorState index <point3>state setRotationState index state setValueToCurrent index setValueAsFloat index value setValueAsVector index <point3>value
507
508
Chapter 1
|
What’s New in 3ds max 4 MAXScript
setValueAsQuat index value setInfluence index influence setStrength index strength setFalloff index influence setName index <string>name <string>getName index getInfluence index getStrength index getFalloff index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} getState index getValue 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
Parameters: index
The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent.
Rotation_Wire interfaces:
Prototype: getWireSubnum index
Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters: index
The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype: getCoController index
Parameters: index
The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype: <string>getExprText index
Parameters: index
The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype: setExprText index <string>text
Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters: index
The index of the parameter <string>text
The expression you wish to set.
See Also In The MAXSDK Help File Class IBaseWireControl
509
510
Chapter 1
|
What’s New in 3ds max 4 MAXScript
RotationList interfaces: This class represents the interface to the list controller. Interface: list Properties: .count : integer : Read .active : index : Read|Write
Methods: Prototype: getCount()
Remarks: This method returns the number of items that appear in the List controllers list box. Prototype: setActive 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: listIndex
The index of the item to set as the active item. Prototype: getActive()
Remarks: This method returns the index of the currently active item. Prototype: delete listIndex
Remarks: This method allows you to delete the indexed sub controller from the list. Parameters: listIndex
The index of the item to delete from the list. Prototype: cut 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:
Parameters: listIndex
The index of the item you wish to cut. Prototype: paste listIndex
Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters: listIndex
The index of the slot to paste into. Prototype: getName listIndex
Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesn’t exist. Parameters: listIndex
The index of the item for which to get the name. Prototype: setName listIndex <string>name
Remarks: This method allows you to set the name of an indexed item. Parameters: listIndex
The index of the item. <string>name
The name to set it to.
See Also In the MAXSDK Help File Class IListControl
511
512
Chapter 1
|
What’s New in 3ds max 4 MAXScript
RotationReactor interfaces: RotationReactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: reactTo <maxObject>object create name:<string> name default value: “scriptCreated”} delete index getCount() select index getSelected() setStateToCurrent index setFloatState index state setVectorState index <point3>state setRotationState index state setValueToCurrent index setValueAsFloat index value setValueAsVector index <point3>value setValueAsQuat index value setInfluence index influence setStrength index strength setFalloff index influence setName index <string>name <string>getName index getInfluence index getStrength index getFalloff index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} getState index getValue index Actions:
scale_list interfaces:
scale_list interfaces: This class represents the interface to the list controller. Interface: list Properties: .count : integer : Read .active : index : Read|Write
Methods: Prototype: getCount()
Remarks: This method returns the number of items that appear in the List controllers list box. Prototype: setActive 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: listIndex
The index of the item to set as the active item. Prototype: getActive()
Remarks: This method returns the index of the currently active item. Prototype: delete listIndex
Remarks: This method allows you to delete the indexed sub controller from the list. Parameters: listIndex
The index of the item to delete from the list. Prototype: cut listIndex
Remarks: This method allows you to cut the index sub controller from the list and stores it in the buffer to paste later.
513
514
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Parameters: listIndex
The index of the item you wish to cut. Prototype: paste listIndex
Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters: listIndex
The index of the slot to paste into. Prototype: getName listIndex
Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesn’t exist. Parameters: listIndex
The index of the item for which to get the name. Prototype: setName listIndex <string>name
Remarks: This method allows you to set the name of an indexed item. Parameters: 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:
Scale_Reactor interfaces: Scale_Reactor interfaces: Interface: reactions Properties: .editStateMode : boolean : Read|Write .useCurve : boolean : Read|Write methods: reactTo <maxObject>object create name:<string> name default value: “scriptCreated”} delete index getCount() select index getSelected() setStateToCurrent index setFloatState index state setVectorState index <point3>state setRotationState index state setValueToCurrent index setValueAsFloat index value setValueAsVector index <point3>value setValueAsQuat index value setInfluence index influence setStrength index strength setFalloff index influence setName index <string>name <string>getName index getInfluence index getStrength index getFalloff index <enum>getType() getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} getState index getValue 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).
515
516
Chapter 1
|
What’s New in 3ds max 4 MAXScript
.isMaster : boolean : Read
This property will return TRUE if the wire is a master predicate, otherwise it will return FALSE. .isSlave : boolean : Read
This method will return TRUE if the wire is a slave predicate, otherwise it will return FALSE. .isTwoWay : boolean : Read
This method will return TRUE if the wire is a two-way predicate, otherwise it will return FALSE. .slaveAnimation : control : Read|Write
This method returns a pointer to the slave animation controller. This method allows you to set the slave animation controller. Prototype: <maxObject>getWireParent index
Parameters: index
The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype: getWireSubnum index
Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters: index
The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype: getCoController index
Parameters: index
The index of the controller. Return Value: This method returns a pointer to the i-th CoController.
ScaleList interfaces:
Prototype: <string>getExprText index
Parameters: index
The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype: setExprText index <string>text
Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters: 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: getCount()
Remarks: This method returns the number of items that appear in the List controllers list box. Prototype: setActive 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.
517
518
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Parameters: listIndex
The index of the item to set as the active item. Prototype: getActive()
Remarks: This method returns the index of the currently active item. Prototype: delete listIndex
Remarks: This method allows you to delete the indexed sub controller from the list. Parameters: listIndex
The index of the item to delete from the list. Prototype: cut 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: listIndex
The index of the item you wish to cut. Prototype: paste listIndex
Remarks: This method allows you to paste the sub-controller from the buffer into the indexed slot in the list. Parameters: listIndex
The index of the slot to paste into. Prototype: getName listIndex
Remarks: This method returns the class name of the indexed sub-controller if a user defined name doesn’t exist. Parameters: listIndex
The index of the item for which to get the name.
ScaleReactor interfaces:
Prototype: setName listIndex <string>name
Remarks: This method allows you to set the name of an indexed item. Parameters: 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: reactTo <maxObject>object create name:<string> name default value: “scriptCreated”} delete index getCount() select index getSelected() setStateToCurrent index setFloatState index state setVectorState index <point3>state setRotationState index state setValueToCurrent index setValueAsFloat index value setValueAsVector index <point3>value setValueAsQuat index value setInfluence index influence setStrength index strength setFalloff index influence setName index <string>name <string>getName index getInfluence index getStrength index getFalloff index <enum>getType()
519
520
Chapter 1
|
What’s New in 3ds max 4 MAXScript
getType enums: {#floatReaction|#positionalReaction|#rotationalReaction|#scaleReaction} getState index getValue index Actions:
sliderManipulator interfaces: Interface: Manip Scripted Manipulators (p. 97) Properties: .mouseState : enum : Read mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}
Methods: Prototype: clearGizmos()
Remarks: This must be called at the beginning of the “updateGizmos” handler in order to clear the current gizmo cache. Prototype: addGizmoMesh <mesh>mesh flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <mesh>mesh 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:
Prototype: addGizmoShape gizmo flags <point3 by value>unselColor <point3 by value>selColor
Parameters: gizmo 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: addGizmoMarker <enum>marker <point3 by value>position 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. 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.
521
522
Chapter 1
|
What’s New in 3ds max 4 MAXScript
gizmoUseScreenSpace
This tells the system to interpret the coordinates of the shape as device coordinates in the viewport, not as 3d values. The values are still specified as 3d points, but the “Z” coordinate is ignored. gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport. <point3 by value>unselColor <point3 by value>selColor
Remarks: The position is a point in 3d space, or 2d screen space. The flags are the same ones supported by addGizmoShape. Prototype: addGizmoText <string>text <point3 by value>position flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <string>text <point3 by value>position 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: 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: updateGizmos t toolTip
Remarks: Parameters: t toolTip
SpringPoint3Controller interfaces:
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: getMass()
Return Value: Returns the mass. Prototype: setMass mass
Parameters: 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: getDrag()
Return Value: Returns the drag.
523
524
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: setDrag drag
Parameters: 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: getTension springIndex
Parameters: springIndex
Return Value: Gets the tension for the spring corresponding to the index. Prototype: setTension springIndex tension
Parameters: springIndex 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: getDampening springIndex
Parameters: springIndex
Return Value: Gets the dampening for the spring corresponding to the index. Prototype: setDampening springIndex dampening
Parameters: springIndex 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:
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: addSpring <node>node
Parameters: <node>node
Remarks: Adds the node to the spring list. Return Value: Returns true if successful, false otherwise Prototype: getSpringCount()
Return Value: Returns the number of springs in the spring system. Prototype: removeSpringByIndex springIndex
Parameters: springIndex
Remarks: Removes the spring corresponding to the index. Prototype: 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)
525
526
Chapter 1
|
What’s New in 3ds max 4 MAXScript
SpringPositionController - superclass: PositionController (p. 337) Flex : Modifier (p. 1128) Flex interfaces: (p. 438) flexOps const StructDef (p. 235)
SpringPositionController interfaces: Interface: Spring Properties: Methods: Prototype: getMass()
Return Value: Returns the mass. Prototype: setMass mass
Parameters: 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: getDrag()
Return Value: Returns the drag. Prototype: setDrag drag
Parameters: 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: getTension springIndex
SpringPositionController interfaces:
Parameters: springIndex
Return Value: Gets the tension for the spring corresponding to the index. Prototype: setTension springIndex tension
Parameters: springIndex 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: getDampening springIndex
Parameters: springIndex
Return Value: Gets the dampening for the spring corresponding to the index. Prototype: setDampening springIndex dampening
Parameters: springIndex 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: addSpring <node>node
Parameters: <node>node
Remarks: Adds the node to the spring list.
527
528
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Return Value: Returns true if successful, false otherwise Prototype: getSpringCount()
Return Value: Returns the number of springs in the spring system. Prototype: removeSpringByIndex springIndex
Parameters: springIndex
Remarks: Removes the spring corresponding to the index. Prototype: 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:
Targa interfaces: This class represents the interface for the Bitmap IO TGA format. Interface: itgaio Methods: Prototype: getColorDepth()
Return Value: This method returns the color depth, which would be 16, 24, or 32. Prototype: setColorDepth colorDepth
Remarks: This method allows you to set the color depth. Parameters: colorDepth
The color depth, being either 16, 24, or 32. Prototype: getCompressed()
Return Value: This method returns TRUE if the compression flag is set, otherwise FALSE. Prototype: setCompressed compression
Remarks: This method allows you to set the compression flag. Parameters: compression
TRUE to set the compression flag, otherwise FALSE. Prototype: getAlphaSplit()
Return Value: This method returns TRUE if the alpha split flag is set, otherwise FALSE. Prototype: setAlphaSplit alphaSplit
Remarks: This method allows you to set the alpha split flag.
529
530
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Parameters: alphaSplit
TRUE to set the alpha split flag, otherwise FALSE. Prototype: getPreMultAlpha()
Return Value: This method returns TRUE if the premultiplied alpha flag is set, otherwise FALSE. Prototype: setPreMultAlpha preMultAlpha
Remarks: This method allows you to set the premultiplied alpha flag. Parameters: 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: planarMap()
Remarks: This method will press the Planar Map button in the rollup interface. Prototype: save()
Remarks: This method will press the Save button in the rollup interface. Prototype: load()
Remarks: This method will press the Load button in the rollup interface.
Unwrap_UVW interfaces:
Prototype: reset()
Remarks: This method will press the Reset button in the rollup interface. Prototype: edit()
Remarks: This method will press the Edit button in the rollup interface. Prototype: setMapChannel mapChannel
Remarks: This method will set the Map Channel field value in the rollup. Parameters: mapChannel
The Map Channel you want to set to. Prototype: getMapChannel()
Return Value: This method will return the Map Channel field in the rollup. Prototype: setProjectionType mapChannel
Parameters: 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: 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: setVC vertexColor
531
532
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method will set the Vertex Color Channel radio button in the rollup interface. Parameters: vertexColor
TRUE to enable; FALSE to disable. Prototype: getVC()
Return Value: This method returns the current state of the Vertex Color Channel radio button in the rollup interface. Prototype: move()
Remarks: This method will press the Move button in the edit floater. Prototype: moveh()
Remarks: This method will press the Move Horizontal button in the edit floater. Prototype: movev()
Remarks: This method will press the Move Vertical button in the edit floater. Prototype: rotate()
Remarks: This method will press the Rotate button in the edit floater. Prototype: scale()
Remarks: This method will press the Scale button in the edit floater. Prototype: scaleh()
Remarks: This method will press the Scale Horizontal button in the edit floater. Prototype: scalev()
Unwrap_UVW interfaces:
Remarks: This method will press the Scale Vertical button in the edit floater. Prototype: mirrorH()
Remarks: This method will press the Mirror Horizontal button in the edit floater. Prototype: mirrorV()
Remarks: This method will press the Mirror Vertical button in the edit floater. Prototype: expandSelection()
Remarks: This method will press the Expand Selection button in the edit floater. Prototype: contractSelection()
Remarks: This method will press the Contract Selection button in the edit floater. Prototype: setFalloffType falloffType
Remarks: This method will set the Falloff type. Parameters: falloffType
The falloff type; 1 for linear, 2 for sinual, 3 for fast, and 4 for slow. Prototype: getFalloffType()
Return Value: This method will return the falloff type; 1 for linear, 2 for sinual, 3 for fast, and 4 for slow. Prototype: setFalloffSpace falloffSpace
533
534
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method will set the space you want the falloff to be computed in. Parameters: falloffSpace
The falloff space; 1 for XY, the local space of the object, 2 for UV, the UVW space of the object. Prototype: 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: setFalloffDist falloffDist
Remarks: This method will set the falloff distance in the edit floater. Parameters: falloffDist
The falloff distance. Prototype: getFalloffDist()
Return Value: This method will return the falloff distance. Prototype: breakSelected()
Remarks: This method will press the Break Selected button in the edit floater. Prototype: weld()
Remarks: This method will press the Target Weld button in the edit floater. Prototype: weldSelected()
Remarks: This method will press the Weld Selected button in the edit floater. Prototype: updateMap()
Unwrap_UVW interfaces:
Remarks: This method will press the Update Map button in the edit floater. Prototype: DisplayMap displayMap
Remarks: This method sets the state of the Display Map button in the edit floater Parameters: displayMap
TRUE to toggle the Display Map button on; FALSE to toggle it off. Prototype: IsMapDisplayed()
Return Value: This method returns the state of the Display Map button in the edit floater. TRUE if it’s on; FALSE if it’s off. Prototype: setUVSpace UVSpace
Remarks: This method sets the space that you want to view the texture vertices in. Parameters: UVSpace
The texture space; 1 for UV, 2 for VW, 3 for UW. Prototype: 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: options()
Remarks: This method will press the Options button in the edit floater. Prototype: lock()
Remarks: This method will toggle the Lock Selected Vertices button in the edit floater. Prototype: hide()
535
536
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method will press the Hide button in the edit floater. Prototype: unhide()
Remarks: This method will press the Unhide button in the edit floater. Prototype: freeze()
Remarks: This method will press the Freeze button in the edit floater. Prototype: unfreeze()
Remarks: This method will press the Unfreeze button in the edit floater. Prototype: filterselected()
Remarks: This method will press the Filter Selected Faces button in the edit floater. Prototype: pan()
Remarks: This method will press the Pan button in the edit floater. Prototype: zoom()
Remarks: This method will press the Zoom button in the edit floater. Prototype: zoomRegion()
Remarks: This method will press the Zoom Region button in the edit floater. Prototype: fit()
Remarks: This method will press the Fit button in the edit floater.
Unwrap_UVW interfaces:
Prototype: fitselected()
Remarks: This method will press the Fit Selected button in the edit floater. Prototype: snap()
Remarks: This method will press the Snap button in the edit floater. Prototype: 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: setCurrentMap map
Remarks: This method sets the currently displayed map to the specified map index. Parameters: map
The index of the map in the drop down list to display. Prototype: 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: setLineColor <point3>color
Remarks: This method sets the line color of the texture vertices. Parameters: <point3>color
The color as a Point3.
537
538
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: <point3>getSelectionColor()
Return Value: This method returns the texture vertices selection color as Point3. Prototype: setSelectionColor <point3>color
Remarks: This method sets the color of selected texture vertices. Parameters: <point3>color
The color as a Point3. Prototype: 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: setRenderWidth width
Remarks: This method sets the width of the bitmap used to render to for display. Parameters: width
The width in pixels. Prototype: 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: setRenderHeight height
Remarks: This method sets the width of the bitmap used to render to for display. Parameters: height
The height in pixels. Prototype: getUseBitmapRes()
Unwrap_UVW interfaces:
Return Value: This method returns the state of the Use Bitmap Resolution, if false the bitmaps are rendered using the RenderWidth/Height values. Prototype: setUseBitmapRes 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: useRes
TRUE to toggle on; FALSE to toggle off. Prototype: getWeldThreshold()
Return Value: This method returns the weld threshold. Prototype: setWeldThreshold height
Remarks: This method sets the threshold values for welds. Parameters: height
The welding threshold/ Prototype: 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: setConstantUpdate 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: update
TRUE to toggle on; FALSE to toggle off. Prototype: getShowSelectedVertices()
539
540
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Return Value: This method returns whether the selected texture vertices are also displayed in the view port. Prototype: setShowSelectedVertices show
Remarks: This method sets whether the selected texture vertices are also displayed in the view port. Parameters: show
TRUE to toggle on; FALSE to toggle off. Prototype: 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: setMidPixelSnap 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: snap
TRUE to toggle on; FALSE to toggle off. Prototype: getMatID()
Return Value: This method returns the current material id index filter. Prototype: setMatID matid
Remarks: This method sets the material drop list to the index supplied. Parameters: matid
The material ID index to set. Prototype: numberMatIDs()
Return Value: This method returns the number of material ids in the material id filter drop down.
Unwrap_UVW interfaces:
Prototype: getSelectedVertices()
Return Value: This method returns the current selected texture vertices in the edit floater as a bit array. Prototype: selectVertices selection
Remarks: This method selects texture vertices in the edit floater dialog. Parameters: selection
The selection set as a bit array. Prototype: isVertexSelected index
Parameters: index
The index of the vertex to check. Return Value: This method returns whether a texture vertex is selected. Prototype: 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: RotateSelectedVerticesCenter angle
Remarks: This method rotates the selected vertices around their center point. Parameters: angle
The angle in radians that you want to rotate the selection by. Prototype: RotateSelectedVertices angle <point3>axis
541
542
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method rotates the selected vertices around a specified point. Parameters: 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: ScaleSelectedVerticesCenter scale dir
Remarks: This method scales the selected points around their center. Parameters: scale
The amount that you want to scale by dir
The direction; 1 for uniform scaling, 2 for X, and 3 for Y. Prototype: ScaleSelectedVertices scale dir <point3>axis
Remarks: This method scales the selected points around a specified point. Parameters: scale
The amount that you want to scale by 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 index
Parameters: time
The time at which you want to get the vertex. index
The index of the vertex. Return Value: This method returns the position of the vertex.
Unwrap_UVW interfaces:
Prototype: numberVertices()
Return Value: This method returns the number of texture vertices Prototype: moveX p
Remarks: This method sets the selected vertices x values in absolute coordinates. Parameters: p
The absolute position along the x axis Prototype: moveY p
Remarks: This method sets the selected vertices y values in absolute coordinates. Parameters: p
The absolute position along the y axis Prototype: moveZ p
Remarks: This method sets the selected vertices z values in absolute coordinates. Parameters: p
The absolute position along the s axis Prototype: getSelectedPolygons()
Return Value: This method returns the selected polygons in the view port as a bit array. Prototype: selectPolygons selection
Remarks: This method selects the polygons in the view ports. Parameters: selection
The polygons you wish to select.
543
544
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: isPolygonSelected index
Parameters: index
The index of the polygon to check. Return Value: This method returns whether a polygon is selected or not. Prototype: numberPolygons()
Return Value: This method returns the number of polygons in the object. Prototype: 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: flipHorizontal()
Remarks: This method will press the Flip Horizontal button in the edit floater. Prototype: flipVertical()
Remarks: This method will press the Flip Vertical button in the edit floater. Prototype: 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: setLockAspect aspect
Unwrap_UVW interfaces:
Remarks: This method sets the Lock Aspect Ratio value Parameters: aspect
TRUE to lock; FALSE to unlock. Prototype: 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: setMapScale 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: scale
The scaling factor for planar map. Prototype: getSelectionFromFace()
Remarks: This method takes the current polygon selection and uses it to select the texture vertices that are associated with it. Prototype: forceUpdate 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: update
This determines whether the mapping is reset on topology change. TRUE to update, otherwise FALSE. Prototype: zoomToGizmo all
545
546
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method zooms the selected or all the viewports to zoom to the current planar map gizmo. Parameters: all
This determines whether the active or all the viewports get zoomed. TRUE to zoom all viewports, FALSE to view the active viewport. Prototype: setVertexPosition time index <point3>pos
Remarks: This method sets the position of a UVW vertex at a specific time. Parameters: time
The time at what you want to set the position. index
The index of the vertex. <point3>pos
The position of the vertex in UVW space. Prototype: markAsDead 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: index
The index of the vertex to mark as dead. Prototype: numberPointsInFace index
Parameters: 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:
Prototype: getVertexIndexFromFace faceIndex ithVertex
Parameters: faceIndex
The index of the face to inspect. 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: getHandleIndexFromFace faceIndex ithVertex
Parameters: faceIndex ithVertex
The index of the face to inspect. 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: getInteriorIndexFromFace faceIndex ithVertex
Parameters: faceIndex
The index of the face to inspect. 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.
547
548
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: getVertexGeomIndexFromFace faceIndex ithVertex
Parameters: faceIndex
The index of the face to inspect. 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: getHandleGeomIndexFromFace faceIndex ithVertex
Parameters: faceIndex
The index of the face to inspect. 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: getInteriorGeomIndexFromFace faceIndex ithVertex
Parameters: faceIndex
The index of the face to inspect. 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:
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: setFaceVertex <point3>pos faceIndex ithVertex sel
Remarks: This method allows you to manipulate the position of vertex attached to a face. Basically it detaches the vertex if multiple faces share that vertex and then moves it to the position specified. So if you want to move the 3rd vertex of face 1 to .5,.5,.0 you would do setFaceVertex [.5 .5 .0] 1 3. If you don’t want the vertex broken use SetVertexSPosition. Parameters: <point3>pos
The position that you want to move a vertex to. faceIndex
The index of the face that you wish to work on. ithVertex
The ith vertex of the face that you want to change sel
Whether or not to select the vertex after it is recreated Prototype: setFaceHandle <point3>pos faceIndex ithVertex 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. faceIndex
The index of the face that you wish to work on. ithVertex
The ith vertex of the face that you want to change sel
Whether or not to select the vertex after it is recreated Prototype: setFaceInterior <point3>pos faceIndex ithVertex 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.
549
550
Chapter 1
|
What’s New in 3ds max 4 MAXScript
faceIndex
The index of the face that you wish to work on. ithVertex
The ith vertex of the face that you want to change sel
Whether or not to select the vertex after it is recreated Prototype: setFaceVertexIndex faceIndex ithVertex vertexIndex
Remarks: This method allows you to set the index of the ith vertex of a face. Parameters: faceIndex
The index of the face that you wish to work on. ithVertex
The ith vertex of the face that you want to manipulate. vertexIndex
The index into the vertex list that you want to set to Prototype: setFaceHandleIndex faceIndex ithVertex vertexIndex
Remarks: This method is identical to setFaceVertexIndex but works on handles for patches. Parameters: faceIndex
The index of the face that you wish to work on. ithVertex
The ith vertex of the face that you want to manipulate. vertexIndex
The index into the vertex list that you want to set to Prototype: setFaceInteriorIndex faceIndex ithVertex vertexIndex
Remarks: This method is identical to setFaceVertexIndex but works on interior handles for patches. Parameters: faceIndex
The index of the face that you wish to work on. ithVertex
The ith vertex of the face that you want to manipulate.
uvwMappingHeightManip interfaces:
vertexIndex
The index into the vertex list that you want to set to Prototype: updateView()
Remarks: This method forces the viewport and dialog to update. Prototype: 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: clearGizmos()
Remarks: This must be called at the beginning of the “updateGizmos” handler in order to clear the current gizmo cache.
551
552
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: addGizmoMesh <mesh>mesh flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <mesh>mesh 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: addGizmoShape gizmo flags <point3 by value>unselColor <point3 by value>selColor
Parameters: gizmo 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:
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: addGizmoMarker <enum>marker <point3 by value>position 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. 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.
553
554
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: addGizmoText <string>text <point3 by value>position flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <string>text <point3 by value>position 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: 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: updateGizmos t toolTip
Remarks: Parameters: t 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:
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: clearGizmos()
Remarks: This must be called at the beginning of the “updateGizmos” handler in order to clear the current gizmo cache. Prototype: addGizmoMesh <mesh>mesh flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <mesh>mesh 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.
555
556
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: addGizmoShape gizmo flags <point3 by value>unselColor <point3 by value>selColor
Parameters: gizmo 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: addGizmoMarker <enum>marker <point3 by value>position 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. 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:
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: addGizmoText <string>text <point3 by value>position flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <string>text <point3 by value>position 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: 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: updateGizmos t toolTip
Remarks: Parameters: t toolTip
557
558
Chapter 1
|
What’s New in 3ds max 4 MAXScript
See Also Scripted Manipulators (p. 97) Interface: manip (p. 366) radiusManip interfaces: (p. 500) ConeAngleManip - superclass: helper (p. 277) PlaneAngleManip - superclass: helper (p. 311) Scripted Plug-ins (p. 1538) sliderManipulator - superclass: helper (p. 333) sliderManipulator interfaces: (p. 520) uvwMappingHeightManip interfaces: (p. 551) uvwMappingLengthManip interfaces: (p. 555) uvwMappingUTileManip interfaces: (p. 558) uvwMappingVTileManip interfaces: (p. 562) uvwMappingWidthManip interfaces: (p. 565)
uvwMappingUTileManip interfaces: Interface: Manip Properties: .mouseState : enum : Read mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}
Methods: Prototype: clearGizmos()
Remarks: This must be called at the beginning of the “updateGizmos” handler in order to clear the current gizmo cache. Prototype: addGizmoMesh <mesh>mesh flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <mesh>mesh 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:
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: addGizmoShape gizmo flags <point3 by value>unselColor <point3 by value>selColor
Parameters: gizmo 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.
559
560
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: addGizmoMarker <enum>marker <point3 by value>position 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. 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: addGizmoText <string>text <point3 by value>position flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <string>text <point3 by value>position 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:
Prototype: 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: updateGizmos t toolTip
Remarks: Parameters: t 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)
561
562
Chapter 1
|
What’s New in 3ds max 4 MAXScript
uvwMappingVTileManip interfaces: Interface: Manip Properties: .mouseState : enum : Read mouseState enums: {#mouseIdle|#mouseDragging|#mouseOverManip}
Methods: Prototype: clearGizmos()
Remarks: This must be called at the beginning of the “updateGizmos” handler in order to clear the current gizmo cache. Prototype: addGizmoMesh <mesh>mesh flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <mesh>mesh 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: addGizmoShape gizmo flags <point3 by value>unselColor <point3 by value>selColor
Parameters: gizmo flags gizmoDontDisplay
Tells the system to not display the gizmo. It will be hit-tested, but not displayed.
uvwMappingVTileManip interfaces:
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: addGizmoMarker <enum>marker <point3 by value>position 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. 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.
563
564
Chapter 1
|
What’s New in 3ds max 4 MAXScript
gizmoUseRelativeScreenSpace
This is like gizmoUseScreenSpace, but the coordinates are specified as values from 0.0 to 1.0, and interpreted in each viewport as a percentage of the width or height of the viewport. <point3 by value>unselColor <point3 by value>selColor
Remarks: The creates a gizmo using a marker. Prototype: addGizmoText <string>text <point3 by value>position flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <string>text <point3 by value>position 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: 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: updateGizmos t toolTip
Remarks: Parameters: t toolTip
uvwMappingWidthManip interfaces:
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: clearGizmos()
Remarks: This must be called at the beginning of the “updateGizmos” handler in order to clear the current gizmo cache. Prototype: addGizmoMesh <mesh>mesh flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <mesh>mesh 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.
565
566
Chapter 1
|
What’s New in 3ds max 4 MAXScript
gizmoActiveViewportOnly
Tells the system to only display and hit-test this gizmo in the active viewport. <point3 by value>unselColor <point3 by value>selColor
Remarks: This creates a gizmo from a mesh (or geometry in MAX lingo). The mesh can be any arbitrary MAX mesh, and created with the tools in MAXScript for creating meshes. One convenient way to do this is to create an instance of a primitive and get the mesh from it. The flags can be 0, or one or more of these value. If you want more than one flag to apply, then you add the values together. Prototype: addGizmoShape gizmo flags <point3 by value>unselColor <point3 by value>selColor
Parameters: gizmo 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: addGizmoMarker <enum>marker <point3 by value>position 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:
Parameters: <enum>marker <point3 by value>position
The position is a point in 3d space, or 2d screen space. 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: addGizmoText <string>text <point3 by value>position flags <point3 by value>unselColor <point3 by value>selColor
Parameters: <string>text <point3 by value>position 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: getLocalViewRay <point2 by value>m
Parameters: <point2 by value>m
567
568
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Return Value: This function takes a mouse position and returns the ray that passes through that mouse position in the direction of the view. It is returned in the local coordinates of the node that owns the manipulator target. Prototype: updateGizmos t toolTip
Remarks: Parameters: t 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:
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
Parameters: index
The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype: getWireSubnum index
Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters: index
The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable.
569
570
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Prototype: getCoController index
Parameters: index
The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype: <string>getExprText index
Parameters: index
The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype: setExprText index <string>text
Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters: 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:
.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
Parameters: index
The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype: getWireSubnum index
Parameters: 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: getCoController index
Parameters: index
The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype: <string>getExprText index
Parameters: index
The index of the parameter.
571
572
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Return Value: This method returns the expression string of the i-th wire parameter. Prototype: setExprText index <string>text
Parameters: 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:
Prototype: <maxObject>getWireParent index
Parameters: index
The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent. Prototype: getWireSubnum index
Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters: index
The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype: getCoController index
Parameters: index
The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype: <string>getExprText index
Parameters: index
The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype: setExprText index <string>text
573
574
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters: index
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
Parameters: index
The index you wish to retrieve. Return Value: This method returns a pointer to the i-th dependent parameter parent.
Scale_Wire interfaces:
Prototype: getWireSubnum index
Remarks: This method returns the i-th dependent parameter subanim num in the animatable. Parameters: index
The index of the subanim. Return Value: This method returns the i-th dependent parameter subanim num in the animatable. Prototype: getCoController index
Parameters: index
The index of the controller. Return Value: This method returns a pointer to the i-th CoController. Prototype: <string>getExprText index
Parameters: index
The index of the parameter. Return Value: This method returns the expression string of the i-th wire parameter. Prototype: setExprText index <string>text
Remarks: This method allows you to set the expression string of the i-th wire parameter. Parameters: index
The index of the parameter <string>text
The expression you wish to set.
See Also In The MAXSDK Help File Class IBaseWireControl
575
576
Chapter 1
|
What’s New in 3ds max 4 MAXScript
Chapter 2:
Learning MAXScript
Welcome to Learning MAXScript. This introductory reference helps you get started using MAXScript, the scripting language that is built into 3ds max. Learning MAXScript can be used as an introductory reference. However, it is most useful if read straight through as a tutorial. You can follow the examples in this reference by using drag-and-drop or copy-and-paste to bring the code from this document into the MAXScript Listener. You can also type in your own text and start experimenting with MAXScript as you learn it.
Getting Started Accessing MAXScript (p. 579) Source Code Layout (p. 580) Entering Information into MAXScript (p. 582) Assigning Variables (p. 585) Mathematical Operations in MAXScript (p. 588)
Working with 3ds max Objects Drawing a Box with MAXScript (p. 591) Modifying the Box (p. 593) Applying Standard Transformations (p. 598) More Box Transformations (p. 603)
Creating Your Own Scripts Controlling Program Flow in Scripts (p. 607) Defining Custom Functions (p. 614) Structure Definitions (p. 618) 3ds max Commands in MAXScript (p. 620)
578
Chapter 2
|
Learning MAXScript
Where to Go From Here Saving your Commands in a Script File (p. 621) Loading and Running Your Script File (p. 621) Loading Other Scripts (p. 623) Learning MAXScript by Walking Through a Script (p. 623) Learning MAXScript with the Macro Recorder (p. 624)
Some Advanced Topics Include: Action Manager (p. 9) ActiveX Controls in MAXScript Rollouts (p. 10) Asset Browser enhancements (p. 22) Curve Control (p. 170) Customize The Order of Rollup Pages (p. 185) General Event Callback Mechanism (p. 29) iDrop - drag and drop (p. 62) Interfaces (p. 67) Menu Manager (p. 75) Network Render Interface (p. 82) Parameter Wiring (p. 85) Quad Menu (p. 90) Scripted Custom Attributes (p. 45) Scripted Manipulators (p. 97) Visual MAXScript (p. 117) Zip-file Script Packages (p. 122)
Accessing MAXScript
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:
579
580
Chapter 2
|
Learning MAXScript
The MAXScript Listener window is an interactive interpreter for the MAXScript language and works similarly to a DOS command prompt window. Enter MAXScript commands in this window, and press ENTER to execute them immediately. Only one instance of the MAXScript Listener window can be open at a time. The Listener is a resizable, modeless window. You can switch between it and the software as you work. If you close the Listener window and then reopen it, any text that was in the window before it was closed reappears. The Listener is divided into two panes. The top (pink) pane is the Macro Recorder pane; the bottom (white) pane is the output pane. The Macro Recorder plane is hidden when the Listener is opened; drag the splitter bar down to open it. When the Macro Recorder is enabled, every recordable command is displayed in the Macro Recorder pane. The output of results from scripts is displayed in the output pane. The output of code executed in the Macro Recorder pane is always directed to the output pane to prevent cluttering the recordings. Both panes allow you to cut-and-paste, drag-and-drop, edit, select, and execute code. You can resize the panes by dragging on the split bar between them. The left end of the status bar contains a resizable Mini Listener.
If the Mini Listener is not visible, drag on the vertical split bar at the left edge of the status panel to reveal this feature. The Mini Listener panes act as single-line sliding windows for the current line in corresponding Listener panes. The Mini Listener panes always show what you are typing or where the cursor is placed in the Listener panes. Conversely, anything you enter into a Mini Listener pane is entered into the corresponding Listener pane at the current cursor position. To install Listener into a viewport: 1.
Right-click the viewport label.
2.
Choose Extended.
3.
Choose MAXScript Listener.
Source Code Layout The layout rules for MAXScript code are unlike those of most programming languages. MAXScript gives you the advantage of freeform languages, such as C and C++, without the need for extensive punctuation. MAXScript lets you break statements and expressions across lines wherever you want. The line break can be in the middle of an expression. MAXScript reads your code until the end of each line and determines whether it has a complete expression. If it does not, it continues to read subsequent lines until it finds the rest of the expression.
Source Code Layout
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:
581
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
When MAXScript performs operations involving both float and integer-type numbers however, it treats the integer as a float number. For example: 3 + 4.0 will return 7.0.
Entering Strings in MAXScript MAXScript is an expression-based language. All of its constructs yield a value. Strings are MAXScript constructs, and they are entered inside quotation marks. The command output for a string, meaning the value a string yields in MAXScript, is the string itself. With the MAXScript Listener window open, say hello to MAXScript: 1.
At the prompt, type Hello and press ENTER. MAXScript answers with undefined. This is called command output, which always appears in blue. The reason for this specific output is that MAXScript doesn’t know the word Hello. It is not defined in the language and therefore MAXScript cannot determine what to do with it.
583
584
Chapter 2
2.
|
Learning MAXScript
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
#( <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.
585
586
Chapter 2
|
Learning MAXScript
To assign a string to a variable: 1.
At the Listener prompt, enter the following command: mystring = “This is my string.”
MAXScript returns the value of the string variable:
2.
You can now refer to this string variable by entering the variable’s name. Enter mystring. MAXScript again returns the value of the string variable:
This is faster than entering the string again. MAXScript remembers this string for as long as your MAXScript session is open, or until you change the variable’s value.
Assigning Variables
To assign a new value to an existing variable: 1.
Enter mystring = “This is not your string.” MAXScript now displays the new value of mystring:
2.
When you refer to mystring now, MAXScript uses the new value. Enter mystring. MAXScript now displays the new variable value:
Notice that MAXScript doesn’t distinguish between lowercase and uppercase variable names because MAXScript names are not case-sensitive.
587
588
Chapter 2
|
Learning MAXScript
Mathematical Operations in MAXScript Besides strings, you can enter other types of data into MAXScript. MAXScript not only recognizes numeric characters as numbers, it can also perform mathematical operations with them. As with strings, if you just enter a number by itself, MAXScript echoes it back to you; it evaluates the number and displays its value. Mathematical operations are more interesting.
Basic Mathematical Operations MAXScript has many built-in functions that let you use MAXScript as a calculator. Enter 36.5 * 2, for example, to see what a certain dimension needs to be if you want to double it.
MAXScript returns the result of the calculation. This is useful for quick calculations where loading an external calculator program doesn’t seem worth the trouble. MAXScript also recognizes several mathematical constants. Enter pi.
MAXScript knows the value of pi and returns it.
Mathematical Operations in MAXScript
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.
589
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
where is any float or integer. Each time you change the seed value, MAXScript generates new ‘random’ numbers.
Drawing a Box with MAXScript
Incrementing Another useful mathematical operation that MAXScript provides is incrementing. This is a shorthand form of assignment that can be used to modify a value in place, as shown in the following long form examples: x = x + 1
There are assignment operators corresponding to the four math operations (+,-,*, and /) that apply the operation to the assignment’s destination with the result. Their syntax is: <destination> <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 MAXScript’s useful capabilities; however, nothing that is visible in the interface. MAXScript is also useful for working with regular objects, such as boxes or cylinders. You can draw a box in MAXScript just by entering the box() command: box()
This creates a box with the default parameters. It is generally better practice to assign an object to a variable, so you can later refer to it by name and manipulate it using that name: mybox = box()
When you use MAXScript to create an object without specifying any parameters, it is important to use empty parentheses, “()”. This tells MAXScript to use the default parameters for the object. If you want to specify any of the parameters during creation, such as the size or location of the object, you do not need parentheses. For example: mybox = box length:20 width:20 height:20
591
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
MAXScript also draws the box in the viewports, as shown in this perspective viewport:
Notice that you can use Undo (as you can with most MAXScript creation and modification commands) to remove the box from the scene.
Modifying the Box In the previous lesson, you created a box by assigning it to a named variable. Because you used a variable for the box, you can now access all of the box’s properties easily. The variable name mybox is the handle to your box. To access the properties of the handle, append a “.” (period), and then the property name. For example, mybox.height can be read as “the height of mybox”. All 3ds max objects have creation parameters such as width, length, and height for boxes, or radius for circles. These objects also have transformation properties, such as scale, rotation, or position, and general properties like name, wireColor, etc. To change any of these properties, you can set the property to a new value.
593
594
Chapter 2
|
Learning MAXScript
To change the object name of the box: If you don’t like the default object name Box01, you can change the name property of the box: Enter mybox.name = “BlueBox” in the Listener window and the software renames the box. You can see the new name in the Name edit box when you go to the Modify panel:
To change the color of the box: The software assigns the color of objects randomly at creation time. Therefore, the color of your box is not necessarily blue. In this case, BlueBox wouldn’t be an appropriate name for your box. However, you can change the color of your box to match the name: Enter mybox.wireColor = blue and watch the box in your viewports turn blue. You may have to select the box again to reflect the new color in the color swatch next to the object name in the Modify panel. The color blue is a predefined color constant in MAXScript and its RGB value is defined as (0,0,255). The other predefined color variables are red, green, white, black, orange, yellow, and brown. Instead of using a predefined color, you can assign a color with different RGB values, such as: mybox.wireColor = (color 255 0 255)
Notice the special syntax for entering specific color values. The example shown would change the box to magenta. If you entered this command, click
Undo to change the box back to blue.
For more information on colors, see the Color Values (p. 729) topic in the MAXScript reference. To change the position of the box: You can change the position of the box by changing the box’s position property. You refer to the position property for this example box with mybox.pos. The position is expressed as the X, Y, Z coordinate. For example [0,-75,0]. Bring the box forward by entering mybox.pos = [0,-75,0] and watch the box jump forward in the perspective view:
Modifying the Box
Click
Undo to move the box back to the origin.
To change the size of the box: To make the box bigger, you can use the scale property of the box: Enter mybox.scale = [1.5,1.5,1.5] to see the box resized to 1.5 times its original size. The scale property requires a scaling factor for each of the X, Y, and Z axes, or, in this case, the width, length and height of the box. You don’t have to use the same value for each axis unless you want to resize the box uniformly.
595
596
Chapter 2
|
Learning MAXScript
If you want to change the scale to affect only the height and the width, but not the length, use the following example: mybox.scale = [1,3,2]
When you scale your original [20,20,20] box by any factor, the box’s parameters are still 20 for width, 20 for length, and 20 for height. You can see this when you open the Modify panel. The box parameters are not changed by the scale transformation:
Modifying the Box
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 box’s height. Using the scale property to transform the height of the box does not. Again, the effect of using either method is visually the same, but when you want to maintain the original creation parameters of an object, so that you can alter them even after a number of different transformations, you must use the scale property to manipulate the size of the box, not the individual creation properties.
If you entered the last two commands, click 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:
597
598
Chapter 2
|
Learning MAXScript
Notice that you can use the “*” character as a wildcard to see all box parameters. If you had entered showClass “box*.*,” MAXScript would have listed the Box and the BoxGizmo classes. The other inspector function is showProperties(). To learn more about these functions, search for the “Class and Object Inspector Functions and Properties” topic in the MAXScript Reference.
Applying Standard Transformations Now that you know how to create and modify the basic properties of a box, you need to learn how to apply the standard transformations (move, scale, and rotate) to it. It is possible to designate position, size, and orientation when the box is created; however, you can also carry out these operations after you have created your object, just as you would in 3ds max. To move the box: Moving an object in MAXScript is very simple: move name_obj [<x,y,z>]
where name_obj is the name of the object you want to move and <x,y,z> is the amount you want it to move. It is important to note that you are not moving the object to <x,y,z>, but by the amounts <x,y,z>. Therefore, if you apply the move function more than once, the object continues to move. This is also true for the scale and rotate transforms. This is in contrast to setting a property of an object. If you set the object position, scale, and rotation properties several times, the object won’t change, assuming that you assign the same value each time.
Applying Standard Transformations
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]
will move your box 30 units along the X-axis.
Undo three times to move the box back to its
599
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
To scale the box: Scaling is performed in a similar manner: scale name_obj [<x,y,z]
where name_obj is the name of the object and <x,y,z> is a 3D coordinate that corresponds to the amount you would like to scale the object along the X, Y, and Z-axis, respectively. Again, the scale transformation is different from the scale object property. Setting the object’s scale property (name_obj.scale = …) repeatedly with the same values will only scale the object the first time, but applying the scale transformation repeatedly will continue to scale the object. To rotate the box: The rotate transformation is not as simple as the move and rotate transforms. In fact, there are three ways to rotate an object in MAXScript: •
Euler Angles
•
Quaternions
•
Angleaxis
This introduction will only consider Euler Angles. If you would like further information on any of these transformations, see the MAXScript reference. To apply a rotation transform in MAXScript, you must first define the rotation as a sort of rotation object, and then apply the rotation object to the object you want to rotate. The rotation object is defined in the following way: rot_obj = eulerangles x y z
where rot_obj can be any name and x, y, and z represent the amount you want to rotate your object (in degrees) around the X, Y, and Z-axes, respectively. For example: rot_box = eulerangles 0 30 0
creates an object called rot_box, which will rotate an object around the Y-axis by 30 degrees. This rotation can be applied to your box in the following way: rotate mybox rot_box
601
602
Chapter 2
|
Learning MAXScript
In fact, this rotation could be applied to any object by writing the same line as above and replacing mybox with the name of the object you want to rotate.
If you entered the above commands, click
Undo to move the box back to its original position.
If you designate angles for more than one axis: rot_box2 = eulerangles 30 45 60
The rotation is applied to an object, with the X-axis rotation occurring first, followed by the Y-axis rotation, and then the Z-axis rotation. Note: Moving, scaling, or rotating objects, or setting transform-related properties within a coordinate system, will operate in relation to the current reference coordinate system (i.e., Local, World, Screen), which is displayed in the main 3ds max toolbar. If you want to perform these transformations in another coordinate system, see the Coordsys (p. 685) topic in the MAXScript reference.
More Box Transformations
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)
603
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
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
605
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
To animate your box: MAXScript has several syntax forms that mirror the main UI tools, such as the Animate button, the time slider, and the active coordinate system. In the following example, you turn on the Animate button, set the slider to several different values, and adjust the properties of your box, just as you would do using the software’s UI: animate on ( at time 0 (mybox.pos = [-100, 0, 0]; mybox.scale = [1, 1, 0.25]) at time 100 (mybox.pos = [100, 0, 0]; mybox.scale = [1, 1, 3]) )
Drag the slider around, and you will see that MAXScript has animated the box, and placed keyframes at 0 and 100. When you use MAXScript to animate objects, the actual Animate button in the UI does not come on, nor does the time slider move; these things happen within MAXScript. In this example, the time was given as a simple number. If no unit is specified, MAXScript interprets this as a frame number. You can also use one of the various time literals in the following manner: 2.5s 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.
607
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 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
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
613
614
Chapter 2
|
Learning MAXScript
Defining Custom Functions MAXScript’s built-in functions are very powerful. They provide access to objects, allowing you to read and set their properties. However, scripting in 3ds max normally entails going beyond simple object creation. Fortunately, MAXScript allows you to make your own functions, giving you the ability to streamline and customize your work.
Local and Global Variables In MAXScript, there are two classes of variables that you can create: “local” and “global” variables. When a variable is global, it means that the variable can be used anywhere in the program. The only place you cannot use a global variable is before you have defined it. For example, the following lines will produce an error: sphere radius:rad global rad = 10
The variable “rad” does not exist until it has been defined. The following is an acceptable form of the previous lines: global rad = 10 sphere radius:rad
Now that “rad” has been defined, MAXScript was able to use it in the definition of a sphere. In fact, since “rad” is a global variable, it can be used throughout the rest of the script. There are several global variables that can be used without defining them first. They are the system global variables, which have already been created and assigned to a default value. Most of these variables can be reassigned to different values. For more information on the system global variables, see the 3ds max System Globals (p. 630) topic in the MAXScript reference. Unlike global variables, local variables can be used only within the block in which they are defined. A block is a grouping of MAXScript code, such as the statements within loops and conditional statements. Here is an example of a for loop: for i = 1 to 3 do ( local rad = 10 s = sphere() s.pos.x = i * 10 s.radius = rad )
Local variables can only exist within a block. For this reason, they must be created in a block. If you try to define a local variable from the top level of MAXScript, you will receive an error message. In the previous example, you defined a local variable named “rad”. This variable is active only within the parentheses inside the for loop; if you attempt to use the variable “rad” elsewhere, you will get an error. Although rad is initialized to a specific value, this is not necessary. When you define variables using a “local” or “global” identifier, you can do so without assigning an initial value. The name of the variable will be recognized. However, the software will not know the type of the variable (name,
Defining Custom Functions
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.
615
616
Chapter 2
|
Learning MAXScript
Defining Custom Functions In MAXScript, you can use functions to perform almost any of the software’s operations. Start with a simple function definition that subtracts two variables:
MAXScript returns subtract() to let you know that it has defined the function, subtract. The definition contains the keyword function (you can also use the word fn in place of function), followed by the name of the function (subtract), followed by the list of variables (x and y). The equal sign signifies the start of the body of the function. The body is the series of statements that the function executes. Even if there is only one statement, the body of the function must be in parentheses. Note: Any variables created in the body of a function are local variables unless otherwise specified. Once a function has been defined, it can be used anywhere throughout the script. Therefore, it is useful to place function definitions at the beginning of your scripts. In order to use a function, you simply enter the function name and the values for its variables:
Defining Custom Functions
This example uses what are known as positional arguments. When you call the function, you must supply both arguments, and you must supply them in the proper order for the function to execute properly. The second type of arguments you can use are keyword arguments. This is what is used for all of the object constructors in MAXScript. The function definition is the same, with the exception of declaring the keyword arguments, or default values for the variables in a function. The following example determines whether a number is positive, negative, or equal to zero: function sign val:0 = ( if val == 0 then messagebox (”Equal to 0”) else if val > 0 then messagebox (”Greater than 0”) else messagebox (”Less than 0”) )
The messagebox command causes a message box to pop up on the screen, displaying the argument in the parentheses that follow the command. In this example, a parameter called val has been declared in the function definition. The value after the colon is the parameter’s default value. When the function definition contains parameters like this, they are optional in the function call. If you enter sign(), without specifying any parameters in the function call, MAXScript uses the default value:
The “Equal to 0” message box appears, since the default value for val (0) will be used. However, if you do define val: sign val:-5
the “Less than 0” message appears. You can include as many keyword arguments in a function as you need, and they can be entered in any order when calling the function. This is useful when you consider functions such as object-creation functions, where the new object might have 20 or 30
617
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: [ = <expr> ] – name and optional initial value
Create a new structure, called person: Struct person (name, height, age, sex)
Structure Definitions
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.
619
620
Chapter 2
|
Learning MAXScript
3ds max Commands in MAXScript In addition to controlling modeling and animation, MAXScript scripts can invoke 3ds max menu and toolbar commands. You do this using the “max” keyword. For example: max file open max unhide all max quick render
The keyword max is followed by one or more words that describe the command. The available commands can be displayed by using the “?” character in a partial max command. For example: max time ? -- shows all the time-related commands max sel ? -- shows all the commands with ‘sel’ in them as a substring max ? -- shows all the commands (there are a lot)
Below is a partial list of the available commands to give you an idea of the type of 3ds max commands you can perform with MAXScript. For a complete list, see the 3ds max Commands (p. 1630) topic in the MAXScript reference. 3ds max Command Name
Command Description
max ?
Displays all max commands in the Listener
max delete
Deletes selected objects or sub-objects
max file new
Displays the new file dialog
max file open
Displays the open file dialog
max file save
Activates File/Save
max move
Activates Select and Move mode
max properties
Displays the Object Properties Dialog
max quick render
Performs a quick render
max redo
Performs a redo operation
max reset file
Activates File/Reset
max rotate
Activates Select And Rotate mode
max select
Activates select mode
max select all
Selects all objects
max time end
Sets the time slider to the end frame (Go to End)
max time start
Sets the time slider to the start frame (Go to Start)
max undo
Performs an undo operation
max unfreeze all
Unfreezes all objects
max unhide all
Unhides all objects
max vpt front
Sets the active viewport to Front
max zoomext sel
Activates Zoom Extents Selected
Saving your Commands in a Script File
Saving your Commands in a Script File So far, you have entered your commands into the Listener window. If you had to stop at some point, and couldn’t finish some code in one session, you would have to start all over, entering the commands you already used in the previous session. MAXScript allows you to store your commands in an external file that you can load and run. The general procedure for storing commands in a script file is to click the New Script button in the MAXScript rollout, and type commands in the Script Editor window that opens. Because you have already entered a lot of commands in the Listener window, you can copy them from that window into the Script Editor window. To copy tutorial commands from the Listener into the script editor window: 1.
Click the New Script button in the MAXScript rollout on the Display panel. The Script Editor window appears with the title “Untitled - MAXScript”.
2.
Position the Script Editor window side-by-side or below the Listener window so that you can copy and paste text between the two windows.
3.
In the Listener window, select the black command line from the Drawing a Box with MAXScript (p. 591) topic (mybox = box length:20 width:20 height:20)
4.
Press CTRL+C on your keyboard to copy the text to the Clipboard.
5.
Click the Script Editor window to place the cursor in it, and press CTRL+V on your keyboard to paste the command into the Script Editor window.
6.
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.
Loading and Running your Script File You can open a script file for editing, or you can include it in another script to run automatically when that script runs. To run the script you just saved: 1.
Reset 3ds max.
2.
Go to the Utilities panel, turn on MAXScript, and in the MAXScript rollout, click the Run Script button. The Choose Editor File dialog appears.
621
622
Chapter 2
3.
|
Learning MAXScript
Select the box_draw.ms file, and click Open. MAXScript immediately carries out the command that is contained in the script file and places a box in the scene.
To open a script file for editing: If you want to edit your script later to add more commands to it, you need to open it: 1.
In the MAXScript rollout, click the Open Script button
2.
Select the script you want to edit and click Open. The Script Editor window opens, showing the text of your script. You can now edit your commands or add new ones, as you would edit any other text file. Save the script file to keep your changes.
To evaluate the commands in your script: If you enter any commands in the Script Editor window manually (not by copying and pasting from the Listener window), you can test the validity of all commands: 1.
If your Listener window isn’t open, click the Open Listener button in the MAXScript rollout.
2.
In the Script Editor window, choose File > Evaluate All. MAXScript evaluates the commands in your script file. It sends any feedback to the Listener window. It also sends each valid command to the user interface as if you had run the script. If your script contains any syntax errors, MAXScript reports those in the Listener window in red.
To include your script in another script: If you want to write a script for each tutorial (for example one for drawing a box, one for modifying the box, and another one for transforming it), you could then use those three scripts in another one that contains all the box operations. Assuming you had created the scripts box_draw.ms, box_mod.ms, and box_trans.ms, you could then include them in a new script, box_all.ms. The text for box_all.ms would be as follows: include “box_draw.ms” include “box_mod.ms” include “box_trans.ms”
To reset 3ds max before running scripts: If you want to start with a new scene before running any scripts, you need to reset the software: 1.
Choose File > Reset.
2.
Answer the Yes-No prompt to either save or discard the changes to your scene.
3.
Open and run the script you want. Note that resetting the software closes all MAXScript windows so that you can’t copy any more commands from the Listener window. You can always copy commands from the help file, as described below.
Loading Other Scripts
To copy commands from the help file: You can copy commands from the tutorial help file: 1.
In the Help window, highlight the command you want to copy.
2.
Right-click the highlighted text and select Copy from the pop-up menu.
3.
In the Script Editor window, choose the Edit > Paste menu to paste the command into the current script file, or press CTRL+V on your keyboard.
Loading Other Scripts The software comes with many scripts pre-installed in the scripts directory. Or, you might find MAXScript files on the World Wide Web that other MAXScript users have posted. To load any of those script files isn’t different from loading your own scripts: To load a script: If you want to study a script before running it, open it first: 1.
In the MAXScript rollout, click the Open Script button.
2.
Select the script you want to study and click Open. The Script Editor window opens. It shows the text of the script you selected. You can now read the commands and see if you get an understanding of what the script might do when you run it.
To run a script: 1.
In the MAXScript rollout, click the Run Script button. The Choose Editor File dialog appears.
2.
Select the script file you want to run, and click Open. MAXScript immediately carries out the commands that are contained in the script file.
Learning MAXScript by Walking Through a Script You can learn a lot about MAXScript by just using several different script files. The best method to learn MAXScript commands and command syntax is to step through a script and watch the responses in the Listener window and in the user interface. You can “walk” through a script by loading a script into the Script Editor window and executing one command line or a command block at a time: To step through a script: 1.
Open a script into the Script Editor window.
2.
Place the cursor into the first command line and press ENTER on the number pad of your keyboard. The Number Pad <ENTER> key is a shortcut for executing the current command line or the selected block of code.
623
624
Chapter 2
|
Learning MAXScript
MAXScript executes the current command line and reflects the outcome in the Listener window and, if appropriate, in the user interface. 3.
Move the cursor to the next command line or select the next block of code from the script. Press the number pad ENTER key again, and so on.
From here on, step through other scripts and take note of the effects. Most of the script files included with 3ds max are very well commented and include a description about the scripts purpose. For more information about using script files, see the Running Scripts (p. xlix) topic in the MAXScript Reference.
Learning MAXScript with the Macro Recorder Another useful tool for learning MAXScript is the Macro Recorder. If you want to learn how to perform a task in MAXScript, you can use the Macro Recorder to get started. The Macro Recorder captures many of the actions performed by the user, and generates the MAXScript commands that correspond to those actions. The Macro Recorder output is displayed in the top pane of the MAXScript Listener window. This pane has a pink background. The Macro Recorder has several filtering options that control what types of user actions are recorded, whether the generated script commands contain explicit object references or are selection-relative, and whether the generated MAXScript commands contain explicit or relative transforms and coordinates. These options can be set using the Macro Recorder menu in the Listener window. Many user actions generate Macro Recorder output, but not all of them. In general, most of the buttons on the Menu Bar, toolbars, Status Bar, Create panel, and Modify panel generate Macro Recorder output. If the button invokes a secondary dialog, changing setting or performing actions in the secondary dialog typically will not generate Macro Recorder output. In the Create and Modify panels, Macro Recorder output is generated if MAXScript can create the object or modifier. This makes the Macro Recorder a useful too for learning MAXScript, as you can perform tasks in the UI and simultaneously see how to perform these same tasks with MAXScript. For further documentation on the Macro Recorder, see the Macro Recorder (p. l) topic in the MAXScript reference.
The Scripts Included with 3ds max You can open each script in the scripts directory and study what each script does by stepping through them. The script files are ASCII files that you can open with any ASCII editor for viewing or printing. Most script files are very well commented and include a description of the script’s purpose. Of particular interest is demo.ms, which you can step through to explore various aspects of MAXScript’s capabilities.
Chapter 3:
Reserved Keywords, Symbols, Punctuation and Variables
As with any computer language, MAXScript features a number of lexical tokens, corresponding to the words and numbers and punctuation that are the building blocks of English. Tokens fall into several categories: •
Reserved ‘keywords’ that typically introduce clauses in the language, such as if, for, and function.
•
Punctuation marks and symbols that separate or group clauses or specify math operators, etc.
•
Reserved global variables containing 3ds max system global variables and MAXScript predefined global variables.
The following list of topics contains information about the above types of tokens and their syntax: Language Reserved Keywords (p. 625) Punctuation and Symbols (p. 627) Reserved Global Variables (p. 628)
Language Reserved Keywords Keywords begin or separate portions of MAXScript commands. For example, one form of the if expression is: if <expr> then <expr> [ else <expr> ]
In order for MAXScript to easily identify the various portions of the if expression, the words if, then and else are reserved keywords and can not be used as variable names or identifiers. So, for example, you cannot declare a variable or function called if. The following table lists all MAXScript reserved keywords. Click a reserved keyword to go to a description of its usage. In some cases, a keyword may have more additional meanings, depending on its context. This information is also summarized in the MAXScript Grammar (p. 1681) topic.
626
Chapter 3
|
Reserved Keywords, Symbols, Punctuation and Variables
Reserved Keywords about
about
and
Logical_Expressions
animate
animate
as
value_common_properties_operators_and_methods
at
at_time
by
For_Loop
case
Case_Expression
catch
Try_Expression
collect
For_Loop
continue
Skipping_Loop_Iterations
coordsys
coordsys
do
While_and_Do_Loops
else
If_Expression
exitv
Loop_Exit
fn
Creating_Functions
for
For_Loop
from function
Creating_Functions
global
Scope_of_Variables
if
If_Expression
in
For_Loop
local
Scope_of_Variables
macroscript
Defining_Macro_Scripts
mapped
Creating_Functions
max
MAX_Commands
not
Logical_Expressions
of
Case_Expression
off
Predefined_Globals
on
Rollout_Clauses
or
Logical_Expressions
parameters
Scripted_Plugin_Clauses
persistent
Persistent_Global_Variables
plugin
Scripted_Plugins
rcmenu
Scripted_Right_Click_Menus
return
The_Return_Expression
rollout
Utility_Clauses
Punctuation and Symbols
set
Sticky_Contexts
struct
Structure_Definition
then
If_Expression
throw
Try_Expression
to
For_Loop
tool
Scripted_Mouse_Tools
try
Try_Expression
undo
undo
utility
Scripted_Utilities
when
Change_Handlers_and_When_Constructs
where
For_Loop
while
While_and_Do_Loops
with
Loop_Exit
The from keyword is reserved, but not currently used.
Punctuation and Symbols The following table shows all MAXScript punctuation marks and symbols. Their meanings are described in the definitions of the various language constructs that use them and also in the MAXScript Grammar (p. 1681) topic. Some of these punctuation marks and symbols offer more information. Click a linked punctuation mark or symbol to go to a description of its usage. In some cases, a keyword may have more additional meanings, depending on its context. (
Block_Expressions
)
Block_Expressions
+
Math_Expressions
*
Math_Expressions
-
Math_Expressions
/
Math_Expressions
^
Math_Expressions
+=
Math_Assignment
-=
Math_Assignment
*=
Math_Assignment
/=
Math_Assignment
--
Source_Code_Layout_and_Continuation_Lines
=
Math_Assignment
;
Source_Code_Layout_and_Continuation_Lines
<eol>
627
628
Chapter 3
|
Reserved Keywords, Symbols, Punctuation and Variables
, [
2D_and_3D_Point_Literals
]
2D_and_3D_Point_Literals
:
Function_Calls
‘
Names
& . {
BitArray_Values
}
BitArray_Values
#
Array_Values
==
Logical_Expressions
!=
Logical_Expressions
Logical_Expressions
>=
Logical_Expressions
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 . autoBackup.time
Get/set the time in minutes between auto backup as a . 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
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).
631
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
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).
633
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
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.
635
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
--------
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
sysInfo.DesktopSize
A read only variable to get the desktop size in pixels as a <point2> value. sysInfo.DesktopBPP
A read only variable to get the desktop color depth in bits per pixel as an value.
3ds max System Globals
sysInfo.MAXPriority
Get/set the 3ds max process priority as a 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 . Valid unit display types are: #Generic #Metric #US #custom units.MetricType
Get/set the current metric unit display type as a . Valid metric unit display types are: #Millimeters #Centimeters #Meters #Kilometers
637
638
Chapter 3
|
Reserved Keywords, Symbols, Punctuation and Variables
units.USType
Get/set the current US standard unit display type as a . 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 . 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 units.CustomUnit
Get/set the current custom unit type as a . Valid custom unit display types are: units.SystemScale
Get/set the current system unit scale value as a . 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 . 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
useEnvironmentMap
Lets you get and set the global rendering environment (Rendering > Environment) Use Map value. A Boolean value – true if Use Map is on, false if off. See Working with 3ds max Atmospherics (p. 1345). videoPostTracks
Contains a MAXTVNode value that defines the top-level Video Post Track View node. This variable is read-only. See Track View Nodes (p. 1382). This variable contains the value undefined in 3D Studio VIZ. viewport.activeViewport
Lets you get and set the index of the active viewport. See Accessing Active Viewport Info, Type, and Transforms (p. 1581). viewport.numViews
Contains the number of viewports in the current viewport layout. This variable is read-only. See Accessing Active Viewport Info, Type, and Transforms (p. 1581). The following 3ds max system global variables are specific to 3ds max’s default scanline A-Buffer renderer. These variables return undefined if the current renderer is not 3ds max’s default scanline A-Buffer renderer. scanlineRender.antiAliasFilter
Lets you get and set the anti-aliasing filter. For a list of all of the anti-aliasing filters you can say: showClass “*:filter*”
For example: scanlineRender.antiAliasFilter = quadratic()
The anti-aliasing filters and their parameters are described in the 3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters (p. 1614) topic. scanlineRender.antiAliasFilterSize
Contains a float value that defines the anti-aliasing filter size. scanlineRender.enablePixelSampler
Lets you enables and disables global super sampling. A Boolean value - true if Disable all Samplers is off, false if on.
639
640
Chapter 3
|
Reserved Keywords, Symbols, Punctuation and Variables
MAXScript System Globals These globals give access to the MAXScript system state. You can access and assign to them as noted. currentTime
Contains a Time value that defines the current evaluation time in frames as set by the at time context expression currently in force. This is useful in functions that need to do time-relative computations that may be called from code that sets working animation time. If there is no at time context in force, currentTime contains the current user interface slider time, unless a render is in progress. If a render is being performed, currentTime contains the frame being rendered. This variable is read-only. editorFont
Lets you get and set a String value that defines the font name for script Editor windows. Setting this variable effects all currently open and future script Editor and MAXScript Listener windows. This variable contains the corresponding value set in the MAXScript page of Customize > Preferences. editorFontSize
Lets you get and set an Integer value defining the font point size for script Editor. Setting this variable effects all currently open and future script Editor and MAXScript Listener windows. This variable contains the corresponding value set in the MAXScript page of Customize > Preferences. editorTabWidth
Lets you get and set an Integer value defining the tab width (in characters) for script Editor windows. Setting this variable effects all currently open and future script Editor windows. This variable contains the corresponding value set in the MAXScript page of Customize > Preferences. escapeEnable
Lets you get and set a Boolean value defining whether ESC key interrupt detection is on or off. Setting enableEscape to false turns ESC key interrupt detection off, setting it to true turns it on again. This variable is useful when used in conjunction with a Progress Bar. You can set enableEscape to false when you don’t want the user to be able to interrupt a script running a long computation and you have set up a progress bar with its own Cancel button. See Progress Bar Display (p. 1578). heapFree
Contains an Integer value defining the current amount of free memory in the MAXScript heap. This value will vary constantly depending on where MAXScript is in its collection regime. This variable is read-only.
MAXScript System Globals
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.
641
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, , is: <destination> = <expr>
where <destination> can be one of: <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 , 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>: [ <expr> ]
-- an indexed element
or a <property>: .
-- 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 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
Accessors are evaluated left-to-right. The first example evaluates the i‘th element of my_things, which is presumably a nested array or an array of strings, before yielding the j‘th element of that element. The second example retrieves an object from an array of my_objects, then its target, then the position of the target (a 3D point), and finally the x coordinate of that point. An can also be a block-expression, allowing you to compute the target object to be accessed. For example: (instance myNode).pos=myNode.parent.pos
Create an instance of the node whose value is stored in variable myNode, and set its position to the position of the myNode‘s parent object. (find_table “foo”)[n - 2] = “fred”
Call function find_table with a parameter value of “foo”. The return value from the function is presumably an array. Set element n-2 of this array to the value “fred”. The named properties defined for the MAXScript values and classes are documented with the value and class descriptions. Order of Evaluation In an assignment, <expr> is evaluated before <destination>, as can be seen in the following example: Script: a=#() -- create an empty array to play with a[(print “in <destination>“;1)]=(print “in <expr>“;10)
Output: #() “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)
645
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, , is as follows: ( local | global ) <decl> { , <decl> }
where <decl> is defined as: [ = <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
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
647
648
Chapter 4
|
Variables - Assignment and Scope
in scope context level 2, and their scope is only scope context level 2. The scope of variable k varies depending on whether this script has been run before. The first time the script is run, variable k is first defined at line 5, and its scope is scope context level 2. In line 11, variable k is used again. Because the variable k defined at line 5 is no longer in scope, a new variable k is defined whose scope is global. The second time you run the script, at line 5 MAXScript detects variable k already exists and uses it. So the first time you run the script line 11 will print undefined, and the second time you run the script line 11 will print the last value calculated at line 5. Note: The scope of the variable used as a for loop counter (variable i in the above script) is a special case. The for loop counter variable’s scope is always the scope context created for the for loop. This is true even if the for loop counter variable’s name has already been implicitly or explicitly declared at a higher scope context level. When you explicitly declare a local variable, you can reuse the same name as a variable at a higher scope context level. If you do this, the newly declared local variable hides the outer variables with the same name. Any reference to that variable name later in the local variable’s scope refers to the new local variable. At the end of the local variable’s scope, the next outer variable becomes visible again. This visibility scheme is called lexical scoping. An example of lexical scoping is shown in the following script. Script: global foo = 23, x = 20
-- explicit declaration of foo and x, -- scope is global y = 10 -- implicit declaration of y, -- scope is global format “context level global: foo= %\n” foo if x > y then ( -- top-level open parentheses - new -- scope is created local baz = foo + 1 -- uses the global foo local foo = y - 1 -- declares 1st local foo, hides global foo format “context level 1: foo= %\n” foo b=box() -- b implicitly declared as local b.pos.x = foo -- uses 1st local foo if (foo > 0) then ( local a local foo = y - x -- a nested 2nd local foo, hides 1st local format “ context level 2: foo= %\n” foo a = sin foo -- uses 2nd local foo format “a= %\n” a ) -- leave scope b.pos.y = foo - 1.5 -- back to 1st local foo format “context level 1: foo= %\n” foo ) -- leave scope -- b, baz and foo no longer in scope format “context level global: foo= %\n” foo -- back to global foo
Scope of Variables
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 won’t inadvertently change the higherlevel variable’s value.
•
Values of variables explicitly defined as local are displayed in error call stack trace-backs.
•
In 3ds max R2.5, if a 3ds max class, a MAXScript method, or a MAXScript read-only global variable has the same name as an implicitly declared local variable, a MAXScript runtime error will be generated if an assignment to that variable name occurs. Since the variable name already existed with a global scope, an implicitly declared local variable was not created. Since one or more new 3ds max classes will be created by any third party plug-ins the user has loaded, you were not be able to tell ahead of time if a variable name was a global variable name. In 3ds max R3, if the MAXScript compiler detects that the first reference to such a variable is an assignment, it will implicitly declare a local variable, rather than leaving it as a reference to a read-only system global. For example, executing the following expression in 3ds max R2.5 would result in a value of Box, since Box is a 3ds max object class. In 3ds R3, MAXScript detects
649
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 () -- 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
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
651
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
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
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 variable’s value to another variable, the reference to that value’s memory is placed in the new variable. The same applies to assigning a variable’s value to an array element or passing it as a function call argument; in all cases the reference is assigned or passed. When you assign a new value to a variable or when a variable goes out of scope, the reference that the variable contained is dropped. When your program has dropped all references to a value’s memory, that memory becomes eligible for reclamation. This is in contrast to value assignment in which a copy of the whole value’s memory is made and assigned. Value assignment has one advantage over reference assignment, namely that every time a variable or an array element is re-assigned, the old value’s memory space can be immediately
653
654
Chapter 4
|
Variables - Assignment and Scope
reclaimed because the old value is unique and nothing else can be referring to it. With reference assignment, the system cannot reclaim the original value’s memory space, because other variables may still point to the same value. Some scripting languages use a copy-based approach, such as HyperCard’s HyperTalk, but its inefficiency as well as some value sharing problems make it inappropriate for MAXScript. This creates the task of reclaiming memory in MAXScript. Programming languages such as C or Pascal require that the programmer explicitly reclaim a value’s memory when it is no longer needed, and this is one of the most difficult parts of programming in those languages. Recent variants like Java and some advanced languages like Lisp and Smalltalk provide automatic memory reclamation. MAXScript also provides this and it is described in the Memory Allocation and Garbage Collection (p. 655) topic. If you assign a variable’s value to another variable, the reference to that value’s memory is placed in the new variable. Thus, both variables are actually referencing the exact same value. If you assign a new value to one of the variables, that variable will contain a reference to the new value, and the other variable will contain a reference to the old value. Normally this is the desired behavior, as you don’t want both variables to reference the new value. However, a complication occurs if a compound value, like a point3 or array, is referenced by more than one variable, and you assign a new value to a component of the compound value. When you assign a value to a component of a compound value, a new compound value is not created. Therefore any variables that reference the compound value will still point to the same value, and will “see” the changed component value. Examples of this behavior are shown in the following script: Script: ( a=”hello world” 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 string’s reference in b and print their values create a string value, put reference in b print values – they are different put string’s 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
In some cases, this behavior is the desired behavior, and in other cases it is not. For those cases where it is not the desired behavior, a copy method is defined for most value types that will create a separate copy of a value. In some cases, such as arrays and structures, the value itself may contain compound values. The copy made is what is called a shallow copy - only a copy of the upper-level value itself (that is, the array) is created. Copies aren’t made of compound values in the value (that is, the elements of the array).
Memory Allocation and Garbage Collection MAXScript allocates its own working memory in addition to any memory 3ds max allocates as it works. The default working memory size setting for MAXScript is 5.5 MB, and the memory is virtual and pageable like all 3ds max memory. The default allocation accommodates most tasks, but you can increase it by incrementing the MAXScript system global variable heapSize: heapSize += 2000000
-- another 2 MB, for a total of 7.5 MB
You can add this statement to your startup script if you always need extra memory allocated for MAXScript tasks or you can set the default size in the MAXScript tab in the 3ds max Preferences dialog. Increasing the MAXScript heap reduces memory address space for other 3ds max tasks. Adjust the default memory setting only after you receive “Out of memory” error messages from MAXScript, or when garbage collection pauses occur frequently. You can increase the MAXScript heap as many times as you need during a 3ds max session, but you cannot reduce it. Restart 3ds max to reset the MAXScript memory heap to the default setting. MAXScript uses a memory management scheme called automatic garbage collection. This means you don’t have to explicitly reclaim any memory that a value takes up when you no longer need it. When you assign a new value to a variable or when a local variable’s block exits, the reference that the variable contained is dropped. When your program has dropped all references to a value’s memory, that memory becomes eligible for reclamation. Some values, such as arrays, have internal references to other values. In an array, each element contains a reference to another value. When you assign a new value to an array element, the element’s old reference is dropped. If you remove all references to the array itself, all the references in the elements of that array are implicitly dropped. The same applies to component values, such as in user structures and most 3ds max objects. MAXScript reclaims memory in a garbage collection pass through memory when MAXScript runs out of memory. This simple approach can result in a short pause because the entire MAXScript memory is scanned for garbage. Some languages use background collectors that work continuously; others use advanced schemes that minimize the scanning. Later versions of MAXScript might adopt one or more of these techniques. The advantage of garbage collection is you can create as many values as you need, and MAXScript cleans up the ones you no longer use.
655
656
Chapter 4
|
Variables - Assignment and Scope
Manual Garbage Collection The function gc() invokes the garbage collector. Normally, the collector runs automatically when available memory runs low, so you don’t normally need to call it explicitly. However, in some situations, it is useful to be able to force a collect to ensure a pause due to garbage collection will be delayed as long as possible. You can also invoke the collector to cause any unreferenced open files to be closed. In some situations, a file can be left open if a runtime error occurs while it is still open. If the file object was being held in a local variable at this point, it may not be possible to get at it from the Listener to force a close. Any subsequent attempts to open it may result in an “already open” error from the operating system. Running the collector will cause the file object to be reclaimed and this forces any open file associated with it to be closed. gc()
This function returns the number of bytes free in the MAXScript heap after collection. Note that the collector may take many seconds to run if the heap is full of many small reclaimable objects.
Chapter 5:
Names, Literal Constants, and Expressions
Names Names are used in MAXScript to identify variables, functions, parameters, properties, and so on. Names start with an alphabetic character or “_” (underscore), and can contain any number of alphanumeric characters or “_”. Examples of valid names are: foo bar123 this_is_a_very_long_identifier _heresOneWithStudlyCaps
The following names are not valid: 1object 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:
An example of a syntax where a name identifier is specified is: for ( in | = ) <sequence> ( do | collect ) <expr>
In this example, 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 “#”: #
In syntax descriptions, name values are specified as:
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
Sets the Out-of-Range (ORT) type for the controller for the time before the first key. The 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: ‘‘ #’‘ ‘‘:
-- 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: [-]{}[.{}[(e | E)[+ | -]{}+] 0x{}+
-- 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
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{}+
-- 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)
661
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]}+ [-]{}:{}[.{}] [-]<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>
::= ::= ::= ::=
::=
$<path> | $ [ ] [ / ] [ ] { / } ... { | _ | * | ? | \ } ‘{ | _ | * | ? | \ }‘
The root of a <path> can be an , which limits the pathname searching to the object set you specify. ObjectSets are described in the ObjectSet Values (p. 781) topic.
Pathname Literals
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 system’s directory structure. For example, $dummy/head/neck
names the scene object neck whose parent is object head, which has the top-level parent object dummy. This pathname helps you identify a specific object in a 3ds max scene, even if several objects have the same name. If head is unique in the scene, MAXScript lets you use the shorthand $head to refer to it regardless of its hierarchy position. Even if the object is not uniquely named you can use the shorthand form, but it is undetermined which of the same-named objects you will get. Pathnames also provide a powerful way to refer to several objects at once, such as all the children of a certain parent, or all the objects with names containing the string foot. For this, you can use wild-card patterns, as you can with operating system shell file naming schemes. For example, $dummy/*
names all the immediate children of dummy. The “*” character is used as a wild card. Or, $neck*
finds all the objects, whose names start with the string neck, anywhere in the hierarchy. You can use wild cards anywhere in a pathname. For example, $*foot*
finds all the objects with foot anywhere in their names. The “*” wild-card character effectively matches any number other characters. You can also use the “?” wild-card character to match exactly one “don’t care” character. This is, the “?” wild-card character will match any single character. For example, $box0?
finds all the objects that begin with box0 and have exactly one character after the 0 in their names. Wild-card characters can also be used for specifying parent levels in a hierarchy. For example, $dummy/*/*
names all the children of all the children of $dummy.
663
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
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
665
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)
Output: 10.0 45 #(1, 0.707107, 23.0)
-- can contain expressions
Array Literals
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 . 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
667
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> <while_loop> <do_loop> <struct_def> <max_command>
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
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 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 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. -
-- unary minus
The unary minus is only applicable to factors that evaluate to a number. Examples: -0.75 sin (-a*pi)
669
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>: [ <expr> ]
-- an indexed element
or a <property>: .
-- 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 -- conversion between types
where <math_operand> can be one of: <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
Note also that the math unary minus is not defined here, it is one of the 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 assignment’s 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
671
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: 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
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 are as follows:
== != > < >=
Examples: a > b sin x == 0.0 a + b 0 and a < n + 1 not x and y a and b or c and d and not e
As with math expressions, 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
Short-Circuiting Logical Expressions Following the convention in most other programming languages, logical expressions in MAXScript are short-circuiting or non-strict. This means only enough of the sub-expression is evaluated to determine the overall result: •
If the first operand is false in an and expression, the result must be false, therefore, the second operand is not evaluated.
•
If the first operand is true in an or expression, the result must be true, therefore, the second operand is not evaluated.
This saves execution time and enables useful shorthand notation. For example, if you want to calculate “sin a” if the value of variable a isn’t undefined, you can use the following example: if a != undefined and sin a > 0 then ...
In a strict language, the “sin a” evaluation of an undefined operand results in an error, and you would need to break up the expression into two if statements: if a != undefined then if sin a > 0 then ...
Function Calls A function call expression passes an optional list of arguments to a MAXScript or user-defined function, and the value returned by the function is the function call expression’s result. A has one of the following forms: { <argument> }+ ()
-- one or more arguments -- no arguments
in which, <argument> is one of the following: :
-- 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.
675
676
Chapter 5
|
Names, Literal Constants, and Expressions
All 3ds max objects, including geometric objects, splines, materials, and so on are created using function calls. The name of the object creation function is the object’s class name. For example: standard() 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 languages—they are required and have a fixed number and order.
•
Keyword Arguments: You write keyword arguments as a keyword:value pair, and they can appear in any order after the positional arguments. Functions can use some or all of their keyword arguments as optional arguments. If you call a function and don’t supply optional keyword arguments, they will have either the default value supplied by the called function, or the special value unsupplied when first referenced in the called function.
Optional keyword arguments are useful in command languages where commands can have many options. They are particularly useful within 3ds max where most functions have numerous optional keyword arguments. For example, all scene object creation functions take optional keyword arguments for their creation parameters. As there are sometimes more than 100 arguments to these functions, using positional arguments would simply be unworkable. As an example of positional arguments, the syntax for the print function is: print [ to: ]
is a positional argument, and is required. to: is an optional keyword argument, where to is the argument keyword and is the argument value. If the to argument value is unsupplied, MAXScript outputs to Listener. Otherwise, MAXScript outputs to the file specified by .
Function Precedence
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 has a lower precedence than an , 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 you don’t have to parenthesize. For example: sin -x
is interpreted as: sin (-x)
677
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 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
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 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 , you can insert a block-expression anywhere you can put an . 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]
679
680
Chapter 5
|
Names, Literal Constants, and Expressions
As described in the Scope of Variables (p. 646) topic, top-level open parentheses in a script file or in the Listener create a new variable scope. Any block-expressions with the top-level block-expression do not create a new variable scope, even if the variable is explicitly declared as local in the inner block-expression. A variable’s scope extends into any block-expressions within the variable’s scope. If you declare a variable as local in a scope, the newly declared local variable hides any outer variables with the same name. Any reference to that variable name later in the local variable’s scope refers to the new local variable. At the end of the local variable’s scope, the next outer variable becomes visible again. This is shown in the following script: Script: a=1 ( local a=2 ( local a=3 ) print a ) a
Output: 1 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
name, the two scripts can interfere with one another. This can cause apparently random failures of one or both scripts. •
You are sure you are using the correct variable in the event that a variable with the same name has already been declared at a higher scope, and you won’t inadvertently change the higherlevel variable’s value.
•
Values of variables explicitly defined as local are displayed in error call stack trace-backs.
•
In 3ds max R2.5, if a 3ds max class, a MAXScript method, or a MAXScript read-only global variable has the same name as an implicitly declared local variable, a MAXScript runtime error will be generated if an assignment to that variable name occurs. Since the variable name already existed with a global scope, an implicitly declared local variable was not created. Since one or more new 3ds max classes will be created by any third party plug-ins the user has loaded, you were not be able to tell ahead of time if a variable name was a global variable name. In 3ds max 4, if the MAXScript compiler detects that the first reference to such a variable is an assignment, it will implicitly declare a local variable, rather than leaving it as a reference to a read-only system global. For example, executing the following expression in 3ds max R2.5 would result in a value of Box, since Box is a 3ds max object class. In 3ds max 4, MAXScript detects that the first use of variable box is an assignment and creates an implicitly declared local variable box. The result of this expression in 3ds max 4 is the value undefined. (if false do box=10;box)
Context Expressions Context expressions are the parts of the MAXScript syntax that are most specifically designed for use with 3ds max. Context expressions are mirrors of some of the most important abstractions in the 3ds max user interface - the animate button, the time-line slider, the working coordinate system, and so on. Context expressions make it as easy to create animation and perform geometry manipulation in MAXScript as these tools do in the user interface. The basic idea for this is a prefix is supplied that sets up a context for the evaluation of its expression. For example: animate on ( move $box01 [20, 0, 0] rotate $box02 45 x_axis )
681
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 is: { , } <expr>
where is one of: [ with ] animate at level <node> in <node> at time [ in ] coordsys about [ with ] undo
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
See also Cascading Contexts (p. 688) Nested Contexts (p. 688) Sticky Contexts (p. 689)
animate The [ with ] animate 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 )
683
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
-- set context to hand
rotate $finger11 10 y_axis PalmCenter=$finger21.parent.pos PalmCenter+=(LHandPos-$finger21.pos)/2. dummy name:”palmLink” pos:PalmCenter
-----------
rotate hand’s child thumb rotate hand’s child first finger get hand’s 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
at time The at 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 context corresponds to the current reference coordinate system list in the main 3ds max toolbar. Prefixing an expression, operation, or block-expression with a coordsys context causes 3D coordinate operations to be interpreted in the specified coordinate system. Moving, scaling, or rotating objects, or setting transform-related properties within a coordsys context operate in relation to the given coordsys. Accessing coordinate properties such as position, center, rotation axis, and so on, within a coordsys context causes those values to be delivered relative to the given coordsys. The following forms are supported: [ in ] coordsys world
use the world space coordinate system [ in ] coordsys local
use the object’s local coordinate system [ in ] coordsys parent
use the object’s parent’s coordinate system [ in ] coordsys grid
use the active grid’s coordinate system [ in ] coordsys screen
use the currently active viewport’s coordinate system [ in ] coordsys <node>
use the specified node’s local coordinate system - this is equivalent to the “pick” coordinate system capability in the 3ds max user interface [ in ] coordsys <matrix3>
use the coordinate system specified by the given 3D matrix
685
686
Chapter 5
|
Names, Literal Constants, and Expressions
Examples: -- randomly jiggle each object in the selection around +/- 20 units in coordsys local selection.pos = random [-20,20,20] [20,20,20] -- rotate objects in parent’s coordinate system in coordsys parent rotate selection (EulerAngles 0 0 90)
about The about context is the MAXScript equivalent of the rotate/scale transform center list on the main 3ds max toolbar. It defines the center point about which any scale or rotation operation is performed within its context. Note that, like the center list in 3ds max, this sets only the center point for the operation, not the axis. The axis is taken from the current working coordinate system set using the coordsys context expression: about selection
rotates/scales about the center of the current selection about pivot
rotates/scales about each object’s pivot point about coordsys
rotates/scales about the center of the current working coordinate system set using the coordsys context expression about <node>
rotates/scales about the pivot point of the given object about <matrix3>
rotates/scales about the center of the coordinate system specified by the given 3D matrix about <point3>
rotates/scales about the given point with coordinate system and axes taken from the current working coordinate system. Examples: -- rotate all the boxes 30 degrees about the y_axis of $foo about $foo rotate $box* 30 y_axis -- rotate each planet 45 degrees around its parent in coordsys parent about coordsys rotate $planets* 45 z_axis
undo
undo The undo 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
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.
687
688
Chapter 5
|
Names, Literal Constants, and Expressions
Normally, if there are entries in the Undo stack when the scene is closed, 3ds max will prompt with a save-changes requester. In some cases, where you are controlling undo in MAXScript, you may want to force the need for a save-changes prompt.
Cascading Contexts You can cascade a set of context prefixes, optionally separated by commas, onto one subject expression, effectively applying all the contexts (in order) to the subject expression. For example: animate on, at time (t+1), with undo off, coordsys local ( ... )
All the context forms are true expressions, yielding the value of their subject expression, so: pos0 = at time 35 $box01.position pos1 = at time 75 $box01.position
assigns the box01 position at time’s 35 and 75 to variables pos0 and pos1. This is particularly useful with the at time context, as you can very easily do across-time computations. The operand to an at time context can be any valid time value (numbers are taken as frames for convenience), including sub-frame times down to the tick level. The animation system in 3ds max will interpolate animated parameters at these fine levels so you can easily do sub-frame simulation computations.
Nested Contexts All context expressions remember the prior setting of the context when they are set, and restore the original setting when the expression completes. Therefore, you can nest context clauses in any way you want, including contexts of the same type to override an outer setting. Example: with animate on, ( move ... rotate ... animate off ( move ... rotate ... ) scale ... ... )
at time t -- all these place keys -- turn off animate for a bit -- working maneuvers, these don’t effect animation -- animate on is restored here -- place keys again
Sticky Contexts
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
where 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 | off set level <node>
-- variant of at 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
689
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: <do_loop> <while_loop>
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 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 the result is false, the optional else <expr> is evaluated and its value is returned as the result of the . If there is no else or the do form is used, the 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
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 is: case [ <expr> ] of ( )
where <expr> is the test expression and is a sequence of labeled expressions: : <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 - 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 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 ( in | = ) <sequence> ( do | collect ) <expr>
where 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
Examples: for i = 1 to 10 do print i -- sequence numbers for item in table1 do x = x + item.height -- sequence an array for t in 0f to 100f by 5f do ... -- sequence time (given as -- frames, here) bigones = for obj in $box* -- you can sequence pathnames! where obj.height > 100 collect obj -- collect the big boxes into -- an array
The first <sequence> form is the standard number loop, the first <expr> value is the start value, the to <expr> value is the limit value and the optional by <expr> value is the loop value increment. The allowable value types are integer, float and time. If the by value isn’t given it defaults to 1. The second form of <sequence> takes a sequencable collection, such as an array (p. 666) or ObjectSet (p. 781), and iterates through all its values, assigning successive elements in the collection to the loop value each time through the loop. MAXScript contains several sequence collections, including PathName values (p. 780), the current selection set, the children of a node, and the stack of modifiers on an object. See also the Collections (p. 773) topic for caveats when using a collection in a for loop. Each <sequence> source form takes an optional where <expr> which must evaluate to true or false. The where expression is evaluated at the beginning of each loop and only executes the loop body for that loop value if the where expression is true. The do <expr> form simply evaluates the body expression once for each value in the sequence. The loop variable is visible to the code in the body expression as though it was declared locally and initialized to the successive loop values each time. When the do <expr> form of a for loop is used as an expression, its return value is always OK. The collect <expr> form gathers the expression values from the loop iterations and stores them in an array, which is then yielded as the value of the overall for loop. This, for example, is a good way to gather procedural selections of objects from a scene. If the where expression is used with the collect form of the for loop, only the values from those iterations for which the where expression is true are collected. This can be used to collect a filtered sub-set of the iterated values. You can also achieve this collection filtering in a for loop that does not use a where expression by yielding the special value dontCollect for those iterations that should not be added to the collection. As described in the Scope of Variables (p. 646) topic, a for loop creates a new scope context. The for loop index variable’s scope is always the extent of the for loop, even if another variable of the same name already exists. Once the for loop exits, the for loop index variable is no longer accessible. The scope of any variables created in a for loop is always the extent of the for loop. This is shown in the following example:
695
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 )
-----------
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
avg_pos /= $*.count
See also Skipping Loop Iterations (p. 696) Loop Exit (p. 697)
Skipping Loop Iterations MAXScript provides a continue construct that allows you to jump to the end of a for, do, or while loop body <expr> and resume with the next loop iteration. Its syntax is: continue
Examples: for i=1 to 8 do (if i == 5 do continue; print i) -- prints 1..4, 6..8 while not eof f do ( 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
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 lets you specify what the overall value of the loop expression should be if the loop exits prematurely. If you don’t specify an exit value, the loop returns the value undefined upon exit. Exiting a for ... do loop using a with <expr> results in a value of OK. Exiting a for ... collect loop using a with <expr> results in the array of body values collected up to the point of exit.
Try Expression MAXScript provides simple exception-handling with the try expression, a simplified form of the C++ exception-handling scheme. The try expression lets you bracket a piece of code and catch any runtime errors. This allows you to respond appropriately or take corrective action, rather than let MAXScript halt the execution of your script and print an error message. The syntax for the try expression is: try <protected_expr> catch
The <protected_expr> is executed and any errors that occur are trapped and the 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 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.
697
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> [ ] 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 is: [mapped] (function | fn) { <parameter> } = <expr>
in which is the name of the function. The optional sequence of <parameter>s can be one of: : [ ]
-- keyword parameter with -- optional default value
and the <expr> after the ‘=’ (equal sign) is the body of the function. The function 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 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 . 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 function’s definition. The form is: showSource
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
Function Variables When you define a function, the following events occur: •
The function definition is evaluated, creating a function value.
•
The function is used to declare a new variable with that name.
•
The function value is placed into that variable.
•
The function value is returned as the result of the function definition expression.
Because the function itself is a value stored in a variable, you not only can call the function through the function name variable. By simply referring the function’s variable you can also assign the function value to another variable, store it in an array, or pass it as an argument to another function. Example: -- some 3D surface functions fn saddle x y = sin x * sin y fn sombrero x y = cos (x^2 + y^2) / 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.
701
702
Chapter 7
|
Creating Functions
Examples: fn funcA which = ( if which == 1 then fn saddle x y = sin x * sin y else fn sombrero x y = cos (x^2 + y^2) / (1 + (x^2 + y^2)) ) myfunc=funcA 2 z=myfunc 10 10
In the above example, the scope of variables saddle and sombrero is local to funcA, and the variables are out of scope outside the function. The return value of funcA is either the function value saddle() or sombrero(), and is assigned to variable myfunc. As also can be seen in this example, you can define a function within any expression.
See also Scope of Variables (p. 646) Function Calls (p. 675)
Function Parameters The parameters to a function are implicitly declared as local variables at the head of the function body, and are initialized with the arguments given by the caller. The parameters have a scope that extends to the end of the function body <expr>. They can be assigned to and hidden by nested local variables with the same name, as can other local variables. Keyword parameters can be given default values in the function definition, implicitly making them optional to the caller. If the caller does not supply one of the keyword arguments, it is initialized to the default value upon function entry. The default values are specified after the ‘:’ (colon). If a keyword parameter is defined with no default value and is not supplied by the caller, it is initialized to the special value unsupplied. You can check for this value in the body of your function and handle missing required keyword argument errors accordingly. Example: fn foo a b: c: d: = ( if c == unsupplied then print “Where’s the c: argument??” ... )
As described in the Reference Assignment (p. 653) topic, MAXScript uses an assignment called reference assignment. In a function, each parameter variable contains a reference to the value passed to the function by the caller. Assigning to a parameter variable places a new reference in the parameter variable, and has no effect on the variable values in the caller - it is an entirely local action. An exception to this is if the parameter value is a compound value such as an 3D Point, string, or array, and you assign a new value to one of the components of the compound value. In this case, the
Function Parameters
variable’s reference does not change, and the changed compound value will still be referenced by the variable in the caller. While in some cases you may want a function to return multiple values, it typically is not a good practice to do this by assigning to the components of a parameter variable compound value. To manipulate a compound value passed as a parameter, a compound value needs to be created in the caller and passed to the function, which can give results as shown in this example: Script: fn getXYZset val = ( val.x=random -100 100 val.y=random 100 100 val.z=random val.x val.y ) ( v1=[0,0,0] v4=v1 getXYZSet v1 format “v1= %; v4= %\n” v1 v4 getXYZSet v4 format “v1= %; v4= %\n” v1 v4 )
Output: getXYZset() 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.
703
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
The Return Expression As with the loop constructs, you can break out of a function body block-expression prematurely in MAXScript, and return a result without evaluating the remaining portion of the block. For this purpose, you use the return expression: return <expr>
If a return expression is evaluated in the course of running a function body, the function exits immediately and yields the value given in the return <expr>. Note that it is unnecessary and somewhat inefficient to place a return expression at the end of a function body to return an expression value. Instead, simply place the result expression at the end of a function body. If a return <expr> is used in a mapped function and a collection is passed as the first argument to the function, the value returned will be OK rather than <expr>. As a special case, you can exit a script controller’s script using a return <expr>. Example: fn find_root twod_fn = ( local root, last_root while true do ( ... if abs(root - last_root) < epsilon then return root ... ) )
705
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: [ = <expr> ]
-- 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 aren’t made of compound values stored in the structure, rather the same compound value is stored in both struct values. This can be seen in the following example, where changing a component value of a compound value in a copy of a struct value also changes value in the original struct value: Script: struct test (pos1, pos2) 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:, pos2:) #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
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),
709
710
Chapter 8
|
Structure Definition
fn setSeed val = (SeedVal = val), fn setPointer val = ( if val > 0 and val ] [#noMap]
-- mappable
where <stream> is ( | <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 { } [ 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
classOf
Returns the value’s class. Each type of value has its own class. If the value is a Node value, classOf() returns the class of the world state object (the state of the node at the top of its stack). See the Node : MAXWrapper (p. 820) topic for more information. Note: To avoid a conflict between a user class value in global variable named ‘rollout’ and MAXScript reserved word ‘rollout’ which always introduces a rollout definition the class variable name for a rollout is RolloutClass. So, for a rollout foo you’d now say “if classOf foo == RolloutClass”. superClassOf
Returns the value’s superclass. A value’s superclass is the class from which the value’s class was derived. isKindOf
Returns true if value has given class or inherits from class. isStructDef
Returns true if the value is a structure definition isStruct
Returns true if the value is a structure instance isController
Returns true if the value is a controller getHashValue
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
715
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 as string operation, that is the result is a string representation of the object rather than the object name. classOf, superClassOf, and isKindOf The following table shows the hierarchy of classes and superclasses for a variable that contains a reference to a 3ds max Box object (i.e., b=box()). ClassOf
SuperClassOf
and isKindOf
b
Box
GeometryClass
box
GeometryClass
Node
GeometryClass
Node
MAXWrapper
Node
MAXWrapper
Value
MAXWrapper
Value
Value
Value
Value
Value
The isKindOf() and classOf() functions are useful for filtering objects from a set. For example, either of the following will collect all objects of class box into variable allBoxes: allBoxes=for obj in $* where (isKindOf obj box) do collect obj allBoxes=#() for obj in $* do (if classOf obj == box then append allBoxes obj)
Number Values
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: [-]{}[.{}[(e | E)[+ | -]{}+] 0x{}+
-- decimal number -- hexadecimal number
717
718
Chapter 9
|
Values
Example Literals: 123 123.45 -0.00345 1.0e-6 0x0E 0xFFE0 .1
Operators:
+ * /
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. ^
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. -
unary minus
== != > < >= 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 value corresponding to the first character of the string. bit.intAsHex
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
When you display or print a Float, MAXScript prints the value to the 6th significant digit. The following table shows examples of values stored to a MAXScript variable, the value as stored, and the value as displayed. Input Value
Stored Value
Displayed Value
1.23456789
1.23456788
1.23457
1.1
1.10000002
1.1
1.01
1.00999999
1.01
1.001
1.00100004
1.001
1.0001
1.00010001
1.0001
1.00001
1.00001001
1.00001
1.000001
1.00000095
1.0
1.0000001
1.00000011
1.0
1.00000001
1.00000000
1.0
100017.911
100017.914
100018.0
Examples: The following script shows the use of various literals, constructors, properties, operators, and methods of the Number class. Script: -- numbers test bed i=10 -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
721
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: “”
See the String Literals (p. 660) topic for a description of String literals. Constructors: 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>
Standard lexical string comparisons (case sensitive). To perform a case insensitive comparison, first convert the strings to Name values. <string>[]
Returns indexed character as a single-character string, index starts at 1.
String Values
<string>[] = <single_character_string>
Sets indexed character to character given. <string> as
Converts the string to an instance of the given class. You can convert a string into a Name value using the as operator, for example: “Foo” as name
-- returns #foo
You can also convert strings to numbers using the as operator. For example: “123.4” as float
-- returns 123.4
You can use any of the Number classes as a target class - Number, Float, or Integer. If you use Number, the appropriate class will be used depending on the syntax of the number in the string. You can convert a string to a StringStream value using the as operator. For example: “$box01” as stringstream
-- returns the string as a stringstream
Converting a string to a StringStream value allows you to read through a string using the MAXScript’s text file I/O operations. See the StringStream Values (p. 766) topic for a description of StringStreams. Methods: copy <string>
Creates a new copy of the string value. For example: newstr = copy oldstr
The new value contains a copy of the text contents of the copied string, and is independent of the copied string. execute <string>
Compiles and evaluates the contents of the string as a MAXScript expression and returns the result of the evaluation. For example: execute “2 + 2”
-- yields the value 4
str = “$foo.ffd_2x2x2.control_point_” + n as string + “ = [1,1,1]” execute str
The result of an execute() call is the result of the last expression in the string argument.
723
724
Chapter 9
|
Values
You can use execute() as a temporary work-around to the current limitation in naming scene objects - there is currently no way to name an object using a computed name. For example: obj = execute (”$foo/” + child_name)
would retrieve the child of $foo named in the variable child_name. Here’s a more complex example: side = “left” finger = 2 limb = “arm” obj = execute (”$torso/” + limb + “/” + side + “/finger/” + finger as string)
The scope of variables used in the evaluated string is global and not the scope in effect when the execute() method is executed. So if you call execute() within a function, scripted utility, or anywhere where the scope is not global, you will need to explicitly specify the scope of any variables used in the string that is executed. In the following example, the scope of variable posObj is local to utility myUtil, so the string needs to specify the variable’s name as being in myUtil’s scope: Utility myUtil “My Utility” ( ... local posObj ... fn test obj = ( local i, j, thisCont ... thisCont=execute (”myUtil.posObj.’”+j+”‘pos.controller”) ... )
In general, you cannot access locals from outside of an object, except for top-level locals in rollouts, utilities, tools and plug-ins (because they are semi-permanent and are stored with these objects). Function parameters and locals are dynamic and stack-based and not accessible as properties of the function definition. For more information on variable scope, see the Scope of Variables (p. 646) and Accessing Locals and Other Items in a Rollout from External Code (p. 1480) topics. GetTextExtent <string>
Returns a Point2 value containing the size of the string in pixels if it was displayed in a command panel. findString <string> <search_string>
Returns the index of search_string in string or undefined if not found. For example: findString “Thanks for all the fish!” “all”
-- returns 12
String Values
filterString <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>
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>
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: ]
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.
725
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
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: #
See the Names (p. 657) topic for a description of Name literals. Constructors: <string> as name
Converts a String value into a name Operators:
== != < > =
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)
727
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
true if boolean=false, false if boolean=true and
true if both boolean values are true or
true if either boolean value is true Notes: The boolean and and or evaluations are non-strict. This means that only the first boolean may be evaluated to determine the overall result: •
If the first operand is false in an and expression, the result must be false, therefore, the second operand is not evaluated.
•
If the first operand is true in an or expression, the result must be true, therefore, the second operand is not evaluated.
This saves execution time and enables useful shorthand notation. For example, if you want to calculate ‘sin a’ if the value of variable ‘a’ isn’t undefined, you could use the example below: if a != undefined and sin a > 0 then ..
Examples: The following script shows the use of various literals and operators of the BooleanClass class. Script: -- boolean test bed bool1=true -- set variables to boolean literals bool2=on if bool1 and bool2 do print “booleans are equal” -- compare the booleans -- define an “exclusive or” function - returns true if only one of the -- inputs is true fn xor b1 b2 = (not (b1 and b2)) and (b1 or b2) xor false false -- evaluate 4 combinations of inputs to xor xor false true xor true false xor true true
Color Values
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 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: .red or .r .green or .g .blue or .b .alpha or .a
: : : :
Float Float Float Float
color component properties .hue or .h .saturation or .s .value or .v
derived properties
: Float : Float : Float
729
730
Chapter 9
|
Values
Operators: == !=
+ * /
Channel-by-channel math operations. Numbers operate on r,g,b,a channels equally. -
unary minus Methods: copy
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
Returns a random color between the given colors. The alpha component of the result will always be 255. composite
Composites color1 over color2 through color1’s alpha. This function is equivalent to: color1 + color2*((255. - color1.alpha)/255.)
-- 3D Noise Functions noise3 noise4 turbulence fractalNoise
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
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
Constructors: point3 <x> as point3
-- equivalent to [1,0,0] -- equivalent to [0,1,0] -- equivalent to [0,0,1]
731
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> *
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
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>
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>
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>
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.
733
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
Output: The following figures show the bitmap generated by the above script for each noise function type.
noise3
noise4
turbulence
735
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> <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
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>
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: .pos .position .dir
: Float : Float : Point3
-- pos and position are synonyms -- unit normalized direction vector
Methods: copy
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.
737
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> <w_float>
The x, y, z values make up the vector portion. w is the angle of rotation about the vector. quat <degrees_float> as quat <eulerangle> as quat <matrix3> as quat -- extracts the rotation component as a quat
Properties: .w .x .y .z
: : : :
Float Float Float Float
quaternion complex components as Floats .angle .axis
: Float : Point3
derived properties - an angle in degrees and a rotation axis Operators: + * / -
Quaternion algebra * <matrix3>
Quaternion algebra using rotation portion of the matrix3 == != as
quats can convert to Matrix3’s, Angleaxis’s, Eulerangle’s
Quat Values
Methods: copy
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
Returns true if the quaternion is equal to the identity quaternion (x=y=z=0.0; w=1.0). normalize
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
Returns the inverse of the quaternion (1/q). conjugate
Returns the conjugate of a quaternion. logN
Returns the natural logarithm of UNIT quaternion. exp
Returns the exponentiated quaternion (where q.w=0). slerp <start_quat> <end_quat>
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
Returns the “log difference” of two quaternions as: logN ((inverse p_quat)*q_quat) qCompA <prev_quat> <now_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 slerp (slerp p_quat q_quat number) \ (slerp a_quat b_quat number) \ (2*(1-number)*number) qorthog
Returns quat rotated by 180 degrees (quaternion space metric) about the specified axis axis_point3. transform <matrix3>
Returns the transformation of the specified quaternion by the specified matrix.
739
740
Chapter 9
|
Values
squadrev <start_quat> \ <start_tangent_quat> <end_tangent_quat> \ <end_quat>
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
Returns a random rotation between the two quats, using Slerp. Related Methods: quatToEuler 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 <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
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> as angleaxis <eulerangle> as angleaxis <matrix3> as angleaxis
extracts the rotation component as an angleaxis Operators: == != as
AngleAxis can convert to Matrix3’s, Quat’s, Eulerangle’s Properties: .angle .axis .numrevs
: Float : Point3 : Integer
Methods: copy
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
Random rotation in degrees, but uses quat Slerp, so loses multiple revolution angles.
741
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> as eulerAngles as eulerAngles <matrix3> as eulerAngles
Extracts the rotation component as an eulerAngles. Operators: <eulerAngles> == <eulerAngles> <eulerAngles> != <eulerAngles> <eulerAngles> as
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
quatToEuler 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 <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
743
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
matrix from row vectors matrix3 0
zero matrix matrix3 1
identity matrix as matrix3 as matrix3 <eulerangles> as matrix3
rotation matrices rotateXMatrix rotateYMatrix rotateZMatrix
-- all angles in degrees
rotation matrices transMatrix <point3>
translation matrix scaleMatrix <point3>
scale matrix rotateYPRMatrix
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
Operators: <matrix3> <matrix3> <matrix3> <matrix3>
+ <matrix3> - <matrix3> * <matrix3> as
Matrix3’s can convert to Quat’s, AngleAxis, EulerAngles using the matrix’s rotation component Properties: <matrix3>.row1 <matrix3>.row2 <matrix3>.row3 <matrix3>.row4 <matrix3>.translation
: : : : :
Point3 Point3 Point3 Point3 Point3
read/write access to rows. Row4 is the translation. <matrix3>.rotationpart <matrix3>.translationpart <matrix3>.scalerotationpart <matrix3>.scalepart
: : : :
Quat, read-only Point3, read-only Quat, read-only Point3, read-only
access to various transforms, with the remaining transforms zero-ed out. <matrix3>.determinantsign
: Integer, read-only
returns sign of the matrix’s determinant Methods: copy <matrix3>
Creates a new copy of the matrix3 value. For example: newMatrix3 = copy oldMatrix3
The new value contains a copy of the input matrix3 value, and is independent of the input matrix3 value. isIdentity <matrix3>
Returns true if the matrix is equal to the identity matrix. inverse <matrix3>
Returns the inverse of the matrix. xformMat <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).
745
746
Chapter 9
|
Values
identity <matrix3>
-- mapped function
Sets the input matrix or matrices to the identity matrix. If the parameter is a single matrix, this function returns an identity matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 values are replaced with the identity matrix. zero <matrix3>
-- mapped function
Sets the input matrix or matrices to the zero matrix. If the parameter is a single matrix, this function returns an zero matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 values are replaced with the zero matrix. orthogonalize <matrix3>
-- mapped function
Sets the input matrix or matrices to the an “unbiased” orthogonalization of the matrix. An orthogonal matrix has an axis system where each axis is 90 degrees from the others (it’s not skewed). If the parameter is a single matrix, this function returns the orthogonalized matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the orthogonalized matrix value(s). translate <matrix3> <point3>
-- mapped function
Applies an incremental translation transformation to the input matrix or matrices. This is equivalent to multiplying on the RIGHT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s). rotateX <matrix3> rotateY <matrix3> rotateZ <matrix3> rotate <matrix3>
-- 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> [ ] -- 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 is true, the translation component is scaled. If 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
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> preRotateY <matrix3> preRotateZ <matrix3> preRotate <matrix3>
-- 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> [ ] -- 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 is true, the translation component is scaled. If 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:
747
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
Properties: .rows .columns
: Integer, read-only : Integer, read-only
Operators: + -- both BigMatrix values must have same size [] -- returns BigMatrixRowArray of indexed row [] -- returns float value of indexed column [] = -- sets value in the indexed column
Because accessors are themselves operands, these definitions are recursive, which means that you can string accessors together: [][] -- returns float value of indexed row and column [][] = -- sets value in the matrix
Methods: invert
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
transpose
Returns the transpose of , i.e. result BigMatrix[i][j] = BigMatrix[j][i]. clear
Frees all the elements and sets the matrix size to be 0x0 setSize
Deletes the current elements and sets the size of the matrix to rows x columns. identity
-- 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
749
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> <w_integer>
Constructs a Box2 with the upper left corner at [x,y] with width w and height h. Box2
Constructs a Box2 object from the specified corners. Properties: .x .y .w .h .left .right .top .bottom .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: == !=
Standard comparison operators. Two Box2 values are equal if all of their component values are equal. Methods: scale
Scales the coordinates of the box about the center of the box. translate <point2>
Translates the coordinates of the box by the distance specified. contains <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
Adjusts the coordinates of the box such that top < bottom and left < right.
Time Values
empty
Sets the Box2 to a special “empty” value. isEmpty
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]}+ [-]{}:{}[.{}] [-]<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
-- time from normal fraction
Properties: .ticks .frame .normalized
: Time as ticks : Time as frames : Time as normalized fraction of active segment
751
752
Chapter 9
|
Values
Operators: + - * /
scale time
== != > >= < <end_time>
Properties: .start .end
: Time : Time
Undefined Value
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
753
754
Chapter 9
|
Values
Ok Value The Ok class implements the void value returned by some functions and expressions that don’t have a meaningful value to return. There is one distinguished instance of the OK class in the reserved system variable OK.
Unsupplied Value The Unsupplied class implements the value used to initialize unsupplied keyword parameters to functions. There is one distinguished instance of the Unsupplied class in the reserved system variable unsupplied. You can test to see whether a caller has supplied an optional keyword argument by comparing it with unsupplied. Constructor: unsupplied
Examples: fn walk_tree obj parent: = ( if parent == unsupplied then ... else ... ... )
DontCollect Value The dontCollect value is used in for loops to signal that the value is not to be collected. See For Loop (p. 694) for details. dontCollect is a separate distinguished instance of the Undefined class, and so will fail in the way the undefined value does if used in computations. Constructor: dontCollect
Examples: -- collect all spheres with radius less than 5 little_spheres = for i in $* collect if classOf i == sphere and i.radius < 5 then i else dontCollect
DontCollect Value
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 [ [ [ [ [
filename: ] numframes: ] color: ] gamma: ] pixelAspect: ]
\ \ \ \
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
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.
755
756
Chapter 9
|
Values
selectBitMap [ caption: ]
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
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: .filename
: String
Lets you get or set the file name associated with the bitmap. .palette
: Array
Yields an array of 256 colors (a bug in the current 3ds max SDK prevents working with paletted files of other than 256 entries). Take care accessing this array with colors indexes retrieved by the getIndexedPixels() function described below, because these indexes are 0-based and MAXScript array indexes are 1-based. Yields undefined if the bitmap is not paletted. Currently you cannot create a paletted bitmap in MAXScript, however you can read and write to a pre-existing paletted bitmap. .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. .numframes
: Integer
The number of frames in a multi-frame file, yields 1 for a single image file. .height
: Integer, read-only
Returns bitmap’s height in pixels. .width
: Integer, read-only
Returns bitmap’s width in pixels. .gamma
: Float, read-only
Returns bitmap’s gamma value. .aspect
: Float, read-only
Returns the bitmap’s pixel aspect. Note that this is the aspect of the pixel, not the aspect of the bitmap image. Methods: display
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
unDisplay
Close the VFB associated with the bitmap if open. save [frame:]
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
Closes the bitmap file associated with the bitmap if it is open for output. A bitmap file is opened for output when you call save on the bitmap value the first time. If a VFB associated with the bitmap is open, it will be closed. This function also frees all memory allocated by the bitmap, including the internal pixel frame buffer. If you are generating many bitmaps, say in a rendering loop, you can use the close() function to free these often large amounts of memory, that won’t otherwise be released until the next garbage collection. copy <source_bitmap> <dest_bitmap>
Copies the source bitmap to the destination bitmap. If the size of the two bitmaps is different, the image will be scaled to fit the destination bitmap. gotoFrame
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
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
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.
757
758
Chapter 9
|
Values
getIndexedPixels
Retrieve a row of pixels as an array of palette index numbers. The coord_point2 argument specifies the starting pixel coordinate with 0,0 at the top-left-hand pixel. The index numbers are origin 0. Note that this is in keeping with indexed color conventions but not MAXScript’s. Take care accessing any retrieved palette array using these numbers because the retrieved palette is returned as a MAXScript array and these arrays use 1-based indexes. You cannot get pixels sequences that cross row boundaries. setIndexedPixels
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
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
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
: : : : : : : : : : : :
<point2> <point3> <node> <point2>
See the 3ds max Software Development Kit Help file for information on the data stored in the g-buffer channels. getChannelAsMask [to:] [fileName:”filename_string”] [pixelAspect:] [gamma:] [layer:] [invert:] [node:<node> | objectID: | matID:] [velocity:#angle | #magnitude] | [angle:]
\ \ \ \
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:
The source bitmap containing the source g-buffer channel data.
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:
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:
Specifies the generated bitmap’s gamma value.
759
760
Chapter 9
|
Values
pixelAspect:
Specifies the generated bitmap’s pixel aspect. Note that this is the aspect of the pixel, not the aspect of the bitmap image. layer:
Specifies the channel layer of the source bitmap to extract data from. Defaults to 1. invert:
If true, inverts the generated bitmap. Defaults to false. node:<node> objectID: matID:
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:
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:
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
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
silentMode()
Returns a boolean signifying the Silent mode state. selectSaveBitMap [ caption: ]
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: filename:<seed_filename_string> getBitmapSaveFileName caption: filename:<seed_filename_string>
Displays the bitmap file selection dialog. Both functions return a fully-specified file path name or undefined if the user cancels out. If an existing file name is selected using the getBitmapSaveFileName() function, a File Exists/Confirm Overwrite dialog will be displayed. Note: The getBitmapOpenFileName() function does not require that an existing file name be selected - i.e., a file name is returned if the user types a file name that does not exist. If necessary, you should check the file name that is returned to ensure the file exists. Notes: When you open a bitmap file, an entire frame is loaded into memory. When you are finished processing a bitmap, it is a good idea to either call close() on the bitmap or assign the value undefined to the variable storing the bitmap value, and then manually run garbage collection (gc()), so that it’s memory can be released. Another technique for conserving memory when using the render() or getChannelAsMask() functions repeatedly is to use the to: keyword argument which allows those functions to overwrite an existing bitmap’s pixel image with the new rendering or mask. There currently is no access to the properties associated with the bitmap output plug-ins. This means that you cannot set the codec used for .avi files, nor the setup parameters for .rla and .tga files. The properties used are the properties that were last used when saving that file type in 3ds max. Examples: The following script shows how to properly create and save a multi-frame image file.
761
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.
--------
result result result result result result result
Output: $Teapot:Teapot01 @ [0,0,0] OK $Target_Camera:Camera01 @ [200,0,100] #{1, 3, 5..12} BitMap:c:\t.avi OK OK
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 don’t need to distribute bitmap files along with your script. Script: ( b=selectbitmap() -- open image file browser bname=”bitmap_”+(getfilenamefile b.filename) -- build name from filename w=b.width -- get properties of bitmap h=b.height format “----------\nfn load_% = (\n” bname -- start defining function format “local %=bitmap % %\n” bname w h -- create bitmap in function -- write out a function that unpacks an integer into a pixel color format “fn unpack val = for p in val collect (r=p/256^2; g=p/256-r*256; b=mod p 256; color r g b)\n” for r=0 to h-1 do -- for each row in the bitmap -- have function write the column of pixels to the bitmap ( format “setpixels % [0,%] (unpack #(” bname r pixels=getpixels b [0,r] w -- read in the column of pixels for c=1 to w do -- loop through each pixel
FileStream Values
(
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
creates a new file and returns a value. If the specified file cannot be created, the value undefined is returned.
763
764
Chapter 9
|
Values
openFile [ mode:<mode_string> ]
opens an existing file and returns a 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
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
read next line, return as string readChar
read next char, return as string readChars
reads the specified number of characters and returns them in a string. readDelimitedString <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 <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
positions the input file at the beginning of the next line filePos
retrieve the current offset into the file seek
position the file at the given offset so that subsequent I/O will start there. eof
return true if there is no more data in the file, false otherwise. flush
ensure all output to file is on disk, flushes the memory buffers. close
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
read and evaluate the next MAXScript from the file readExpr
read and evaluate the next MAXScript <expr> from the file
FileStream Values
execute
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 to: format { } to:
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)
765
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 <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 to:<stringstream> format ““ {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> readDelimitedString <stringstream> <string> skipToString <stringstream> <string> skipToNextLine <stringstream> execute <stringstream>
WindowStream Values
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 to:<windowstream> format ““ {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)
767
768
Chapter 9
|
Values
MAXKey Common Properties, Operators, and Methods Constructor: addNewKey [ #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
Returns the indexed key as a MAXKey instance. []
where is: .keys <node>..keys
Properties: For keys associated with all keyframeable controller types, the following properties are accessible: .time .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: .value
varies
-- class determined by its containing controller
Methods: copy
Creates a copy of the key value. This copy is not independent of the original key, as a key value always references a key in a controller. This method exists primarily to support copying of arrays. The keys on Bézier, TCB, and Barycentric Morph controllers have additional properties and methods. See the Bezier Controller Keys (p. 1310), TCB Controller Keys (p. 1335), and Barycentric Morph Controller Keys (p. 1308) topics for details.
See also MAXKeyArray Values (p. 793) Controller Common Properties, Operators, and Methods (p. 1289) Value Common Properties, Operators, and Methods (p. 714)
Working with MAXKey Values
Working with MAXKey Values Changing the .time property of a key may cause it to go out of time order relative to the other keys in the controller. You must call the sortKeys() function on the controller or associated MAXKeyArray once all key time manipulations of this kind is complete so that animation will perform correctly. The class of a key’s value property is determined by the controller it is in, for example, a linear_float key has a float .value, a tcb_rotation key has a quaternion .value, etc. The properties are all settable and support the math-assignment operators and nested-property access. Here are some examples: $foo.pos.keys[2].time += 20f -- change time of single key $foo.pos.keys.time += 20f -- change time of all keys $box1.uvw_map.center.keys[2].value.x += 20 for k in $baz.bend.angle.keys do k.value *= 1.1
In some cases, the actual value stored in a key is not the value shown in the command panels, shown in Track View, the value returned by the .value property of the key, or the value returned when accessing the property to which the key’s controller is assigned. Instead, a scaling factor is applied to the key’s value before the value is made “visible”. For example, percentages are normally displayed with a range of 0-100, rotation angles are in degrees, colors are [0-255,0-255,0-255]. The unscaled key values for percentages are normally in a range of 0-1, rotation angles in radians, and colors are [0-1,0-1,0-1]. In the description of properties for each class, the scaling factor, if any, is identified for each property. Take for example the following properties for the PArray class: .X_Spin_Vector .Spin_Time_Variation .Spin_Phase .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.
769
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: .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
Operators: []
Returns element of ArrayParameter. Indexes start at 1. [] =
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 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 it’s properties set the value for one element via its alias and show the element was changed
771
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 obj’s 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: #(, , ...) #() -- an empty array
See also Array Literals (p. 666). Constructors: as array
Convert collection to an array. Properties: <array>.count
: Integer, read-only
Returns number of elements in array. Operators: <array>[]
Returns element of array. Indexes start at 1. <array>[] =
Sets element of array to value, growing array as necessary. <array> +
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
Methods: append <array>
Append value to array, growing it as necessary. copy <array> [#noMap]
-- mapped
Creates a copy of all the elements in the array. Returns a value of OK. If #noMap is specified, the copy made is what is called a shallow copy - only a copy of the upper-level value itself (that is, the array value) is created. Copies aren’t made of values stored in the array, rather a reference to the same value is stored in both array values. deleteItem <array>
Delete element indexed by number from array, shrinking it in size by 1. join <array>
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>
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 <array>
Inserts the value at the specified index in the array, growing the array if necessary qsort <array> [start:] [end:] [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))
777
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
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
779
780
Chapter 10
|
Collections
PathName Values PathNames provide the mechanism for naming objects in the 3ds max scene. See also the Pathname Literals (p. 662) topic. Pathname values are mappable. Example Literals: $box01 $torso/left_upper_arm/left_lower_arm $*box* $torso/* $torso...*
Properties: <pathname>.center
: Point3, read-only
Returns center of bounding box of all objects in pathname. <pathname>.max
: Point3, read-only
Returns maximum corner of bounding box. <pathname>.min
: Point3, read-only
Returns minimum corner of bounding box. <pathname>.count
: Integer, read-only
Returns number of objects in set. This property is only valid for wild-carded pathnames, i.e., a pathname that could contain more than one scene object. Operators: <pathname>[] <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 ... -- ... for obj in myBoxes where not isDeleted obj do move obj [10,0,0]
ObjectSet Values
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 , one of the many context expressions that are described in the Context Expressions (p. 681) topic. Examples: a = $*feet*[i]
-- retrieves the i’th object in the *feet*’s
-- tell me what things inside dummy have a non-identity scale for obj in $dummy...* where obj.scale != [1,1,1] do format “% has non-identity scale: %\n” obj.name obj.scale -- place $foo’s pivot point at the max corner of the set of ‘box*’ objects. $foo.pivot = $box*.max in $dummy ( sphere name:”ear1” pos:[10,10,10] -- create as children of $dummy sphere name:”ear2” pos:[-10,10,10] scale $foo/* [1,1,2] -- looks for ‘foo’ as a child of $dummy )
ObjectSet Values ObjectSets represent the main scene object categories in 3ds max. The “constructors” below are all reserved system variables. ObjectSet values are mappable. Constructors: objects geometry lights cameras helpers shapes systems spacewarps selection
-- all the objects -- the standard 3ds max categories...
-- the current selection
Properties: .center
: Point3, read-only
Returns center of bounding box of all objects in set. .max
: Point3, read-only
Returns maximum corner of bounding box.
781
782
Chapter 10
|
Collections
.min
: Point3, read-only
Returns minimum corner of bounding box. .count
: Integer, read-only
Returns number of objects in set. Operators: [] 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 you’ve specified. So, in the above example, it will name only helper objects that start with ‘d’. The order of sequencing is consistent in a stable scene but somewhat arbitrary - it depends on how 3ds max stores its object hierarchy internally which is effected mostly by order of additions and deletions to and from the scene.
SelectionSetArray Values
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.
783
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
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[]
-- set by string or name value -- set by order in drop-down list
Operators: <selectionset>[]
-- retrieve nth object in set
Properties: <selectionset>.center
: Point3, read-only
Returns center of bounding box of all objects in set. <selectionset>.max
: Point3, read-only
Returns maximum corner of bounding box. <selectionset>.min
: Point3, read-only
Returns minimum corner of bounding box. <selectionset>.count
: Integer, read-only
Returns number of objects in set. Notes: Unlike ObjectSet, you cannot use SelectionSet as the root of a pathname. The order of sequencing is consistent in a stable scene but somewhat arbitrary - it depends on how 3ds max stores its object hierarchy internally which is effected mostly by order of additions and deletions to and from the scene.
NodeChildrenArray Values A NodeChildrenArray represents the direct children of a scene node as a virtual array. As such, you can iterate over the children, apply mapped functions to them and obtain certain properties such as count and bounding box info. Also see the General Node Properties (p. 836) topic. NodeChildrenArray values are mappable. Constructors: <node>.children
Properties: <nodechildrenarray>.center
: Point3, read-only
Returns center of bounding box of children. <nodechildrenarray>.max
: Point3, read-only
Returns maximum corner of bounding box.
785
786
Chapter 10
|
Collections
<nodechildrenarray>.min
: Point3, read-only
Returns minimum corner of bounding box. <nodechildrenarray>.count
: Integer, read-only
Returns number of objects in set. Operators: <nodechildrenarray>[]
-- 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: .count
: Integer, read-only
Returns the number of vertices in the VertexSelection array. .selSetNames
: Array of names, read-only
Returns an array of names of the current vertex-level named selection sets for the object the VertexSelection is associated with. The following properties are present for singleton selections (of the form $foo.verts[n]): .index
: Integer, read-only
Returns the index of the selected element in the mesh, e.g., $foo.selectedVerts[2].index
returns the vertex index of the 2nd vertex in the current selection.
VertexSelection Values
.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> | )
Selects the specified vertices. []
Retrieves the indexed vertex as a singleton VertexSelection. Index starts at 1 [] = <point3>
Sets the position of the indexed vertex. [( | )]
Retrieves the indexed vertices as a VertexSelection. Index starts at 1. [( | <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. [( | <string>)] = ( | | )
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 <point3>
Moves the vertices in the VertexSelection. select
Selects the vertices in the VertexSelection. deselect
Deselects the vertices in the VertexSelection. delete
Deletes the vertices in the VertexSelection. append ( | )
Appends the vertex or vertices to the VertexSelection. findItem (.selectedFaces <mesh>.Faces
-- the currently selected faces of the mesh object -- all of the faces of the mesh object, read-only
Properties: .count
: Integer, read-only
Returns the number of faces in the FaceSelection array. .selSetNames
: Array of names, read-only
Returns an array of names of the current face-level named selection sets for the object the FaceSelection is associated with. The following property is present for singleton selections (of the form $foo.faces[n]): .index
: Integer, read-only
Returns the index of the selected element in the mesh, e.g., $foo.selectedFaces[2].index
returns the face index of the 2nd face in the current selection. Note that iterating over a selection yields singleton selections in the loop body: sf = for i in $foo.selectedFaces collect i.index
sf contains selected faces as array Operators: <mesh>.selectedFaces = (<array> | )
Selects the specified faces. []
Retrieves the indexed face as a singleton FaceSelection. Index starts at 1.
FaceSelection Values
[] = <point3>
Sets the vertices of the indexed face to the vertex indices specified in the point3 value. [( | )]
Retrieves the indexed faces as a FaceSelection. Index starts at 1. [( | <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. [( | <string>)] = ( | | )
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 <point3>
Moves the faces in the FaceSelection. select
Selects the faces in the FaceSelection. deselect
Deselects the faces in the FaceSelection. delete
Deletes the faces in the FaceSelection. append ( | )
Appends the face(s) to the FaceSelection. findItem (.selectedEdges <mesh>.Edges
-- the currently selected edges of the mesh object -- all of the edges of the mesh object, read-only
Properties: <edgeselection>.count
: Integer, read-only
Returns the number of edges in the edge array. <edgeselection>.selSetNames
: Array of names, read-only
Returns an array of names of the current edge-level named selection sets for the object the EdgeSelection is associated with. The following property is present for singleton selections (of the form $foo.edges[n]): <edgeselection>.index
: Integer, read-only
Returns the index of the selected element in the mesh, e.g., $foo.selectedEdges[2].index
returns the edge index of the 2nd edge in the current selection. Note that iterating over a selection yields singleton selections in the loop body: se = for i in $foo.selectedVerts collect i.index
se contains selected edges as array Operators: <mesh>.selectedEdges = (<array> | )
Selects the specified edges. <edgeselection>[]
Retrieves the indexed edge as a singleton EdgeSelection. Index starts at 1 <edgeselection>[( | )]
Retrieves the indexed edges as a EdgeSelection. Index starts at 1. <edgeselection>[( | <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>[( | <string>)] = ( | | )
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
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> | )
Appends the edge(s) to the EdgeSelection. findItem <edgeselection> (<edgeselection[] | )
Returns the selection index of the matching item or 0 if not found. The item is selection index or singleton EdgeSelection. Examples: -- move edges in ‘mouth’ named selection set move $foo.edges[#mouth] [0,0,10] -- select edges in ‘front edges’ set select $baz.edges[”front edges”] -- set ‘baz’ named selection set to given edges $foo.edges[#baz] = #(1,3,4,5,10) -- set ‘cursel’ set to current selection $baz.edges[#cursel] = $baz.selectedEdges -- all the names of the edge-level named selection sets for object $foo $foo.edges.selSetNames -- print out all edge-level named selection sets for n in $.edges.selSetNames do print $.edges[n]
BitArray Values The MAXScript BitArray class provides direct access to 3ds max’s SDK BitArray class. The SDK BitArray is used throughout 3ds max to compactly encode selections as a string of bits. Literals: #{ <selection> }
-- these are curly-brackets
where <selection> is a comma-separated list of the following: ..
-- 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.
791
792
Chapter 10
|
Collections
Properties: .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: [] [] = + - -
------
yields true if selected, else false sets or clears indexed bit union (”OR” operation) difference invert the bitarray
Methods: append
Adds index to bitarray, growing bitarray if necessary. join
Union (”OR” operation) of the two bitarrays. findItem
Yields index if selected, 0 otherwise. deleteItem
Clears the index selection. copy
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
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>..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. .keys
The key array can be accessed using the keys property on a controller. Examples: $foo.position.controller.keys $foo[3][1].keys
Properties: .count
: Integer, read-only
Returns the number of keys in the key array. Operators: []
Returns a MAXKey (p. 767) value representing the indexed key in the key array. Indexes start at 1. Methods: append
Appends key to key array. deleteItem
Deletes the indexed key. Key indexes are 1-based. addNewKey [ #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 [ #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
793
794
Chapter 10
|
Collections
deleteKey
Deletes the indexed key. Key indexes are 1-based. moveKeys [ #selection ]
Moves all keys by the time given. If #selection is specified, move the current selection otherwise move all keys. sortKeys
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
Operators: <modifierarray>[]
Retrieves indexed modifier. Index is 1-based with 1 being the modifier on the top of the modifier stack. <modifierarray>[( | <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>[ | | <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>[ | | <string> ] =
( <material> | )
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.
795
796
Chapter 10
|
Collections
meditMaterials[<slot_index_integer>] = ( <material> | )
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> ( | | <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> | )
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
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
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
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.
797
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:
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
Here’s a fragment of the first example’s output: lights (const ObjectSet): $lights lightLevel (system Float): 1.0 Sunlight (const MAXClass): Sunlight Directionallight (const MAXClass): Directionallight lightLevelController (system Control): Controller:Bezier_Float light (const MAXSuperClass): light NewLight (const Primitive): NewLight() lightTintColor (system Color): (color 255 255 255) Volume_Light (const MAXClass): Volume_Light lightTintColorController (system Control): Controller:Bezier_Color gw.getMaxLights (Primitive): getMaxLights() gw.setLight (Primitive): setLight()
showClass: The showClass() function prints information about a specified 3ds max class or classes. It has the following form: showClass <pattern_string> [ to:<stream> ]
where <pattern_string> is a string containing a wild-card pattern to match against 3ds max class names, superclass names and property names, and the optional to:<stream> keyword argument specifies a Stream Value (p. 763) to output the display to. The pattern string has this form: “[ :<superclass_name> ][ .<property_name> ]”
Class and Object Inspector Functions
Examples: -- 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
showClass “path*” showClass “noise.*” showClass showClass showClass showClass
In the output from the last example, the controllers include 3ds max’s core controllers and any 3rd-party plug-in controllers. In some cases, embedded controllers for some complex plug-ins may be visible in the showClass() listing (such as for character studio and HyperMatter). You should not attempt to create and use these controllers individually, this may result in system exceptions. If you leave out the superclass pattern (the ‘:’ part), it matches all superclasses. If you leave out the property pattern (the ‘.’ part), you only get class names printed. Note: This function only displays matching MAXWrapper classes (nodes, modifiers, materials, etc.), not the foundation classes in MAXScript (float, integer, array, point3, etc.). The following shows examples of the output of showClass(): Script: showclass “box*” 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.
801
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 () : integer .falloff : float
Class and Object Inspector Functions
.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.
803
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 <property_name> setProperty <property_name>
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 <string_or_name> setPropertyController <string_or_name>
Get and set the controller assigned to the named property of the value. If no controller has been assigned to the property, a value of undefined is returned. SubAnims and ParamBlocks: 3ds max stores all of properties for objects in structures called subAnims. In some cases, a subAnim will contain nested subAnims. An example of this can be seen with the Standard material. If you apply a Standard material to an 3ds max object, and then expand the object’s tracks in Track View to display the material, you will see three Track View nodes - Parameters, Maps, and Shader. Each of these nodes is a subAnim defined in the Standard material’s class. Expanding the tracks for these three nodes, you will see various properties listed. These properties are defined in each of the nested subAnims in a structure called a ParamBlock. MAXScript automatically finds animatable properties in all ParamBlocks associated with an object. To access these properties, you use the same nesting as shown in Track View when referencing those properties in MAXScript. For example, you would access the Ambient Color property in a Standard material in MAXScript as: $box01.material.shader.diffuse_color
Dynamic Properties
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 node’s .position property, to be individually and directly set. See the Nested Object Properties (p. 815) topic for details.
Dynamic Properties In addition to the properties listed in the reference, MAXScript provides access to the dynamic properties in 3ds max entities, those properties that are specific to an individual object and depend on the operations you’ve performed on that object in the 3ds max scene. These includes such things as animatable modifier sub-objects like gizmos and FFD control points and sub-controllers like those in a List controller or P/R/S Transform or Path controller. These correspond to the many animatable parameters and sub-objects that you see in the Track View for an object; if you can see them in the Track View they will be visible as either static or dynamic properties in the MAXScript value that corresponds to that object. The property name you specify is matched against the sub-animatable name (as it would be seen in the Track View or sub-object drop-down) using the standard MAXScript conventions of mapping spaces to ‘_’ underscores and ignoring case when dealing with 3ds max class and property names. You can also simply leave out the spaces in any dynamic property names. Example: p = $foo.bend.center $baz.taper.gizmo.rotation = quat 30 z_axis $foo.pos.controller.bezier_position = [10,0,0]
Because these properties are dynamic and may change as controllers are replaced and sub-objects become animated, they may vary from object to object and so are not reported in the properties section of the showClass() function output. Instead, you can use the built-in function showProperties() which will display the accessible properties on a 3ds max entity including the currently visible dynamic properties. Both functions are described in the Class and Object Inspector Functions (p. 799) topic.
805
806
Chapter 11
|
3ds max Objects
Indexed Access to Animatable Properties in 3ds max Objects As an alternative to using named property accesses, you can access in an object any animatable property that is visible as a track in Track View by indexing the 3ds max object value as though it were an array. This simplifies such tasks as iterating over all the animatable properties in an object and accessing sub-controllers that don’t have unique names, such as within list controllers. Properties: <maxwrapper_object>.numSubs
: Integer, read-only
Yields the number of accessible sub-animatables, or tracks, in an object. This is the number of immediate children subAnims, and may include as yet invisible tracks in the track view, such as visibility tracks on a node or yet-to-be animated vertices in an FFD. This property operates on any MAXWrapper subclass. Methods: getSubAnimName <maxwrapper_object> 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>
Returns the indexed subAnim. See the index operator below. Operators: <maxwrapper_object>[]
Returns the indexed subAnim. You can apply the index operator, [], to any MAXWrapper object (nodes, modifiers, controllers, materials, etc.) to access a numbered subAnim. For example: for i in 1 to $foo.numSubs do print $foo[i] -- iterate them $bar.position.controller[3] -- third subAnim in a position list controller ffd_mod[i].value -- position of i’th FFD control point
You cannot set subAnims with the index operator, this is a read-only access. -- SubAnim Class MAXScript defines a SubAnim class, instances of which provide a general representation for 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 .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
controller. The .value property yields the value at the current MAXScript time. You can assign to this value to set the track’s value at that time. <subAnim>.controller
: Controller
The controller for the track SubAnim. Returns undefined if a controller has not yet been assigned or if the SubAnim is not animatable. You can assign a new controller to a track by assigning to the .controller property of its subAnim. <subAnim>.keys
: KeyArray, read-only
Yields the key array for that track or undefined if not keyable or a controller has not yet been assigned. This property is read-only. <subAnim>.isAnimated
: Boolean, read-only
Yields true if there is an animated controller present. This property is read-only. <subAnim>.object
: MAXWrapper, read-only
Yields the subAnim object, or undefined if not assigned. This property is read-only. The .object property may return any kind of MAXWrapper object, depending on what the parent object decides to put there. For example, <node>[1].object is the visibility controller or undefined if not yet assigned, <node>[2].object contains the bindings of any space warps bound to the node, or undefined if none have been bound, <node>[3].object is the transform controller, <node>[4].object is the node’s object, either the modified object if there are modifiers present or the base object if not, <node>[5].object is the material assigned to the node or undefined if no material has been assigned, and <node>[6].object is the Image Motion Blur Multiplier controller or undefined if not yet assigned,. For example: b = box() b[4].object
-- returns a reference to the Box base object
<subAnim>.numSubs
: Integer, read-only
The number of immediate subAnim children. If you attempt to access subAnim properties, such as .value, .numSubs, .category, etc., on certain subAnims that had yet to be assigned controllers, such as scene node visibility tracks, these properties return null values such as 0, or undefined, as appropriate. Methods: getSubAnim <subAnim>
Returns the indexed subAnim. See the index operator below. Operators: <subAnim>[]
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
807
808
Chapter 11
|
3ds max Objects
MAXScript SubAnims descend automatically through ‘hidden’ subAnim levels, reflecting the structure seen in Track View. Note that you can get at the base object’s Track View parameters by indexing into the base object: b=box() getSubAnimNames b[4] -- returns #(#length, #width, #height, ...) b[4][2].value -- returns current width value i = 3 b[4][i].controller = float_list() -- assign height controller
Third-Party Plug-In Classes The MAXWrapper Value (p. 808) classes are the core 3ds max classes that are supported directly within MAXScript. Many of the kinds of 3ds max objects you will work with are provided through 3rd-party plug-ins for 3ds max, they are not built directly in to MAXScript. For these classes, an automatic plug-in detector scans for plug-ins that MAXScript doesn’t internally know about and attempts to provide MAXScript access to them. This includes new core classes in new releases of 3ds max that MAXScript doesn’t internally know about, and 3rd-party plug-ins (such as HyperMatter, Sand Blaster, Surface Tools, etc.). Not all parameters and properties of the detected plug-ins are accessible. In general, the detector will only find animatable parameters on these 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
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)
809
810
Chapter 11
|
3ds max Objects
<MAXWrapperobject>.classID <maxclass>.classID
The classID property retrieves the internal 3ds max Class ID of the MAXWrapper classes and objects. The value returned is an array containing two numbers, PartA and PartB of the 3ds max internal class ID. For a MAXWrapper object, the value returned is the Class ID of the class the object is an instance of. For example, Box.classID
-- returns #(16, 0)
b=box() b.classID
-- returns #(16, 0)
The combination of the PartA and PartB numbers is guaranteed to be unique for each class. <MAXWrapperObject>.superClassID <maxclass>.superClassID
Retrieves the 3ds max superclass ID of the MAXWrapper classes and objects. Methods: copy <MAXWrapper_object>
The copy() function is implemented by all the 3ds max objects available in MAXScript, such as scene objects, controllers, modifiers, materials, etc. You can use this function to make a clone of the source object, for example in situations where you want individual copies or you want to make a shared object unique. For example: addModifier $foo $baz.bend
will cause foo to share the bend modifier on baz, whereas: addModifier $foo (copy $baz.bend)
will give foo a separate clone of the bend modifier on baz. Any changes to the bend modifier on foo will not affect baz and vice versa. In the next example, we set up several objects all sharing a single rotation controller: c = bezier_rotation() $foo.rotation.controller = c $baz.rotation.controller = c $bar.rotation.controller = c
To later make one of the controllers unique, you could do this: $baz.rotation.controller = copy $baz.rotation.controller
When the MAXWrapper object is not a scene node, the copy is only created in MAXScript memory. When the MAXWrapper object is a scene node, a new scene node is created which is visible and accessible by the user in the 3ds max viewports.
MAXWrapper Common Properties, Operators, and Methods
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 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
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.
811
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
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> <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>
Returns the AppData item string of the given ID number from the given 3ds max object. Returns the value undefined if the ID’d item is not present. deleteAppData <MAXWrapper_object>
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.
813
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
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 foo’s position as a ‘detached’ point3 -- set the x prop of that point, it doesn’t know -- about foo anymore, foo’s pos is not changed
In this case, you would have to explicitly re-assign the free-standing point to $foo’s position to affect $foo: $foo.pos = p
-- set foo’s new position
In general, any property on a MAXWrapper object that is itself a foundation compound value such as a Point3 or Quat will yield a free-standing value when simply accessed and supports object subproperty assignment in cascaded property assignment.
815
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
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>
Returns the time of indexed note key. getNoteKeyIndex < notetrack >
Returns the index of the note key at the specified time. Associated Methods: addNoteTrack <MAXWrapper_object>
Adds a new note track to the MAXWrapper object. deleteNoteTrack <MAXWrapper_object>
Deletes specified note track from the MAXWrapper object.
MAXNoteKeyArray Values
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>
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: .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: .count
: Integer, read-only
returns the number of objects in set Operators: [] at 1.
-- accesses member of collection. Indexes start
Methods: addNewNoteKey
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 ( #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
Deletes the indexed note key. Key indexes are 1-based. sortNoteKeys
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.
817
818
Chapter 11
|
3ds max Objects
Associated Methods: getNoteKeyTime <notetrack>
Returns the time of indexed note key. getKeyIndex < notetrack >
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> [ #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>[]
Properties: <MAXNoteKey>.time <MAXNoteKey>.selected write access. <MAXNoteKey>.value
Time Boolean
-- time value or number (interpreted as frames) -- specifies whether the key is selected. Read/
String
-- string contained in the note key
Working with Note Tracks Changing the time property of a note key may cause it to go out of time order relative to the other keys in the controller. You must call the sortKeys() function on the controller or associated MAXNoteKeyArray once all key time manipulations of this kind is complete so that animation will perform correctly. Example: Script: s = sphere() -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 sphere’s pos -- apply second note track to sphere’s pos -- check number of note tracks on pos
Working with Note Tracks
hasNoteTracks s.pos.controller -- test to see if pos controller has note tracks -addNewNoteKey ntp1.keys 20 #select -- add key to first note track, and select the key addNewNoteKey ntp1.keys 40 -- add another key to first note track -n = getNoteTrack s.pos.controller 1 -- retrieve first note track on the pos controller nk=n.keys -- retrieve an instance of the note track key array -nk[2].value = “Yo What’s Up” -- set value for second note key nk[2].time = 10 -- change the time for second note key. Now first key nk[1].selected = true -- select the first note key sortNoteKeys nk -- changed the time of the note keys, so 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 What’s 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
819
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 [] <wild_card_pathname>[]
n’th scene object in collection <node_constructor> [ [ [ [ [ [ [ [ [ location [ [ [
name: <string> ] prefix: <string> ] material: <material> ] target: <node> ] pos: <point3> ] position: <point3> ] rotation: ] 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: ] \ -- 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
All of the node constructors can take the above optional keyword arguments, along with any of general node properties or any of the properties for the particular node class as keyword arguments. The name keyword can be used to specify the name for the created node. 3ds max allows the same name to be used for more than one node. The prefix keyword can be used in place of the name keyword argument to specify the start of the node name from which 3ds max will generate a unique name by adding a series of digits, as it does when creating objects interactively. For example: for i in 1 to 100 do sphere prefix:”baz”
creates 100 spheres, giving each a unique name beginning with “baz”, such as $baz01, $baz02, $baz03, etc. The material keyword can be used to apply the specified material to the created node. The target keyword can be used to automatically apply a LookAt controller to the node’s transform track, and set the specified node as the LookAt target. The transformation arguments, pos, scale, rotation, and pivot, are applied to the new object in the order they are specified in the constructor call, so you can control transform order. The pos, scale, and rotation arguments are mutually exclusive with the transform argument which can be used as an alternative way to set the node’s complete transform matrix in one go. Note: Exercise care if you specify the target keyword. When you specify a target object, 3ds max stores with the target object the last object it was assigned as a target of. If you delete the target object, the behavior of 3ds max is to also delete the object looking at it. If the target object is a targetobject class object, deleting an object looking at it will also delete the target object, even if another object is also looking at it. Properties: See the General Node Properties (p. 836) and Node Transform Properties (p. 841) topics for details about the properties accessible on scene nodes. Methods: Most node methods are automatically mapped over node collections. IsValidNode
Returns true if is a node value, and the node has not been deleted. Otherwise, it returns false. move <node> <point3> scale <node> <point3> rotate <node> rotate <node> 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).
821
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 node’s transform controllers and keys and the visibility controller and its keys if a visibility track has been assigned. snapshot <node>
-- mapped
This function provides functionality similar to the SnapShot tool in 3ds max. It generates a new node that contains a copy of the world-state mesh of the source <node> at the time that the snapshot is made. Any existing modifiers are collapsed out of the new node and the mesh snapshot accounts for any space warps currently applied. As with the clone methods (copy, reference and instance,) you can add any of the standard node creation keyword arguments, such as pos:, name:, etc. The following example achieves an animation-based snapshot similar to the SnapShot tool in 3ds max: for t in 0 to 100 do at time t snapshot $foo delete <node>
-- mapped
Deletes the specified node(s). instanceReplace <dest_node> <src_node> referenceReplace <dest_node> <src_node>
-- mapped -- mapped
Lets you turn existing nodes into instances and references to other nodes. You can use these, for example, to replace the geometry of one node with another, perhaps for implementing custom level-of-detail tools. The <dest_node> is turned into an instance or reference to the <src_node>. As a new instance, existing geometry and modifiers are removed and replaced by the <src_node>’s, but all the node-related properties are kept, such as material, transform, visibility, name, etc. As a new reference, the base object for the <dest_node> becomes the world-state of the <src_node>, such that any changes to the src_node will affect the <dest_node>, but changes to the <dest_node> are local to it. It is possible to develop a custom scripted version of the File/Replace function with these functions and the mergeMAXFile() function by temporarily changing the name of a node in the current scene, merging in that named node from another, making the first node an instance of the newly merged node with instanceReplace(), deleting the newly merged node and renaming the old node back again. Both these functions are collection mapped, so you can make a selection of objects all instance or reference the same object, for example: instanceReplace $foo* $baz
makes all the foo* objects be instances of baz’s geometry and modifier stack. attachObjects <node1> <node2> [ move: ]
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
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>
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.
823
824
Chapter 11
|
3ds max Objects
For example: fn axisRotate obj rotation = (local axis local objA = if classof obj == objectSet or classof obj == array then obj else #(obj) if getCoordCenter() != #local then (axis = getTransformAxis objA[1] 0 for obj1 in objA do in coordsys axis about axis rotate obj1 rotation ) else (for obj1 in objA do (axis = getTransformAxis obj1 0 in coordsys axis about axis rotate obj1 rotation ) ) ) invalidateTM <node>
Invalidates the node’s transformation matrix cache. invalidateTreeTM <node>
Invalidates the node’s transformation matrix cach and notify the node’s subtree that the transformation matrix has changed. The following MAXScript function can be used to force an update of an object whose transform is partially controlled by a scripted controller (such as a script controller on the position track): mapped fn TMInvalidate obj = (at time (currenttime-1) obj.transform nodeInvalRect obj invalidateTreeTM obj redrawViews() ) invalidateWS <node>
Invalidates the node’s world space cache. getNodeByName <string> exact:
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
getInheritanceFlags <node> setInheritanceFlags <node> (#all | #none | ) keepPos:
Get and set the inheritance flags for the specified node as an . 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 | )
Get and set the transform lock flags for the specified node as an . 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>
Sets whether the node inherits the visibility of its parent object (if any). If is true, node inherits visibility. If is false the node does not inherit visibility. getVisController <node>
Returns an instance of the node’s visibility controller. Returns undefined if the node does not have a visibility track. getImageBlurMultController <node>
Returns the node’s Image Motion Blur Multiplier controller. Returns undefined if not Image Motion Blur Multiplier controller has been assigned to the node. setImageBlurMultiplier <node>
Sets the node’s Image Motion Blur Multiplier value at the specified time to the specified value setImageBlurMultController <node>
Sets the node’s Image Motion Blur Multiplier controller to the specified controller setMotBlur <node>
Sets which type of motion blur to use for node. If = 1, None. If = 2, Object Motion Blur. If = 3, Image Motion Blur. setRenderable <node>
Sets whether the node is renderable. If is true, node is renderable. If 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>
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.
825
826
Chapter 11
|
3ds max Objects
-- Group-Related Methods group <node> [ name:<string> ] [ prefix:<string> ] \ [ select: ] -- 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
-- mapped
Ungroups one level of a group node. For example: ungroup $group01
ungroups group $group01 explodeGroup
-- 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
Sets whether the group is set as open or closed. If is true, the group is set as open. If is false the group is closed.
Working with Note Tracks
*** 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>
Sets whether the node is a group member or not. If is true, node is set as a group member. If 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>
Sets whether the node is flagged as a group head or not. If is true, node is flagged as a group head. If is false, the node is set as not being a group head. Note: If you flag a node as a group head using this method, the node’s mesh will not be displayed in the viewports, and its properties will not be shown in the Modify panel. If you flag a group head node as not being a group head using this method, you will not be able to Open or Explode the group via the Group menu command. Example: -- create a set of spheres, group them, and test group head and member of group mySpheres=for i=1 to 5 collect sphere pos:(random [-100,-100,0] [100,100,0]) group MySpheres name:”MyGroup” isGroupHead $MyGroup -- returns true isGroupMember $sphere01 -- returns true -- check to see if group is open. Open group and test member of group isOpenGroupHead $MyGroup -- returns false setGroupHeadOpen $MyGroup true isOpenGroupMember $sphere01 -- returns false -- create a new set of spheres, append the group to the set, and then group them all NewSpheres=for i=1 to 3 collect sphere pos:(random [-100,-100,0] [100,100,0]) append NewSpheres $MyGroup group NewSpheres name:”BiggerGroup” -- open the group head, test member of group, and then close the groups. setGroupHeadOpen $BiggerGroup true isOpenGroupMember $MyGroup setGroupHeadOpen $MyGroup false setGroupHeadOpen $BiggerGroup false
827
828
Chapter 11
|
3ds max Objects
-- Node Viewport State Methods hide <node> unhide <node> freeze <node> unfreeze <node> flagForeground <node>
------
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 plane’s effectiveness. Remember to unflag objects when you don’t need to interactively control them any more. getTrajectoryOn <node>
Returns true if Trajectory is shown for the node, false otherwise. setTrajectoryOn <node>
Sets whether Trajectory is shown for the node. If is true, Trajectory is shown. If is false, Trajectory is not shown. isBoneOnly <node>
Returns true if the node’s showLinksOnly property is true. getCVertMode <node>
Returns true if node is displayed using vertex colors in shaded viewports, false otherwise. setCVertMode <node>
Sets whether to display the effect of assigned vertex colors for the node in shaded viewports. If is true, node is displayed using vertex colors. If 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>
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
-- Node Selection Methods clearSelection() clearNodeSelection [ redraw: ]
Deselects all currently selected scene nodes. Scene is redrawn unless redraw:false is specified. deselect <node>
-- mapped
Deselects the given node(s). For example: deselect $box*
deselects all items whose names start with “box”. deselectNode <node>
Deselects a single node select <node>
-- mapped
Deselects any currently selected objects and then selects the node(s) you specified. selectMore <node>
-- mapped
Adds the node(s) to the set of selected objects. If you want to build a set of selected objects from scratch in a loop, you can use clearSelection() to clear the selection before entering the loop, and use selectMore() in the loop to add objects to the set of selected objects. -- Modifier Stack Related Methods validModifier [ <node> | | ] <modifier>
Tests whether a particular modifier may be added the given <node> or to all of the objects in the objectset or group. Returns true if so, false if not. The validModifier() method operates exactly as does the Modify panel in determining modifier applicability. Any modifier that takes a deformable object will return true for all scene objects except Helpers. This corresponds to the Modify panel’s behavior of allowing modifiers such as Bend, Taper, etc. to be applied to lights and cameras, space warp objects, etc., as well as geometry types like box, sphere, etc., but not helpers such as dummys or bones. The validModifier() method will return true if an empty is specified, or if a 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 is empty in the first case, or because the modifier cannot be applied to the dummy object that is the parent object of the objects in the group. You will need to test for these conditions in your script, or use the modPanel.addModToSelection() method described in the Modify Panel (p. 1572) topic. addModifier <node> <modifier> [before:index]
-- mapped
Applies the modifier to all instances of the node(s) to which the function is applied. The optional before: keyword argument can be used to insert the modifier into the node’s modifier stack just before the indexed modifier, counting from the top of the stack. The added modifier will apply to any appropriate active sub-object selection in the node only if
829
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 instance’s gizmo corresponds to position and size of the node the modifier instance is applied to. To apply a modifier to a collection in the same manner that 3ds max applies modifiers, use the modPanel.addModToSelection() method described in the Modify Panel (p. 1572) topic. Also see the Modifier and SpacewarpModifier (p. 1095) topic for more details. deleteModifier <node> <modifier_or_index>
-- mapped
Lets you delete modifiers from the modifier stack. Takes either a modifier value which is present on the <node> stack, or an index specifying the index of the modifier to delete, counting from the top of the stack. collapseStack <node>
-- mapped
Collapses the modifiers out of a stack, leaving a resultant editable mesh as the base object of the node(s). If there are no modifiers in the stack when this is called, no action is taken. If you want to force an object to be an editable mesh, use the function convertToMesh(). -- Node Modifier Transform Context Methods getModContextTM <node> <modifier>
Returns a Matrix3 value giving the modifier’s context transform for the local coordinates used in modifier sub-object gizmos. Accessing the transform properties of a modifier subobject such as a gizmo or a center in MAXScript yields values that are relative to that modifier’s context transform, equivalent to the values shown in track view for those properties. If the modifier is not operating on a sub-object selection, such as a face or vertex selection, or if the modifier was interactively applied to an object selection, this context TM is the local coordinate space of the object itself. However, if the modifier is operating on either an object selection set or a sub-object selection, the context transform gives the position and orientation of that selection, and so you can use the getModContextTM() function to get the world-space transform properties of any of its sub-objects.
Working with Note Tracks
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>
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>
-- 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.
831
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 ... -- ... 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>
Computes the closest intersection of the ray and the surface of the given node. Returns another Ray which defines the position of intersection in 3D space and the surface normal direction vector at that point. The intersection test respects the face normals of the node, i.e. if a face’s normal points away from the ray’s source, an intersection test is not performed on that face. intersectRay() works if the world state of the node (the state of the node at the top of the node’s stack) has a surface, such as an editable mesh, a Standard, Extended, or Compound Primitive, or a Patch or NURBS surface object. Splines and NURBS curves do not have a surface. Returns undefined if the ray doesn’t intersect the node, the faces it does intersect point away from the ray’s position, or the node does not have a surface.
Working with Note Tracks
intersectRayEx <node>
Takes a ray and computes the closest intersection to the surface of the given node. It returns an array with the following three elements. 1.A Ray defining the position of intersection in 3-space and the surface normal direction vector at the point. 2.The index of the face the ray intersects with 3.The barycentric coordinates of the face that was hit. This method only works if the world state of the node is a mesh, either because it started as an editable mesh or because it has modifiers applied that convert the node to a mesh. Unlike intersectRay(), this method will not work if the node is a Standard or Extended Primitive - the node’s stack must evaluate to a mesh. The intersection test respects the face normals of the node, i.e. if a face’s normal points away from the ray’s source, an intersection test is not performed on that face. Returns undefined if the ray doesn’t intersect the node, the faces it does intersect point away from the ray’s position, or the node isn’t a mesh. Barycentric coordinates are the coordinates relative to the triangular face. The barycentric coordinates of a point p relative to a triangle describe that point as a weighted sum of the vertices of the triangle. If the barycentric coordinates are b0, b1, and b2, then: p = b0*p0 + b1*p1 + b2*p2;
where p0, p1, and p2 are the positions of the vertices of the triangle. The Point3 returned by this method has the barycentric coordinate stored in its three component values. The coordinate is relative to the triangular face that was intersected. Barycentric coordinates can also be used to interpolate any quantity whose value is known at the vertices of the triangle. Following is an example of finding the UV coordinates at the intersection point: Script: s = sphere material:(standardMaterial diffuseMap:(checker())) showTextureMap s.material s.material.diffuseMap on --- Add a normal modifier to make the sphere into a mesh addModifier s (normalModifier()) r = ray [-100,5,0] (s.center-[-100,5,0]) --- Get the Intersection details arr = (intersectRayEx s r) --- Create a dummy at the point of intersection dummy pos:(arr[1]).pos --- Get the texture face tf = getTVFace s arr[2] --- Get the UVW verts of the face tv1 = getTVert s tf.x
833
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>
Retrieves the node’s user property with the given key as a string. is either a String or a Name value. If the key does not exist, a value of undefined is returned. setUserProp <node>
Sets the node’s user property with the given key to the given value. getUserPropBuffer <node>
Retrieves the entire user property buffer as a string containing all the user property settings. This is effectively the contents of the User Defined Properties box in the 3ds max Object Properties dialog. setUserPropBuffer <node> <string>
Sets the user property buffer to the given string. See the Node User-Defined Properties and Methods (p. 848) topic for more information on these methods. -- Inverse Kinematics Properties The following methods get and set the node’s IK values as seen in the Hierarchy panel, Object Parameters rollout. getRotTaskWeight <node>
Returns the rotation binding weight for the node. setRotTaskWeight <node>
Sets the rotation binding weight for the node. getPosTaskWeight <node>
Returns the position binding weight for the node. setPosTaskWeight <node>
Sets the position binding weight for the node. getTaskAxisState <node> <pos_or_rot_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
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. sets the axis to check: 0 specifies X, 1 specifies Y, 2 specifies Z. setTaskAxisState <node> <pos_or_rot_integer>
Sets the axis state for position or rotation binding to the specified boolean value. See getTaskAxisState() for a description of the parameters. mirrorIKConstraints <node> <pos_or_rot_integer>
Mirrors the specified IK constraints on the specified node’s transform controller about the specified axis. 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 <node>
Returns true if the can be bound to the <node> as a follow object, false otherwise. If the 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.
835
836
Chapter 11
|
3ds max Objects
Associated Methods: uniqueName <prefix>
Generates a unique scene node name from a prefix string by adding a series of digits, in the same manner the 3ds max does as you create objects in the scene. This name is only guaranteed to be unique until the next scene node creation. For example: $foo.name = uniqueName “foo”
See also MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) General Node Properties (p. 836) Node Transform Properties (p. 841) Node User-Defined Properties and Methods (p. 848) Nested Object Properties (p. 815) Class and Object Inspector Functions (p. 799) Dynamic Properties (p. 805) Node Subclasses (p. 849) NURBS Node Properties and Methods (p. 1397)
General Node Properties All the properties listed here are accessible on any node subclass. Unless otherwise noted, these properties can not be animated. <node>.name
String
default: varies
Get or set the scene object’s name. <node>.baseObject
A subclass of Node
default: varies
-- read-only
Retrieve the base object in a scene node. This has relevance in nodes that have modifiers present that change the node type as it is processed up the stack. For example, a line with an extrude modifier starts out as a Shape and turns into an Editable Mesh at the top of the stack, its so-called world state. The baseObject property gives you access to the base object in the modifier stack. Because the classOf() function on scene node objects returns the class of the world state object (the top of the stack), you can use the baseObject property to determine the class of the original object used to create the node. This property is read-only. <node>.material
Get or set the object’s material.
Material
default: undefined
General Node Properties
<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 object’s mesh after any modifiers have been applied, but before any space warps have been applied. This property is read-only unless the scene node or base object is an Editable Mesh object, in which case the specified TriMesh replaces the base object. See the Editable_Mesh : GeometryClass and TriMesh : Value (p. 1041) topic for more information on TriMesh and Editable Mesh.
837
838
Chapter 11
|
3ds max Objects
-- Target/LookAt Related Properties <node>.isTarget
Boolean
default: false
Returns true if then node is the target of another object’s LookAt controller, false if it is not. If the object is the automatically created target object of a light’s or camera’s LookAt controller, and you set this property to false, you can delete the target object without causing the light or target to be deleted. <node>.lookAt
Node
default: undefined
Get a node that is looking at <node>, or set a node to look at <node>. This is the converse of the <node>.target property. If <node> is not the target of some object’s LookAt controller, the value undefined is returned. If <node> is the target of more than one object, only one such object is returned. If this property is used to set <node> as the target of another object, a LookAt controller is automatically assigned to that object. <node>.target
Node
default: undefined
Get or set the target node for <node>’s LookAt controller. Returns undefined if there is no target or the node does not have a LookAt controller. If this property is used to set an object as the target of <node>, a LookAt controller is automatically assigned to <node>. Exercise care if you assign a node to the target property. When you specify a target object, 3ds max stores with the target object the last object it was assigned as a target of. If you delete the target object, the behavior of 3ds max is to also delete the object looking at it. If the target object is a targetobject class object, deleting an object looking at it will also delete the target object, even if another object is also looking at it. <node>.targetDistance
Float
default: undefined
Get or set the distance from the node to its target. Returns undefined if <node> does not have a target. Setting this property moves the target along the object-to-target vector to the distance specified. For example, $spot01.targetDistance $cam2.targetDistance = 100
-- Viewport Related Properties <node>.isSelected
Boolean
default: false
Get or set whether the node is selected. <node>.isHidden
Boolean
default: false
Get or set whether the node is flagged as hidden in the viewports. A node may be hidden even if this property is false. If the node’s category is marked as hidden in the Hide by Category rollout in the Display panel, or if the node is flagged as frozen and Hide Frozen Objects is on in the Hide rollout in the Display panel, the node will be hidden regardless of this property’s value. <node>.xray
Boolean
default: false
Get or set whether the node is displayed in See Through mode in shaded viewports. <node>.ignoreExtents
Boolean
default: false
Get or set whether the extents of the node is ignored when performing a zoom extents.
General Node Properties
<node>.boxMode
Boolean
default: false
Get or set whether the node is displayed in box mode in the viewports. <node>.allEdges
Boolean
default: false
Get or set whether all the node’s edges are displayed in the viewports. <node>.backFaceCull
Boolean
default: false
Get or set whether the node’s back faces are culled (not displayed) in the viewports. <node>.wireColor
Color
default: random color
Get or set the node’s wireframe color <node>.showLinks
Boolean
default: false
Get or set whether to display a wireframe representation of the hierarchical link(s) from the node to its children. <node>.showLinksOnly
Boolean
default: false
Get or set whether to display only the wireframe representation of the hierarchical link(s) for the node. Setting this property to true also sets showLinks to true. <node>.isFrozen
Boolean
default: false
Get or set whether the node is frozen in the viewports. <node>.showTrajectory
Boolean
default: false
Get or set whether the node’s trajectory is displayed in the viewports. <node>.showVertexColors
Boolean
default: false
Get or set whether to display the effect of assigned vertex colors for the node in shaded viewports. <node>.vertexColorsShaded
Boolean
default: false
Get or set whether the vertex color display for the node is shaded in the viewports. When true, the colors are unshaded and appear in their pure RGB values. When false, the colors appear like any other assigned color in the viewports. <node>.isDependent
Boolean
default: false
Returns true if the node has its dependent flag set, otherwise returns false. A node is dependent in the sense of 3ds max’s Views/Show Dependencies mode. When the Modify panel is open, Show Dependencies will show all the nodes that are dependent on the current modifier or object being editing by highlighting them in green, and the dependent flag for the node is set. This property will always return false if the Modify panel is closed, or if Views/Show Dependencies is off. This property is read-only. -- Rendering Related Properties <node>.castShadows
Boolean
default: true
Get or set whether the node casts shadows when rendered. This property parallels the Cast Shadows property in an object’s right-click Object Properties dialog. <node>.receiveShadows
Boolean
default: true
Get or set whether the node casts shadows when rendered. This property parallels the Receive Shadows property in an object’s right-click Object Properties dialog.
839
840
Chapter 11
|
3ds max Objects
<node>.gbufferChannel
Integer
default: 0
Get or set the node’s g-buffer Object ID channel value. Valid object ID values in 3ds max range from 0 to 65535. This property parallels the G-Buffer Object Channel property in an object’s right-click Object Properties dialog. <node>.visibility
Boolean
default: true
-- animatable
This is a boolean property (unlike its value as a signed float in the 3ds max Track View) true or on denotes visible, false or off invisible. Animate this property to control an node’s visibility at render-time, for example: animate on ( at time 0 $foo.visibility = on at time 35 $foo.visibility = off at time 57 $foo.visibility = on )
The controller for this property is stored in the 1st subAnim of the node. You can access this controller as: <node>[1].controller
-- the visibility controller
You can also get a node’s visibility controller using the getVisController() method. <node>.inheritVisibility
Boolean
default: true
Get or set whether the node inherits the visibility of its parent object (if any). This property parallels the Inherit Visibility property in an object’s right-click Object Properties dialog. <node>.renderable
Boolean
default: true
Get or set whether the node is renderable. <node>.renderOccluded
Boolean
default: false
Get or set whether to Render Occluded Objects behind the node. This property parallels the Render Occluded Objects property in an object’s right-click Object Properties dialog. <node>.motionBlurOn
Boolean
default: true
Get or set whether motion blur is enabled for the object. This property parallels the Motion Blur Enabled property in an object’s right-click Object Properties dialog. <node>.motionBlurOnController
Controller
default: undefined
Get or set the motion blur on/off controller used for the node. <node>.motionBlur
Name
default: #none
Get or set the type of motion blur to be used for the node. Valid parameter values are: #none, #object, and #image. For backward compatibility, this property can also be set to false for none or true for object motion blur. This property parallels the Motion Blur type specified in an object’s right-click Object Properties dialog.
Node Transform Properties
<node>.imageMotionBlurMultiplier Float
default: 1.0
-- animatable
Get or set the node’s image motion blur multiplier value. The controller for this property is stored in the 6th subAnim of the node. You can access this controller as: <node>[6].controller
-- the imageMotionBlurMultiplier controller
You can also get and set a node’s imageMotionBlurMultiplier controller using the getImageBlurMultController() and setImageBlurMultController() methods. <node>.rcvcaustics
Boolean
default: true
Get or set whether the node receives caustics. Caustics are not supported by the 3ds max scanline renderer. <node>.generatecaustics
Boolean
default: false
Get or set whether the node generates caustics. Caustics are not supported by the 3ds max scanline renderer. <node>.rcvGlobalIllum
Boolean
default: true
Get or set whether the node receives global illumination. Global illumination is not supported by the 3ds max scanline renderer. <node>.generateGlobalIllum
Boolean
default: false
Get or set whether the node generates global illumination. Global illumination is not supported by the 3ds max scanline renderer.
Node Transform Properties Unless otherwise noted, the following transform properties are always interpreted with respect to the current working coordinate system as defined by the currently active coordsys context (p. 681). The default coordsys is world. The pos, rotation, and scale properties of a node are aliases to the corresponding subcontroller for the node’s transform controller. If the transform controller does not have one of these subcontrollers, accessing the corresponding node property will result in an “Unknown property” error message. For example, the LookAt controller does not have a Rotation subcontroller, and the IK controller does not have any subcontrollers. You can still access the transform values using the Matrix3 properties of the node’s transform property, for example, objpos=obj.transform.translationpart. <node>.transform
: : : : : :
Matrix3 -- can read/write to. If written to, the Matrix3 value is decomposed into its position, rotation, and scale values, and these values are stored in the respective position, rotation, and scale controllers, if those controllers exist and can be written to.
<node>.pos <node>.pos.controller <node>.pos.isAnimated <node>.pos.keys <node>.pos.track
: : : : :
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>.rotation
: Quat
841
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
: : : : : : :
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
<node>.scale <node>.scale.controller <node>.scale.isAnimated <node>.scale.keys <node>.scale.track
: : : : :
Point3 -- fraction Controller -- can use .track synonym throughout Boolean, read-only -- true if scale is animated MAXKeyArray Controller -- synonym of .scale.controller
<node>.dir
: Point3 -- local z-axis direction vector
Rotates node so that the node’s Z axis points in the specified direction. The node is rotated around its Z axis such that the Y axis points as much as possible in the world -Z direction. <node>.max bounding box <node>.min bounding box <node>.center
: Point3, read-only -- max coordinates of node’s
: Point3 -- coordinates of center of node’s bounding box
<node>.transform
: Matrix3 -- node’s main transformation matrix
: Point3, read-only -- min coordinates of node’s
Note that rotation in the internal transformation matrices is left-handed in contradiction to the 3ds max user interface and MAXScript. Take care when mixing rotation derived from these matrices and rotation used in rotation-related functions or from rotation properties. <node>.pivot
: Point3
<node>.objectOffsetPos <node>.objectOffsetRot <node>.objectOffsetScale
: Point3 : Quat : Point3
-- node’s pivot point position
Node geometry’s position, rotation, and scale offset from the pivot in world coordinates. <node>.objectTransform
: Matrix3, read-only
Node geometry’s offset in world coordinates.
See also Using Node Transform Properties (p. 843)
Using Node Transform Properties
Using Node Transform Properties This topic provides information on three transforms related to nodes -- the Node Transform Matrix, the Object-Offset Transform Matrix, and the Object Transform Matrix. The Node and Object-Offset Transform Matrices are stored by 3ds max. The Object Transform Matrix is derived from these two matrices. This topic also presents information on how these transforms are constructed and how they are used by 3ds max, and how they can be accessed and manipulated in MAXScript. The Pivot Point -- The Node Transform Matrix The transform center, or pivot point, is the location about which a rotation takes place, or to and from which a scale occurs. All nodes in 3ds max have a pivot point. You can think of the pivot point as representing a node’s local center and local coordinate system. The pivot point of a node is used for a number of purposes: •
As the center for rotation and scaling.
•
Defines the transform origin for linked children.
•
Defines the joint location for Inverse Kinematics.
The thing that most users think of as the pivot point -- graphically represented in 3ds max by the axis tripod that is displayed when a node is selected and the coordinate system is set to local -- is actually just a visual representation of the node’s transform matrix. The node’s transform matrix is what is controlled by the transform controller that places the node in the scene. The transform controller controls the transform relative to the node’s parent. Construction of the Node Transform Matrix for the PRS Transform Controller The PRS controller uses sub-controllers to create the final transform. There are three sub-controllers -- one for Position, one for Rotation, and one for Scale. The PRS controller is passed the transform matrix of the node’s parent. If the node has no parent, the matrix starts out as the identity matrix. The PRS controller first calls the position controller, then the rotation controller, then the scale controller. First the position controller pre-multiplies the input matrix is by the position value. If the matrix passed is the identity matrix, this is equivalent to setting the bottom row (the translation row) of the matrix. Next, the rotation controller pre-multiplies the matrix by the rotation value. Finally, the scale controller pre-multiplies the matrix by the scale value. Some position controllers can actually apply more than just position to the matrix. For example, the Path Controller, when the Follow switch is active, actually applies some rotation to have the node remain tangent to the path it is following. Thus when the rotation controller receives the matrix, the matrix already has some rotation applied. The matrix, after the position, rotation and scale controllers have updated it, becomes the Node Transform Matrix 3ds max uses to position, rotate and scale nodes in the scene. Thus, the entire transform is: Node Transform Matrix = Controller Scale * Controller Rotation * Controller Position * Parent Transform Matrix
843
844
Chapter 11
|
3ds max Objects
The Object-Offset Transform Matrix The Object-Offset Transform Matrix provides an offset of the geometry of an object from its node. One can see a node’s pivot point graphically represented in 3ds max by selecting a node, going to the Hierarchy branch of the Hierarchy panel, selecting the ‘Pivot’ button, and choosing either the ‘Affect Pivot Only’ or ‘Affect Object Only’ button. This displays a large axis tripod that shows the location and orientation of the node’s pivot point. By choosing one of these buttons, and using the Move/Rotate/Scale toolbar controls, a user can manipulate the position of the geometry of the object independent of the pivot point. Or they may manipulate the pivot point independent of the geometry of the object. The way the user is able to independently manipulate the pivot and the object is managed internally using the Object-Offset Transform Matrix. The Object-Offset Transform Matrix affects how the geometry of the object is related to the node. The Object-Offset Transform Matrix transforms the geometry of the object itself some amount from the node. To understand how the Object-Offset Transform Matrix is used, consider the following example from the 3ds max user interface. In the Hierarchy branch under ‘Pivot’, when the user has chosen the ‘Affect Object Only’ button they are free to move the geometry of the object around independent of the node. The pivot point does not move -- only how the geometry of the object is oriented relative to the pivot. What is happening internally is that the Object-Offset Transform Matrix is being manipulated. This transform is simply an additional offset that is applied to the geometry of the object that is independent of the node. The Object-Offset Transform Matrix is not inherited by any child nodes. As another example consider the use of the ‘Affect Pivot Only’ button. This mode lets the user move the pivot without affecting the position of the geometry of the object. When the user moves the pivot point, what is actually happening is the Node Transform Matrix is being altered (to re-orient the pivot point), then the Object-Offset Transform Matrix is adjusted to counter the node transform. This lets the geometry of the object stay in the same place while the pivot point moves around. Construction of the Object-Offset Transform Matrix The Object-Offset Transform Matrix consists of separate position, rotation and scale transforms. Like the Node Transform Matrix, these are applied by pre-multiplying position, then rotation, then scale. Thus the Object-Offset Transform Matrix is: Object-Offset Transform Matrix = Offset Scale * Offset Rotation * Offset Position
Unlike the Node Transform Matrix, the Object-Offset Transform Matrix is not inherited by children of the node.
Using Node Transform Properties
The Object Transform Matrix The Object Transform Matrix is the transform matrix an object’s geometry needs to be multiplied by to transform it into world space. This transform matrix includes the parent transform, the Node Transform, and the Object Offset Transform. Thus, the entire transform used to transform the points of any object is: Object Transform Matrix = Object-Offset Transform Matrix * Node Transform Matrix
This matrix could be used, for example, if you have a mesh object and wanted to get the world space coordinate of one of its vertices. You could do this by taking the vertex coordinate in object space and multiplying it by the Object Transform Matrix. Using the Node Transforms in MAXScript The node transform properties are derived from and modify the values of the transform controllers associated with the node, they are not associated directly with the node’s main transformation matrix. This has a number of consequences: 1.
Assigning to a transform property (such as pos or rotation) with animation enabled plants keyframes only in the associated controller. If you modify the node’s transform matrix directly, keyframes are generated for all the transform controllers for that node.
2.
Rotation properties and in fact all rotation-related functions in MAXScript reflect the direction convention used in the 3ds max user interface. This convention is the right-hand rule, namely, positive angles rotate counter-clockwise about positive axes. Internally, however, 3ds max stores rotations in node matrices using the left-hand rule. It is important to remember this inversion when working directly with node transform matrices using the transform and objectTransform properties. You’ll need to invert rotations (for example, by multiplying axes by [-1,-1,-1] or using the inverse() function on quaternions) when mixing them with 3ds max and MAXScript standard rotations.
3.
Certain controllers, such as the path controller with bank or follow enabled, affect the rotation of a node by adjusting the node’s transform matrix directly and this rotation is not reflected in rotation controller values. This means, in this example for instance, that bank and follow rotations are not directly accessible through the rotation property, you need to access them directly in the node’s transformation matrix using something like: r = $foo.transform.rotationPart
which returns a quaternion. Remember, however, that the 3ds max rotation direction convention is not reflected when directly accessing a transform matrix, so to use this value in other rotation operations you would need to invert it: $baz.rotation = inverse r
A node’s transform property contains the Node Transform Matrix, and reflects the position, rotation, and scale of the node’s pivot point. Accessing the pivot property will return the same value as the pos property. Setting the pivot property will move the pivot point location to the specified coordinates, however the node’s geometry will not be moved.
845
846
Chapter 11
|
3ds max Objects
A node’s objectoffsetpos, objectoffsetrot, and objectoffsetscale properties contain the component parts of the Object-Offset Transform Matrix. A node’s objecttransform property contains the Object Transform Matrix. Since this matrix is a combination of the Node Transform and Object-Offset Transform Matrices, this property is read only. Note that these properties are always returned in the World coordinate system context. The following script shows the initial node transform properties for a 25x25x25 box created at [75,75,0], after moving the pivot point to [50,50,0], and after rotating only the pivot point 35 degrees about the Z axis. Also shown is the position of one of the box’s vertices after each transform. Script: fn DumpXForms obj = ( -- output node transform properties format “%:\t%\n” “transform” obj.transform format “%:\t%\n” “position “ obj.pos format “%:\t%\n” “rotation “ obj.rotation -- output node’s pivot point location format “%:\t%\n” “pivot “ obj.pivot -- output object offsets format “%:\t%\n” “objectoffsetpos “ obj.objectoffsetpos format “%:\t%\n” “objectoffsetrot “ obj.objectoffsetrot format “%:\t%\n” “objectoffsetscale” obj.objectoffsetscale -- output object transform format “%:\t%\n” “objecttransform “ obj.objecttransform -- output vertex position in local and world coordinates format “%:\t%\n” “vert 1 (local) “ (in coordsys local getvert obj 1) format “%:\t%\n” “vert 1 (world1) “ (in coordsys world getvert obj 1) -- calculate and output vertex position in world coordinates local v_pos=(in coordsys local getvert obj 1)* obj.objecttransform format “%:\t%\n” “vert 1 (world2) “ v_pos ) --- define function for rotating only the pivot point fn RotatePivotOnly obj rotation= ( local rotValInv=inverse (rotation as quat) animate off in coordsys local obj.rotation*=RotValInv obj.objectoffsetrot*=RotValInv obj.objectoffsetpos*=RotValInv ) -( b=box pos:[75,75,0] -- create a 25x25x25 box, vertex 1 at [62.5,62.5,0] (world) convertToMesh b -- convert box to mesh so we can access the vertex location DumpXForms b -- print transforms b.pivot=[50,50,0] -- move pivot only to [50,50,0] DumpXForms b -- print transforms RotatePivotOnly b (EulerAngles 0 0 35) -- rotate pivot only 35 degrees about local Z DumpXForms b -- print transforms )
Using Node Transform Properties
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]
847
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: = <property1> = <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>
retrieves the node’s user property with the given key as a string. is either a String or a Name value. If the key does not exist, a value of undefined is returned. setUserProp <node>
sets the node’s user property with the given key to the given value getUserPropBuffer <node>
retrieves the entire user property buffer as a string containing all the user property settings. This is effectively the contents of the User Defined Properties box in the 3ds max Object Properties dialog setUserPropBuffer <node> <string>
sets the user property buffer to the given string The following two example code fragments save and load user properties for objects in a scene. The first code fragment creates a file and loops through all objects outputting for each the object name and user property buffer string. Note that the object name goes out in a form that will come back in (via a readValue()) as a direct reference to a scene object. Also, the user property string is output using print() so it will be in a quoted form to be read as one (long) string literal by a corresponding readValue(). The second code fragment reads in the file created by the first piece and applies the user properties to any same-named object in the current scene. Note that readValue() can read in pathnames ($) 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
-- 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)
849
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
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)
851
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
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: .length
Float
default: 25.0
-- animatable
Sets the length of the box object. .width
Float
default: 25.0
-- animatable
Sets the width of the box object. .height
Float
default: 25.0
-- animatable
Sets the height of the box object. .lengthsegs Length_Segments
Integer
default: 1
-- animatable, alias:
Sets the number of divisions along the length of the object. .widthsegs
Integer
default: 1
-- animatable, alias: Width_Segments
Sets the number of divisions along the width of the object. .heightsegs Height_Segments
Integer
default: 1
-- animatable, alias:
Sets the number of divisions along the height of the object. .mapcoords
Boolean
default: false
When on, generates coordinates for applying mapped materials to the box.
853
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: .Back_Length
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 1
-- animatable
Sets the length of the back edge. .Side_Length
Float
Sets the length of the side edge. .Front_Length
Float
Sets the length of the front edge. .Back_Width
Float
Sets the width of the back edge. .Side_Width
Float
Sets the width of the side edge. .Front_Width
Float
Sets the width of the front edge. .height
Float
Sets the overall height of the object. .Back_Segments
Integer
The number of segments along the back edge of the object. .Side_Segments
Integer
default: 1
-- animatable
The number of segments along the side edge of the object. .Front_Segments
Integer
default: 1
-- animatable
The number of segments along the front edge of the object. .Width_Segments
Integer
default: 1
-- animatable
The number of segments along the width of the object. .Height_Segments
Integer
default: 1
-- animatable
The number of segments along the height of the object. Note: The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.
Capsule : GeometryClass
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: .radius
Float
default: 15.0
-- animatable
default: 25.0
-- animatable
The radius of the capsule. .height
Float
The height of the capsule. .heighttype
Integer
default: 1
Set what .height specifies: Overall Centers (not including domed caps) .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. .heightsegs height_segments
Integer
default: 1
-- animatable; alias:
The number of divisions along the capsule’s major axis. .smooth
Boolean
default: true
-- animatable
When on, blends the faces of the capsule, creating a smooth appearance in rendered views. .smooth_on
Integer
default: 1
-- animatable
Smooth_on is an integer alias of smooth: OFF ON .sliceon
Boolean
default: false -- animatable
Turns on/off the Slice function. .slice_on
Integer
default: 0
Slice_on is an integer alias of sliceon: OFF ON
-- animatable
855
856
Chapter 11
|
3ds max Objects
.slicefrom slice_from
Float
default: 0.0
-- animatable, angle; alias:
Sets the starting angle (on the local Z-axis) for slicing. .sliceto slice_to
Float
default: 0.0
-- animatable, angle; alias:
Sets the angle (on the local Z-axis) to slice to. .mapCoords
Boolean
default: false
When on, sets up the required coordinates for applying mapped materials to the capsule.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
ChamferBox : GeometryClass Constructor: chamferBox ...
Properties: .length
Float
default: 0.1
-- animatable
Float
default: 0.1
-- animatable
Float
default: 0.1
-- animatable
Float
default: 0.01
-- animatable
The length of the object. .width
The width of the object. .height
The height of the object. .Fillet
Slices off the edges of the chamferbox. The higher the number, the more filleted the chamferbox becomes. .Length_Segments
Integer
default: 1
-- animatable
The number of divisions along the length of the object. .Width_Segments
Integer
default: 1
-- animatable
The number of divisions along the width of the object. .Height_Segments
Integer
default: 1
-- animatable
The number of divisions along the height of the object. .Fillet_Segments
Integer
default: 3
-- animatable
The number of segments in the filleted edges of the box. Adding fillet segments increases the edge roundness.
ChamferCyl : GeometryClass
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: .radius
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
The radius of the chamfered cylinder. .height
Float
The dimension along the central axis. Negative values create the chamfered cylinder below the construction plane. .Fillet
Float
default: 0.0
-- animatable
Slices off the edges of the chamfered cylinder. The higher the number, the more filleted the cylinder becomes. .Height_Segments
Integer
default: 1
-- animatable
The number of divisions along the corresponding axis. .Fillet_Segments
Integer
default: 1
-- animatable
The number of segments in the filleted edges of the box. Adding fillet segments curves the edges, producing a chamfered cylinder. .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. .Cap_Segments
Integer
default: 1
-- animatable
The number of concentric divisions along the center of the chamfered cylinder’s top and bottom .Smooth Boolean
default: true -- animatable
When on, blends the faces of the chamfered cylinder, creating a smooth appearance in rendered views.
857
858
Chapter 11
|
3ds max Objects
.Smooth_On
Integer
default: 1
-- animatable
Integer alias for .smooth: OFF ON .SliceOn Boolean
default: false
-- animatable
Turn on/off the slice function. .Slice_On
Integer
default: 0
Float
default: 0.0
-- animatable
Integer alias for .slice_on: OFF ON .Slice_From
-- animatable, angle
Sets the starting angle (on the local Z-axis) for slicing. .Slice_To
Float
default: 0.0
-- animatable, angle
Sets the angle (on the local Z-axis) to slice to. Note: The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Cone : GeometryClass Constructor: cone ...
Properties: .radius1
Float
default: 15.0
-- animatable, alias: Radius_1
default: 0.0
-- animatable, alias: Radius_2
The first radius of the cone. .radius2
Float
The second radius of the cone. .height
Float
default: 25.0
-- animatable
Height along the central axis. Negative values create the cone below the construction plane. .heightsegs Height_Segments
Integer
default: 5
-- animatable, alias:
The number of divisions along the cone’s major axis.
Cylinder : GeometryClass
.capsegs
Integer
default: 1
-- animatable, alias: Cap_Segments
The number of concentric divisions around the center of the cone’s top and bottom. .sides
Integer
default: 24
-- animatable
The number of sides around the cone. Higher numbers shade and render as true circles with Smooth selected. Lower numbers create regular polygonal objects with Smooth off. .smooth
Boolean
default: true
-- animatable
When on, blends the faces of the cone, creating a smooth appearance in rendered views. .slice
Boolean
default: false
-- animatable, alias: sliceon
Turns on/off slice function. .Slice_On
Integer
default: 0
Integer alias for .slice: OFF ON .sliceFrom Slice_From
Float
default: 0.0
-- animatable, angle, alias:
Sets the starting angle (on the local Z-axis) for slicing. .sliceTo
Float
default: 0.0
-- animatable, angle, alias: Slice_To
Sets the angle (on the local Z-axis) to slice to. .mapCoords
Boolean
default: false
When on, sets up required coordinates for applying mapped materials to the cone.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Cylinder : GeometryClass Constructor: cylinder ...
Properties: .radius
Float
default: 15.0
-- animatable
default: 25.0
-- animatable
The radius of the cylinder. .height
Float
Height along the central axis. Negative values create the cylinder below the construction plane. .heightsegs Height_Segments
Integer
default: 1
-- animatable, alias:
The number of divisions along the cylinder’s major axis.
859
860
Chapter 11
|
3ds max Objects
.capsegs Cap_Segments
Integer
default: 1
-- animatable, alias:
The number of concentric divisions around the center of the cylinder’s top and bottom. .sides
Integer
default: 24
-- animatable
The number of sides around the cylinder. With Smooth on, higher numbers shade and render as true circles. With Smooth off, lower numbers create regular polygonal objects. .smooth
Boolean
default: true
-- animatable
When on, the faces of the cylinder are blended together, creating a smooth appearance in rendered views. .slice
Boolean
default: false
-- animatable, alias: sliceon
Turns on/off slice function. .Slice_On
Integer
default: 0
Integer alias for .slice: OFF ON .sliceFrom Slice_From
Float
default: 0.0
-- animatable, angle, alias:
Sets the starting angle (on the local Z-axis) for slicing. .sliceTo Slice_To
Float
default: 0.0
-- animatable, angle, alias:
Sets the angle (on the local Z-axis) to slice to. .mapCoords
Boolean
default: false
When on, sets up the required coordinates for applying mapped materials to the cylinder.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Gengon : GeometryClass
Gengon : GeometryClass Generic polygon. Constructor: gengon ...
Properties: .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. .radius
Float
default: 0.0
-- animatable
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
The radius of the gengon. .Fillet
The width of the fillet area. .height
Float
Height along the central axis. Negative values create the gengon below the construction plane. .Side_Segments
Integer
default: 1
-- animatable
The number of divisions around the gengon. .Height_Segments
Integer
default: 1
-- animatable
The number of divisions along the gengon’s major axis. .Fillet_Segments
Integer
default: 1
-- animatable
The number of divisions for the edge filleting. The higher this setting, the rounder the fillet appears. Note: The Generate Mapping Coordinates and Smooth properties are not accessible to MAXScript in 3ds max R4.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
861
862
Chapter 11
|
3ds max Objects
Geosphere : GeometryClass Constructor: geosphere ...
Properties: .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.) .typeInPos
Point3
default: [0,0,0]
The point3 position of the geosphere. .typeInRadius
Float
default: 25.0
The radius of the geosphere. .radius
Float
default: 25.0
-- animatable
default: 4
-- animatable, alias:
The radius of the geosphere. .segs segments
Integer
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. .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.) .smooth
Boolean
default: true
-- animatable
When on, applies smoothing groups to the surface of the sphere. .hemisphere
Boolean
default: false
-- animatable
default: false
-- alias:
When on, creates a half-sphere. .baseToPivot
Boolean
Base_to_Pivot
Sets the pivot point location. When on, the pivot is at the bottom of the sphere. When off, the pivot is at the center of the sphere. This option has no effect when Hemisphere is on. .mapCoords Generate_mapping_coords
Boolean
default: false
-- alias:
When on, applies default mapping coordinates to the geosphere.
Hedra : GeometryClass
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: .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.) .p .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. .scalep
Float
default: 1.0
-- animatable
Controls the axis of reflection for the p facet of a polyhedron. .scaleq
Float
default: 1.0
-- animatable
Controls the axis of reflection for the q facet of a polyhedron. .scaler
Float
default: 1.0
-- animatable
Controls the axis of reflection for the r facets of a polyhedron. .P_Scale
Float
default: 100.0
Controls the axis of reflection for the p facet of a polyhedron.
863
864
Chapter 11
|
3ds max Objects
.Q_Scale
Float
default: 100.0
Controls the axis of reflection for the q facet of a polyhedron. .R_Scale
Float
default: 100.0
Controls the axis of reflection for the r facets of a polyhedron. .vertices
Integer
default: 0
-- alias: vertType
Sets the internal geometry of each facet of the polyhedron: Basic (Facets are not subdivided beyond the minimum.) Center (Each facet is subdivided by placing an additional vertex at its center, with edges from each center point to the facet corners.) Center & Sides (Each facet is subdivided by placing an additional vertex at its center, with edges from each center point to the facet corners, as well as to the center of each edge. Compared to Center, Center & Sides doubles the number of faces in the polyhedron.) .radius
Float
default: 25.0
-- animatable
The radius of any polyhedron in current units. .mapCoords
Boolean
default: false
When on, sets up required coordinates for applying mapped materials to the hedra. Note: The (scalep, scaleq, scaler) and (P_Scale, Q_Scale, R_Scale) sets of scale parameters are aliases of each other, except that the first set is stored as fractions, and the second set is stored as percentages. This second set of parameters are those shown in the command panels and in Track View. In order to access the vertices property for hedra, you need to access the property via the baseobject property of the node. This is because vertices is also a property name for all nodes, and conflicts with the hedra’s vertices property. For example: MyHedra.baseobject.vertices=1
-- set Vertices option to Center
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
L_Ext : GeometryClass
L_Ext : GeometryClass Constructor: l_ext ...
Note: This class is not available in 3D Studio VIZ. Properties: .Side_Length
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
Float
default: 0.0
-- animatable
Integer
default: 1
-- animatable
The length of the side edge. .Front_Length
Float
The length of the front edge. .Side_Width
Float
The width of the side edge. .Front_Width
Float
The width of the front edge. .height
The height of the object. .Side_Segments
Number of segments along the side edge. .Front_Segments
Integer
default: 1
-- animatable
Number of segments along the front edge. .Width_Segments
Integer
default: 1
-- animatable
Number of segments along the width of the object. .Height_Segments
Integer
default: 1
-- animatable
Number of segments along the height of the object. Note: The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
865
866
Chapter 11
|
3ds max Objects
OilTank : GeometryClass Constructor: oilTank ...
Properties: .radius
Float
default: 0.0
-- animatable
Float
default: 0.0
-- animatable
The radius of the oiltank. .height
The height along the central axis. Negative values create the oiltank below the construction plane. .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. .blend
Float
default: 0.0
-- animatable
When greater than 0, creates a bevel at the edge of the caps. .sides
Integer
default: 12
-- animatable
Sets the number of sides around the oiltank. To create a smoothly rounded object, use a higher number of sides and turn Smooth on. To create an oiltank with flat sides, use a lower number of sides and turn Smooth off. .Height_Segments
Integer
default: 1
-- animatable
Sets the number of divisions along the oiltank’s major axis. .Smooth_On
Integer
default: 1
-- animatable
Integer
default: 0
-- animatable
Float
default: 0.0
-- animatable, angle
Turn on/off smooth: OFF ON .Slice_On
Turn on/off slice: OFF ON .Slice_From
Sets the starting angle (on the local Z-axis) for slicing. .Slice_To
Float
default: 0.0
-- animatable, angle
Sets the angle (on the local Z-axis) to slice to. Note: The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.
Plane : GeometryClass
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: .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.) .typeinPos
Point3
default: [0,0,0]
Position of the plane in the World Space Coordinate system. .typeinLength
Float
default: 25.0
Float
default: 25.0
Float
default: 25.0
-- animatable
Float
default: 25.0
-- animatable
Integer
default: 4
-- animatable, alias:
Length of the plane object. .typeinWidth
Width of the plane object. .length
Length of the plane object. .width
Width of the plane object. .lsegs Length_Segments
Number of divisions along the length of the plane object. .wsegs Width_Segments
Integer
default: 4
-- animatable, alias:
Number of divisions along the width of the plane object. .density
Float
default: 1.0
-- animatable
Specifies the factor by which the number of segments in both length and width are multiplied at render time. .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.
867
868
Chapter 11
|
3ds max Objects
.mapCoords
Boolean
default: false -- alias: Mapping
When on, generates coordinates for applying mapped materials to the box. Note: The renderScale property is a multiplier applied to the Plane’s length and width property values at render time. The density property is a multiplier applied to the Plane’s lsegs and wsegs property values at render time.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Prism : GeometryClass Constructor: prism ...
Properties: .side1Length
Float
default: 25.0
-- animatable, alias: Side_1_Length
Sets the length of triangle’s first side. .side2Length
Float
default: 25.0
-- animatable, alias: Side_2_Length
Sets the length of triangle’s second side. .side3Length
Float
default: 25.0
-- animatable, alias: Side_3_Length
Sets the length of triangle’s third side. .height
Float
default: 10.0
-- animatable
The height of the prism’s central axis. .side1Segs
Integer
default: 1
-- animatable, alias: Side_1_Segments
The number of divisions along the first side. .side2Segs
Integer
default: 1
-- animatable, alias: Side_2_Segments
The number of divisions along the second side. .side3Segs
Integer
default: 1
-- animatable, alias: Side_3_Segments
The number of divisions along the third side. .heightsegs
Integer
default: 1
-- animatable, alias: Height_Segments
The number of divisions along the central axis. .mapCoords
Boolean
default: false
When on, sets up the required coordinates for applying mapped materials to the prism.
Pyramid : GeometryClass
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: .width
Float
default: 25.0
-- animatable
default: 25.0
-- animatable
default: 25.0
-- animatable
default: 1
-- animatable, alias:
The width of the pyramid. .depth
Float
The depth of the pyramid. .height
Float
The height of the pyramid. .widthsegs Width_Segments
Integer
The number of divisions along the width of the pyramid. .depthSegs Depth_Segments
Integer
default: 1
-- animatable, alias:
The number of divisions along the depth of the pyramid. .heightsegs Height_Segments
Integer
default: 1
-- animatable, alias:
The number of divisions along the height of the pyramid. .mapCoords
Boolean
default: false
When on, sets up required coordinates for applying mapped materials to the pyramid.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
869
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. .’max diameter’ radius
Float
default: 500.0 --
animatable; alias:
The outside radius of the ringwave. .’Radius Segs’ radial_Segments
Integer
default: 1
--
animatable; alias:
The segment count between the inner and outer surfaces in the direction of radius. .’ring width’ Ring_Width
Float
default: 1.0
--
animatable; alias:
The mean ring width as measured inward from the outer radius. .’ring segments’ sides
Integer
default: 200 --
animatable; alias:
The number of segments in the circumferential direction for both the inner, outer, and end (cap) surfaces. .height
Float
default: 0.0
-- animatable
The height of the ringwave along its major axis. .’Height Segs’ Height_Segments
Integer
default: 1
--
animatable; alias:
The number of segments in the direction of the height. .Repeat
Integer
default: 2
-- animatable
Repeat = 0 - Cyclic Growth; 1 - Grow and Stay; 2 - No Growth .’time on’
Integer
default: 0
-- animatable; alias: Start_Time
The time where the ringwave appears, and begins to grow. .’time growing’
Integer
default: 9600
-- alias: Grow_Time
The time after .’time on’ that the ringwave takes to reach full size. .’display until’ End_Time
Integer
default: 16000 --
animatable; alias:
The time after which the ringwave disappears. .’Outer Edge Breakup’ Outer_Edge_Breakup
Boolean
default: false
-- alias:
Integer
default: 1 -- alias:
Turns on breakup of the outer edge. .’Major Cycles Outer’ Outer_Edge_Major_Cycles
The number of major waves around the outer edge.
RingWave : GeometryClass
.’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. .’Major Cycle Flux Per Outer’ Integer alias: Outer_Edge_Major_Crawl_Time
default: 16000
--
animatable;
The time each major wave takes to move around the outer circumference of the RingWave. .’Minor Cycles Outer’ Outer_Edge_Minor_Cycles
Integer
default: 1 -- alias:
The number of random-sized smaller waves in each major cycle. .’Minor Cycle Flux Outer’ alias: Outer_Edge_Minor_Flux
Float
default: 0.0
--
animatable;
The average size of the smaller waves, expressed as a percentage of the unmodulated width. .’Minor Cycle Flux Per Outer’ Integer alias: Outer_Edge_Minor_Crawl_Time
default: -16000 --
animatable;
The time each minor wave takes to move across its respective major wave. .’Inner Edge Breakup’ Inner_Edge_Breakup
Boolean
default: true -- alias:
Turns on the breakup of the inner edge. .’Major Cycles Inner’ Inner_Edge_Major_Cycles
Integer
default: 11 -- alias:
The number of major waves around the inner edge. .’Major Cycle Flux Inner’ alias: Inner_Edge_Major_Flux
Float
default: 25.0
-- animatable;
The size of the major waves, expressed as a percentage of the unmodulated width. .’Major Cycle Flux Per Inner’ Integer alias: Inner_Edge_Major_Crawl_Time
default: 19360 --
animatable;
The time each major wave takes to move around the inner circumference of the RingWave. .’Minor Cycles Inner’ Inner_Edge_Minor_Cycles
Integer
default: 29 -- alias:
The average size of the smaller waves, expressed as a percentage of the unmodulated width. .’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. .’Minor Cycle Flux Per Inner’ Integer alias: Inner_Edge_Minor_Crawl_Time
default: -4320 --
animatable;
The time each minor wave takes to move across its respective major wave. .repeats
Integer
default: 2
The number of times the ringwave cycle repeats.
--
radio button number
871
872
Chapter 11
|
3ds max Objects
.’Mapping Coords’
Boolean
default: false
When on, assigns mapping coordinates to the ringwave. .Smoothing
Boolean
default: false
When on, smooths the surface of the ringwave.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Sphere : GeometryClass Constructor: sphere ...
Properties: <Sphere>.radius
Float
default: 25.0
-- animatable
default: 16
-- animatable, alias: segments
The radius of the sphere. <Sphere>.segs
Integer
The number of polygonal divisions for the sphere. <Sphere>.smooth
Boolean
default: true
-- animatable
When on, blends the faces of the sphere, creating a smooth appearance in rendered views. <Sphere>.hemisphere
Float
default: 0.0
-- animatable
Increasing values progressively “cut off” the sphere, starting at the base, to create a partial sphere. Values range from 0.0 to 1.0. The default is 0.0, producing a full sphere. A setting of 0.5 produces a hemisphere, and 1.0 reduces the sphere to nothing. <Sphere>.chop
Integer
default: 0
Sets whether the hemisphere is ‘chopped’ or ‘squashed’: Chop (Reduces the number of vertices and faces in the sphere by “chopping” them out as the hemisphere is cut off.) Squash (Maintains the number of vertices and faces in the original sphere, “squashing” the geometry into a smaller and smaller volume toward the top of the sphere. Since the geometry is maintained, you can use different versions of a squashed sphere for morph objects.) <Sphere>.slice
Boolean
default: false
When on, uses the From and To angles to create a partial sphere. The effect is similar to lathing a semicircular shape fewer than 360 degrees. <Sphere>.sliceFrom Slice_From
Float
default: 0.0
The start angle (on the local Z-axis) for slicing.
-- animatable, angle, alias:
Spindle : GeometryClass
<Sphere>.sliceTo Slice_To
Float
default: 0.0
-- animatable, angle, alias:
The stop angle (on the local Z-axis) for slicing. <Sphere>.recenter
Boolean
default: false
When on, moves a sphere upward along its local Z axis so the pivot point is at its base. When off, the pivot point is on the construction plane at the center of the sphere. <Sphere>.mapCoords
Boolean
default: false
When on, generates coordinates for applying mapped materials to the box.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Spindle : GeometryClass Constructor: spindle ...
Properties: <Spindle>.radius
Float
default: 0.0
-- animatable
Float
default: 0.0
-- 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
Float
default: 0.0
-- animatable
When greater than 0, creates a bevel at the edge of the caps. <Spindle>.sides
Integer
default: 12
-- animatable
The number of sides around the spindle. Higher numbers shade and render as true circles with Smooth on. Lower numbers create regular polygonal objects with Smooth off. <Spindle>.Cap_Segments
Integer
default: 5
-- animatable
The number of concentric divisions along the center of the spindle’s top and bottom. <Spindle>.Height_Segments
Integer
default: 1
-- animatable
The number of divisions along the spindle’s major axis.
873
874
Chapter 11
|
3ds max Objects
<Spindle>.Smooth_On
Integer
default: 1
-- animatable
Integer
default: 0
-- animatable
Float
default: 0.0
-- animatable, angle
Turns on/off smooth: OFF ON <Spindle>.Slice_On
Turn on/off slice: OFF ON <Spindle>.Slice_From
The start angle (on the local Z-axis) for slicing. <Spindle>.Slice_To
Float
default: 0.0
-- animatable, angle
The stop angle (on the local Z-axis) for slicing. Note: The Generate Mapping Coordinates property is not accessible to MAXScript in 3ds max 4.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
TargetObject : GeometryClass The generic target for cameras, spotlights, tape measure helpers, etc. In MAXScript, you must explicitly construct a target for those objects that need one. For example: c = targetCamera pos:[x,y,z] target:(targetObject pos:[xt, yt, zt])
Constructor: targetObject ...
Properties: There are no additional properties for TargetObject.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Teapot : GeometryClass
Teapot : GeometryClass Constructor: teapot ...
Note: This class is not available in 3D Studio VIZ. Properties: .radius
Float
default: 25.0
-- animatable
default: 4
-- animatable, alias: segments
The radius of the teapot. .segs
Integer
The number of divisions for the teapot or its individual parts. .smooth
Boolean
default: true
-- animatable
When on, blends faces of the teapot, creating a smooth appearance in rendered views. .body
Boolean
default: true
-- animatable
When on, the body of the teapot is included in the object. .handle
Boolean
default: true
-- animatable
When on, the handle of the teapot is included in the object. .spout
Boolean
default: true
-- animatable
When on, the spout of the teapot is included in the object. .lid
Boolean
default: true
-- animatable
When on, the lid of the teapot is included in the object. .mapCoords
Boolean
default: false
When on, sets up required coordinates for applying mapped materials to the teapot.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Torus : GeometryClass Constructor: torus ..
Properties: .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.
875
876
Chapter 11
|
3ds max Objects
.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. .radius2
Float
default: 10.0
-- animatable, alias: Radius_2
The radius of the cross-sectional circle. .tubeRotation
Float
default: 0.0
-- animatable, angle
The degree of rotation. Vertices are uniformly rotated about the circle running through the center of the torus ring. Positive and negative values for this setting “roll” the vertices in either direction over the surface of the torus. .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. .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. .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.) .slice
Boolean
default: false -- animatable
When on, creates a portion of a sliced torus rather than the entire 360 degrees. .sliceFrom Slice_From
Float
default: 0.0
-- animatable, angle, alias:
The angle where the torus slice begins. .sliceTo
Float
default: 0.0
-- animatable, angle, alias: Slice_To
The angle where the torus slice ends. .mapCoords
Boolean
default: false
When on, sets up required coordinates for applying mapped materials to the torus.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Torus_Knot: GeometryClass
Torus_Knot: GeometryClass Constructor: torus_knot ...
Note: This class is not available in 3D Studio VIZ. Properties: .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.) .radius
Float
default: 0.0
-- animatable
default: 120
-- animatable
The radius of the base curve. .segments
Integer
The number of segments around the perimeter of the torus. .p
Float
default: 2.0
-- animatable
Describe up and around-the-center winding numbers. .q
Float
default: 3.0
-- animatable
Describe down and around-the-center winding numbers. .Warp_Count
Float
default: 0.0
-- animatable
The number of “points” in a star shape around the curve. .Warp_Height
Float
default: 0.0
-- animatable
The height of the “points” given as a percentage of the base curve radius. .radius2
Float
default: 10.0
-- animatable
The radius of the cross section of the torus knot object. .sides
Integer
default: 12
-- animatable
The number of sides around the cross section. .Eccentricity
Float
default: 1.0
-- animatable
The ratio of the major to minor axes of the cross section. A value of 1 provides a circular cross section, while other values create elliptical cross sections. .Twist
Float
default: 0.0
-- animatable
The number of times the cross section twists around the base curve. .Lumps
Float
default: 0.0
-- animatable
The number of bulges in the torus knot. .Lump_Height
Float
default: 0.0
-- animatable
The height of the lumps, as a percentage of the radius of the cross section. .Lump_Offset
Float
default: 0.0
-- animatable, angle
The offset of the start of the lumps, measured in degrees. The purpose of this value is to animate the lumps around the torus.
877
878
Chapter 11
|
3ds max Objects
.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.) .Gen_UV
Integer
default: 0
Turn on/off generate mapping coordinates OFF ON .U_Tile
Float
default: 1.0
-- animatable
Tile the mapping coordinates along U. .V_Tile
Float
default: 1.0
-- animatable
Tile the mapping coordinates along V. .U_Offset
Float
default: 0.0
-- animatable
Offset the mapping coordinates along U. .V_Offset
Float
default: 0.0
-- animatable
Offset the mapping coordinates along V.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Tube : GeometryClass Constructor: tube ...
Properties: .radius1
Float
default: 25.0
-- animatable, alias: Radius_1
The first radius for the tube. .radius2
Float
default: 20.0
-- animatable, alias: Radius_2
The second radius for the tube. Note: The larger radius specifies the outside radius of the tube, while the smaller specifies the inside radius. .height
Float
default: 50.0
-- animatable
The dimension along the central axis. Negative values create the tube below the construction plane.
Tube : GeometryClass
.heightsegs
Integer
default: 1
-- animatable, alias: Height_Segments
The number of divisions along the tube’s major axis. .capsegs
Integer
default: 1
-- animatable, alias: Cap_Segments
The number of concentric divisions around the center of the tube’s top and bottom. .sides
Integer
default: 24
-- animatable
The number of sides around the tube. Higher numbers shade and render as true circles with Smooth on. Lower numbers create regular polygonal objects with Smooth off. .smooth
Boolean
default: true
-- animatable
When on, faces of the tube are blended together, creating a smooth appearance in rendered views. .slice
Boolean
default: false -- animatable
Enables/Disables the Slice feature, which removes part of the tube’s circumference. .Slice_On
Integer
default: 0
Integer alias of slice: OFF ON .sliceFrom
Float
default: 0.0
-- animatable, angle, alias: Slice_From
The angle where the tube slice begins. .sliceTo
Float
default: 0.0
-- animatable, angle, alias: Slice_To
The angle where the tube slice ends. .mapCoords
Boolean
default: false
When on, sets up required coordinates for applying mapped materials to the tube.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Geometry - Dynamics Objects The following list displays the dynamics objects: Damper (p. 880) Spring (p. 883)
879
880
Chapter 11
|
3ds max Objects
Damper : GeometryClass Constructor: damper ...
Note: This class is not available in 3D Studio VIZ. Properties: .End_Placement_Method
Integer
default: 1
Set binding method for damper: Reference Objects (Choose this option when binding the damper to two objects.) Free Spring (Choose this when using the damper as a simple object that’s not bound to others or used in a dynamics simulation.) .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. .Renderable_Spring
Integer
default: 1
Turn on/off renderability of the damper: not renderable renderable .Generate_Mapping_Coordinates
Integer
default: 0
Turn on/off mapping coordinates for the object: OFF ON .Base_Stud_Diameter
Float
default: 0.5
-- animatable
The diameter of the base, or “mount” of the damper. .Base_Stud_Height
Float
default: 0.2
-- animatable
Float
default: 1.0
-- animatable
The height of the base. .Cylinder_Diameter
The diameter of the main housing of the damper. .Cylinder_Height
Float
default: 1.0
-- animatable
Integer
default: 8
-- animatable
The height of the main housing. .Cylinder_Sides
The number of sides of both the base and the main housing. .Cylinder_Fillet_1
Float
default: 0.0
-- animatable
The size of the fillet on the lower edge of the main housing. .Cylinder_Fillet_1_Segments
Integer
default: 0
-- animatable
The number of segments for Fillet 1. The higher this setting, the rounder the fillet profile appears. .Cylinder_Fillet_2
Float
default: 0.0
The size of the fillet on the upper edge of the main housing.
-- animatable
Damper : GeometryClass
.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. .Inside_Diameter
Float
default: 0.0
-- animatable
The inside diameter of the main housing, which is actually a tube rather than a cylinder. .Smooth_Cylinder
Integer
default: 1
Turn on/off smoothing for the base and the main housing: OFF ON .Piston_Diameter
Float
default: 0.2
-- animatable
Float
default: 1.0
-- animatable
Integer
default: 6
-- animatable
Integer
default: 1
Integer
default: 0
The diameter of the piston. .Piston_Height
The height of the piston. .Piston_Sides
The number of sides in the piston. .Smooth_Piston
Turn on/off smoothing for the piston: OFF ON .Enable_Boot
Turn this on to add the boot to the damper: OFF ON The boot is an optional component of the damper that’s similar to the rubber “accordion” boot found on various types of dampers, such as shock absorbers. The boot acts like a bound dynamic object, in that one of its ends is bound to the main housing, while the other is bound to the piston. Thus, as the piston moves within the housing, the boot expands and contracts to follow. .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. .Boot_Large_Diameter
Float
default: 1.0
-- animatable
Integer
default: 8
-- animatable
default: 4
-- animatable
The maximum diameter of the boot. .Boot_Sides
The number of sides making up the boot. .Boot_Folds
Integer
The number of accordion folds (bulges) along the height of the boot. .Boot_Fold_Resolution
The number of segments in each fold.
Integer
default: 4
-- animatable
881
882
Chapter 11
|
3ds max Objects
.Boot_Stop_Diameter
Float
default: 0.4
-- animatable
The diameter of the stop, which is the ring at the top of the boot. .Boot_Stop_Height
Float
default: 0.2
-- animatable
default: 0.2
-- animatable
The thickness (height) of the stop ring. .Boot_Stop_Setback
Float
The distance of the stop ring from the top of the piston. .Boot_Stop_Fillet
Float
default: 0.0
-- animatable
The size of the fillet on the upper edge of the stop ring. .Boot_Stop_Fillet_Segements
Integer
default: 0
-- animatable
The number of segments the stop fillet. The higher this setting, the round the fillet profile appears. .Smooth_Boot
Integer
default: 1
Integer
default: 0
Turn on/off smoothing for the boot: OFF ON .Dynamics_Object_Type
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.) .Drag
Float
default: 0.0
Integer
default: 0
Integer
default: 2
-- animatable
The force per unit linear speed. .Drag_Units
Sets the units of drag: Pounds per inch/second Newtons per meter/second .Damper_Direction
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.) .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. .Force_Units
Set the units of force: Pounds Newtons
Integer
default: 0
Spring : GeometryClass
Note: The Reference End Point objects cannot be specified in MAXScript in 3ds max R4.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Spring : GeometryClass Constructor: spring ...
Note: This class is not available in 3D Studio VIZ. Properties: <Spring>.End_Placement_Method
Integer
default: 1
Set the end placement method: Reference Objects (Choose this when binding the spring to two objects.) Free Spring (Choose this when using the spring as a simple object that’s not bound to other objects or used in a dynamics simulation.) <Spring>.Free_Spring_Height
Float
default: 1.0
-- animatable
The straight-line height or length of the spring when it is not bound. This is not the actual length of the spring’s wire. <Spring>.Diameter
Float
default: 1.0
-- animatable
The overall diameter of the spring, as measured at the center of the wire. (The diameter of the wire itself has no effect on this setting.) <Spring>.Number_of_Turns
Float
default: 1.0
-- animatable
The number of full 360-degree turns in the spring. <Spring>.Turn_Direction
Integer
default: 0
Integer
default: 0
Sets the direction of the turns in the spring: counterclockwise clockwise <Spring>.Segmentation_Method
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.)
883
884
Chapter 11
|
3ds max Objects
Manual Segments (When this option is chosen, length of the spring contains a fixed number of segments, no matter how many turns in the spring. Thus, as you increase the number of turns, you must manually increase the number of segments to maintain a smooth curve.) <Spring>.Segments_Per_Turn
Integer
default: 16
-- animatable
The number of segments in each 360-degree turn of the spring. <Spring>.Segments_Along_Turn
Integer
default: 16
-- animatable
The total number of manual segments in the spring. <Spring>.Smooth_Spring
Integer
default: 0
Set smoothing method for spring: All (All surfaces are smoothed.) None (No smoothing is applied.) Sides (Smoothing runs along the length of the wire, but not around its perimeter.) Segments (Smoothing runs around the perimeter of the wire, but not along its length.) .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
Integer
default: 0
Float
default: 0.2
-- animatable
Integer
default: 6
-- animatable
Set the shape of the wire: Round Rectangular D-Section <Spring>.Generate_Mapping_Coordinates
Turn on/off generate texture coordinates OFF ON <Spring>.Round_Wire_Diameter
The diameter of the wire. <Spring>.Round_Wire_Side_Count
The number of sides that make up the cross section of the round wire. <Spring>.Rectangular_Wire_Width
Float
default: 0.2
-- animatable
default: 0.2
-- animatable
default: 0.0
-- animatable
Determines the width of the rectangular cross section. <Spring>.Rectangular_Wire_Depth
Float
Determines the depth of the rectangular cross section. <Spring>.Rectangular_Wire_Fillet_Size
Float
When combined with .Rectangular_Fillet_Sides, this lets you fillet (round) the corners of the cross section.
Spring : GeometryClass
<Spring>.Rectangular_Fillet_Sides
Integer
default: 0
-- animatable
Float
default: 0.0
-- animatable,
The number of segments in the fillet. <Spring>.Rectangular_Wire_Rotation_Angle angle
Rotates the angle of the cross section along the entire length of the spring. <Spring>.D_Section_Wire_Width
Float
default: 0.2
-- animatable
Float
default: 0.2
-- animatable
Integer
default: 4
-- 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
The number of segments that make up the rounded side of the D-shape. <Spring>.D_Section_Wire_Fillet_Size
Float
default: 0.0
-- animatable
When combined with .D_Section_Wire_Fillet_Sides, this lets you fillet (round) the corners of the cross section. <Spring>.D_Section_Wire_Fillet_Sides
Integer
default: 0
-- animatable
Float
default: 0.0
-- animatable,
The number of segments in the fillet. <Spring>.D_Section_Wire_Rotation_Angle angle
Rotates the angle of the cross section along the entire length of the spring. <Spring>.Dynamics_Spring_Free_Height
Float
default: 1.0
-- animatable
Specifies the height (or length) at which the spring is “relaxed” and therefore contributes no force--either compression or extension. <Spring>.Dynamics_K_Constant_Value
Float
default: 1.0
-- animatable
The amount of force exerted per unit change in length with respect to the Relaxed Hgt value. This could also be described as the measure of force-per-units-change in length as compared to the Relaxed Length. <Spring>.Dynamics_K_Constant_Units
Integer
default: 0
Integer
default: 0
Sets the Units for the K constant: Pounds per inch Newtons per meter <Spring>.Dynamics_Spring_Direction
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.)
885
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
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 [ <mat_method> ]
Creates a Boolean2 object using node and an optional node . specifies how 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 ID’s matches ID’s to materials, then combines materials matches materials to ID’s, then combines them discards original material, uses new node’s instead discards new node’s material, uses original
Properties: The following properties are available only after the boolean2 object has been created. The values shown for the properties are those for a boolean2 object created from two spheres. The operand transforms are in the local coordinate system of the boolean2 object. .Sphere02 .Operand_A_Transform .Sphere01 .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 <mat_method>
sets operand B. The values for and <mat_method> are describe above. boolObj.getOperandSel boolObj.setOperandSel
these methods get and set whether operand_A and operand_B are selected in the Operands list. = 1 - operand_A, 2 - operand_B
887
888
Chapter 11
|
3ds max Objects
boolObj.getBoolOp boolObj.setBoolOp
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 boolObj.setBoolCutType
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 boolObj.setDisplayResult
these methods get and set whether Results or Operands are displayed. If true, Result is displayed. If false, Operands are displayed. boolObj.getShowHiddenOps boolObj.setShowHiddenOps
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 boolObj.setUpdateMode
these methods get and set the Update mode as follows: 1 - Always 2 - When Rendering 3 - Manually boolObj.getOptimize boolObj.setOptimize
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
Conform : GeometryClass Constructor: Conform compound objects are not constructable by MAXScript in 3ds max 4. Properties: .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. .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. .S_Sphere02 .Operand_A_Transform .D_Sphere01 .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: .segments
Integer
default: 0
-- animatable
The number of segments in the connecting bridge. .tension
Float
default: 0.5
-- animatable
Controls the curvature in the connecting bridge. A value of 0 provides no curvature, while higher values create curves that attempt to more smoothly match the surface normals on either end of the connecting bridge.
889
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. .Op_0__Sphere02 .Op_0_Transform .Op_1__Sphere01 .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: .Def_Scale_X .Def_Scale_Y .Def_Twist .Def_Teeter_X .Def_Teeter_Y .Def_Bevel .Def_Fit_X .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). .ellipse .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
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
Integer
default: 1
-- animatable
The number of scattered duplicates of the source object. <Scatter>.Base_Scale percentage
Float
default: 100.0
-- animatable,
Alters the scale of the source object, affecting each duplicate identically. This scale occurs before any other transforms.
891
892
Chapter 11
|
3ds max Objects
<Scatter>.Vertex_Chaos
Float
default: 0.0
-- animatable
Applies a random perturbation to the vertices of the source object. <Scatter>.Animation_Offset
Time
default: 0f
-- animatable
The number of frames by which each source object duplicate’s animation is offset from the previous duplicate. <Scatter>.x_rotation
Float
default: 0.0
-- animatable
The maximum random rotational offset you want about the local X-axis of each duplicate. <Scatter>.y_rotation
Float
default: 0.0
-- animatable
The maximum random rotational offset you want about the local Y-axis of each duplicate. <Scatter>.z_rotation
Float
default: 0.0
-- animatable
The maximum random rotational offset you want about the local Z-axis of each duplicate. <Scatter>.X_Translation
Float
default: 0.0
-- animatable
The maximum random movement you want along the X-axis of each duplicate. <Scatter>.Y_Translation
Float
default: 0.0
-- animatable
The maximum random movement you want along the Y-axis of each duplicate. <Scatter>.Z_Translation
Float
default: 0.0
-- animatable
The maximum random movement you want along the Z-axis of each duplicate. <Scatter>.A_Translation_on_Face
Float
default: 0.0
-- animatable
The first barycentric coordinate on the surface of the face, upon which duplicates are translated. <Scatter>.B_Translation_on_Face
Float
default: 0.0
-- animatable
The second barycentric coordinate on the surface of the face, upon which duplicates are translated. <Scatter>.N_Translation_on_Face
Float
default: 0.0
-- animatable
The offset along the normal of the face, upon which duplicates are translated. <Scatter>.Local_X_Scaling
Float
default: 0.0
-- animatable
The percent of random scaling along the X-axis of each duplicate. <Scatter>.Local_Y_Scaling
Float
default: 0.0
-- animatable
The percent of random scaling along the X-axis of each duplicate. <Scatter>.Local_Z_Scaling
Float
default: 0.0
-- animatable
The percent of random scaling along the X-axis of each duplicate. The following properties are available only after the Scatter object has been created. The values shown for the properties are those for a Scatter object created from two boxes. The operand transforms are in the local coordinate system of the Scatter object. <Scatter>.S_Box04 <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
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
ShapeMerge : GeometryClass Constructor: ShapeMerge compound objects are not constructable by MAXScript in 3ds max 4. Properties: <ShapeMerge>.Operation_Type
Integer
default: 1
Set the shapemerge operation type: Cookie Cutter (Cuts the shape out of the mesh object’s surface.) Merge (Merges the shape with the surface of the mesh object.) <ShapeMerge>.Remove_Interior_Exterior
Integer
default: 0
Reverses the effect of Cookie Cutter or Merge. With the Cookie Cutter option, the effect is obvious. When Invert is off, the shape is a hole in the mesh object. When Invert is on, the shape is solid and the mesh is missing. When you’re using Merge, Invert reverses the 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
893
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: .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.) .stitchBorder
Boolean
default: false
Boolean
default: false
Integer
default: 0
Turn on/off stitch border. .retriangulate
Turn on/off retriangulate. .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.) .update
Integer
default: 0
Set update settings for the terrain object: Always (Updates the terrain object immediately when you change an operand, including the original object of an instanced or referenced operand.) When Rendering (Updates the terrain object when you render the scene or when you force an update. With this option, viewports won’t show current geometry unless you.) Manually (Updates the terrain object when you force an update.)
Terrain : GeometryClass
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. .numOps
Integer
default: 0
The number of contour operands. Read-only. .horizSimplification
Integer
default: 0
horizSimplification = 0 – No Simplification; 1 – Use 1/2 of Points; 2 - Use 1/4 of Points; 3 – Interpolate Points * 2; 4 - Interpolate Points * 4 .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. .Op_0__Circle01 .Op_0_Transform .Op_1__Circle02 .Op_1_Transform .Op_2__Circle03 .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 <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
Deletes the indexed operand, index_integer is 1-based. terrainOps.getOperand
Returns the indexed contour operand as a 3ds max base object (not a node), index_integer is 1-based.
895
896
Chapter 11
|
3ds max Objects
terrainOps.getOperandTM
Returns the indexed operand’s local transformation matrix as a Matrix3 value. This transformation matrix is relative to the terrain’s node transformation matrix. terrainOps.setOperandTM <matrix3>
Sets the indexed operand’s local transformation matrix. This transformation matrix is relative to the terrain’s node transformation matrix. terrainOps.update
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
Awning : GeometryClass Constructor: awning ...
Properties: .height .width .depth .Horizontal_Frame_Width .Vertical_Frame_Width .Frame_Thickness .Glazing_Thickness .Rail_Width .Number_of_Panels .Percent_Open .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: .height .width .depth .Double_Doors
Float Float Float Integer
default: default: default: default:
0.0 0.0 0.0 0
Boolean Boolean Float Boolean Float Float Float Boolean Float Float
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
-- animatable -- animatable -- animatable
Double_Doors = 0 - false; 1 - true .Flip_Swing .Flip_Hinge .open .Create_Frame .Frame_Width .Frame_Depth .Door_Offset .Generate_Mapping_Coords .Leaf_Thickness .Stiles_Top_Rail
-- animatable -- animatable -- animatable -- animatable -- animatable -- animatable
897
898
Chapter 11
|
3ds max Objects
.Bottom_Rail .Number_of_Panels_Horizontally .Number_of_Panels_Vertically .Muntin .Panel_Type
Float Integer Integer Float Integer
default: default: default: default: default:
12.0 1 1 2.0 1
-- animatable
default: default: default: default: default: default: default:
0.25 45.0 0.25 0.5 0.25 1.0 0.5
--------
-- animatable
Panel_Type = 0 - None; 1 - Glass; 2 - Beveled .Glass_Thickness .Bevel_Angle .Panel_Thickness_1 .Panel_Thickness_2 .Panel_Middle_Thickness .Panel_Width_1 .Panel_Width_2
Float Float Float Float Float Float Float
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: .height .width .depth .Horizontal_Frame_Width .Vertical_Frame_Width .Frame_Thickness .Glazing_Thickness .Panel_Width .Number_of_Casements
Float Float Float Float Float Float Float Float Integer
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 .Percent_Open .Opens_to_Inside .Generate_Mapping_Coords
Integer Boolean Boolean
default: 0 -- animatable default: false default: false
Fixed : GeometryClass
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: .height .width .depth .Horizontal_Frame_Width .Vertical_Frame_Width .Frame_Thickness .Glazing_Thickness .Rail_Width .Number_of_Panels_Horizontally .Number_of_Panels_Vertically .Chamfered_Profile .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
0.0 0.0 0.0 0
-- 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: .height .width .depth .Double_Doors
Double_Doors = 0 - false; 1 - true
Float Float Float Integer
default: default: default: default:
899
900
Chapter 11
|
3ds max Objects
.Flip_Swing .Flip_Hinge .Open__degrees .Create_Frame .Frame_Width .Frame_Depth .Door_Offset .Generate_Mapping_Coords .Leaf_Thickness .Stiles_Top_Rail .Bottom_Rail .Number_of_Panels_Horizontally .Number_of_Panels_Vertically .Muntin .Panel_Type
Boolean Boolean Float Boolean Float Float Float Boolean Float Float Float Integer Integer Float Integer
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
default: default: default: default: default: default: default:
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 .Glass_Thickness .Bevel_Angle .Panel_Thickness_1 .Panel_Thickness_2 .Panel_Middle_Thickness .Panel_Width_1 .Panel_Width_2
Float Float Float Float Float Float Float
--------
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: .height .width .depth .Horizontal_Frame_Width .Vertical_Frame_Width .Frame_Thickness .Glazing_Thickness .Rail_Width .Vertical_Rotation .Percent_Open .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
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
901
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
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
Float Float Float Float Float Float Float Integer
default: default: default: default: default: default: default: default:
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
default: 0.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Float
default: 2.0
--
Float
default: 2.0
--
QuadPatch : GeometryClass
<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
default: 0.5
--
Float
default: 0.25
--
Float
default: 1.0
--
Integer Integer Boolean Boolean Integer
default: default: default: default: default:
Boolean
default: false
1 1 false true 0 --
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: .length
Float
default: 25.0
-- animatable
Float
default: 25.0
-- animatable
Integer
default: 1
-- animatable, alias:
The patch length. .width
The patch width. .lengthsegs Length_Segments
The number of facets along the length of the grid. .mapCoords
Boolean
default: false
When on, applies mapping coordinates to the grid. .widthsegs Width_Segments
Integer
default: 1
The number of facets along the width of the grid.
-- animatable, alias:
903
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: .length
Float
default: 25.0
-- animatable
default: 25.0
-- animatable
The length of the patch. .width
Float
The width of the patch. .mapCoords
Boolean
default: false
When on, applies mapping coordinates to the grid.
See also GeometryClass Common Properties, Operators, and Methods (p. 852) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Geometry - Particle Systems The following list displays the particle system objects: Blizzard (p. 906) PArray (p. 913) PCloud (p. 923) Snow (p. 931) Spray (p. 933) SuperSpray (p. 935) Note: Particle Systems are not available in 3D Studio VIZ.
Particle System Common Properties, Operators, and Methods
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.
905
906
Chapter 11
|
3ds max Objects
Blizzard : GeometryClass Constructor: blizzard ...
Note: This class is not available in 3D Studio VIZ. Properties: -- Basic Parameters .Emitter_Width animatable
Float
default: 0.0
--
Float
default: 0.0
--
Boolean
default: false
The width of the emitter icon. .Emitter_Length animatable
The width of the emitter icon. .emitterHidden
When on, hides the emitter in viewports. When off, the emitter is displayed in viewports. The emitter is never rendered. .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.) .viewPercent percentage, alias: Percentage_Displayed
Float
default: 10.0
--
Sets the percentage of particles displayed in the viewport. -- Particle Generation .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. .Birth_Rate animatable
Integer
default: 10
Integer
default: 100
The number of particles emitted per frame. .Total_Number
The total number of particles to be emitted.
--
Blizzard : GeometryClass
.speed animatable
Float
default: 10.0
--
The velocity of the particle at birth, along the normal, in units traveled per frame. .Speed_Variation animatable, percentage
Float
default: 0.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Time
default: 0f
Time
default: 30f
Time
default: 100f
Percentage of variation to the speed of emission for each particle. .tumble animatable
Amount of random rotation of the particles. .Tumble_Rate animatable
Speed at which the particles rotate. .Emitter_Start
The frame at which particles begin to exist in the scene. .Emitter_Stop
The last frame at which particles are emitted. .Display_Until
Time at which all particles will disappear, regardless of other settings. .life animatable
Time
default: 30f
--
Time
default: 0f
--
The lifespan of each particle from the time of creation. .Life_Variation animatable
The number of frames by which the life of each particle can vary from the norm. .subsampleCreationTime
Boolean
default: false
When on, enables the addition of a time offset to the equations of motion that prevents puffing in time. .subsampleEmitterTranslation
Boolean
default: true
If the object-based emitter is moving in space, particles are created at integral times at positions along the geometry’s path between renderable positions. This prevents puffing in space. .subsampleEmitterRotation
Boolean
default: true
If the emitter is rotating, turn this on to avoid puffing and produce smooth spiral effects. .size animatable
Float
default: 1.0
--
Float
default: 0.0
--
The target size for all particles in the system. .Size_Variation animatable, percentage
The percentage by which the size of each particle may vary from the norm. .Growth_Time
Time
default: 10f
The number of intervals over which the particle grows from being very small (0.1a system constant) to the Size value.
907
908
Chapter 11
|
3ds max Objects
.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. .seed alias: Random_Seed
Integer
default: 0
--
By changing the Seed value, you achieve different results using otherwise identical particle settings. -- Particle Type .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.) .standardParticle
Integer
default: 0
standardParticle = 0 - Triangle; 1 - Cube; 2 - Special; 3 - Facing; 4 - Constant; 5 - Tetra; 6 SixPoint; 7 - Sphere .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. .Metaparticle_Tension_Variation animatable, percentage
Float
default: 0.0
--
Float
default: 0.5
--
Float
default: 1.0
Boolean
default: true
The percent of variation of the Tension effect. .metaballRenderCoarsness alias: Metaparticle_Coarseness
The coarseness for metaparticles in the rendered scene. .metaballViewCoarsness
The coarseness for the viewport display. .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. .Bubble_Amplitude
Turns on/off One Connected Blob. OFF ON
Integer
default: 0
Blizzard : GeometryClass
.instancingObject
Node
default: undefined
Boolean
default: false
The object which is instanced. .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. .instanceKeyOffsetType
Integer
default: 0
Set the animation offset keying: None (Each particle duplicates the timing of the original object. As a result, the animation of all particles will be identically timed.) Birth (The firstborn particle is an instance of the current animation of the source object at the moment of that particle’s birth. Each subsequent particle then use the same start time for the animation.) Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each particle is born using the same animation as the source object at the time of birth, but with a random offset of frames, based on the .instanceFrameOffset value.) .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. .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.) .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. .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. .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.)
909
910
Chapter 11
|
3ds max Objects
-- Rotation and Collision .Spin_Time animatable
Time
default: 30f
--
The number of frames for one rotation of a particle. If set to 0, no rotation takes place. .Spin_Time_Variation animatable, percentage
Float
default: 0.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Integer
default: 0
The percent of variation of the Spin Time. .Spin_Phase animatable, angle
The initial particle rotation, in degrees. .Spin_Phase_Variation animatable, percentage
The percent of variation of the Phase. .spinAxisType
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.) .X_Spin_Vector animatable
Float
default: 1.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Spin vector of the X-axis. .Y_Spin_Vector animatable
Spin vector of the Y-axis. .Z_Spin_Vector animatable
Spin vector of the Z-axis. .Spin_Axis_Variation animatable, angle
The amount, in degrees, by which the spin axis of each particle may vary from the specified X Axis, Y Axis, and Z Axis settings. .Interparticle_Collisions_On
Integer
default: 0
Integer
default: 2
Turn on/off interparticle collisions: OFF ON .Interparticle_Collision_Steps
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. .Interparticle_Collision_Bounce animatable, percentage
The degree to which speed is recovered after a collision.
Float
default: 100.0
--
Blizzard : GeometryClass
.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 .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. .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. .motionVariation Float default: 0.0 animatable, percentage; alias: Object_Motion_Multiplier_Variation
--
Percentage of variation of the Multiplier value. -- Particle Spawn .spawnType
Integer
default: 0
Determines what happens to particles at either collision or death: None (Particles act as they normally would. That is, upon collision, they either bounce or stick, depending on Particle Bounce settings in the deflector, and on death they disappear.) Die After Collision (Particles disappear when they strike a deflector to which they’re bound, such as the SDeflector.) Spawn on Collision (Spawn effects take place upon collision with a bound deflector.) Spawn on Death (Spawn effects take place at the end of each particle’s life.) Spawn Trails (Particles are spawned from existing particles at each frame of that particle’s life.) .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. .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. .Spawn_Affects
Integer
default: 100
The percentage of particles that will spawn. Reducing this reduces the number of particles that produce spawned particles. .Spawn_Multiplier_Variation percentage
Float
default: 0.0
Percentage range by which the Multiplier value will vary, frame by frame.
--
911
912
Chapter 11
|
3ds max Objects
.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 parent’s path by up to 90 degrees. .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. .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.) .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. .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. .lifespanValueQueue
Array
default: #()
lifespanValueQueue is an array of integers which correspond to lifespan values for each spawned generation of particles. .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
PArray : GeometryClass Constructor: parray ...
Note: This class is not available in 3D Studio VIZ. Properties: -- Basic Parameters .emitter
Node
default: undefined
Integer
default: 0
The object which acts as an emitter. .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.) .numDistinctPoints alias: Number_of_Emitters
Integer
default: 20
--
The number of emitter points used when At Distinct Points is chosen. .Use_Selected_Subobjects animatable
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 .iconsize alias: Emitter_Width
Float
default: 20.0
Boolean
default: false
--
The width of the emitter icon. .iconHidden
When on, hides the emitter in viewports. When off, the emitter is displayed in viewports. The emitter is never rendered. .viewType
Set the display icon for particles in the viewport: Dots (Displays the particles as dots.) Ticks (Displays the particles as crosses.)
Integer
default: 0
913
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.) .viewPercent percentage, alias: Percentage_Displayed
Float
default: 10.0
--
The percentage of particles displayed in the viewport. -- Particle Generation .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. .Birth_Rate animatable
Integer
default: 10
Integer
default: 100
Float
default: 10.0
--
The number of particles emitted per frame. .Total_Number
The total number of particles to be emitted. .speed animatable
--
The velocity of the particle at birth, along the normal, in units traveled per frame. .Speed_Variation animatable, percentage
Float
default: 0.0
--
Percentage of variation to the speed of emission for each particle. .Divergence_Angle animatable, angle
Float
default: 10.0
--
Applies an angular degree of variation by which each particle’s velocity can vary from the emitter normal. .Emitter_Start
Time
default: 0f
The frame at which particles begin to exist in the scene. .Emitter_Stop
Time
default: 30f
Time
default: 100f
The last frame at which particles are emitted. .Display_Until
Time at which all particles will disappear, regardless of other settings. .life animatable
Time
default: 30f
--
default: 0f
--
The lifespan of each particle from the time of creation. .Life_Variation animatable
Time
The number of frames by which the life of each particle can vary from the norm.
PArray : GeometryClass
.subsampleCreationTime
Boolean
default: false
When on, enables the addition of a time offset to the equations of motion that prevents puffing in time. .subsampleEmitterTranslation
Boolean
default: true
If the object-based emitter is moving in space, particles are created at integral times at positions along the geometry’s path between renderable positions. This prevents puffing in space. .subsampleEmitterRotation
Boolean
default: true
If the emitter is rotating, turn this on to avoid puffing and produce smooth spiral effects. .size animatable
Float
default: 1.0
--
Float
default: 0.0
--
The target size for all particles in the system. .Size_Variation animatable, percentage
The percentage by which the size of each particle may vary from the norm. .Growth_Time
Time
default: 10f
The number of intervals over which the particle grows from being very small (0.1a system constant) to the Size value. .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. .seed alias: Random_Seed
Integer
default: 0
--
By changing the Seed value, you achieve different results using otherwise identical particle settings. -- Particle Type .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.)
915
916
Chapter 11
|
3ds max Objects
.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.) .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. .Metaparticle_Tension_Variation animatable, percentage
Float
default: 0.0
--
Float
default: 0.5
--
The percent of variation of the Tension effect. .metaballRenderCoarsness alias: Metaparticle_Coarseness
The coarseness for metaparticles in the rendered scene. .metaballViewCoarsness
Float
default: 1.0
Boolean
default: true
The coarseness for the viewport display. .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
.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.) .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. .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. .fragSmoothingAngle
Float
default: 0.0
Node
default: undefined
Boolean
default: false
Sets the amount of smoothing angle. .instancingObject
The object which is instanced. .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. .instanceKeyOffsetType
Integer
default: 0
Set the animation offset keying: None (Each particle duplicates the timing of the original object. As a result, the animation of all particles will be identically timed.) Birth (The firstborn particle is an instance of the current animation of the source object at the moment of that particle’s birth. Each subsequent particle then use the same start time for the animation.) Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each particle is born using the same animation as the source object at the time of birth, but with a random offset of frames, based on the .instanceFrameOffset value.) .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.
917
918
Chapter 11
|
3ds max Objects
.mappingType
Integer
default: 0
Time
default: 30f
Specifies how a mapped material affects the particles: Time (Maps particles over time.) Distance (Maps particles over a distance.) .Mapping_Time_Base animatable
--
The number of frames from the birth of the particle that it takes to complete one mapping of the particle. .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. .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.) .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. .fragEdgeMatID
Integer
default: 2
Specifies which submaterial ID number is assigned to the edges of the fragments. .fragBackMatID
Integer
default: 3
Specifies which submaterial ID number is assigned to the back sides of the fragments. -- Rotation and Collision .Spin_Time animatable
Time
default: 0f
--
The number of frames for one rotation of a particle. If set to 0, no rotation takes place. .Spin_Time_Variation animatable, percentage
Float
default: 0.0
--
Float
default: 0.0
--
Float
default: 0.0
--
The percent of variation of the Spin Time. .Spin_Phase animatable, angle
The initial particle rotation, in degrees. .Spin_Phase_Variation animatable, percentage
The percent of variation of the Phase.
PArray : GeometryClass
.spinAxisType
Integer
default: 0
The spin axis for the particles: Random (The spin axis for each of the particles is random.) Direction of Travel/Mblur (Rotates the particles about a vector formed by the direction in which they’re moving.) User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.) .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. .X_Spin_Vector animatable
Float
default: 1.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Spin vector of the X-axis. .Y_Spin_Vector animatable
Spin vector of the Y-axis. .Z_Spin_Vector animatable
Spin vector of the Z-axis. .Spin_Axis_Variation animatable, angle
The amount, in degrees, by which the spin axis of each particle may vary from the specified X Axis, Y Axis, and Z Axis settings. .Interparticle_Collisions_On
Integer
default: 0
Integer
default: 2
Turn on/off interparticle collisions: OFF ON .Interparticle_Collision_Steps
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. .Interparticle_Collision_Bounce animatable, percentage
Float
default: 100.0
--
default: 0.0
--
The degree to which speed is recovered after a collision. .Interparticle_Collision_Bounce_Variation animatable, percentage
Float
The percentage of random variation of the Bounce value, applied to the particles.
919
920
Chapter 11
|
3ds max Objects
-- Object Motion Inheritance .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. .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. .motionVariation Float default: 0.0 animatable, percentage; alias: Object_Motion_Multiplier_Variation
--
Percentage of variation of the Multiplier value. -- Bubble Motion .Bubble_Amplitude animatable
Float
default: 0.0
--
The distance the particle moves off its usual velocity vector as it travels. .Bubble_Amplitude_Variation animatable, percentage
Float
default: 0.0
--
The percent of Amplitude variation applied to each particle. .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. .Bubble_Period_Variation animatable, percentage
Float
default: 0.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Integer
default: 0
The percent of Period variation for each particle. .Bubble_Phase animatable, angle
The initial displacement of the bubble pattern along the vector. .Bubble_Phase_Variation animatable, percentage
The percent of Phase variation for each particle. -- Particle Spawn .spawnType
Determines what happens to particles at either collision or death: None (Particles act as they normally would. That is, upon collision, they either bounce or stick, depending on Particle Bounce settings in the deflector, and on death they disappear.) Die After Collision (Particles disappear when they strike a deflector to which they’re bound, such as the SDeflector.)
PArray : GeometryClass
Spawn on Collision (Spawn effects take place upon collision with a bound deflector.) Spawn on Death (Spawn effects take place at the end of each particle’s life.) Spawn Trails (Particles are spawned from existing particles at each frame of that particle’s life.) .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. .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. .Spawn_Generations
Integer
default: 1
The number of spawns beyond the original particle generation. For example, if this is set to 1, and you’re spawning at death, one spawning will occur beyond the original lifespan of each particle. .Spawn_Affects
Integer
default: 100
The percentage of particles that will spawn. Reducing this reduces the number of particles that produce spawned particles. .Spawn_Multiplier
Integer
default: 1
Multiplies the number of particles spawned at each spawning event. .Spawn_Multiplier_Variation percentage
Float
default: 0.0
--
Percentage range by which the Multiplier value will vary, frame by frame. .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 parent’s path by up to 90 degrees. .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. .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.)
921
922
Chapter 11
|
3ds max Objects
.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. .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. .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. .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.) .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. .lifespanValueQueue
Array
default: #()
lifespanValueQueue is an array of integers which correspond to lifespan values for each spawned generation of particles. .Spawn_Lifespan
Integer
default: 0
Array
default: #()
Value that sets initial lifespan of spawned particles. .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
PCloud : GeometryClass Constructor: pcloud ...
Note: This class is not available in 3D Studio VIZ. Properties: -- Basic Parameters .emitter
Node
default: undefined
Integer
default: 0
Float
default: 0.0
The object which acts as an emitter. .formation
Set the emitter formation: Box Emitter Sphere Emitter Cylinder Emitter Object-based Emitter .Emitter_Rad_Len animatable
--
The radius of a spherical or cylindrical icon, and the length of a box icon. .Emitter_Width animatable
Float
default: 0.0
--
Float
default: 0.0
--
Boolean
default: false
Integer
default: 0
The width of a box emitter. .Emitter_Height animatable
The height of a box or cylindrical emitter. .emitterHidden
Hides the emitter in the viewport, when on. Note: the emitter is never rendered. .viewType
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.) .viewPercent percentage, alias: Percentage_Displayed
The percentage of particles displayed in the viewport.
Float
default: 10.0
--
923
924
Chapter 11
|
3ds max Objects
-- Particle Generation .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. .Birth_Rate animatable
Integer
default: 10
Integer
default: 100
Float
default: 0.0
--
The number of particles emitted per frame. .Total_Number
The total number of particles to be emitted. .speed animatable
--
The velocity of the particle at birth, along the normal, in units traveled per frame. .Speed_Variation animatable, percentage
Float
default: 0.0
--
Percentage of variation to the speed of emission for each particle. .motionType
Integer
default: 0
Set the particle’s motionType Random Direction (This option emits particles in random directions.) Enter Vector (The direction of the particles is determined by a vector defined by the three X, Y, and Z vectors.) Reference Object (Emits particles in the direction of the local Z axis of a specified object.) .Direction_Vector_X animatable
Float
default: 1.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Node
default: undefined
The particle direction vectors for the X-axis. .Direction_Vector_Y animatable
The particle direction vectors for the Y-axis. .Direction_Vector_Z animatable
The particle direction vectors for the Z-axis. .motionReferenceObject
The object used as the reference object. .directionVariation Float animatable, percentage, alias: Speed_Direction_Variation
default: 0.0
--
Percentage of variation to the direction when you choose either the Direction Vector or Reference Object option. .Emitter_Start
Time
The frame at which particles begin to exist in the scene.
default: 0f
PCloud : GeometryClass
.Emitter_Stop
Time
default: 0f
Time
default: 100f
The last frame at which particles are emitted. .Display_Until
Time at which all particles will disappear, regardless of other settings. .life animatable
Time
default: 101f
--
default: 0f
--
The lifespan of each particle from the time of creation. .Life_Variation animatable
Time
The number of frames by which the life of each particle can vary from the norm. .size animatable
Float
default: 1.0
--
Float
default: 0.0
--
The target size for all particles in the system. .Size_Variation animatable, percentage
The percentage by which the size of each particle may vary from the norm. .Growth_Time
Time
default: 0f
The number of intervals over which the particle grows from being very small (0.1a system constant) to the Size value. .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. .seed alias: Random_Seed
Integer
default: 0
--
By changing the Seed value, you achieve different results using otherwise identical particle settings. -- Particle Type .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.) .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.)
925
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.) .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. .Metaparticle_Tension_Variation animatable, percentage
Float
default: 0.0
--
Float
default: 0.5
--
The percent of variation of the Tension effect. .metaballRenderCoarsness alias: Metaparticle_Coarseness
The coarseness for metaparticles in the rendered scene. .metaballViewCoarsness
Float
default: 1.0
Boolean
default: true
The coarseness for the viewport display. .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. .instancingObject
Node
default: undefined
Boolean
default: false
The object which is instanced. .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. .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
Birth (The firstborn particle is an instance of the current animation of the source object at the moment of that particle’s birth. Each subsequent particle then use the same start time for the animation.) Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each particle is born using the same animation as the source object at the time of birth, but with a random offset of frames, based on the .instanceFrameOffset value.) .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. .mappingType
Integer
default: 0
Time
default: 30f
Specifies how a mapped material affects the particles: Time (Maps particles over time.) Distance (Maps particles over a distance.) .Mapping_Time_Base animatable
--
The number of frames from the birth of the particle that it takes to complete one mapping of the particle. .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. .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 .Spin_Time animatable
Time
default: 0f --
The number of frames for one rotation of a particle. If set to 0, no rotation takes place. .Spin_Time_Variation animatable, percentage
Float
default: 0.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Integer
default: 0
The percent of variation of the Spin Time. .Spin_Phase animatable, angle
The initial particle rotation, in degrees. .Spin_Phase_Variation animatable, percentage
The percent of variation of the Phase. .spinAxisType
The spin axis for the particles:
927
928
Chapter 11
|
3ds max Objects
Random (The spin axis for each of the particles is random.) Direction of Travel/Mblur (Rotates the particles about a vector formed by the direction in which they’re moving.) User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.) .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. .X_Spin_Vector animatable
Float
default: 1.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Spin vector of the X-axis. .Y_Spin_Vector animatable
Spin vector of the Y-axis. .Z_Spin_Vector animatable
Spin vector of the Z-axis. .Spin_Axis_Variation animatable, angle
The amount, in degrees, by which the spin axis of each particle may vary from the specified X Axis, Y Axis, and Z Axis settings. .Interparticle_Collisions_On
Integer
default: 0
Integer
default: 2
Turn on/off interparticle collisions: Off On .Interparticle_Collision_Steps
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. .Interparticle_Collision_Bounce animatable, percentage
Float
default: 100.0
--
default: 0.0
--
The degree to which speed is recovered after a collision. .Interparticle_Collision_Bounce_Variation animatable, percentage
Float
The percentage of random variation of the Bounce value, applied to the particles.
PCloud : GeometryClass
-- Object Motion Inheritance .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. .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. .motionVariation Float default: 0.0 animatable, percentage; alias: Object_Motion_Multiplier_Variation
--
Percentage of variation of the Multiplier value. -- Bubble Motion .Bubble_Amplitude animatable
Float
default: 0.0
--
The distance the particle moves off its usual velocity vector as it travels. .Bubble_Amplitude_Variation animatable, percentage
Float
default: 0.0
--
The percent of Amplitude variation applied to each particle. .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. .Bubble_Period_Variation animatable, percentage
Float
default: 0.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Integer
default: 0
The percent of Period variation for each particle. .Bubble_Phase animatable, angle
The initial displacement of the bubble pattern along the vector. .Bubble_Phase_Variation animatable, percentage
The percent of Phase variation for each particle. -- Particle Spawn .spawnType
Determines what happens to particles at either collision or death: None (Particles act as they normally would. That is, upon collision, they either bounce or stick, depending on Particle Bounce settings in the deflector, and on death they disappear.) Die After Collision (Particles disappear when they strike a deflector to which they’re bound, such as the SDeflector.)
929
930
Chapter 11
|
3ds max Objects
Spawn on Collision (Spawn effects take place upon collision with a bound deflector.) Spawn on Death (Spawn effects take place at the end of each particle’s life.) Spawn Trails (Particles are spawned from existing particles at each frame of that particle’s life.) .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. .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. .Spawn_Generations
Integer
default: 1
The number of spawns beyond the original particle generation. For example, if this is set to 1, and you’re spawning at death, one spawning will occur beyond the original lifespan of each particle. .Spawn_Multiplier
Integer
default: 1
Multiplies the number of particles spawned at each spawning event. .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 parent’s path by up to 90 degrees. .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. .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.) .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. .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
.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. .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.) .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. .lifespanValueQueue
Array
default: #()
lifespanValueQueue is an array of integers which correspond to lifespan values for each spawned generation of particles. .Spawn_Lifespan
Integer
default: 0
Array
default: #()
Value that sets initial lifespan of spawned particles. .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
Integer
default: 100
Maximum number of particles displayed in viewports at any given frame. <Snow>.rendercount
Integer
default: 100
Maximum number of particles that can appear in a single frame when you render it. <Snow>.flakesize
Float
Size of a particle in the active units.
default: 2.0
-- animatable, alias: Flake_Size
931
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
Float
default: 1.0
-- animatable, alias:
Speed at which snowflakes rotate. The greater the Tumble Rate, the faster the rotation. <Snow>.display
Integer
default: 0
Set how particles are displayed in viewports: Flakes (star-shaped snowflakes) Dots Ticks <Snow>.render
Integer
default: 0
Set how particles are rendered: Six Point (Each particle is rendered as a six-pointed star. Each side of the star is a face to which you can assign a material.) Triangle (Each particle is rendered as a triangle. Only one side of the triangle is a face to which you can assign a material.) Facing (Particles are rendered as square faces whose width and height equal Flake Size. Facing particles are provided especially for use with material maps.) <Snow>.start
Time
default: 0f
-- alias: starttime
Number of the first frame where particles appear. <Snow>.lifetime
Time
default: 30f
-- alias: life
The lifetime of a particle, in number of frames. <Snow>.birthrate
Time
default: 0f
-- animatable, alias: Birth_Rate
The number of new particles born per frame. If this is less than or equal to the maximum sustainable rate, the particle system generates an even flow of particles. If it is greater than the maximum rate, the particle system generates particles in bursts. <Snow>.constant
Boolean
default: true
When on, Birth Rate is unavailable and the birth rate used equals the maximum sustainable rate. When off, Birth Rate is available. Turning Constant off does not mean that the birth rate varies automatically; the birth rate remains constant unless you animate the Birth Rate parameter. <Snow>.emitterwidth
Float
The width of the emitter.
default: 25.0
-- animatable, alias: width
Spray : GeometryClass
<Snow>.emitterheight
Float
default: 25.0
-- animatable, alias: length
The height of the emitter. <Snow>.hideemitter
Boolean
default: false
When on, the emitter is hidden in the viewports. Note: The emitter is never rendered.
See also Particle System Common Properties, Operators, and Methods (p. 905) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Spray : GeometryClass Constructor: spray …
Note: This class is not available in 3D Studio VIZ. Properties: <Spray>.viewportcount
Integer
default: 100
Maximum number of particles displayed in viewports at any given frame. <Spray>.rendercount
Integer
default: 100
Maximum number of particles that can appear in a single frame when you render it. <Spray>.dropsize
Float
default: 2.0
-- animatable, alias: Drop_Size
default: 10.0
-- animatable
Size of a particle in the active units. <Spray>.speed
Float
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
933
934
Chapter 11
|
3ds max Objects
<Spray>.render
Integer
default: 0
Set how particles are rendered: Tetrahedron (Particles are rendered as long tetrahedrons, with the length you specify in the Drop Size parameter. Tetrahedron is the default setting for rendering. It provides a basic simulation of water drops.) Facing (Particles are rendered as square faces whose width and height equal Drop Size. Facing particles are provided especially for use with material maps.) <Spray>.start
Time
default: 0f
-- alias: starttime
Number of the first frame where particles appear. <Spray>.lifetime
Time
default: 30f
-- animatable, alias: life
The lifetime of a particle, in number of frames. <Spray>.birthrate Birth_Rate
Time
default: 0f
-- animatable, alias:
The number of new particles born per frame. If this is less than or equal to the maximum sustainable rate, the particle system generates an even flow of particles. If it is greater than the maximum rate, the particle system generates particles in bursts. <Spray>.constant
Boolean
default: true
When on, Birth Rate is unavailable and the birth rate used equals the maximum sustainable rate. When off, Birth Rate is available. Turning Constant off does not mean that the birth rate varies automatically; the birth rate remains constant unless you animate the Birth Rate parameter. <Spray>.emitterheight
Float
default: 25.0
-- animatable, alias: length
Float
default: 25.0
-- animatable, alias: width
Boolean
default: false
The height of the emitter. <Spray>.emitterwidth
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
SuperSpray : GeometryClass Constructor: superSpray ...
Note: This class is not available in 3D Studio VIZ. Properties: -- Basic Parameters <SuperSpray>.Off_Axis animatable, angle
Float
default: 0.0
--
Affects the angle of the particle stream off the Z axis (along the plane of the X axis). <SuperSpray>.Axis_Spread animatable, angle
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
Float
default: 0.0
--
Affects the angle of emission about the Z axis. This has no effect if Off_Axis is set to 0. <SuperSpray>.Plane_Spread animatable, angle
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
Boolean
default: false
--
Size of the emitter icon. <SuperSpray>.iconHidden
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
The percentage of particles displayed in the viewport.
Float
default: 10.0
--
935
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
Integer
default: 100
Float
default: 10.0
--
The number of particles emitted per frame. <SuperSpray>.Total_Number
The total number of particles to be emitted. <SuperSpray>.speed animatable
--
The velocity of the particle at birth, along the normal, in units traveled per frame. <SuperSpray>.Speed_Variation animatable, percentage
Float
default: 0.0
--
Percentage of variation to the speed of emission for each particle. <SuperSpray>.Emitter_Start
Time
default: 0f
Time
default: 30f
Time
default: 100f
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
Time at which all particles will disappear, regardless of other settings. <SuperSpray>.life animatable
Time
default: 30f
--
Time
default: 0f
--
The lifespan of each particle from the time of creation. <SuperSpray>.Life_Variation animatable
The number of frames by which the life of each particle can vary from the norm. <SuperSpray>.subsampleCreationTime
Boolean
default: false
When on, enables the addition of a time offset to the equations of motion that prevents puffing in time. <SuperSpray>.subsampleEmitterTranslation
Boolean
default: true
If the object-based emitter is moving in space, particles are created at integral times at positions along the geometry’s path between renderable positions. This prevents puffing in space. <SuperSpray>.subsampleEmitterRotation
Boolean
default: true
If the emitter is rotating, turn this on to avoid puffing and produce smooth spiral effects. <SuperSpray>.size animatable
The target size for all particles in the system.
Float
default: 1.0
--
SuperSpray : GeometryClass
<SuperSpray>.Size_Variation animatable, percentage
Float
default: 0.0
--
The percentage by which the size of each particle may vary from the norm. <SuperSpray>.Growth_Time
Time
default: 10f
The number of intervals over which the particle grows from being very small (0.1a system constant) to the Size value. <SuperSpray>.Fade_Time
Time
default: 10f
The number of intervals over which the particle will shrink to 1/10th its Size setting prior to its death. <SuperSpray>.seed 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.)
937
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
--
Float
default: 0.5
--
Float
default: 1.0
Boolean
default: true
The percent of variation of the Tension effect. <SuperSpray>.metaballRenderCoarsness alias: Metaparticle_Coarseness
The coarseness for metaparticles in the rendered scene. <SuperSpray>.metaballViewCoarsness
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
default: undefined
Boolean
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 particle’s birth. Each subsequent particle then use the same start time for the animation.) Random (This option is the same as None when Frame Offset is set to 0. Otherwise, each particle is born using the same animation as the source object at the time of birth, but with a random offset of frames, based on the .instanceFrameOffset value.) <SuperSpray>.instanceFrameOffset 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
<SuperSpray>.mappingType
Integer
default: 0
Time
default: 30f
Specifies how a mapped material affects the particles: Time (Maps particles over time.) Distance (Maps particles over a distance.) <SuperSpray>.Mapping_Time_Base animatable
--
The number of frames from the birth of the particle that it takes to complete one mapping of the particle. <SuperSpray>.Mapping_Distance_Base 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
Time
default: 30f
--
The number of frames for one rotation of a particle. If set to 0, no rotation takes place. <SuperSpray>.Spin_Time_Variation animatable, percentage
Float
default: 0.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Integer
default: 0
The percent of variation of the Spin Time. <SuperSpray>.Spin_Phase animatable, angle
The initial particle rotation, in degrees. <SuperSpray>.Spin_Phase_Variation animatable, percentage
The percent of variation of the Phase. <SuperSpray>.spinAxisType
The spin axis for the particles: Random (The spin axis for each of the particles is random.) Direction of Travel/Mblur (Rotates the particles about a vector formed by the direction in which they’re moving.) User Defined (Uses a vector defined in the three X, Y, and Z spin vector values.) <SuperSpray>.Blur_Stretch 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
Spin vector of the X-axis.
Float
default: 1.0
--
939
940
Chapter 11
|
3ds max Objects
<SuperSpray>.Y_Spin_Vector animatable
Float
default: 0.0
--
Float
default: 0.0
--
Float
default: 0.0
--
Spin vector of the Y-axis. <SuperSpray>.Z_Spin_Vector animatable
Spin vector of the Z-axis. <SuperSpray>.Spin_Axis_Variation animatable, angle
The amount, in degrees, by which the spin axis of each particle may vary from the specified X Axis, Y Axis, and Z Axis settings. <SuperSpray>.Interparticle_Collisions_On
Integer
default: 0
Integer
default: 2
Turn on/off interparticle collisions: OFF ON <SuperSpray>.Interparticle_Collision_Steps
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 --
Float
default: 0.0
The degree to which speed is recovered after a collision. <SuperSpray>.Interparticle_Collision_Bounce_Variation animatable, percentage
--
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
Float
default: 0.0
--
The distance the particle moves off its usual velocity vector as it travels. <SuperSpray>.Bubble_Amplitude_Variation animatable, percentage
Float
The percent of Amplitude variation applied to each particle.
default: 0.0
--
SuperSpray : GeometryClass
<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
--
Float
default: 0.0
--
Float
default: 0.0
--
Integer
default: 0
The percent of Period variation for each particle. <SuperSpray>.Bubble_Phase animatable, angle
The initial displacement of the bubble pattern along the vector. <SuperSpray>.Bubble_Phase_Variation animatable, percentage
The percent of Phase variation for each particle. -- Particle Spawn <SuperSpray>.spawnType
Determines what happens to particles at either collision or death: None (Particles act as they normally would. That is, upon collision, they either bounce or stick, depending on Particle Bounce settings in the deflector, and on death they disappear.) Die After Collision (Particles disappear when they strike a deflector to which they’re bound, such as the SDeflector.) Spawn on Collision (Spawn effects take place upon collision with a bound deflector.) Spawn on Death (Spawn effects take place at the end of each particle’s life.) Spawn Trails (Particles are spawned from existing particles at each frame of that particle’s life.) <SuperSpray>.Die__X_frames_after_collision 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.
--
941
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 parent’s 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
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 ...
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 ...
See Creating New NURBS Objects (p. 1389) for details.
943
944
Chapter 11
|
3ds max Objects
Properties: .thickness
Float
default: 1.0
--
animatable
Rendered thickness of the surface. .sides
Integer
default: 12
--
animatable
Rendered sides of the surface. .angle
Float
default: 0.0
--
animatable
The rotational position of the cross-section in the renderer. Other properties for Point Surfaces are accessed through a NURBSSet descriptor object. See Working with NURBS (p. 1384) for more details.
See also NURBS Node Properties and Methods (p. 1397) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Shape : Node The following list shows the 3ds max shape class objects: --Splines Arc (p. 949) Circle (p. 950) Donut (p. 951) Ellipse (p. 953) Helix (p. 954) Line (p. 955) NGon (p. 957) Rectangle (p. 958) Section (p. 959) Star (p. 960) Text (p. 962) --NURBS Curves CV_Curve (p. 964) Point_Curve (p. 965)
Shape Common Properties, Operators, and Methods
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 curve’s 3ds max unit length, which usually is more than enough. For example, if a curve has a length of 100 3ds max units, the default step size would be 500. The interpolation algorithm has an accuracy of no better than + or - (1/steps) 3ds max units. These methods employ a cache to speed up their operation in the common case where you step
945
946
Chapter 11
|
3ds max Objects
gradually along a single curve. The cache remembers the state for the last point on the curve and picks up there if you call again on the same curve at the same animation time. This can exponentially speed up interpolation processing. However, MAXScript does not have a way of knowing if you’ve edited the curve from one call to the next, so you have to be sure to reset the cache with the resetLengthInterp() method if the user can edit the curve between calls in your code. All coordinates are in the current coordinate system. pathInterp <shape> [ <curve_num> ] <parameter>
Return a point3 coordinate on the numbered curve (defaults to 1) corresponding to the parameter value (0.0 to 1.0) that matches the 3ds max Path controller percentage (vertexbased) interpolation. lengthInterp <shape> [ <curve_num> ] <parameter> [ steps: ]
Return a point3 coordinate on the numbered curve (defaults to 1) corresponding to the parameter value (0.0 to 1.0) that is that fraction along the curve’s total length. resetLengthInterp()
Clear length interpolation cache. Use this if the curve you are length-interpolating along might have been edited between calls. curveLength <shape> [ <curve_num> ]
Return the arc length of the numbered curve. This length does not reflect any transform level scaling performed on the shape. pathTangent <shape> [ <curve_num> ] <parameter>
Return the tangent direction vector at the 3ds max Path (vertex-based) interpolated point along the specified curve. You can use this function, for example, to set an object’s direction to follow the curve. lengthTangent <shape> [ <curve_num> ] <parameter> [ steps: ]
Return the tangent direction vector at the arc-length-interpolated point along the specified curve. You can use this function to set an object’s direction to follow the curve. nearestPathParam <shape> [ <curve_num> ] <point3> [ steps: ]
Return the interpolation parameter value (0.0 to 1.0) corresponding to the point along the curve that is closest to the given <point3> coordinate. The parameter is given as a 3ds max Path (vertex-based) interpolation parameter value. You can then use pathInterp with this value to find the nearest point’s coordinates, or use one of the following functions for converting between arc-length parameters and 3ds max Path percentage parameters. pathToLengthParam <shape> [ <curve_num> ] <parameter> [ steps: ]
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: ]
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
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Shapes - Splines The following list shows the 3ds max spline shape class objects: Arc (p. 949) Circle (p. 950) Donut (p. 951) Ellipse (p. 953) Helix (p. 954) Line (p. 955) NGon (p. 957) Rectangle (p. 958) Section (p. 959) Star (p. 960)
Spline Shape Common Properties, Operators, and Methods The following properties methods apply to all spline shape objects. Properties: <spline>.renderable
Boolean
default: false
When on, the shape is rendered using a 12-sided circle as a cross section. <spline>.thickness
Float
default: 1.0
The diameter of the rendered spline. <spline>.mapCoords
Boolean
default: false
When on, applies mapping coordinates. The U coordinate is wrapped once around the thickness of the spline, while the V coordinate is mapped once along the length of the spline. Tiling is achieved via the tiling parameters of the material. Note: Since renderable is a property for all nodes, a name conflict exists between the renderable property for nodes and the renderable property for splines. MAXScript handles the conflict for this property differently than for all other cases where an object class property name conflicts with a node level property name. Normally, you would access the node level property as a property of the node, and the object property as a property of the baseobject property of the node. The renderable property however is always applied to the spline object’s renderable property rather than the node’s renderable property.
947
948
Chapter 11
|
3ds max Objects
So, looking in the Object Properties dialog, $.renderable=false turns off renderable at the node level. To turn off the spline’s renderable property, you need to say $.baseobject.renderable=false. Methods: The following methods are defined for 3D Studio VIZ. applyOffset <spline_shape_node>
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 \ [trim: ] [extend: ] [infinite: ] \ [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
Arc : Shape Constructor: arc ...
Properties: .radius
Float
default: 25.0
-- animatable
Float
default: 45.0
-- animatable
The arc radius. .from
Location of the start point as an angle measured from the local positive X axis. .to
Float
default: 135.0
-- animatable
Location of the end point as an angle measured from the local positive X axis. .pie
Boolean
default: false
When on, creates a closed spline in the form of a pie. The start point and end point are connected to the center with straight segments. .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. .steps
Integer
default: 6
Number of divisions between each vertex. .optimize
Boolean
default: true
When on, removes unneeded steps from straight segments in the spline. .adaptive
Boolean
default: false
When on, sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps. .angle
Float
default: 0.0
--
animatable
The rotational position of the cross-section in the renderer. .thickness
Float
default: 1.0
--
animatable
Diameter of the rendered spline. .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. .viewport_thickness Float
default: 1.0
Diameter of the viewport spline. .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. .viewport_angle
Float
default: 0.0
The rotational position of the cross-section in the viewports.
949
950
Chapter 11
|
3ds max Objects
.DisplayRenderMesh
Boolean
default: false
When on, displays the mesh generated by the spline in the viewports. .UseViewportSettings
Boolean
default: false
When on, displays the mesh generated by the Viewport settings. .DisplayRenderSettings
Boolean
default: true
When on, displays the mesh generated by the render settings. .renderableBoolean
default: true
When on, the spline is displayed in the rendered scene. .mapCoordsBoolean
default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline. Note: The Reverse property is not accessible to MAXScript in 3ds max 4.
See also Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Circle : Shape Constructor: circle ...
Properties: .radius
Float
default: 25.0
-- animatable
The radius of the circle. .steps
Integer
default: 6
The number of divisions between each vertex. .optimize
Boolean
default: true
When on, removes unneeded steps from straight segments in the spline. .adaptive
Boolean
default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps. .angle
Float
default: 0.0
--
animatable
The rotational position of the cross-section in the renderer. .thickness
Float
Diameter of the rendered spline.
default: 1.0
--
animatable
Donut : Shape
.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. .viewport_thickness Float
default: 1.0
Diameter of the viewport spline. .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. .viewport_angle
Float
default: 0.0
The rotational position of the cross-section in the viewports. .DisplayRenderMesh
Booleandefault: false
When on, displays the mesh generated by the spline in the viewports. .UseViewportSettings
Boolean
default: false
When on, displays the mesh generated by the Viewport settings. .DisplayRenderSettings
Boolean
default: true
When on, displays the mesh generated by the render settings. .renderableBoolean
default: true
When on, the spline is displayed in the rendered scene. .mapCoordsBoolean
default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline.
See also Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Donut : Shape Constructor: donut ...
Properties: .radius1
Float
default: 35.0
-- animatable
Sets the radius of the first circle. .radius2
Float
default: 25.0
Sets the radius of the second circle. .steps
Integer
default: 6
The number of divisions between each vertex.
-- animatable
951
952
Chapter 11
|
3ds max Objects
.optimize
Boolean
default: true
When on, removes unneeded steps from straight segments in the spline .adaptive
Boolean
default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps. .angle
Float
default: 0.0
--
animatable
The rotational position of the cross-section in the renderer. .thickness
Float
default: 1.0
--
animatable
Diameter of the rendered spline. .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. .viewport_thickness
Float
default: 1.0
Diameter of the viewport spline. .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. .viewport_angle
Float
default: 0.0
The rotational position of the cross-section in the viewports. .DisplayRenderMesh
Boolean default: false
When on, displays the mesh generated by the spline in the viewports. .UseViewportSettings
Boolean
default: false
When on, displays the mesh generated by the Viewport settings. .DisplayRenderSettings
Boolean
default: true
When on, displays the mesh generated by the render settings. .renderable
Boolean
default: true
When on, the spline is displayed in the rendered scene. .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
Ellipse : Shape Constructor: ellipse ...
Properties: <Ellipse>.length
Float
default: 25.0
-- animatable
The size of the Ellipse along the local Y axis. <Ellipse>.width
Float
default: 35.0
-- animatable
The size of the Ellipse local X axis. <Ellipse>.steps
Integer
default: 6
The number of divisions between each vertex. <Ellipse>.optimize
Boolean
default: true
When on, removes unneeded steps from straight segments in the spline. <Ellipse>.adaptive
Boolean
default: false
When on, Adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps. <Ellipse>.angle
Float
default: 0.0
--
animatable
The rotational position of the cross-section in the renderer. <Ellipse>.thickness
Float
default: 1.0
--
animatable
Diameter of the rendered spline. <Ellipse>.sides
Float
default: 12.0
--
animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example. <Ellipse>.viewport_thickness Float
default: 1.0
Diameter of the viewport spline. <Ellipse>.viewport_sides
Integer
default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example. <Ellipse>.viewport_angle
Float
default: 0.0
The rotational position of the cross-section in the viewports. <Ellipse>.DisplayRenderMesh
Boolean
default: false
When on, displays the mesh generated by the spline in the viewports. <Ellipse>.UseViewportSettings
Boolean
default: false
When on, displays the mesh generated by the Viewport settings. <Ellipse>.DisplayRenderSettings
Boolean
default: true
When on, displays the mesh generated by the render settings. <Ellipse>.renderableBoolean
default: true
When on, the spline is displayed in the rendered scene. <Ellipse>.mapCoordsBoolean
default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline.
953
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: .radius1
Float
default: 35.0
-- animatable
The radius for the Helix start. .radius2
Float
default: 15.0
-- animatable
The radius for the Helix end. .height
Float
default: 25.0
-- animatable
default: 2.0
-- animatable
The height of the Helix. .turns
Float
The number of turns the Helix makes between its start and end points. .bias
Float
default: 0.0
-- animatable
Forces the turns to accumulate at one end of the helix. A bias of -1.0 forces the turns towards the start of the helix, a bias of 0.0 evenly distributes the turns between the ends, and a bias of 1.0 forces the turns towards the end of the helix. .direction
Integer
default: 0
Set the direction the helix turns: Clockwise Counterclockwise .angle
Float
default: 0.0
--
animatable
The rotational position of the cross-section in the renderer. .thickness
Float
default: 1.0
--
animatable
Diameter of the rendered spline. .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. .viewport_thickness Float
Diameter of the viewport spline.
default: 1.0
Line : Shape
.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. .viewport_angle
Float
default: 0.0
The rotational position of the cross-section in the viewports. .DisplayRenderMesh
Boolean
default: false
When on, displays the mesh generated by the spline in the viewports. .UseViewportSettings
Boolean
default: false
When on, displays the mesh generated by the Viewport settings. .DisplayRenderSettings
Boolean
default: true
When on, displays the mesh generated by the render settings. .renderableBoolean
default: true
When on, the spline is displayed in the rendered scene. .mapCoordsBoolean
default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline.
See also Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Line : Shape Constructor: line ...
Properties: .steps
Integer
default: 6
The number of divisions between each vertex. .optimize
Boolean
default: true
When on, removes unneeded steps from straight segments in the spline. .adaptive
Boolean
default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps. .angle
Float
default: 0.0
--
animatable
The rotational position of the cross-section in the renderer. .thickness
Float
default: 1.0
Diameter of the rendered spline.
--
animatable
955
956
Chapter 11
|
.sides
3ds max Objects
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. .viewport_thickness Float
default: 1.0
Diameter of the viewport spline. .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. .viewport_angle
Float
default: 0.0
The rotational position of the cross-section in the viewports. .DisplayRenderMesh
Boolean
default: false
When on, displays the mesh generated by the spline in the viewports. .UseViewportSettings
Boolean
default: false
When on, displays the mesh generated by the Viewport settings. .DisplayRenderSettings
Boolean
default: true
When on, displays the mesh generated by the render settings. .renderableBoolean
default: true
When on, the spline is displayed in the rendered scene. .mapCoordsBoolean
default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline. Note: The Line shape is equivalent to a SplineShape shape. All the properties and methods associated with SplineShape are also valid on a Line shape. These properties and methods are described in the SplineShape : Shape (p. 1079) topic.
See also Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
NGon : Shape
NGon : Shape Constructor: ngon ...
Properties: .radius
Float
default: 25.0
Integer
default: 0
-- animatable
The NGon radius. .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) .sides
Integer
default: 6
-- animatable
Number of sides and vertices used by the NGon. .corner_Radius
Float
default: 0.0
-- animatable
Degree of rounding to apply to the corners of the NGon. A setting of 0 specifies a standard unrounded corner. .circular
Boolean
default: true
-- animatable
When on, specifies a circular NGon. .steps
Integer
default: 6
The number of divisions between each vertex. .optimize
Boolean
default: true
When on, removes unneeded steps from straight segments in the spline. .adaptive
Boolean
default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps. .angle
Float
default: 0.0
-- animatable
The rotational position of the cross-section in the renderer. .radiusFloat default: 1.0 -- animatable .thickness Float default: 1.0 -- animatable
Radius of the rendered spline. .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. .viewport_thickness Float
default: 1.0
Diameter of the viewport spline. .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. .viewport_angle
Float
default: 0.0
The rotational position of the cross-section in the viewports.
957
958
Chapter 11
|
3ds max Objects
.DisplayRenderMesh
Boolean
default: false
When on, displays the mesh generated by the spline in the viewports. .UseViewportSettings
Boolean
default: false
When on, displays the mesh generated by the Viewport settings. .DisplayRenderSettings
Boolean
default: true
When on, displays the mesh generated by the render settings. .renderableBoolean
default: true
When on, the spline is displayed in the rendered scene. .mapCoordsBoolean
default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline.
See also Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Rectangle : Shape Constructor: rectangle ...
Properties: .length
Float
default: 10.0
-- animatable
The size of the rectangle along the local Y axis. .width
Float
default: 25.0
-- animatable
The size of the rectangle along the local X axis. .Corner_Radius cornerRadius
Float
default: 0.0
-- animatable; alias:
Creates rounded corners. When set to 0, the rectangle contains 90-degree corners. .steps
Integer
default: 6
The number of divisions between each vertex. .optimize
Boolean
default: true
When on, removes unneeded steps from straight segments in the spline. .adaptive
Boolean
default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps. .angle
Float
default: 0.0
-- animatable
The rotational position of the cross-section in the renderer.
Section : Shape
.thickness
Float
default: 1.0
-- animatable
Radius of the rendered spline. .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. .viewport_thickness Float
default: 1.0
Diameter of the viewport spline. .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. .viewport_angle
Float
default: 0.0
The rotational position of the cross-section in the viewports. .DisplayRenderMesh
Boolean
default: false
When on, displays the mesh generated by the spline in the viewports. .UseViewportSettings
Boolean
default: false
When on, displays the mesh generated by the Viewport settings. .DisplayRenderSettings
Boolean
default: true
When on, displays the mesh generated by the render settings. .renderableBoolean
default: true
When on, the spline is displayed in the rendered scene. .mapCoordsBoolean
default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline.
See also Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Section : Shape Constructor: section ...
Properties: <Section>.length
Float
default: 0.0
-- animatable
The length of the displayed section rectangle. <Section>.width
Float
default: 0.0
The width of the displayed section rectangle.
-- animatable
959
960
Chapter 11
|
3ds max Objects
Note: The Section Parameters rollout item properties are not accessible to MAXScript in 3ds max 4. A bug prevents a Section shape from being properly collapsed to a SplineShape in some cases. This only happens when a Section shape is created inside a loop and is being converted to a SplineShape. To collapse to a SplineShape, a viewport redraw must be performed after the Section shape is created. An example of creating contour lines from an object is: Script: meshSelected = sphere() -- object to create contours of minZ = meshSelected.min.z -- get min and max Z positions maxZ = meshSelected.max.z numLevels = 10 -- the number of contours delta = (maxZ - minZ) / (numLevels + 1) -- the number of steps for currentZ = minZ to maxZ by delta do -- start loop... ( s = section pos:[0, 0, currentZ] -- create Section max views redraw -- this line needed to get around bug convertToSplineShape s -- convert Section to SplineShape s.renderable = true -- set to renderable )
See also Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Star : Shape Constructor: star ...
Properties: <Star>.radius1
Float
default: 25.0 -- alias: Radius_1
The radius of the inner vertices of the star. <Star>.radius2
Float
default: 12.0 -- alias: Radius_2
The radius of the outer vertices of the star. <Star>.points
Integer
default: 6
-- alias: numPoints
The number of points on the star. The valid range is from 3 to 100. <Star>.distort
Float
default: 0.0
-- alias: Distortion
Rotates the outer vertices about the center of the star. This produces a saw-tooth affect. <Star>.fillet1Floatdefault: 0.0
Rounds the inner vertices (the valleys) of the star.
Star : Shape
<Star>.fillet2Floatdefault: 0.0
Rounds the outer vertices (the points) of the star. <Star>.steps
Integer
default: 6
The number of divisions between each vertex. <Star>.optimize
Boolean
default: true
When on, removes unneeded steps from straight segments in the spline. <Star>.adaptive
Boolean
default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps. <Star>.angle
Float
default: 0.0
-- animatable
The rotational position of the cross-section in the renderer. <Star>.thickness
Float
default: 1.0
-- animatable
Radius of the rendered spline. <Star>.sides
Float
default: 12.0
-- animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example. <Star>.viewport_thickness Float
default: 1.0
Diameter of the viewport spline. <Star>.viewport_sides
Integer
default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example. <Star>.viewport_angle
Float
default: 0.0
The rotational position of the cross-section in the viewports. <Star>.DisplayRenderMesh
Boolean
default: false
When on, displays the mesh generated by the spline in the viewports. <Star>.UseViewportSettings
Boolean
default: false
When on, displays the mesh generated by the Viewport settings. <Star>.DisplayRenderSettings
Boolean
default: true
When on, displays the mesh generated by the render settings. <Star>.renderableBoolean
default: true
When on, the spline is displayed in the rendered scene. <Star>.mapCoords
Boolean
default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline. Note: The Fillet_Radius_1 and Fillet_Radius_2 properties are not accessible to MAXScript in 3ds max 4. In order to access the points property for Star, you need to access the property via the baseobject property of the node. This is because points is also a property name for all nodes, and conflicts with the Star’s points property. For example: MyStar.baseobject.points=10
-- set number of Star points to 10
961
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: .font
String
default: “Arial”
Choose from a list of all fonts available to 3ds max. .italic
Boolean
default: false
Turn on/off italicized text. .underline
Boolean
default: false
Turn on/off underlined 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.) .size
Float
default: 100.0
-- animatable
Te text height where the height measuring method is defined by the active font. .kerning
Float
default: 0.0
-- animatable
The kerning (the distance between letters). .leading
Float
default: 0.0
-- animatable
The leading (the distance between lines). .text
String
default: “3ds max Text”
The text displayed in the viewport. .steps
Integer
default: 6
The number of divisions between each vertex. .optimize
Boolean
default: true
When on, removes unneeded steps from straight segments in the spline. .adaptive
Boolean
default: false
When on, adaptive sets the number of steps for each spline to produce a smooth curve. Straight segments always receive 0 steps.
Text : Shape
.angle
Float
default: 0.0
-- animatable
The rotational position of the cross-section in the renderer. .thickness
Float
default: 1.0
-- animatable
Radius of the rendered spline. .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. .viewport_thickness Float
default: 1.0
Diameter of the viewport spline. .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. .viewport_angle
Float
default: 0.0
The rotational position of the cross-section in the viewports. .DisplayRenderMesh
Boolean
default: false
When on, displays the mesh generated by the spline in the viewports. .UseViewportSettings
Boolean
default: false
When on, displays the mesh generated by the Viewport settings. .DisplayRenderSettings
Boolean
default: true
When on, displays the mesh generated by the render settings. .renderableBoolean
default: true
When on, the spline is displayed in the rendered scene. .mapCoordsBoolean
default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the spline; the V coordinate is mapped once along the length of the spline. Note: The Manual Update and Alignment properties are not accessible to MAXScript in 3ds max 4. In 3DS VIZ, the default value for property Text is “VIZ Text”
See also Spline Shape Common Properties, Operators, and Methods (p. 947) Shape Common Properties, Operators, and Methods (p. 945) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
963
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 ...
See Creating New NURBS Objects (p. 1389) for details. Properties: .angle
Float
default: 0.0
-- animatable
The rotational position of the cross-section in the renderer. .thickness
Float
default: 1.0
-- animatable
Diameter of the rendered curve. .sides
Float
default: 12.0
-- animatable
Sets the number of sides for the curve mesh in the renderer. A value of 4 will give you a square cross section, for example. .renderableBoolean
default: true
When on, the curve is displayed in the rendered scene. .mapCoordsBoolean
default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the curve; the V coordinate is mapped once along the length of the curve. Additional Properties for CV curves are accessed through a NURBSSet descriptor object. See Working with NURBS (p. 1384) for more details.
See also Shape Common Properties, Operators, and Methods (p. 945) NURBS Node Properties and Methods (p. 1397) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Point_Curve : Shape
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 ...
See Creating New NURBS Objects (p. 1389) for details. Properties: .angle
Float
default: 0.0
-- animatable
The rotational position of the cross-section in the renderer. .thickness
Float
default: 1.0
-- animatable
Diameter of the rendered curve. .sides
Float
default: 12.0
-- animatable
Sets the number of sides for the curve mesh in the renderer. A value of 4 will give you a square cross section, for example. .renderableBoolean
default: true
When on, the curve is displayed in the rendered scene. .mapCoordsBoolean
default: false
Turn this on to apply mapping coordinates. The U coordinate wraps once around the thickness of the NURBS curve; the V coordinate is mapped once along the length of the curve. Additional properties for point curves are accessed through a NURBSSet descriptor object. See Working with NURBS (p. 1384) for more details.
See also Shape Common Properties, Operators, and Methods (p. 945) NURBS Node Properties and Methods (p. 1397) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
965
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. .type
Name
default: #freeDirect
Boolean
default: true
the valid type values are: #omni #freeSpot #targetSpot #freeDirect #targetDirect .enabled
-- 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. .excludeList
Array
default: #()
Objects in this array are excluded from the effects of the light. .includeList
Array
default: undefined
Objects in this array receive the effects of the light. .inclExclType Integer default: 3
Select the type of object in the Include/Exclude list: Illumination Shadow Casting Both .castShadows
Boolean
default: false
When on, the light will cast shadows on objects. .rgb animatable, alias: color
Color
default: (color 180 180 180)
The red, green, and blue components of the light’s color.
--
Light Common Properties, Operators, and Methods
.hsv
Point3
default: [0,0,180]
Hue, Saturation, and Value color of light. .hue
Integer
default: 0
Integer
default: 0
Integer
default: 180
Float
default: 1.0
Hue component of hsv. .saturation
Saturation component of hsv. .value
Value component of hsv. .multiplier
-- animatable
Amplifies the power of the light by a positive or negative amount. .contrast
Float
default: 0.0
-- animatable
Adjusts the contrast between the diffuse and ambient areas of the surface. Leave this set to 0 for normal contrast. Increase the value to increase the contrast for special effects: for example, the harsh light of outer space. .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. .affectDiffuse
Boolean
default: true
When on, the light affects the diffuse properties of an object’s surface. When off, the light has no effect on the diffuse surface. .affectSpecular
Boolean
default: true
When on, the light affects the specular properties of an object’s surface. When off, the light has no effect on the specular properties. .ambientOnly
Boolean
default: false
When on, the light affects only the ambient component of the illumination. .projector
Boolean
default: false
Turn on to project projectorMap. .projectorMap
TextureMap
default: undefined
Assigning a TextureMap to projectorMap causes a new subAnim named Projection_Map to be created for the light. This subAnim contains the properties of the TextureMap. .useShadowProjectorMap Boolean default: false
When on, the light will project a map. .nearAttenStart Float animatable, alias: Attenuation_Near_Start
default: 0.0
-- alias:
The distance at which the light begins to fade in. .nearAttenEnd Float animatable, alias: Attenuation_Near_End
default: 40.0
The distance at which the light reaches its full value.
-- alias:
967
968
Chapter 11
|
3ds max Objects
.useNearAtten
Boolean
default: false
Enables/Disables near attenuation for the light. .showNearAtten
Boolean
default: false
When on, displays the near attenuation range settings in viewports. For spotlights, attenuation ranges appear as lens-shaped sections of the cone. For directional lights, the ranges appear as circular sections of the cone. For omni lights and spot or directional lights with Overshoot turned on, the ranges appear as spheres. .farAttenStart alias: Attenuation_Far_Start
Float
default: 80.0
-- animatable,
The distance at which the light begins to fade out. .farAttenEnd alias: Attenuation_Far_End
Float
default: 200.0
-- animatable,
The distance at which the light has faded to zero. .useFarAtten
Boolean
default: false
Enables/Disables far attenuation for the light. .showFarAtten
Boolean
default: false
Displays the far attenuation range settings in viewports. For spotlights, attenuation ranges appear as lens-shaped sections of the cone. For directional lights, the ranges appear as circular sections of the cone. For omni lights and spot or directional lights with Overshoot turned on, the ranges appear as spheres. .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.) .DecayRadius alias: Decay_Falloff
Float
default: 40.0
-- animatable,
The distance over which the decay occurs. .useGlobalShadowSettings
Boolean
default: false
Turn on to use global settings for shadows cast by this light. Turn off to enable individual control of the shadows. .raytracedShadows
Boolean
default: false
When true, ray traced shadows are produced. When false, shadow-mapped shadows are produced. .ShadowColor alias: Shadow_Color
Color
The color of shadows cast by this light.
default: (color 0 0 0) -- animatable,
Light Common Properties, Operators, and Methods
.shadowMultiplier alias: Shadow_Density .shadowProjectorMap
Float
default: 1.0
-- animatable,
TextureMap
default: undefined
Assigning a TextureMap to shadowProjectorMap causes a new subAnim named Shadow_Projection_Map to be created for the light. This subAnim contains the properties of the TextureMap. .lightAffectsShadow
Boolean
default: false
When on, blends the light’s color with the shadow color (or shadow colors, if the shadow is mapped). .atmosShadows
Boolean
default: true
When on, atmospheric effects cast shadows as the light passes through them. .atmosOpacity Float percentage, alias: Atmosphere_Opacity
default: 100.0
-- animatable,
Adjusts the opacity of the shadows. This value is a percentage. .atmosColorAmt Float percentage, alias: Atmosphere_Color_Amount
default: 100.0
-- animatable,
Adjusts the amount that the atmosphere’s color is blended with the shadow color. If Shadow Maps are being used (raytracedShadows = false), the shadow properties are: .mapBias alias: map_bias
Float
default: 1.0
-- animatable,
Moves the shadow toward or away from the shadow-casting object (or objects). .mapSize alias: map_size
Integer
default: 512
-- animatable,
Sets the size (in pixels squared) of the shadow map that’s computed for the light. .sampleRange alias: map_range
Float
default: 4.0
-- animatable,
Determines how much area within the shadow is averaged. This affects how soft the edge of the shadow is. .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. .absolute_Bias absoluteMapBias
Integer
default: 0
-- integer alias of
969
970
Chapter 11
|
3ds max Objects
If Ray Traced Shadows are being used (raytracedShadows = true), the shadow properties are: .raytraceBias
Float
default: 0.2
-- animatable
Moves the shadow toward or away from the shadow-casting object (or objects). If the Bias value is too low, shadows can “leak” through places they shouldn’t, produce moire patterns or making out-of-place dark areas on meshes. If Bias is too high, shadows can “detach” from an object. If the Bias value is too extreme in either direction, shadows might not be rendered at all. .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: .aspect alias: Aspect_Ratio
Float
default: 1.0
-- animatable,
default: 45.0
-- animatable
The aspect ratio for the rectangular light beam. .falloff
Float
The size of a light’s falloff. The Falloff value is measured in 3ds max units. .showCone
Boolean
default: false
Float
default: 43.0
Turns display of the cone on or off. .hotspot
-- animatable
The size of a light’s cone. The Hotspot value is measured in 3ds max units.
FreeSpot : Light
.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. .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: .aspect Aspect_Ratio
Float
default: 1.0
-- animatable, alias:
The aspect ratio for the rectangular light beam. .falloff
Float
default: 45.0
-- animatable
The angle of a light’s falloff. The Falloff value is measured in degrees. .showCone
Boolean
default: false
Turns display of the cone on or off. .hotspot
Float
default: 43.0
-- animatable
The angle of a light’s cone. The Hotspot value is measured in degrees. .overShoot
Boolean
default: false
When on, the light casts light in all directions. However, projections and shadows occur only within its falloff cone. .coneShape
Integer
default: 1
The shape of the falloff and hotspot areas: Circle Rectangle
-- alias: lightShape
971
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: .aspect alias: Aspect_Ratio
Float
default: 1.0
-- animatable,
default: 45.0
-- animatable
The aspect ratio for the rectangular light beam. .falloff
Float
The angle of a light’s falloff. The Falloff value is measured in degrees. .showCone
Boolean
default: false
Float
default: 43.0
Turns display of the cone on or off. .hotspot
-- animatable
The angle of a light’s cone. The Hotspot value is measured in degrees. .overShoot
Boolean
default: false
When on, the light casts light in all directions. However, projections and shadows occur only within its falloff cone.
TargetSpot : Light
.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: .aspect Aspect_Ratio
Float
default: 1.0
-- animatable, alias:
The aspect ratio for the rectangular light beam. .falloff
Float
default: 45.0
-- animatable
The angle of a light’s falloff. The Falloff value is measured in degrees. .showCone
Boolean
default: false
Turns display of the cone on or off. .hotspot
Float
default: 43.0
-- animatable
The angle of a light’s cone. The Hotspot value is measured in degrees. .overShoot
Boolean
default: false
When on, the light casts light in all directions. However, projections and shadows occur only within its falloff cone. .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])
973
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: .fov
Float
default: 45.0
-- animatable, angle
Determines how wide an area the camera views. .orthoProjection
Boolean
default: false
When on, the camera view looks just like a User view. When off, the camera view is the standard perspective-like view. .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) .showCone
Boolean
default: false
Displays the cone (actually a pyramid) defined by a camera’s field of view. The cone appears in the other viewports but does not appear in a camera viewport. .showHorizon
Boolean
default: false
Displays the horizon line. A dark gray line appears at the level of the horizon in the camera’s viewport. .nearrange Near_Env_Range
Float
default: 0.0
-- animatable; alias:
default: 1000.0
-- animatable; alias:
The near range for atmospheric effects. .farrange Far_Env_Range
Float
The far range for atmospheric effects.
Camera Common Properties, Operators, and Methods
.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. .nearclip near_clip
Float
default: 1.0
-- animatable, alias:
Objects closer than the near clipping plane are invisible to the camera. .farclip far_clip
Float
default: 1000.0
-- animatable, alias:
Objects farther than the far clipping plane are invisible to the camera. .showRanges
Boolean
default: false
When on, displays yellow rectangles within the camera’s cone to show the Near and Far range settings. .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 renderer’s image aspect ratio in coordsys cam -- work in coordinate system of the camera
975
976
Chapter 11
|
3ds max Objects
( for obj in objs where obj != cam do -- loop across all objects except the camera ( if obj.min.z >=0 do continue -- if object is behind camera, skip it -- get max value of the object’s bounding box, correcting for the image aspect ratio -- in the y values v = maxof #((abs obj.max.x),(abs obj.min.x),(abs (obj.max.y*asp)),(abs (obj.min.y*asp))) fov = maxof #(fov,(2*atan(-v/obj.min.z))) -- increase fov if needed ) ) cam.fov=fov -- set the camera’s fov to the new fov value ) --test bed -cam=$camera01 -- specify the camera to “zoom extent all” on ZE_Cam cam $* -- call the function, passing the camera and an object set containing all objects
FreeCamera : Camera Constructor: freecamera ...
Properties: There are no additional properties for FreeCamera.
See also Camera Common Properties, Operators, and Methods (p. 974) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
TargetCamera : Camera Constructor: targetCamera ...
Properties: There are no additional properties for TargetCamera.
TargetCamera : Camera
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)
977
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
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: .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)
979
980
Chapter 11
|
3ds max Objects
Grid : Helper Constructor: grid ...
Properties: .length
Float
default: 50.0
-- animatable
default: 50.0
-- animatable
default: 10.0
-- animatable
Length of the grid. .width
Float
Width of the grid. .grid
Float
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: .axisLength
Float
default: 20.0
Sets the length of the tripod axis. .size
Float
default: 20.0
--
animatable
Sets the size of of the point helper. .centermarker
Boolean
default: false
--
animatable
When turned on, a small X marker is displayed at the center of the point helper object. .axistripod
Boolean
default: false
--
animatable
When this is turned on, an axis tripod with ‘x’, ‘y’, and ‘z’ labels is displayed. .cross
Boolean
default: true
--
animatable
When this is turned on, an axis aligned cross is displayed. .box
Boolean
default: false
--
animatable
When this is turned on, a square box is displayed centered at the center of the point helper object.
Protractor : Helper
.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. .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: .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)
981
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: .length
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0
-- alias: parameter
Length of the box gizmo. .width
Float
Width of the box gizmo. .height
Float
Height of the box gizmo. .seed
Integer
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
CylGizmo : Helper Constructor: cylGizmo ...
Properties: .radius
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0
-- alias: parameter
Radius of cylinder gizmo object. .height
Float
Height of cylinder gizmo object. .seed
Integer
Base value used to generate the atmospheric effect. Each apparatus in the scene should have a different seed. If more than one apparatus uses the same seed and same atmospheric effect, they will produce nearly identical results.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
SphereGizmo : Helper Constructor: sphereGizmo ...
Properties: <SphereGizmo>.radius
Float
default: 0.0
-- animatable
Radius of sphere gizmo object. <SphereGizmo>.hemisphere
Integer
default: 0
When turned on, the bottom half of the SphereGizmo is discarded, creating a hemisphere: OFF ON <SphereGizmo>.seed
Integer
default: 0
Base value used to generate the atmospheric effect. Each apparatus in the scene should have a different seed. If more than one apparatus uses the same seed and same atmospheric effect, they will produce nearly identical results.
983
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: .showAxis
Boolean
default: true
When on, an axis tripod is displayed with the camera point object. .axisLength
Float
default: 20.0
The length of the axis tripod.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Helper - VRML 1.0/VRBL The following list shows the VRML 1.0/VRBL helper objects: Inline (p. 984) LOD (p. 985) VRML_VRBL (p. 985)
Inline : Helper Constructor: inline ...
Properties: There are no additional properties for Inline.
LOD : Helper
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)
985
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
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)
987
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
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 . WAVsound.end
A read only variable to get the Sound track range end time as a value. WAVsound.mute
Get/set whether Sound track is active as . WAVsound.isPlaying
A read only variable that returns whether the Sound track is currently playing as a value. Methods: WAVsound.scrub
Plays back the specified time interval of the Sound track.
989
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
System : Node System objects are not creatable by MAXScript. Once a system object in created in 3ds max, various properties associated with the system are accessible by MAXScript. The 3ds max system objects are: Bones (p. 991) Sunlight (p. 991) RingArray (p. 992) Note: Only the Sunlight class is available in 3D Studio VIZ.
Bones : System Note: This class is not available in 3D Studio VIZ. Bones system objects are not creatable by MAXScript. A Bones system is comprised of the Bone Helper (p. 978) objects, a master IK controller, and slave IK controllers. The slave IK controllers are used as the transform controller for all nodes in the IK system, and the master IK controller controls the individual slave IK controllers. The methods associated with the IK controller are described in the IK_ControllerMatrix3Controller : Matrix3Controller (p. 1313) topic.
Sunlight : System Sunlight system objects are not creatable by MAXScript. A Bones system is comprised of a Compass Helper (p. 979) object and a TargetDirectionalLight (p. 972) object. The TargetDirectionalLight’s transform is controlled by a set of float controllers, which are sub-controllers of a non-accessible position controller (a Sunlight_Slave_Controller position controller). These float controllers can be accessed as subAnims of the TargetDirectionalLight node. These float controllers, and their subAnim index number, are: Solar_Time - subAnim[3] Solar_Date - subAnim[4] Latitude - subAnim[5] Longitude - subAnim[6] Orbital_Scale - subAnim[7]
For example, if node $Sun01 is the light for a Sunlight system, the Solar_Time controller can be accessed as: solarTimeCont=$Sun01[3].object
991
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
-- 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: .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. .spin
Float
default: 0.0
-- animatable
The rate at which fragments rotate, in revolutions per second.
993
994
Chapter 11
|
3ds max Objects
.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. .fallOffEnable
Boolean
default: false
Turn on to use the Falloff setting. The falloff range appears as a yellow, tri-hooped sphere. .minFragmentSize
Integer
default: 1
The minimum number of faces per fragment to be randomly generated by the “explosion.” .maxFragmentSize
Integer
default: 1
The maximum number of faces per fragment to be randomly generated by the “explosion.” .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. .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. .detonation
Time
default: 5f
The frame at which the bomb goes off. Bound objects are unaffected before this time. .seed
Integer
default: 0
Change to alter randomly generated numbers in the bomb. You can achieve a different bomb effect by changing Seed while maintaining the other settings. Associated Methods: bindSpaceWarp <node>
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
ConformSpaceWarp : SpacewarpObject Constructor: conformSpaceWarp ...
Note: This class is not available in 3D Studio VIZ. Properties: .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. .Standoff_Distance
Float
default: 1.0 -- animatable
The distance maintained between the vertex and the surface of the target object. .Selected_Verts
Integer
default: 0
-- animatable
When on, only the sub-object selection of vertices on the Stack are pushed. When off, all vertices in the object are pushed regardless of the Stack selection: OFF ON .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>
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)
995
996
Chapter 11
|
3ds max Objects
SpaceDisplace : SpacewarpObject Constructor: spaceDisplace ...
Note: This class is not available in 3D Studio VIZ. Properties: <Spacedisplace>.strength
Float
default: 0.0
-- animatable
When set to 0.0, the Displace warp has no effect. Values greater than 0.0 displace object geometry or particles away from the position of the Displace space warp object. Values less than 0.0 displace geometry toward the warp. <Spacedisplace>.decay
Float
default: 0.0
-- animatable
By default, the Displace warp has the same strength throughout world space. Increasing Decay causes displacement strength to diminish as distance increases from the position of the Displace warp object. <Spacedisplace>.lumCenterEnable
Boolean
default: false
Turn on/off use of the luminance center. <Spacedisplace>.lumCenter
Float
default: 0.5
-- animatable
By default, the Displace space warp centers the luminance by using medium (50%) gray as the zero displacement value. Gray values greater than 128 displace in the outward direction (away from the Displace warp object) and gray values less than 128 displace in the inward direction (toward the Displace warp object). <Spacedisplace>.bitmap
Bitmap
default: undefined
Bitmap assigned to use for displacement. <Spacedisplace>.map
TextureMap
default: undefined
Texture map assigned to use for displacement. <Spacedisplace>.blur
Float
default: 0.0
-- animatable
Increase this value to blur or soften the effect of the bitmapped displacement. <Spacedisplace>.maptype
Integer
default: 0
The map projection type: Planar (Projects the map from a single plane.) Cylindrical (Projects the map as if it were wrapped around the cylinder.) Spherical (Projects the map from a sphere, with singularities at the top and bottom of the sphere, where the bitmap edges meet at the sphere’s poles.) Shrink Wrap (Truncates the corners of the map and joins them all at a single pole, creating one singularity.) <Spacedisplace>.length
Float
default: 1.0
-- animatable
The length of the bounding box on the space warp gizmo. <Spacedisplace>.width
Float
default: 1.0
The width of the bounding box on the space warp gizmo.
-- animatable
SpaceDisplace : SpacewarpObject
<Spacedisplace>.height
Float
default: 1.0
-- animatable
The height of the bounding box on the space warp gizmo. <Spacedisplace>.U_Flip
Boolean
default: false
When on, reverses the orientation of the map along the U-axis. <Spacedisplace>.U_Tile
Float
default: 1.0
-- animatable
The number of times the map repeats along the U-axis. <Spacedisplace>.V_Flip
Boolean
default: false
When on, reverses the orientation of the map along the V-axis. <Spacedisplace>.V_Tile
Float
default: 1.0
-- animatable
The number of times the map repeats along the U-axis. <Spacedisplace>.W_Flip
Boolean
default: false
When on, reverses the orientation of the map along the W-axis. <Spacedisplace>.W_Tile
Float
default: 1.0
-- animatable
The number of times the map repeats along the U-axis. The following properties are defined for SpaceDisplace, but are not used: <Spacedisplace>.axis <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)
997
998
Chapter 11
|
3ds max Objects
SpaceFFDBox : SpacewarpObject Constructor: spaceFFDBox ...
Note: This class is not available in 3D Studio VIZ. Properties: <SpaceFFDBox>.length
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
default: true
-- alias: Lattice
Sets the length of the lattice. <SpaceFFDBox>.width
Float
Sets the width of the lattice. <SpaceFFDBox>.height
Float
Sets the length of the lattice. <SpaceFFDBox>.dispLattice
Boolean
When turned on, lines are drawn connecting the control points to make a grid. <SpaceFFDBox>.dispSource
Boolean
default: false
-- alias: Source_Volume
When on, the control points and lattice are displayed in their unmodified state. <SpaceFFDBox>.deformType
Integer
default: 0
Specifies which vertices are affected by the FFD: Only In Volume (Only vertices that lie inside the source volume are deformed. Vertices outside the source volume are not affected.) All Vertices (All vertices are deformed regardless of whether they lie inside or outside the source volume, depending on the .falloff value.) <SpaceFFDBox>.falloff
Float
default: 0.0
-- animatable
The distance from the lattice that the FFD effect will decrease to zero. When this value is set to 0, it’s effectively turned off, and there is no falloff; that is, all vertices are affected regardless of their distance from the lattice. The units of the Falloff parameter are specified relative to the size of the lattice: A falloff of 1 means that the effect will go to 0 for points that are a lattice width/length/height away from the lattice (depending on which side they are on). <SpaceFFDBox>.tension
Float
default: 25.0
-- animatable
Sets the tension of the deformation splines. <SpaceFFDBox>.continuity
Float
default: 25.0
Sets the continuity of the deformation splines. Associated Methods: bindSpaceWarp <node> <spaceFFDBox_node>
-- animatable
SpaceFFDCyl : SpacewarpObject
Associated Binding Modifier: FFD_Binding
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier. Note: The number of control points in a SpaceFFDBox created by MAXScript is always 4x4x4. There is no method for assigning controllers to the FFD control points, nor is there a method for assigning the number or accessing the number of Length, Width, and Height points using MAXScript in 3ds max 4.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation (p. 1461) for details on accessing the control points in an FFD.
SpaceFFDCyl : SpacewarpObject Constructor: spaceFFDCyl ...
Note: This class is not available in 3D Studio VIZ. Properties: <SpaceFFDCyl>.radius
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
default: true
-- alias: Lattice
Sets the radius of the lattice. <SpaceFFDCyl>.height
Float
Sets the height of the lattice. <SpaceFFDCyl>.dispLattice
Boolean
When on, lines are drawn connecting the control points to make a grid. <SpaceFFDCyl>.dispSource
Boolean
default: false
-- alias: Source_Volume
When on, the control points and lattice are displayed in their unmodified state. <SpaceFFDCyl>.deformType
Integer
default: 0
Specifies which vertices are affected by the FFD: Only In Volume (Only vertices that lie inside the source volume are deformed. Vertices outside the source volume are not affected.) All Vertices (All vertices are deformed regardless of whether they lie inside or outside the source volume, depending on the .falloff value.)
999
1000
Chapter 11
|
3ds max Objects
<SpaceFFDCyl>.falloff
Float
default: 0.0
-- animatable
The distance from the lattice that the FFD effect will decrease to zero. When this spinner is set to 0, it’s effectively turned off, and there is no falloff; that is, all vertices are affected regardless of their distance from the lattice. The units of the Falloff parameter are specified relative to the size of the lattice: A falloff of 1 means that the effect will go to 0 for points that are a lattice width/length/height away from the lattice (depending on which side they are on). <SpaceFFDCyl>.tension
Float
default: 25.0
-- animatable
Sets the tension of the deformation splines. <SpaceFFDCyl>.continuity
Float
default: 25.0
-- animatable
Sets the continuity of the deformation splines. Associated Methods: bindSpaceWarp <node> <spaceFFDCyl_node>
Associated Binding Modifier: FFD_Binding
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier. Note: The number of control points in a SpaceFFDCyl is always 4x8x4. There is no method for assigning controllers to the FFD control points, nor is there a method for assigning the number or accessing the number of Side, Radial, and Height points using MAXScript in 3ds max 4.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) See also Class and Object Inspector Functions (p. 799) and Scripting Vertex and Control Point Animation (p. 1461) for details on accessing the control points in an FFD.
SpaceRipple : SpacewarpObject
SpaceRipple : SpacewarpObject Constructor: spaceRipple ...
Note: This class is not available in 3D Studio VIZ. Properties: <Spaceripple>.amplitude1
Float
default: 5.0
-- animatable, alias: Amplitude_1
Ripple amplitude along the ripple warp object’s local X axis. Amplitude is expressed in active units. <Spaceripple>.amplitude2
Float
default: 5.0
-- animatable, alias: Amplitude_2
Ripple amplitude along the ripple warp object’s local Y axis. Amplitude is expressed in active units. <Spaceripple>.wavelength
Float
default: 25.0 -- animatable, alias: Wave_Length
The length of each wave, in active units. <Spaceripple>.phase
Float
default: 0.0
-- animatable
Offsets the phase of the wave from its origin at the ripple object’s center. Whole values have no effect; only fractional values do. Animating this parameter makes the ripple appear to travel through space. <Spaceripple>.decay
Float
default: 0.0
-- animatable
When set to 0.0, the ripple has the same amplitude or amplitudes throughout world space. Increasing the Decay value causes amplitude to diminish as distance increases from the position of the ripple warp object. <Spaceripple>.circles
Integer
default: 10
The number of circles in the ripple icon. <Spaceripple>.segments
Integer
default: 16
The number of segments (pie slices) in the ripple icon. <Spaceripple>.divisions
Integer
default: 4
Adjusts the size of the ripple icon without altering the ripple effect as scaling would. Associated Methods: bindSpaceWarp <node> <spaceRipple_node>
Associated Binding Modifier and Properties: RippleBinding
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. The following property is associated with this binding modifier: .Flexibility
Float
default: 1.0
1001
1002
Chapter 11
|
3ds max Objects
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
SpaceWave : SpacewarpObject Constructor: spaceWave ...
Note: This class is not available in 3D Studio VIZ. Properties: <Spacewave>.amplitude1
Float
default: 5.0
-- animatable, alias: Amplitude_1
Wave amplitude along the wave warp object’s local X axis. <Spacewave>.amplitude2
Float
default: 5.0
-- animatable, alias: Amplitude_2
Wave amplitude along the wave warp object’s local Y axis. <Spacewave>.wavelength
Float
default: 25.0
-- animatable, alias: Wave_Length
The length of each wave along the wave’s local Y axis, in active units. <Spacewave>.phase
Float
default: 0.0
-- animatable
Offsets the phase of the wave from its origin at the wave object’s center. Whole values have no effect; only fractional values do. Animating this parameter makes the wave appear to travel through space. <Spacewave>.decay
Float
default: 0.0
-- animatable
When set to 0.0, the wave has the same amplitude or amplitudes throughout world space. Increasing the Decay value causes amplitude to diminish as distance increases from the position of the wave warp object. <Spacewave>.circles
Integer
default: 4
The number of side segments along the wave object’s local X dimension. <Spacewave>.segments
Integer
default: 20
The number of segments along the wave object’s local Y dimension. <Spacewave>.divisions
Integer
default: 10
Adjusts the size of the wave icon without altering the wave effect as scaling would. Associated Methods: bindSpaceWarp <node> <spaceWave_node>
Associated Binding Modifier and Properties: WaveBinding
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. The following property is associated with this binding modifier: <WaveBinding>.Flexibility
Float
default: 1.0
Gravity : SpacewarpObject
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: .strength
Float
default: 1.0
-- animatable
Increasing Strength increases the effect of gravity; that is, how objects move in relation to the Gravity icon’s direction arrow. Strength less than 0.0 creates negative gravity, which repels particles moving in the same direction and attracts particles moving in the opposite direction. When Strength is set to 0.0, the Gravity space warp has no effect. .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. .gravitytype
Integer
default: 0
Set the type of gravity effect: 0 – Planar 1 - Spherical .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.
1003
1004
Chapter 11
|
3ds max Objects
.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. .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>
Associated Binding Modifier: GravityBinding
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Motor : SpacewarpObject Constructor: motor ...
Note: This class is not available in 3D Studio VIZ. Properties: <Motor>.On_Time
Time
default: 0f
The frame at which the motor effect begins. <Motor>.Off_Time
Time
default: 30f
The frame at which the motor effect ends. <Motor>.Basic_Torque
Float
default: 1.0
The amount of force exerted by the space warp. <Motor>.units
Integer
default: 0
The unit of measure for the basic torque setting: Newton-meters Pound-feet Pound-inches
-- animatable
Motor : SpacewarpObject
<Motor>.Feedback_On
Integer
default: 0
When on, the force varies depending on the speed of the affected objects relative to the specified Target Speed. When off, the force remains constant, regardless of the speed of the affected objects: OFF ON <Motor>.Reversible
Integer
default: 0
When on, if the object’s speed exceeds the Target Speed setting, the force is reversed: OFF ON <Motor>.Target_Revs
Float
default: 100.0
-- animatable
The maximum revolutions before the feedback takes effect. <Motor>.Revs_Units
Integer
default: 1
The unit of measure for the target revolutions: RPH RPM RPS <Motor>.Control_Gain
Float
default: 50.0
-- animatable
Specifies how quickly the force adjusts to approaching the target speed. If set to 100%, the correction is immediate. If set lower, a slower and “looser” response occurs. <Motor>.Enable_Variation
Integer
default: 0
Turn on to enable the variations: OFF ON <Motor>.Variation_Period_1
Time
default: 0.625f
The time over which the noise variation makes a full cycle. <Motor>.Amplitude_1
Float
default: 100.0
-- animatable
The strength of the variation (in percent). <Motor>.Variation_Phase_1
Float
default: 0.0
-- animatable, angle
Offsets the variation pattern. <Motor>.Variation_Period_2
Time
default: 0.625f
Provides an additional variation pattern to increase the noise. <Motor>.Amplitude_2
Float
default: 100.0
-- animatable
The strength of the variation of the second wave in (percent). <Motor>.Variation_Phase_2
Float
default: 0.0
Offsets the variation pattern of the second wave.
-- animatable, angle
1005
1006
Chapter 11
|
3ds max Objects
<Motor>.Range_Enable
Integer
default: 0
When on, limits the range of the effect to a sphere, displayed as a tri-hooped sphere. The effect falls off increasingly as the particles near the boundary of the sphere. OFF ON <Motor>.Range_Value
Float
default: 1000.0 -- animatable
The radius of the range of the effect, in units. <Motor>.Icon_Size
Float
default: 0.0
The size of the Motor icon. This is for display purposes only, and does not alter the Motor effect. Associated Methods: bindSpaceWarp <node> <motor_node>
Associated Binding Modifier: MotorMod
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
PBomb : SpacewarpObject Constructor: pbomb ...
Note: This class is not available in 3D Studio VIZ. Properties: .symmetry
Integer
default: 0
The shape, or pattern of the blast effect: Spherical (The blast force radiates outward from the PBomb icon in all directions. The icon looks like a spherical anarchist’s bomb.) Cylindrical (The blast force radiates outward from and normal to the central axis, or core of the cylindrical icon. The icon looks like a stick of dynamite with a fuse.) Planar (The blast force radiates both up and down, perpendicular to the plane of the planar icon. The icon looks like a plane with arrows pointing up and down along the direction of the blast force.)
PBomb : SpacewarpObject
.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. .Start_Time
Time
default: 30f
The frame number at which the impulse forces are first applied to the particles. .Lasts_For
Time
default: 1f
The number of frames, beyond the first, over which the forces are applied. This value should typically be a small number, such as between 0 and 3. .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. .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.) .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. .Icon_Size
Float
default: 0.0
The overall size of the PBomb icon. Associated Methods: bindSpaceWarp <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)
1007
1008
Chapter 11
|
3ds max Objects
PushSpaceWarp : SpacewarpObject Constructor: pushSpaceWarp ...
Note: This class is not available in 3D Studio VIZ. Properties: .On_Time
Time
default: 0f
The frame in which the space warp begins its effect. .Off_Time
Time
default: 30f
The frame in which the space warp ends its effect. .Basic_Force
Float
default: 1.0
-- animatable
The amount of force exerted by the space warp. .units
Integer
default: 0
The unit of force used by the basic force: Newtons Pounds .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 .Reversible
Integer
default: 0
When on, if the object’s speed exceeds the Target Speed setting, the force is reversed OFF ON .Target_Speed
Float
default: 100.0
-- animatable
The maximum speed in units per frame before the Feedback takes effect. .Control_Gain
Float
default: 50.0
-- animatable
Specifies how quickly the force adjusts to approaching the target speed. If set to 100 percent, the correction is immediate. If set lower, a slower and “looser” response occurs. .Enable_Variation
Integer
default: 0
Time
default: 0.625f -- animatable
Turn on/off variations: OFF ON .Variation_Period_1
The time over which the noise variation makes a full cycle. .Amplitude_1
Float
The strength of the variation (in percent).
default: 100.0
-- animatable
PushSpaceWarp : SpacewarpObject
.Variation_Phase_1
Float
default: 0.0
-- animatable, angle
Time
default: 0.625f -- animatable
Offsets the variation pattern. .Variation_Period_2
Provides an additional variation pattern (a second wave) to increase the noise. .Amplitude_2
Float
default: 100.0
-- animatable
The strength of the variation of the second wave (in percent). .Variation_Phase_2
Float
default: 0.0
-- animatable, angle
Offsets the variation pattern of the second wave .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 .Range_Value
Float
default: 1000.0 -- animatable
The radius of the range of the effect, in units. .Icon_Size
Float
default: 0.0
The size of the Push icon. This is for display purposes only, and does not alter the Push effect. Associated Methods: bindSpaceWarp <node>
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)
1009
1010
Chapter 11
|
3ds max Objects
Wind : SpacewarpObject Constructor: wind ...
Note: This class is not available in 3D Studio VIZ. Properties: <Wind>.strength
Float
default: 1.0
-- animatable
Increasing Strength increases the wind effect. Strength less than 0.0 creates a suction. It repels particles moving in the same direction and attracts particles moving in the opposite direction. When Strength is 0.0, the Wind warp has no effect. <Wind>.decay
Float
default: 1.0
-- animatable
When Decay is set to 0.0, the Wind warp has the same strength throughout world space. Increasing the Decay value causes wind strength to diminish as distance increases from the position of the Wind warp object. <Wind>.windtype
Integer
default: 0
Sets the type of wind: Planar Spherical <Wind>.turbulence
Float
default: 1.0
-- animatable
Causes particles to change course randomly as the wind blows them. The greater the value, the greater the turbulence effect. <Wind>.frequency
Float
default: 1.0
-- animatable
When set greater than 0.0, causes turbulence to vary periodically over time. This subtle effect is probably not visible unless your bound particle system generates a large number of particles. <Wind>.windScale
Float
default: 0.0
-- animatable
Scales the turbulence effect. When Scale is small, turbulence is smoother and more regular. As Scale increases, turbulence grows more irregular and wild. <Wind>.showRange Boolean
default: false
When on, and when the decay value is greater than zero, icons appear in the viewports that represent the range at which the force of wind is half the maximum value. <Wind>.iconsize
Float
default: 10.0
-- animatable
Size of the Wind warp object icon, in active units. <Wind>.hoopson
Boolean
default: false
When turned on, icons appear in the viewports that represent the range at which the force of wind is half the maximum value. When you use the Planar option, the indicators are two planes; when you use the Spherical option, the indicator is a double-hooped sphere.
SpaceBend : SpacewarpObject
Associated Methods: bindSpaceWarp <node> <wind_node>
Associated Binding Modifier: WindBinding
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Spacewarp - Modifier-Based Note: Spacewarp objects are not available in 3D Studio VIZ. The following list shows the Modifier-Based space warp objects: SpaceBend (p. 1011) SpaceNoise (p. 1012) SpaceSkew (p. 1014) SpaceStretch (p. 1015) SpaceTaper (p. 1016) SpaceTwist (p. 1017)
SpaceBend : SpacewarpObject Constructor: spaceBend ...
Note: This class is not available in 3D Studio VIZ. Properties: <SpaceBend>.length
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
The length of the warp object. <SpaceBend>.width
Float
The width of the warp object. <SpaceBend>.height
Float
The height of the warp object.
1011
1012
Chapter 11
|
3ds max Objects
<SpaceBend>.decay
Float
default: 0.0
-- animatable
When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially. <SpaceBend>.angle
Float
default: 0.0
-- animatable
The angle to bend from the vertical plane. <SpaceBend>.direction
Float
default: 0.0
-- animatable
Te direction of the bend relative to the horizontal plane. <SpaceBend>.Lower_Limit
Float
default: 0.0
-- animatable, alias: Lowerlimit
Te lower boundary in world units from the bend center point beyond which the bend no longer affects geometry. <SpaceBend>.Upper_Limit
Float
default: 0.0
-- animatable, alias: Upperlimit
The upper boundary in world units from the bend center point beyond which the bend no longer affects geometry. Associated Methods: bindSpaceWarp <node> <spaceBend_node>
Associated Binding Modifier: SimpleOSMToWSMMod
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
SpaceNoise : SpacewarpObject Constructor: spaceNoise ...
Note: This class is not available in 3D Studio VIZ. Properties: <SpaceNoise>.length
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
The length of the warp object. <SpaceNoise>.width
Float
The width of the warp object. <SpaceNoise>.height
Float
The height of the warp object.
SpaceNoise : SpacewarpObject
<SpaceNoise>.decay
Float
default: 0.0
-- animatable
When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially. <SpaceNoise>.seed
Integer
default: 0
-- animatable
Generates a random start point from the number you set. Especially useful in creating terrain, because each setting can produce a different configuration. <SpaceNoise>.scale
Float
default: 100
-- animatable
The size of the noise effect (not strength). Larger values produce smoother noise, lower values more jagged noise. <SpaceNoise>.fractal
Integer
default: 0
-- animatable
When on, produces a fractal effect based on current settings: OFF ON <SpaceNoise>.Rough
Float
default: 0.0
-- animatable
Determines the extent of fractal variation. Lower values are less rough than higher values. <SpaceNoise>.iterations
Float
default: 6.0
-- animatable
The number of iterations (or octaves) used by the fractal function. Fewer iterations use less fractal energy and generate a smoother effect. An iteration of 1.0 is the same as turning Fractal off. <SpaceNoise>.phase
Integer
default: 0
-- animatable
Shifts the start and end points of the underlying wave. <SpaceNoise>.strength
Point3
default: [0,0,0]
-- animatable
The strength of the noise effect along each of three axes. Enter a value for at least one of these axes to produce a noise effect. Note: Since scale is a property for all nodes, a name conflict exists between the scale property for nodes and the scale property for SpaceNoise. To access the SpaceNoise scale property, you need to access this property as a property of a node’s baseObject property. For example: sn=spaceNoise() sn.baseObject.scale=150
The Animate Noise property is not accessible using MAXScript in 3ds max 4. Associated Methods: bindSpaceWarp <node> <spaceNoise_node>
Associated Binding Modifier: SimpleOSMToWSMMod
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
1013
1014
Chapter 11
|
3ds max Objects
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
SpaceSkew : SpacewarpObject Constructor: spaceSkew ...
Note: This class is not available in 3D Studio VIZ. Properties: <SpaceSkew>.length
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
The length of the warp object. <SpaceSkew>.width
Float
The width of the warp object. <SpaceSkew>.height
Float
The height of the warp object. <SpaceSkew>.decay
Float
When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially. <SpaceSkew>.amount
Float
default: 0.0
-- animatable
The angle to skew from the vertical plane. <SpaceSkew>.direction
Float
default: 0.0
-- animatable
The direction of the skew relative to the horizontal plane. <SpaceSkew>.Lower_Limit
Float
default: 0.0
-- animatable
The lower limit boundaries in world units from the skew center point, beyond which the skew no longer affects the geometry. <SpaceSkew>.Upper_Limit
Float
default: 0.0
-- animatable
The upper limit boundaries in world units from the skew center point, beyond which the skew no longer affects the geometry. Associated Methods: bindSpaceWarp <node> <spaceSkew_node>
Associated Binding Modifier: SimpleOSMToWSMMod
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
SpaceStretch : SpacewarpObject
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
SpaceStretch : SpacewarpObject Constructor: spaceStretch ...
Note: This class is not available in 3D Studio VIZ. Properties: <SpaceStretch>.length
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
The length of the warp object. <SpaceStretch>.width
Float
The width of the warp object. <SpaceStretch>.height
Float
The height of the warp object. <SpaceStretch>.decay
Float
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.
1015
1016
Chapter 11
|
3ds max Objects
Associated Methods: bindSpaceWarp <node> <spaceStretch_node>
Associated Binding Modifier: SimpleOSMToWSMMod
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
SpaceTaper : SpacewarpObject Constructor: spaceTaper ...
Note: This class is not available in 3D Studio VIZ. Properties: <SpaceTaper>.length
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
The length of the warp object. <SpaceTaper>.width
Float
The width of the warp object. <SpaceTaper>.height
Float
The height of the warp object. <SpaceTaper>.decay
Float
When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially. <SpaceTaper>.amount
Float
default: 0.0
-- animatable
The extent to which the ends are scaled. Amount is a relative value with a maximum of 10. <SpaceTaper>.curvature
Float
default: 0.0
-- animatable
Applies a curvature to the sides of the Taper gizmo, thus affecting the shape of the tapered object. Positive values produce an outward curve along the tapered sides, negative values an inward curve. At 0, the sides are unchanged.
SpaceTwist : SpacewarpObject
<SpaceTaper>.symmetry
Integer
default: 0
When on, produces a symmetrical taper around the primary axis. A taper is always symmetrical around the effect axis: OFF ON <SpaceTaper>.Lower_Limit
Float
default: 0.0
-- animatable
The lower limit boundaries in world units from the taper center point, beyond which the taper no longer affects the geometry. <SpaceTaper>.Upper_Limit
Float
default: 0.0
-- animatable
The upper limit boundaries in world units from the taper center point, beyond which the taper no longer affects the geometry. Associated Methods: bindSpaceWarp <node> <spaceTaper_node>
Associated Binding Modifier: SimpleOSMToWSMMod
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
SpaceTwist : SpacewarpObject Constructor: spaceTwist ...
Note: This class is not available in 3D Studio VIZ. Properties: <SpaceTwist>.length
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
default: 0.0
-- animatable
The length of the warp object. <SpaceTwist>.width
Float
The width of the warp object. <SpaceTwist>.height
Float
The height of the warp object.
1017
1018
Chapter 11
|
3ds max Objects
<SpaceTwist>.decay
Float
default: 0.0
-- animatable
When is set to 0, there is no decay, and the space warp affects its bound object regardless of its distance from the object. When you increase the decay, the effect on the bound object falls off exponentially. <SpaceTwist>.angle
Float
default: 0.0
-- animatable
The amount of twist around the vertical axis. <SpaceTwist>.bias
Float
default: 0.0
-- animatable
Causes the twist rotation to bunch up at either end of the object. When the parameter is negative, the object twists closer to the gizmo center. When the value is positive, the object twists more away from the gizmo center. When the parameter is 0, the twisting is uniform. <SpaceTwist>.Lower_Limit
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
The lower limit for the twist effect. <SpaceTwist>.Upper_Limit
Float
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
PDynaFlect : SpacewarpObject Constructor: PDynaFlect ...
Note: This class is not available in 3D Studio VIZ. Properties: .Time_On
Time
default: 0f
Specifies the frame at which the deflection begins. .Time_Off
Time
default: 100f
-- animatable
Specifies the frame at which the deflection ends. .Reflects
Float
default: 10000.0
-- animatable
Specifies the percentage of particles to be reflected by the PDynaFlect. .bounce
Float
default: 1.0
-- animatable
This multiplier specifies how much of the initial speed of the particle is maintained after collision with the PDynaFlect. .Bounce_Variation
Float
default: 0.0
-- animatable
Specifies the variation of Bounce applied to the range of particles. .chaos
Float
default: 0.0
-- animatable
Applies a random variation to the bounce angle. .Velocity_Inheritance
Float
default: 1.0
-- animatable
Determines how much of a moving PDynaFlect’s speed is applied to reflected or refracted particles. .Particle_Mass
Float
default: 1.0
-- animatable
Specifies the mass based on the chosen unit. .Particle_Mass_Units
Integer
default: 0
Sets the mass unit for particles: Gram Kilogram Pound .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. .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.
1019
1020
Chapter 11
|
3ds max Objects
Associated Methods: bindSpaceWarp <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
Integer
default: 0
--
animatable; alias:
The time at which the deflection begins. <SDynaFlect>.’time off’ time_off
Integer
default: 16000 --
animatable; alias:
The time at which the deflection ends. <SDynaFlect>.affects alias: reflects
Float
default: 10000.0
--
animatable; percentage;
The percentage of particles to be reflected by the PDynaFlect. <SDynaFlect>.bouncevar Float percentage; alias: bounce_variation
default: 0.0
--
animatable;
The variation of Bounce applied to the range of particles. <SDynaFlect>.inheritVelocity velocity_inheritance
Float
default: 1.0
--
animatable: alias:
Determines how much of a moving PDynaFlect’s speed is applied to reflected or refracted particles. <SDynaFlect>.mass particle_mass
Float
default: 1.0
The mass based on the chosen unit.
--
animatable; alias:
SDynaFlect : SpacewarpObject
<SDynaFlect>.’mass units’ particle_mass_units
Integer
default: 0
--
animatable; alias:
Float
default: 0.0
--
animatable
Float
default: 0.0
--
animatable
Float
default: 0.0
--
animatable
Float
default: 0.0
--
animatable
--
animatable
--
animatable
The unit to use for particle mass values: Gram Kilogram Pound <SDynaFlect>.’force in x’
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’
Location on the X-axis where force is applied. <SDynaFlect>.’apply at y’
Float
default: 0.0
Location on the Y-axis where force is applied. <SDynaFlect>.’apply at z’
Float
default: 0.0
Location on the Z-axis where force is applied. <SDynaFlect>.number
Integer
default: 0
--
animatable
Number of particles. <SDynaFlect>.friction
Float
default: 0.0
--
animatable
When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and there’s no change in the particle behavior. As the friction value increases, particles begin to rebound at incorrect angles and with greater speed. <SDynaFlect>.collider
Undefined
default: undefined
--
max object
Node which particles deflect off of. <SDynaFlect>.bounce
Float
default: 1.0
-- animatable
Multiplier that specifies how much of the initial speed of the particle is maintained after collision with the SDynaFlect. <SDynaFlect>.chaos
Float
default: 0.0
-- animatable
Applies a random variation to the bounce angle. <SDynaFlect>.radius
Float
default: 0.0
-- animatable
Radius of the SdynaFlect icon. This setting also alters the effect of the deflection, because particles bounce off the perimeter of the icon.
1021
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: .’time on’
Integer
default: 0
-- animatable; alias: time_on
Time at which the deflector turns on. .’time off’ time_off
Integer
default: 1600000 -- animatable; alias:
Time at which the deflector turns off. .affects alias: reflects
Float
default: 10000.0 -- animatable; percentage;
The percentage of particles to be reflected by the UDynaFlect. .bounce
Float
default: 1.0
-- animatable
This multiplier specifies how much of the initial speed of the particle is maintained after collision with the UDynaFlect. .bouncevar Float percentage; alias: bounce_variation
default: 0.0
--
animatable;
The variation of Bounce applied to the range of particles. .chaos
Float
default: 0.0
-- animatable
Applies a random variation to the bounce angle. .Friction
Float
default: 0.0
-- animatable
When set to 0.0 (the default) the surface of the deflector is treated as frictionless, and there’s no change in particle behavior. As Friction increases, particles begin to rebound at incorrect angles and with greater speed.
UDynaFlect : SpacewarpObject
.inheritVelocity velocity_inheritance
Float
default: 1.0
-- animatable; alias:
Determines how much of a moving UDynaFlect’s speed is applied to reflected or refracted particles. .mass particle_mass
Float
default: 1.0
-- animatable; alias:
The mass value of the particle. .’mass units’ particle_mass_units
Integer
default: 0
-- animatable; alias:
Float
default: 0.0
-- animatable
Sets the unit of mass to use: Gram Kilogram Pound .’force in x’
Force applied along the X-axis. .’force in y’
Float
default: 0.0
-- animatable
Force applied along the Y-axis. .’force in z’
Float
default: 0.0
-- animatable
Float
default: 0.0
-- animatable
Force applied along the Z-axis. .’apply at x’
Location on the X-axis where force is applied. .’apply at y’
Float
default: 0.0
-- animatable
Location on the Y-axis where force is applied. .’apply at z’
Float
default: 0.0
-- animatable
Location on the Z-axis where force is applied. .number
Integer
default: 20
-- animatable
Number of particles. .collider
Undefined default: undefined
--
max object
Node which deflects particles. .radius
Float
default: 0.0
-- animatable; alias: icon_size
The size of the UDynaFlect icon. Associated Methods: bindSpaceWarp <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.
1023
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: .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. .width
Float
default: 10.0
-- animatable
default: 10.0
-- animatable
The deflector’s width. .length
Float
The deflector’s length. .variation
Float
default: 0.0
--
animatable
Float
default: 0.0
--
animatable
default: 0.0
--
animatable
The bounce variation. .chaos
Angle variation after bounce. .friction
Float
Amount of friction applied to particle.
Path_Follow : SpacewarpObject
.inheritVelocity Float default: 0.0
--
animatable
Percentage of deflector’s motion inherited by the particle. .quality
Integer
default: 20
--
animatable
Affects how well the system deflects particles. The lower the number, the more likely it is to leak, but the faster it will go. Associated Methods: bindSpaceWarp <particlesys_node> <deflector_node>
Associated Binding Modifier: DeflectorBinding
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Path_Follow : SpacewarpObject Constructor: path_Follow ...
Note: This class is not available in 3D Studio VIZ. Properties: <Path_Follow>.Range_Limited
Integer
default: 1
When off, the range of influence of the space warp is limited to the value set in .range_value. When on, the space warp influences all bound particles in the scene, regardless of their distance from the path object. OFF ON <Path_Follow>.Range_Value
Float
default: 100.0
-- animatable
The range of influence when Unlimited Range is off. This is the distance between the path object and the particle system. The position of the Path Follow space warp’s icon is ignored.
1025
1026
Chapter 11
|
3ds max Objects
<Path_Follow>.Spline_Follow_Type
Integer
default: 1
Set the follow type: Along Offset Splines (The distance between the particle system and the path alter the effect of the particle motion. If the first vertex of the spline is at the birthplace of the particle, the particle follows the spline path. If you move the path away from the particle system, the particles are affected by the offset.) Along Parallel Splines (Particles follow a copy of the selected path, parallel to the particle system. In this mode, the position of the path relative to the particle system does not matter. The orientation of the path, however, affects the particle stream.) <Path_Follow>.Constant_Speed
Integer
default: 0
When on, all particles travel at the same speed: OFF ON <Path_Follow>.Tangent_Chaos
Float
default: 0.0
-- percentage
Causes particles to converge or diverge toward the path over time, or to simultaneously converge and diverge. You specify the effect by choosing Converge, Diverge, or Both (see following). This provides a tapering effect over the length of the path. <Path_Follow>.Tang_Chaos_Var
Float
default: 0.0
The amount by which .tangent_chaos can vary for each particle. <Path_Follow>.Tangent_Dir
Integer
default: 0
Set behavior of tangent chaos: Converge (When .tangent_chaos is greater than 0, the particles move in toward the path as they follow the path. The effect is that the stream tapers from larger to smaller over time. Diverge (Provides the opposite effect of Converge. The particles diverge from the path over time.) Both (Splits the particle stream, causing some particles to converge and others to diverge.) <Path_Follow>.Spiral_Chaos
Float
default: 0.0
The number of turns by which particles spiral about the path. In conjunction with .tangent_chaos, alters the diameter of the spiral. <Path_Follow>.Spiral_Chaos_Var
Float
default: 0.0
The amount by which each particle can vary from the Spiral value. <Path_Follow>.Spiral_Dir
Integer
default: 0
The direction of spiraling behavior: Clockwise Counterclockwise Bidirectional (The stream is splits so that particles spiral in both directions.) <Path_Follow>.Start_Time
Time
default: 0f
The frame at which Path Follow begins to influence the particles.
POmniFlect : SpacewarpObject
<Path_Follow>.Travel_Time
Time
default: 30f
The time each particle takes to traverse the path. <Path_Follow>.Travel_Var
Float
default: 0.0
-- percentage
The amount by which each particle’s travel time can vary. <Path_Follow>.Stop_Time
Time
default: 100f
The frame at which Path Follow releases the particles and no longer influences them. <Path_Follow>.Icon_Size
Float
default: 0.0
The size of the Path Follow icon. Does not alter the Path Follow effect. Note: There is not a way to select the Path shape object using MAXScript in 3ds max 4. The Seed parameter in not accessible using MAXScript in 3ds max 4. Associated Methods: bindSpaceWarp <particlesys_node> <path_Follow_node>
Associated Binding Modifier: PathFollowMod
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
POmniFlect : SpacewarpObject Constructor: POmniFlect ...
Note: This class is not available in 3D Studio VIZ. Properties: .deceleration
Float
default: 1.0
--
animatable
Sets the deceleration of particles. .’decel var’ percentage
Float
default: 0.0
--
animatable;
Affects the variation in deceleration of particles. .friction
Float
default: 0.0
--
animatable; percentage
When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and there’s no change in the particle behavior. As the friction value increases, particles begin to rebound at incorrect angles and with greater speed.
1027
1028
Chapter 11
|
3ds max Objects
.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. .collider
Undefined default: undefined
--
max object
Node which particles will deflect off of. .’time on’
Integer
default: 0
--
animatable; alias: time_on
The frame at which the deflection begins. .’time off’ time_off
Integer
default: 16000
--
animatable; alias:
The frame at which the deflection ends. .affects reflects
Float
default: 10000.0
--
animatable; alias:
The percentage of particles to be reflected by the POmniFlect. Controller Scaling: (1 : 100.0) .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. .bouncevar bounce_variation
Float
default: 0.0
--
animatable; alias:
The variation of Bounce applied to the range of particles. Controller Scaling: (1 : 100.0) .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. .Refracts
Float
default: 100.0
-- animatable
The percentage of particles not already reflected that will be refracted by the POmniFlect. .’pass velocity’ alias: pass_velocity
Float
default: 1.0
--
animatable;
Sets how much of a particle’s initial speed is maintained after passing through the POmniFlect. The default setting of 1 retains the initial speed is retained, so there’s no change. A setting of 0.5 reduces the speed by half. .’passvel var’ Float default: 0.0 percentage; alias: Pass_Velocity_Variation
--
animatable;
Variation of Pass Velocity applied to the range of particles. .refraction Float percentage; alias: distortion
default: 50.0
--
animatable;
Controls the angle of refraction. A value of 0 means there’s no refraction. A value of 100% sets the angle of the particles to be parallel with the POmniFlect surface. A value of –100% sets the angle perpendicular to the surface. The Distortion effect is reversed when particles strike the POmniFlect from the back side.
POmniFlect : SpacewarpObject
.’refraction var’ Float percentage; alias: distortion_variation
default: 0.0
--
animatable;
Range of variation of the Distortion effect. .Diffusion percentage
Float
default: 0.0
-- animatable,
Applies a diffusion effect to the refraction by randomly modifying each particle’s Distortion angle by the Diffusion angle. This effectively scatters the particles into a hollow cone. .’diffusion var’ Float percentage; alias: diffusion_variation
default: 0.0
--
animatable;
default: 1.0
--
animatable;
Range of variation of the Diffusion value. .inheritVelocity alias: velocity_inheritance
Float
Determines how much of a moving POmniFlect’s speed is applied to reflected or refracted particles. .spawn alias: spawn_percentage
Float
default: 100.0
--
animatable; percentage;
The percentage of particles that can use spawn effects. .Pass_Velocity
Float
default: 1.0
-- animatable
How much of the particle’s initial speed is maintained after passing through the POmniFlect. .Pass_Velocity_Variation percentage
Float
default: 0.0
-- animatable,
The variation of the Pass Velocity setting applied to the range of particles. .width
Float
default: 0.0
-- animatable
The width of the POmniFlect icon. This is for display purposes only and does not influence the deflector effect. .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>
1029
1030
Chapter 11
|
3ds max Objects
Associated Binding Modifier: POmniFlectMod
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
SDeflector : SpacewarpObject Constructor: sdeflector ...
Note: This class is not available in 3D Studio VIZ. Properties: <SDeflector>.friction
Float
default: 0.0
-- animatable
When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and there’s no change in the particle behavior. As the friction value increases, particles begin to rebound at incorrect angles and with greater speed. <SDeflector>.collider
UndefinedClass
default: undefined
--
max object
Node which particles deflect off of. <SDeflector>.bounce
Float
default: 1.0
-- animatable
Determines the speed with which particles bounce off the deflector. At 1.0, the particles bounce at the same speed as they approach. At 0, they don’t deflect at all. <SDeflector>.bouncevar
Float
default: 0.0
-- animatable
The amount by which each particle can vary from the Bounce setting. <SDeflector>.chaos
Float
default: 0.0
-- animatable
The amount of variation from the perfect angle of reflection (found when Chaos is set to 0.0). 100% induces a variation in reflection angle of up to 90 degrees <SDeflector>.inheritVelocity 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
Associated Methods: bindSpaceWarp <particlesys_node> <sdeflector_node>
Associated Binding Modifier: SDeflectMod
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
SOmniFlect : SpacewarpObject Constructor: SOmniFlect ...
Note: This class is not available in 3D Studio VIZ. Properties: <SOmniFlect>.’time on’
Integer
default: 0
--
animatable; alias: time_on
Time at which the deflection starts. <SOmniFlect>.’time off’ time_off
Integer
default: 16000 --
animatable; alias:
Time at which the deflection ends. <SOmniFlect>.affects alias: reflects
Float
default: 100.0 --
animatable, percentage;
The percentage of particles to be reflected by the SOmniFlect. <SOmniFlect>.bounce
Float
default: 1.0
-- animatable
This is a multiplier that specifies how much of the initial speed of the particle is maintained after collision with the SOmniFlect. Using the default setting of 1.0 causes the particle to rebound with the same speed as it collides. A real-world effect would usually be less than 1.0. For a “flubber” effect, set greater than 1.0. <SOmniFlect>.bouncevar alias: bounce_variation
Float
default: 0.0 --
animatable, percentage;
The variation of Bounce applied to the range of particles. <SOmniFlect>.chaos
Float
default: 0.0
-- animatable
Applies a random variation to the bounce angle. When set to 0.0 (no chaos), all particles bounce off the SOmniFlect surface perfectly (like banking pool balls). A non-zero setting causes the deflected particles to scatter.
1031
1032
Chapter 11
|
3ds max Objects
<SOmniFlect>.Refracts percentage
Float
default: 100.0
-- animatable,
The percentage of particles not already reflected that will be refracted by the SOmniFlect. <SOmniFlect>.’pass velocity’ alias: pass_velocity
Float
default: 1.0
--
animatable;
Defines how much of a particle’s initial speed is maintained after passing through the SOmniFlect. The default setting of 1 retains the initial speed is retained, so there’s no change. A setting of 0.5 reduces the speed by half. <SOmniFlect>.’passvel var’ Float default: 0.0 percentage; alias: pass_velocity_variation
--
animatable;
Variation of the Pass Velocity setting applied to the range of particles. <SOmniFlect>.refraction alias: distortion
Float
default: 50.0 --
animatable; percentage;
Controls the angle of refraction. A value of 0 means there’s no refraction. A value of 100% sets the angle of the particles to be parallel with the SOmniFlect surface. A value of –100% sets the angle perpendicular to the surface. The Distortion effect is reversed when particles strike the SOmniFlect from the back side. <SOmniFlect>.’refraction var’ Float 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 particle’s 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 SOmniFlect’s speed is applied to reflected or refracted particles. <SOmniFlect>.deceleration
Float
default: 1.0 -- animatable
Sets the deceleration of particles. <SOmniFlect>.’decel var’
Float
default: 0.0 --
animatable; percentage
Sets the variation in deceleration of particles. <SOmniFlect>.spawn alias: spawn_percentage
Float
default: 100.0 --
animatable; percentage;
The percentage of particles that can use spawn effects. <SOmniFlect>.friction
Float
default: 0.0
--
animatable; percentage
When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and there’s no change in the particle behavior. As the friction value increases, particles begin to rebound at incorrect angles and with greater speed.
UDeflector : SpacewarpObject
<SOmniFlect>.collider
Undefined
default: undefined --
max object
Node which particles deflect from. <SOmniFlect>.radius
Float
default: 0.0
-- animatable
The radius of the SomniFlect icon. Note: getPropnames() and showProperties() show two sets of parameters called Pass_Velocity and Pass_Velocity_Variation. The first set is for Refraction, the second for Spawn Effects Only groups. Due to this sharing of property names, you cannot access the Spawn Effects Only Pass_Velocity and Pass_Velocity_Variation using their property names. You can access the value assigned to these parameters, and their controller if assigned, as subAnims 17 and 18 of the base object. Associated Methods: bindSpaceWarp <particlesys_node> <SOmniFlect_node>
Associated Binding Modifier: SOmniFlectMod
This modifier is automatically created by the bindSpaceWarp() method, and is not otherwise creatable by MAXScript. There are no properties associated with this binding modifier.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
UDeflector : SpacewarpObject Constructor: uDeflector ...
Note: This class is not available in 3D Studio VIZ. Properties: .bounce
Float
default: 1.0
-- animatable
The speed with which particles bounce off the deflector. At 1.0, the particles bounce at the same speed as they approach. At 0, they don’t deflect at all. .bouncevar
Float
default: 0.0
-- animatable
The amount by which each particle can vary from the Bounce setting. .chaos
Float
default: 0.0
-- animatable
The amount of variation from the perfect angle of reflection (found when Chaos is set to 0.0). 100% induces a variation in reflection angle of up to 90 degrees.
1033
1034
Chapter 11
|
3ds max Objects
.Friction
Float
default: 0.0
-- animatable, percentage
Determines the amount of tangential “stick” at the surface as particles bounce off the deflector. .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. .radius
Float
default: 0.0
-- animatable; alias: icon_size
The size of the Udeflector icon. .collider
Undefined default: undefined
--
max object
Node which particles deflect from. Note: There is no way to set the Deflector object using MAXScript in 3ds max 4. Associated Methods: bindSpaceWarp <particlesys_node>
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: .’time on’
Integer
default: 0
-- animatable; alias: time_on
Time at which deflection starts. .’time off’ time_off
Integer
Time at which deflection ends.
default: 16000
-- animatable; alias:
UOmniFlect : SpacewarpObject
.affects alias: reflects
Float
default: 10000.0 --
animatable; percentage;
Percentage of particles to be reflected by the UOmniFlect. .bounce
Float
default: 1.0
-- animatable
This multiplier specifies how much of the initial speed of the particle is maintained after collision with the UOmniFlect. .bouncevar alias: bounce_variation
Float
default: 0.0
-- animatable; percentage;
Specifies the variation of Bounce applied to the range of particles. .chaos
Float
default: 0.0
-- animatable
Applies a random variation to the bounce angle. When set to 0.0 (no chaos), all particles bounce off the UOmniFlect surface perfectly (like banking pool balls). A non-zero setting causes the deflected particles to scatter. .Refracts percentage
Float
default: 100.0
-- animatable,
Specifies the percentage of particles not already reflected that will be refracted by the UOmniFlect. .’pass velocity’ pass_velocity
Float
default: 1.0
-- animatable; alias:
Specifies how much of a particle’s initial speed is maintained after passing through the UOmniFlect. .’passvel var’ alias: pass_velocity_variation
Float
default: 0.0
-- animatable; percentage;
Specifies the variation of Pass Velocity applied to the range of particles. .refraction alias: distortion
Float
default: 50.0
-- animatable; percentage;
Controls the angle of refraction. A value of 0 means there’s no refraction. A value of 100% sets the angle of the particles to be parallel with the UOmniFlect surface. A value of –100% sets the angle perpendicular to the surface. The Distortion effect is reversed when particles strike the UOmniFlect from the back side. .’refraction var’ Float percentage; alias: distortion_variation
default: 0.0
-- animatable;
Specifies a range of variation of the Distortion effect. .Diffusion percentage
Float
default: 0.0
-- animatable,
Applies a diffusion effect to the refraction by randomly modifying each particle’s Distortion angle by the Diffusion angle. This effectively scatters the particles into a hollow cone. .’diffusion var’ Float percentage; alias: diffusion_variation
default: 0.0
Specifies a range of variation of the Diffusion value.
--
animatable;
1035
1036
Chapter 11
|
3ds max Objects
.Friction
Float
default: 0.0
-- animatable
When set to 0.0 (the default), the surface of the deflector is treated as frictionless, and there’s no change in the particle behavior. As the Friction value increases, particles begin to rebound at incorrect angles and with greater speed. .inheritVelocity velocity_inheritance
Float
default: 1.0
-- animatable; alias:
Determines how much of a moving UOmniFlect’s speed is applied to reflected or refracted particles. .deceleration
Float
default: 1.0
-- animatable
The deceleration value for the particles. .’decel var’
Float
default: 0.0
-- animatable; percentage
The range of variation in decelerations values. .spawn spawn_percentage
Float
default: 100.0
-- animatable; percentage; alias:
Specifies the percentage of particles that can use spawn effects .Pass_Velocity
Float
default: 1.0
-- animatable
Specifies how much of the particle’s initial speed is maintained after passing through the UOmniFlect. .Pass_Velocity_Variation percentage
Float
default: 0.0
-- animatable,
Specifies the variation of the Pass Velocity setting applied to the range of particles. .radius
Float
default: 0.0
-- animatable; alias: icon_size
The size of the UOmniFlect icon. .collider
UndefinedClass
default: undefined
--
max object
Node which particles deflect from. Note: getPropnames() and showProperties() show two sets of parameters called Pass_Velocity and Pass_Velocity_Variation. The first set is for Refraction, the second for Spawn Effects Only groups. Due to this sharing of property names, you cannot access the Spawn Effects Only Pass_Velocity and Pass_Velocity_Variation using their property names. You can access the value assigned to these parameters, and their controller if assigned, as subAnims 17 and 18 of the base object. Associated Methods: bindSpaceWarp <particlesys_node>
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
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 [#proxy]
Loads the specified node object from the specified scene file as an XRef object. The case of objectname_string must match the object’s name in the scene file. If #proxy is specified, the node object is loaded as the proxy object, otherwise it is loaded as the non-proxy object. The XRefObject is always loaded at world center. Properties: <XRefObject>.proxyFileName
String
default: varies
String
default: varies
String
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
default: varies
String
default: varies
String
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.
1037
1038
Chapter 11
|
3ds max Objects
<XRefObject>.renderProxy
Boolean
default: false
If true, the proxy object will be rendered, otherwise the non-proxy object will be rendered. <XRefObject>.updateMaterial
Boolean
default: false
If true, sets the Update Material option on. <XRefObject>.ignoreAnimation
Boolean
default: false
If true, sets the Ignore Animation option on. Methods: updateXRef <XRefObject>
Reloads the XRef object.
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
XRefScene Values A XRefScene value represents a XRef Scene object in 3ds max. A XRefScene value is returned when the xref.addNewXRefFile() and xref.getXRefFile() functions are called. XRef Scene objects can be nested. For example, scene file A can contain an XRef Scene object specifying XRef file B, and XRef file B can contain an XRef Scene object specifying XRef file C (eg: A xrefs B, and B xrefs C). To provide access to the nested XRef scene objects, the applicable XRefScene methods provide an optional root keyword parameter. If this argument is provided then these methods act on the root node of the specified XRefScene value, otherwise they act on root node of the current scene. To get to C from A, you load A and do something like: bXref = xrefs.getXRefFile 1 -- taken from root node of current scene cXref = xrefs.getXRefFile 1 root:bXref -- taken from root of bXref cRoot = cXref.tree -- to get root of C
Constructor: xrefs.addNewXRefFile [ #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
xrefs.getXRefFile [root:<XRefScene>]
If root is not specified, returns the XRefScene value corresponding to the indexed XRef Scene object in the XRef Scenes dialog. If the root:<XRefScene> is specified, the XRefScene value corresponding to a nested XRef Scene object within the XRefScene’s XRef Scene object is returned. The index is 1-based, and corresponds to the order of the XRef Scene objects listed in the XRef Scenes dialog. You can use the xrefs.getXRefFileCount() method to determine the number of XRef Scene objects in the scene. Properties: <XRefScene>.filename
String
default: varies
The file name of the XRef Scene object. If you change this property to a new scene file name, the objects in the specified file are displayed, replacing the objects from the initial scene file. <XRefScene>.tree
Node
The root node of the XRef Scene object. This is a read-only property. You can access the children objects in an XRef Scene object using this property. For example: aXref=xrefs.getXRefFile 1 aXref.tree.children
----aXref.tree.children[1].width -<XRefScene>.parent
returns first XRef Scene object objects in the XRef Scene object, for example, may return: #children($Box01, $Box02) returns width value of $Box01
Node
default: undefined
The parent of the XRef Scene object. By default this is undefined but can be set to any node in the scene. <XRefScene>.autoUpdate
Boolean
default: false
If true, automatic XRef file updating is on. <XRefScene>.boxDisp
Boolean
default: false
If true, all nodes the in the XRef Scene object are displayed in Box display mode. <XRefScene>.hidden
Boolean
default: false
If true, the XRef Scene object is hidden. <XRefScene>.disabled
Boolean
default: false
If true, the XRef Scene object is disabled. <XRefScene>.ignoreLights
Boolean
default: false
If true, the lights in the XRef Scene object will not be displayed. <XRefScene>.ignoreCameras
Boolean
default: false
If true, the cameras in the XRef Scene object will not be displayed. <XRefScene>.ignoreShapes
Boolean
default: false
If true, the shapes in the XRef Scene object will not be displayed. <XRefScene>.ignoreHelpers
Boolean
default: false
If true, the helpers in the XRef Scene object will not be displayed. <XRefScene>.ignoreAnimation
Boolean
default: false
If true, any animation in the XRef Scene object will be ignored.
1039
1040
Chapter 11
|
3ds max Objects
Methods: delete <XRefScene>
Deletes the XRef Scene object. merge <XRefScene>
Merges the nodes in the XRef Scene object into the scene and deletes the XRef Scene object. updateXRef <XRefScene>
Tries to reload the XRef Scene object. Returns true if the operation is successful, false otherwise. flagChanged <XRefScene>
This method indicates that the specified XRef Scene object has been changed and should be updated. Use the xrefs.updateChangedXRefs() method to update the changed XRef Scene objects. Associated Methods: xrefs.getXRefFileCount [root:<XRefScene>]
If root is not specified, returns the total number of top-level XRef Scene objects in the scene. If the root:<XRefScene> is specified, the total number of XRef Scene objects in the nested XRef file within the XRefScene’s XRef file is returned. xrefs.deleteAllXRefs [root:<XRefScene>]
If root is not specified, deletes all XRef Scene objects. If the root:<XRefScene> is specified, only the specified XRefScene’s XRef Scene object, and its nested XRef Scene objects, are deleted. xrefs.updateChangedXRefs [#noRedraw] [root:<XRefScene>]
If root is not specified, updates all XRef Scene objects flagged as changed. If the root:<XRefScene> is specified, only the specified XRefScene’s XRef Scene objects flagged as changed are updated. If #noRedraw is specified, the viewports won’t be updated after the XRef Scene objects are loaded. Returns true if the XRef Scene objects were loaded okay, otherwise false. xrefs.findUnresolvedXRefs [root:<XRefScene>]
If root is not specified, returns an array of file name strings for all the unresolved XRef Scene objects. If the root:<XRefScene> is specified, only the unresolved XRef Scene objects within the specified XRefScene’s XRef Scene object are returned. xrefs.attemptUnresolvedXRefs [root:<XRefScene>]
If root is not specified, tries to load any XRef Scene objects that are currently unresolved. If the root:<XRefScene> is specified, only the unresolved XRef Scene objects within the specified XRefScene’s XRef Scene object are loaded.
Editable_Mesh : GeometryClass and TriMesh : Value
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 .
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Class and Object Inspector Functions (p. 799) Scripting Vertex and Control Point Animation (p. 1461) Note: 1.
Only the update() function updates the mesh’s internal caches and images in 3ds max viewports. This is because updates can be computationally expensive and you don’t want them performed on every function call. However, you must make sure you do call the update() function after a series of changes and before the mesh is to be worked on in 3ds max or by other functions in MAXScript.
2.
Coordinates are given in the MAXScript working coordinate system.
1041
1042
Chapter 11
|
3ds max Objects
3.
If the update() function is called on an object that is selected and currently open in the Modify panel, it will drop the current selection in order to avoid a potential crash in 3ds max, which at the moment, does not support scripted changes to an object open in the Modify panel.
4.
If you are creating or modifying a mesh, and have not yet run update() on the mesh, 3ds max will crash if you minimize and then maximize the 3ds max window. This is because an only partially created mesh is created, and the internal 3ds max mesh structure is left in an unstable state.
Constructors (Editable_Mesh): mesh [ length: ] [ width: ] \ [ lengthsegs: ] [ widthsegs: ]
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: ] [ numfaces: ]
Creates a mesh of the given geometry but with no topology (i.e., no faces or edges). You have to individually place the vertices and create the faces from the vertices. The default number of vertices and faces are 36 and 50, respectively. mesh vertices:<array_of_point3s> \ faces:<array_of_point3s> \ [ materialIDs:<array_of_integers> ] \ [ tverts:<array_of_point3s> ]
Creates a mesh from an array of vertices and faces. Each Point3 value in the vertices array specifies the position of the vertex in the current coordinate system. Each Point3 value in the faces array specifies the 3 vertex indices that form the face. The materialIDs array specifies the material ID to be assigned to each face. Each Point3 value in the tverts array specifies the UVW coordinates of the texture vertices. See Texture Mapping in the methods section for more information on texture vertices. An example of construction a mesh using this form of the constructor is: mesh vertices:#([0,0,0],[10,0,0],[0,10,0],[10,10,0]) \ faces:#([1,2,3],[2,4,3]) materialIDS:#(1,2) collapseStack <node>
-- mapped
Collapses the object space modifiers out of a stack, leaving a resultant Editable Mesh as the base object of the node. If there are no object space modifiers in the stack when this is called, no action is taken. So, if you want to force an object to be an editable mesh (for example, for the mesh operation listed below), you can apply a null modifier and then collapse the stack: addModifier $foo (normalModifier()) collapseStack $foo
collapseStack() does not collapse the effect of any world space modifiers (including bindings to space warps). The world space modifiers remain on the object’s stack. To collapse an object to a mesh use the snapshot() method.
Editable_Mesh : GeometryClass and TriMesh : Value
snapshot <node>
-- mapped
This function provides functionality similar to the SnapShot tool in 3ds max. It generates a new node that contains a copy of the world-state mesh of the source <node> at the time that the snapshot is made. Any existing modifiers are collapsed out of the new node and the mesh snapshot accounts for any space warps currently applied. convertToMesh <node>
-- mapped
Converts appropriate scene object types into Editable Meshes. It is similar to collapseStack() in that it will remove all object space modifiers present, but unlike collapseStack() it will always replace the base object with an editable mesh version, even if there are no modifiers present. It can be applied to any object that an Edit Mesh modifier can work on, such as geometry and shapes, but not helpers, space warps, lights, etc. convertTo <node> [ TriMeshGeometry | Mesh ]
-- mapped
Converts appropriate scene object types into Editable Meshes. Operates in an identical manner to convertToMesh(). Constructors (TriMesh): TriMesh()
Creates an empty TriMesh. Use the methods listed below to build the mesh. <node>.mesh
Extracts a copy of a node’s world state if it is convertible to a mesh. <editable_mesh_baseobject>.mesh
Extracts a copy of base object’s mesh. .mesh
Extracts a copy of another TriMesh’s mesh. Note: GeometryClass boolean operations (p. 852) also create editable_mesh objects. Operators: The following operators perform boolean operations on meshes. These operations destructively modify the first operand mesh to contain the boolean result, as do the same boolean <node> operations. <mesh> + <mesh> <mesh> - <mesh> <mesh> * <mesh>
-- union -- difference -- intersection
Properties: <mesh>.numverts
Integer
Get or set the number of vertices <mesh>.numfaces
Integer
Get or set the number of faces <mesh>.numtverts
Integer
Get or set the number of texture vertices
1043
1044
Chapter 11
|
3ds max Objects
<mesh>.numcpvverts
Integer
Get or set the number of color-per-vertex vertices <mesh>.mesh
TriMesh
Reading this property yields a copy of the mesh, taken from after any modifiers are applied, but before any space warps are applied. Assigning to this property sets the mesh to the TriMesh value given. You can use this property, along with copy() and the <node_or_baseobject>.mesh property to build a TriMesh from other objects’ meshes. The following properties are not applicable to TriMeshes: <mesh>.selectedVerts
VertexArray
Get the currently selected vertices of the Editable_Mesh object. See VertexSelection Values (p. 786). <mesh>.verts
VertexArray
Get all of the vertices of the Editable_Mesh object. See VertexSelection Values (p. 786). <mesh>.selectedFaces
FaceArray
Get the currently selected faces of the Editable_Mesh object. See FaceSelection Values (p. 788). <mesh>.Faces
FaceArray
Get all of the faces of the Editable_Mesh object. See FaceSelection Values (p. 788). <mesh>.selectedEdges
EdgeArray
Get the currently selected edges of the Editable_Mesh object. See EdgeSelection Values (p. 790). <mesh>.Edges
EdgeArray
Get all of the edges of the Editable_Mesh object. See EdgeSelection Values (p. 790). <mesh>.displacementMapping
Boolean
Get or set whether to perform displacement mapping for the Editable_Mesh object. There is no corresponding user interface element for this property. <mesh>.subdivisionDisplacement
Boolean
Get or set whether to perform subdivision displacement for the Editable_Mesh object. This property corresponds to the Subdivision Displacement checkbox in the Surface Properties rollout. <mesh>.splitMesh
Boolean
Get or set whether to split the mesh during subdivision displacement. This property corresponds to the Split Mesh checkbox in the Surface Properties rollout. Setting this property will enable subdivisionDisplacement if it is set to false. You can both read and assign to the above properties with the exception of the properties that return a VertexSelection, FaceSelection, or EdgeSelection. If you assign numbers to them to add room for more vertices or faces, the mesh will lose all current topology/geometry (i.e., vertices, faces, and edges), assuming you want to rebuild it from scratch. If you want to retain the current topology/ geometry, use the setNumVerts(), setNumTVerts() and setNumFaces() methods described below.
Editable_Mesh : GeometryClass and TriMesh : Value
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 it’s position before the world space modifiers have been applied. You can create a new mesh object using the snapshot() method which accounts for the effects of world space modifiers. The update() method makes any scripted changes to a base object mesh visible to 3ds max and you must call this function at some point after modifying a mesh so that 3ds max sees a valid mesh. Because this update can be a compute-intensive operation, it is made available as a separate function so you perform many changes on a mesh and then invoke the update just once to signal all the changes to 3ds max. All vertex and face indexes start at 1, following the other indexing conventions in MAXScript. All coordinates used are relative to the current working coordinate system. -- General Methods update <mesh> [ geometry: ] [ topology: ] \ [ normals: ] -- mapped
The three optional keyword arguments provide control over the kind of updating done to the mesh. If the geometry: argument is true, the geometry cache is rebuilt (normals and edge list) and the mesh’s bounding box is invalidated. If the topology: argument is true,
1045
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 { | } {<source_node> | <source_mesh>} \ targetNode:<node=unsupplied> sourceNode:<node=unsupplied> \ attachMat: condenseMat: \ deleteSourceNode:
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 }
<mesh> <node> <mesh> <node>
<param_name> [ <modifier_or_index> ] <param_name> <param_name> { | } [ <modifier_or_index> ] <param_name> { |
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
#PolyThreshSelection - Planar Threshold (number) #SoftSelSoft Selection - Use Soft Selection (boolean) #SSUseEDistSoft Selection - Edge Distance (boolean) #SSEDistSoft Selection - Edge Distance (number) [note: if value hasn’t been changed, returns a value of 0] #SSBackSoft Selection - Ignore Backfacing (boolean) [note: this is the inverse of the UI element] #FalloffSoft Selection - Falloff (number) #PinchSoft Selection - Pinch (number) #BubbleSoft Selection - Bubble (number) #WeldDistWeld - Distance (number) #WeldBoxSizeWeld - Box Size in Pixels (number) #ExtrudeTypeExtrude/Chamfer (boolean) [note: true - Group; false - Local] #ShowVNormalsShow Vertex Normals (boolean) #ShowFNormalsShow Face Normals (boolean) #NormalSizeNormal Scale (number)
Vertex methods meshop.breakVerts <Mesh mesh>
For each vertex in , 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>
Chamfers the specified vertices by the specified amount. meshop.cloneVerts <Mesh mesh>
Clones the specified vertices. meshop.cutVert <Mesh mesh> <point3 destination> <point3 projdir> node:<node=unsupplied>
If <mesh> is a node, or if <mesh> is an Editable Mesh and <node> is specified, destination and projdir are in the current coordinate system context. If <mesh> is an Editable Mesh and <node> is not specified, destination and projdir are in the mesh’s local coordinate system. Returns the index of the new vertex if created, or undefined if no vertex was created. meshop.deleteIsoVerts <Mesh mesh>
Deletes all vertices not used by a face. meshop.deleteVerts <Mesh mesh>
Deletes the specified vertices.
1047
1048
Chapter 11
|
3ds max Objects
meshop.detachVerts <Mesh mesh> delete: asMesh:
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 is true, the faces are detached and returned as a Mesh value. If 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> node:<node=unsupplied>
Returns the position of the specified vertex. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position returned is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the return value is in the mesh’s local coordinate system. meshop.getVertexAngles <Mesh mesh>
This method calculates, for each vertex, the sum of the angles of this vertex’s corner in each face it’s on. So for instance, a point lying in the middle of a grid would always have vertex angle 2*PI, whereas a corner of a box would only have 270. Returns an array of size=(#vertices in mesh). The array element for any vertices not specified in will contain the value 0. meshop.getVertsByColor <Mesh mesh> channel:
Returns the vertices whose vertex color is within the color range as a . The range values shouldbe in the range of 0 to 255. meshop.getVertsByColor <Mesh mesh> <point3 uvw> channel:
Returns the vertices whose vertex UVW is within the UVW range as a . The range values shouldbe in the range of 0 to 1. meshop.makeVertsPlanar <Mesh mesh>
Moves the specified vertices so that they are planar. meshop.minVertexDistanceFrom <Mesh mesh>
Returns the minimal distance from to the vertices specified in .
Editable_Mesh : GeometryClass and TriMesh : Value
meshop.minVertexDistancesFrom <Mesh mesh>
This function computes distances from selected vertices (as indicated by ) 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 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 edges away are set to -1. If 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 is non-zero, it represents the number of edges one should “travel” in trying to find the nearest selected vertex -- this means that it only takes twice as long for twice as many verts. (This is like the Edge Distance parameter in EMesh’s Soft Selection dialog.) meshop.moveVert <Mesh mesh> <point3 offset> node:<node=unsupplied>
Moves the specified vertices by . If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the offset is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the offset is in the mesh’s local coordinate system. meshop.moveVertsToPlane <Mesh mesh> <point3 normal> node:<node=unsupplied>
Moves the specified vertices into the specified plane. The target plane is defined as all points which, when DotProd’d with N, return offset. All vertices are moved along the normal vector N. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the normal is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the normal is in the mesh’s local coordinate system. meshop.setHiddenVerts <Mesh mesh>
Sets the specified vertices as hidden, and non-specified vertices as visible. meshop.setNumVerts <Mesh mesh>
Sets the number of vertices in the mesh. Any new vertices are created at [0,0,0] in the mesh’s local coordinate system. meshop.setVert <Mesh mesh> <point3 pos> node:<node=unsupplied>
Moves the specified vertices to the specified position. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the mesh’s local coordinate system. meshop.setVertColor <Mesh mesh>
Sets the vertex color for the specified vertices in the specified <mapChannel>. meshop.weldVertsByThreshold <Mesh mesh>
Welds the specified vertices that are within the threshold distance.
1049
1050
Chapter 11
|
3ds max Objects
meshop.weldVerts - renamed to weldVertSet meshop.weldVertSet <Mesh mesh> weldpoint:<point3=unsupplied> node:<node=unsupplied>
Welds the specified vertices. If <weldpoint> is specified, the resulting vertex is positioned at that point. The result is put at the average location of the selected vertices. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the mesh’s local coordinate system. If <weldpoint> is not specified, the resulting vertex is positioned at the average location of the specified vertices.
Vertex data methods meshop.setNumVDataChannels <Mesh mesh> keep:]
Sets the number of vertex data channels available. The number of vertex data channels can be set from 0 to 100. The first ten channels are for Discreet’s use only. If keep is false or not specified, the old channel data is discarded. If true, the old channel data is retained after the resize. The predefined channels are: channel 1: Soft Selection channel 2: Vertex weights (for NURMS MeshSmooth) channel 3: Vertex Alpha values channel 4: Cornering values for subdivision use meshop.getNumVDataChannels <Mesh mesh>
Returns the number of vertex data channels available as an . meshop.setVDataChannelSupport <Mesh mesh>
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>
Returns whether the specified vertex data channel is supported. meshop.getVDataValue <Mesh mesh>
Returns the floating point data value associated with vertex vert_index in vertex data channel vdChannel as a . meshop.setVDataValue <Mesh mesh>
Sets the floating point data value associated with vertex vert_index in vertex data channel vdChannel.
Editable_Mesh : GeometryClass and TriMesh : Value
meshop.freeVData <Mesh mesh>
Deallocates the existing vertex data channel array and turns off the vertex data channel support state.
Edge methods meshop.chamferEdges <Mesh mesh> <edgelist>
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> <point3 projdir> node:<node=unsupplied>
If <mesh> is a node, or if <mesh> is an Editable Mesh and <node> is specified, projdir is in the current coordinate system context. If <mesh> is an Editable Mesh and <node> is not specified, projdir is in the mesh’s local coordinate system. Returns the index of the new vertex if created, or undefined if no vertex was created. meshop.deleteEdges <Mesh mesh> <edgelist> delIsoVerts:
Deletes the specified edges. If <delIsoVerts> is true, any isolated vertices are deleted. meshop.divideEdge <Mesh mesh> visDiag1: visDiag2: fixNeighbors: split:
Divides the specified edge at a fractional distance of <edgef> along its length. and specify whether each of the two new edges will be visible. If 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>
Tessellates the specified edges. This algorithm is exactly the one used in the Tessellate modifier, when operating on Faces and Edge SO elements. specifies the tension for the edge tessellation. This value should be fairly small, between 0 and .5, and corresponds to the value in the Tessellate, Edit Mesh, or Editable Mesh UI’s divided by 400. meshop.extrudeEdges <Mesh mesh> <edgelist> dir: | #independent | #common}=#independent> node:<node=unsupplied>
Creates new edges corresponding to the specified edges, and then moves the new edges by . The direction the edges are moved is determined by . If 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
1051
1052
Chapter 11
|
3ds max Objects
coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the direction is in the mesh’s local coordinate system.) If dir:#independent is specified, the edges are moved based on the normals of the faces using the edge. If dir:#common is specified, the edges are moved based on the normals of the face clusters using the edge. meshop.getEdgesUsingVert <Mesh mesh>
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>
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> dir: | #independent | #common}=#independent> node:<node=unsupplied>
Moves the specified faces by and outlines them by . The direction the faces are moved is determined by . If is a point3 value, the faces will be moved in that direction. (If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the direction is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the direction is in the mesh’s local coordinate system.) If dir:#independent is specified, the faces are moved based on the individual face normals. If dir:#common is specified, the faces are moved based on the face cluster normals. meshop.cloneFaces <Mesh mesh>
Clones the specified faces. meshop.collapseFaces <Mesh mesh>
Collapses the specified faces. meshop.cutFace <Mesh mesh> <point3 start> <point3 destination> <point3 projdir> node:<node=unsupplied>
If <mesh> is a node, or if <mesh> is an Editable Mesh and <node> is specified, start, destination, and projdir are in the current coordinate system context. If <mesh> is an Editable Mesh and <node> is not specified, start, destination, and projdir are in the mesh’s local coordinate system. Returns the index of the new vertex if created, or undefined if no vertex was created.
Editable_Mesh : GeometryClass and TriMesh : Value
meshop.deleteFaces <Mesh mesh> delIsoVerts:
Deletes the specified faces. If <delIsoVerts> is true, any isolated vertices are deleted. meshop.detachFaces <Mesh mesh> delete: asMesh:
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 is true, the faces are detached and returned as a Mesh value. If is false, the faces are detached as an element in the mesh and a value of OK is returned. meshop.divideFace <Mesh mesh> baryCoord:<point3=unsupplied>
Divides the specified face. If is specified, the new vertex will be created at the corresponding position. If is not specified, the new vertex will be created at the center of the face. meshop.divideFaceByEdges <Mesh mesh> fixNeighbors: split:
Divides the specifed face. New vertices are created on the specified edges at the specified fractional distance along their length. If 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>
Divides the specified faces, with new vertices created at the center of the faces. meshop.explodeAllFaces <Mesh mesh>
“Explodes” the mesh into separate elements. specifies the angle between faces that indicates whether they should be in the same or different element. meshop.explodeFaces <Mesh mesh>
“Explodes” the specified faces into separate elements. specifies the angle between faces that indicates whether they should be in the same or different element. meshop.extrudeFaces <Mesh mesh> dir: | #independent | #common}=#independent> node:<node=unsupplied>
Creates new faces corresponding to the specified faces, and then moves the new faces by and outlines them by . The direction the faces are moved is determined by . If is a point3 value, the faces will be moved in that direction. (If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the direction is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the direction is in the mesh’s local coordinate system.) If dir:#independent is specified, the faces are moved based on the individual face normals. If dir:#common is specified, the faces are moved based on the face cluster normals.
1053
1054
Chapter 11
|
3ds max Objects
meshop.getBaryCoords <Mesh mesh> <point3 pos> node:<node=unsupplied>
The barycentric coordinates of the specified point in the plane of the specified face, relative to the face. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the mesh’s local coordinate system. meshop.getElementsUsingFace <Mesh mesh> fence:
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 . If is specified, its faces are considered as barriers to the element and are not processed. meshop.getFaceCenter <Mesh mesh> node:<node=unsupplied>
Returns the face center of the specified face. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the mesh’s local coordinate system. meshop.getFaceRNormals <Mesh mesh> node:<node=unsupplied>
Returns a three element array of the render normals for the face’s three vertices. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the position is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the position is in the mesh’s local coordinate system. meshop.getFacesUsingVert <Mesh mesh>
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>
Returns a bitarray of size=(#vertices in mesh) with bits set for all vertices used by the specified faces. meshop.makeFacesPlanar <Mesh mesh>
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
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>
Sets the specified faces as hidden, and non-specified faces as visible. meshop.setNumFaces <Mesh mesh>
Sets the number of faces in the mesh.
Mesh methods meshop.createPolygon <Mesh mesh> smGroup: matID:
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> <point3 normal> fixNeighbors: split: 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 is true, the faces on the other side of each end of the cut should be split to prevent splits at the ends. If <split> is true, the cut will split the mesh apart. If false, the cut will just refine the mesh by adding geometry. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the normal is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the normal is in the mesh’s local coordinate system. meshop.getPolysUsingVert <Mesh mesh> ignoreVisEdges: threshhold:
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.
1055
1056
Chapter 11
|
3ds max Objects
meshop.optimize <Mesh mesh> saveMatBoundries: saveSmoothBoundries: autoEdge:
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 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 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 is true, faces won’t be collapsed across a material boundary. If <saveSmoothBoundries> is true, faces won’t be collapsed across a dissimilar smoothing group boundary. meshop.slice <Mesh mesh> <point3 normal> separate: delete: node:<node=unsupplied>
Slices the mesh along the specified slicing plane. The slicing plane is defined as all points which, when DotProd’d with <normal>, return . <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>) - < 0. If <delete> is true, <separate> is ignored. If <mesh> is a node, or if <mesh> is an Editable Mesh or a Mesh value and <node> is specified, the normal is in the current coordinate system context. If <mesh> is an Editable Mesh or a Mesh value and <node> is not specified, the normal is in the mesh’s local coordinate system. copy
Yields a copy of the source TriMesh. delete
Clears out the TriMesh’s geometry and topology, effectively freeing its memory. The following method is not applicable to TriMeshes: animateVertex <mesh>
Applies controllers to the specified vertices of the Editable_Mesh, where is one of: #all
Editable_Mesh : GeometryClass and TriMesh : Value
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: ] [ numfaces: ]
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: ] [ width: ] [ lengthsegs: ] \ [ widthhsegs: ]
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>
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>
Deletes the map vertex and face arrays for the specified channel, and sets their count to 0.
1057
1058
Chapter 11
|
3ds max Objects
meshop.getMapFacesUsingMapVert <Mesh mesh> <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> <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>
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.setFaceColor <Mesh mesh>
For the specified map channel, sets the map vertex color to for the map vertices used by the map faces associated with the specified faces. meshop.setVertAlpha <Mesh mesh>
For the specified map channel, sets the map vertex color to (color ) for the specified map vertices. meshop.setVertColor <Mesh mesh>
For the specified map channel, sets the map vertex color to for the specified map vertices. meshop.setNumMaps <Mesh mesh> keep:
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 . meshop.setMapSupport <Mesh mesh>
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>
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
meshop.setNumMapVerts <Mesh mesh> keep:
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>
Returns the number of vertices for the map channel as an . meshop.setNumMapFaces <Mesh mesh> keep: keepCount:
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>
Returns the number of faces for the map channel as an . meshop.setMapVert <Mesh mesh>
Sets the coordinates of the specified map vertex. meshop.getMapVert <Mesh mesh>
Returns the coordinates of the specified map vertex as a <point3>. meshop.setMapFace <Mesh mesh>
Sets the map vertices for the specified map face. meshop.getMapFace <Mesh mesh>
Returns the vertices of the specified map face as a <point3>. meshop.makeMapPlanar <Mesh mesh>
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>
Returns a with a bit set for each isolated map vertex (unrefereced by any map face) for the specified channel. meshop.deleteMapVertSet <Mesh mesh> { | | }
Deletes the specified map vertices. Returns a with a bit set for each map face that used one of the deleted map vertices. Normally, you should delete or modify the map faces using the map vertices before deleting the map vertices, as after the vertex deletion you can’t tell which vertex on a face was a vertex that was deleted. meshop.freeMapVerts <Mesh mesh>
Deallocates the map vertex array and sets the number of map vertices to 0. meshop.freeMapFaces <Mesh mesh>
Deallocates the map face array and sets the number of map faces to 0.
1059
1060
Chapter 11
|
3ds max Objects
meshop.applyUVWMap { | } \ utile: vtile: wtile: uflip: vflip: wflip: cap: tm:<Matrix3=identity matrix> channel:
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>
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>
Sets the number of map faces to the number of mesh faces, and the number of map vertices to the number of mesh vertices. The map face vertices are set to the same vertex index as the corresponding mesh face vertices (i.e., there will be a 1-to-1 correspondence between map faces/vertices and the mesh faces/vertices). The map vertex UVW coordinates are set to the normalized (0 to 1) position of the corresponding mesh vertex in the mesh’s bounding box.
Mapping methods – Color per vertex channel (Channel 0) meshop.getNumCPVVerts <Mesh mesh>
Returns the number of Color Per Vertex mapping channel vertices. meshop.setNumCPVVerts <Mesh mesh>
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>
Sets the number of Default Texture mapping channel vertices.
Data methods – Vertex selection weight channel (Channel 1) meshop.getVSelectWeight <Mesh mesh>
Returns the Vertex Selection Weight data value for the specified vertex. meshop.setVSelectWeight <Mesh mesh>
Sets the Vertex Selection Weight data value for the specified vertex.
Editable_Mesh : GeometryClass and TriMesh : Value
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>
Returns the Vertex Weight data value for the specified vertex. meshop.setVertWeight <Mesh mesh>
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>
Returns the Vertex Alpha data value for the specified vertex. meshop.setVAlpha <Mesh mesh>
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>
Returns the Vertex Corner data value for the specified vertex. meshop.setVertCorner <Mesh mesh>
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.
1061
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> -- editable mesh only meshop.getBubble <Mesh mesh> -- editable mesh only meshop.setBubble <Mesh mesh> -- editable mesh only meshop.getDisplacementMapping <Mesh mesh> -- editable mesh only meshop.setDisplacementMapping <Mesh mesh> -- editable mesh only meshop.getExtrusionType <Mesh mesh> -- editable mesh only meshop.setExtrusionType <Mesh mesh> -- editable mesh only meshop.getFalloff <Mesh mesh> -- editable mesh only meshop.setFalloff <Mesh mesh> -- editable mesh only meshop.getIgnoreBackfacing <Mesh mesh> -- editable mesh only meshop.setIgnoreBackfacing <Mesh mesh> -- editable mesh only meshop.getIgnoreVisEdges <Mesh mesh> -- editable mesh only meshop.setIgnoreVisEdges <Mesh mesh> -- editable mesh only meshop.getNormalSize <Mesh mesh> -- editable mesh only meshop.setNormalSize <Mesh mesh> -- editable mesh only meshop.getPinch <Mesh mesh> -- editable mesh only meshop.setPinch <Mesh mesh> -- editable mesh only meshop.getPlanarThreshold <Mesh mesh> -- editable mesh only meshop.setPlanarThreshold <Mesh mesh> -- editable mesh only meshop.getSelByVertex <Mesh mesh> -- editable mesh only meshop.setSelByVertex <Mesh mesh> -- editable mesh only meshop.getShowFNormals <Mesh mesh> -- editable mesh only meshop.setShowFNormals <Mesh mesh> -- editable mesh only meshop.getShowVNormals <Mesh mesh> -- editable mesh only meshop.setShowVNormals <Mesh mesh> -- editable mesh only meshop.getSoftSel <Mesh mesh> -- editable mesh only meshop.setSoftSel <Mesh mesh> -- editable mesh only meshop.getSplitMesh <Mesh mesh> -- editable mesh only meshop.setSplitMesh <Mesh mesh> -- editable mesh only meshop.getSSEdgeDist <Mesh mesh> -- editable mesh only meshop.setSSEdgeDist <Mesh mesh> -- editable mesh only meshop.getSSUseEdgeDist <Mesh mesh> -- editable mesh only meshop.setSSUseEdgeDist <Mesh mesh> -- editable mesh only meshop.getSubdivisionAngle <Mesh mesh> -- editable mesh only meshop.setSubdivisionAngle <Mesh mesh> -- editable mesh only meshop.getSubdivisionDisplacement <Mesh mesh> -- editable mesh only meshop.setSubdivisionDisplacement <Mesh mesh> -- editable mesh only meshop.getSubdivisionDistance <Mesh mesh> -- editable mesh only meshop.setSubdivisionDistance <Mesh mesh> -- editable mesh only meshop.getSubdivisionEdge <Mesh mesh> -- editable mesh only meshop.setSubdivisionEdge <Mesh mesh> -- editable mesh only meshop.getSubdivisionMaxLevels <Mesh mesh> -- editable mesh only meshop.setSubdivisionMaxLevels <Mesh mesh> -- editable mesh only
Editable_Mesh : GeometryClass and TriMesh : Value
meshop.getSubdivisionMaxTriangles <Mesh mesh> -- editable mesh only meshop.setSubdivisionMaxTriangles <Mesh mesh> -- 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> -- editable mesh only meshop.getSubdivisionSteps <Mesh mesh> -- editable mesh only meshop.setSubdivisionSteps <Mesh mesh> -- 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> -- editable mesh only meshop.getWeldPixels <Mesh mesh> -- editable mesh only meshop.setWeldPixels <Mesh mesh> -- editable mesh only meshop.getWeldThreshold <Mesh mesh> -- editable mesh only meshop.setWeldThreshold <Mesh mesh> -- editable mesh only
-- Vertex Methods getNumVerts <mesh>
Returns number of vertices as an integer, equivalent to using <mesh>.numverts setNumVerts <mesh> [ ]
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>
Returns the position (in the current working coordinate system) of the indexed vertex as a point3 setVert <mesh> ( <point3> | )
Sets the position coordinates of the indexed vertex as a point3 value, or 3 floats - X,Y,Z deleteVert <mesh>
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>
Returns the normal at the indexed vertex’s position as a point3. The normal is based on the faces that use the vertex and the smoothing groups assigned to those faces. setNormal <mesh> <point3>
Sets the indexed vertex’s normal vector
1063
1064
Chapter 11
|
3ds max Objects
getVertSelection <node> [ <modifier_or_index> ] [ name: ] getVertSelection <mesh>
Returns the current vertex selection set, or the specified named selection set if the optional name: parameter is specified, as a BitArray. The optional <modifier_or_index> identifies the Edit Mesh or Mesh Select modifier on the given scene object from which the selection BitArray is obtained. For example: getVertSelection $foo $foo.modifiers[3]
If the optional <modifier_or_index> argument is not supplied, the <node> must be an Editable Mesh object and the selection is taken from the base object. If <modifier_or_index> is supplied, it must be either a modifier on the node or a number. If it is a modifier, it must be either an Edit Mesh or a Mesh Select modifier. If it is a number, it is used as an index into the Edit Mesh/Select Modifiers on the <node> starting from the top of the stack. Note that this index does not count any other types of modifier present. So, an index of 1 will always get the selection currently active at the top of the stack. The function returns a BitArray that are the 1-based indexes of the vertices currently selected, or the vertices specified by the named selection set, in the object by the given modifier. For example: getVertSelection $foo $foo.modifiers[3]
yields #{2..5,9,25..27}
This is a snapshot of the selection -- the BitArray doesn’t change automatically as you make different selections. Further, it reflects the current vertex selection whether or not the modifier is in vertex sub-object selection mode (this selection is remembered and 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 you’ve got many edit mesh modifiers with non-unique names. You can also use a constructed string as an index into the modifiers array, for example: $foo.modifiers[”edit mesh” + i as string]
assuming the variable ‘i’ had some indexing value and the names were set up thusly. ‘+’ on strings concatenates. setVertSelection <node> [ ( [ setVertSelection <mesh> ( [
<modifier_or_index> ] <sel_bitarray> | <sel_array> ) name: ] [ keep: <sel_bitarray> | <sel_array> ) keep: ]
\ \ ] \
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
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>
Returns the face vertex indexes for the indexed face as a point3. Each component of the point3 value contains a vertex index. setFace <mesh>
Sets the face vertex indexes for the indexed face from a point3. setFace <mesh> \
Sets the face vertex indexes for the indexed face from 3 vertex indexes.
1065
1066
Chapter 11
|
3ds max Objects
deleteFace <mesh>
Deletes indexed face from the mesh. Renumbers faces accordingly. collapseFace <mesh>
Deletes indexed face from the mesh, welding its 3 vertices together at the center of the original face. Renumbers faces accordingly. getFaceNormal <mesh>
Returns the normal of the indexed face as a point3. setFaceNormal <mesh> <point3>
Sets the indexed face’s normal vector. As soon as you run update() on the mesh, this value is overwritten. getFaceMatID <mesh>
Returns the indexed face’s material ID as an integer. setFaceMatID <mesh>
Sets the indexed face’s material ID. getFaceSmoothGroup <mesh>
Returns the indexed face’s smoothing groups as a 32-bit integer. There are 32 possible smoothing groups. Each bit in the returned value corresponds to a smoothing group. If a bit is turned on, the face is part of that smoothing group. You can retrieve the list of smoothing groups for a face as a BitArray using the following function: fn getfacesmoothgroupB obj face = ( local sgroup_val=getfacesmoothgroup obj face local sg_bitarray=#{} if sgroup_val < 0 do ( sg_bitarray[32]=true sgroup_val -= 2^31 ) for i = 1 to 31 do ( sg_bitarray[i]= (mod sgroup_val 2 > .5) sgroup_val /= 2 ) sg_bitarray ) setFaceSmoothGroup <mesh> <smoothing_group_integer>
Sets the indexed face’s smoothing groups. If you have a face’s desired smoothing groups as a BitArray, you could set the face’s smoothing group data using the following function: fn setfacesmoothgroupB obj face sg_bitarray = ( local sgroup_val=0 for i in sg_bitarray do sgroup_val += 2^(i-1) setfacesmoothgroup obj face sgroup_val update obj )
Editable_Mesh : GeometryClass and TriMesh : Value
getFaceSelection <node> [ <modifier_or_index> ] [ 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: ] [ keep: <sel_bitarray> | <sel_array> ) keep: ]
\ \ ] \
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> ( | | | #selection ) \ <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 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>
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>
Returns a bitarray of size=(#edges in mesh) with bits set for all edges that are used by the specified faces.
1067
1068
Chapter 11
|
3ds max Objects
meshop.getPolysUsingFace <Mesh mesh> ignoreVisEdges: threshhold:
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>
Smooths the specified faces based on the threshold angle. meshop.unifyNormals <Mesh mesh>
Unifies the normals of the specified faces. meshop.flipNormals <Mesh mesh>
Flips the normal of the specified faces. meshop.getFaceArea <Mesh mesh>
Returns the area of the specified faces as a . -- Edge Methods getEdgeVis <mesh> <edge_index_integer>
Returns the edge visibility for given edge (1,2,3) on indexed face as a boolean. setEdgeVis <mesh> <edge_index_integer>
Sets the edge visibility for given edge (1,2,3) on indexed face. getEdgeSelection <node> [ <modifier_or_index> ] [ 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: ] [ keep: <sel_bitarray> | <sel_array> ) keep: ]
\ \ ] \
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
meshop.getPolysUsingEdge <Mesh mesh> <edgelist> ignoreVisEdges: threshhold:
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 $
1069
1070
Chapter 11
|
3ds max Objects
meshop.autoEdge <Mesh mesh> <edgelist> type:
Sets/clears the edge visibility for the specified edges based on the threshold angle. Note: for an edge to be autoEdged, both it and the “reverse” edge on the face sharing the edge vertices must be specified in the edge specification. Note: 3ds max defines an edge as the edge of a face. In any mesh object, the number of edges is 3 times the number of faces. A face has 3 vertices, and the face edges connect these vertices. Edges 1, 2, and 3 are the edges between vertices 1 and 2, 2 and 3, and 3 and 1, respectively. The first edge in a mesh is edge 1 on face 1, and the last edge is edge 3 on the last face. The following script selects all of the visible edges in the specified mesh: EdgeSelSet=#() for face = 1 to obj.numfaces do for edge = 1 to 3 do if (getedgevis obj face edge) then append EdgeSelSet (((face-1)*3)+edge) setedgeselection obj EdgeSelSet update obj
The following function returns the indices of the 2 vertices that define an edge as a Point2 value. The two arguments to the function are a editable mesh node or TriMesh value and the edge index. A value of undefined is returned if the first argument isn’t an editable mesh node or TriMesh value, or if the edge index is out of range. fn edgeVerts theObj theEdge = ( if not (classof theObj == Editable_mesh or classof theObj == triMesh) do return undefined if theEdge < 1 or theEdge > (theObj.numfaces*3) do return undefined local theFace = ((theEdge-1)/3)+1 local theVerts = getFace theObj theFace case ((mod (theEdge-1) 3) as integer) of ( 0: point2 theVerts.x theVerts.y 1: point2 theVerts.y theVerts.z 2: point2 theVerts.z theVerts.x ) )
-- Texture Vertex Methods getNumTVerts <mesh>
Returns number of texture vertices as an integer, equivalent to using <mesh>.numtverts setNumTVerts <mesh> [ ]
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>
Returns the UVW coordinates of the indexed texture vertex
Editable_Mesh : GeometryClass and TriMesh : Value
setTVert <mesh> ( <point3> | <x> )
Sets the UVW coordinates of the indexed texture vertex as a point3 value, or 3 floats U,V,W getTVFace <mesh> setTVFace <mesh> setTVFace <mesh> \
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> [ ]
The buildTVFaces() function only needs to be called on meshes you are adding texture vertices to yourself to create the internal texture face array. Meshes that 3ds max applies mapping coordinates to maintain the TVFace array automatically. This is not done automatically when you add texture vertices to meshes yourself so you need to call buildTVFaces() explicitly whenever you change the texture vertex count, and before you construct the texture faces. If the optional boolean argument is true, the existing texture mapping remains intact. If it is false or not supplied, the existing texture mapping is lost (all texture faces are rebuilt, with all three vertices of the texture face using texture vertex 1). numMapsUsed <mesh>
Returns the an upper limit on the number of texture map channels used by the given node. This is at least 1+(highest channel in use). This method is used so a script that does something to all map channels doesn’t always have to do it to every channel up to 99 (the highest possible texture map channel), but rather only to this value. This method is not applicable to TriMeshes. Note: The mesh class contains a list of texture vertices which are completely independent of the regular vertices in the mesh. There is no correlation between the number of vertices in a mesh and the number of texture vertices. In addition to the texture vertices there are also texture faces. There needs to be one texture face for every regular face in the mesh. Each texture face has three indices into the texture vertex array. The coordinates of a texture vertex are UVW coordinates, and are accessed as Point3 values. The 3 components are U, V, and W, and each component value is in the range of 0 to 1. An example script for creating planar texture mapping on an object is shown in the Working with Editable Meshes (p. 1077) topic. The texture vertex methods do not support multiple mapping channels in 3ds max 4.
1071
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> [ ]
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> [ ]
Builds the c-p-v face array after you have set the c-p-v vertex count. If the optional boolean argument is true, the existing topology remains intact. If it is false or not supplied, the topology is lost. defaultVCFaces <mesh>
Sets the number of c-p-v vertices and c-p-v faces to match exactly the current mesh’s geometry and topology and calls buildVCFaces() getVertColor <mesh>
Returns the color of the indexed c-p-v vertex as a color getVCFace <mesh>
Returns the topology for the indexed c-p-v face as a point3 containing 3 c-p-v vertex indexes setVCFace <mesh>
Sets the indexed c-p-v face topology from a point3 containing 3 c-p-v vertex indexes setVCFace <mesh> \
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
-- 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>
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>
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>
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
1073
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
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.
1075
1076
Chapter 11
|
3ds max Objects
meshOps.unhideAll <editable_mesh_node_or_modifier>
Unhides the hidden sub-objects at the current Sub-Object level - valid in Vertex, Face, Polygon, and Element Sub-Object levels. meshOps.unifyNormal <editable_mesh_node_or_modifier>
Unifies the normals of the selected faces - valid in Face, Polygon, and Element Sub-Object levels. meshOps.viewAlign <editable_mesh_node_or_modifier>
Aligns all selected sub-objects to the 0,0,0 plane of the active viewport - valid in Vertex, Edge, Face, Polygon, and Element Sub-Object levels. meshOps.visibleEdge <editable_mesh_node_or_modifier>
Sets selected edges visible. Valid in Edge Sub-Object level. meshOps.weld <editable_mesh_node_or_modifier>
Welds the selected vertices - valid in Vertex Sub-Object level. The meshOps methods depend on the Modify panel being open and the desired object, either an Editable Mesh base object or Edit Mesh modifier, being currently open in the panel. The meshOps methods do not perform any operation if these conditions aren’t met. You will need to use MAXScript functions like max modify mode or setCommandPanelTaskMode mode:#modify to open the Modify panel, select to select the object, subObjectLevel = to set the SubObject level, and modPanel.setCurrentObject 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
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 it’s position and normalize the position to a range of [0,0,0] to [1,1,1]. This is the planar UVW space. for v = 1 to obj.numverts do ( normalize_pos=((getvert obj v)-obj.min)/(obj.max-obj.min) flip around position component values based on which direction the planar mapping is perpendicular to case direction of (#x:( tmp=normalize_pos.x normalize_pos.x=normalize_pos.y normalize_pos.y=normalize_pos.z normalize_pos.z=tmp ) #y:( tmp=normalize_pos.y normalize_pos.y=normalize_pos.z normalize_pos.z=tmp )
1077
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
SplineShape : Shape SplineShapes are the general editable versions of all the shape objects, in the same way that Editable Meshes relate to geometry objects. They are the objects that a shape is converted to when you apply an Edit Spline modifier and the result of collapsing a modifier stack on a shape base object. MAXScript lets you construct SplineShapes from scratch, adding individual curves and controls points or you can modify an existing shape by converting it to a SplineShape and using the methods listed below.
See also Shape Common Properties, Operators, and Methods (p. 945) Spline Shape Common Properties, Operators, and Methods (p. 947) Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Class and Object Inspector Functions (p. 799) Scripting Vertex and Control Point Animation (p. 1461) Note: 1.
You must convert existing shapes to SplineShapes in order to operate on them with the these methods. Use the convertToSplineShape() function to do this.
2.
Only the updateShape() function updates the shape’s internal caches and images in 3ds max viewports. This is because updates can be computationally expensive and you don’t want them performed on every function call. However, you must make sure you do call the updateShape() function after a series of changes and before the shape is to be worked on in 3ds max or by other functions in MAXScript.
3.
The in and out vectors for Bezier control points are given as vector handle coordinates, not as true vectors as the names suggests.
4.
Coordinates are given in the MAXScript working coordinate system - this is important to note if you are familiar with the corresponding SDK spline functions which always work in objectlocal coordinates.
5.
If the updateShape() function is called on an object that is selected and currently open in the Modify panel, it will drop the current selection in order to avoid a potential crash in 3ds max, which at the moment, does not support scripted changes to an object open in the Modify panel.
6.
If you are creating or modifying a spline object, and have not yet run updateShape() on the spline, 3ds max will crash if you minimize and then maximize the 3ds max window. This is because an only partially created spline is created, and the internal 3ds max spline structure is left in an unstable state.
1079
1080
Chapter 11
|
3ds max Objects
Properties: <SplineShape>.angle
Float
default: 0.0
-- animatable
The rotational position of the cross-section in the renderer. <SplineShape>.thickness
Float
default: 1.0
-- animatable
Diameter of the rendered spline. <SplineShape>.sides
Float
default: 12.0
-- animatable
Sets the number of sides for the spline mesh in the renderer. A value of 4 will give you a square cross section, for example. <SplineShape>.viewport_thickness
Float
default: 1.0
Diameter of the viewport spline. <SplineShape>.viewport_sides
Integer
default: 12
Sets the number of sides for the spline mesh in the viewports. A value of 4 will give you a square cross section, for example. <SplineShape>.viewport_angle
Float
default: 0.0
The rotational position of the cross-section in the viewports. <SplineShape>.DisplayRenderMesh
Booleandefault: false
When on, displays the mesh generated by the spline in the viewports. <SplineShape>.UseViewportSettings
Boolean
default: false
When on, displays the mesh generated by the Viewport settings. <SplineShape>.DisplayRenderSettings
Boolean
default: true
When on, displays the mesh generated by the render settings. <SplineShape>.numSplines
Integer, read-only
The number of individual spline curves in the shape. Up to 3*N vertex and tangent coordinates are available as properties, where N is the number of vertices in the SplineShape. A vertex and its tangents are available as properties once a controller has been assigned to the vertex. Controllers can be assigned to vertices using the animateVertex() method described in the Scripting Vertex and Control Point Animation (p. 1461) topic. For example, if a circle object is collapsed to a SplineShape, and some of its vertices are animated, the properties for the vertices and tangents would be similar to: $Circle01.Spline_1___InVec_1 $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
Methods: -- Shape Methods updateShape <shape>
Updates the shape’s internal caches and viewport display to account for all the changes made by other functions in this kit. This update must be done before 3ds max or any other code tries to work with a modified shape object. The updateShape() function makes any scripted changes to a base object spline shape propagate into the bottom of any modifier stack that is present. Note that there is no check to warn you that modifications such as topology changes might invalidate modifiers already in the stack. This is equivalent to opening and modifying the base object in a Modify panel, ignoring its warnings about invalidating the object. resetShape <shape>
Clears all the spline curves out of a shape numSplines <shape>
Returns the number of spline curves in the shape as an integer. Equivalent to <shape>.numSplines. setFirstSpline <shape> <spline_index_integer>
Rolls the order of the splines in a shape around so that the numbered spline is the first spline in the shape. This is useful when working with multi-spline shapes in the Lofter and some other modifiers such as Surface Tools which are sensitive to spline order. hideselectedsplines <shape>
Hides the selected splines in the shape. hideselectedsegments <shape>
Hides the selected segments in the shape. hideselectedverts <shape>
Hides the segments attached to the selected knots in the shape. unhidesegments <shape>
Unhides all segments in the shape. addAndWeld <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> <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 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.
1081
1082
Chapter 11
|
3ds max Objects
unBindKnot <shape> <spline_index_integer>
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>
Applies controllers to the specified vertices and tangents of the splineshape, where is one of: #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: ]
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
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>
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:] [byVertex:] [numArcSteps:]
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>
Divides the segment into the specified number of divisions. Double precision calculations, very accurate. interpCurve3D <splineShape> <spline_index> <param_float> [pathParam:]
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:]
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
1083
1084
Chapter 11
|
3ds max Objects
refineSegment <shape> <spline_index_integer> \ <seg_index_integer> <seg_interp_param_float>
Adds a new knot to the indexed segment of the indexed curve at a place along the indexed segment corresponding to the given segment interpolation parameter. This value is a float in the range 0.0 to 1.0, specifying a proportion along the segment. The new knot coordinates and in-vector and out-vector are automatically computed to maintain the segment’s existing curvature. This is the primitive used by the refine function in the Edit Spline modifier. You can use the MAXScript spline path interpolation functions to derive segment parameters given that a curve’s path interpolation parameter is divided evenly among the segments in a curve. (So given a path interpolation parameter u and a target segment n in a spline of m segments, the segment parameter is u - (n-1)/m.) The refineSegment() function returns the index of the newly inserted knot. getSegSelection <shape> <spline_index_integer>
Returns the indices of the selected segments in the specified shape spline as an array of integers. setSegSelection <shape> <spline_index_integer> \ <segment_index_array> [ keep: ]
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>
Deletes the indexed knot in the indexed spline. The remaining knots are renumbered to account for the deletion. getKnotType <shape> <spline_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
setKnotType <shape> <spline_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>
Retrieves the coordinates of the indexed knot as a point3 in the current working coordinate system. setKnotPoint <shape> <spline_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>
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> <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>
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> <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> \ [keep: ]
Selects the knots specified by in the specified shape spline. 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.
1085
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
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.
1087
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
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>
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.
1089
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
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 -> integer patch.setNumVerts [keep:] patch.getNumVecs -> integer patch.setNumVecs [keep:] patch.getNumPatches -> integer patch.setNumPatches [keep:] patch.getNumEdges -> integer patch.setNumEdges [keep:]
The following functions get and set individual vertex and vector handle locations. The vertex and vector coordinates are interpreted in MAXScript’s current working coordinate context. Consistent with the rest of MAXScript, all vertex/patch/vector/edge indexes start numbering at 1. patch.getVert -> Point3 patch.setVert <point3> patch.getVec -> Point3 patch.setVec <point3>
1091
1092
Chapter 11
|
3ds max Objects
The following two functions are the main mechanism for creating individual patches in the patch mesh. patch.makeQuadPatch <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 <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
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
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 -> integer_array patch.getVertPatches -> integer_array patch.getVertEdges -> integer_array patch.getVecVert -> integer patch.getVecPatches -> integer_array patch.getEdgeVert1 -> integer patch.getEdgeVert2 -> integer patch.getEdgeVec12 -> integer patch.getEdgeVec21 -> integer
The following functions access and manipulate the texture mapping information in the patch object. patch.setNumMaps [keep:] -> patch.getNumMaps -> integer patch.setMapSupport <map_chan> [init:] -> patch.getMapSupport <map_chan> -> boolean patch.maxMapChannels -> patch.setNumMapVerts <map_chan> [keep:] patch.getNumMapVerts <map_index> patch.setNumMapPatches <map_chan> [keep:] patch.getMapVert <map_chan> patch.setMapVert <map_chan> <point3> patch.getMapPatch <map_chan> patch.setMapPatch <map_chan>
1093
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 -> integer patch.setMtlID <mtl_id> patch.getPatchMtlID -> integer patch.setPatchMtlID <patch_index> <mtl_id>
The following functions access and control viewport and renderer tesselation and visibility. patch.setMeshSteps <steps> patch.getMeshSteps patch.setMeshStepsRender <steps> patch.getMeshStepsRender patch.setShowInterior patch.getShowInterior patch.setAdaptive patch.getAdaptive
The following functions access topology info for the specified sub-object. patch.getEdges [] -> integer_array patch.getPatches [] -> integer_array patch.getVectors -> 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 <matrix3>
The following functions perform various high-level operations on a patch object: patch.weldVerts <weldIdentical_bool> <startVert> patch.weld2Verts patch.weldEdges patch.deletePatchParts <del_vert_bitarray> <del_patches_bitarray> patch.clonePatchParts <patch_bit_array> patch.subdivideEdges <propogate> patch.subdividePatches <propogate> patch.addTriPatch patch.addQuadPatch
The following functions get and manipulate surface normal information. Again, normal vectors are given in MAXScript’s current working coordinate context. patch.patchNormal <patch> patch.edgeNormal <edge> patch.updatePatchNormals patch.flipPatchNormal <patch> patch.unifyNormals patch.autoSmooth <useSel_bool> <preventIndirectSmoothing_bool>
Patch : GeometryClass
The following functions access and change the vertex and interior vertex types: patch.changeVertType #corner|#coplanar patch.getVertType -> #corner or #coplanar patch.changePatchInteriorType <patch> #automatic|#manual patch.getPatchInteriorType <patch> -> #automatic or #manual
The following function returns the current mesh tesselation for the patch object: patch.getMesh
-> 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 <patch> <w> -> point3 patch.interpQuadPatch <patch> -> point3
See also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Class and Object Inspector Functions (p. 799) Scripting Vertex and Control Point Animation (p. 1461)
Modifier : MAXWrapper and SpacewarpModifier : MAXWrapper The Modifier and SpacewarpModifier families of classes can be created and added to an object’s modifier stack using the addModifier() or modPanel.addModToSelection() methods. Unless otherwise noted, the term modifier will be used to mean members of either class. By making a single modifier and adding it to several objects, you are sharing the modifier between the objects, as you would by applying a modifier to a selection of objects in the 3ds max user interface. The constructors in the following classes can take any of the listed properties as optional keyword arguments with the defaults as shown. Existing modifiers can be accessed in two ways: •
As a property access on a <node>. When you access a property on a <node> scene object, such as its name or position, or length, MAXScript will also consider modifiers on the object to be properties, for example: $box1.heightsegs $box1.twist $box1.twist.angle
-- get creation parameter -- get the twist modifier -- the twist’s angle
1095
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
get and set modifier name <modifier>.enabled <modifier>.enabledInViews
: boolean : boolean
lets you control the modifier’s enabled/disabled state. These are read/write properties that let you determine and set the enabled state of the given modifier, for example: $foo.modifiers[2].enabled = false
-- turn off 2nd modifier
The enabledInViews property controls viewport display, enabled controls both viewport and rendered display.
Patch : GeometryClass
Associated Methods: The modifier stack on a scene node can be manipulated using the following <node> methods: validModifier ( <node> | ) <modifier>
Tests whether a particular modifier may be added the given <node> or . Returns true if so, false if not. The validModifier() method operates exactly as does the Modify panel in determining modifier applicability. Any modifier that takes a deformable object will return true for all scene objects except Helpers. This corresponds to the Modify panel’s behavior of allowing modifiers such as Bend, Taper, etc. to be applied to lights and cameras, space warp objects, etc., as well as geometry types like box, sphere, etc., but not helpers such as dummys or bones. addModifier <node> <modifier> [before:index]
-- mapped
adds the modifier to all instances of the node to which the function is applied. The optional before: keyword argument can be used to insert the modifier into the node’s modifier stack just before the indexed modifier, counting from the top of the stack. The added modifier will apply to any appropriate active sub-object selection in the node only if the node is currently selected and open in the Modify panel at the desired sub-object level. You can use the 3ds max System global variable, subObjectLevel to test and set the level for the object currently open in the Modify panel. For example: max modify mode 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 instance’s gizmo corresponds to position and size of the node the modifier instance is applied to. To apply a modifier to a collection in the same manner that 3ds max applies modifiers, use the modPanel.addModToSelection() described in the Modify Panel (p. 1572) topic. A limitation of the addModifier() function is that it cannot generally apply modifiers to sub-object selections, and so it disables any current sub-object levels. To apply a modifier to a sub-object selection in the same manner that 3ds max applies modifiers, use the modPanel.addModToSelection(). This function correctly observes the currently selected sub-object level in the Modify panel.
1097
1098
Chapter 11
|
3ds max Objects
deleteModifier <node> <modifier_or_index>
lets you delete modifiers from the modifier stack. Takes either a modifier value present on the <node> stack, or an index specifying the index of the modifier to delete, counting from the top of the stack. collapseStack <node>
-- mapped
collapses the modifiers out of a stack, leaving the appropriate resultant editable base class, such as Editable Mesh, Editable Spline, NURBS Surface, etc., as the base object of the node. If there are no modifiers in the stack when this is called, no action is taken. If you want to force a stack collapse or conversion to editable base class form, use one of the node conversion functions, such as convertToMesh(),convertToSplineShape(), etc. See the methods section in Node Common Properties, Operators, and Methods (p. 820) for more details. getModContextTM <node> <modifier>
Returns a Matrix3 value giving the modifier’s context transform for the local coordinates used in modifier sub-object gizmos. Accessing the transform properties of a modifier subobject such as a gizmo or a center in MAXScript yields values that are relative to that modifier’s context transform, equivalent to the values shown in track view for those properties. If the modifier is not operating on a sub-object selection, such as a face or vertex selection, or if the modifier was interactively applied to an object selection, this context TM is the local coordinate space of the object itself. However, if the modifier is operating on either an object selection set or a sub-object selection, the context transform gives the position and orientation of that selection, and so you can use getModContextTM() to get the world-space transform properties of any of its sub-objects. getModContextBBoxMin <node> <modifier> getModContextBBoxMax <node> <modifier>
These functions complement the getModContextTM() function and can be used to derive the world-space coordinates of the bounding box of the modifier context. This can be used, for example, to determine the bounds of a modifier operating on a sub-selection or the bounds of an FFD lattice. This is particularly useful for scripting FFD control point placement, since these control points live in a 0-to-1 lattice space--the mod context bounding box gives the world space bounds of this lattice space allowing you to compute scaled lattice space coordinates from world coordinates. The functions return Point3 values for the minimum and maximum extents of the bounding box.
See also MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Modifier Sub-Object Transform Properties (p. 1099)
Modifier Sub-Object Transform Properties
Modifier Sub-Object Transform Properties In MAXScript, the values of modifier sub-object transform properties, such as centers and gizmo position, rotation and scale, are not given in the current working coordinate system, but rather are typically in the coordinate system of the object to which it is applied. This is in contrast to scene node transform properties. The values given are exactly as would be seen in the sub-object’s corresponding track view or as might be referenced in an Expression controller track variable for that sub-object property. To convert from local to world coordinates, you multiply the local coordinates by the node’s objecttransform matrix. To convert from world to local coordinates, you multiple the world coordinates by the inverse of the node’s objecttransform matrix. For example: obj=box pos:[10,20,30] addModifier obj (affect_region()) objTM=obj.objecttransform modTM=getModContextTM obj obj.affect_region -- calculate world coordinates of end point obj.affect_region.end_point * (inverse modTM) * objTM -- set end point at world coordinates [20,20,0] obj.affect_region.end_point = [20,20,0] * modTM * (inverse objTM)
FFD Control Points FFD control point sub-object properties are also accessible but have several special considerations. The control points properties are named as they appear in the track view, subject to the MAXScript convention of using ‘_’ underscores for spaces, so for example: $foo.ffd_2x2x2.control_point_1 $baz.ffd_3x3x3.control_point_32 = [1,2,3]
There are two special considerations when accessing FFD control points. First, you can only access control points that have ALREADY been animated by hand, or by using the animateVertex() or the animateAll() MAXScript functions (see the Scripting Vertex and Control Point Animation (p. 1461) topic). The FFD doesn’t actually create accessible control points until you do this, a behavior that shows up in the track view in normal 3ds max use - you cannot actually place control point keyframes in the track view until you’ve animated the control point. Second, control point coordinates are in FFD lattice space. This is a normalized space, with [0,0,0] at the lower left-hand corner (at control_point_1) and [1,1,1] at the opposite corner of the FFD lattice, so you have to be careful about computing and scaling correct coordinates when you set them. This is also reflected in the track view for FFD control points in normal 3ds max use - if you look at their values in a keyframe property dialog or a function graph, they are in this normalized lattice space, not world-space coordinates. You’d have to work in this space also if you tried to use expression controllers to control FFDs. The modifier utility functions getModContextBBoxMin() and getModContextBBoxMin() can be used to determine the world-space bounds of an FFD lattice allowing you to compute scaled lattice space coordinates from world coordinates. See details on these functions in the Modifier Common Properties, Operators, and Methods (p. 1096) topic. An example
1099
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
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)
1101
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
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: .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. .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.
1103
1104
Chapter 11
|
3ds max Objects
.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. .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. .start_point
Point3
default: [0,0,0]
-- animatable
The starting point for the application of the affect region. .end_point
Point3
default: [0,0,25] – animatable
The end point for application of the affect region. Methods: AffectRegionVal
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: .angle
Float
default: 0.0
-- animatable
The angle to bend from the vertical plane. .direction
Float
default: 0.0
-- animatable
The direction of the bend relative to the horizontal plane.
Bend : Modifier
.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 .limit
Boolean
default: false
When on, applies limit constraints to the bend effect. .upperlimit
Float
default: 0.0
-- animatable, alias: Upper_Limit
The upper boundary in world units from the bend center point beyond which the bend no longer affects geometry. .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. .center
Point3
default: [0,0,0] -- animatable
You can translate and animate the center, altering the Bend gizmo’s shape, and thus the shape of the bent object. .gizmo
SubAnim
You can transform and animate the gizmo like any other object, altering the effect of the Bend modifier. .position
Point3
default: [0,0,0]
-- animatable
The position of the gizmo object. Translating the gizmo translates its center an equal distance. .rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the gizmo object. Rotating the gizmo takes place with respect to its center. .scale
Point3
default: [1,1,1]
-- animatable
The scaling of the gizmo object. Scaling the gizmo takes place with respect to its center.
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
1105
1106
Chapter 11
|
3ds max Objects
Bevel : Modifier Constructor: bevel ...
Properties: .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 .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 .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.) .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.) .segments
Integer
default: 1
-- animatable
The number of intermediate segments between each level. .Smooth_Levels
Integer
default: 0
Controls whether smoothing groups are applied to the sides of a beveled object. Caps always use a different smoothing group than the sides. When turned on, smoothing groups are applied to the sides, and the sides appear rounded. When turned off, smoothing groups are not applied, and the sides appear as flat bevels. OFF ON .Produce_Mapping_Coords
Integer
default: 0
When turned on, mapping coordinates are applied to the beveled object. OFF ON
Bevel : Modifier
.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 .Separation_Between_Lines
Float
default: 1.0
-- animatable
The distance to be maintained between edges. .Starting_Outline
Float
default: 0.0
-- animatable
The distance the outline is offset from the original shape. A non-zero setting changes the original shape’s size. Positive values make the outline larger and negative values make the outline smaller. .Level_1_Height
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
The distance of Level 1 above the Start level. .Level_1_Outline
Float
The distance to offset the Level 1 outline from the Start Outline. .Use_Level_2
Integer
default: 0
Adds a level after Level 1 when on. OFF ON .Level_2_Height
Float
default: 0.0
-- animatable
Float
default: 0.0
-- animatable
The distance above Level 1. .Level_2_Outline
The offset distance of the Level 2 outline from Level 1. .Use_Level_3
Integer
default: 0
Adds a level after the previous level. If Level 2 is not on, Level 3 is added after Level 1. OFF ON .Level_3_Height
Float
default: 0.0
-- animatable
default: 0.0
-- animatable
The distance above the previous level. .Level_3_Outline
Float
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)
1107
1108
Chapter 11
|
3ds max Objects
Bevel_Profile : Modifier Constructor: bevel_profile ...
Properties: .Produce_Mapping_Coords
Integer
default: 0
Integer
default: 1
When on, assigns UV coordinates. OFF ON .Cap_Bottom
When on, caps the end with the lowest local Z value (bottom) of the object. When turned off, the bottom is open. OFF ON .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 .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.) .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 .Separation_Between_Lines
Float
default: 1.0
-- animatable
The distance that sides should be kept apart to prevent intersections. .profile_gizmo
SubAnim
You can move, scale, and rotate the gizmo to alter the effect of the bevel profile modifier on the object. .position animatable
The position of the profile gizmo.
Point3
default: [0,0,0]
--
CameraMap : Modifier
.rotation animatable
Quat
default: (quat 0 0 0 1) --
Point3
default: [1,1,1]
The rotation of the profile gizmo. .scale animatable
The scale of the profile gizmo. Note: There is no way to set the Profile shape using MAXScript in 3ds max 4.
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
CameraMap : Modifier Constructor: cameraMap ...
Properties: There are no additional properties for CameraMap. Note: There is no way to set the Camera using MAXScript in 3ds max 4.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
--
1109
1110
Chapter 11
|
3ds max Objects
Cap_Holes : Modifier Constructor: cap_holes ...
Properties: .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 .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 .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
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)
1111
1112
Chapter 11
|
3ds max Objects
Displace : Modifier Constructor: displace ...
Properties: .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. .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. .lumCenterEnable
Boolean
default: false
When on, the software uses .center to determine which level of gray Displace uses as the zero displacement value. .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. .bitmap
Bitmap
default: undefined
This bitmap is used for displacement. .map
TextureMap
default: undefined
This texture map is used for displacement. .blur
Float
default: 0.0
-- animatable
Blurs or softens the effect of the bitmapped displacement by increasing the value. .maptype
Integer
default: 0
Type of map projection: Planar (Projects the map from a single plane.) Cylindrical (Projects the map as if it were wrapped around the cylinder.) Spherical (Projects the map from a sphere, with singularities at the top and bottom of the sphere where the bitmap edges meet at the sphere’s poles.) Shrink Wrap (Projects the map from a sphere, as Spherical does, but truncates the corners of the map and joins them all at a single pole, creating only one singularity at the bottom.)
Displace : Modifier
.cap
Boolean
default: false
When on, a copy of the map is projected from the ends of the cylinder. .length
Float
default: 1.0
-- animatable
The length of the displace gizmo’s bounding box. .width
Float
default: 1.0
-- animatable
The width of the displace gizmo’s bounding box. .height
Float
default: 1.0
-- animatable
The height of the displace gizmo’s bounding box. Height has no effect on Planar mapping. .U_Tile
Float
default: 1.0
-- animatable
The number of times the bitmap repeats along the U-axis. .U_Flip
Boolean
default: false
When on, reverses the orientation of the map along the U-axis. .V_Tile
Float
default: 1.0
-- animatable
The number of times the bitmap repeats along the V-axis. .V_Flip
Boolean
default: false
When on, reverses the orientation of the map along the V-axis. .W_Tile
Float
default: 1.0
-- animatable
The number of times the bitmap repeats along the W-axis. .W_Flip
Boolean
default: false
When on, reverses the orientation of the map along the W-axis. .useMap
Boolean
default: false
When on, has Displace use the UV mapping set earlier in the stack. This has no effect if the object is not mapped. .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. .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 .Map_Channel
Integer
default: 1
The map channel to use for displacement projection. .axis
Integer
default: 2
Flips the alignment of the mapping gizmo along one of its three axes: X Y Z
1113
1114
Chapter 11
|
3ds max Objects
.gizmo
SubAnim
You can move, scale, and rotate the gizmo to alter the effect of the displacement modifier on the object. .position
Point3
default: [0,0,0]
-- animatable
The position of the displace gizmo. .rotation
Quat
default: (quat 0 0 -1 0) -- animatable
The rotation of the displace gizmo. .scale
Point3
default: [1,1,1]
-- animatable
The scaling of the displace gizmo. Note: The Gizmo property is not present until the Displace modifier has been applied to a node.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Edit_Mesh : Modifier Constructor: edit_mesh ...
Properties: There are no additional properties for Edit_Mesh. See the getVertSelection(), getFaceSelection(), and getEdgeSelection() functions in the Editable_Mesh (p. 1041) topic for information about accessing the current selections in the Edit_Mesh modifier. See the Editable Mesh Modify Panel Command Modes and Operations section in the Editable_Mesh (p. 1041) topic for information on invoking the various Edit_Mesh operations.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Edit_Patch : Modifier
Edit_Patch : Modifier Constructor: edit_patch ...
Properties: There are no additional properties for Edit_Patch. See the Editable Patch Modify Panel Command Modes and Operations section in the Patch (p. 1088) topic for information on invoking the various Edit_Patch operations.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Edit_Spline : Modifier Constructor: edit_spline ...
Properties: There are no additional properties for Edit_Spline. See the Editable Spline Modify Panel Command Modes and Operations section in the SplineShape (p. 1079) topic for information on invoking the various Edit_Spline operations.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Extrude : Modifier Constructor: extrude ...
Properties: <Extrude>.amount
Float
default: 25.0
-- animatable
default: 1
-- animatable, alias: segments
The depth of the extrusion. <Extrude>.segs
Integer
The number of segments that will be created in the extruded object.
1115
1116
Chapter 11
|
3ds max Objects
<Extrude>.capStart
Boolean
default: true
When on, generates a flat surface over the start of the extruded object. <Extrude>.capEnd
Boolean
default: true
When on, generates a flat surface over the end of the extruded object. <Extrude>.capType
Integer
default: 0
Cap type: Morph (Arranges cap faces in a predictable, repeatable pattern, which is necessary for creating morph targets. Morph capping can generate long, thin faces that don’t render or deform as well as grid capping. Use morph capping primarily if you’re extruding multiple morph targets.) Grid (Arranges cap faces in a square grid trimmed at the shape boundaries. This method produces a surface of evenly sized faces that can be deformed easily by other modifiers. When you choose the Grid capping option, the grid lines are hidden edges rather than visible edges.) <Extrude>.output
Integer
default: 1
Set the output: Patch (Produces an object that you can collapse to a patch object.) Mesh (Produces an object that you can collapse to a mesh object.) NURBS (Produces an object that you can collapse to a NURBS surface.) <Extrude>.matIDsBoolean
default: true
When on, assigns different material IDs to the sides and the caps of the extruded object. Specifically, the sides receive ID 3, and the caps receive IDs 1 and 2. <Extrude>.useShapeIDsBooleandefault: false
When on, the software uses the material ID values assigned to segments in the modified object. <Extrude>.smoothBoolean
default: true
When on, applies smoothing to the extruded shape. <Extrude>.mapCoords
Boolean
default: false
Creates the extruded object with mapping coordinates already applied. When Generate Mapping Coordinates is turned on, additional mapping coordinates are applied to the end caps placing a single 1 x 1 tile on each cap. Note: The Generate Material IDs, Use Shape IDs, and Smooth properties are not accessible to MAXScript in 3ds max 4.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
FFDBox : Modifier
FFDBox : Modifier Constructor: ffdBox ...
Properties: .dispLattice
Boolean
default: true
-- alias: Lattice
Draws lines connecting the control points to make a grid. .dispSource
Boolean
default: false -- alias: Source_Volume
Displays the control points and lattice in their unmodified state. .deformType
Integer
default: 0
deformType = 0 - Only In Volume; 1 - All Vertices .falloff
Float
default: 0.0
-- animatable
Determines the distance from the lattice that the FFD effect will decrease to zero. .tension
Float
default: 25.0
-- animatable
Adjusts the tension of the deformation splines. .continuity
Float
default: 25.0
-- animatable
Adjusts the continuity of the deformation splines. .inPoints
Boolean
default: true
-- alias: Inside_Points
Only control points inside the object are affected by Conform to Shape. .outPoints
Boolean
default: true
-- alias: Outside_Points
Only control points outside the object are affected by Conform to Shape. .offset
Float
default: 0.05
-- animatable
The distance by which control points affected by Conform to Shape are offset from the object surface. .lattice_transform SubAnim .position .rotation .scale
Point3 Quat Point3
default: [0,0,0] -- animatable default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable
Methods: conformToShape
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
resets the control points of the FFD to their default positions. getDimensions setDimensions
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.
1117
1118
Chapter 11
|
3ds max Objects
animateVertex
Applies controllers to the specified control points of the FFD modifier, where is one of: #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
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
FFDCyl : Modifier Constructor: ffdCyl ...
Properties: .dispLattice
Boolean
default: true
-- alias: Lattice
Draws lines connecting the control points to make a grid. .dispSource
Boolean
default: false -- alias: Source_Volume
Displays the control points and lattice in their unmodified state. .deformType
Integer
default: 0
Deform type: Only In Volume (Deforms vertices that lie inside the source volume. Vertices outside the source volume are not affected.) All Vertices (Deforms all vertices regardless of whether they lie inside or outside the source volume depending on the value in the Falloff spinner. The deformation outside the volume is a continuous extrapolation of the deformation inside the volume. Note that the deformation can be extreme for points far away from the source lattice.) .falloff
Float
default: 0.0
-- animatable
Determines the distance from the lattice that the FFD effect will decrease to zero. .tension
Float
default: 25.0
-- animatable
Adjusts the tension of the deformation splines. .continuity
Float
default: 25.0
-- animatable
Adjusts the continuity of the deformation splines. .inPoints
Boolean
default: true
-- alias: Inside_Points
Only control points inside the object are affected by Conform to Shape. .outPoints
Boolean
default: true
-- alias: Outside_Points
Only control points outside the object are affected by Conform to Shape. .offset
Float
default: 0.05
-- animatable
The distance by which control points affected by Conform to Shape are offset from the object surface. .lattice_transform
SubAnim
.position .rotation .scale
Point3 Quat Point3
default: [0,0,0] -- animatable default: (quat 0 0 0 1) -- animatable default: [1,1,1] -- animatable
1119
1120
Chapter 11
|
3ds max Objects
Methods: conformToShape
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
resets the control points of the FFD to their default positions. getDimensions setDimensions
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
Applies controllers to the specified control points of the FFD modifier, where is one of: #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
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
Scripting Vertex and Control Point Animation (p. 1461) Modifier Sub-Object Transform Properties (p. 1099)
FFD_2x2x2 : Modifier Constructor: ffd_2x2x2 ...
Properties: .dispLattice
Boolean
default: true
-- alias: Lattice
Draws lines connecting the control points to make a grid. .dispSource
Boolean
default: false -- alias: Source_Volume
Displays the control points and lattice in their unmodified state. .deformType
Integer
default: 0
Deform type: Only In Volume (Deforms vertices that lie inside the source volume. Vertices outside the source volume are not affected.) All Vertices (Deforms all vertices, regardless of whether they lie inside or outside the source volume.) .inPoints
Boolean
default: true
-- alias: Inside_Points
Only control points inside the object are affected by Conform to Shape. .outPoints
Boolean
default: true
-- alias: Outside_Points
Only control points outside the object are affected by Conform to Shape. .offset
Float
default: 0.05
-- animatable
The distance by which control points affected by Conform to Shape are offset from the object surface. .lattice_transform
SubAnim
.position animatable .rotation animatable .scale animatable
Point3
default: [0,0,0]
--
Quat
default: (quat 0 0 0 1) --
Point3
default: [1,1,1]
--
Note: The Falloff, Tension, and Continuity parameters are not accessible by MAXScript in 3ds max 4.
1121
1122
Chapter 11
|
3ds max Objects
Methods: conformToShape
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
resets the control points of the FFD to their default positions. animateVertex
Applies controllers to the specified control points of the FFD modifier, where is one of: #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
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
FFD_3x3x3 : Modifier Constructor: ffd_3x3x3 ...
Properties: .dispLattice
Boolean
default: true
-- alias: Lattice
Draws lines connecting the control points to make a grid. .dispSource
Boolean
default: false -- alias: Source_Volume
Displays the control points and lattice in their unmodified state. .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.) .inPoints
Boolean
default: true
-- alias: Inside_Points
Only control points inside the object are affected by Conform to Shape. .outPoints
Boolean
default: true
-- alias: Outside_Points
Only control points outside the object are affected by Conform to Shape. .offset
Float
default: 0.05
-- animatable
The distance by which control points affected by Conform to Shape are offset from the object surface. .lattice_transform
SubAnim
.position animatable .rotation animatable .scale animatable
Point3
default: [0,0,0]
--
Quat
default: (quat 0 0 0 1) --
Point3
default: [1,1,1]
--
Note: The Falloff, Tension, and Continuity parameters are not accessible by MAXScript in 3ds max 4. Methods: conformToShape
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
resets the control points of the FFD to their default positions.
1123
1124
Chapter 11
|
3ds max Objects
animateVertex
Applies controllers to the specified control points of the FFD modifier, where is one of: #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
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: .dispLattice
Boolean
default: true
-- alias: Lattice
Draws lines connecting the control points to make a grid. .dispSource
Boolean
default: false -- alias: Source_Volume
Displays the control points and lattice in their unmodified state.
FFD_4x4x4 : Modifier
.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.) .inPoints
Boolean
default: true
-- alias: Inside_Points
Only control points inside the object are affected by Conform to Shape. .outPoints
Boolean
default: true
-- alias: Outside_Points
Only control points outside the object are affected by Conform to Shape. .offset
Float
default: 0.05
-- animatable
The distance by which control points affected by Conform to Shape are offset from the object surface. .lattice_transform
SubAnim
.position animatable .rotation animatable .scale animatable
Point3
default: [0,0,0]
--
Quat
default: (quat 0 0 0 1) --
Point3
default: [1,1,1]
--
Note: The Falloff, Tension, and Continuity parameters are not accessible by MAXScript in 3ds max 4. Methods: conformToShape
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
resets the control points of the FFD to their default positions. animateVertex
Applies controllers to the specified control points of the FFD modifier, where is one of: #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
1125
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
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
Face_Extrude : Modifier Constructor: face_extrude ...
Properties: .amount
Float
default: 0.0
-- animatable
Float
default: 100.0
-- animatable
The extent of the extrusion. .scale
Scales each cluster of selected faces independently about its center. .extrude_center extrudeFromCenter
Point3
default: [0,0,0]
-- animatable; alias:
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)
1127
1128
Chapter 11
|
3ds max Objects
Flex : Modifier Constructor: flex ...
Note: This class is not available in 3D Studio VIZ. Properties: .flex
Float
default: 1.0
-- animatable
Sets the amount of flex and bend. Larger values increase the effect. Range=0 to 1000. .strength
Float
default: 3.0
-- animatable
Sets the spring strength. A value of 100 is rigid. Range=0 to 100. .sway
Float
default: 7.0
-- animatable
Sets the time for the object to come to rest. Lower values increase the time for the object to come to rest. Range=0 to 100. .chase
Boolean
default: true
Turns chase springs on/off. .center
Boolean
default: true
Turns the use of weights on/off. .solver
Integer
default: 0
The type of solver that will be used: Euler Solver Mid-point solver Runnge Kutta The higher the solver number, the more accurate/stable it is, and the slower it will run. .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. .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. .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. .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. .paintRadius
Float
default: 36.0
Set the size of the brush in world units. Range=.001 to 99999. .paintFeather
Float
default: 0.7
Set the hardness of the brush. A value of 1 is soft. Range=-1 to 1.
Flex : Modifier
.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. .forceNode ArrayParameter Nodes; alias: Force_Nodes
default: #()
--array containing Force
Assigns force effect to particle space warps identified in an array. .colliderNode
ArrayParameter
default: #()
--
node array
Array contains a list of collider objects that flex will use. .referenceFrame
Integer
default: 0
-- alias: Reference_Frame
Flex will start computing at this frame. .endFrame
Integer
default: 100
Flex will stop computing after this time. .enableEndFrame
Boolean
default: false
Turns the end frame on/off. .affectAll
Boolean
default: false
Forces flex to ignore any selection in the stack, causing it to flex the entire object. .enableAdvanceSprings Boolean
default: false
Enables the advance spring fields. When this is off, the Stretch and Torque parameters are slaved to the Stretch and Stiffness parameters. .stretchStrength Float
default: 0.2
--
animatable
--
animatable
--
animatable
--
animatable
Controls the strength of stretch springs. .stretchSway
Float
default: 0.2
Controls the sway of stretch springs. .torqueStrength
Float
default: 0.2
Controls the strength of torque springs. .torqueSway
Float
default: 0.2
Controls the sway of torque springs. .holdLength
Boolean
default: false
Turns on/off the hold length parameter. .holdLengthPercent Float
default: 25.0
The maximum percentage the spring can stretch/squash. .addMode
Integer
default: 0
Flag to determine how springs will be added: Single spring across selected vertices Edge Springs Edge Springs across only selected vertices Hold Springs Hold Springs across only selected vertices .displaySprings
Booleandefault: false
Turns on/off the display of spring when in sub-object mode.
1129
1130
Chapter 11
|
3ds max Objects
.holdRadius
Float
default: 50.0
The maximum distance that will be looked around when the hold springs are added. .extraStrength 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 strength of extra springs (those that belong to a group other than 0 [stretch] or 1 [torque]). .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]). .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. .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. .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. .createSpringDepth Integer
default: 2
The number of times the system is recursed when using create soft body. .createSpringMult
Float
default: 2.0
The amount the flex effect is multiplied after each recursion when using create soft body. The following property is defined by Flex, but is not used: .paintBackface
Boolean
default: true
Flex Methods: Paint
Presses the paint button in the flex interface. SetReference
Presses the Set Reference button in the flex interface. Reset
Presses the Reset button in the flex interface. AddForce
Adds a force to the force list. force (node) - The force to be added to the force list. RemoveForce
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
NumberVertices
Returns and integer containing the number of points in the system. SelectVertices <sel>
Selects the vertices passed in sel. Sel (bitarray) - The bitarray that holds the selection. Update (boolean) - Determines whether the viewports get updated. GetSelectedVertices
Returns bitarray containing the current selected vertices. GetVertexWeight
Returns the weight of a specific vertex. index (integer) - The index of the vertex you want to get the weight of. SetVertexWeight
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 <sel>
Sets the edges to sel. Sel (bitarray) - The bitarray that holds the edge selection. Update (boolean) - Determines whether the viewports get updated. GetEdgeList
Returns bitarray containing the current edge selection list. AddSpringFromSelection
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
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
Removes all the springs the in the system. addSpringButton
Equivalent of hitting the Add Spring button in the interface. RemoveSpringButton
Equivalent of hitting the Remove Spring button in the interface. optionsButton
Equivalent of hitting the Options button in the interface.
1131
1132
Chapter 11
|
3ds max Objects
createSimpleSoftButton
Equivalent of hitting the Create Simple Soft Bodies button in the interface. RemoveSpringByEnd
This removes all springs that are connected to a vertex. a (integer) – The vertex index to be checked. removeSpringByEnds
This removes all springs that are connected to both vertex a and b. a (integer) – First vertex index. b (integer) – Second vertex index. removeSpringByIndex
Remove a spring from the list which is at index in the spring list. index (integer) – Index of the spring. numberSprings
Returns the number of springs in the system getSpringGroup
Returns the group that the spring belongs to. index (integer) – Index of the spring you want to examine. setSpringGroup
Sets the spring’s groups. index (integer) – Index of the spring. group (integer) – The group number (0-12). getSpringLength
Gets the rest length of a particular spring. index (integer) – Index of the spring that you want to examine. setSpringLength
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
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
Returns the number of vertices in the object the Flex modifier is applied to. flexOps.GetVertexWeight
Returns the weight of the specified vertex. flexOps.SelectVertices \ ( | | )
Lathe : Modifier
Selects the specified vertices. Clears any previously selected vertices. flexOps.isEdgeVertex
Returns 0 if the specified vertex is not an edge vertex, 1 if it is an edge vertex. flexOps.ClearEdgeVertices \ ( | )
Sets the specified vertices to not be edge vertices. flexOps.SetEdgeVertices \ ( | )
Sets the specified vertices to be edge vertices. flexOps.SetVertexWeights \ ( | ) \ ( <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: .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. .weldCore
Boolean
default: false
When on, simplifies the mesh by welding together vertices that lie on the axis of revolution. .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. .segs
Integer
default: 16
-- animatable, alias: segments
Determines how many interpolated segments are created in the surface between the start and endpoint.
1133
1134
Chapter 11
|
3ds max Objects
.capStart
Boolean
default: false
Caps the start of the lathed object with Degrees set to less than 360 and a closed shape. .capEnd
Boolean
default: false
Caps the end of the lathed object with Degrees set to less than 360 and a closed shape. .capType
Integer
default: 0
Cap type: Morph (Arranges cap faces in a predictable, repeatable pattern necessary for creating morph targets. Morph capping can generate long, thin faces that don’t render or deform as well as grid capping. Use morph capping primarily if you are lathing multiple morph targets.) Grid (Arranges cap faces in a square grid trimmed at the shape boundaries. This method produces a surface of evenly sized faces that can easily be deformed by other modifiers.) .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.) .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. .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. .useShapeIDs Boolean
default: false
When on, the software uses the material ID values assigned to segments in the object. .smooth
Boolean
default: true
When on, applies smoothing to the extruded shape. .axis
SubAnim
At this sub-object level, you can transform and animate the axis of revolution. .position animatable
Point3
default: [0,0,0]
--
Position of the axis of revolution. .rotation
Quat
default: (quat -0.707107 0 0 0.707107) -- animatable
Rotation of the axis of revolution. .scale animatable
Point3
Scale of the axis of revolution.
default: [1,1,1]
--
Lattice : Modifier
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: .Strut_Radius
Float
default: 2.0
-- animatable
Integer
default: 1
-- animatable
The radius of the struts. .Strut_Segments
The number of segments along the struts. Increase this value when you need to deform or distort the struts with subsequent modifiers. .Strut_Sides
Integer
default: 4
-- animatable
The number of sides around the perimeter of the struts. .Joint_Radius
Float
default: 5.0
-- animatable
Integer
default: 1
-- animatable
The radius of the joints. .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)
1135
1136
Chapter 11
|
3ds max Objects
Linked_XForm : Modifier Constructor: linked_xform ...
Properties: .Control
Node
default: undefined
Object that the vertices are linked to. When transformed, the vertices follow. Note: While you can assign a node to the Control property in MAXScript, an internal transform in Linked_XForm is not properly set. This will cause an immediate, undesired offset of the geometry of the node the modifier is applied to.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
MaterialByElement : Modifier Constructor: materialByElement ...
Properties: <MaterialByElement>.method
Integer
default: 1
Set method: Random Distribution (Assigns the materials at random to different elements in the object.) List Frequency (Determines an approximate relative weight (percentage) for each of up to eight material ID’s) <MaterialByElement>.Material_ID_Count Integer
default: 2
-- animatable
The minimum number of material IDs to assign. Because material ID assignment is random, setting it to the number of materials in the multi/sub-object material or higher doesn’t guarantee that all materials get used. <MaterialByElement>.Material_ID__1
Float
default: 0.5 -- animatable
Approximate relative weight (percentage) for first material ID. <MaterialByElement>.Material_ID__2
Float
default: 0.5 -- animatable
Approximate relative weight (percentage) for second material ID. <MaterialByElement>.Material_ID__3
Float
default: 0.0 -- animatable
Approximate relative weight (percentage) for third material ID. <MaterialByElement>.Material_ID__4
Float
default: 0.0 -- animatable
Approximate relative weight (percentage) for fourth material ID.
MaterialModifier : Modifier
<MaterialByElement>.Material_ID__5
Float
default: 0.0 -- animatable
Approximate relative weight (percentage) for fifth material ID. <MaterialByElement>.Material_ID__6
Float
default: 0.0 -- animatable
Approximate relative weight (percentage) for sixth material ID. <MaterialByElement>.Material_ID__7
Float
default: 0.0 -- animatable
Approximate relative weight (percentage) for seventh material ID. <MaterialByElement>.Material_ID__8
Float
default: 0.0 -- animatable
Approximate relative weight (percentage) for eighth material ID. <MaterialByElement>.Random_Seed
Integer
default: 12345
The seed value for the (pseudo-)randomization of material ID assignments. Note: Material_ID values are shown as percentages in the 3ds max user interface, but stored as fractions.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
MaterialModifier : Modifier Constructor: materialModifier ...
Properties: <Materialmodifier>.materialid 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)
1137
1138
Chapter 11
|
3ds max Objects
Melt : Modifier Constructor: melt ...
Note: This class is not available in 3D Studio VIZ. Properties: <Melt>.Melt_Amount
Float
default: 0.0
-- animatable
The extent of the “decay,” or melting effect applied to the gizmo, thus affecting the object. <Melt>.Spread
Float
default: 19.0
-- animatable
Specifies how much the object and melt will spread as the Amount value increases. It’s basically a “bulge” along a flat plane. <Melt>.Solidity_Preset
Integer
default: 0
The relative height of the center of the melted object. Less-solid substances like jelly tend to settle more in the center as they melt. This group provides several presets for different types of substances, as well as a Custom spinner for setting your own solidity: Ice (The default Solidity setting.) Glass (Uses a high Solidity setting to simulate glass.) Jelly (Causes a significant drooping effect in the center.) Custom (Sets any solidity between 0.2 and 30.0.) <Melt>.Solidity_Custom_Value
Float
default: 1.0
Integer
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. Don’t Flip Axis Flip Axis <Melt>.center
Point3
default: [0,0,0]
The center of the melt gizmo. <Melt>.gizmo
SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Melt modifier. <Melt.gizmo>.position
Point3
default: [0,0,0]
-- animatable
The position of the gizmo. Translating the gizmo translates its center an equal distance.
MeshSmooth : Modifier
<Melt.gizmo>.rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the gizmo. Rotating the gizmo takes place with respect to its center. <Melt.gizmo>.scale
Point3
default: [1,1,1]
-- animatable
The scaling of the gizmo. Scaling the gizmo takes place with respect to its center. The following properties are defined by Melt, but are not used: <Melt>.cut_Off__obsolete <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.
1139
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
Integer
default: 0
--
animatable; alias:
Number of smoothing iterations to be applied to the object at render time. <MeshSmooth>.useRenderSmoothness use_render_smoothness
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
Float
default: 1.0
--
animatable;
Lets you choose a different Smoothness value to be applied to the object at render time. <MeshSmooth>.ignoreBackfacing
Boolean
default: false
When on, selection of sub-objects selects only those sub-objects whose normals are visible in the viewport. When off (the default), selection includes all sub-objects, regardless of the direction of their normals. <MeshSmooth>.controlLevel
Integer
default: 0
Allows you to see the control mesh after one or more iterations and to edit sub-object points and edges at that level. <MeshSmooth>.displayCage display_control_mesh
Boolean
default: false; alias:
Displays an orange wireframe gizmo that shows what the control mesh looks like after it’s been converted to polygons (if applicable) and before the smoothing occurs. <MeshSmooth>.useSoftSel
Boolean
default: false
Affects the action of Move, Rotate, and Scale functions within editable object or edit modifier, and the action of deformation modifiers applied to the object if they are operating on a sub-object selection. When on, 3ds max applies a spline curve deformation to the unselected sub-objects surrounding the selection that you transform. <MeshSmooth>.useEdgeDist
Boolean
default: false
Turn on/off use Edge Distance. <MeshSmooth>.edgeDist
Integer
default: 1
Limits the region affected by the number of edges between the selection and the affected vertices.
MeshSmooth : Modifier
<MeshSmooth>.affectBackfacing
Boolean
default: false
When on, deselected sub-objects whose normals (or, in the case of vertices and edges, the normals of faces to which they’re attached) are facing in the opposite direction to the average normal of the selected sub-objects, are affected by the soft selection influence. <MeshSmooth>.falloff
Float
default: 20.0
Distance in current units from the center to the edge of a sphere defining the affected region. Use higher falloff settings to achieve more gradual slopes, depending on the scale of your geometry. <MeshSmooth>.pinch
Float
default: 0.0
Raises and lowers the top point of the curve along the vertical axis. Sets the relative “pointedness” of the region. When negative, a crater is produced instead of a point. At a setting of 0, Pinch produces a smooth transition across this axis. <MeshSmooth>.bubble
Float
default: 0.0
Expands and contracts the curve along the vertical axis. Sets the relative “fullness” of the region. Limited by Pinch, which sets a fixed starting point for Bubble. A setting of 0 for Pinch and 1.0 for Bubble produces a maximum smooth bulge. Negative values for Bubble move the bottom of the curve below the surface, creating a “valley” around the base of the region. <MeshSmooth>.strength
Float
default: 0.5
-- animatable
Sets the size of the added faces using a range from 0.0 to 1.0. Values near 0.0 create small faces that are very thin and close to the original vertices and edges, values near 0.5 size faces evenly between edges, and values near 1.0 create large new faces and make the original faces very small. <MeshSmooth>.Relax
Float
default: 0.0
-- animatable
Applies a positive relax effect to smooth all vertices. <MeshSmooth>.limitSurface project_to_limit_surface
Boolean
default: false; alias:
Places all points on the “limit surface” of the MeshSmooth result, which is the surface you’d get after an infinite number of iterations. <MeshSmooth>.smoothResult
Boolean
default: false; alias: smooth_output
Applies the same smoothing group to all faces. <MeshSmooth>.sepByMats separate_by_materials
Boolean
default: false; alias:
Prevents the creation of new faces for edges between faces that do not share Material IDs. <MeshSmooth>.sepBySmGroups separate_by_smoothing_group
Boolean
default: false; alias:
Prevents the creation of new faces at edges between faces that don’t share at least one smoothing group.
1141
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
default: 0
-- animatable
Float Float Float
default: 20.0 default: 0.0 default: 0.0
-- animatable -- animatable -- animatable
Use_Soft_Selection = 0 - off; 1 - on <Mesh_Select>.falloff <Mesh_Select>.Pinch <Mesh_Select>.Bubble
Mirror : Modifier
See the getVertSelection(), getFaceSelection(), and getEdgeSelection() functions in the Editable_Mesh (p. 1041) topic for information about accessing the current selections in the Mesh_Select modifier.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Mirror : Modifier Constructor: mirror ...
Properties: <Mirror>.mirror_axis
Integer
default: 0
The axis or axes about which the mirroring takes place: X Y Z XY YZ ZX <Mirror>.Mirror_Offset
Float
default: 0.0
-- animatable
The offset, in units, from the mirror axis. <Mirror>.copy
Boolean
default: false
When on, copies the geometry rather than simply mirroring it. <Mirror>.mirror_center
SubAnim
Represents the axis of the mirror effect. You can move, rotate or scale the gizmo to affect the mirroring. <Mirror.Mirror_Center>.position
Point3
default: [0,0,0]
-- animatable
Quat
default: (quat 0 0 0 1) -- animatable
Point3
default: [1,1,1]
The position of the mirror center. <Mirror.Mirror_Center>.rotation
The rotation of the mirror center. <Mirror.Mirror_Center>.scale
The scaling of the mirror center.
-- animatable
1143
1144
Chapter 11
|
3ds max Objects
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Morpher : Modifier Constructor: Morpher ...
Note: This class is not available in 3D Studio VIZ. Properties: <Morpher>.Use_Limits
Integer
default: 1
When on, 3ds max uses the minimum and maximum limits for all channels. <Morpher>.Spinner_Minimum
Float
default: 0.0
Float
default: 100.0
Integer
default: 0
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 1’s percentage controller is stored in subAnim 1.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
NCurve_Sel : Modifier
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: .seed
Integer
default: 0
-- animatable
A random start point is generated from the number you set. .scale
Float
default: 100.0
-- animatable
The size of the noise effect (not strength). Larger values produce smoother noise, lower values more jagged noise. .fractal
Boolean
default: false
-- animatable
When on, produces a fractal effect based on current settings. .roughness
Float
default: 0.0
-- animatable, alias: rough
The extent of fractal variation. Lower values are less rough than higher values. .iterations
Float
default: 6.0
-- animatable
The number of iterations (or octaves) used by the fractal function. Fewer iterations use less fractal energy and generate a smoother effect. An iteration of 1.0 is the same as turning .fractal off. .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. .animate
Boolean
default: false
Enables/disables animation playback. .frequency
Float
default: 0.25
The speed of the noise effect. Higher frequencies make the noise quiver faster. Lower frequencies produce a smoother and more gentle noise. .phase
Time
default: 0f
-- animatable
1145
1146
Chapter 11
|
3ds max Objects
Shifts the start and end points of the underlying wave. .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. .gizmo
SubAnim
You can move, rotate, or scale the gizmo sub-object to affect the noise. You can also animate the sub-object transforms. .position
Point3
default: [0,0,0]
-- animatable
Quat
default: (quat 0 0 0 1) -- animatable
Point3
default: [1,1,1]
The position of the gizmo. .rotation
The rotation of the gizmo. .scale
-- animatable
The scaling of the gizmo.
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Normalize_Spline : Modifier Constructor: normalize_spline ...
Properties: <normalize_spline>.Length
Float
default: 20.0
Determines how many control points are added. Smaller values produce more control points; larger values produce fewer.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
NormalModifier : Modifier
NormalModifier : Modifier Constructor: normalModifier ...
Properties: .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. .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)
1147
1148
Chapter 11
|
3ds max Objects
Optimize : Modifier Constructor: optimize ...
Properties: .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 .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 .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 . .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. .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. .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. .preservemat1
Boolean
default: false
When on, prevents face collapse across material boundaries. .preservesmooth1
Boolean
default: false
When turned on, allows only faces that share at least one smoothing group to collapse.
Optimize : Modifier
.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 . .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. .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. .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. .preservemat2
Boolean
default: false
When on, prevents face collapse across material boundaries. .preservesmooth2
Boolean
default: false
When turned on, allows only faces that share at least one smoothing group to collapse. .manualUpdate
Boolean
default: false
When on, enables the Update button. When turned off, Optimize works as it does by default, updating the viewport display dynamically. .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)
1149
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
Float
default: 1.0
-- animatable
Scales the object along the U (horizontal) axis of the gizmo patch. <PatchDeform>.V_Percent percentage
Float
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
Float
default: 1.0
-- animatable
Scales the object along the V (vertical) axis of the gizmo patch. <PatchDeform>.rotation
Float
default: 0.0
-- animatable, angle
Rotates the modified object with respect to the gizmo patch. <PatchDeform>.Plane_to_Patch_Deform
Integer
default: 0
Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo patch: XY YZ ZX <PatchDeform>.Flip_deformation_axis
Integer
default: 0
When on, reverses the gizmo direction. Don’t flip Flip <PatchDeform>.gizmo
SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the modifier. The PatchDeform gizmo is a representation of the deforming patch object, so transforming it determines which part of the patch affects the modified object.
PathDeform : Modifier
<PatchDeform.gizmo>.position
Point3
default: [0,0,0]
-- animatable
The position of the patchdeform gizmo. <PatchDeform.gizmo>.rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the patchdeform gizmo. <PatchDeform.gizmo>.scale
Point3
default: [1,1,1]
-- animatable
The scale of the patchdeform gizmo. Note: There is no way to specify the patch to deform to using MAXScript in 3ds max 4.
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
PathDeform : Modifier Constructor: pathDeform ...
Properties: <PathDeform>.path
Node
default: undefined
Float
default: 0.0 -- animatable,
The selected path object. <PathDeform>.Percent_along_path percentage
Moves the object along the gizmo path based on a percentage of the path length. <PathDeform>.Stretch
Float
default: 1.0 -- animatable
Scales the object along the gizmo path, using the object’s pivot point as the base of the scale. <PathDeform>.rotation
Float
default: 0.0 -- animatable, angle
Rotates the object about the gizmo path. <PathDeform>.Twist
Float
default: 0.0 -- animatable, angle
Twists the object about the path. The twist angle is based on the rotation of one end of the overall length of the path. Typically, the deformed object takes up only a portion of the path, so the effect can be subtle.
1151
1152
Chapter 11
|
3ds max Objects
<PathDeform>.axis
Integer
default: 2
The axus if the gizmo object which is aligned with the corresponding local axis of the path object: X Y Z <PathDeform>.Flip_deformation_axis
Integer
default: 0
When on, reverses the gizmo path 180 degrees about the specified axis. Don’t flip Flip <PathDeform>.gizmo
SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the modifier. The PathDeform gizmo is a representation of the deforming path object, so transforming it determines which part of the path affects the modified object. <PathDeform.Gizmo>.position
Point3
default: [0,0,0]
-- animatable
The position of the pathdeform gizmo. <PathDeform.Gizmo>.rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the pathdeform gizmo. <PathDeform.Gizmo>.scale
Point3
default: [1,1,1]
-- animatable
The scale of the pathdeform gizmo.
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Preserve : Modifier Constructor: preserve ...
Properties: .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. .Edge_Length_Weight
Float
The relative importance of the edge length.
default: 1.0
-- animatable
Push : Modifier
.Face_Angle_Weight
Float
default: 0.3
-- animatable
default: 0.3
-- animatable
The relative importance of the face angle. .Volume_Weight
Float
The relative importance of the volume. .Apply_To_Whole_Mesh
Integer
default: 0
When on, applies Preserve to the entire object, regardless of the selection passed from previous levels of the stack: OFF ON .Selected_Verts_Only
Integer
default: 0
When on, uses previous sub-object vertex selections. Note that it doesn’t matter if the Vertex sub-object level is active in a previous stack item. As long as vertices have been selected, Preserve will use that selection. OFF ON .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_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.
1153
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: .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_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. .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: .amplitude1
Float
default: 5.0
-- animatable, alias: Amplitude_1
The amplitude of the first ripple. .amplitude2
Float
default: 5.0
-- animatable, alias: Amplitude_2
The amplitude of the second ripple, which is perpendicular to the first ripple. .wavelength
Float
default: 25.0
-- animatable, alias: Wave_Length
The distance between the peaks of the wave. The greater the length, the smoother and more shallow the ripple for a given amplitude.
Skew : Modifier
.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. .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. .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. .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. .position
Point3
default: [0,0,0]
-- animatable
The poosition of the ripple gizmo. .rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the ripple gizmo. .scale
Point3
default: [1,1,1]
-- animatable
The scale of the ripple gizmo.
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Skew : Modifier Constructor: skew ...
Properties: <Skew>.amount
Float
default: 25.0
-- animatable
The angle to skew from the vertical plane. <Skew>.direction
Float
default: 0.0
-- animatable
The direction of the skew relative to the horizontal plane.
1155
1156
Chapter 11
|
3ds max Objects
<Skew>.axis
Integer
default: 2
The axis that will be skewed: X Y Z <Skew>.limit
Boolean
default: false
When on, applies limit constraints to the Skew modifier. <Skew>.upperlimit
Float
default: 0.0
-- animatable, alias: Upper_Limit
The upper limit boundaries in world units from the skew center point, beyond which the skew no longer affects the geometry. <Skew>.lowerlimit
Float
default: 0.0
-- animatable, alias: Lower_Limit
The lower limit boundaries in world units from the skew center point, beyond which the skew no longer affects the geometry. <Skew>.center
Point3
default: [0,0,0]
-- animatable
At this sub-object level, you can translate and animate the center of the Skew effect. <Skew>.gizmo
SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Skew modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center. <Skew.Gizmo>.position
Point3
default: [0,0,0]
-- animatable
The position of the skew gizmo. <Skew.Gizmo>.rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the skew gizmo. <Skew.Gizmo>.scale
Point3
default: [1,1,1]
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)
-- animatable
Skin : Modifier
Skin : Modifier Constructor: skin ...
Note: This class is not available in 3D Studio VIZ. Properties: <Skin>.Effect
Float
default: 0.0
Absolute weight of selected vertices. <Skin>.filter_vertices
Boolean
default: false
Turn vertex selection on/off. <Skin>.filter_cross_sections
Boolean
default: true
Turn cross-section selection on/off. <Skin>.filter_envelopes
Boolean
default: true
Boolean
default: false
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
Boolean
default: true
Turn on/off the display of weighted vertices. <Skin>.ref_frame
Integer
default: 0
Sets the frame where the bones and the mesh are in a reference position. <Skin>.paint_radius
Float
default: 24.0
Sets the brush radius. <Skin>.paint_feather
Float
default: 0.7
Sets the brush falloff. <Skin>.cross_radius
Float
default: 10.0
Scales the selected envelope cross-section. <Skin>.always_deform
Boolean
default: true
Always deforms the skin when the bones are moved. The Animate button does not have to be turned on to move bones and deform the skin. <Skin>.paint_str
Float
default: 0.1
Sets the brush strength. <Skin>.localSquash
Array
default: #()
--
float array
Amount of squash applied to each bone. <Skin>.initialSquash
Array
default: #()
--
float array
Array containing initial squash values for a bone. <Skin>.initialStaticEnvelope
Boolean
default: false
When turned on, an initial static envelope size is used when a bone is added. When off, the initial envelope size is determined by the object bounding box.
1157
1158
Chapter 11
|
3ds max Objects
<Skin>.initialInnerEnvelopePercent Float
default: 0.75
The multiplier used to find the inner cross-section size when initialStaticEnvelope is false. <Skin>.initialOuterEnvelopePercent Float
default: 3.5
The multiplier used to find the outer cross-section size when initialStaticEnvelope is false. <Skin>.initialEnvelopeInner
Float
default: 10.0
The inner cross-section size when initialStaticEnvelope is true. <Skin>.initialEnvelopeOuter
Float
default: 50.0
The outer cross-section size when initialStaticEnvelope is true. <Skin>.draw_all_gizmos
Boolean
default: true
Turn on/off the display off all gizmos. <Skin>.draw_all_vertices
Boolean
default: false
Turns on/off the display of all vertices as small dots. <Skin>.shadeweights
Boolean
default: true
Turn on/off display of weighted vertices using vertex colors. <Skin>.envelopesAlwaysOnTop
Boolean
default: true
Turn on/off display of envelopes on top of the mesh. <Skin>.crossSectionsAlwaysOnTop
Boolean
default: true
Turn on/off display of cross-sections on top of the mesh. <Skin>.rigid_vertices
Boolean
default: false
When turned on, a single vertex can only be affected by one bone. <Skin>.rigid_handles
Boolean
default: false
When turned on, all handles have the same weights as the knot that owns them. <Skin>.fast_update
Boolean
default: false
When turned on, the system uses only rigid vertices for the viewport display. <Skin>.gizmos
Array
default: #()
--
max object array
Array containing all gizmos assigned to skin. Methods: The following methods require that the Skin modifier be the displayed modifier in the Modify panel, and that the Modify panel is active. skinops.addbone <Skin>
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
skinops.addCrossSection <Skin>
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>
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>
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> <Enable_bool>
Enables/disables the gizmo type whose index equals GizmoID_integer.
1159
1160
Chapter 11
|
3ds max Objects
skinOps.GetBoneName <Skin>
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>
Returns the bone visibility parameter of the bone. 0 is invisible, 1 is visible. skinops.getBonePropFalloff
<Skin>
Returns the falloff parameter of the bone. 1 – linear 2 – sinual 3 – fast out 4 – slow out skinops.getBonePropRelative <Skin>
Gets the relative property of the bone. It returns 1 if relative or 0 is absolute. skinops.GetCrossSectionU <Skin>
Gets the U value from the specified bone and cross section skinops.getCurrentSelectGizmoType <Skin>
Returns the current selected gizmo type. skinops.GetEndPoint <Skin>
Returns a point3 which is the end point of the bone. skinOps.GetInnerRadius <Skin> \
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>
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> \
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
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>
Returns a point3 which is the start point of the bone. skinOps.GetVertexWeight <Skin> \
Returns the influence of the Nth bone affecting the specified vertex. skinOps.GetVertexWeightBoneID <Skin> \
Returns the system bone index of the Nth bone affecting the specified vertex. skinOps.GetVertexWeightCount <Skin>
Returns the number of bones influencing the specified vertex. skinops.isBoneSelected <Skin>
Returns 1 if the bone is selected otherwise 0. skinOps.IsVertexModified <Skin>
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>
Returns 1 if the vertex is selected, 0 if it is not selected. skinops.loadEnvelope <Skin>
Opens the load envelopes dialog skinops.loadEnvelope <Skin>
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.
1161
1162
Chapter 11
|
3ds max Objects
skinops.pasteToBone
<Skin>
Pastes the copy buffer to bone id supplied. skinops.pasteToSelectedBone
<Skin>
Pastes the copy buffer to the current selected bone. skinops.removebone <Skin>
Removes the current selected bone from the bones system. skinops.removebone <Skin>
Removes the BoneID from the bones system. skinops.RemoveCrossSection $<Skin>
Removes the current selected cross section from the current selected bone. skinops.RemoveCrossSection <Skin>
Removes a particular cross-section from a particular bone. skinOps.ReplaceVertexWeights <Skin> ( | ) ( <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>
Saves the envelopes to the file supplied skinOps.SelectBone <Skin>
Selects the specified bone in the Bone list. skinops.selectCrossSection <Skin>
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>
Desc – this function selects the gizmo who index equals gizmoID. skinops.selectGizmoType <Skin>
Selects the gizmo type whose index equals gizmoTypeID. skinops.selectNextBone <Skin>
Selects the next bone in the bone list.
Skin : Modifier
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> \ ( | |
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>
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>
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>
Sets the U value from the specified bone and cross section. skinops.SetEndPoint
<Skin> <EndPointPos_point3>
Sets the end point of the specified bone. skinOps.SetInnerRadius <Skin> \
Sets the inner cross section radius for the specified bone and cross section. skinOps.SetOuterRadius <Skin> \
Sets the outer cross section radius for the specified bone and cross section. skinops.setSelectedBonePropEnvelopeVisible <Skin>
Sets the bone visibility parameter of the current selected bone. For Visible_integer, 0 = visible, 1 = invisible when not selected
1163
1164
Chapter 11
|
3ds max Objects
skinops.setSelectedBonePropFalloff
<Skin>
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>
Sets the relative property of the current selected bone. For relative_integer, 0 is relative mode, 1 is absolute mode. skinops.SetStartPoint
<Skin> <EndPointPos_point3>
Sets the start point of the specified bone skinOps.SetVertexWeights <Skin> \ ( | ) ( <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>
Zooms the active or all views to the selected bone. If All_boolean is true, then all views are zoomed. skinops.ZoomToGizmo <Skin>
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
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]
--
Quat
default: (quat 0 0 0 1) -- animatable
Point3
default: [1,1,1]
The position of the slice plane object. <sliceModifier.Slice_Plane>.rotation
The rotation of the slice plane object. <sliceModifier.Slice_Plane>.scale animatable
The scale of the slice plane object.
--
1165
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
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.
1167
1168
Chapter 11
|
3ds max Objects
<Squeeze>.Squeeze_Amount
Float
default: 0.0
-- animatable
The magnitude of the squeezing action. Values larger than zero tend to constrict the “waist” of the object, and values less than zero tend to bulge the waistline out, as if the object had been stepped on. <Squeeze>.Squeeze_Curvature
Float
default: 2.0
-- animatable
The degree of curvature into the squeeze. Low values cause a sharp squeezing effect, while high values create a gradual, less pronounced squeeze. <Squeeze>.Limit_Squeeze_Effects
Integer
default: 0
When on, limits the extent of the squeeze effect as defined by the Lower and Upper Limit settings. OFF ON <Squeeze>.Squeeze_Lower_Limit
Float
default: -50.0
-- animatable
The limit of the squeeze effect in the positive direction along the Z axis. <Squeeze>.Squeeze_Upper_Limit
Float
default: 50.0
-- animatable
The limit of the squeeze effect in the negative direction along the Z axis. <Squeeze>.Bias percentage
Float
default: 0.0
-- animatable,
The relative amounts of bulge and squeeze while retaining a constant object volume. <Squeeze>.Volume percentage
Float
default: 100.0
-- animatable,
Increases or decreases the effects of both Squeeze and Bulge in parallel. <Squeeze>.center
Point3
default: [0,0,0] -- animatable
At this sub-object level, you can translate and animate the center, altering the Squeeze gizmo’s shape, and thus the shape of the squeezed object. <Squeeze>.gizmo
SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Squeeze modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center. <Squeeze.Gizmo>.position
Point3
default: [0,0,0]
-- animatable
The position of the squeeze gizmo. <Squeeze.Gizmo>.rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the squeeze gizmo. <Squeeze.Gizmo>.scale
Point3
default: [1,1,1]
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)
-- animatable
STL_Check : Modifier
STL_Check : Modifier Constructor: stl_check ...
Properties: <STL_Check>.Selection_Type
Integer
default: 4
Selects incorrect geometry specific to the following settings: Open Edge (Checks for open edges.) Double Face (Checks for faces that share the same 3D space.) Spike (Checks for spikes, which are isolated faces that share only one edge with the object.) Multiple Edge (Checks for faces that share more than one edge.) Everything (Checks for all of the above.) <STL_Check>.Select_Faces
Integer
default: 1
These options specify the level of incorrect geometry that’s selected, based on the settings for the selection_type value: Don’t Select (When on, STL Check doesn’t select any part of objects in error.) Select Edges (When on, STL Check marks the edges of faces in error by selecting them. The selection of erroneous edges is visible in viewports.) Select Faces (When on, STL Check marks the faces of any object in error by selecting them. The selection of erroneous faces is visible in viewports.) <STL_Check>.Check_Now
Integer
default: 0
Turn on to perform the STL check. For complex objects, expect a pause between the time you turn this on, and the time you see the reported errors in the Status group. OFF ON <STL_Check>.Change_MatID
Integer
default: 1
When on, STL Check also marks faces in error by assigning them a unique material ID. OFF ON <STL_Check>.Material_ID
Integer
default: 2
The material ID that STL Check assigns to faces in error.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
1169
1170
Chapter 11
|
3ds max Objects
Stretch : Modifier Constructor: stretch ...
Properties: <Stretch>.Stretch
Float
default: 0.0
-- animatable
The base scale factor for all three axes. The scale factor derived from the Stretch value varies according to the sign of the value. <Stretch>.Amplify
Float
default: 0.0
-- animatable
The scale factor applied to the minor axes. Amplify generates a multiplier using the same technique as stretch. The multiplier is then applied to the stretch value before the scale factor for the minor axes is calculated. <Stretch>.axis
Integer
default: 2
Determines which of the object’s local axes is the Stretch Axis: X Y Z <Stretch>.limit
Boolean
default: false
When on, the stretch effect is limited by the from and to values. <Stretch>.from
Float
default: 0.0
-- animatable
The boundary of the stretch effect along the negative Stretch Axis. <Stretch>.to
Float
default: 0.0
-- animatable
The boundary of the stretch effect along the positive Stretch Axis. <Stretch>.center
Point3
default: [0,0,0]
-- animatable
At this sub-object level, you can translate and animate the center, altering the Stretch gizmo’s shape, and thus the shape of the stretched object. <Stretch>.gizmo
SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Stretch modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center. <Stretch.Gizmo>.position
Point3
default: [0,0,0]
-- animatable
The position of the stretch gizmo. <Stretch.Gizmo>.rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the stretch gizmo. <Stretch.Gizmo>.scale
Point3
default: [1,1,1]
The scale of the stretch gizmo. Note: The Limit Effect property is not accessible by MAXScript in 3ds max 4.
-- animatable
Surface : 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)
Surface : Modifier Constructor: surface ...
Properties: <surface>.threshold
Float
default: 1.0
-- animatable
The overall distance that is used to weld the vertices of the spline object. All vertices/ vectors within the threshold of each other are treated as one. <surface>.steps
Integer
default: 5
-- animatable
The number of steps used between each vertex. The higher the step count, the smoother the curve you will get between vertices. Note: The Flip Normals, Remove Interior Patches, and Use Only Selected Segs. properties are not accessible by MAXScript in 3ds max 4.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
SurfDeform : Modifier Constructor: surfDeform ...
Properties: <SurfDeform>.surface
Node
default: undefined
The surface used to apply deformation. <SurfDeform>.U_Percent 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.
1171
1172
Chapter 11
|
3ds max Objects
<SurfDeform>.U_Stretch
Float
default: 1.0
-- animatable
Scales the object along the U (horizontal) axis of the gizmo patch. <SurfDeform>.V_Percent percentage
Float
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. <SurfDeform>.V_Stretch
Float
default: 1.0
-- animatable
Scales the object along the V (vertical) axis of the gizmo patch. <SurfDeform>.rotation
Float
default: 0.0
-- animatable, angle
Rotates the modified object with respect to the gizmo patch. <SurfDeform>.Plane_to_Patch_Deform
Integer
default: 0
Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo patch: XY YZ ZX <SurfDeform>.Flip_deformation_axis
Integer
default: 0
When on, reverses the gizmo direction. Don’t flip Flip <SurfDeform>.gizmo
SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the modifier. The PatchDeform gizmo is a representation of the deforming patch object, so transforming it determines which part of the patch affects the modified object. <SurfDeform.Gizmo>.position
Point3
default: [0,0,0]
-- animatable
The position of the surfdeform gizmo. <SurfDeform.Gizmo>.rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the surfdeform gizmo. <SurfDeform.Gizmo>.scale
Point3
default: [1,1,1]
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)
-- animatable
Taper : Modifier
Taper : Modifier Constructor: taper ...
Properties: .amount
Float
default: 1.0
-- animatable
The extent to which the ends are scaled. Amount is a relative value with a maximum of 10. .curve
Float
default: 0.0
-- animatable, alias: curvature
Applies a curvature to the sides of the Taper gizmo, thus affecting the shape of the tapered object. Positive values produce an outward curve along the tapered sides, negative values an inward curve. At 0, the sides are unchanged. .primaryaxis
Integer
default: 2
The central axis or spine of the taper: X Y Z .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 .symmetry
Boolean
default: false
-- animatable
When on, produces a symmetrical taper around the primary axis. A taper is always symmetrical around the effect axis. .limit
Boolean
default: false
Enables/disables upper and lower limits for the taper effect. .upperlimit
Float
default: 0.0
-- animatable, alias: Upper_Limit
The upper limit boundaries in world units from the taper center point, beyond which the taper no longer affects the geometry. .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. .center
Point3
default: [0,0,0]
-- animatable
At this sub-object level, you can translate and animate the center, altering the Taper gizmo’s shape, and thus the shape of the melted object
1173
1174
Chapter 11
|
3ds max Objects
.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. .position
Point3
default: [0,0,0]
-- animatable
The position of the taper gizmo. .rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the taper gizmo. .scale
Point3
default: [1,1,1]
-- animatable
The scale of the taper gizmo.
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Tessellate : Modifier Constructor: tessellate ...
Properties: .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
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: .angle
Float
default: 0.0
-- animatable
The amount of twist around the vertical axis. .bias
Integer
default: 0
-- animatable
Causes the twist rotation to bunch up at either end of the object. When the parameter is negative, the object twists closer to the gizmo center. When the value is positive, the object twists more away from the gizmo center. When the parameter is 0, the twisting is uniform. .axis
Integer
default: 2
The axis along which the twist will occur. This is the local axis of the Twist gizmo. X Y Z .limit
Boolean
default: false
When on, applies limit constraints to the Twist modifier. .upperlimit
Float
default: 0.0
-- animatable, alias: Upper_Limit
The upper limit for the twist effect. .lowerlimit
Float
default: 0.0
-- animatable, alias: Lower_Limit
The lower limit for the twist effect. .center
Point3
default: [0,0,0]
-- animatable
You can translate and animate the center at this sub-object level, altering the Twist gizmo’s shape, and thus the shape of the twisted object.
1175
1176
Chapter 11
|
3ds max Objects
.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. .position
Point3
default: [0,0,0]
-- animatable
The position of the twist gizmo. .rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the twist gizmo. .scale
Point3
default: [1,1,1]
-- animatable
The scale of the twist gizmo.
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Unwrap_UVW : Modifier Constructor: unwrap_UVW ...
Note: This class is not available in 3D Studio VIZ. Properties: There are no additional properties for Unwrap_UVW. Methods: The following methods require that the Unwrap UVW modifier be the displayed modifier in the Modify panel, and that the Modify panel is active. PlanarMap()
Presses the Planar Map button in the rollup interface Save()
Presses the Save button in the rollup interface Load()
Presses the Load button in the rollup interface Reset()
Presses the Reset button in the rollup interface Edit()
Presses the Edit button in the rollup interface
Unwrap_UVW : Modifier
SetMapChannel
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
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 (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.
1177
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
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
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
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
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.
1179
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
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
Sets the color of selected texture vertices. color (point3) – The color that you want the selected vertice to be. GetRenderWidth
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
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
SetWeldThreshold
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
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
Returns a boolean value which indicates whether a texture vertex is selected. index (integer) – The index of the vertex to check.
1181
1182
Chapter 11
|
3ds max Objects
MoveSelectedVertices
Moves the selected texture vertices by the offset. offset (point3) - The offset by which you want to move the vertices. RotateSelectedVertices
Rotates the selected vertices around their center point. angle (float) – The angle in radians that you want to rotate the selection by. RotateSelectedVertices
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>
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>
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
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
This sets the selected vertices x values in absolute coordinates. p (float) – The absolute position along the x axis.
Unwrap_UVW : Modifier
MoveY
This sets the selected vertices y values in absolute coordinates. p (float) – The absolute position along the y axis. MoveZ
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
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
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.
1183
1184
Chapter 11
|
3ds max Objects
ForceUpdate
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
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 <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
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
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
GetVertexIndexFromFace
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
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
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
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
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).
1185
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
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> <sel>
This allows you to manipulate the position of vertex attached to a face. Basically, it detaches the vertex if multiple faces share that vertex and then moves it to the position specified. So if you want to move the 3rd vertex of face 1 to (.5,.5,.0) you would do setFaceVertex [.5 .5 .0] 1 3. If you don’t want the vertex broken use SetVertexSPosition. pos (point3) - The position that you want to move a vertex to. fIndex (integer) – The index of the face that you wish to work on. vIndex (integer) – The ith vertex of the face that you want to change. sel (boolean) – Whether or not to select the vertex after it is recreated. SetFaceHandle <pos> <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> <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
SetFaceVertexIndex
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
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
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: .U_Tile
Float
default: 1.0
Integer
default: 0
-- animatable
The tiling along the U-axis. .U_Flip
When on, reverses the direction of the map along the U-axis. OFF ON .V_Tile
The tiling along the V-axis.
Float
default: 1.0
-- animatable
1187
1188
Chapter 11
|
3ds max Objects
.V_Flip
Integer
default: 0
When on, reverses the direction of the map along the V-axis. OFF ON .W_Tile
Float
default: 1.0
Integer
default: 0
-- animatable
The tiling along the W-axis. .W_Flip
When on, reverses the direction of the map along the W-axis. OfFF ON .U_Offset
Float
default: 0.0
-- animatable
Float
default: 0.0
-- animatable
Float
default: 0.0
-- animatable
Offsets the map along the U-axis. .V_Offset
Offsets the map along the V-axis. .W_Offset
Offsets the map along the W-axis. .Map_or_Vertex_Color
Integer
default: 0
Specifies whether to apply the transform to a mapping channel or a vertex color channel: Map Channel Vertex Color Channel Note: The Map Channel property is not accessible by MAXScript in 3ds max 4.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
UVWmap : Modifier Constructor: uvwmap ...
Properties: .maptype
Integer
default: 0
Determines the type of mapping coordinates used. Different kinds of mapping are distinguished by how the map is geometrically projected onto the object and how the projection interacts with the object’s surfaces.
UVWmap : Modifier
Planar (Projects the map from a single plane flat against the object, somewhat like projecting a slide. Planar projection is useful when only one side of an object needs to be mapped. It is also useful for obliquely mapping multiple sides, and for mapping two sides of a symmetrical object.) Cylindrical (Projects the map from a cylinder, wrapping it around an object. Seams where the edges of the bitmap meet are visible unless a seamless map is used. Cylindrical projection is useful for objects that are roughly cylindrical in shape.) Spherical (Surrounds the object by projecting the map from a sphere. You see a seam and mapping singularities at the top and bottom of the sphere where the bitmap edges meet at the sphere’s poles. Spherical mapping is useful for objects that are roughly spherical in shape.) Shrink Wrap (Uses spherical mapping, but truncates the corners of the map and joins them all at a single pole, creating only one singularity. Shrink-wrap mapping is useful when you want to hide the mapping singularity.) Box (Projects the map from the six sides of a box. Each side projects as a planar map, and the effect on the surface depends on the surface normal. Each face is mapped from the closest box surface whose normal most closely parallels its own normal.) Face (Applies a copy of the map to every face of an object. Pairs of faces sharing a hidden edge are mapped with the full rectangular map. Single faces with no hidden edge are mapped with a triangular portion of the map.) XYZ to UVW (Maps 3D procedural coordinates to UVW coordinates. This “sticks” the procedural texture to the surface. If the surface stretches, so does the 3D procedural map.) .cap
Boolean
default: false
When on, applies planar mapping coordinates to the caps of the cylinder. .length
Float
default: 1.0
-- animatable
The length of the UVW mapping gizmo. .width
Float
default: 1.0
-- animatable
The width of the UVW mapping gizmo. .height
Float
default: 1.0
-- animatable
The height of the UVW mapping gizmo. .utile
Float
default: 1.0
-- animatable, alias: U_Tile
The tiling of the UVW map along the U-axis. .uflip
Boolean
default: false
When on, reverses the image about the U-axis. .vtile
Float
default: 1.0
-- animatable, alias: V_Tile
The tiling of the UVW map along the V-axis. .vflip
Boolean
default: false
When on, reverses the image about the V-axis. .wtile
Float
default: 1.0
-- animatable, alias: W_Tile
The tiling of the UVW map along the W-axis.
1189
1190
Chapter 11
|
3ds max Objects
.wflip
Boolean
default: false
When on, reverses the image about the W-axis. .channel
Integer
default: 0
Specifies whether to apply the transform to a mapping channel or a vertex color channel: Map Channel Vertex Color Channel .mapChannel
Integer
default: 1
The map channel used to apply mapping transforms. .axis
Integer
default: 2
Specifies which axis of the gizmo is aligned with the local Z-axis of the object: X Y Z .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. .position
Point3
default: [0,0,0]
-- animatable
The position of the UVWmap gizmo. .rotation
Quat
default: (quat 0 0 -1 0) -- animatable
The rotation of the UVWmap gizmo. .scale
Point3
default: [1,1,1]
-- animatable
The scale of the UVWmap gizmo. Note: The Map Channel property is not accessible by MAXScript in 3ds max 4. The Gizmo property is not present until the Uvwmap modifier has been applied to a node.
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Vertex_Colors : Modifier
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)
1191
1192
Chapter 11
|
3ds max Objects
VolumeSelect : Modifier Constructor: volumeselect ...
Properties: .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 .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.) .invert
Boolean
default: false
When on, the entire selection set is reversed. Geometry that was unselected becomes selected, and vice versa. .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.) .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
.Node
Node
default: undefined
The node which defines the selection space when .volume is set to 3 (mesh object). .matID Material_ID
Integer
default: 1
-- alias:
When .volume is set to 5 (material ID), all faces or vertices using the material ID specified by this value are selected. .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. .texture TextureMap
TextureMap
default: undefined
-- alias:
When .volume is set to 4 (texture map), this texture map will define the selection space. .map Map_Channel_Type
Integer
default: 0
-- alias:
Specifies whether to apply the selection by mapping channel or vertex color channel: Map Channel Vertex Color Channel .mapChannel Map_Channel
Integer
default: 1
-- alias:
Specifies which map channel to use when .map is set to 0. .autofit
Boolean
default: true
-- alias: Auto_fit
When on, automatically adjusts the gizmo size and shape to fit the object as you change the underlying topology. .UseAffectRegion Use_affect_region
Boolean
default: false
-- alias:
default: 20.0
-- animatable
When on, a soft selection region is applied. .falloff
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. .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. .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.
1193
1194
Chapter 11
|
3ds max Objects
.center
Point3
default: [0,0,0]
-- animatable
You can translate and animate the center, which affects rotation or scaling of the Volume Select modifier’s gizmo. .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. .position
Point3
default: [0,0,0]
-- animatable
The position of the volumeselect gizmo. .rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the volumeselect gizmo. .scale
Point3
default: [1,1,1]
-- animatable
The scale of the volumeselect gizmo. Note: The Map Channel property is not accessible by MAXScript in 3ds max 4. The center and gizmo properties are not present until the Volumeselect modifier has been applied to a node.
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Wave : Modifier Constructor: wave ...
Properties: <Wave>.amplitude1
Float
default: 5.0
-- animatable, alias: Amplitude_1
This produces a sine wave along the gizmo’s Y-axis. Switching a value from positive to negative reverses the positions of peaks and troughs. <Wave>.amplitude2
Float
default: 5.0
-- animatable, alias: Amplitude_2
This produces a sine wave the gizmo’s X-axis. Switching a value from positive to negative reverses the positions of peaks and troughs. <Wave>.wavelength
Float
default: 25.0
-- animatable, alias: Wave_Length
The distance in current units between the crests of both waves. <Wave>.phase
Float
default: 0.0
-- animatable
Shifts the wave pattern over the object. Positive numbers move the pattern in one direction, while negative numbers move it in the other.
XForm : Modifier
<Wave>.decay
Float
default: 0.0
-- animatable
Limits the effect of the wave generated from its origin. A decay value decreases the amplitude at increasing distance from the center. As this value increases, the wave is concentrated at the center and flattened until it disappears (completely decays). <Wave>.center
Point3
default: [0,0,0]
-- animatable
At this sub-object level, you can translate and animate the center, altering the Wave gizmo’s shape, and thus the shape of the wavy object. <Wave>.gizmo
SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Wave modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center. <Wave.Gizmo>.position
Point3
default: [0,0,0]
-- animatable
The position of the wave gizmo. <Wave.Gizmo>.rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the wave gizmo. <Wave.Gizmo>.scale
Point3
default: [1,1,1]
-- animatable
The scale of the wave gizmo.
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
XForm : Modifier Constructor: xform ...
Properties: <XForm>.center
Point3
default: [0,0,0]
-- animatable
At this sub-object level, you can translate and animate the center, altering the Xform gizmo’s shape, and thus the shape of the object. <XForm>.gizmo
SubAnim
At this sub-object level, you can transform and animate the gizmo like any other object, altering the effect of the Xform modifier. Translating the gizmo translates its center an equal distance. Rotating and scaling the gizmo takes place with respect to its center. <XForm.Gizmo>.position
Point3
The position of the wave gizmo.
default: [0,0,0]
-- animatable
1195
1196
Chapter 11
|
3ds max Objects
<XForm.Gizmo>.rotation
Quat
default: (quat 0 0 0 1) -- animatable
The rotation of the wave gizmo. <XForm.Gizmo>.scale
Point3
default: [1,1,1]
-- animatable
The scale of the wave gizmo.
See also Modifier Sub-Object Transform Properties (p. 1099) Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Spacewarp Binding SpacewarpModifiers The SpaceWarp Binding SpacewarpModifiers are not directly created in MAXScript, but are rather created and applied to a node using the bindSpaceWarp() method. Most of the SpacewarpModifiers do not have any additional properties. Constructors and Properties: SimpleOSMToWSMMod: bindSpaceWarp <node> 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> DeflectorBinding: bindSpaceWarp <particlesys_node> <deflector_node> DisplaceBinding: bindSpaceWarp <node> <spaceDisplace_node> FFD_Binding: bindSpaceWarp <node> <spaceFFDBox_node> bindSpaceWarp <node> <spaceFFDCyl_node> GravityBinding: bindSpaceWarp <node> MotorMod: bindSpaceWarp <node> <motor_node> PathFollowMod: bindSpaceWarp <particlesys_node> <path_Follow_node>
XForm : Modifier
PBombMod: bindSpaceWarp <node> PDynaFlectMod: bindSpaceWarp <node> POmniFlectMod: bindSpaceWarp <particlesys_node> PushMod: bindSpaceWarp <node> RippleBinding: bindSpaceWarp <node> <spaceRipple_node> .Flexibility Float default: 1.0
-- animatable
SDeflectMod: bindSpaceWarp <particlesys_node> <sdeflector_node> SDynaFlectMod: bindSpaceWarp <node> <SDynaFlect_node> SOmniFlectMod: bindSpaceWarp <particlesys_node> <SOmniFlect_node> SpaceConform: bindSpaceWarp <node> UDeflectorMod: bindSpaceWarp <particlesys_node> UDynaFlectMod: bindSpaceWarp <node> UOmniFlectMod: bindSpaceWarp <particlesys_node> WaveBinding: bindSpaceWarp <node> <spaceWave_node> <WaveBinding>.Flexibility Float
default: 1.0
WindBinding: bindSpaceWarp <node> <wind_node>
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
-- animatable
1197
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
The map channel used.
Integer
default: 1
SpaceCameraMap : SpacewarpModifier
<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.
1199
1200
Chapter 11
|
3ds max Objects
<SpacePatchDeform>.U_Stretch
Float
default: 1.0
-- animatable
Scales the object along the U (horizontal) axis of the gizmo patch. <SpacePatchDeform>.V_Percent percentage
Float
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. <SpacePatchDeform>.V_Stretch
Float
default: 1.0
-- animatable
Scales the object along the V (vertical) axis of the gizmo patch. <SpacePatchDeform>.rotation angle
Float
default: 0.0
-- animatable,
Rotates the modified object with respect to the gizmo patch. <SpacePatchDeform>.Plane_to_Patch_Deform
Integer
default: 0
Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo patch: XY YZ ZX <SpacePatchDeform>.Flip_deformation_axis
Integer
default: 0
When on, reverses the gizmo direction: OFF ON Note: There is no way to specify the patch to deform to using MAXScript in 3ds max 4.
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
SpacePathDeform : SpacewarpModifier Constructor: SpacePathDeform ...
Properties: <SpacePathDeform>.path
Node
default: undefined
Float
default: 0.0
The node designated as the path. <SpacePathDeform>.Percent_along_path percentage
-- animatable,
Moves the object along the gizmo path based on a percentage of the path length.
SpaceSurfDeform : SpacewarpModifier
<SpacePathDeform>.Stretch
Float
default: 1.0
-- animatable
Scales the object along the gizmo path, using the object’s pivot point as the base of the scale. <SpacePathDeform>.rotation angle
Float
default: 0.0
-- animatable,
Float
default: 0.0
-- animatable,
Rotates the object about the gizmo path. <SpacePathDeform>.Twist angle
Twists the object about the path. The twist angle is based on the rotation of one end of the overall length of the path. Typically, the deformed object takes up only a portion of the path, so the effect can be subtle. <SpacePathDeform>.axis
Integer
default: 2
Choose one to rotate the gizmo path to align with a specified local axis of the object: X Y Z <SpacePathDeform>.Flip_deformation_axis
Integer
default: 0
When on, reverses the gizmo path 180 degrees about the specified axis. OFF ON
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
SpaceSurfDeform : SpacewarpModifier Constructor: SpaceSurfDeform ...
Properties: <SpaceSurfDeform>.surface
Node
default: undefined
Float
default: 50.0
The surface used for deformation. <SpaceSurfDeform>.U_Percent percentage
-- 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.
1201
1202
Chapter 11
|
3ds max Objects
<SpaceSurfDeform>.U_Stretch
Float
default: 1.0
-- animatable
Scales the object along the U (horizontal) axis of the gizmo patch. <SpaceSurfDeform>.V_Percent percentage
Float
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. <SpaceSurfDeform>.V_Stretch
Float
default: 1.0
-- animatable
Scales the object along the V (vertical) axis of the gizmo patch. <SpaceSurfDeform>.rotation angle
Float
default: 0.0
-- animatable,
Rotates the modified object with respect to the gizmo patch. <SpaceSurfDeform>.Plane_to_Patch_Deform
Integer
default: 0
Choose a two-axis plane of the object to make parallel with the XY plane of the gizmo patch: XY YZ ZX <SpaceSurfDeform>.Flip_deformation_axis
Integer
default: 0
Flip_deformation_axis = 0 - off; 1 - on
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Surface_Mapper : SpacewarpModifier Constructor: surface_mapper ...
Properties: There are no additional properties for Surface_Mapper. Methods: updateSurfaceMapper <surface_mapper>
This method has the effect of performing a manual update to the mapping provided by the associated NURBS surface. Note: There is no way to specify the Source Texture Surface using MAXScript in 3ds max 4.
Material Common Properties, Operators, and Methods
See also Modifier Common Properties, Operators, and Methods (p. 1096) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Material : MAXWrapper The Material class represents the materials which you can assign to objects in 3ds max. You can create materials like standard, blend, and raytrace, access various properties on them, and assign these materials to 3ds max objects. The classes derived directly from the Material class are described in the Material Types (p. 1204) topic. Other classes are derived from these classes, and inherit the properties and methods defined for the Material class. The properties, operators, and methods that are common to all classes derived directly from the Material class are described in the Material Common Properties, Operators, and Methods (p. 1203) topic. The Material class is derived from the MAXWrapper class, and inherits the properties and methods defined for that class. These properties and methods are described in the MAXWrapper (p. 808) topic.
Material Common Properties, Operators, and Methods Properties: <material>.name
All the material subclasses can access the name property and specify it as a constructor parameter. <material>.effectsChannel
All the material subclasses can access the effectsChannel property and specify it as a constructor parameter. Methods: assignNewName <material>
Modifies the name of the specified material to make it unique. The name is of the form “Material #1” where the number is incremented as required to make ensure it’s unique. okMtlForScene <material>
Tests the material name against other material names in the scene, and returns true if there are no other materials with the same name, false otherwise. Before assigning material to scene, call this to avoid duplicate names.
1203
1204
Chapter 11
|
3ds max Objects
getMTLMEditFlags ( <material> | ) setMTLMEditFlags ( <material> | )
Get and set the MEdit options for the specified material or texture as a . 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> | ) setMTLMeditObjType ( <material> | )
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> | ) setMTLMeditTiling ( <material> | )
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> | )
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
NoMaterial (p. 1212) RaytraceMaterial (p. 1212) Shellac (p. 1233) Standard (p. 1224) TopBottom (p. 1233)
Blend : Material Constructor: blend ...
Properties: .map1
Material
default: Standard
-- alias: Map_1
default: true
-- alias: Map_1_Enable
The first material to be blended. .map1Enabled
Boolean
Turn on/off the use of the first material in the blend. .map2
Material
default: Standard
-- alias: Map_1
Boolean
default: true
-- alias: Map_2_Enable
TextureMap
default: undefined
the second material to be blended. .map2Enabled
Turn on/off .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. .maskEnabled
Boolean
default: true
-- alias: MaskEnable
Enable/disable the use of the map mask. .interactive
Integer
default: 0
Selects which of the two materials is displayed on object surfaces in viewports by the interactive renderer: Material 1 Material 2 .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.
1205
1206
Chapter 11
|
3ds max Objects
.useCurve
Boolean
default: false
Determines whether the Mixing Curve affects the mix. .upper .lower
Float Float
default: 0.75 default: 0.25
-- animatable -- animatable
These values adjust the level of the Upper and Lower limits. If the two values are the same, the two materials meet at a definite edge. Wider ranges give more gradual blending from one sub-material to the other. The mixing curve displays the effect of changing these values.
See also Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
CompositeMaterial : Material Constructor: compositeMaterial()
Properties: .materialList Array default: #(Standard, undefined, ... , undefined, undefined) -- alias: Material
This array contains all of the materials included in the composite material. .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. .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 .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. .baseMaterial Standard Material materialList[0]
S ets a base material for the composite material.
default: (null) – alias for
DoubleSided : Material
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: .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. .material1
Material
default: Standard
-- alias: Material_1
Boolean
default: true
-- alias: Map_1_Enable
The facing material. .map1Enabled
Turn on/off display of the facing material. .material2
Material
default: Standard
-- alias: Material_2
Boolean
default: true
-- alias: Map_2_Enable
The back material. .map2Enabled
Turn on/off display of the back material.
1207
1208
Chapter 11
|
3ds max Objects
See also Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
MatteShadow : Material Constructor: matteShadow ... matte ...
Properties: <MatteShadow>.opaqueAlpha
Boolean
default: true
-- alias: Opaque_Alpha
Determines whether or not the matte material appears in the alpha channel. If you turn off Opaque Alpha, the matte object will not make an alpha channel, and the image can be used for compositing, just as if there are no matte objects in the scene. <MatteShadow>.applyAtmosphere
Boolean
default: false
Turns the fogging of matte objects on and off. <MatteShadow>.atmosphereDepth
Integer
default: 0
When applying fog, you can choose between two different methods. You can either apply fog as if the matte surface is at an infinite distance from the camera or you can apply it as if the matte surface is actually at that point on the object being shaded. In other words, you can apply the fog to the matte surface in either 2D or 3D. The following controls determine how this is applied: At Background Depth (This is the 2D method. The scanline renderer fogs the scene, and then renders its shadows. In this case, the shadows won’t be lightened by the fog. If you want to lighten the shadows, you need to turn up the shadow brightness.) At Object Depth (This is the 3D method. The renderer first renders the shadows, and then fogs the scene. Since this varies the amount of fog over the 3D matte surface, the generated matte/alpha channels don’t blend perfectly into the background. Use At Object Depth when the matte object is meant to be a 3D object in the scene that the 2D background represents.) <MatteShadow>.receiveShadows
Boolean
default: false
When on, renders shadows on the matte surfaces. <MatteShadow>.affectAlpha
Boolean
default: false
When on, shadows cast on a matte material are applied to the alpha channel. This lets you render bitmaps with alpha channels that you can composite later.
MorpherMaterial : Material
<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
default: 50
-- animatable,
The amount of reflection to use. This is a percentage that can range from 0 to 100. <MatteShadow>.map
TextureMap
default: undefined
Boolean
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
default: 0.0 default: 0.0 default: 0.0
-- animatable, percentage -- animatable, percentage -- animatable, percentage
Float Float Float
default: 0.0 default: 0.0 default: 0.0
-- 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.
1209
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: ] multiSubMaterial [ numsubs: ]
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
<multisubmaterial>.names
ArrayParameter
default: #(”“, ““, ... ““, ““)
Stores the sub-material slot name (not the sub-material name). <Multimaterial>.materialIDList ArrayParameter default: #(0, 1, 2, 3, 4, 5, 6, 7, 8, 9) -- int array; Index <Multisubmaterial>.materialIDList ArrayParameter default: #(0, 1, 2, 3, 4, 5, 6, 7, 8, 9) -- int array; Index
Stores the sub-material ID’s. <Multimaterial>.material1 for materialList[0]; SubAnim <Multisubmaterial>.material1 for materialList[0]; SubAnim
Standardmaterial
default: Standard
Standardmaterial
--
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)
1211
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: .Ambient_Color_On
Float
default: 0.0
If Ambient_Color_On = 0, Ambient_Amount is used, otherwise Ambient is used .Ambient animatable
Color
default: (color 0 0 0) --
Sets the degree to which the material absorbs ambient light. .Ambient_Amount percentage
Float
default: 0.0
-- animatable;
The amount that the ambient map affects the material expressed as a percentage of full intensity. .Luminosity_Color_On
Float
default: 0.0
If Luminosity_Color_On = 0, Self_Illum__Amount is used, otherwise Luminosity is used
RayTraceMaterial : Material
.Luminosity animatable
Color
default: (color 0 0 0) --
The self-illumination color of the material. .Self_Illum_Amount percentage
Float
default: 0.0
-- animatable;
The amount that the self-illumination map affects the material expressed as a percentage of full intensity. .Diffuse 127.5) -- animatable
Color
default: (color 127.5 127.5
Sets the diffuse color. .Transparency_Color_On
Float
default: 0.0
If Transparency_Color_On = 0, Transparency_Amount is used, otherwise Transparecy is used .Transparecy animatable
Color
default: (color 0 0 0) --
Float
default: 0.0
The filter color of the material. .Transparency_Amount percentage
-- animatable;
The amount that the transparency map affects the material expressed as a percentage of full intensity. .Reflect_Color_On
Float
default: 0.0
If Reflect_Color_On = 0, Reflect_Amount is used, otherwise Reflect is used .Reflect animatable
Color
default: (color 0 0 0) --
Float
default: 0.0
The specular reflection color. .Reflect_amount percentage
-- animatable;
The amount that the reflection map affects the material expressed as a percentage of full intensity. .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. .Spec__Color - animatable
Color
default: (color 255 255 255) -
Float
default: 50.0
Sets the color of specular highlights. .Specular_Level percentage
-- animatable;
Sets the intensity of specular highlights. Set the Specular Level to a very high value for very strong, tight highlights.
1213
1214
Chapter 11
|
3ds max Objects
.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. .Soften
Float
default: 0.1
-- animatable
Softens the effect of highlights formed by glancing light. .Extra_Lighting animatable
Color
default: (color 0 0 0) --
Adds light to the surface of objects with the Raytrace material. .translucency animatable
Color
default: (color 0 0 0) --
Creates a translucent effect. The Translucency color is a non-directional diffuse reflection. .Fluorescence animatable
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. .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. .Wire_Size percentage
Float
default: 100.0 -- animatable;
Sets the size of the wire in wireframe mode. .Color_Density_Enable
Boolean
default: false -- animatable
Turns on/off the color density controls. .Color_Density_Start
Float
default: 0.0
-- animatable
The position in the object where the density color begins to appear. .Color_Density_End
Float
default: 25.0
-- animatable
The position in the object where the density color reaches its full Amount value. .Color_Density_Amount Float
default: 1.0
-- animatable
The amount of density color. It can range from 0 to 1.0. Reducing this value reduces the density color effect. .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
.Fog_Enable
Boolean
default: false -- animatable
Turn on/off the use of density fog in the raytrace material. .Fog_Start
Float
default: 0.0
-- animatable
The position in the object where the density fog begins to appear. .Fog_End
Float
default: 25.0
-- animatable
The position in the object where the density fog reaches its full Amount value. .Fog_Amount
Float
default: 1.0
-- animatable
Controls the amount of density fog. It can range from 0 to 1.0. Reducing this value reduces the density fog effect and makes the fog translucent. .Fog_Color - animatable
Color
default: (color 255 255 255) -
Integer
default: 0
-- animatable
default: 0.5
-- animatable
The color of the density fog. .Reflection_Type
Set the type of reflection: Default (Reflections are layered with the diffuse color) Additive (Refelections are added to the diffuse color) .Reflection_Gain
Float
Controls reflection brightness. The lower the gain value, the brighter the reflection. At a gain of 1.0, no reflection is visible. .Enable_Raytraced_Reflections
Boolean
default: false
Boolean
default: true
Turns raytracing of reflective objects on or off. .Enable_Raytraced_Refractions
Turns raytracing of transparent objects on or off. .Reflection_Falloff_Mode animatable
Integer
default: 0
--
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 .Reflection_Falloff_End_Distance animatable
Float
default: 100.0 --
The distance in world units where the reflected ray is fully attenuated.
1215
1216
Chapter 11
|
3ds max Objects
.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 .Refraction_Falloff_End_Distance animatable
Float
default: 100.0 --
The distance in world units where the refracted ray is fully attenuated. .Bump_Map_Effect
Float
default: 1.0
-- animatable
Adjusts the effect of bump maps on raytraced reflections and refractions. .Override_Global_Antialiasing_Settings false -- animatable
Boolean
default:
If Override_Global_Antialiasing_Settings = false, Global Antialiasing Settings are used. If true, the antialiaser is determined by Adaptive_Antialiasing_On. .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 .Options___Raytracer_Enable - animatable
Boolean
default: true
-
Boolean
default: true
-
Boolean
default: true
-
Boolean
default: true
-
Turns the raytracer on or off. .Options___Antialiasing_Enable - animatable
Turns antialiasing on or off. .Options___Self_Reflect_Refract - animatable
Turns self reflection/refraction on or off. .Options___Raytrace_Atmospherics - animatable
Turns the raytracing of atmospheric effects on or off. Atmospheric effects include combustion, fog, volume light, and so on. .Options___Reflect_Refract_Material_ID_s true -- animatable
Boolean
default:
When on, the material reflects effects assigned to material IDs in the renderer’s G-Buffer. .Options___Raytrace_Objects_in_Glass true -- animatable
Turns the raytracing of objects inside raytraced objects on or off.
Boolean
default:
RayTraceMaterial : Material
.Options___Raytrace_Atmospherics_in_Glass true -- animatable
Boolean
default:
Turns the raytracing of atmospherics inside raytraced objects on or off. .Options___Color_Density___Fog_Enable true -- animatable
Boolean
default:
Turns the color density and fog features on or off. The following properties are associated with the Antialiaser configuration dialogs. .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. .Local_Min__Rays 4 -- animatable
Integer
default:
Integer
default:
Float
default:
The minimum number of rays that the algorithm casts. .Local_Max__Rays 32 -- animatable
The maximum number of rays the algorithm casts. .Local_Blur_Offset 0.0 -- animatable
The sharpness or blurriness of reflections or refractions without regard to distance. This value is specified in pixels. .Local_Blur_Aspect 1.0 -- animatable
Float
default:
Float
default:
Changes the shape of the blur by changing the aspect ratio. .Local_Defocus 0.0 -- animatable
Blurs based on distance. Objects near the surface are not blurred, but objects farther away are blurred. The rays cast are spread as they leave the surface of the raytrace map object. .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. .ambientMap undefined
TextureMap
default:
Float
default:
Boolean
default:
TextureMap
default:
The map assigned to the ambient map channel. .ambientMapAmount 100.0
The relative strength of the ambient map channel. .ambientMapEnable false
Turn on/off use of the ambient map channel. .bumpMap undefined
The map assigned to the bump map channel.
1217
1218
Chapter 11
|
3ds max Objects
.bumpMapAmount 100.0
Float
default:
Boolean
default:
TextureMap
default:
Float
default:
Boolean
default:
TextureMap
default:
Float
default:
Boolean
default:
TextureMap
default:
Float
default:
Boolean
default:
TextureMap
default:
Float
default:
Boolean
default:
The relative strength of the bump map channel. .bumpMapEnable false
Turn on/off use of the bump map channel. .diffuseMap undefined
The map assigned to the diffuse map channel. .diffuseMapAmount 100.0
The relative strength of the diffuse map channel. .diffuseMapEnable false
Turn on/off use of the diffuse map channel. .displacementMap undefined
The map assigned to the displacement map channel. .displacementMapAmount 100.0
The relative strength of the displacement map channel. .displacementMapEnable false
Turn on/off use of the displacement map channel. .reflectionMap undefined
The map assigned to the reflection map channel. .reflectionMapAmount 100.0
The relative strength of the reflection map channel. .reflectionMapEnable false
Turn on/off use of the reflection map channel. .refractionMap undefined
The map assigned to the refraction map channel. .refractionMapAmount 100.0
The relative strength of the refraction map channel. .refractionMapEnable false
Turn on/off use of the refraction map channel.
RayTraceMaterial : Material
.glossinessMap undefined
TextureMap
default:
The map assigned to the glossiness map channel. . glossinessMapAmount
Float
default: 100.0
The relative strength of the glossiness map channel. . glossinessMapEnable
Boolean
default: false
Turn on/off use of the glossiness map channel. .specularLevelMap lt: undefined
TextureMap
defau
Float
defau
Boolean
defau
TextureMap
default:
Float
default:
Boolean
default:
The map assigned to the specularLevel map channel. .specularLevelMapAmount lt: 100.0
The relative strength of the specularLevel map channel. .specularLevelMapEnable lt: false
Turn on/off use of the specularLevel map channel. .luminosityMap undefined
The map assigned to the luminosity map channel. .luminosityMapAmount 100.0
The relative strength of the luminosity map channel. .luminosityMapEnable false
Turn on/off use of the luminosity map channel. .transparencyMap t: undefined
TextureMap
defaul
Float
defaul
Boolean
defaul
The map assigned to the transparency map channel. .transparencyMapAmount t: 100.0
The relative strength of the transparency map channel. .transparencyMapEnable t: false
Turn on/off use of the transparency map channel. .environmentMap : undefined
TextureMap
default
Float
default
The map assigned to the environment map channel. .environmentMapAmount : 100.0
The relative strength of the environment map channel.
1219
1220
Chapter 11
|
3ds max Objects
.environmentMapEnable : false
Boolean
default
Turn on/off use of the environment map channel. .transEnvMap undefined
TextureMap
default:
Float
default:
Boolean
default:
The map assigned to the transEnv map channel. .transEnvMapAmount 100.0
The relative strength of the transEnv map channel. .transEnvMapEnable false
Turn on/off use of the transEnv map channel. .iorMap undefined
TextureMap
default:
Float
default: 100.0
Boolean
default: false
The map assigned to the ior map channel. .iorMapAmount
The relative strength of the ior map channel. .iorMapEnable
Turn on/off use of the ior map channel. .translucencyMap t: undefined
TextureMap
defaul
Float
defaul
Boolean
defaul
The map assigned to the translucency map channel. .translucencyMapAmount t: 100.0
The relative strength of the translucency map channel. .translucencyMapEnable t: false
Turn on/off use of the translucency map channel. .extraLightingMap lt: undefined
TextureMap
defau
Float
defau
Boolean
defau
The map assigned to the extraLighting map channel. .extraLightingMapAmount lt: 100.0
The relative strength of the extraLighting map channel. .extraLightingMapEnable lt: false
Turn on/off use of the extraLighting map channel. .flourescenceMap t: undefined
TextureMap
defaul
Float
defaul
The map assigned to the flourescence map channel. .flourescenceMapAmount t: 100.0
The relative strength of the flourescence map channel.
RayTraceMaterial : Material
.flourescenceMapEnable t: false
Boolean
defaul
TextureMap
defaul
Float
defaul
Boolean
defaul
Turn on/off use of the flourescence map channel. .colorDensityMap t: undefined
The map assigned to the colorDensity map channel. .colorDensityMapAmount t: 100.0
The relative strength of the colorDensity map channel. .colorDensityMapEnable t: false
Turn on/off use of the colorDensity map channel. .fogColorMap undefined
TextureMap
default:
Float
default:
Boolean
default:
The map assigned to the fogColor map channel. .fogColorMapAmount 100.0
The relative strength of the fogColor map channel. .fogColorMapEnable false
Turn on/off use of the fogColor map channel. .diffusionMap undefined
TextureMap
default:
Float
default:
Boolean
default:
The map assigned to the diffusion map channel. .diffusionMapAmount 100.0
The relative strength of the diffusion map channel. .diffusionMapEnable false
Turn on/off use of the diffusion map channel. .specularMap undefined
TextureMap
default:
Float
default:
Boolean
default:
The map assigned to the specular color map channel. .specularMapAmount 100.0
The relative strength of the specular color map channel. .specularMapEnable false
Turn on/off use of the specular color map channel.
1221
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. .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. .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. .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). .Attenuation_Start
Float
default: 0.0
Float
default: 2.0
Integer
default: 0
The distance in world units where attenuation begins. .Attenuation_Exponent
The distance in world units where the ray is fully attenuated. .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 scene’s background or the background specified locally in the Raytracer Parameters rollout) rather than the actual color of what the reflected/refracted ray sees.) Use Attenuation_Color .Attenuation_Color (color 0 0 0)
Color
default:
The color used for attenuation. .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. .Attenuation_Control_1
Float
default: 0.6666
Float
default: 0.3333
Float
default: 0.0
Controls the shape of the curve near the curve start. .Attenuation_Control_2
Controls the shape of the curve near the curve end. .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
.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. .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. .Enable_Reflection_Falloff false
Boolean
default:
Turns on/off falloff of reflection. .Reflection_Falloff_Distance
Float
default: 0.0
Boolean
default: false
Float
default: 0.0
The distance until the reflections are fully attenuated. .Enable_Refraction_Falloff
Turns on/off falloff of refraction. .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)
1223
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:
String
default: “Blinn” -- alias:
Sets the shader type: Anisotropic Blinn Metal Multi-Layer Oren-Nayar-Blinn Phong Strauss <Standard>.shaderByName Shader_Name
Sets the type of shader with a string, rather than a number. Enter “anisotropic”, “blinn”, “metal”, “multi-layer”, “oren-nayar-blinn”, “phong”, or “strauss”. Note: The .shaderType and .shaderByName are linked and will automatically change each others values. <Standard>.wire
Boolean
default: false
When on, the material will be rendered in wireframe mode. <Standard>.twoSided Two_sided
Boolean
default: false
-- alias:
When on, the material will be applied to both sides of the selected faces. <Standard>.faceMap Face_Map
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
Boolean
default: false
Renders each face of a surface as if it were flat. <Standard>.adTextureLock Ambient_Diffuse_Texture_Lock
Boolean
default: false
When on, ambient and diffuse texture maps will be locked.
-- alias:
StandardMaterial : Material
<Standard>.adLock Ambient_Diffuse_Lock
Boolean
default: false
-- alias:
Integer
default: 0
-- alias:
Float
default: 100.0
-- animatable,
When on, ambient and diffuse colors will be locked. <Standard>.opacityType Opacity_Type
Sets the type of opacity: Filter Subtractive Additive <Standard>.opacity percentage
Sets the opacity/transparency of the material as a percentage. <Standard>.filterColor Color 127.5) -- animatable, alias: Filter_Color
default: (color 127.5 127.5
The color transmitted through transparent or semi-transparent materials such as glass. <Standard>.opacityFallOffType Falloff_Type
Integer
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
Float
default: 0.0
-- animatable,
Specifies the amount of transparency at the outside or inside extreme. <Standard>.ior alias: Index_of_Refraction
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
Float
default: 1.0
-- animatable,
default: 0
-- alias:
default: false
-- alias:
Sets the size of the wire in wireframe mode. <Standard>.wireUnits Wire_Units
Integer
Sets the unites to use with the .wiresize value: Pixels Units <Standard>.applyReflectionDimming Apply_Reflection_Dimming
Boolean
Turn on to use reflection dimming. When off, the reflection-mapped material is not affected by the presence or absence of direct light.
1225
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
Boolean
default: false
-- animatable,
default: true
-- alias:
When on, applies supersampling to the material. <standard>.subSampleTextureOn SubSample_Textures
Boolean
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
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
default: 0.0
-- alias:
Float
default: 0.0
-- 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 material’s maps. The maps array stores the textureMap for each channel, the mapEnables array stores whether the that map channel is enabled, and the mapAmounts array stores the amount value for each channel. The meaning of each map channel depends on the shaderType value. Table Map Channels for Standard Material Shaders (p. 1232) shows the meaning of each map channel for each shader. For example, for the Blinn shader type element 5 of the map arrays correspond to the Glossiness map channel. The names in this table also reflect property aliases that have been defined for easier access to the map channels. Again for the Blinn shader type, array element 4, the property aliases for the 3 map arrays are: GlossinessMap (maps[5]), GlossinessMapEnable (mapEnables[5]), and GlossinessMapAmount (mapAmounts[5]). A textureMap needs to be assigned to a maps array element (or alias) before the corresponding mapAmounts property (or alias) can be animated. The following properties are associated with the Dynamics Properties rollout. These properties are not present in 3D Studio VIZ. <Standard>.bounce 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.
1227
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
default: (color 25.5 25.5 25.5) --
Controls the ambient color. The ambient color is the color in direct light. <Standard>.diffuse Color animatable, alias: Diffuse_Color
default: (color 127.5 127.5 127.5) --
Controls the diffuse color. The diffuse color is the color in direct light. <Standard>.specular Color animatable, alias: Specular_Color
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
Boolean
default: false
-- alias:
When on, the diffuse and specular colors are linked together. <Standard>.useSelfIllumColor Use_Self_Illumination
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
Float
default: 0.0
-- animatable, percentage,
Sets the amount of self-illumination. <Standard>.selfIllumColor alias: Self_Illum_Color
Color
default: (color 0 0 0) -- animatable,
Sets a separate color to use for self-illumination. <Standard>.specularLevel alias: Specular_Level
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
<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 material’s 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 material’s diffuse component. Increasing this value increases diffuse brightness, and decreasing it reduces diffuse brightness without affecting the specular highlight. <Standard>.anisotropy
Float
default: 50.0
-- animatable, percentage
Controls the anisotropy, or shape, of the highlight. At 0, the highlight is round. At 100, the highlight is extremely narrow. <Standard>.orientation
Float
default: 0.0
-- animatable, percentage
Changes the orientation of the highlight. <Standard>.unused
Integer
default: 1
the unused property is defined but not used by the shader Shader Type: Multi-Layer <Standard>.ambient Color animatable, alias: Ambient_Color
default: (color 25.5 25.5 25.5) --
Controls the ambient color. The ambient color is the color not in direct light. <Standard>.diffuse Color animatable, alias: Diffuse_Color
default: (color 127.5 127.5 127.5) --
Controls the diffuse color. The diffuse color is the color in direct light. <Standard>.useSelfIllumColor Use_Self_Illumination
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.
1229
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
Color
default: (color 0 0 0) -- animatable,
Sets an alternate color to use for self-illumination. <Standard>.diffuseLevel alias: Diffuse_Level
Float
default: 100.0
-- animatable, percentage,
Controls the brightness of the material’s diffuse component. Increasing this value increases diffuse brightness, and decreasing it reduces diffuse brightness without affecting the specular highlight. <Standard>.diffuseRoughness 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 color’s 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 color’s 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 color’s 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 color’s highlight. At 0, the highlight is round. At 100, the highlight is extremely narrow. <Standard>.orientation
Float
default: 0.0
-- animatable, percentage
Changes the orientation of the first color’s highlight. <Standard>.specular2 animatable, alias: Color_2
Color
default: (color 229.5 229.5 229.5) --
Affects the intensity of the second color’s 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 color’s specular highlight. As you increase the value, the highlight grows brighter.
StandardMaterial : Material
<Standard>.glossiness2 alias: Glossiness_2
Float
default: 25.0
-- animatable, percentage,
Affects the size of the second color’s specular highlight. As you increase the value, the highlight gets smaller and the material appears shinier. <Standard>.anisotropy2 Anisotropy_2
Float
default: 0.0
-- animatable, alias:
Controls the anisotropy, or shape, of the second color’s highlight. At 0, the highlight is round. At 100, the highlight is extremely narrow. <Standard>.orientation2
Float
default: 0.0
-- animatable, percentage
Changes the orientation of the second color’s highlight. Shader Type: Strauss <Standard>.diffuse Color 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)
1231
1232
Chapter 11
|
3ds max Objects
Map Channels for Standard Material Shaders Anisotropic
Blinn
Metal
Multi-Layer
Oren-NayarBlinn
Phong
Strauss
1
AmbientMap
AmbientMap
AmbientMap
AmbientMap
AmbientMap
AmbientMap
DiffuseMap
2
DiffuseMap
DiffuseMap
DiffuseMap
DiffuseMap
DiffuseMap
DiffuseMap
GlossinessMap
3
SpecularMap
SpecularMap
SpecularMap
DiffuseLevelMap SpecularMap
SpecularMap
MetalnessMap
4
DiffuseLevel Map
SpecularLevel Map
SpecularLevel Map
Diffuse RoughnessMap
GlossinessMap
SpecularLevel Map
OpacityMap
5
SpecularLevel Map
GlossinessMap
GlossinessMap
SpecularMap
SpecularLevel Map
GlossinessMap
FilterMap
6
Glossiness Map SelfIllumMap
SelfIllumMap
SpecularLevel Map
SelfIllumMap
SelfIllumMap
BumpMap
7
Anisotropy Map
OpacityMap
GlossinessMap
OpacityMap
OpacityMap
ReflectionMap
8
OrientationMap FilterMap
FilterMap
AnisotropyMap
FilterMap
FilterMap
RefractionMap
9
SelfIllumMap
BumpMap
BumpMap
OrientationMap DiffuseLevelMap BumpMap
10
OpacityMap
ReflectionMap
ReflectionMap
specularMap2
Diffuse RoughnessMap
ReflectionMap
11
FilterMap
RefractionMap
RefractionMap
SpecularLevel Map2
BumpMap
RefractionMap
12
BumpMap
Displacement Map
Displacement Map
GlossinessMap2 ReflectionMap
13
ReflectionMap
AnisotropyMap2 RefractionMap
14
RefractionMap
Orientation Map2
15
Displacement Map
SelfIllumMap
OpacityMap
16
OpacityMap
17
FilterMap
18
BumpMap
19
ReflectionMap
20
RefractionMap
21
Displacement Map
Displacement Map
Displacement Map
Displacement Map
Shellac : Material
Shellac : Material Constructor: Shellac ...
Properties: <Shellac>.shellacMtl1
Material
default: Standard
-- alias: Base_Material
Material
default: Standard
-- 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: .topMaterial Top______Standard
Material
default: Standard
-- alias:
Material
default: Standard
-- alias:
Boolean
default: true
-- alias: Map_1_Enable
The top material. .bottomMaterial Bottom______Standard
The bottom material. .map1Enabled
Turns on/off the use of the top material in the topbottom material. .map2Enabled
Boolean
default: true
-- alias: Map_2_Enable
Turns on/off the use of the bottom material in the topbottom material.
1233
1234
Chapter 11
|
3ds max Objects
.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. .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. .coordinates
Integer
default: 0
Choose how the software determines the boundary between top and bottom: World (Faces point up or down according to the scene’s world coordinates. When you rotate the object, the boundary between top and bottom faces remains in place.) Local (Faces point up or down according to the object’s local coordinates. When you rotate the object, the material rotates with it.)
See also Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
TextureMap : Material The TextureMap class represents the 2D and 3D texture maps which you can assign to materials or certain object properties in 3ds max. You can create texture maps like bitmap, dent, and swirl, access various properties on them, and assign these texture maps to materials and to certain 3ds max object properties. The classes derived directly from the TextureMap class are described in the TextureMap Types (p. 1240) topic. The properties, operators, and methods that are common to all classes derived directly from the TextureMap class are described in the TextureMap Common Properties, Operators, and Methods (p. 1235) topic. TextureMaps also share a set of classes for properties that are used in several different TextureMap classes. These shared classes are described in the TextureMap Shared Classes (p. 1236) topic. The TextureMap class is derived from the Material class, and inherits the properties and methods defined for that class. These properties and methods are described in the Material Common Properties, Operators, and Methods (p. 1203) topic.
TextureMap Common Properties, Operators, and Methods
TextureMap Common Properties, Operators, and Methods Properties: .name
All the TextureMap subclasses can access the name property and specify it as a constructor parameter. Methods: assignNewName
Modifies the name of the specified texture to make it unique. The name is of the form “Map #1” where the number is incremented as required to make ensure it’s unique. renderMap [ [ [ [ [ [
into: ] size:<point2> ] filename:<string> ] scale: ] filter: ] display: ]
\ \ \ \ \
Provides access the Render Map function available in the Material Editor. The function returns a Bitmap value containing a rendering of the given texture map. If you specify the optional into: argument, the function renders the map into the supplied bitmap, taking size and other attributes from the existing bitmap. If you don’t, a new bitmap value is created using the size: and fileName: arguments in its creation. Default size value is [200,200]. The scale: argument is a scale factor applied to 3D TextureMaps. This is the scale of the surface in 3d space that is mapped to UV and controls how much of the texture appears in the bitmap representation. Default scale value is 1. If the filter: argument is true, the bitmap is filtered. It is quite a bit slower to rescale bitmaps with filtering on. Defaults filter value is false/off. If the display: argument is true, the resulting bitmap is displayed using the virtual frame buffer; otherwise it is not. Default display value is false/off. Example: rm = renderMap $foo.material.diffuseMap size:[640,480] \ fileName:”foodif.bmp” save rm close rm
The above will render a map to a bitmap and save it as a .bmp file.
1235
1236
Chapter 11
|
3ds max Objects
Associated Methods: showTextureMap <material>
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
UVGenClass : Material Properties: .mappingType
Integer
default: 0
mappingType = 0 - Texture; 1 - Environment If the Coordinates rollout for the textureMap is displayed in Material Editor and this property’s value is changed, the Texture/Environ radiobutton and Mapping dropdown displays are not updated to reflect the change. .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. .mapChannel
Integer
default: 1
Float Float
default: 0.0 default: 0.0
The UV coordinate map channel. .U_Offset .V_Offset
-- animatable -- animatable
Offset mapping coordinates along the surface’s local U axis or V axis. That is, at 0.0 (the default), the map begins at the U or V origin. Increasing an Offset value moves the map forward along that axis, and decreasing it moves it backward. .U_Tiling .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 material’s map is repeated in the surface’s local U axis or V axis. .U_Angle
Float
default: 0.0
-- animatable, angle
default: 0.0
-- animatable, angle
default: 0.0
-- animatable, angle
default: 1.0
-- animatable
Rotates the map about the U-axis (in degrees). .V_Angle
Float
Rotates the map about the V-axis (in degrees). .W_Angle
Float
Rotates the map about the W-axis (in degrees). .Blur
Float
Affects the sharpness or blurriness of the map based on its distance from the view. The farther away the map is, the greater the blurring. The Blur value blurs maps in world space. .Blur_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.
1237
1238
Chapter 11
|
3ds max Objects
.Phase
Float
default: 0.0
-- animatable
default: 1.0
-- animatable
The speed of the animation of the noise function. .Noise_Amount
Float
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. .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. .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: .coordType
Integer
default: 0
The type of coordinates used for mapping: Object XYZ (Uses planar mapping based on the object’s local coordinates (disregarding the pivot point location).) World XYZ (Uses planar mapping based on the scene’s world coordinates (disregarding the object’s bounding box).) Explicit Map Channel (Uses the map channel specified by the .mapChannel value.) Vertex Color Channel (Uses assigned vertex colors as a channel.) .mapChannel
Integer
default: 1
The map channel used for mapping coordinates. .offset
Point3
default: [0,0,0]
-- animatable
Changes the position of the map in UV coordinates. The map moves in relation to its size. .Tiling
Point3
default: [1,1,1]
The number of times the map is tiled across each axis.
-- animatable
TexOutputClass : Material
.angle angle
Point3
default: [0,0,0]
-- animatable, point3
Rotates the map about the U, V, and W-axis (in degrees). .blur
Float
default: 1.0
-- animatable
Affects the sharpness or blurriness of the map based on its distance from the view. The farther away the map is, the greater the blurring. The Blur value blurs maps in world space. .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: .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. .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. .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. .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. .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. .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.
1239
1240
Chapter 11
|
3ds max Objects
.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. .curve_1 .curve_2 .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
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: .blur animatable, percentage .Foreground_Color 0) -- animatable
Float
default: 0.0
--
Color
default: (color 0 0
Specifies the foreground color for the image, used by some Photoshop filters. .Background_Color 0) -- animatable
Color
default: (color 0 0
Specifies the background color for the image, used by some Photoshop filters.
1241
1242
Chapter 11
|
3ds max Objects
.coordinates
SubAnim
See the UVGenClass (p. 1237) topic for the StandardUVGen properties. .output
StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties. Note: The following properties are not accessible by MAXScript in 3ds max 4: the Use Alpha Plane checkbox in the Parameters rollout, and all properties in the Bitmap Parameters and Time Parameters rollouts.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Adobe_Premiere_Video_Filter : TextureMap Constructor: adobe_premiere_video_filter ...
Note: This class is not available in 3D Studio VIZ. Properties: .coordinates
SubAnim
See the UVGenClass (p. 1237) topic for the StandardUVGen properties. .output
StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties. Note: The following properties are not accessible by MAXScript in 3ds max 4: all properties in the Time Parameters rollout.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
BitmapTexture : TextureMap
BitmapTexture : TextureMap Constructor: bitmaptexture ... bitmaptex ...
Properties: .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. .filename
String
default: ““
Integer
default: 0
-- alias: file_name
The name of the bitmap file. .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.) .monoOutput
Integer
default: 0
Some parameters, such as opacity or specular level are a single value as opposed to a material’s three-value color components. Controls in this group determine the source of the Output mono channel in terms of the input bitmap: RGB Intensity (Uses the intensity of the red, green, and blue channels for mapping. The color of the pixels is ignored and only the value or luminance of the pixels is used. The colors are computed as gray values in the range between 0 (black) and 255 (white).) Alpha (Uses the intensity of the alpha channel for mapping.) .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.) .apply
Boolean
default: false
Turn on to use the cropping or placements settings. .cropPlace
Integer
default: 0
Set whether cropping or placement is active: Crop Place
1243
1244
Chapter 11
|
3ds max Objects
.clipu clip_u_offset
Float
default: 0.0
-- animatable, alias:
Adjusts the bitmap location along the U-axis. .clipv clip_v_offset
Float
default: 0.0
-- animatable, alias:
Adjusts the bitmap location along the V-axis. .clipw clip_u_width
Float
default: 1.0
-- animatable, alias:
default: 1.0
-- animatable, alias:
default: 1.0
-- animatable, alias:
Adjusts the width of the bitmap. .cliph clip_v_width
Float
Adjusts the height of the bitmap. .jitter jitter_placement
Float
The amount of random offset. At 0, there is no random offset. .alphasource
Integer
default: 0
Controls in this group determine the source of the Output alpha channel in terms of the input bitmap: Image Alpha (Uses the image’s alpha channel.) RGB Intensity (Converts the colors in the bitmap to grayscale tonal values and uses them for transparency. Black is transparent and white is opaque.) None (Opaque; does not use transparency.) .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. .starttime
Timedefault: 0f
The frame where the playback of the animated map will begin. .playbackrate
Float
default: 1.0
Lets you speed up and slow down the rate that the animation is applied to the map (for example, 1.0 is normal speed, 2.0 is twice as fast, .333 is 1/3 as fast). .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.) .coords
StandardUVGen
-- alias: coordinates
See the UVGenClass (p. 1237) topic for the StandardUVGen properties.
Bricks : TextureMap
.output
StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties. Associated Methods: enumerateFiles [ <MAXWrapper_obj> ] [ <arg> ] [ #inactive ] [ #videoPost ] [ #render ] [ #missing ] [ #localOnly ]
\ \
Lets you run through all the bitmap files currently used in the scene or in an individual object. You can filter this so it just gives you the bitmap files that are inactive or missing. See the Bitmap Files (p. 1641) topic for a description of this method’s parameters. freeSceneBitmaps()
Frees up all the memory used by the image file bitmap caches. This is useful if memory is fragmented with a lot of different bitmaps and you want to have just the ones currently active reloaded.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Bricks : TextureMap Constructor: bricks ...
Properties: .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. .Show_Texture_Swatches
Integer
default: 1
When on, updates to show the texture assigned by a map for Bricks or Mortar. OFF ON .Brick_Color animatable
Color
default: (color 165.75 76.5 51)
Float
default: 3.0
The color of the bricks. .Horizontal_Count
The number of bricks in a row.
-- animatable
--
1245
1246
Chapter 11
|
3ds max Objects
.Vertical_Count
Float
default: 8.0
-- animatable
default: 0.4
-- animatable
default: 0.2
-- animatable
The number of bricks in a column. .Color_Variance
Float
The color variation among the bricks. .Fade_Variance
Float
The fading variation among the bricks. .Mortar_Color animatable
Color
default: (color 211.65 196.35 183.6)
Float
default: 1.0
--
The color of the mortar. .Horizontal_Gap
-- animatable
The horizontal size of the mortar between the bricks. .Vertical_Gap
Float
default: 1.0
-- animatable
The vertical size of the mortar between the bricks. .Lock_Gap_Symmetry
Integer
default: 1
When on, the vertical_gap and horizontal_gap values are locked to one another. Off On .Holes
Integer
default: 0
-- animatable
The percentage of holes in the bricked surface caused by missing bricks. The mortar shows through the holes. .Edge_Roughness
Float
default: 0.0
-- animatable
Controls the roughness of the edges of the mortar. .Random_Seed
Integer
default: 43304
-- animatable
Randomly applies patterns of color variation to the bricks. Does not require any other setting to generate completely different patterns. .Line_Shift
Float
default: 0.0
-- animatable
Shifts every second row of bricks a distance of one unit. .Random_Shift
Float
default: 0.0
-- animatable
Randomly shifts all rows of bricks a distance of one unit. .Use_Row_Edit
Integer
default: 0
Integer
default: 2
Float
default: 1.0
Turn on/off row edit: Off On .Per_Row
The amount of bricks per row. .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
.Use_Column_Edit
Integer
default: 0
Turn on/off column edit: OFF ON .Per_Column
Float
default: 1.0
The amount of bricks per column. .Change_Column
Float
default: 1.0
For every row you specify in the Per_Column value, the software stores the amount of bricks that you specify in the Change_column value. .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: .celcolor alias: Cell_Color
Color
default: (color 255 255 255) -- animatable,
textureMap
default: undefined
The color of the cell. .cellmap
Assigns a map to the cells, rather than a solid color.
1247
1248
Chapter 11
|
3ds max Objects
.map1Enabled
Boolean
default: true
-- alias: Map1_On
When on, enables the map. When off, disables the map (cell color reverts to celcolor). .variation
Float
default: 0.0
-- animatable
Varies the color of the cells by randomly altering RGB values. The higher the variation, the greater the random effect. This percentage value can range from 0 to 100. At 0, the color swatch or the map completely determines the cell color. .divcolor1 Color animatable, alias: Division_Color1
default: (color 127.5 127.5 127.5) --
The color of the first cell division. .divmap1
textureMap
default: undefined
-- alias: DivisionMap1
Assigns a map to the first cell division. .map2Enabled
Boolean
default: true
-- alias: Map2_On
When on, enables the first cell division map. When off, disables the associated map (the division color reverts to divcolor1). .divcolor2 Division_Color2
Color
default: (color 0 0 0) -- animatable, alias:
The color of the second cell division. .divmap2
textureMap
default: undefined
-- alias: DivisionMap2
Assigns a map to the second cell division. .map3Enabled
Boolean
default: true
-- alias: Map3_On
When on, enables the second cell division map. When off, disables the associated map (the division color reverts to divcolor2). .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.) .size
Float
default: 5.0
-- animatable
Alters the overall scale of the map. Adjust this value to fit the map to your geometry. .spread
Float
default: 0.5
-- animatable
default: 0.1
-- animatable, alias:
Alters the size of individual cells. .smooth Bump_smoothing
Float
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. .fractal
Boolean
default: false
When on, makes the cellular pattern a fractal pattern. .iteration Iterations
Float
default: 3.0
-- animatable, alias:
Sets the number of times the fractal function is applied. Caution: Increasing this value increases rendering time.
Checker : TextureMap
.adaptive
Boolean
default: true
When on, the number of fractal iterations is set adaptively. That is, the number of iterations increases the closer the geometry is to the scene’s point of view, and decreases in the distance. This reduces aliasing and also saves time while rendering. .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. .lowthresh .midthresh .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. .coords
StandardXYZGen
-- alias: coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties. .output
StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Checker : TextureMap Constructor: checker ...
Properties: .soften
Float
default: 0.0
-- animatable
Blurs the edges between the checkers. A little blurs a lot. .color1 Color_1
Color
default: (color 0 0 0) -- animatable, alias:
Sets the color of one of the checkers.
1249
1250
Chapter 11
|
3ds max Objects
.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. .map1Enabled
Boolean
default: true
-- alias: Map_1_Enable
This enables the associated map. .color2 alias: Color_2
Color
default: (color 255 255 255) -- animatable,
Sets the color of the second checker. .map2
textureMap
default: undefined
-- alias: Map_2
Selects a map to use within the area of the checker color. For example, you could put an additional checkerboard within one of the checker colors. .map2Enabled
Boolean
default: true
-- alias: Map_2_Enable
This enables the associated map. .coords
StandardUVGen
-- alias: coordinates
See the UVGenClass (p. 1237) topic for the StandardUVGen properties.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
CompositeTextureMap : TextureMap Constructor: compositeTextureMap ... compositeTexture ...
Properties: .mapList undefined) -- alias: Maps .mapEnabled alias: Map_1_Enable
ArrayParameter
default: #(undefined,
ArrayParameter
default: #(true, true) --
Dent : TextureMap
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: .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. .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. .iterations
Integer
default: 2
-- animatable
Sets the number of calculations used to create the dents. .color1 Color_1
Color
default: (color 0 0 0) -- animatable, alias:
Sets the color of the dent. .map1
TextureMap
default: undefined
Colors can be replaced by maps in the dent pattern. .map1Enabled
Boolean
Enables the associated map.
default: true
-- alias: MapOn1
1251
1252
Chapter 11
|
3ds max Objects
.color2 alias: Color_2
Color
default: (color 255 255 255)
-- animatable,
Sets the second color of the dent. .map2
TextureMap
default: undefined
Assigns second map to the dent pattern. .map2Enabled
Boolean
default: true
-- alias: MapOn2
Enables the associated map. .coords
StandardXYZGen
-- alias: coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Falloff : TextureMap Constructor: falloff ...
Properties: .color1 Color_1
Color
default: (color 0 0 0) -- animatable, alias:
Sets the first color for falloff. .map1Amount Map_Amount_1
Float
default: 100.0
-- animatable, alias:
Relative strength of the first color in the falloff map. .map1
TextureMap
default: undefined
-- alias: Map_1
Assigns a map to the first slot in the falloff. .map1On
Boolean
default: true
-- alias: Map_1_Enable
When on, the selected maps are used in the falloff. When off, colors are used. .color2 alias: Color_2
Color
default: (color 255 255 255) -- animatable,
Sets the second color for falloff. .map2Amount Map_Amount_2
Float
default: 100.0
-- animatable, alias:
Relative strength of the second color in the falloff map. .map2
TextureMap
default: undefined
-- alias: Map_1
Assigns a map to the second slot in the falloff. .map2On
Boolean
default: true
-- alias: Map_2_Enable
When on, the selected maps are used in the falloff. When off, colors are used.
Falloff : TextureMap
.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.) .mtlIOROverride Mtl_IOR_Override_Enable
Boolean
default: true
-- alias:
When on, allows change to the Index of Refraction set by the material. .ior Index_of_Refraction
Float
default: 1.6
-- animatable, alias:
default: 0.0
-- animatable, alias:
Sets a new Index of Refraction. .nearDistance Near_Distance
Float
The distance at which the blend effect begins. Note: This is only available for the Distance Blend falloff type. .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. .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. .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 doesn’t affect the falloff map.)
1253
1254
Chapter 11
|
3ds max Objects
Object ( Picks an object whose orientation determines the falloff direction, .node. The falloff direction is the direction from the point being shaded toward the object’s center. Points on the side toward the object center get the Towards value, and those away from the object get the Away value.) Local X Axis (Sets the falloff direction to the object’s local X-axis. Changing the orientation of the object changes the falloff direction. When no object is chosen, the falloff direction uses the local X-axis of the object being shaded.) Local Y Axis (Sets the falloff direction to the object’s local Y-axis. Changing the orientation of the object changes the falloff direction. When no object is chosen, the falloff direction uses the local Y-axis of the object being shaded.) Local Z Axis (Sets the falloff direction to the object’s local Z-axis. Changing the orientation of the object changes the falloff direction. When no object is chosen, the falloff direction uses the local Z-axis of the object being shaded.) World X Axis (Sets the falloff direction to the world coordinate system X-axis. Changing object orientation doesn’t affect the falloff map.) World Y Axis (Sets the falloff direction to the world coordinate system Y-axis. Changing object orientation doesn’t affect the falloff map.) World Z Axis (Sets the falloff direction to the world coordinate system Z-axis. Changing object orientation doesn’t affect the falloff map.) .node Falloff_Direction_Object
Node
default: undefined
-- alias:
When Falloff_Direction = 1, this object will determine the falloff direction. .texture_output
StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties. .mixcurve
SubAnim
default: SubAnim:MixCurve
This mix curve determines the falloff. .curve_1
SubAnim
default: SubAnim:Curve_1
The curve_1 SubAnim contains the mix curve points. You cannot create or access these points unless the point is animated. If a point is animated, you can access the point position using the .Point_X property of curve_1, where X in the point number.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
FalloffTextureMap : TextureMap
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: .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. .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. .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. .nthFrame .useEnviroment
Integer Boolean
default: 1 default: true
When off, environment maps are ignored by the mirror during rendering. It’s useful to turn this off when you have mirrors in the scene and you’re rotoscoping against a flat screen environment map. A screen environment map does not exist in 3D space the way the other environment-map types do, and will not render properly. .applyToFaceID
Boolean
default: false
When on, a specified material is applied to the mirror face. .faceID
Integer
default: 1
Specifies the material ID number where you want the mirror assigned.
1255
1256
Chapter 11
|
3ds max Objects
.distortionType
Integer
default: 0
To simulate irregular surfaces, you can distort the flat-mirror reflections. Distortion can be based on a bump map or on noise controls built into Flat Mirror material. None (No distortion) Use Bump Map (Distorts the reflection using the material’s bump map. A flat mirror surface that has a Bump map will appear bumpy, but its reflection won’t be distorted by the bumps unless you use this option.) Use Built-in Noise (Distorts the reflection using the settings in the Noise group.) .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.) .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. .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. .size
Float
default: 10.0
-- animatable
Sets the scale of the noise function. Smaller values give smaller chunks of noise. .level
Float
default: 2.0
-- animatable
Sets the number of fractal iterations or turbulence (as a continuous function).
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Gradient : TextureMap
1257
Gradient : TextureMap Constructor: gradient ...
Properties: .color1 alias: Color_1
Color
default: (color 0 0 0) -- animatable,
The gradient interpolates between 3 colors. This is the first color. .map1
TextureMap
default: undefined
-- alias: Map_1
You can interpolate between 3 maps instead of colors. This is the first map. .map1Enabled Map_1_Enable
Boolean
default: true
-- alias:
When on, the associated map is enabled. .color2 animatable, alias: Color_2
Color
default: (color 127.5 127.5 127.5) --
The gradient interpolates between 3 colors. This is the second color. .map2
TextureMap
default: undefined
-- alias: Map_2
You can interpolate between 3 maps instead of colors. This is the second map. .map2Enabled Map_2_Enable
Boolean
default: true
-- alias:
When on, the associated map is enabled. .color3 - animatable, alias: Color_3
Color
default: (color 255 255 255)
-
The gradient interpolates between 3 colors. This is the third color. .map3
TextureMap
default: undefined
-- alias: Map_3
You can interpolate between 3 maps instead of colors. This is the third map. .map3Enabled Map_3_Enable
Boolean
default: true
-- alias:
default: 0.5
-- animatable,
When on, the associated map is enabled. .color2Pos alias: Color_2_Position
Float
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. .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.) .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
.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.) .noiseSize alias: Noise_Size
Float
default: 1.0
-- animatable,
Scales the noise function. Smaller values give smaller chunks of noise. .noisePhase alias: Noise_Phase
Float
default: 0.0
-- animatable,
Controls the speed of the animation of the noise function. A 3D noise function is used for the noise. The first two parameters are U and V and the third is phase. .noiseLevels alias: Noise_Levels
Float
default: 4.0
-- animatable,
Sets the number of fractal iterations or turbulence (as a continuous function). .noiseThresholdLow alias: Low_Threshold .noiseThresholdHigh alias: High_Threshold .noiseThresholdSMooth alias: Threshold_Smoothing
Float
default: 0.0
-- animatable,
Float
default: 1.0
-- animatable,
Float
default: 0.0
-- 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. .coords coordinates
StandardUVGen
-- alias:
See the UVGenClass (p. 1237) topic for the StandardUVGen properties. .output
StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.
Gradient_Ramp : TextureMap
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_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.) .Source_Map_On
Integer
When on, assigns a map to a mapped gradient. OFF ON
default: 1
1259
1260
Chapter 11
|
3ds max Objects
.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.) .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. .size
Float
default: 1.0
-- animatable
Sets the scale of the noise function. Smaller values give smaller chunks of noise. .phase
Float
default: 0.0
-- animatable
Controls the speed of the animation of the noise function. A 3D noise function is used for the noise; the first two parameters are U and V and the third is phase. .Levels
Float
default: 4.0
-- animatable
Sets the number of fractal iterations or turbulence (as a continuous function). .Low_Threshold .High_Threshold
Float Float
default: 0.0 default: 1.0
-- animatable -- animatable
When the noise value is above the Low threshold and below the High threshold, the dynamic range is stretched to fill 0 to 1. This causes a smaller discontinuity at the threshold transition and produces less potential aliasing. .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. .coordinates
SubAnim
See the UVGenClass (p. 1237) topic for the StandardUVGen properties. .output
StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties. .gradient_ramp SubAnim .flag__1 SubAnim .flag__2 SubAnim .flag__3 SubAnim .color Point3 animatable .color Point3 animatable .color Point3 animatable .position Float animatable
default: [255,0,0]
--
default: [0,0,255]
--
default: [0,255,0]
--
default: [0,255,0]
--
Marble : TextureMap
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Marble : TextureMap Constructor: marble ...
Properties: <Marble>.size
Float
default: 70.0
-- animatable
Sets the spacing between the veins. <Marble>.width Vein_width
Float
default: 0.025
-- animatable, alias:
Sets the width of the veins. <Marble>.color1 Color_1
Color
default: (color 51 51 25.5) -- animatable, alias:
The color for the veins. <Marble>.map1
TextureMap
default: undefined
-- alias: Map_1
default: true
-- alias: Map_1_Enable
The map used for the veins. <Marble>.map1Enabled
Boolean
When on, the veins use map1 as their color. <Marble>.color2 alias: Color_2
Color
default: (color 209.1 209.1 153) -- animatable,
The color of the background. <Marble>.map2
TextureMap
default: undefined
-- alias: Map_2
default: true
-- alias: Map_2_Enable
The map used for the background. <Marble>.map2Enabled
Boolean
When on, map2 is used for the background. <Marble>.coords
StandardXYZGen
-- alias: coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
1261
1262
Chapter 11
|
3ds max Objects
Mask : TextureMap Constructor: mask ... maskTex ...
Properties: <Mask>.map
TextureMap
default: undefined
The map viewed through the mask. <Mask>.mapEnabled
Boolean
default: true
TextureMap
default: undefined
-- alias: Map_1_Enable
Enables the map. <Mask>.mask
The map to be used as a mask. <Mask>.maskEnabled
Boolean
default: true
-- alias: Map_2_Enable
default: false
-- alias: Invert
Enables the mask map. <Mask>.maskInverted
Boolean
When on, inverts the effect of the mask.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Mix : TextureMap Constructor: mix ...
Properties: <Mix>.color1
Color
default: (color 0 0 0) -- animatable, alias: Color_1
The first color to be mixed. <Mix>.map1
TextureMap
default: undefined
-- alias: Map_1
Sets a map to be used instead of color1. <Mix>.map1Enabled
Boolean
default: true
-- alias: Map_1_Enable
When on, map1 is enabled. <Mix>.color2 Color_2
Color
default: (color 255 255 255) -- animatable, alias:
The second color to be mixed. <Mix>.map2
TextureMap
default: undefined
Sets a map to be used instead of color2.
-- alias: Map_2
Noise : TextureMap
<Mix>.map2Enabled
Boolean
default: true
-- alias: Map_2_Enable
default: 0.0
-- animatable, percentage
When on, map2is enabled. <Mix>.mixAmount
Float
Determines the proportion of the mix. 0 means only color1 is visible on the surface, 1 means only color2 is visible. <Mix>.mask
TextureMap
default: undefined
You can also use a map instead of the mix amount. The two colors will mix in greater or lesser degree according to the intensity of the map. <Mix>.maskEnabled
Boolean
default: true
-- alias: MaskEnable
When on, mask is used instead of mixAmount. <Mix>.useCurve
Boolean
default: false
Determines whether the Mixing Curve effects the mix. <Mix>.lower <Mix>.upper
Float Float
default: 0.3 default: 0.7
-- animatable -- animatable
Adjusts the level of the upper and lower limits. If the two values are the same, the two materials will meet at a definite edge. Wider ranges give more gradual mixing. <Mix>.output
StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Noise : TextureMap Constructor: noise ...
Properties: .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.) .size Noise_Size
Float
Sets the scale of the noise function.
default: 25.0
-- animatable, alias:
1263
1264
Chapter 11
|
3ds max Objects
.thresholdLow Low_Threshold .thresholdHigh High_Threshold
Float
default: 0.0
-- animatable, alias:
Float
default: 1.0
-- 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. .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. .phase
Float
default: 0.0
-- animatable
Controls the speed of the animation of the noise function. Use this option to animate the noise function. .color1 Color_1
Color
default: (color 0 0 0) -- animatable, alias:
Sets the first principal noise color. .map1
TextureMap
default: undefined
-- alias: Map_1
default: true
-- alias: Map_1_Enable
Map used in place of color1. .map1Enabled
Boolean
When on, map1 is enabled. .color2 alias: Color_2
Color
default: (color 255 255 255) -- animatable,
Sets the second principal noise color. .map2
TextureMap
default: undefined
-- alias: Map_2
default: true
-- alias: Map_2_Enable
Map used in place of color2. .map2Enabled
Boolean
When on, map2 is enabled. .coords
StandardXYZGen
-- alias: coordinates
see the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties .output
StandardTextureOutput
see the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
NoTexture : TextureMap
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: .map1
TextureMap
default: undefined
-- alias: Map_1
Map used to apply output settings. .map1Enabled
Boolean
default: true
-- alias: Map_1_Enable
When on, enables the associated map. .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)
1265
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
Color
default: (color 0 0 0) -- animatable,
Sets the color of a particle at its birth. <Particle_Age>.map1
TextureMap
default: undefined
-- alias: Map_1
Sets the map used for a particle at its birth. <Particle_Age>.map1Enabled
Boolean
default: true
-- alias: Map_1_Enable
default: 0.0
-- animatable, alias:
When on, the associated map is enabled. <Particle_Age>.age1 Age_1
Float
Sets the age where a particle starts changing from color1 to color2, expressed as a percentage of the particle’s entire life. <Particle_Age>.color2 animatable, alias: Color_2
Color
default: (color 127.5 127.5 127.5) --
Sets the color of a particle in mid-life. <Particle_Age>.map2
TextureMap
default: undefined
Sets the map used for a particle in mid-life.
-- alias: Map_2
Particle_MBlur : TextureMap
<Particle_Age>.map2Enabled
Boolean
default: true
-- alias: Map_2_Enable
default: 50.0
-- animatable, alias:
When on, the associated map is enabled. <Particle_Age>.age2 Age_2
Float
Sets the age where a particle’s color equals color2, expressed as a percentage of the particle’s entire life. <Particle_Age>.color3 alias: Color_3
Color
default: (color 255 255 255) -- animatable,
Sets the color of a particle at its death. <Particle_Age>.map3
TextureMap
default: undefined
-- alias: Map_3
Sets the map used for a particle at its death. <Particle_Age>.map3Enabled
Boolean
default: true
-- alias: Map_3_Enable
default: 100.0
-- animatable, alias:
When on, the associated map is enabled. <Particle_Age>.age3 Age_3
Float
Sets the age where a particle changes to color3, expressed as a percentage of the particle’s entire life. <Particle_Age>.output
StandardTextureOutput
See the TexOutputClass (p. 1239) topic for the StandardTextureOutput properties.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Particle_MBlur : TextureMap Constructor: particle_mblur ...
Note: This class is not available in 3D Studio VIZ. Properties: <Particle_MBlur>.color1 Color_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.
1267
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: .size
Float
default: 50.0
-- animatable
Sets the size of the marble pattern. Change this to change the scale of marble, relative to the object’s geometry. .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. .color1 animatable, alias: Color_1
Color
default: (color 189.975 189.975 160.65) --
The first color used in the marble. .saturation1 Color_1_Saturation
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. .map1
TextureMap
default: undefined
Map used in place of color1. .map1Enabled
Boolean
default: true
-- alias: EnableMap1
When on, the associated map is enabled. .color2 animatable, alias: Color_2
Color
default: (color 59.925 89.25 59.925) --
The second color used in the marble. .saturation2 Color_2_Saturation
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
.map2
TextureMap
1269
default: undefined
Map used in place of color2. .map2Enabled
Boolean
default: true
-- alias: EnableMap2
When on, the associated map is enabled. .coords - alias: Coordinates
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: .color1 alias: Color_1
Color
default: (color 10.2 20.4 79.05)
-- animatable,
The color at the center of the water mass. .color2 alias: Color_2
Color
default: (color 10.2 30.6 79.05)
-- animatable,
The color surrounding the center of the water mass. .color3 alias: Color_3
Color
default: (color 10.2 40.8 79.05)
-- animatable,
The color surrounding color2, meeting the land. .color4 alias: Color_4 .color5 alias: Color_5 .color6 alias: Color_6 .color7 alias: Color_7 .color8 alias: Color_8
Color
default: (color 10.2 99.45 12.75)
-- animatable,
Color
default: (color 99.45 79.05 12.75) -- animatable,
Color
default: (color 79.05 20.4 7.65)
-- animatable,
Color
default: (color 99.45 79.05 51)
-- animatable,
Color
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
.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. .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. .oceanPercent Ocean_Percent
Float
default: 60.0
-- animatable, alias:
Sets the percentage of the planet’s surface that is covered by water. .randomSeed
Integer
default: 12345
Sets the seed for pseudo-random generation of the pattern. Changing this number can completely change the pattern, even if other settings remain the same. On the other hand, a different Planet map with the same settings including the same Random Seed will appear the same. .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. .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
Raytrace : TextureMap Constructor: raytrace ...
Properties: .Trace_Mode
Integer
default: 0
Sets whether to cast reflected or refracted rays: Auto Detect (If assigned to the material’s Reflection component, the raytracer will reflect. If assigned to Refraction, it will refract. If you assign Raytrace to any other component, you have to manually specify whether you want reflected rays or refracted rays.) Reflection (Casts reflected rays off the object’s surface.) Refraction (Casts refracted rays into or through the object’s surface.) .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. .Options__Antialiasing_Enable true -- animatable
Boolean
default:
Turns antialiasing on or off. Antialiasing is possibly the slowest portion of raytrace rendering. .Options__Self_Reflect_Refract true -- animatable
Boolean
default:
Boolean
default:
Turns self reflection/refraction on or off. .Options__Raytrace_Atmospherics true -- animatable
Turns the raytracing of atmospheric effects on or off. Atmospheric effects include fire, fog, volume light, and so on. .Options__Reflect_Refract_Material_ID_s true -- animatable
Boolean
default:
When on, the material reflects effects assigned to material IDs in the renderer’s G-buffer on or off. .Options__Raytrace_Objects_in_Glass true -- animatable
Boolean
default:
Boolean
default:
Turns the raytracing of objects inside raytraced objects on or off. .Options__Raytrace_Atmospherics_in_Glass true -- animatable
Same as the previous control, but for atmospheric effects instead of objects. .Options__Color_Density___Fog_Enable true -- animatable
Turns the color density and fog features on or off.
Boolean
default:
1271
1272
Chapter 11
|
3ds max Objects
.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.) .Background_Color (color 0 0 0) -- animatable
Color
default:
Boolean
default:
Boolean
default:
Float
default:
Color used as background. .Local_Antialias_Override false
When on, allows you to modify local anitialiasing settings. .Adaptive_Antialiasing false
When on, enables the adaptive antialiaser for this Raytrace map. .Local_Threshold 0.1 -- animatable
Determines the sensitivity of the adaption algorithm. This value can range from 0 to 1, where 0 always casts the maximum number of rays and 1 always casts only the minimum number of rays. .Local_Min__Rays 4 -- animatable
Integer
default:
Integer
default:
Float
default:
Sets the initial number of rays cast per pixel. .Local_Max_Rays 32 -- animatable
Sets the maximum number of rays the algorithm casts. .Local_Blur_Offset 0.0 -- animatable
Affects the sharpness or blurriness of reflections or refractions without regard to distance. You can use this to soften the details of a reflection or refraction. This value is specified in pixels. .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. .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. .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
.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. .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. .Attenuation_Mode
Integer
default: 0
Sets Attenuation Mode: Off Linear (Linear attenuation is calculated between the attenuation_start and attenuation_end values.) Inverse Scale (Sets inverse square attenuation. Inverse square attenuation is calculated beginning at the attenuation_start range, and doesn’t use the attenuation_end range. Inverse scale is the actual attenuation rate for light in the real world. However, it doesn’t always give the effect you want in a rendered scene.) Exponential (Sets exponential attenuation. Exponential attenuation is calculated between the attenuation_start and attenuation_end values. You also specify the exponent to use.) Custom Falloff (Specifies a custom curve to use for attenuation.) .Attenuation_Start 0.0 -- animatable
Float
default:
Float
default:
Float
default:
Integer
default: 0
The distance in world units where attenuation begins. .Attenuation_End 100.0 -- animatable .Attenuation_Exponent 2.0 -- animatable .Attenuation_Color_Mode
Attenuation_Color_Mode = 0 - Background; 1 - use Attenuation_Color .Attenuation_Color (color 0 0 0) -- animatable
Color
default:
Float
default:
Sets the distance in world units where the ray is fully attenuated. .Attenuation_Near 1.0 -- animatable
Sets the strength of the reflected/refracted ray at the start range distance. This is a normalized percentage that can range from 0.0 to 1.0.
1273
1274
Chapter 11
|
3ds max Objects
.Attenuation_Control_1 0.6666 -- animatable
Float
default:
Float
default:
Float
default:
Controls the shape of the curve near the curve start. .Attenuation_Control_2 0.3333 -- animatable
Controls the shape of the curve near the curve end. .Attenuation_Far 0.0 -- animatable
Sets the strength of the reflected/refracted ray at the end range distance. This is a normalized percentage that can range from 0.0 to 1.0. .Use_Reflectivity_Map false -- animatable
Boolean
default:
Float
default:
Enables a reflectivity map. .Reflectivity_Map_Amount 1.0 -- animatable
Controls the amount of raytracing used by the material it is assigned to. .Basic_Tint_Enable false
Boolean
default:
Float
default:
Color
default:
Boolean
default:
Boolean
default:
Color
default:
Float
default:
Turns basic tinting on or off. .Tint_Amount 1.0 -- animatable
Sets the amount of tinting used. .Tint_Color (color 255 255 255) -- animatable
Assigns a tint color for reflections. .Use_Tint_Map false
Enables the use of a map for tinting. .Color_Density_Enable false
Turns color density on or off. .Color_Density_Color (color 255 255 255) -- animatable
Sets the transmission color. .Color_Density_Amount 1.0 -- animatable
Controls the amount of density color. It can range from 0 to 1.0. Reducing this value reduces the density color effect.
Raytrace : TextureMap
.Color_Density_Start 0.0 -- animatable .Color_Density_End 25.0 -- animatable
Float
default:
Float
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. .Use_Color_Density_Map false
Boolean
default:
Boolean
default:
Color
default:
Float
default:
Enables the use of a map for the color density filter. .Fog_Enable false
Turns fog on or off. .Fog_Color (color 255 255 255) -- animatable
Sets the fog color. .Fog_Amount 1.0 -- animatable
Controls the amount of density fog. It can range from 0 to 1.0. Reducing this value reduces the density fog effect and makes the fog translucent. .Fog_Start 0.0 -- animatable .Fog_End 25.0 -- animatable
Float
default:
Float
default:
Start and End Distance controls, expressed in world units, adjust the fog effect based on the object’s dimensions. Start is the position in the object where the density fog begins to appear. End is the position in the object where the density fog reaches its full Amount value. To have a lighter effect, increase the End value. To have a heavier effect, reduce the End value. .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. .Interobject_Interphase_Fusing false .IIF_Tolerance 1.0
Boolean
default:
Float
default:
1275
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: .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.) .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. .useAtmosphericMap Use_Atmospheric
Boolean
default: true
-- alias:
When off, environment maps are ignored by Reflect/Refract map during rendering. It’s useful to turn this off when you have mirrors in the scene and you’re rotoscoping against a flat screen environment map. A screen environment map does not exist in 3D space the way the other environment-map types do, and will not render properly.
Reflect_Refract : TextureMap
.apply
Boolean
default: true
Float
default: 0.0
Turns on filtering to blur the maps. .blurOffset alias: Blur_Offset
-- animatable,
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. .blur
Float
default: 1.0
-- animatable
Affects the sharpness or blurriness of the generated map based on its distance from the object. The farther away the map is, the greater the blurring. Blur is primarily used to avoid aliasing. It’s a good idea to use a small amount of blurring for all maps in order to avoid the scintillation or aliasing that can occur when pixel details are reduced off in the distance. .near alias: Near_Value
Float
default: 0.0
-- animatable,
Float
default: 500.0 -- animatable,
Integer
default: 0
Sets the near range for fog. .far alias: Far_Value
Sets the far range for fog. .frametype
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.) .nthframe
Integer
default: 1
Sets the frame rate for automatic maps. .bitmapName undefined)
ArrayParameter
default: #(undefined, ... ,
Array with 6 elements. Each element stores a string reflecting the name of a source bitmap file. .outputname Output_Name
String
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)
default: undefined -- alias:
1277
1278
Chapter 11
|
3ds max Objects
RGB_Multiply : TextureMap Constructor: rgb_multiply ...
Properties: .color1 alias: Color_1 .map1 .map1Enabled
Color
default: (color 255 255 255) -- animatable,
TextureMap Boolean
default: undefined default: true
Color
default: (color 255 255 255) -- animatable,
TextureMap Boolean
default: undefined default: true
Integer
default: 2
-- alias: Map_1 -- alias: Map_1_Enable
Enables associated map. .color2 alias: Color_2 .map2 .map2Enabled
-- alias: Map_2 -- alias: Map_2_Enable
Enables associated map. .alphaFrom
Determines how to generate alpha for the map: Map #1 (Uses the first map’s alpha channel.) Map #2 (Uses the second map’s alpha channel.) Multiply Alphas (Generates a new alpha channel by multiplying the alpha channels of the two maps.)
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
RGB_Tint : TextureMap Constructor: rgb_tint ...
Properties: .red
Color
default: (color 255 0 0) -- animatable
The tint of the red color channel. .green
Color
default: (color 0 255 0) -- animatable
The tint of the green color channel. .blue
Color
The tint of the blue color channel.
default: (color 0 0 255) -- animatable
Smoke : TextureMap
.map1
TextureMap
default: undefined
-- alias: Map_1
default: true
-- alias: Map_1_Enable
Sets the map to be tinted. .map1Enabled
Boolean
Enable the effect of map1.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Smoke : TextureMap Constructor: smoke ...
Properties: <Smoke>.size
Float
default: 40.0
-- animatable
Changes the scale of the smoke “clumps.” <Smoke>.iterations
Integer
default: 5
-- animatable
Sets the number of times the fractal function is applied. The higher the value, the more detail within the smoke, but the longer the calculation time. <Smoke>.phase
Float
default: 0.0
-- animatable
Shifts the turbulence within the smoke pattern. Animate this parameter to animate the movement of the smoke. <Smoke>.exponent
Float
default: 1.5
-- animatable
Makes color2, representing the smoke, sharper and more wispy. As this value increases, the smoke “tendrils” become smaller within the pattern. <Smoke>.color1 Color_1
Color
default: (color 0 0 0) -- animatable, alias:
The smokeless portion of the effect. <Smoke>.map1
TextureMap
default: undefined
The map used for the smokeless portion of the effect. <Smoke>.map1On
Boolean
default: true
-- alias: Map1_On
Enables the associated map. <Smoke>.color2 alias: Color_2
Color
default: (color 229.5 229.5 229.5) -- animatable,
The color of the smoke. <Smoke>.map2
TextureMap
The map used for the smoke.
default: undefined
1279
1280
Chapter 11
|
3ds max Objects
<Smoke>.map2On
Boolean
default: true
-- alias: Map2_On
Enables the associated map. <Smoke>.coords
StandardXYZGen
-- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Speckle : TextureMap Constructor: speckle ...
Properties: <Speckle>.size
Float
default: 60.0
-- animatable
Adjusts the size of the speckles. Use this to make the speckles match your geometry. <Speckle>.color1 Color_1
Color
default: (color 51 127.5 255) -- animatable, alias:
The color of the speckles. <Speckle>.map1
TextureMap
default: undefined
The map used as the color of the speckles. <Speckle>.map1On
Boolean
default: true
-- alias: Map1_On
Enables associated map. <Speckle>.color2 Color_2
Color
default: (color 178.5 204 204) -- animatable, alias:
The color of the background. <Speckle>.map2
TextureMap
default: undefined
The map used as the color of the background. <Speckle>.map2On
Boolean
default: true
-- alias: Map2_On
Enables associated map. <Speckle>.coords
StandardXYZGen
-- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Splat : TextureMap
Splat : TextureMap Constructor: splat ...
Properties: <Splat>.size
Float
default: 40.0
-- animatable
Adjusts the size of the splats. Use this to make the splats match your geometry. <Splat>.iterations
Integer
default: 4
-- animatable
Sets the number of times the fractal function is evaluated. The higher the number, the more detailed the splats, but the longer the calculation time. <Splat>.threshold
Float
default: 0.2
-- animatable
Determines how much of color1 is mixed with color2. At 0, only color1 is displayed; at 1, only color2 is displayed. <Splat>.color1 Color_1
Color
default: (color 178.5 204 204) -- animatable,
The color of the background. <Splat>.map1
TextureMap
default: undefined
The map used as the color of the background. <Splat>.map1On
Boolean
default: true
-- alias: Map1_On
Enables associated map. <Splat>.color2 Color_2
Color
default: (color 51 127.5 255)
-- animatable,
The color of the splats. <Splat>.map2
TextureMap
default: undefined
The map used as the color of the splats. <Splat>.map2On
Boolean
default: true
-- alias: Map2_On
Enables associated map. <Splat>.coords
StandardXYZGen
-- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
1281
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
Color
default: (color 0 0 0) -- animatable, alias:
The color of the indentations. <Stucco>.map1
TextureMap
default: undefined
The map used as the color of the indentations. <Stucco>.map1On
Boolean
default: true
-- alias: Map1_On
Enables associated map. <Stucco>.color2 alias: Color_2
Color
default: (color 229.5 229.5 229.5) -- animatable,
The background stucco color. <Stucco>.map2
TextureMap
default: undefined
The map used as the background stucco color. <Stucco>.map2On
Boolean
default: true
-- alias: Map2_On
Enables associated map. <Stucco>.coords
StandardXYZGen
-- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Swirl : TextureMap
Swirl : TextureMap Constructor: swirl ...
Properties: <Swirl>.Base
Color
default: (color 229.5 147.9 76.5) -- animatable
The underlying layer for the swirl effect. <Swirl>.Swirl
Color
default: (color 0 25.5 51) -- animatable
Mixed with the Base color or map, produces the swirl effect. <Swirl>.Color_Contrast
Float
default: 0.4
-- animatable
Controls the contrast between Base and Swirl. At 0, the swirl is blurred. Higher values increase the contrast until all colors become black and white, even if Swirl Intensity and Swirl Amount are very high. <Swirl>.Swirl_Intensity
Float
default: 2.0
-- animatable
Controls the intensity of the swirl color. Higher values create a more vibrant mix of colors. At 0, the swirl effect disappears. <Swirl>.Swirl_Amount
Float
default: 1.0
-- animatable
Controls the quantity of the swirl color that gets mixed into the base color. If set to 0, only the base color is used. <Swirl>.Twist
Float
default: 1.0
-- animatable
Changes the number of spirals in the swirl effect. Higher values increase the number of spirals. Negative values change the direction of the twist. At 0, the colors are randomly distributed, not swirled. <Swirl>.Constant_Detail
Integer
default: 4
-- animatable
Changes the level of detail within a swirl. Lower values minimize the level of detail within the swirl. At 0, all detail is lost. Higher values increase detail until the swirl effect disappears. <Swirl>.Center_Position_Y <Swirl>.Center_Position_X
Float Float
default: -0.5 default: -0.5
-- animatable -- animatable
Adjusts the location of the swirl’s center on the object. <Swirl>.Lock_Background
Integer
default: 1
X and Y values remain identical as you adjust them. By turning off Lock and adjusting either the X or Y position, you can “slide” the swirl effect across the object. OFF ON <Swirl>.Random_Seed
Float
default: 23638.4
-- animatable
Sets a new starting point for the swirl effect. Changes the swirl pattern while maintaining other parameters. <Swirl>.coordinates
SubAnim
See the UVGenClass (p. 1237) topic for the StandardUVGen properties.
1283
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: .applyBlur
Boolean
default: true
Float
default: 1.0
Turns on filtering to blur the maps. .blur
-- animatable
Affects the sharpness or blurriness of the generated map based on its distance from the object. The farther away the map is, the greater the blurring. Blur is primarily used to avoid aliasing. It’s a good idea to use a small amount of blurring for all maps in order to avoid the scintillation or aliasing that can occur when pixel details are reduced off in the distance. .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.) .nthFrame
Integer
default: 1
Boolean
default: true
Sets the regeneration rate in animations. .useEnviroment
When off, environment maps are ignored by the refraction during rendering. It’s useful to turn it this off when you have refractions in the scene and you’re rotoscoping against a flat screen environment map. A screen environment map does not exist in 3D space the way the other environment map types do, and will not render properly.
Vertex_Color : TextureMap
.thicknessOffset alias: Thickness_Offset
Float
default: 0.5
-- animatable,
Affects the size of the refractive offset, or jog effect. At 0, there’s no offset, and the object can appear invisible in the rendered scene. At 10.0, the offset is at its greatest. .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)
1285
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 they’re farther apart, the water is less regular. <Water>.amplitude
Float
default: 1.0
-- animatable
Adjusts the strength and the depth of the waves by increasing the contrast between the two colors. <Water>.phase
Float
default: 0.0
-- animatable
Shifts the wave pattern. Animate this parameter to animate the motion of the pattern. <Water>.distribution
Integer
default: 0
3D distributes the wave centers on the surface of an imaginary sphere, affecting all sides of a 3D object. 2D distributes the wave in circles centered on the XY plane, which is more appropriate for flat water surfaces such as oceans and lakes. 3D 2D <Water>.randomSeed
Integer
default: 30159
Provides a seed number to generate the water pattern. The pattern changes with each seed, but all other settings are maintained. <Water>.color1 alias: Color_1
Color
default: (color 198.9 198.9 239.7) -- animatable,
Sets the wave trough color. <Water>.map1
TextureMap
default: undefined
Sets a map as the wave trough color. <Water>.map1On
Boolean
Enables associated map.
default: true
-- alias: Map1_On
Wood : TextureMap
<Water>.color2 alias: Color_2
Color
default: (color 25.5 25.5 198.9) -- animatable,
The color of wave peaks. <Water>.map2
TextureMap
default: undefined
Sets a map as the color of wave peaks. <Water>.map2On
Boolean
default: true
-- alias: Map2_On
Enables associated map. <Water>.coords
StandardXYZGen
-- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Wood : TextureMap Constructor: wood ...
Properties: <Wood>.thickness Grain_Thickness
Float
default: 7.0
-- animatable, alias:
Sets the relative thickness of the color bands that make up the grain. <Wood>.radialNoise Radial_Noise
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
default: (color 201.45 175.95 68.85) -- animatable,
TextureMap Boolean
default: undefined default: true
Enables associated map.
-- alias: MapOn1
1287
1288
Chapter 11
|
3ds max Objects
<Wood>.color2 alias: Color_2 <Wood>.map2 <Wood>.map2Enabled
Color
default: (color 130.05 81.6 12.75) -- animatable,
TextureMap Boolean
default: undefined default: true
-- alias: MapOn2
Enables associated map. <Wood>.coords
StandardXYZGen
-- alias: Coordinates
See the StandardXYZGen (p. 1238) topic for the StandardXYZGen properties.
See also TextureMap Common Properties, Operators, and Methods (p. 1235) Material Common Properties, Operators, and Methods (p. 1203) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Animation Controllers All animation in 3ds max is implemented using one of the many controller classes accessible in the Track View and Motion Panel, or assigned automatically by 3ds max when you use the Animate button to do keyframing. Certain controllers (keyframeable controllers) store their animation values as keys. This section includes topics that discuss all aspects of scripting 3ds max controllers and the Key classes used in keyframing. Controller Common Properties, Operators, and Methods (p. 1289) Time and Key Functions on Object Hierarchies (p. 1299) Controllers - Superclass Level (p. 1300) The controllers are arranged in a hierarchy of superclasses and classes. All classes in a superclass output a specific data type (for example, Float or Point3). Each animatable property in 3ds max has a data type, and any of the classes in the superclass that outputs that data type can be assigned that property. So, for example, the linear_float and noise_float controllers are classes in the Float superclass, and either can be assigned to the height property of a box, which is has a Float data type. The list of controller superclasses can be determined using the apropos() function: apropos “controller:super”
The list of available controllers can be determined using the showClass() function: showClass “*:*controller*”
which lists all the known classes that have “controller” in their superclass name. The controllers include, at least, 3ds max’s core controllers and any 3rd-party plug-in controllers. In some cases, embedded controllers for some complex plug-ins may be visible in the showClass() listing (such as for character studio and HyperMatter). You should not attempt to create and use these controllers individually, this may result in system exceptions.
Wood : TextureMap
Controller Common Properties, Operators, and Methods Properties: All controllers have the following properties: .keys .value
MAXKeyArray -- read-only, the controller’s 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 controller’s value property if the controller is a key-based controller. The only exception to this is that you can assign a Matrix3 value to a PRS controller’s value property. MAXScript will automatically set the individual position, rotation, and scale values to the values represented in the Matrix3 value. If an Ease Curve has been assigned to a controller, the following controller-related sub-property is available: .Ease_Curve
Float
-- the controller’s ease curve value
If an Ease Curve has been assigned to a controller, the following controller-related sub-property is available: .Multiplier_Curve
Float
-- the controller’s multiplier curve value
See the Ease and Multiplier Curve Functions (p. 1297) topic for methods and notes related to ease and multiplier curves. Example: globaltracks.float.mycontroller.value globaltracks.float.mycontroller.keys[2]
Associated Properties: All animatable properties in 3ds max objects let you reference several controller-related subproperties. These are: <property>.controller <property>.track <property>.isAnimated <property>.keys
-----
the property’s controller a synonym for .controller a boolean indicating whether the property is animated read-only, gets the property’s controller’s key array
The track property is a simple synonym for controller. If an animatable property does not yet have a controller assigned, the isAnimated property returns false and the controller, track, and keys properties return undefined.
1289
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>
Returns the controller currently assigned to the vertex, undefined if no controller assigned. getPointController <editable_spline_node> <spline_index_integer>
Returns the controller for specified vertex in the specified spline, undefined if no controller assigned. Each spline knot consists of 3 vertices: the in vector, the knot, and the out vector. Note: Applying a controller to a property causes the controller to take on the properties value at frame 0. If keys are present for the controller before the assignment to the property, all keys will be adjusted by the difference between the controller’s value at frame 0 and the property’s value. This is shown in the following example.
Wood : TextureMap
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 controller’s value through a MAXWrapper property, the scaling factor associated with that property is applied to the controller’s value. MAXScript also internally stores the last scaling factor applied to the controller’s value. If you are directly accessing the value property of the controller, or the value property of a key in the controller, the stored scaling factor is used. This can result in a controller’s value property returning different values at different times in a script, based on how the controller was last accessed. Because of this, it is highly recommended that you do not instance a controller onto multiple MAXWrapper properties which have different scaling factors. The scaling factor, if any, is listed for each MAXWrapper property in the documentation of the MAXWrapper classes.
1291
1292
Chapter 11
|
3ds max Objects
Methods: displayControlDialog <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
returns true or false depending on whether the controller supports the following time operations deleteTime [ #incLeft ] [ #incRight ] [ #noSlide ]
Deletes an interval of time from the controller, removing all the keys with that interval and, by default, sliding the keys to the right of the interval to the left by the width of the interval. The optional symbolic arguments choose one of several options: #incLeft: includes any key exactly at the start time of the interval #incRight: includes any key exactly at the end time of the interval #noSlide: doesn’t slide the later keys to fill in the gap removed- this effectively just deletes any keys in the interval. The 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 [ #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
scaleTime
Scales the times of the keys within the given interval. Again, the 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
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 [ #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 [ ] [ #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
1293
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 [ #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 [ #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
Deletes the indexed key. Key indexes are 1-based. selectKeys [ | ]
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 [ | ]
Deselects specified keys. Arguments are as described in selectKeys(). selectKey
Selects the indexed key. Key indexes are 1-based. isKeySelected
Returns true if indexed key is selected, false otherwise. Key indexes are 1-based. deselectKey
Deselects the indexed key. Key indexes are 1-based. moveKeys [ #selection ]
Moves the specified keys by the time given. If #selection is specified, move the current selection otherwise move all keys. moveKey
Move the indexed key by the specified time.
Controller Key Functions
numKeys
Returns the number of keys in the controller. Returns -1 if you call it on a controller that does not support keyframing. getKey
Returns the indexed key as a MAXKey instance. See the Controller Key Functions (p. 1294) topic for MAXKey class information. getKeyTime
Returns the time of indexed key. getKeyIndex
Returns the index of the key at the specified time. numSelKeys
Returns the number of keys currently selected in the track view. sortKeys
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
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, specifies whether to create the key in the transform controller’s position or rotation (or roll angle) sub-controller. If rot_or_pos_integer = 0, the key is created in the position controller. For all other values, the key is created in the rotation (or roll angle) controller. If the controller passed to this method is not a transform level controller, the value is not used. Returns true if the key creation was successful, false otherwise.
1295
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
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
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
setBeforeORT
Sets the Out-of-Range (ORT) type for the controller for the time before the first key. The must be one of the following name values: #constant #cycle #loop #pingPong #linear #relativeRepeat setAfterORT
Sets the Out-of-Range (ORT) type for the controller for the time after the last key. The must be one of the symbolic values shown in setBeforeORT() above. No testing done on the validity of is performed. enableORTs
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 [ ]
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
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
Returns the number of ease curves currently operating on the controller. applyEaseCurve
Applies the combined ease curves in the specified controller to the given time value, returning the transformed time. addMultiplierCurve [ ]
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
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.
1297
1298
Chapter 11
|
3ds max Objects
numMultiplierCurves
Returns the number of multiplier curves currently operating on the controller. getMultiplierValue
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: .Ease_Curve
-- the controller’s ease curve value
If an Ease Curve has been assigned to a controller, the following controller-related sub-property is available: .Multiplier_Curve
-- the controller’s multiplier curve value
Note: The values stored in an Ease Curve controller are stored as integer time ticks. Example: The following script shows example usages of some of the above methods. Script: -- controller test bed 3 b=box height:10 at time 5 animate on b.height=50 at time 10 animate on b.height=100 bhc=b.height.controller ec=bezier_float() at time 0 animate on ec.value = 0 at time 100 animate on ec.value=100*ticksPerFrame setBeforeORT ec #linear setAfterORT ec #linear addEaseCurve bhc ec applyEaseCurve bhc 50 addEaseCurve bhc ec numEaseCurves bhc deleteEaseCurve bhc 2 numEaseCurves bhc at time 50 bhc.ease_curve.value mc=bezier_float() at time 0 animate on mc.value = 1 at time 100 animate on mc.value = 2 addMultiplierCurve bhc mc at time 50 bhc.multiplier_curve
Controller Key Reducer
Controller Key Reducer reduceKeys <step> [ ]
where 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 is an optional time range within which the keys are reduced given as either 2 time values or an Interval value, defaulting to the active animation range. Examples: reduceKeys $foo.pos.controller 0.5 1f
reduce keys on foo’s position, retain 0.5 units accuracy, sample every frame. reduceKeys $baz.bend.angle.controller 0.1 0.5f (interval 20 75)
Reduce keys on baz’s bend angle, retain 0.1 units accuracy, sample every half frame, reduce within the interval 20f to 75f. As with the reducer in the track view, a progress bar and cancel button is displayed.
Time and Key Functions on Object Hierarchies Certain of the controller time and key functions can be called on any 3ds max object or collection of 3ds max objects, not just individual controllers. If called in this way, they apply recursively to all the nested controllers within those objects and on any on sub-objects and sub-controllers within those objects. In this way, they work in a manner similar to the object-level tracks in the 3ds max Track View that allow you to manipulate keys and time for all the sub-objects and sub-controllers within them. The time and controller functions that work this way are: deleteTime reverseTime scaleTime insertTime setTimeRange addNewKey deleteKeys selectKeys deselectKeys moveKeys sortKeys reduceKeys addEaseCurve deleteEaseCurve setBeforeORT setAfterORT enableORTs
1299
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
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)
1301
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
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)
1303
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: .keys .node .align
: MAXKeyArray : Node : Booleandefault: true
Fixes the orientation of the attached object to the face where it’s assigned. When this is turned off, the orientation of the attached object is not affected by the orientation of the face on the target object.
Attachment Controller Keys
.manupdate
: Booleandefault: false
Enables the update button. Methods: AttachCtrl.getKey
Returns the indexed key as a MAXAKey value AttachCtrl.addNewKey
Returns the indexed key as a MAXAKey value AttachCtrl.update
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: .time .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
1305
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
Methods: addMorphTarget <morph_controller>
Adds a new morph target object to the given morph controller. The 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>
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>
Deletes the numbered morph target in the given controller. setMorphTargetName <morph_controller>
Changes the target name of the numbered target in the given morph controller. getMKTargetWeights <morph_controller> <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>
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>
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.
1307
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: .time only. .selected access.
Time
-- time value or number (interpreted as frames). Read-
Boolean
-- specifies whether the key is selected. Read/write
Methods: getMKTime <morph_key>
Returns the given morph key’s time. setMKTime <morph_key>
Sets the time of the given morph key. getMKWeight <morph_key>
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>
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
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
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: .keys
MAXKeyArray
----------
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
1309
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: .time .selected .value .inTangent .outTangent .inTangentType .outTangentType .x_locked .y_locked .z_locked .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
Examples: c = bezier_position () $bar.pos.controller = c
-- create and assign new controller
k = addNewKey c 0f k.value = [10,0,0] k.outTangentType = #slow
-- add a key at frame 0 -- set value there -- and outgoing tangent type
k = addNewKey c 100f k.value = [200,10,0] k.inTangentType = #custom k.inTangent = [0.2, 0.02, 0.112] k.x_locked = false
------
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)
1311
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: .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: .time only. .selected access.
Time
-- time value or number (interpreted as frames). Read-
Boolean
-- 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
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.
1313
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>
Get and set the Position threshold value for the specified object. ik.GetRotThreshold <node> ik.SetPosThreshold <node>
Get and set the Rotation threshold value for the specified object. ik.GetIterations <node> ik.SetIterations <node>
Get and set the Iterations value for the specified object. ik.GetStartTime <node> ik.SetStartTime <node>
Get and set the Start time for the specified object ik.GetEndTime <node> ik.SetEndTime <node>
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 value ik.setPrecedence <node>
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>
Get/set whether the node is a terminator.
Linear Controllers
ik.getBindPos <node> ik.setBindPos <node>
Get/set whether Bind Position is turned on for the node. ik.getBindOrient <node> ik.setBindOrient <node>
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: .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: .time .selected .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)
1315
1316
Chapter 11
|
3ds max Objects
Link_Control : Matrix3Controller Constructor: link_control ...
Properties: .transform
Matrix3Controller
Contains the transform controller below the link controller Methods: linkCtrl.getLinkCount
Returns the number of nodes linked to as an integer. linkCtrl.getLinkNode
Returns the node for the indexed link as a node value. linkCtrl.setLinkNode <node>
Sets the node for the indexed link. The indexed link must already exist. linkCtrl.getLinkTime
Returns the time for the indexed link as a time value. linkCtrl.setLinkTime
Sets the time for the indexed link. The indexed link must already exist. linkCtrl.addLink <node>
Adds the specified node as a link with the specified time. linkCtrl.deleteLink
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
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
1317
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>
Returns the name of the indexed subcontroller in the list controller listCtrl.setName <list_controller> <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
listCtrl.getActive <list_controller>
Returns the index of the active subcontroller in the list controller listCtrl.setActive <list_controller>
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: .position .roll_angle .scale
Bezier_Position Bezier_Float Bezier_Scale
-- the position controller -- the roll controller -- the scale controller
1319
1320
Chapter 11
|
3ds max Objects
There presently are no methods for directly accessing or setting the target node in the LookAt controller. To set the target node, the LookAt controller needs to be assigned to a node, and then the lookat property of the node is set to the target node. If the transform controller for a node is not a LookAt controller, and a target node is assigned to the lookat property of the node, a LookAt controller is automatically assigned to the node. For example, $box01.lookat=$box02
is equivalent to $box01.transform.controller=lookat() $box01.lookat=$box02
Note: The following properties are not accessible by MAXScript in 3ds max 4 the Axis radio-button and the Flip checkbox.
See also Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
MasterBlock : MasterBlockController Constructor: The MasterBlock controller is not creatable by MAXScript. It can only be created in the Block Control node in the Global Tracks node of Track View. If multiple MasterBlocks are present, you will need to access the MasterBlocks as a subAnim of trackviewnodes.global_tracks. block_control. This is because all MasterBlocks have the same name (MasterBlock). Properties: Once a MasterBlock has been created in Track View, the following MasterBlock property is available: <MasterBlock>.blend
Float
Once a track has been added to the MasterBlock, a Block controller is added to the MasterBlock, and the track’s controller is added as an input controller to the Block controller. The name assigned to the Block controller is the name specified for the block. The Block controller is then available as a property of the MasterBlock, and the track’s controller is available as a property of the Block controller. In addition, the track’s controller is replaced with a list controller and the track’s original controller is placed in the list controller along with a Slave controller. This Slave controller is controlled by the Block controller. For example, if a block with name “BoxHeight” is present, and contains the height controller for a box object, the block and its track can be accessed as follows:
Motion Capture Controllers
mb=trackviewnodes.global_tracks.block_control[1] -- SubAnim:MasterBlock getpropnames mb -- #(#Blend, #height) h=mb.height -- SubAnim:height h.object -- Controller:Block getpropnames h -- #(#Box01_Height) h.box01_height -- 157.083 - the box’s height h.box01_height.controller -- Controller:Bezier_Float - the box’s height controller
See also Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Motion Capture Controllers float_motion_capture : floatController point3_motion_capture : point3Controller position_motion_capture : positionController rotation_motion_capture : rotationController scale_motion_capture : scaleController Constructor: float_motion_capture ... point3_motion_capture ... position_motion_capture ... rotation_motion_capture ... scale_motion_capture ...
Note: These classes are not available in 3D Studio VIZ. Properties: <motion_capture>.data
Controller
The data controller type depends on the motion controller data type. The controller is typically a Bezier controller. There are presently no properties or methods associated with the motion capture controllers themselves.
See also Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
1321
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
limits values to > 0
Boolean Boolean Boolean
default: false default: false default: false
On_Off : FloatController
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: .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: .time only. .selected access.
Time
-- time value or number (interpreted as frames). Read-
Boolean
-- specifies whether the key is selected. Read/write
1323
1324
Chapter 11
|
3ds max Objects
See also Key Common Properties, Operators, and Methods (p. 768) Value Common Properties, Operators, and Methods (p. 714)
Path : PositionController Constructor: path ...
Properties: <path>.allowUpsideDown
Boolean
default: false
-- alias: Allow_Upside_Down
Turn on to avoid the situation in which an object flips when going around a vertically oriented path. <path>.axis
Integer
default: 0
Boolean
default: false
axis = 0 - X; 1 - Y; 2 - Z <path>.axisFlip
-- alias: Axis_Flip
Flips the direction of the object on the path 180 degrees. <path>.bank
Boolean
default: false
Allows the object to bank (roll) as it negotiates the curves of the spline. <path>.bankAmount Bank_Amount
Float
default: 0.5
-- animatable, alias:
The amount of the banking to one side or the other, depending on whether the value is positive or negative. <path>.constantVel
Boolean
default: false
-- alias: Constant_Velocity
Provides a constant velocity along the path. When off, the velocity of the object along the path varies depending on the distance between the vertices on the path. <path>.follow
Booleandefault: false
Aligns the object to the trajectory as it follows the contour. <path>.loop
Boolean
default: false
--
boolean
When turned on, the path controlled object will loop back to the start point of the path, after the end point is reached. <path>.path
Node
default: undefined -– node; Path_Constraint
The spline in the scene that you want the selected object to follow. <path>.pathlist
Array
default: #() --
node array; SubAnim
The object will follow the resultant path which is the weighted average of the paths in this array. The weight for each path is found in the corresponding entry in <path>.weightlist. <path>.percent
Floatdefault: 0.0
-- animatable, percentage
The percent that the object is positioned along the path. <path>.relative
Boolean
default: false
--
booleanExample
When turned on, the path controlled object will maintain the position offset between its initial position and the start point of the path.
PRS : Matrix3Controller
<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 controller’s value property. MAXScript will automatically set the individual position, rotation, and scale values to the values represented in the Matrix3 value.
1325
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
Creates a new reaction for the specified reactor controller. deleteReaction
Deletes the specified reaction. 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 ( | <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
Returns the number of reactions for the specified reactor controller. selectReaction
Selects the specified reaction. 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
Returns the number of the selected reaction. getReactionFalloff
Returns the specified reaction’s falloff. 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
setReactionFalloff
Sets the specified reaction’s falloff to the specified value. 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
Returns the specified reaction’s influence. 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
Sets the specified reaction’s influence to the specified value. 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
Returns the specified reaction’s strength. 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
Sets the specified reaction’s strength to the specified value. 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
Returns the specified reaction’s state. The value type returned matches the reactor controller type. 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
Sets the specified reaction’s state to the specified value. 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 type must match the reactor controller type. getReactionValue
Returns the specified reaction’s value. The return value type is the same as the controller type being reacted to. 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
Sets the specified reaction’s value to the specified value. 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 type must match the controller type being reacted to.
1327
1328
Chapter 11
|
3ds max Objects
setReactionName <string>
Sets the name of the specified reaction. 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 <which>
Returns the specified reaction’s name. 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
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.
1329
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
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: .radius .height .slice_from .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 controller’s script is any valid MAXScript expression that evaluates to the proper data type, and can contain global and local variables, functions, and structure definitions. The script is compiled in its own local scope, and the locals are only visible inside the scope of the script controller. Script controller local variables are heap-based locals, which are slightly different from normal (stack-based) locals. Normal locals are visible in the current scope and have a lifetime of one execution of that scope. Heap-based locals are also visible only in the current scope, but have a lifetime equal to the lifetime of the top-level expression where they are defined. A script controller’s locals are created the first time the script is executed and are kept permanently in the heap (unless
1331
1332
Chapter 11
|
3ds max Objects
and until you redefine the script). This means you can store values in local variables during one execution of the script controller and these values will still be present at the next evaluation. You cannot access the script controller’s locals from another utility or from Listener, because they are not executing within the scope of the script controller. See the Scope of Variables (p. 646) topic for more information. As a special case, you can exit a script controller’s script using a return <expr>. A controller is always evaluated by 3ds max with respect to a specific animation time. This might be the current time slider or incrementing frame time if an animation is playing or a render is under way. In the case of Script controllers, the time being evaluated is used to establish an automatic ‘at time’ context around the controller script, so any properties you access (outside of other explicit ‘at time’ expressions) yield the correct values for the current controller evaluation time. This means you don’t have to do anything special in your scripts to work at the correct time. You can access the evaluation time if you need to with the standard MAXScript variable, currentTime. You can also reference scene property values at other times by using explicit ‘at time’ expressions in your scripts, as in normal MAXScript programming. Remember that MAXScript lets you write multiline string literals, if you need. Examples: A position script keeping the object at the center of all other objects in the scene as they move about: local pos = [0,0,0] for o in objects where o != $foo do pos += o.pos pos / (objects.count - 1)
The above script computes the average position of all objects except the current one (written as $foo here) by setting up a local variable that iterates through all objects except $foo, accumulates a total position vector, and computes the average in the last line, which is the final result of the script. A position script keeping the object attached to the highest vertex in a given object: local high_index = 1, high_z = (getVert $foo 1).z for i in 2 to $foo.numVerts do if (getVert $foo i).z > high_z then ( high_index = i high_z = (getVert $foo i).z ) getVert $foo high_index
The above script runs over the vertices in $foo remembering the index of the vertex with the largest z and returns that vertex’s coordinates as the new position.
Slave_Control : Matrix3Controller
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)
1333
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
Node Float Float Integer
default: default: default: default:
undefined 0.0 -- animatable 0.0 -- animatable 1
align = 1 - No Alignment; 2 - Align to U; 3 - Align to V <Surface_position>.flip
Boolean
default: false
See also Controller Common Properties, Operators, and Methods (p. 1289) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
TCB Controllers TCB_float : floatController TCB_point3 : point3Controller TCB_position : positionController TCB_rotation : rotationController TCB_scale : scaleController Constructor: TCB_float ... TCB_point3 ... TCB_position ... TCB_rotation ... TCB_scale ...
Properties: .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
TCB Controller Keys For TCB controller keys, the following additional properties are accessible: .time .selected .value .tension .continuity .bias .easeTo .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
1335
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: .r .g .b
Float Float Float
default: 0.0 default: 0.0 default: 0.0
-- animatable -- animatable -- animatable
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
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_x_rotation Float default: 0.0 .local_y_rotation Float default: 0.0 .local_z_rotation Float default: 0.0 .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
7 - XYX 8 - YZY 9 - ZXZ Point3_XYZ: .x .y .z
Float Float Float
default: 0.0 default: 0.0 default: 0.0
-- animatable -- animatable -- animatable
Float Float Float
default: 0.0 default: 0.0 default: 0.0
-- animatable -- animatable -- animatable
Float Float Float
default: 0.0 default: 0.0 default: 0.0
-- animatable -- animatable -- animatable
Position_XYZ: .x_position .y_position .z_position
ScaleXYZ: <ScaleXYZ>.x_scale <ScaleXYZ>.y_scale <ScaleXYZ>.z_scale
Methods: getXYZControllers
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.
1337
1338
Chapter 11
|
3ds max Objects
Atmospheric Effects Common Properties, Operators, and Methods Atmospherics have the following common properties and methods: Properties: .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. .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
Returns true if the atmospheric is set to active; false otherwise. getGizmo
Retrieves the indexed gizmo node from the atmospheric. The gizmo node will be a light or atmospheric helper. The Index is 1-based. deleteGizmo
Deletes the indexed gizmo from the atmospheric. appendGizmo <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
Sets the atmospheric active or inactive. If 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
Appends the atmospheric to the Atmospheric Effects list getAtmospheric
Retrieves the atmospheric at the indexed position in the Atmospheric Effects list. Index is 1-based. setAtmospheric
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
Deletes the atmospheric at the indexed position in the Atmospheric Effects list. Index is 1based.
Fire_Effect : Atmospheric
editAtmosphere <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 [ gizmo: <node> ]
Opens the Environment dialog, and opens the rollout for the specified atmospheric if it has been added to the Atmospheric Effects list. If the optional gizmo: argument is specified, and the specified node is a gizmo for the atmospheric, that gizmo is selected in the atmospheric’s gizmo list. The 3ds max global variable numAtmospherics gives you the number of current atmospherics in the rendering environment. Note: Unlike most MAXWrapper objects, you can not copy an Atmospheric.
See also MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714) Example: atmos = combust density:20 outer_color:red appendGizmo atmos $SphereGizmo01
Atmospheric Effect Types The following list shows the 3ds max Atmospheric Effect types: Fire_Effect (p. 1339) Fog (p. 1342) Volume_Fog (p. 1343) Volume_Light (p. 1344)
Fire_Effect : Atmospheric Constructor: Fire_Effect ...
Properties: .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.
1339
1340
Chapter 11
|
3ds max Objects
.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. .Smoke_Color
Color
default: (color 25.5 25.5 25.5)
-- animatable
Sets the color of smoke for use with the Explosion option. .Flame_Type
Integer
default: 0
Sets the flame type: Fire Ball (Creates round puffy flames. Fireballs are well suited for explosions.) Tendril (Creates directional pointed flames with veins along their center. The flames orient along the local Z axis of the fire apparatus. Tendril creates campfire-like flames.) .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. .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. .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. .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. .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. .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. .phase
Float
default: 0.0
Controls the rate of change for the fire effect.
-- animatable
Setting explosion start and end times for 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. .Explosion
Integer
default: 0
When on, animates size, density, and color automatically based on the animation of the phase value. OFF ON .Smoke
Integer
default: 1
Controls whether or not the explosion creates smoke. OFF ON .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
1341
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_Color .Use_Color_Map
Color Integer
default: (color 255 255 255) default: 0
-- animatable
Use_Color_Map = 0 - off; 1 - on .Use_Opacity_Map
Integer
default: 0
Use_Opacity_Map = 0 - off; 1 - on .Fog_Background
Integer
default: 1
Fog_Background = 0 - off; 1 - on .Fog_Type
Integer
default: 0
Fog_Type = 0 - Standard; 1 - Layered .Exponential
Integer
default: 0
Exponential = 0 - off; 1 - on .Near .Far .Top .Bottom .Density .falloff
Float Float Float Float Float Integer
default: default: default: default: default: default:
0.0 100.0 100.0 0.0 50.0 2
------
animatable, percentage animatable, percentage animatable animatable animatable
falloff = 0 - Top; 1 - Bottom; 2 - None .Horizon_Noise
Integer
default: 0
Horizon_Noise = 0 - off; 1 - on .size .angle .phase
Float Float Float
default: 20.0 default: 5.0 default: 0.0
-- animatable -- animatable, angle -- animatable
Note: You currently cannot assign texture maps as the color and opacity maps using MAXScript. Once these texture maps have been assigned, they are accessible as subAnims of Fog.
Volume_Fog : Atmospheric
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: .Soften_Gizmo_Edges .Fog_Color animatable .Exponential
Float Color
default: 0.2 -- animatable default: (color 255 255 255)
Integer
default: 0
Float Float Integer Integer
default: default: default: default:
Integer
default: 0
Exponential = 0 - off; 1 - on .Density .Step_Size .Max_Steps .Fog_Background
20.0 4.0 100 1
-- animatable
Fog_Background = 0 - off; 1 - on .Noise_Type
Noise_Type = 0 - Regular; 1 - Fractal; 2 - Turbulence .invert
Integer
default: 0
Float Float Float Float Float Float Float Integer
default: default: default: default: default: default: default: default:
invert = 0 - off; 1 - on .High_Threshold .Low_Threshold .Uniformity .Levels .size .phase .Wind_Strength .Wind_Direction
1.0 0.0 0.0 3.0 20.0 0.0 0.0 0
-------
animatable animatable animatable animatable animatable animatable
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)
--
1343
1344
Chapter 11
|
3ds max Objects
Volume_Light : Atmospheric Constructor: volume_light ...
Properties: .Fog_Color 255) -- animatable .attenuation_color 255) -- animatable .Exponential
Color
default: (color 255 255
Color
default: (color 0 0
Integer
default: 0
Float
default: 5.0
--
Float
default: 90.0
--
Float
default: 0.0
--
Integer
default: 0
Float
default: 2.0
Integer
default: 3
Exponential = 0 - off; 1 - on .Density animatable .Max_Light animatable .Min_Light animatable .Use_Attenuation_Color
Use_Attenuation_Color = 0 - off; 1 - on .Attenuation_Color_Multiplier animatable .Filter_Shadows
--
Filter_Shadows = 0 - Low; 1 - Medium; 2 - High; 3 - Use Light Smp Range .Samples .Auto_Sample
Integer Integer
default: 20 default: 1
Float
default: 100.0
--
Float
default: 100.0
--
Integer
default: 0
Float
default: 0.0
Integer
default: 0
Integer
default: 0
Auto_Sample = 0 - off; 1 - on .Atten_Start animatable .Atten_End animatable .Noise_On
Noise_On = 0 - off; 1 - on .Noise_Amount animatable .Link_To_Light
--
Link_To_Light = 0 - off; 1 - on .Noise_Type
Noise_Type = 0 - Regular; 1 - Fractal; 2 - Turbulence .invert invert = 0 - off; 1 - on .High_Threshold animatable .Low_Threshold animatable
Integer
default: 0
Float
default: 1.0
--
Float
default: 0.0
--
Volume_Light : Atmospheric
.Uniformity animatable .Levels animatable .size animatable .phase animatable .Wind_Strength .Wind_Direction
Float
default: 0.0
--
Float
default: 3.0
--
Float
default: 20.0
--
Float
default: 0.0
--
Float Integer
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.
1345
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
Lets you get and set the global rendering environment (Rendering\Environment) Use Map value. If is true Use Map is turned on, false it is turned off. getBackGroundController()
Returns the global rendering environment (Rendering\Environment) background color controller. setBackGround <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 ( | <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
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: .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
Adds the render effect to the Rendering/Effects dialog list.
1347
1348
Chapter 11
|
3ds max Objects
setActive
Sets the render effect active or inactive. If 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
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
Retrieves the render effect at the indexed position in the Rendering/Effects dialog list. The index is 1-based. editEffect [ gizmo: <node> ]
Opens the Rendering/Effects dialog, and opens the rollout for the specified render effect if it has been added to the Render Effects list. If the optional gizmo: argument is specified, and the specified node is a gizmo for the render effect, that gizmo is selected in the render effect’s gizmo list. setEffect
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
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
File Output Effect (p. 1356) Film Grain (p. 1356) Lens Effects (p. 1357)
Blur : RenderEffect Constructor: blur ...
Properties: .blur_type
Integer
default: 0
Float
default: 10.0
-- animatable
Select a blur type: Uniform Directional Radial .bUnifPixRad
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. .bUnifAlpha
Boolean
default: true
-- animatable
Applies the Uniform Blur effect to the alpha channel when turned on. .bDirUPixRad
Float
default: 10.0
Determines the horizontal intensity of the Blur effect. Increasing the value increases the number of surrounding pixels that each pixel will use to compute its blur. The more pixels used means a greater horizontal blur for the image. .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. .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. .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.
1349
1350
Chapter 11
|
3ds max Objects
.bDirRotation
Integer
default: 0
Rotates the axis of the U and V pixels that will be blurred by the U and V Pixel Radius spinners. By using Rotation with the U and V Pixel Radius spinners you can have the Blur effect applied to any direction in your rendered image. When rotation is 0, U corresponds to the image’s X-axis and V corresponds to the image’s Y-axis. .bDirAlpha
Boolean
default: true
-- animatable
Applies the Directional Blur effect to the Alpha channel when turned on. .bRadialPixRad
Float
default: 20.0
Determines the intensity of the Radius Blur effect. Increasing the value increases the number of surrounding pixels that each pixel will use to compute its blur. The more pixels used means a greater blur for the image. .bRadialXOrig
Integer
default: 320
Sets the origin for the radial blur effect along the X axis. .bRadialYOrig
Integer
default: 240
Sets the origin for the radial blur effect along the Y axis. axis..bRadialTrail
Float
default: 0.0
Adds “direction” to your blur by weighting more or less blur towards the center of the Blur effect. This adds a streaking effect and creates the illusion that your objects or your camera are rapidly moving in a particular direction. .bRadialAlpha
Boolean
default: true
-- animatable
Applies the Radial Blur effect to the Alpha channel when turned on. .bRadialNode
Node
default: undefined
Node to which radial blur is assigned. .bRadialUseNode
Boolean
default: false
Turn on/off use object center for selected node, bradialnode. .selImageActive
Boolean
default: true
-- animatable
When on, the blur affects the entire rendered image. This is useful when the blur effect dims your rendered image. .selImageBrighten
Float
default: 0.0
Brightens the entire image. .selImageBlend
Float
default: 100.0
Blends the Blur effect and the Whole Image parameters with the original rendered image. This can be used to create a soft-focus effect. .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. .selIBackBrighten
Float
default: 0.0
Brightens the rendered image except for the background image or animation. .selIBackBlend
Float
default: 100.0
Blends the Blur effect and the Non-Background parameters with the original rendered image.
Blur : RenderEffect
.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. .selLumActive
Boolean
default: false
Affects any pixels that have luminance values that fall between it’s Min and Max values, selLumMin & selLumMax. .selLumBrighten
Float
default: 0.0
Brightens pixels that fall between the Minimum and Maximum luminance values. .selLumBlend
Float
default: 100.0
Blends the Blur effect and the Luminance parameters with the original rendered image. .selLumMin
Float
default: 90.0
The minimum luminance value necessary for each pixel in order for the Blur effect to be applied to the pixel. .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. .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. .selMaskActive
Boolean
default: false
When turned on, applies the Blur effect according to the channel selected and mask applied through the Material/Map Browser. .selMaskMap
TextureMap
default: undefined
Map assigned to the blur effect. .selMaskChannel select_mask_channel
Integer
default: 4
-- alias:
Selects a channel that the Blur effect will be applied to: Red Blue Green Alpha Luminance .selMaskBrighten
Float
default: 0.0
Brightens the portions of the image that the Blur effect is applied to. .selMaskBlend
Float
default: 100.0
Blends the Map Mask Blur effect with the original rendered image. .selMaskMin
Float
default: 90.0
The minimum value (RGB, Alpha, or Luminance) a pixel must have in order to have the Blur effect applied to it.
1351
1352
Chapter 11
|
3ds max Objects
.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. .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. .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. .selObjIdsIds
Array
default: #()
--
int array
This array contains all of the Object ID’s to which the blur effects will be applied. .selObjIdsBrighten
Float
default: 0.0
--
animatable
Brightens the portion of the image that the Object ID-specific Blur effect is applied to. .selObjIdsBlend
Float
default: 100.0
--
animatable
Blends the Object ID Blur effect with the original rendered image. .selObjIdsFRadius
Float
default: 10.0
--
animatable
Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum luminance values. .selObjIdsLumMin
Float
default: 0.0
--
animatable
The minimum luminance value a pixel must have in order to have the Blur effect applied to it. .selObjIdsLumMax
Float
default: 100.0
--
animatable
The maximum luminance value a pixel can have for the Blur effect to be applied to it. .selMatIdsActive
Boolean
default: false
--
animatable
Applies the Blur effect to a material or part of a material with a specific material effects channel, if the material matches the Filter settings. .selMatIdsIds
Array
default: #()
--
int array
This array contains all of the Material ID’s to which the blur effects will be applied. .selMatIdsBrighten
Float
default: 0.0
--
animatable
Brightens the portion of the image that the Blur effect is applied to. .selMatIdsBlend
Float
default: 100.0
--
animatable
Blends the Material ID Blur effect with the original rendered image. .selMatIdsFRadius
Float
default: 10.0
--
animatable
Feathers the Blur effect applied to pixels that fall between the Minimum and Maximum luminance values. .selMatIdsLumMin
Float
default: 0.0
--
animatable
The minimum luminance value a pixel must have in order to have the Blur effect applied to it. .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
.selGenBrightType
Integer
default: 1
--
animatable
Selects the type of brightening applied to the feather falloff curve: Additive Multiplicative .select_falloff_curve SubAnim .curve_1
default: SubAnim:Select_Falloff_Curve SubAnim default: SubAnim:Curve_1
The brightening curve for the feather falloff. .curve_2
SubAnim
default: SubAnim:Curve_2
The blend curve for the feather falloff.
See also Render Effects Common Properties, Operators, and Methods (p. 1347) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Brightness_and_Contrast : RenderEffect Constructor: brightness_and_contrast ...
Properties: .Brightness .contrast .ignoreBack alias: ignore_background
Float Float Boolean
default: 0.5 default: 0.5 default: false
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)
-- animatable -- animatable -- animatable,
1353
1354
Chapter 11
|
3ds max Objects
Color_Balance : RenderEffect Constructor: color_balance ...
Properties: .red .green .blue .preserveLum Preserve_Luminosity .ignoreBack Ignore_Background
Integer Integer Integer Boolean
default: default: default: default:
0 0 0 false
Boolean
default: false
-----
animatable animatable animatable animatable, alias:
-- 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: .AffectAlpha .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. .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. .FocalPoint
Integer
default: 0
-- alias: Focal_Point
default: 0
-- alias: Focal_Type
FocalPoint = 0 - Focal Node; 1 - Use Camera .FocalType
Integer
FocalType = 0 - Custom; 1 - Use Camera
Depth_of_Field : RenderEffect
.HorizFocalLoss Horiz_Focal_Loss .VertFocalLoss Vert_Focal_Loss .FocalRange Focal_Range .FocalLimit Focal_Limit
Float
default: 10.0
-- animatable, alias:
Float
default: 10.0
-- animatable, alias:
Float
default: 100.0 -- animatable, alias:
Float
default: 200.0 -- animatable, alias:
Methods: DOF.addCam
Adds the specified camera to the Depth of Field camera dropdown. camera_node_name_string is the name of the camera as a string, and must match the case of the camera’s name. Returns true if the addition was successful, false if it failed. The normal reason for a failure is that the named camera is not present in the scene. DOF.addFocalNode <node_name_string>
Adds the specified node to the Depth of Field focal point node dropdown. node_name_string is the name of the node as a string, and must match the case of the node’s name. Returns true if the addition was successful, false if it failed. The normal reason for a failure is that the named node is not present in the scene. DOF.deleteCam
Deletes the indexed camera from the Depth of Field camera dropdown, where 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
Deletes the specified camera from the Depth of Field camera dropdown. camera_node_name_string is the name of the camera as a string, and must match the case of the camera’s name. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the named camera is not present in the dropdown. DOF.deleteFocalNode
Deletes the indexed node from the Depth of Field focal point node dropdown, where 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 <node_name_string>
Deletes the specified node from the Depth of Field focal point node dropdown. node_name_string is the name of the node as a string, and must match the case of the node’s name. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the named node is not present in the dropdown.
1355
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: .bitmap .channelType
BitMap Integer
default: BitMap: default: 0
-- output bitmap -- alias: channel_type
channelType = 0 - Whole Image; 1 - Luminance; 2 - Depth; 3 - Alpha .active .affectSource affect_source .cameraNode .nearZ near_z_depth .farZ far_z_depth .fitScene fit_entire_scene
Boolean Boolean
default: true default: false
-- animatable -- animatable, alias:
Node Float
default: undefined default: 0.0
-- alias: camera_node -- animatable, alias:
Float
default: -500.0
-- animatable, alias:
Boolean
default: true
-- 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)
Film_Grain : RenderEffect Constructor: film_grain ...
Properties: .Grain Float .’Mask Background’ Boolean Ignore_Background
default: 0.2 default: false
-- animatable -- animatable; alias:
Lens_Effects : RenderEffect
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: .size .intensity .seed .angle .squeeze .affectAlpha Affect_Alpha .affectZBuffer Affect_Z_Buffer .distAffectsSize Distance_Affects_Size .distAffectsIntensity Distance_Affects_Intensity .centerAffectsSize Off_Center_Affects_Size .centerAffectsIntensity Off_Center_Affects_Intensity .innerOcclusionRadius alias: Inner_Occlusion_Radius .outerOcclusionRadius alias: Outer_Occlusion_Radius .occlusionAffectsSize Occlusion_Affects_Size .occlusionAffectsIntensity Occlusion_Affects_Intensity .affectByAtmosphere Affect_By_Atmosphere
Float Float Integer Float Float Boolean
default: default: default: default: default: default:
100.0 100.0 1357 0.0 0.0 true
-- animatable -- animatable
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Float
default: 3.0
-- animatable,
Float
default: 33.0
-- animatable,
Boolean
default: true
-- alias:
Boolean
default: true
-- alias:
Boolean
default: false
-- alias:
-- animatable -- animatable -- alias:
1357
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
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
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
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
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
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
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
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 le.save
Saves the Lens Effects configuration to the file specified by . Animated parameter values are not saved. le.numLights
Returns the number of lights in the light list. le.addLightNode
Adds light node to the light list. le.addLight
Adds the specified light to the Lens Effects Lights dropdown. light_node_name_string is the name of the light as a string, and must match the case of the light’s name. Returns true if the addition was successful, false if it failed. The normal reason for a failure is that the named light is not present in the scene. le.deleteLight
Deletes the indexed light from the Lens Effects Lights dropdown, where 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
le.deleteLightByName
Deletes the named light from the Lens Effects Lights dropdown. light_node_name_string is the name of the light as a string, and must match the case of the light’s name. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the named light is not present in the dropdown. le.lightIndex
Returns the light list index of the named light. Returns –1 if the light’s name is not in the light list. le.lightName
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
Deletes the indexed element, where is the index of the element in the Lens Effects composition window. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the indexed element does not exist. le.deleteElementByName <element_name_string>
Deletes the named element. element_name_string is the name of the element as a string, and must match the case of the element’s name. Returns true if the deletion was successful, false if it failed. The normal reason for a failure is that the named element does not exist.
See also Lens_Effects - Auto_Secondary (p. 1360) Lens_Effects - Glow (p. 1363) Lens_Effects - Manual_Secondary (p. 1366) Lens_Effects - Ray (p. 1370) Lens_Effects - Ring (p. 1373) Lens_Effects - Star (p. 1376) Lens_Effects - Streak (p. 1379) Render Effects Common Properties, Operators, and Methods (p. 1347) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
1359
1360
Chapter 11
|
3ds max Objects
Lens_Effects - Auto_Secondary Constructor: le.addASec
Properties: .elementName alias: Name .on .minSize animatable; alias: Min_Size .maxSize animatable; alias: Max_Size .axis animatable .intensity animatable .quantity animatable .colorSource animatable; alias: Source_Color .sides
String
default: “Auto Secondary” --
Boolean Float
default: true default: 25.0
--
Float
default: 100.0
--
Float
default: 3.0
--
Float
default: 30.0
--
Integer
default: 12
--
Float
default: 20.0
--
Integer
default: 0
sides = 0 - Circular; 1 - Three; 2 - Four; 3 - Five; 4 - Six; 5 - Seven; 6 - Eight .occlusion animatable .presets
Float
default: 100.0
Integer
default: 0
--
presets selects a preset from the indexed list. presets = 0 - no preset. .squeeze .radialColor1 animatable; alias: Radial_Color_1 .radialColor2 animatable; alias: Radial_Color_2 .radialColor3 animatable; alias: Radial_Color_3 .radialColor4 animatable; alias: Radial_Color_4 .colorRadius1 animatable; alias: Radius_Color_1 .colorRadius2 animatable; alias: Radius_Color_2 .colorRadius3 animatable; alias: Radius_Color_3 .colorRadius4 animatable; alias: Radius_Color_4 .radialMtl Radial_Material .useRadialMtl Apply_Radial_Color_Map .radial_falloff
Boolean Color
default: false default: (color 0 0 0) --
Color
default: (color 57 34 89) --
Color
default: (color 85 139 85) --
Color
default: (color 190 99 10) --
Float
default: 90.0
--
Float
default: 92.0
--
Float
default: 95.0
--
Float
default: 98.0
--
TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
SubAnim
Lens_Effects - Auto_Secondary
.radialMap Radial_Falloff_Map .useRadialMap Apply_Radial_Falloff_Map .circularColorMix animatable; alias: Circular_Color_Mix .quadrant1Color animatable; alias: Quadrant_1_Color .quadrant2Color animatable; alias: Quadrant_2_Color .quadrant3Color animatable; alias: Quadrant_3_Color .quadrant4Color animatable; alias: Quadrant_4_Color .circularMtl Circular_Material .useCircularMtl Apply_Circular_Color_Map .circular_falloff .circularMap Circular_Falloff_Map .useCircularMap Apply_Circular_Falloff_Map .radial_size .radialSizeMap Radial_Size_Map .useRadialSizeMap Apply_Radial_Size_Map .applyLights Apply_to_Lights .applyImage Apply_to_Image .applyImageCenters Apply_to_Image_Centers .sourceObjectID Source_Object_ID .objectID animatable; alias: Object_ID .sourceEffectsID Source_Effects_ID .effectsID animatable; alias: Effects_ID .sourceUnclampedColor Source_Unclamped_Color .unclampedColor animatable; alias: Unclamped_Color .unclampedColorInvert Source_Unclamped_Color_Invert .sourceSurfaceNormal Source_Surface_Normal
TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
Float
default: 0.0
--
Color
default: (color 255 0 0)
--
Color
default: (color 255 0 0)
--
Color
default: (color 255 0 0)
--
Color
default: (color 255 0 0)
--
TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
SubAnim TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
SubAnim TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
Boolean
default: true
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer
default: 1
--
Boolean
default: false
-- alias:
Integer
default: 0
--
Boolean
default: false
-- alias:
Float
default: 1.0
--
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
1361
1362
Chapter 11
|
3ds max Objects
.surfaceNormal animatable; alias: Surface_Normal .surfaceNormalInvert Source_Surface_Normal_Invert .sourceWhole Source_Whole .sourceAlpha Source_Alpha .alpha .sourceZBuffer Source_Z_Buffer .zHi animatable; alias: Z_Hi .zLo animatable; alias: Z_Lo .filterAll Filter_All .filterEdge Filter_Edge .filterPerimeterAlpha Filter_Perimeter_Alpha .filterPerimeter Filter_Perimeter .filterBrightness Filter_Brightness .brightness animatable; alias: Bright .brightnessInvert Filter_Brightness_Invert .filterHue Filter_Hue .hueRange animatable; alias: Hue_Range .hue animatable .applyNoise Apply_Additional_Effects .noiseMap Noise_Map .radial_density .radialDensity Radial_Density_Map .useRadialDensity Apply_Radial_Density_Map .curve_1
Float
default: 0.0
--
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer Boolean
default: 0 default: false
-- alias:
Float
default: 1000.0
--
Float
default: 0.0
--
Boolean
default: true
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer
default: 0
--
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer
default: 0
--
Color
default: (color 255 0 0) --
Boolean
default: false
-- alias:
TextureMap
default: undefined
-- alias:
SubAnim TextureMap
default: undefined
-- alias:
Boolean
default: false
-- 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
.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. .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. .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 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
Properties: .elementName String .on Boolean .size Float .intensity Float .objectsHide Boolean .occlusion Float .squeeze Boolean .useSourceColor Float Source_Color .centerColor Color animatable; alias: Center_Color .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;
1363
1364
Chapter 11
|
3ds max Objects
.radialMtl Radial_Material .useRadialMtl Apply_Radial_Color_Map .radial_falloff .radialMap Radial_Falloff_Map .useRadialMap Apply_Radial_Falloff_Map .circularColorMix Circular_Color_Mix .quadrant1Color alias: Quadrant_1_Color .quadrant2Color alias: Quadrant_2_Color .quadrant3Color alias: Quadrant_3_Color .quadrant4Color alias: Quadrant_4_Color .circularMtl Circular_Material .useCircularMtl Apply_Circular_Color_Map .circular_falloff .circularMap Circular_Falloff_Map .useCircularMap Apply_Circular_Falloff_Map .radial_size .radialSizeMap Radial_Size_Map .useRadialSizeMap Apply_Radial_Size_Map .applyLights Apply_to_Lights .applyImage Apply_to_Image .applyImageCenters Apply_to_Image_Centers .sourceObjectID Source_Object_ID .objectID Object_ID .sourceEffectsID Source_Effects_ID .effectsID Effects_ID .sourceUnclampedColor Source_Unclamped_Color .unclampedColor Unclamped_Color
TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
SubAnim TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
Float
default: 0.0
-- animatable; alias:
Color
default: (color 255 0 0) -- animatable;
Color
default: (color 255 0 0) -- animatable;
Color
default: (color 255 0 0) -- animatable;
Color
default: (color 255 0 0) -- animatable;
TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
SubAnim TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
SubAnim TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
Boolean
default: true
-- alias:
Boolean
default: true
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer
default: 1
-- animatable; alias:
Boolean
default: false
-- alias:
Integer
default: 1
-- animatable; alias:
Boolean
default: false
-- alias:
Float
default: 1.0
-- animatable; alias:
Lens_Effects - Glow
.unclampedColorInvert Boolean Source_Unclamped_Color_Invert .sourceSurfaceNormal Boolean Source_Surface_Normal .surfaceNormal Float Surface_Normal .surfaceNormalInvert Boolean Source_Surface_Normal_Invert .sourceWhole Boolean Source_Whole .sourceAlpha Boolean Source_Alpha .alpha Integer .sourceZBuffer Boolean Source_Z_Buffer .zHi Float Z_Hi .zLo Float Z_Lo .filterAll Boolean .filterEdge Boolean .filterPerimeterAlpha Boolean Filter_Perimeter_Alpha .filterPerimeter Boolean Filter_Perimeter .filterBrightness Boolean Filter_Brightness .brightness Integer Bright .brightnessInvert Boolean Filter_Brightness_Invert .filterHue Boolean .hueRange Integer Hue_Range .hue Color .applyNoise Boolean Apply_Additional_Effects .noiseMap TextureMap .radial_density SubAnim .radialDensity TextureMap Radial_Density_Map .useRadialDensity Boolean Apply_Radial_Density_Map .curve_1
default: false
-- alias:
default: false
-- alias:
default: 0.0
-- animatable; alias:
default: false
-- alias:
default: false
-- alias:
default: false
-- alias:
default: 0 default: false
-- animatable -- alias:
default: 1000.0
-- animatable; alias:
default: 0.0
-- animatable; alias:
default: true default: false default: false
-- alias: Filter_All -- alias: Filter_Edge -- alias:
default: false
-- alias:
default: false
-- alias:
default: 0
-- animatable; alias:
default: false
-- alias:
default: false default: 0
-- alias: Filter_Hue -- animatable; alias:
default: (color 255 0 0) -- animatable default: false -- alias: default: undefined
-- alias: Noise_Map
default: undefined
-- alias:
default: false
-- 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.
1365
1366
Chapter 11
|
3ds max Objects
.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. .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. .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 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
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
default: “Manual
Boolean Float
default: true default: 50.0
--
Float
default: 30.0
--
Float
default: 150.0
--
Float
default: 20.0
--
Integer
default: 0
sides = 0 - Circular; 1 - Three; 2 - Four; 3 - Five; 4 - Six; 5 - Seven; 6 - Eight
Lens_Effects - Manual_Secondary
<manual_secondary>.occlusion animatable <manual_secondary>.squeeze <manual_secondary>.presets
Float
default: 100.0
Boolean Integer
default: false default: 0
--
presets selects a preset from the indexed list. presets = 0 - no preset. <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
Color
default: (color 0 0 0) --
Color
default: (color 57 34 89) --
Color
default: (color 85 139 85) --
Color
default: (color 190 99 10) --
Float
default: 90.0
--
Float
default: 92.0
--
Float
default: 95.0
--
Float
default: 98.0
--
TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
SubAnim TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
Float
default: 0.0
--
Color
default: (color 255 0 0) --
Color
default: (color 255 0 0) --
Color
default: (color 255 0 0) --
Color
default: (color 255 0 0) --
TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
SubAnim TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
SubAnim
1367
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
default: undefined
-- alias:
Boolean
default: false
-- alias:
Boolean
default: true
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer
default: 1
--
Boolean
default: false
-- alias:
Integer
default: 0
--
Boolean
default: false
-- alias:
Float
default: 1.0
--
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Float
default: 0.0
--
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer Boolean
default: 0 default: false
-- alias:
Float
default: 1000.0
--
Float
default: 0.0
--
Boolean
default: true
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Lens_Effects - Manual_Secondary
<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
Integer
default: 0
--
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer
default: 0
--
Color
default: (color 255 0 0) --
Boolean
default: false
-- alias:
TextureMap
default: undefined
-- alias:
SubAnim TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
<manual_secondary.radial_falloff>.curve_1
SubAnim
The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. <manual_secondary.circular_falloff>.curve_1
SubAnim
The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. <manual_secondary.radial_size>.curve_1
SubAnim
The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. <manual_secondary.radial_density>.curve_1
SubAnim
The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. Note: The le.addMSec 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.
1369
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
Properties: .elementName .on .size .intensity .number Quantity .angle .sharpness .objectsHide .occlusion .squeeze .colorSource Source_Color .centerColor alias: Center_Color .edgeColor alias: Edge_Color .radialMtl Radial_Material .useRadialMtl Apply_Radial_Color_Map .radial_falloff .radialMap Radial_Falloff_Map .useRadialMap Apply_Radial_Falloff_Map .circularColorMix Circular_Color_Mix .quadrant1Color alias: Quadrant_1_Color .quadrant2Color alias: Quadrant_2_Color .quadrant3Color alias: Quadrant_3_Color .quadrant4Color alias: Quadrant_4_Color .circularMtl Circular_Material
String Boolean Float Float Integer
default: default: default: default: default:
“Ray” true 300.0 10.0 100
-- alias: Name
Float Float Boolean Float Boolean Float
default: default: default: default: default: default:
0.0 8.0 false 100.0 false 100.0
Color
default: (color 255 255 255) -- animatable;
Color
default: (color 255 0 0) -- animatable;
TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
SubAnim TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
Float
default: 0.0
-- animatable; alias:
Color
default: (color 255 0 0) -- animatable;
Color
default: (color 255 0 0) -- animatable;
Color
default: (color 255 0 0) -- animatable;
Color
default: (color 255 0 0) -- animatable;
TextureMap
default: undefined
-- animatable -- animatable -- animatable; alias: -- animatable -- animatable -- animatable -- animatable; alias:
Lens_Effects - Ray
.useCircularMtl Boolean Apply_Circular_Color_Map .circular_falloff SubAnim .circularMap TextureMap Circular_Falloff_Map .useCircularMap Boolean Apply_Circular_Falloff_Map .radial_size SubAnim .radialSizeMap TextureMap Radial_Size_Map .useRadialSizeMap Boolean Apply_Radial_Size_Map .applyLights Boolean Apply_to_Lights .applyImage Boolean Apply_to_Image .applyImageCenters Boolean Apply_to_Image_Centers .sourceObjectID Boolean Source_Object_ID .objectID Integer Object_ID .sourceEffectsID Boolean Source_Effects_ID .effectsID Integer Effects_ID .sourceUnclampedColor Boolean Source_Unclamped_Color .unclampedColor Float Unclamped_Color .unclampedColorInvert Boolean Source_Unclamped_Color_Invert .sourceSurfaceNormal Boolean Source_Surface_Normal .surfaceNormal Float Surface_Normal .surfaceNormalInvert Boolean Source_Surface_Normal_Invert .sourceWhole Boolean .sourceAlpha Boolean .alpha Integer .sourceZBuffer Boolean Source_Z_Buffer .zHi Float Z_Hi .zLo Float Z_Lo .filterAll Boolean .filterEdge Boolean .filterPerimeterAlpha Boolean Filter_Perimeter_Alpha
default: false
-- alias:
default: undefined
-- alias:
default: false
-- alias:
default: undefined
-- alias:
default: false
-- alias:
default: true
-- alias:
default: true
-- alias:
default: false
-- alias:
default: false
-- alias:
default: 1
-- animatable; alias:
default: false
-- alias:
default: 1
-- animatable; alias:
default: false
-- alias:
default: 1.0
-- animatable; alias:
default: false
-- alias:
default: false
-- alias:
default: 0.0
-- animatable; alias:
default: false
-- alias:
default: default: default: default:
-----
false false 0 false
alias: Source_Whole alias: Source_Alpha animatable alias:
default: 1000.0
-- animatable; alias:
default: 0.0
-- animatable; alias:
default: true default: false default: false
-- alias: Filter_All -- alias: Filter_Edge -- alias:
1371
1372
Chapter 11
|
3ds max Objects
.filterPerimeter Filter_Perimeter .filterBrightness Filter_Brightness .brightness Bright .brightnessInvert Filter_Brightness_Invert .filterHue .hueRange Hue_Range .hue .applyNoise Apply_Additional_Effects .noiseMap .radial_density .radialDensity Radial_Density_Map .useRadialDensity Apply_Radial_Density_Map
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer
default: 0
-- animatable; alias:
Boolean
default: false
-- alias:
Boolean Integer
default: false default: 0
-- alias: Filter_Hue -- animatable; alias:
Color Boolean
default: (color 255 0 0) -- animatable default: false -- alias:
TextureMap SubAnim TextureMap
default: undefined
-- alias: Noise_Map
default: undefined
-- alias:
Boolean
default: false
-- alias:
.curve_1
SubAnim
The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. .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. .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. .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 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
See also Lens_Effects : RenderEffect (p. 1357) Value Common Properties, Operators, and Methods (p. 714)
Lens_Effects - Ring Constructor: le.addRing
Properties: .elementName String .on Boolean .size Float .intensity Float .plane Float .thickness Float .objectsHide Boolean .occlusion Float .squeeze Boolean .colorSource Float Source_Color .centerColor Color animatable; alias: Center_Color .edgeColor Color alias: Edge_Color .radialMtl TextureMap Radial_Material .useRadialMtl Boolean Apply_Radial_Color_Map .radial_falloff SubAnim .radialMap TextureMap Radial_Falloff_Map .useRadialMap Boolean Apply_Radial_Falloff_Map .circularColorMix Float Circular_Color_Mix .quadrant1Color Color alias: Quadrant_1_Color .quadrant2Color Color alias: Quadrant_2_Color .quadrant3Color Color alias: Quadrant_3_Color .quadrant4Color Color alias: Quadrant_4_Color .circularMtl TextureMap Circular_Material .useCircularMtl Boolean Apply_Circular_Color_Map .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
-- alias:
default: false
-- alias:
default: undefined
-- alias:
default: false
-- alias:
default: 0.0
-- 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
-- alias:
default: false
-- alias:
1373
1374
Chapter 11
|
3ds max Objects
.circularMap TextureMap Circular_Falloff_Map .useCircularMap Boolean Apply_Circular_Falloff_Map .radial_size SubAnim .radialSizeMap TextureMap Radial_Size_Map .useRadialSizeMap Boolean Apply_Radial_Size_Map .applyLights Boolean Apply_to_Lights .applyImage Boolean Apply_to_Image .applyImageCenters Boolean Apply_to_Image_Centers .sourceObjectID Boolean Source_Object_ID .objectID Integer Object_ID .sourceEffectsID Boolean Source_Effects_ID .effectsID Integer Effects_ID .sourceUnclampedColor Boolean Source_Unclamped_Color .unclampedColor Float Unclamped_Color .unclampedColorInvert Boolean Source_Unclamped_Color_Invert .sourceSurfaceNormal Boolean Source_Surface_Normal .surfaceNormal Float Surface_Normal .surfaceNormalInvert Boolean Source_Surface_Normal_Invert .sourceWhole Boolean Source_Whole .sourceAlpha Boolean Source_Alpha .alpha Integer .sourceZBuffer Boolean Source_Z_Buffer .zHi Float Z_Hi .zLo Float Z_Lo .filterAll Boolean .filterEdge Boolean .filterPerimeterAlpha Boolean Filter_Perimeter_Alpha
default: undefined
-- alias:
default: false
-- alias:
default: undefined
-- alias:
default: false
-- alias:
default: true
-- alias:
default: true
-- alias:
default: false
-- alias:
default: false
-- alias:
default: 1
-- animatable; alias:
default: false
-- alias:
default: 1
-- animatable; alias:
default: false
-- alias:
default: 1.0
-- animatable; alias:
default: false
-- alias:
default: false
-- alias:
default: 0.0
-- animatable; alias:
default: false
-- alias:
default: false
-- alias:
default: false
-- alias:
default: 0 default: false
-- animatable -- alias:
default: 1000.0
-- animatable; alias:
default: 0.0
-- animatable; alias:
default: true default: false default: false
-- alias: Filter_All -- alias: Filter_Edge -- alias:
Lens_Effects - Ring
.filterPerimeter Filter_Perimeter .filterBrightness Filter_Brightness .brightness Bright .brightnessInvert Filter_Brightness_Invert .filterHue .hueRange Hue_Range .hue .applyNoise Apply_Additional_Effects .noiseMap .radial_density .radialDensity Radial_Density_Map .useRadialDensity Apply_Radial_Density_Map
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer
default: 0
-- animatable; alias:
Boolean
default: false
-- alias:
Boolean Integer
default: false default: 0
-- alias: Filter_Hue -- animatable; alias:
Color Boolean
default: (color 255 0 0) -- animatable default: false -- alias:
TextureMap SubAnim TextureMap
default: undefined
-- alias: Noise_Map
default: undefined
-- alias:
Boolean
default: false
-- alias:
.curve_1
SubAnim
The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. .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. .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. .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 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.
1375
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
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:
“Star” true 200.0 20.0 8.0 0.0 0.5 9.5
default: default: default: default: default:
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
-- alias:
default: false
-- alias:
default: undefined
-- alias:
default: false
-- alias:
default: 0.0
-- 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
<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
-- alias:
default: false
-- alias:
default: undefined
-- alias:
default: false
-- alias:
default: true
-- alias:
default: true
-- alias:
default: false
-- alias:
default: false
-- alias:
default: 1
-- animatable; alias:
default: false
-- alias:
default: 1
-- animatable; alias:
default: false
-- alias:
default: 1.0
-- animatable; alias:
default: false
-- alias:
default: false
-- alias:
default: 0.0
-- animatable; alias:
default: false
-- alias:
default: false
-- alias:
default: false
-- alias:
default: 0 default: false
-- animatable -- alias:
default: 1000.0
-- animatable; alias:
default: 0.0
-- animatable; alias:
default: true default: false
-- alias: Filter_All -- alias: Filter_Edge
1377
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
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer
default: 0
-- animatable; alias:
Boolean
default: false
-- alias:
Boolean Integer
default: false default: 0
-- alias: Filter_Hue -- animatable; alias:
Color Boolean
default: (color 255 0 0) -- animatable default: false -- alias:
TextureMap SubAnim TextureMap
default: undefined
-- alias: Noise_Map
default: undefined
-- alias:
Boolean
default: false
-- alias:
<star.radial_falloff>.curve_1
SubAnim
The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. <star.circular_falloff>.curve_1
SubAnim
The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. <star.radial_size>.curve_1
SubAnim
The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. <star.radial_density>.curve_1
SubAnim
The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. Note: The le.addStar 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
See also Lens_Effects : RenderEffect (p. 1357) Value Common Properties, Operators, and Methods (p. 714)
Lens_Effects - Streak Constructor: le.addStreak
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
-- alias:
default: 100.0 default: false default: 100.0
-- animatable -- animatable;
default: (color 0 0 255) -- animatable; default: (color 255 255 255) -default: undefined
-- alias:
default: false
-- alias:
default: undefined
-- alias:
default: false
-- alias:
default: 50.0
-- animatable;
default: (color 0 0 0) -- animatable; default: (color 255 255 255) -default: (color 0 0 0) -- animatable; default: undefined
-- alias:
1379
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
default: false
-- alias:
SubAnim TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
SubAnim TextureMap
default: undefined
-- alias:
Boolean
default: false
-- alias:
Boolean
default: true
-- alias:
Boolean
default: true
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer
default: 1
-- animatable;
Boolean
default: false
-- alias:
Integer
default: 1
-- animatable;
Boolean
default: false
-- alias:
Float
default: 1.0
-- animatable;
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Float
default: 0.0
-- animatable;
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer Boolean
default: 0 default: false
-- animatable -- alias:
Float
default: 1000.0
-- animatable;
Float
default: 0.0
-- animatable;
Boolean
default: true
-- alias:
Lens_Effects - Streak
<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
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer
default: 0
-- animatable;
Boolean
default: false
-- alias:
Boolean
default: false
-- alias:
Integer
default: 0
-- animatable;
Color Boolean
default: (color 255 0 0) -- animatable default: false -- alias:
TextureMap SubAnim TextureMap
default: undefined
-- alias: Noise_Map
default: undefined
-- alias:
Boolean
default: false
-- alias:
<streak.radial_falloff>.curve_1
SubAnim
The curve_1 SubAnim contains the radial_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. <streak.circular_falloff>.curve_1
SubAnim
The curve_1 SubAnim contains the circular_falloff curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. <streak.radial_size>.curve_1
SubAnim
The curve_1 SubAnim contains the radial_size curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property. <streak.radial_density>.curve_1
SubAnim
The curve_1 SubAnim contains the radial_density curve. You cannot create or access points in this curve unless the point is animated. In this case, you can access the animated point position as a SubAnim of the curve_1 property.
1381
1382
Chapter 11
|
3ds max Objects
Note: The le.addStreak 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
newTrackViewNode [ <maxtvnode> ] [ #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>
adds the sub-controller to the given Track View node. The deleteTrackViewController <maxtvnode>
deletes the controller from the given Track View node
See also Value Common Properties, Operators, and Methods (p. 714)
1383
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
Working with the NURBS Classes Unlike other parts of MAXScript that let you script 3ds max scene objects directly, the NURBS family of classes provides an indirect means of working with 3ds max NURBS objects. They allow you to build an idealized structure representing 3ds max NURBS objects and then use this structure to either create new or add to scene NURBS objects or to access certain parts of existing scene objects. The structure is made up of instances of the MAXScript NURBS classes, listed in the NURBS Classes (p. 1401) topic. The main class for this is NURBSSet. It is the structure that corresponds to a scene NURBS object and contains a collection of NURBS items such as curves, surfaces, dependent surfaces, points, and so on, which are themselves instances of the other MAXScript NURBS classes. You construct a NURBSSet object describing a NURBS object and then have it be instantiated as a real scene object. Conversely, you can ask for a NURBSSet to be created that corresponds to a given scene NURBS object and use it to examine the component NURBS items and to modify certain properties directly on the scene object it describes. Parameter Validity The 3ds max NURBS SDK methods and the corresponding MAXScript methods and properties perform very little parameter validation. As a result, passing invalid parameters to the functions or accessing invalid ranges will generate Assertion Failures easily. In most cases 3ds max will not crash if Retry or Ignore is selected. An example of this is: 1.
Create a CV surface and select it.
2.
Enter in MAXScript: s = getnurbsset $ #relational obj = getobject s 1 tess = getviewtess obj #displacement
This is invalid because the viewport does not support displacement approximation, only the production renderer does. Therefore, this will generate an Assertion Failure.
1385
1386
Chapter 11
|
3ds max Objects
NURBSId’s and Indexes An important concept to understand when working with NURBSSets and the other NURBS classes, is the way you identify component items in the set. Before a NURBSet is instantiated as a scene NURBS object, the individual curves and points and surfaces are identified by an index number. As you append objects to the set they are assigned successive indexes, starting at 1. When you want to refer to a particular item, for example to specify the parent surfaces in a blend surface, you use this index. Once an object has been added to a NURBSSet, its index can determined through the .index property. This is a read-only property. However, once a NURBSet is associated with a scene object, either by being instantiated or because it was directly created from an existing scene object, this index is no longer valid. Instead, a different number, called a NURBSId, is assigned to each item and you must use that Id when referring to items from then on. The NURBSId of any item in an instantiated NURBSSet can be obtained through the .NURBSId property on that object. These identifiers, indexes or NURBSId’s, are used in many places to specify the parent objects for other dependent objects. Often, these are specified using the .parent or .parentID properties on a dependent object. You must be sure to use the correct property depending on whether the containing NURBSSet has been associated with a scene object or not: .parent for non-associated NURBSSets, .parentID for associated NURBSSets. Remember that indexes used in .parent settings are 1-based.
Overview of the Principal NURBS Classes The diagram below shows the inheritance tree of the principal classes in the NURBS family. The base classes are shown at the top, and the inheritance hierarchy proceeds toward the bottom and to the right. NURBSObject (p. 1402) is the main base class, with NURBSPoint (p. 1403), NURBSControlVertex (p. 1409), NURBSCurve (p. 1409), NURBSSurface (p. 1425), NURBSCVCurve (p. 1412), and NURBSPointCurve (p. 1418) also functioning as base classes. Several additional classes are used with NURBS objects, but are not part of the NURBS hierarchy. These classes are the NURBSDisplay (p. 1447), NURBSSelection (p. 1448), NURBSSet (p. 1450), NURBSSurfaceApproximation (p. 1453), and NURBSTextureSurface (p. 1455) classes.
Overview of the Principal NURBS Classes
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.
1387
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 object’s tessellation into triangle meshes for use in the viewports and the production renderer. The NURBSPoint classes describe a point in 3D space. Depending on the specific class, points can be either independent or dependent. Independent points are those that don’t rely on other objects to define their location. Dependent points are related to the objects they depend on such that the relationship established initially remains if the point, curve or surface moves. For example, a point can be created such that it always remains a certain distance from another point. The options are XYZ-relative, along a normal, or along a tangent (or set of tangents for a surface-dependent constrained point). The NURBSControlVertex class defines a Control Vertex of a NURBS Curve or NURBS Surface. This class shares may of the same properties as a NURBSPoint and has the added property of a rational weight. The weight value of a CV is rational. That is, it is relative to other CVs in the curve or surface. Changing the weight of all CVs at once has no effect, because this doesn’t change the ratio between weights. The NURBSCurve classes describe the properties of NURBS curves. As with the NURBSPoint classes, depending on the specific class, curves can be either independent or dependent. Independent curves are those that don’t rely on other objects to define their location. A dependent curve is an object that depends on one or more other objects to define what it is. For example, a Blend Curve depends on the two parent curves that it blends between when it was created (as well as on its two tension parameters). The NURBSSurface classes describe the properties of NURBS surfaces. As with the NURBSPoint and NURBSCurve classes, depending on the specific class, surfaces can be either independent or dependent. Independent surfaces are those that don’t rely on other objects to define their location. Dependent surfaces are surface sub-objects whose geometry depends on other surfaces or curves in the NURBS model. When you change the geometry of the original parent surface or curve, the dependent surface changes as well.
Creating New NURBS Objects
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
1389
1390
Chapter 11
|
3ds max Objects
-- add the NURBSCVCurve object to the set appendObject nset c -- create the NURBS object from the NURBSSet n = NURBSNode nset name:”nurbs01” pos:[10,0,0]
Note that the NURBSSet supplied to the NURBSNode() function will be modified by that function to be a relational representative for the newly created scene node which you can then use to modify the scene object -- you don’t have to re-extract a fresh relational NURBSSet.
Modifying Existing NURBS Objects The classes can also be used to modify the properties of existing NURBS objects in the scene. To gain access to an internal 3ds max NURBS object you must have the data copied into a NURBSSet. This is done using the node method getNURBSSet(). You can then use the methods of the NURBSSet to access the objects. For example, the following sample code attempts to grab the first NURBS sub-object from the first node in the current selection set. It then checks if it’s a blend surface and if so adjust one of the tension parameters. -- get the first node in selection node = selection[1]; -- make sure creation has been completed on the node stopCreating node -- get the nurbs set for it getSet = getNURBSSet node #relational -- extract the first obj, check class & set tension obj = getObject getSet 1 if classOf obj == NURBSBlendSurface then obj.tension1 = 2.0
The kinds of modification you can perform in this way are limited to changing those parameters and properties that do not alter the structure of the NURBS scene object -- you can modify point and CV positions, CV weights, dependent object parameters such as offsets and extrude amounts, etc. You cannot add or delete objects, change the number of CVs or knots or parent curves, etc. To do this kind of structural modification, use the appendObject(), setObject(), and removeObject() functions defined in the NURBSSet : Value (p. 1450) topic and the addNURBSSet(), breakSurface(), and similar functions defined in the NURBS Node Properties and Methods (p. 1397) topic. The stopCreating() method is used to ensure that the specified node is fully created. This method is primarily used to ensure that a NURBS scene objects is fully created, which it will not be until the creation is stopped. The NURBSSet returned for a NURBS scene object will not be complete if the object is still in creation mode. This method will also deactivated any activated object create buttons in the Create panel. There are other global functions that may be used to modify NURBS scene objects. These functions are documented in the NURBS Node Properties and Methods (p. 1397) topic. For instance, developers
Parameter Ranges for Curves and Surfaces
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 .uParam sets the position of a dependent point in the parent surface’s U parameter space. The valid U and V values that may be passed to this method must be obtained by referencing the 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 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
1391
1392
Chapter 11
|
3ds max Objects
primitives, such as the Prism, don’t use (0,0) to (1,1) because of the way they wrap. Developers may of course assign any values using the API. The 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 {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> <sweep> [capStart:] [capEnd:] [capType:] [weldCore:] [flipNormals:] [mapCoords:] [segs:] [matIDs:] [shapeIDs:] {node_creation_parameters}
\ \ \ \ \
This function generates a NURBS object based on the specified lathe (surface of revolution) definition and returns a pointer to it. This is used by the lathe modifier. curve
<node>
The shape object to revolve. Note that if the curve pointed to is a bezier spline then capping won’t work properly. axis
<Matrix3>
This specifies the axis of revolution. sweep
The angle for the surface of revolution in degrees. capStart:
Specifies if the surface should be capped at the beginning: true to cap; false to leave open. capEnd:
Specifies if the surface should be capped at the ending: true to cap; false to leave open. capType:
This parameter is not currently used and the value specified is ignored. weldCore:
true to collapse any coincident vertices at the center of the surface; otherwise false.
Creating NURBS Scene Objects
flipNormals:
true to invert the orientation of surface normals; otherwise false. mapCoords:
true to generate mapping coordinates; otherwise false. segs:
The number of segments in the surface of revolution. matIDs:
If true special material IDs are assigned to the surfaces and caps. shapeIDs:
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> [capStart:] \ [capEnd:] [capType:] \ [mapCoords:] [matIDs:] \ [shapeIDs:] {node_creation_parameters}
This function generates a NURBS object based on the specified extrusion definition and returns a pointer to it. This is used by the extrude modifier. shape
<node>
The shape node to extrude. Note that if the shape pointed to is a bezier spline then capping won’t work properly. amount
Specifies the height of the extrusion. capStart:
Specifies if the surface should be capped at the beginning: true to cap; false to leave open. capEnd:
Specifies if the surface should be capped at the ending: true to cap; false to leave open. capType:
This parameter is not currently used and the value specified is ignored. matIDs:
If true, special material IDs are assigned to the surfaces and caps. shapeIDs:
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.
1393
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> <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
This is the NURBS curve that is revolved. origin
<point3>
Specifies the origin of the revolution. north
<point3>
This is the axis that specified the up direction. start
This is the start angle of the revolution in radians. end
This is the end angle of the revolution in radians. MakeNURBSSphereSurface <north_axis> \ <startU> <endU> <startV> <endV> [open:]
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
The radius of the sphere. center
The center point of origin of the sphere. north_axis
This specifies the up axis. Use (Point3 0 0 1) for the Z axis for example. ref_Axis
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
The start angle for the sphere in the U direction, specified in radians. endU
The end angle for the sphere in the U direction, specified in radians. startV
The start angle for the sphere in the V direction, specified in radians. endV
The end angle for the sphere in the V direction, specified in radians. open:
If true, the surface is closed; otherwise the surface is not closed. Defaults to false.
Creating NURBSCVSurface Values
MakeNURBSCylinderSurface <sym_axis> \ <start> <end> [open:]
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
The radius of the cylinder. height
The height of the cylinder. origin
The origin of the cylinder. sym_Axis
The axis of symmetry. The standard cylinder primitive specifies (Point3 0 0 1). ref_Axis
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
The start angle in radians. end
The end angle in radians. open:
If true, the surface is closed; otherwise the surface is not closed. Defaults to false. MakeNURBSConeSurface <sym_axis> <start> <end> [open:]
\
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
One of the radii of the cone. radius2
The other radius of the cone. height
The height of the cone. origin
The origin of the cone. sym_Axis
The axis of symmetry. ref_Axis
This is the direction of the seam. The symAxis and refAxis must be perpendicular to one another.
1395
1396
Chapter 11
|
start
3ds max Objects
The start angle in radians. end
The end angle in radians. open:
If true, the surface is closed; otherwise the surface is not closed. Defaults to false. MakeNURBSTorusSurface <majorRad> <minorRad> <sym_axis> <startU> <endU> <startV> <endV> [open:]
\ \
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
This is the radius of the entire ‘donut’ shape. minorRad
The is the radius of the ‘tube’. origin
The origin of the cone. sym_Axis
The axis of symmetry. ref_Axis
This is the direction of the seam. The symAxis and refAxis must be perpendicular to one another. startU
The start angle of the torus in the U direction. endU
The end angle of the torus in the U direction. startV
The start angle of the torus in the V direction. endV
The end angle of the torus in the V direction. open:
If true, the surface is closed; otherwise the surface is not closed. Defaults to false.
NURBS Node Properties and Methods
NURBS Node Properties and Methods Properties: There are several properties on <node> objects that give access to sub-object selections in NURBS objects: <node>.selectedCurveCVs <node>.selectedCurves <node>.selectedImports <node>.selectedPoints <node>.selectedSurfaces <node>.selectedSurfCVs <node>.curveCVs <node>.curves <node>.imports <node>.surfaces <node>.surfCVs <node>.points
These all return a NURBSSelection Value (p. 1448), and enable sub-object manipulation in a manner similar to that provided for Editable Meshes. Methods: The following NURBS-related methods operate on scene nodes: getNURBSSet <node> [#relational]
This function is used to retrieve a NURBSSet that corresponds to the specified NURBS scene node. This allows access the internal objects inside a 3ds max editable NURBS object. If the optional #relational parameter is not supplied, the returned NURBSSet will contain only independent curves and surfaces, all dependent objects will be decomposed into corresponding independent objects. So for example, if you pass an object that has a relational model (perhaps two CV surfaces and a dependent blend surface) it will decompose them into three CV surfaces. This will be the CV surfaces that represent the two surfaces and the blend, but you won’t have the blend relational data. If the #relational argument is supplied, you get back two CV surfaces and a NURBS blend surface and the NURBSSet is an active representative for the scene object -- any changes you make to the properties of it’s constituent NURBSObjects will be reflected directly in the source scene object. addNURBSSet <node>
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.
1397
1398
Chapter 11
|
3ds max Objects
transform <node> <matrix3>
Transforms the specified sub-objects by the matrix supplied in the node’s local space. The sub-objects to be transformed are identified by their NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function. breakCurve <node>
Breaks the specified sub-object curve at the parametric point along the curve defined by the 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> (#U | #V)
Breaks the specified sub-object surface at the parametric point defined by the 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> [flip1:] [flip2:]
\
Joins two curve sub-objects in the specified scene node and makes a single curve out of them. That is, the endpoints of the two curve objects are connected by new segments, and the two original curves are replaced by a single curve. The supplied tolerance is a distance in 3ds max units. If the gap between the curves you are joining is greater than this value, this function creates the join by first creating a blend curve and then joining the three parts. If the gap is less than this value, or if the curves are overlapping or coincident, no blend is created. Creating a blend and then joining the three curves into a single curve is the better technique. The result matches the parent curves well. Without the blend step, the resulting curve can deviate from the parent curves, in order to maintain smoothness. (The amount of deviation depends on how far from tangent the two input curves were at the join.) A problem arises when there is a gap but it is too small. In this case, this function generates the blend but because there isn’t enough room for it, the resulting curve has a loop in it. To avoid this loop, set this parameter higher than the gap distance. If you the tolerance to 0.0, the function chooses a value to use for the tolerance. The sub-objects to be joined are identified by their NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function.
NURBS Node Properties and Methods
joinSurfaces <node> <edge1_integer> \ <edge2_integer>
Joins two surface sub-objects in the specified scene node and makes a single surface from them. The specified edges of the two surface objects are connected by a new surface, and the two original surfaces are replaced by a single surface. The edges are identified by edge index numbers. The tolerance is a distance in 3ds max units. If the gap between the surfaces you are joining is greater than this value, this function creates the join by first creating a blend surface. If the gap is less than this value, or if the surfaces are overlapping or coincident, 3ds max doesn’t create the blend. Creating a blend and then joining the three surfaces into a single surface is the better technique. The result matches the parent surfaces well. Without the blend step, the resulting surface can deviate from the parent surfaces, in order to maintain smoothness. (The amount of deviation depends on how far from tangent the two input surfaces were at the join.) A problem arises when there is a gap but it is too small. In this case, this function generates the blend but because there isn’t enough room for it, the resulting surface has a loop in it. To avoid this loop, set the tolerance parameter higher than the gap distance. If you set the tolerance to 0.0, the function chooses a value to use for the tolerance. The sub-objects to be joined are identified by their NURBSId property which is set up when you instantiate a NURBSSet with the NURBSNode() function or if you extract a relational NURBSSet from an existing NURBS scene node using the getNURBSSet() function. makeIndependent <node>
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>
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.
1399
1400
Chapter 11
|
3ds max Objects
Associated Methods: canConvertTo <node>
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>
-- 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
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)
1401
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: .name
: string
The name of the NURBS object .index
: integer, read-only
Only valid after a NURBSSet is instantiated via NURBSNode() or if the NURBS object is part of a non-relational NURBSSet. .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(). .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
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. .pos .x .y .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 curve’s local U axis). There are four ways to specify the displacement of the point’s location relative to the U position: •
OnObject - the point is actually on the surface of the object.
•
Offset - the point is moved according to a relative (object space) X,Y,Z location.
•
Normal - the point is moved along the direction of the curve’s normal. (Negative values move it opposite to the normal.)
•
Tangent - the point is moved along the tangent of the U Position. If the value is positive it’s the tangent that heads in the direction of increasing U value; if negative it’s the tangent that heads in the direction of decreasing U value.
1403
1404
Chapter 11
|
3ds max Objects
Constructors: NURBSCurveConstPoint [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent curve by NURBSet index. .parentID
: integer
The parent curve by NURBSId. .uParam
: float
Parametric point along the parent curve. .type
: #onObject, #offset, #normal, #tangent
Specifies the transform relationship between the point and the curve. .offset
: point3
Offset vector if an offset type. .normal
: float
Distance along the normal if a normal type. .uTangent
: float
Distance along the curve tangent if a tangent type. .trimCurve : boolean
If true, trims parent curve at the point. .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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
NURBSCurveSurfaceIntersectPoint : NURBSPoint
Properties: .parent1
: integer
The 1st parent curve by NURBSet index. .parent1ID
: integer
The 1st parent curve by NURBSId. .parent2
: integer
The 2nd parent curve by NURBSet index. .parent2ID
: integer
The 2nd parent curve by NURBSId. .trimCurve1
: boolean
If true, trim the 1st parent curve at the intersection. .trimCurve2
: boolean
If true, trim the 2nd parent curve at the intersection. .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. .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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent1
: integer
The parent surface by NURBSet index. .parent1ID
: integer
The parent surface by NURBSId. .parent2
The parent curve by NURBSet index.
: integer
1405
1406
Chapter 11
|
3ds max Objects
.parent2ID
: integer
The parent curve by NURBSId. .trimCurve
: boolean
If true, trims parent curve at the point. .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. .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 getPoint getPoint getPoint
Operators: == !=
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
NURBSPointConstPoint : NURBSPoint This class defines a dependent point that lies at a point or relative to it. It is a point constrained relative to another point. This can be a point used to define a point surface or point curve, it can be a trim point, or just a point in space. There are two ways to specify the displacement of the point’s location relative to the U position: •
OnObject - the point is actually at the parent.
•
Offset - the point is moved according to a relative (object space) X,Y,Z location.
Constructors: NURBSPointConstPoint [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent point by NURBSet index. .parentID
: integer
The parent point by NURBSId. .type .offset
: #onObject, #offset : point3
Offset vector if an offset type.
See also NURBSPoint (p. 1403) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSSurfConstPoint : NURBSPoint This class defines a dependent point on a surface or related to it. There are four ways to specify the displacement of the point’s location relative to the UV position: •
OnObject - the point is actually on the surface of the object.
•
Offset - the point is offset some distance (specified in object space) from the surface of the object.
•
Normal - the point is offset along the direction of the surface’s normal. (Negative values move it opposite to the normal.)
•
Tangent - the point is offset some U and/or V distance along the tangent from the surface. If the value is positive it’s the tangent that heads in the direction of increasing parameter value; if negative it’s the tangent that heads in the direction of decreasing parameter value.
1407
1408
Chapter 11
|
3ds max Objects
Constructors: NURBSSurfConstPoint [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent surface by NURBSet index. .parentID
: integer
The parent surface by NURBSId. .type .uParam
: #onObject, #offset, #normal, #tangent : float
Parametric position along u direction. .vParam
: float
Parametric position along v direction. .offset
: point3
Offset vector if an offset type. .normal
: float
Distance along the normal if a normal type. .uTangent
: float
Distance along the u tangent if a tangent type. .vTangent
: float
Distance along the v tangent if a tangent type.
See also NURBSPoint (p. 1403) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSControlVertex : NURBSObject
NURBSControlVertex Class NURBSControlVertex : NURBSObject This class defines an independent Control Vertex of a NURBS Curve or NURBS Surface. This class shares may of the same properties as a NURBSPoint and has the added property of a rational weight. The weight value of a CV is rational. That is, it is relative to other CVs in the curve or surface. Changing the weight of all CVs at once has no effect, because this doesn’t change the ratio between weights. Constructors: NURBSControlVertex <point3> [<weight_float>] getCV getCV
Operators: == !=
Properties: .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: .isClosed
: boolean, read-only
true if the curve is closed, false if open. .numTrimPoints
: integer, read-only
The number of trim points in the curve.
1409
1410
Chapter 11
|
3ds max Objects
.parameterRangeMin .parameterRangeMax
: float, read-only : float, read-only
Contains the minimum and maximum valid values for in the methods associated with NURBS Curves. .matID
: integer
The material ID assigned to the curve. Methods: All NURBS curve classes have the following methods: evalPos
Returns the position in space of the given parametric point along the curve. evalTangent
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent1
: integer
The 1st parent curve by NURBSet index. .parent1ID
: integer
The 1st parent curve by NURBSId. .parent2
: integer
The 2nd parent curve by NURBSet index. .parent2ID
: integer
The 2nd parent curve by NURBSId. .flip1
: boolean
true to use the end of 1st parent curve; false to use the beginning, defaults to false. .flip2
: boolean
true to use the end of 2nd parent curve; false to use the beginning, defaults to false.
NURBSChamferCurve : NURBSCurve
.tension1
: float
The tension value for the 1st parent curve. .tension2
: float
The tension value for the 2nd parent curve.
See also NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSChamferCurve : NURBSCurve This class defines a dependent Chamfer curve. A Chamfer is a curve that creates a straight line corner between two parent curves. Constructors: NURBSChamferCurve [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent1
: integer
The 1st parent curve by NURBSet index. .parent1ID
: integer
The 1st parent curve by NURBSId. .parent2
: integer
The 2nd parent curve by NURBSet index. .parent2ID
: integer
The 2nd parent curve by NURBSId. .length1
: float
The length for 1st parent curve back from the end that defines the beginning of the chamfer. .length2
: float
The length for 2nd parent curve back from the end that defines the beginning of the chamfer. .flip1
: boolean
true to use the end of 1st parent curve; false to use the beginning, defaults to false. .flip2
: boolean
true to use the end of 2nd parent curve; false to use the beginning, defaults to false. .trim1
: boolean
Sets whether 1st parent curve is trimmed. true if the curve is trimmed; otherwise false.
1411
1412
Chapter 11
|
3ds max Objects
.trim2
: boolean
Sets whether 2nd parent curve is trimmed. true if the curve is trimmed; otherwise false. .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. .flipTrim2
: boolean
If true the 2nd parent curve is trimmed from the point towards low parameter space. If false the curve is trimmed from the point towards high parameter space.
See also NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSCVCurve : NURBSCurve This class defines an independent NURBS CV Curve. The position and weight of the control vertices (CVs) controls the shape of the curve. Unlike spline vertices, CVs don’t necessarily lie on the curve they define. The CVs define a control lattice which surrounds the curve. Constructors: NURBSCVCurve
[<property>:] [closed:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. If closed:true is specified, the curve is created as a closed curve, otherwise it is an open curve. getObject
Properties: .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. .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. .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
.transform
: matrix3
The transformation matrix for the NURBSCVCurve. This controls the relative position of the item within a NURBSSet. .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. .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
Forces the curve to be closed. getKnot setKnot
Get and set the indexed knot’s value, indexes are 1-based. Knots are a mathematical construct that helps define the span of control of CVs and blending functions that define NURBS Curves and Surfaces. The knots are an array of values that determines the parameterization of a curve. Values in the knot vector are nondecreasing. The knots specify the region of influence of the CVs on the curve. It is a way of partitioning the parameter space up into different segments. A B-spline curve or a NURBS curve is a curve that is defined by a series of segments. On each one of the segments the curve is like a polynomial, or in the case of a rational one, it’s like the ratio of polynomials. The knot vector describes how to partition the parameter space of the curve up for each of the different pieces of the polynomial. getCV
Get the indexed CV as a NURBSControlVertex, indexes are 1-based. setCV
Sets the indexed CV to the given NURBSControlVertex, indexes are 1-based. refine
Add a new, interpolated CV at the given parametric point along the curve. reparameterize (#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.
1413
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>:] [closed:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. If closed:true is specified, the curve is created as a closed curve, otherwise it is an open curve. getObject
Properties: .parent
: integer
The parent surface by NURBSet index. .parentID
: integer
The parent surface by NURBSId. .trim
: boolean
If true, trims parent surface at the curve. .flipTrim
: boolean
The state of the trim flip toggle. This controls which portion of the surface is trimmed. Note: The values for CVs for a NURBSCurveOnSurface are values in the parameter space of the surface, not in 3D space. CV surfaces are normally parameterized from 0 to 1, so all the CV values should have values from 0 to 1. Point surfaces are chord-length parameterized, which means that the CV parameter range is about the same as the size of the surface. In most cases, NURBSCurveOnSurfaces work better when point surfaces are used. You may have problems generating NURBSCurveOnSurfaces on CV surfaces. NURBSPointCurveOnSurfaces on CV surfaces are typically easier to work with.
NURBSFilletCurve : NURBSCurve
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent1
: integer
The 1st parent curve by NURBSet index. .parent1ID : integer
The 1st parent curve by NURBSId. .parent2
: integer
The 2nd parent curve by NURBSet index. .parent2ID : integer
The 2nd parent curve by NURBSId. .radius
: float
The radius of the fillet. .flip1
: boolean
true to use the end of 1st parent curve; false to use the beginning, defaults to false. .flip2
: boolean
true to use the end of 2nd parent curve; false to use the beginning, defaults to false. .trim1
: boolean
Sets whether 1st parent curve is trimmed. true if the curve is trimmed; otherwise false. .trim2
: boolean
Sets whether 2nd parent curve is trimmed. true if the curve is trimmed; otherwise false. .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. .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.
1415
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent surface by NURBSet index. .parentID
: integer
The parent surface by NURBSId. .dir
: #U, #V
The direction of the iso curve, either #U or #V. .parameter
: float
The parametric position in the range of 0.0 to 1.0 in the given direction on the surface at which the iso line will sit. .trim
: boolean
If true, trims parent surface at the curve. .flipTrim
: boolean
The state of the trim flip toggle. This controls which portion of the surface is trimmed. .seed
: point2
The seed location is a UV position on the parent surface.
See also NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSMirrorCurve : NURBSCurve
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent curve by NURBSet index. .parentID
: integer
The parent curve by NURBSId. .axis
: #X, #Y, #Z, #XY, #XZ, #YZ
The axis or axes of reflection for the curve. .distance
: float
The mirror offset distance. .transform
: matrix3
This is an additional transformation applied to the axis specification. This corresponds to the gizmo the user may use interactively to alter the location of the mirror axis. This is exactly equivalent to setting the transform on the gizmo of a mirror modifier.
See also NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSOffsetCurve : NURBSCurve This class defines a dependent Offset curve. An Offset curve is offset from the original, parent curve. It lies in the same plane as its parent, and is normal to the original. Constructors: NURBSOffsetCurve [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
1417
1418
Chapter 11
|
3ds max Objects
Properties: .parent
: integer
The parent curve by NURBSet index. .parentID
: integer
The parent curve by NURBSId. .distance
: float
The distance of the offset curve from the parent.
See also NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSPointCurve : NURBSCurve This class defines an independent curve that uses points to describe its shape. All the points lie on the curve itself. Constructors: NURBSPointCurve [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .numPoints
: integer
The number of points in the point curve. If this value is changed, the previous point data is not maintained. .closed
: boolean
true if the curve is closed, false if open. .transform
: matrix3
The transformation matrix for the NURBSPointCurve. This controls the relative position of the item within a NURBSSet. Methods: close
Closes the curve. getPoint
Get the indexed curve point as a NURBSIndependentPoint setPoint
Set the indexed point to the given NURBSIndependentPoint refine
Adds a new, interpolated point at the given parametric position along the curve.
NURBSPointCurveOnSurface : NURBSPointCurve
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent surface by NURBSet index. .parentID
: integer
The parent surface by NURBSId. .trim
: boolean
If true, trims parent surface at the curve. .flipTrim
: boolean
The state of the trim flip toggle. This controls which portion of the surface is trimmed.
See also NURBSPointCurve (p. 1418) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
1419
1420
Chapter 11
|
3ds max Objects
NURBSProjectNormalCurve : NURBSCurve This class defines a dependent Normal Projected curve. A Normal Projected curve lies on a surface. It is based on an existing curve, which is projected onto the surface in the direction of the surface’s normals. Constructors: NURBSProjectNormalCurve [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent1
: integer
The parent surface by NURBSet index. .parent1ID
: integer
The parent surface by NURBSId. .parent2
: integer
The parent curve by NURBSet index. .parent2ID
: integer
The parent curve by NURBSId. .trim
: boolean
If true, trims parent surface at the curve. .flipTrim
: boolean
The state of the trim flip toggle. This controls which portion of the surface is trimmed. .seed
: point2
The seed location is a UV position on the parent surface.
See also NURBSPointCurve (p. 1418) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSProjectVectorCurve : NURBSCurve
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent1
: integer
The parent surface by NURBSet index. .parent1ID
: integer
The parent surface by NURBSId. .parent2
: integer
The parent curve by NURBSet index. .parent2ID
: integer
The parent curve by NURBSId. .trim
: boolean
If true, trims parent surface at the curve. .flipTrim
: boolean
The state of the trim flip toggle. This controls which portion of the surface is trimmed. .seed
: point2
The seed location is a UV position on the parent surface. .pVec
: point3
The projection vector.
See also NURBSPointCurve (p. 1418) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
1421
1422
Chapter 11
|
3ds max Objects
NURBSSurfaceEdgeCurve : NURBSCurve This class defines a dependent Surface Edge curve. Constructors: NURBSSurfaceEdgeCurve [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent surface by NURBSet index. .parentID
: integer
The parent surface by NURBSId. .seed
: Point2
The seed location is a UV position on the parent surface.
See also NURBSPointCurve (p. 1418) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSSurfaceNormalCurve : NURBSCurve This class defines a dependent Surface Normal curve. This is a curve created at a specified distance from a surface and normal to it. Constructors: NURBSSurfaceNormalCurve [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent curve by NURBSet index. .parentID
: integer
The parent curve by NURBSId. .distance
: float
The distance along the normal from the surface to the curve.
NURBSSurfSurfIntersectionCurve : NURBSCurve
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent1
: integer
The 1st parent surface by NURBSet index. .parent1ID
: integer
The 1st parent surface by NURBSId. .parent2
: integer
The 2nd parent surface by NURBSet index. .parent2ID
: integer
The 2nd parent surface by NURBSId. .trimCurve1
: boolean
If true, trim the 1st parent surface at the intersection. .trimCurve2
: boolean
If true, trim the 2nd parent surface at the intersection. .flipTrim1
: boolean
If true the 1st parent surface is trimmed from the point towards low parameter space. If false the surface is trimmed from the point towards high parameter space. .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. .seed
: point2
The seed location is a UV position on the parent surface.
1423
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent curve by NURBSet index. .parentID
: integer
The parent curve by NURBSId. .transform
: matrix3
The offset transformation matrix for the NURBSCVCurve. This controls the relative position of the item to the parent curve.
See also NURBSPointCurve (p. 1418) NURBSCurve (p. 1409) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSSurface : NURBSObject
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. .renderable
: boolean
Specifies whether the surface is renderable. true if the surface is renderable, false if not. .flipNormals
: boolean
Specifies whether all the surface’s surface normals are flipped. true if the surface normals are to be flipped, false if not. .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. .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. .matID
: integer
The material ID of the surface. .closedInU
: boolean, read-only
true if the surface is closed in the U direction, false if open. .closedInV
: boolean, read-only
true if the surface is closed in the V direction, false if open.* .uParameterRangeMin .uParameterRangeMax
: float, read-only : float, read-only
Contains the minimum and maximum valid values for in the methods associated with NURBS Surfaces. .vParameterRangeMin .vParameterRangeMax
: float, read-only : float, read-only
Contains the minimum and maximum valid values for in the methods associated with NURBS Surfaces.
1425
1426
Chapter 11
|
3ds max Objects
.textureSurface1 .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
Returns the coordinates in space of the point at the given U and V parametric position on the surface. evalUTangent
Returns the U tangent vector of the surface at the given U and V parametric position on the surface. evalVTangent
Returns the V tangent vector of the surface at the given U and V parametric position on the surface. getTiling [channel:] setTiling [channel:]
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 [channel:] setTilingOffset [channel:]
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 setGenerateUVs
These methods get and set whether the generation of UV mapping coordinates for the selected channel is enabled.
NURBS1RailSweepSurface : NURBSSurface
getTextureUVs [channel:] setTextureUVs <point2> [channel:]
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 :]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .rail
: integer
The parent rail curve by NURBSet index.
1427
1428
Chapter 11
|
3ds max Objects
.railID
: integer
The parent rail curve by NURBSId. .numCurves
: integer
The number of cross-section curves. .parallel
: boolean
If true, ensures that the sweep surface’s normal is parallel to the rail. .axisTM
: matrix3
The axis of the sweep. Methods: appendCurve <curve> [flip:] [startPoint:]
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 <curveID> [flip:] [startPoint:]
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 setCurve <curve>
Get or set the indexed cross-section curve by NURBSSet index. getCurveID setCurveByID <curveID>
Get or set the indexed cross-section curve by NURBSId. getFlip setFlip
Get or set whether the indexed cross-section curve is reversed. getCurveStartPoint setCurveStartPoint
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
NURBS2RailSweepSurface : NURBSSurface This class defines a dependent 2-Rail Sweep surface. A 2-Rail Sweep surface uses at least three curves. Two curves, the “rails,” define the two edges of the surface. The other curves define the surface’s cross sections. A 2-Rail Sweep surface is similar to a 1-Rail sweep. The additional rail gives you more control over the shape of the surface. Constructors: NURBS2RailSweepSurface [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .rail1
: integer
The 1st parent rail curve by NURBSet index. .rail1ID
: integer
The 1st parent rail curve by NURBSId. .rail2
: integer
The 2nd parent rail curve by NURBSet index. .rail2ID
: integer
The 2nd parent rail curve by NURBSId. .numCurves
: integer
The number of cross-section curves. .parallel
: boolean
If false, the rail curves define a ruled surface, and the cross sections describe lofting from this base ruled surface. If true, each cross section is associated with its best fitting plane. This plane moves along the rails and parallel to them. If the rails are curved, the plane can rotate. If the spacing between the rails changes, the section scales or stretches. In either case, the surface is blended from section to section along its entire length. Methods: appendCurve <curve> [flip:] [startPoint:]
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 <curveID> [flip:] [startPoint:]
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.
1429
1430
Chapter 11
|
3ds max Objects
getCurve setCurve <curve>
Get or set the indexed cross-section curve by NURBSSet index. getCurveID setCurveByID <curveID>
Get or set the indexed cross-section curve by NURBSId. getFlip setFlip
Get or set whether the indexed cross-section curve is reversed. getCurveStartPoint setCurveStartPoint
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent1
: integer
The 1st parent by NURBSet index. .parent1ID
: integer
The 1st parent by NURBSId. .parent2
: integer
The 2nd parent by NURBSet index. .parent2ID
The 2nd parent by NURBSId.
: integer
NURBSBlendSurface : NURBSSurface
.edge1
: integer
Which edge of the 1st parent surface is used for the blend. The property’s 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
.edge2
: integer
Which edge of the 2nd parent surface is used for the blend. .flip1
: boolean
Controls the matching of parent surface normals when creating the Blend surface. For example, normally when you create a Blend surface between two parent surfaces you don’t want a ‘bow tie’ surface (one with the ends rotated 180 degrees so it crosses on itself in the middle). If you simply match the parent normals you’ll occasionally get a ‘bow tie’ surface. To prevent this you use this property to set a state indicating that one or the other should be flipped before it’s used. In this way, when the blend is created, a ‘bow tie’ won’t occur. If true, the 1st parent’s surface normal will be matched; if false the 1st parent’s surface normal will not be matched. .flip2
: boolean
If true, the 2nd parent’s surface normal will be matched; if false the 2nd parent’s surface normal will not be matched. .tension1
: float
The tension value for the 1st parent. .tension2
: float
The tension value for the 2nd parent. .curveStartPoint1 .curveStartPoint2
: float : float
Adjusts the position of the start point at the two edges of the blend. Adjusting the start points can help eliminate unwanted twists or “buckles” in the surface. These values are not applicable if the edges or curves are not closed. Methods: getParent setParent <curve>
Get or set a parent by NURBSSet index. = 1 - parent 1; 2 - parent 2. getParentID setParentID <curveID>
Get or set a parent by NURBSId. = 1 - parent 1; 2 - parent 2. getEdge setEdge <edge>
Get or set which edge of the parent surface is used for the blend. = 1 - parent 1; 2 - parent 2. See the edge1 property description for the <edge> value description.
1431
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent curve or surface by NURBSet index. .parentID
: integer
The parent curve or surface by NURBSId. .edge
: integer
Which edge of the parent surface is capped. This value is not applicable if the parent is a curve. The property’s value is one of the following: 1: 2: 3: 4:
The The The The
low U edge high U edge low V edge high V edge
.curveStartPoint
: integer
The start point on the parent curve. This value is only applicable if the parent is a curve.
See also NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSCVSurface : NURBSSurface
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .uOrder .vOrder
: integer : integer
The order of the surface in the U and V directions. .numUKnots .numVKnots
: integer : integer
The number of knots in the surface in the U and V directions. If this value is changed, the previous knot data is NOT maintained. Because they are generated mathematically, NURBS surfaces have a parameter space in addition to the 3D geometric space in which they are displayed. Specifically, an array of values called knots specifies the extent of influence of each control vertex (CV) on the surface. .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. .transform
: matrix3
The transformation matrix for the NURBSCVSurface. This controls the relative position of the item within a NURBSSet. .uEdgesOverlap : boolean, read-only .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. .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.
1433
1434
Chapter 11
|
3ds max Objects
.rigid
: boolean
true if the surface is ‘rigid’; otherwise false. The only editing allowed on a rigid surface is to transform it at the Surface sub-object level. You can’t move a rigid surface’s points or CVs, or change the number of points or CVs. Rigid surfaces reduce the amount of memory used by the NURBS model. Making surfaces rigid improves performance, especially for large and complex models. When a surface is rigid, you can’t see its points or CVs when you are at the Point or Surface CV sub-object levels. If the model has no nonrigid surfaces and no point curves, the Point and Surface CV sub-object levels aren’t available at all. Methods: closeU
Closes the surface in the U direction. closeV
Closes the surface in the V direction. getUKnot
Get the indexed U-direction knot; knot indexes are 1-based. setUKnot
Sets the indexed U-direction knot to the given value; knot indexes are 1-based. getVKnot
Get the indexed V-direction knot; knot indexes are 1-based. setVKnot
Get the indexed V-direction knot to the given value; knot indexes are 1-based. getCV
Get the CV at the given U and V index as a NURBSControlVertex; CV indexes are 1-based. setCV
Sets the CV at the given U and V index to the supplied NURBSControlVertex; CV indexes are 1-based. refineU
Adds new row of interpolated CVs in the U direction on the surface at the given parametric V point. refineV
Adds new column of interpolated CVs in the V direction on the surface at the given parametric U point. refine
Adds a new row and column of interpolated CVs on the surface at the given parametric UV position. reparameterize (#centripetal | #uniform)
Reparameterizes the surface by chord length (#centripetal) or uniform (#uniform) uniform parameterization.
NURBSExtrudeSurface : NURBSSurface
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent curve by NURBSet index. .parentID
: integer
The parent curve by NURBSId. .distance
: float
The length of extrusion. .axisTM
: matrix3
The extrusion axis. .curveStartPoint
: float
The start point on the parent curve. This value is only applicable if the curve is closed.
See also NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
1435
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .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 setParent <curve>
Get or set a parent surface by NURBSSet index. = 1 - parent 1; 2 - parent 2. setParentID <curveID> getParentID
Get or set a parent surface by NURBSId. = 1 - parent 1; 2 - parent 2. getSeed setSeed <point2>
The UV location of the seed value on a parent surface. = 1 - parent 1; 2 - parent 2. getRadius setRadius
Get or set the radius of the fillet surface. = 1 - start radius; 2 - end radius. getTrimSurface setTrimSurface
Get or set whether to trim a parent’s surface. If true, trims the parent surface at the intersection. = 1 - parent 1; 2 - parent 2. getFlipTrim setFlipTrim
Get or set the direction to trim a parent’s surface. If true the parent surface is trimmed from the point towards low parameter space. If false the surface is trimmed from the point towards high parameter space. = 1 - parent 1; 2 - parent 2.
See also NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSLatheSurface : NURBSSurface
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent curve by NURBSet index. .parentID
: integer
The parent curve by NURBSId. .axisTM
: matrix3
The axis system for the surface of revolution. .sweep
: float
The angle of the revolution in degrees. .curveStartPoint
: float
The start point on the parent curve. This value is only applicable if the curve is closed.
See also NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSMirrorSurface : NURBSSurface This class defines a dependent Mirror surface. A Mirror surface is similar to a mirror object that you create using the Mirror tool (on the 3ds max toolbar) or the Mirror modifier. It is the original surface reflected about one or two axes. Constructors: NURBSMirrorSurface [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
1437
1438
Chapter 11
|
3ds max Objects
Properties: .parent
: integer
The parent curve by NURBSet index. .parentID
: integer
The parent curve by NURBSId. .axis
: #X, #Y, #Z, #XY, #XZ, #YZ
The axis or axes of reflection for the surface. .distance
: float
The offset from the center of the local coordinate system for the mirror object that moves the mirror, in the direction specified by the mirror axis. .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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .surfaceParent
: Integer
The parent surface by NURBSet index. .surfaceParentID
: Integer
The parent surface by NURBSId. .numCurves
: Integer
The number of curves used for the trim loop. .flipTrim
: Boolean
The state of the trim flip toggle. This controls which portion of the surface is trimmed. Methods:
NURBSNBlendSurface : NURBSSurface
getParent
Gets the NURBSSet index of the indexed trim loop. setParent <curve>
Sets the indexed trim loop to the curve specified by the NURBSSet index. getParentID
Gets the NURBSId of the indexed trim loop. setParentID <curveID>
Sets the indexed curve in the trim loop to the curve specified by the NURBSId. appendCurve <curve>
Adds a curve to the end of the list of curves comprising the trim loop by specifying the NURBSSet index. appendCurveByID <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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: There are no additional properties for NURBSNBlendSurface. Methods: getParent
Returns the NURBSSet index of the indexed curve or surface. setParent <curve>
Sets the specified parent curve or surface by NURBSSet index as the indexed edge for the surface.
1439
1440
Chapter 11
|
3ds max Objects
getParentID
Returns the NURBSId of the indexed curve or surface. setParentID <curveID>
Sets the specified parent curve or surface by NURBSId as the indexed edge for the surface. getEdge setEdge <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 surface’s normals. Constructors: NURBSOffsetSurface [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent surface by NURBSet index. .parentID
: integer
The parent surface by NURBSId. .distance
: float
The distance of the offset surface from the parent surface.
See also NURBSSurface (p. 1425) NURBSObject (p. 1402) Value Common Properties, Operators, and Methods (p. 714)
NURBSPointSurface : NURBSSurface
NURBSPointSurface : NURBSSurface This class defines an independent surface that uses points to describe its shape. Constructors: NURBSPointSurface [<property>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .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. .transform
: matrix3
The transformation matrix for the NURBSPointSurface. This controls the relative position of the item within a NURBSSet. .closedU
: boolean
true if the surface is closed in the U direction, false if open. .closedV
: boolean
true if the surface is closed in the V direction, false if open. Methods: closeU
Close the curve in U. closeV
Close the curve in V. getPoint
Get the indexed surface point as a NURBSIndependentPoint; point indexes are 1-based. setPoint
Get the indexed surface point to the given NURBSIndependentPoint; point indexes are 1-based. refineU
Add new row of interpolated points in the U direction on the surface at the given parametric V point. refineV
Add new column of interpolated points in the V direction on the surface at the given parametric U point. refine
Add a new row and column of interpolated points on the surface at the given parametric UV position.
1441
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent1
: integer
The 1st parent curve by NURBSet index. .parent1ID
: integer
The 1st parent curve by NURBSId. .parent2
: integer
The 2nd parent curve by NURBSet index. .parent2ID
: integer
The 2nd parent curve by NURBSId. .flip1
: boolean
Controls the matching of parent curve direction when creating the Ruled surface. For example, normally when you create a Ruled surface between two parent curves you don’t want a ‘bow tie’ surface (one with the ends rotated 180 degrees so it crosses on itself in the middle). If you simply match the parent direction you’ll get a ‘bow tie’ surface. To prevent this you use this property to set a state indicating that one or the other should be flipped before it’s used. In this way, when the ruled surface is created, a ‘bow tie’ won’t occur. If true, the 1st parent’s curve direction will be flipped; if false the 1st parent’s curve direction will not be flipped. .flip2
: boolean
If true, the 2nd parent’s curve direction will be flipped; if false the 2nd parent’s curve direction will not be flipped. .curveStartPoint1
: float
The start point on the 1st parent curve. This value is only applicable if the curve is closed. .curveStartPoint2
: float
The start point on the 2nd parent curve. This value is only applicable if the curve is closed.
NURBSULoftSurface : NURBSSurface
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .numCurves
: integer
The number of curves used by the U Loft. Methods: getCurve
Gets the NURBSSet index of the indexed U Loft curve; curve indexes are 1-based. setCurve <curve>
Sets the indexed U Loft curve to the curve specified by the NURBSSet index. getCurveID
Gets the NURBSId of the indexed U Loft curve in the loft; curve indexes are 1-based. setCurveByID <curveID>
Sets the indexed U Loft curve to the curve specified by the NURBSId. appendCurve <curve> [flip:] [startPoint:] \ [tension:] [useTangent:] [flipTangent:]
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 <curveID> [flip:] [startPoint:] \ [tension:] [useTangent:] [flipTangent:]
Adds a curve to the end of the list of U Loft curves by specifying the NURBSId.
1443
1444
Chapter 11
|
3ds max Objects
getFlip setFlip
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>:]...
any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .numUCurves
: integer
The number of curves in the U direction used by the UV Loft. .numVCurves
: integer
The number of curves in the V direction used by the UV Loft. Methods: getUCurve
Gets the NURBSSet index of the U direction indexed UV Loft curve; curve indexes are 1based. setUCurve <curve>
Sets the indexed UV Loft curve in the U direction to the curve specified by the NURBSSet index. getUCurveID
Gets the NURBSId of the U direction indexed UV Loft curve in the loft; curve indexes are 1-based. setUCurveByID <curveID>
Sets the indexed UV Loft curve in the U direction to the curve specified by the NURBSId. getVCurve
Gets the NURBSSet index of the V direction indexed UV Loft curve; curve indexes are 1based.
NURBSXFormSurface : NURBSSurface
setVCurve <curve>
Sets the indexed UV Loft curve in the V direction to the curve specified by the NURBSSet index. getVCurveID
Gets the NURBSId of the V direction indexed UV Loft curve in the loft; curve indexes are 1-based. setVCurveByID <curveID>
Sets the indexed UV Loft curve in the V direction to the curve specified by the NURBSId. appendUCurve <curve>
Adds a curve to the end of the list of U direction UV Loft curves by specifying the NURBSId. appendUCurveByID <curveID>
Adds a curve to the end of the list of U direction UV Loft curves by specifying the NURBSSet index. appendVCurve <curve>
Adds a curve to the end of the list of V direction UV Loft curves by specifying the NURBSSet index. appendVCurveByID <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>:]...
any of the object’s properties may be set via optional keyword arguments on the constructor. getObject
Properties: .parent
: integer
The parent surface by NURBSet index. .parentID
The parent surface by NURBSId.
: integer
1445
1446
Chapter 11
|
3ds max Objects
.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
Properties: .pos
: point2
The UV coordinate of the texture point. Methods: setIndices
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
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. .display
Properties: .displayCurves
: boolean
true if curves are displayed; otherwise false. .displaySurfaces
: boolean
true if surfaces are displayed; otherwise false. .displayLattices
: boolean
true if lattices are displayed; otherwise false. .displaySurfCVLattices
: boolean
true if surface CV lattices are displayed; otherwise false. .displayCurveCVLattices
: boolean
true if curve CV lattices are displayed; otherwise false. .displayDependents
: boolean
true if dependent sub-objects are displayed; otherwise false. .displayTrimming
: boolean
true if surface trimming is displayed; otherwise false. .degradeOnMove
: boolean
true if the surface may degrade while transforming it; otherwise false. .displayShadedLattice
: boolean
true if the NURBS surfaces appear as shaded lattices in shaded viewports and wireframe viewports display the surface’s lattice without shading. false if NURBS surfaces display as tessellated meshes in shaded viewport and wireframe viewports surfaces display as either iso curves or wire meshes.
See also Value Common Properties, Operators, and Methods (p. 714)
1447
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: .count
: Integer, read-only
Returns the number of sub-objects in the NURBSSelection array. .selSetNames
: Array of names, read-only
Returns an array of names of the current named selection sets corresponding to the NURBSSelection level for the object the NURBSSelection is associated with. The following property is present for singleton selections (of the form $foo.curveCVs[n]): .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>
| | | | | |
) ) ) ) ) )
Selects the specified sub-objects. []
Retrieves the indexed sub-object as a singleton NURBSSelection. Index starts at 1
NURBSSelection : Value
[( | )]
Retrieves the indexed sub-objects as a NURBSSelection. Index starts at 1. [( | <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. [( | <string>)] = ( | | )
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 <point3>
Moves the sub-objects in the NURBSSelection. rotate
Rotates the sub-objects in the NURBSSelection. scale <point3>
Scales the sub-objects in the NURBSSelection. select
Selects the sub-objects in the NURBSSelection. deselect
Deselects the sub-objects in the NURBSSelection. delete
Deletes the sub-objects in the NURBSSelection. append ( | )
Appends the sub-objects(s) to the NURBSSelection. findItem (:]...
any of the object’s properties may be set via optional keyword arguments on the constructor getNURBSSet <node> [#relational]
This function is used to retrieve a NURBSSet that corresponds to the specified NURBS scene node. This allows access the internal objects inside a 3ds max editable NURBS object. If the optional #relational parameter is not supplied, the returned NURBSSet will contain only independent curves and surfaces, all dependent objects will be decomposed into corresponding independent objects. So for example, if you pass an object that has a relational model (perhaps two CV surfaces and a dependent blend surface) it will decompose them into three CV surfaces. This will be the CV surfaces that represent the two surfaces and the blend, but you won’t have the blend relational data. If the #relational argument is supplied, you get back two CV surfaces and a NURBS blend surface and the NURBSSet is an active representative for the scene object -- any changes you make to the properties of it’s constituent NURBSObjects will be reflected directly in the source scene object. Properties: .numObjects .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. .viewConfig .viewIsoULines .viewIsoVLines .viewMeshUSteps .viewMeshVSteps .viewMeshApproxType
: : : : : :
#isoOnly, #isoAndMesh, #meshOnly integer integer integer integer #parametric, #spatial, #curvature,
NURBSSet : Value
: : : : : : :
#regular, #spatialAndCurvature float float float boolean #isoOnly, #isoAndMesh, #meshOnly, #regular, #spatialAndCurvature
.renderIsoULines .renderIsoVLines .renderMeshUSteps .renderMeshVSteps .renderMeshApproxType
: : : : : :
integer integer integer integer #parametric, #spatial, #curvature, #regular, #spatialAndCurvature
.renderSpacialEdge .renderCurvatureAngle .renderCurvatureDistance .renderViewDependent
: : : :
float float float boolean
.display
: NURBSDisplay
.viewSpacialEdge .viewCurvatureAngle .viewCurvatureDistance .viewViewDependent .renderConfig
Takes and returns instances of the NURBSDisplay (p. 1447) class that controls visibility of various components of a NURBS object’s display in the viewports. .viewApproximation .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. .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: [] [] =
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.
1451
1452
Chapter 11
|
3ds max Objects
Methods: appendObject
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
Set the indexed sub-object to the given NURBSObject; indexes are 1-based. You use this function to replace a previously appended object. getObject ( | )
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 subobject’s class is returned. If multiple sub-objects are specified, a NURBSSet value is returned. removeObject
Removes the given sub-object from the NURBSSet. The indexes of all the remaining higher-indexed sub-objects are renumbered down. disconnect
Disconnect a relational NURBS set from its scene object, turning it into a non-relational set. deleteObjects
This method deletes all the NURBSObjects in a NURBSSet, and frees its memory. getProdTess setProdTess getViewTess setViewTess
These methods get and set renderer and viewport NURBSSurfaceApproximation values for individual surfaces, where is one of #surface, #displacement, or #curve corresponding to the 3 kinds of tessellation that can be controlled on a surface. clearProdTess clearViewTess
Resets the surface approximation settings for the surfaces in the NURBSet for the given tessellation type, where 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
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. .viewApproximation .renderApproximation
Properties: .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. .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). .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). .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. .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.
1453
1454
Chapter 11
|
3ds max Objects
.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. .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. .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. .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. .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
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>:]...
Any of the object’s properties may be set via optional keyword arguments on the constructor. getTextureSurface .textureSurface1 .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: .type
: #default, #userDefined, #projected
The type of texture surface. .parent
: integer
The parent surface by NURBSet index. .parentID
: integer
The parent surface by NURBSId. .numUPoints .numVPoints .numPoints
: integer -- read-only : integer -- read-only : point2
The number of U and V points. Methods: getPoint setPoint
Get or set a NURBSTexturePoint value for the texture point at the U and V index of the texture surface.
1455
1456
Chapter 11
|
3ds max Objects
Associated Methods: setTextureSurface
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
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)
1457
1458
Chapter 11
|
3ds max Objects
BipedExportInterface Values The BipedExportInterface class is an interface into a Biped. Constructor: getBipedExportInterface
Returns an instance of BipedExportInterface class. The biped_node can be any node associated with the Biped system, including the footprints. Methods: setNonUniformScale
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 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>
Returns an instance of PhyContextExport class. Properties: .numVerts
Returns the number vertices in the object. This property is read-only.
PhyRigidVertex Values
Methods: convertToRigid
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
If a true value is passed then getVertexInterface() returns a PhyBlendingRigidVertex, if a vertex is blended, otherwise undefined. getVertexInterface
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
Returns the vertex given the vertex index. The vertex can be either PhyRigidVertex or PhyBlendingRigidVertex. Methods: getNode
Returns the node the vertex is linked to. getOffsetVector
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
Returns the vertex given the vertex index. The vertex can be either PhyRigidVertex or PhyBlendingRigidVertex.
1459
1460
Chapter 11
|
3ds max Objects
Properties: .numNodes
Returns the number of nodes the vertex is linked to. This property is read-only. Methods: getNode
Returns the indexed node the vertex is linked to. getOffsetVector
Returns the coordinates of the vertex in the local coordinates of indexed node. getWeight
Returns the weight of the indexed node on the vertex.
Missing Object Classes The following classes are used to represent objects in the scene for which the plug-in defining the object class is missing. An example of this is if you load a scene containing a Biped, but you do not have the character studio plugins, the biped objects will be retained in the scene, and the object’s class will be shown as the appropriate missing object class. These classes are not creatable by MAXScript and do not have any properties or methods. Missing_Atmospheric
Standin for missing Atmospheric class objects. Missing_Camera
Standin for missing Camera class objects. Missing_Float_Control
Standin for missing Float controller class objects. Missing_GeomObject
Standin for missing Geometry object class objects. Missing_Helper
Standin for missing Helper object class objects. Missing_Light
Standin for missing Light object class objects. Missing_Matrix3_Control
Standin for missing Matrix3 controller class objects. Missing_Morph_Control
Standin for missing Morph controller class objects. Missing_Mtl
Standin for missing Material class objects. Missing_OSM
Standin for missing Object Space Modifier class objects. Missing_Point3_Control
Standin for missing Point3 controller class objects. Missing_Position_Control
Standin for missing Position controller class objects.
PhyBlendingRigidVertex Values
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>
Animates one or more vertex, knot, or control point, where is one of #all #selected -- not applicable for FFD modifiers
For FFD modifiers, the animateAll() method will animate all the control points, and is equivalent to animateVertex #all. Its syntax is: animateAll
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.
1461
1462
Chapter 11
|
3ds max Objects
Examples: animateVertex $line01 2 animateVertex $box01 #(2,3,4,5) animateAll $box01.ffd_3x3x3
These animateVertex() method only work on editable meshes, spline shapes and FFD modifiers and will report an error if applied to other types of objects. You can use the functions convertToMesh() and convertToSplineShape() to convert existing geometry into the needed forms. Note that Line objects are SplineShapes already and don’t need conversion. The vertices to be animated are specified by index number, with the keyword #all to animate all vertices or control points, or #selected to animate the currently selected vertices. The #selected keyword is not applicable to FFD modifiers. In the case of SplineShapes, the vertex index numbers are interpreted in a special way to accommodate tangent handles and multiple curves, as follows: •
Each SplineShape vertex has three indexes, one for each in-tangent handle, vertex, and 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 don’t have to work with it at the script level. There are two places in the 3ds max user interface where you can install scripted rollouts: •
In the Utilities panel. You use the utility definition construct in MAXScript to define and install scripted utilities. Once installed, they appear in the Utilities list at the bottom of the MAXScript rollout. If the user selects a utility in this list, its rollout(s) appear below the MAXScript rollout and functions just like a plug-in utility.
•
In special modeless rollout floater windows that you can create with the newRolloutFloater() function. These windows appear on the desktop and function in a way similar to the Material Editor and the Selection floater in 3ds max. You can click to alternate between them and the main 3ds max user interface. You create individual rollout(s) for these windows using the rollout definition construct in MAXScript and install them in a rollout floater window using the addRollout()function.
Choosing which place is best for your scripted rollouts depends on a number of factors. It is best to keep them in the Utilities panel if possible, as that maximizes the use of the screen and is consistent with the 3ds max user interface conventions. However sometimes it is useful to have them in a modeless window if the user of your tool needs to move between the various command panels while using the tool. In some cases, you might want to provide a “float me” button on a scripted Utility rollout, similar to the Color Clipboard utility, so the user can choose to display the rollouts in a rollout floater window or in the Utilities panel. The following topics provide information about scripting utility panels and rollout floater windows: Scripted Utility Panels (p. 1464) Utility Clauses (p. 1466) Managing Multiple Rollouts in a Scripted Utility (p. 1468)
1464
Chapter 12
|
Creating MAXScript Tools
Rollout Clauses (p. 1470) Utility and Rollout Properties, Methods, and Event Handlers (p. 1474) Rollout User-Interface Controls (p. 1481) Visibility of Locals, Functions, Structures and User-Interface Items in Rollout Code (p. 1478) Accessing Locals and Other Items in a Rollout from External Code (p. 1480) Rollout Floater Windows (p. 1477)
Scripted Utility Panels A scripted utility panel is created using the utility definition construct in MAXScript. The top-level syntax is as follows: utility <description_string> [ rolledUp: ] [ silentErrors: ] ( )
The 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 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
Script: utility spread “Spread objects” -- define the utility name and description string ( local last_amt = 0 -- define and initialize local variable -checkbox x “Spread in x” -- create 3 checkboxes checkbox y “Spread in y” checkbox z “Spread in z” spinner spread “Spread amount:” range:[-1000,1000,0] -- create a spinner -on spread changed amt do -- when spinner value changes... ( delta = amt - last_amt -- calculate difference in current and previous for obj in selection do -- values for each selected object ( -- calculate new position based on current position and selection center p = obj.pos + normalize (obj.pos - selection.center) * delta if x.checked then obj.pos.x = p.x -- if checkbox x checked, apply X position if y.checked then obj.pos.y = p.y -- if checkbox y checked, apply Y position if z.checked then obj.pos.z = p.z -- if checkbox z checked, apply Z position ) last_amt = amt -- store spinner value as previous value ) -- end of “on spread changed” ) -- end of utility definition
The Utilities panel rollout created by the previous script looks like the following figure. The Close button is automatically created by MAXScript in the utility rollout, and closes the rollout.
Spread objects rollout
Evaluating a utility definition does several things. It creates a new value which is an instance of the Rollout class and contains the utility definition. It assigns this value to the named global variable and installs the utility description in the Utilities list in the MAXScript rollout. At this point, the user can select the utility from the Utilities list and the utility’s rollout(s) will open. Note: If a scripted utility already exists with the same description, the old rollout(s) is replaced with the new one(s), even if it is currently open in the Utilities panel. This allows you to incrementally develop a utility. Each time you modify and evaluate its definition, the old version is replaced with the new one.
1465
1466
Chapter 12
|
Creating MAXScript Tools
Utility Clauses The of a scripted utility definition is composed of a sequence of utility clauses as follows:
::= { }+
where ::= |
A can contain one or more instances of or . 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 is defined as follows: rollout <description_string> [ rolledUp: ] [ silentErrors: ] ( )
where
::= { }+
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
-on tea pressed do ( pot=teapot radius:rad.value pot.name=”TestPot” pot.segs=seg.value ) -- end on tea pressed -on rad changed value do pot.radius=value -on seg changed value do pot.segs=seg.value -)
-- end rollout creator
-on MyUtil open do ( addRollout bout addRollout creator ) -- end on MyUtil open -on MyUtil close do ( removeRollout bout removeRollout creator ) -- end on MyUtil close -)--end utility MyUtil
The Utilities panel rollouts created by the previous script look like the following:
Multiple rollouts defined in a utility
You can also define rollouts outside utility definitions when you want to add them to a rollout floater window that may not be associated with a scripted utility. This is described more fully in the Rollout Floater Windows (p. 1477) topic.
1467
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 [ rolledUp: ] removeRollout
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
To always open and close extra rollouts when the main utility is opened and closed, place addRollout() and removeRollout() calls in the main utility open and close handlers. For example: on foo open do ( ... addRollout panel_1 addRollout panel_2 rolledUp:true ... ) on foo close do ( ... removeRollout panel_1 removeRollout panel_2 ... )
Calling removeRollout() on an already closed rollout is OK and does nothing. If, during utility development, you forget to close a nested rollout, closing the entire MAXScript utility will remove any remaining open scripted rollouts. Because these rollout definitions are nested within a utility, all the locals, functions, and other items in the utility are visible to nested rollouts, following the standard nested scoping in MAXScript. This means you can “reach out” and access the utility’s locals, user-interface control items, and functions. Conversely, user-interface control items and locals in nested rollouts are exposed as properties of that rollout, so code in the main utility or other rollouts can “reach in” and access them. In the following example, the spinner bar change handler looks at the state of a check box in the nested rollout baz: utility foo “name” ( local ... spinner bar ... ... rollout baz “name” ( local ... checkbox baz_enable ... on ... ) ... on bar changed val do if baz.baz_enable.checked == true then ...
1469
1470
Chapter 12
|
Creating MAXScript Tools
Rollout Clauses Rollout clauses define the components of a rollout (utilities are considered a special case of rollouts) and can be one of four basic things: •
Local variables, functions, or structure definitions are variables, functions, and structures whose scope is the rollout. These locals will exist as long as the rollout value exists. The rollout value will exist until a new value is assigned to the rollout’s variable name. Local variables are particularly useful for storing working data associated with the rollout such as picked objects or arrays of generated objects. The visibility of locals, and accessing rollout locals from external code, are described in the Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code (p. 1478) and Accessing Locals and Other Items in a Rollout from External Code (p. 1480) topics.
•
Mouse tools are used to perform a set of actions based on mouse clicks in the 3ds max viewports, and are described in the Scripted Mouse Tools (p. 1531) topic.
•
User-interface control items are elements displayed in the rollout, such as buttons, spinners, and list boxes.
•
Event handlers are special kinds of functions associated with particular user-interface control items. Event handlers specify the processing you want to occur when a user interacts with a 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.
Formally, the syntax of a is defined as follows:
::= <mousetool> <user_interface_item> <event_handler>
| | | | | |
Locals: A , , and are exactly the same as local variable, function, and structure definitions in MAXScript: ::= local <decl> { , <decl> } <decl> ::= [ = <expr> ] -- optional initial value ::= [ mapped ](function | fn) { <argument> } = <expr> <member>
::= struct ( <member> { , <member> } ) ::= ( [ = <expr> ] | )
Rollout Clauses
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 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 ( { <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” )
1471
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 <event_name> [ <argument> ] do <expr>
Rollout Clauses
The specifies the name of the item to which this handler is connected. The <event_name> specifies the type of event to be handled and the optional <argument> is used to pass various values to the handler. The possible events you can specify depend on the item type. These events include: pressed changed picked entered selected resized moved open close
The available events and the arguments passed are defined in the description for each user-interface item type, as listed in the Rollout User-Interface Controls (p. 1481) topic. The available events and the arguments passed for utilities and rollouts are described in the Utility and Rollout Properties, Methods, and Event Handlers (p. 1474) topic. You can access and invoke the event handler functions in a scripted rollout by referring to the handlers as properties on the user-interface items. The event handler functions are accessed as sub-properties of the item, using the event name as the sub-property name. For example, if a scripted rollout had a check box item named foo, and an on foo changed event handler was defined, you could invoke the handler as follows: foo.changed true -- call foo’s ‘changed’ handler function, passing argument of true
Or, if a scripted rollout had a button item named apply, and an on apply pressed event handler was defined, you could invoke the handler as follows: apply.pressed() -- call apply’s ‘pressed’ handler function, no argument.
You can access an event handler function as a sub-property of the item. For example, ApplyPressedEH = apply.pressed
stores a copy of the on apply pressed event handler function value to variable ApplyPressedEH. The event handler functions can only be read in this way. You cannot set the handler function to another user-defined function.
1473
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: .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. .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
Opens the utility’s main rollout in the Utilities panel. This is equivalent to selecting the utility from the Utilities list in MAXScript’s Utilities panel rollout. closeUtility
Closes the utility’s main rollout in the Utilities panel. This is equivalent to clicking the Close button in this rollout. addRollout [ rolledUp: ]
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
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
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 open do <expr>
Called when the rollout or utility is opened. on close do <expr>
Called when the rollout or utility is closed. on oktoclose do <expr>
Called when the user clicks the rollout’s Close button so the script writer can decide whether to allow the close to proceed. If the expression evaluates to the value true, the rollout is allowed to close. If the expression evaluates to the value false, the action attempting the close is ignored and the rollout or utility is left open. on 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 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.
1475
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
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 <width_integer> \ [ ]
Creates and opens a new rollout floater window with the title and width and height given. If you don’t supply top and left coordinates, the window will open centered in the screen. The width of the 3ds max command panel is 218, in case you want to duplicate its width for precisely accommodating Utilities panel rollouts. This method returns a RolloutFloater value to which you add rollouts. closeRolloutFloater
Closes the rollout floater window. The user can also do this by clicking the close box on the window. Once closed, the window is no longer usable. All the close handlers in the rollout floater window’s rollouts are called and they are released for use in other rollout floater windows or scripted utilities. The existing functions for adding and removing rollouts to the Utilities panel are extended to work with rollout floater windows: addRollout [ ] [ rolledUp: ]
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 [ ]
Removes the rollout from the given rollout floater window. In both functions above, if the optional 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: .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. .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
1477
1478
Chapter 12
|
Creating MAXScript Tools
the resized and moved events are described in the Utility and Rollout properties, Methods, and Event Handlers (p. 1474) topic. Example: rollout grin “Grin Control” ( slider happy “Happy” orient:#vertical across:5 slider sad “Sad” orient:#vertical slider oo “OO” orient #vertical slider ee “EE” orient #vertical slider oh “OH” orient:#vertical on happy changed val do object.xform1.center = ... on sad changed val do object.xform2.gizmo.rotation = ... ... ) gw = newRolloutFloater “Grinning” 300 220 addRollout grin gw
Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code The ordering of user-interface items and functions and sub-rollouts in a utility is important when referencing other items and rollouts in handler or local function code. Specifically, you can only reference a user-interface item or rollout or function in a handler or other function if that item or rollout or function has been defined earlier in the utility. A recommended ordering can help ensure this: local variables structs user-interface items nested rollouts functions event handlers
In some situations, cross-referencing means there’s no way to order definitions and still pre-define everything. To remedy this, MAXScript lets you pre-declare local rollouts and functions, so code that comes before the function or rollout definition will see the correct object. You do this by declaring such rollouts and functions as uninitialized locals. In the following example, there are two rollouts, ro1 and ro2, that each want to reference items within the other. By pre-declaring them as locals in the main utility, this cross-referencing is possible:
Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code
utility foo “name” ( local ro1, ro2, ... -- declare local rollouts ... rollout ro1 “name” ( local ... checkbox enable ... on ... do ro2.enable.checked = false ) ... rollout ro2 “name1” ( local ... checkbox enable ... on ... do ro1.enable.checked = true ) ... )
As a general rule, it is recommended that all local variable names be explicitly declared as locals at their outermost scope. This will prevent any conflicts from occurring if another script has declared the same variable name as a global variable. While functions, structures definitions, and rollouts will always be local to the utility they are defined in (even if they have the same name as a global variable), declaring these as local will ensure the variables are defined, even if the order in which they are defined is changed. Here’s an example showing these declarations: utility foo “Object Frabulator” ( -- local variables local target_obj -- local functions local prop_name -- local rollouts local setup fn prop_name obj name = for c in obj.children do c.name = name + “_” + c.name checkbutton setup_btn “Setup” edittext name_box “New name:” -- use a checkbutton to dynamically control presence of panels on setup_btn changed state do if state then addRollout setup else removeRollout setup on foo close do removeRollout setup rollout setup “Setup fraber” (
-- always close rollouts -- local panel
1479
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 ... )
-- local panel
function frab a b = ... ... on enable changed state do ... ... )
The example defines the utility and places the utility object in a global variable named foo. You can access components in the utility from the Listener or other code as properties of that object, using the name of the variable or item as the property name. Any event-handler functions supplied for user-interface items can also be accessed as sub-properties of the item, using the event name as the property name. For example: print foo.var1 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 foo’s local variable, var1 test foo’s enabled checkbox set it call its ‘changed’ handler function call its ‘frab’ function set foo’s setup rollout local variable, var3 call ‘changed’ handler function for doit button in
Rollout User-Interface Controls Common Properties
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: [ ] [ <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 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 is used as a caption, item label, or text content depending on the control item type, as described in the topics for each type. The optional <parameters> is a sequence of keyword arguments used to set options or influence layout for the control item. The exact parameters that each control item type supports is also defined in the topics for each type. There are properties associated with each of the user-interface control item types. The properties that are common to all user-interface control item types are described in the Rollout User-Interface Controls Common Properties (p. 1481) topic. Properties that are unique to a user-interface control item type are defined in the topics for each type. As you define a sequence of control items, MAXScript will by default automatically lay them out in the rollout, one below the other in the order they are defined. You can override this layout or make adjustments to it using special layout parameters defined in the Rollout User-Interface Controls Common Layout Parameters (p. 1483) topic.
Rollout User-Interface Controls Common Properties All defined user-interface controls have a local variable constructed for them in the rollout and a value representing the control is placed in that variable. These values typically contain state information relevant to the item, such as if a check box is checked, the current spinner value, the items in a list box, and so on. This information is made available to you as various named properties on the item values. You use standard MAXScript property access to read and set these values, for example: frab_x.enabled = true
enable the frab_x spinner foo.text = “Don’t do it”
set foo button text first_item = baz.items[1]
get item list from listbox baz
1481
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: .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. .text
String
For all the user-interface items except edittext and combobox, the text property is an alias of the caption property. For edittext and combobox user-interface items, it is the text in the edit box. The default text property value for edittext user-interface items is a null string (”“). The default text property value for combobox user-interface items is the selected item’s text. .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 .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
Rollout User-Interface Controls Common Layout Parameters The layout of user-interface items defined in a utility or rollout is, by default, handled by MAXScript. It places each successive interface item down the rollout, one below the other, horizontally and vertically aligning them to match the layout conventions in the built-in 3ds max command panels. For the most part, this works well, particularly for rollouts displayed in the Utilities panel, because there is usually just enough room for one item across. In some cases, you may want to adjust or override the automatic layout and for this there are a number of definition-line layout parameters you can use. The user-interface element <parameters> that can be supplied in the item definition varies with the item type and is defined in each type’s topic, for example spinner ranges, check box initial states, list box contents, and so on. There is, however, a set of common layout parameters that you can specify on any user-interface item. Except for the pos parameter, these parameters are not properties of the user-interface item and cannot be accessed or changed by a script. The common layout parameters for all user-interface items are: align:#left align:#center align:#right
Aligns the user-interface item to the left, center, or right in the rollout. Default varies by type. offset: <point2>
default: [0,0]
Specifies an [x,y] offset in pixels relative to automatic placement. This is applied after all other layout parameters are applied, and can be used to adjust them. width:
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:
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.
1483
1484
Chapter 12
|
Creating MAXScript Tools
across:
default: 1
Causes this and following -1 items to be laid out horizontally rather than vertically. The given defines how many items to arrange horizontally. Layout then reverts to normal vertical placement. This parameter effectively divides the utility into the given number of equal-width columns and places items within them using the normal alignment for each item. The other layout parameters can be used with the across: parameter to control layout within the item’s column. pos: <point2>
default: varies
This forces the user-interface item to a fixed [x,y] pixel position in the rollout, with [0,0] at the top-left corner. Examples: button foo “foo” align:#right
normal alignment is center button baz “baz” align:#right offset:[0,6]
align right and bump this button down a bit radiobuttons btn1 “Size:” labels:#(”Big”, “Bigger”, ...) columns:3
three columns of buttons checkbutton b1 “yes” across:3 checkbutton b2 “no” checkbutton b3 “maybe”
put b1, b2, b3 across spinner s1 “Length:” align:#left
normal alignment is right
See also Rollout User-Interface Controls (p. 1481) Rollout User-Interface Controls Common Properties (p. 1481)
Rollout User-Interface Control Types There are 17 types of user-interface controls you can choose from to construct your rollout. The user-interface control types are: bitmap (p. 1487) button (p. 1488) checkbox (p. 1489) checkbutton (p. 1490) colorpicker (p. 1492) combobox (p. 1493) dropdownlist (p. 1494) edittext (p. 1496) label (p. 1497)
Rollout User-Interface Controls Common Layout Parameters
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 )
1485
1486
Chapter 12
|
Creating MAXScript Tools
The resulting Utilities panel rollout will appear as:
Utilities rollout showing all user-interface items
Bitmap
Bitmap A bitmap item is used to place a bitmap image on the rollout. The syntax is: bitmap [ ] \ [ fileName: | 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: .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
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)
1487
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 [ ] [ images: ] \ [ 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 is ignored and the contents of the button are replaced with the bitmaps. The form is: images:#(, <maskImage>, , \ <enabled_out_image_index>, <enabled_in_image_index>, \ , )
where and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. 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
Properties: .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 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 [ ] [ checked: ]
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: .checked
Boolean
The state of the check box, on (true) or off (false). .state
Synonym for .checked
Boolean
1489
1490
Chapter 12
|
Creating MAXScript Tools
Events: on 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 [ ] [ [ [ [
highlightColor: ] toolTip:<string> ] checked: ] images:
\ \ \ ]
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
images:
An image-specification array for providing bitmap images for the check button. If this is specified, the is ignored and the contents of the check button are replaced with the bitmaps. The form is: images:#(, <maskImage>, , \ <enabled_out_image_index>, <enabled_in_image_index>, \ , )
where and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. 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: .checked
Boolean
The state of the check button, on (true) or off (false). .state
Boolean
Synonym for .checked .images
Array
Sets the image-specification array for the check button. For example: -- re-render, update button bm1 = render() foo.images = #(bm1, undefined, 1, 1, 1, 1, 1)
This property is write-only. Events: on 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).
1491
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 [ ] [ color: ] \ [ fieldWidth: ] [ height: ] \ [ 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: .color
Color
The current swatch color. Events: on 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
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 [ ] [ items:<array_of_strings> ] [ selection: ] [ height: ]
\
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: .caption
String
The text of the optional caption above the combo box. .text
String
The text in the edit box. .items
Array
The item string array. .selection
Integer
The currently selected item number, 1-based. If the items list is an empty array, this value is 0. .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.
1493
1494
Chapter 12
|
Creating MAXScript Tools
Events: on 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 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 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 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 [ ] [ items:<array_of_strings> ] \ [ selection: ] [ height: ]
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
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: .items
Array
The item string array. .selection
Integer
The currently selected item number, 1-based. If the items list is an empty array, this value is 0. .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 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)
1495
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 [ ] [ text:<string> ] \ [ fieldWidth: ] [bold: ]
The default alignment of edittext items is #left. Example: edittext prefix_txt “Name prefix:” fieldWidth:70 on prefix_txt entered text do ... ... new_obj = copy master pos:[x,y,z] prefix:prefix_txt.text ...
Parameters: text:
The text string in the edit box. fieldWidth:
The width in pixels of the edit box. By default, the width is set to be from just after the caption text to the right margin of the rollout. bold:
If set to true, the text string in the edit box is displayed in bold format, if set to false, in normal, non-bold format. The default value is false. Properties: <edittext>.text
String
The text in the edit box. <edittext>.caption
String
The text of the optional caption next to the edit box. <edittext>.bold
Boolean
If true, the text is displayed in bold format, if false, in normal, non-bold format. Events: on <edittext> changed <arg> do <expr>
Called each time the user changes the text in the edit box; the <arg> argument contains the new text in the edit box. on <edittext> entered <arg> do <expr>
Called when the user enters text in the edit box and then presses ENTER or TAB to move the cursor out of the field. The <arg> argument contains the new text in the edit box. If you enter a string in the edit box and then press ENTER, the on changed handler is called once per character and once for the ENTER. The on entered handler is just called once, for the ENTER.
Label
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 [ <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 [ ] [ items:<array_of_strings> ] \ [ selection: ] [ height: ]
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
1497
1498
Chapter 12
|
Creating MAXScript Tools
Parameters: items:
The array of text strings that are the items in the list. selection:
The 1-based number of the currently selected item in the list. The default selection value is 1. height:
The overall height of the listbox in number of item lines. Defaults to 10 lines. To have a listBox display exactly N items, set height to N. Properties: <listbox>.items
String
The item string array. <listbox>.selection
Integer
The currently selected item number, 1-based. If the items list is an empty array, this value is 0. <listbox>.selected
String
The text of the currently selected item. Can be used to replace individual items with resetting the entire items array. If the items list is an empty array, this value is undefined. Events: on <listbox> selected <arg> do <expr>
Called when the user selects an item in the list. The <arg> argument contains the new current selection item number. on <listbox> doubleClicked <arg> do <expr>
Called when the user double-clicks on an item in the list. Note that the on selected handler is always called on single clicks and on the first click of a double-click. The <arg> argument contains the number of the item double-clicked. For example, listbox foo items:#(...) on foo doubleClicked sel do ...
See also Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)
Mapbutton
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 [ ] [ map: ] \ [ images: ] [ toolTip:<string> ]
The default alignment of mapbutton items is #center. Example: label mapbutton
sbm_lbl “Background Map:” choosemap “>“ 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 is ignored and the contents of the mapbutton are replaced with the bitmaps. The form is: images:#(, <maskImage>, , \ <enabled_out_image_index>, <enabled_in_image_index>, \ , )
where and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. 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.
1499
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 [ ] [ material:<material> ] \ [ images: ] \ [ toolTip:<string> ]
The default alignment of materialbutton items is #center.
Materialbutton
Example: label materialbutton
smtl_lbl “Set selected object’s 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 is ignored and the contents of the materialbutton are replaced with the bitmaps. The form is: images:#(, <maskImage>, , \ <enabled_out_image_index>, <enabled_in_image_index>, \ , )
where and <maskImage> can be either a bitmap file name string or a MAXScript bitmap value. 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.
1501
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 [ ] [ items:<array_of_strings> ] \ [ selection:{ | | } ] \ [ height: ]
The default alignment of MultiListBox items is #left.
MultiListBox
Example: rollout test “test” (MultiListBox mlb “MultiListBox” items:#(”A”,”B”,”C”) selection:#(1,3) on mlb selected val do format “selected: % - %\n” val mlb.selection[val] on mlb doubleclicked val do format “doubleclicked: % - %\n” val mlb.selection[val] on mlb selectionEnd do format “selectionEnd: %\n” mlb.selection ) rof=newrolloutfloater “tester” 200 300 addrollout test rof test.mlb.items test.mlb.selection=1 test.mlb.selection=#(1,3) test.mlb.selection=#{}
Parameters: items:
The array of text strings that are the items in the list. selection:
A BitArray signifying the currently selected items in the list. The default selection value is #{}. height:
The overall height of the MultiListBox in number of item lines. Defaults to 10 lines. To have a MultiListBox display exactly N items, set height to N. Properties: <listbox>.items
Array of Strings
The item string array. <listbox>.selection
BitArray
The currently selected items. When setting the selection via a script, the selection can be specified as a BitArray, Array of numbers, or a number. If the items list is an empty array, this value is 0. Events: on <listbox> selected <arg> do <expr>
Called when the user selects or deselects an item in the list. The <arg> argument contains the index of the item that was selected or deselected. Since multiple items can be selected or deselected at once, this handler is called for each item in the list, starting from the top of the list, whose selection has changed. on <listbox> doubleClicked <arg> do <expr>
Called when the user double-clicks on an item in the list. Note that the on selected handler is always called on single clicks and on the first click of a double-click. The <arg> argument contains the number of the item double-clicked. on <listbox> selectionEnd do <expr>
Called when the user selects or deselects an item in the list, but after all the calls to the on selected handler have been made.
1503
1504
Chapter 12
|
Creating MAXScript Tools
Notes: There isn’t a way to deselect all the items in the list by clicking in the list somewhere. To clear the list selection you will need a “Clear Selection” button that sets selection=#{}.
Pickbutton A pickbutton item is used to place a scene object-picker button on the rollout. It operates like a normal pick button in the 3ds max user interface, turning light-green when pressed and causing an object-pick mode to be entered. The user can then choose a scene object by clicking on it. The pick mode exits and the button returns to its unpressed state. The user can right-click to cancel the pick mode. The syntax is: pickbutton [ ] [ message:<string> ] \ [ filter: ] [ 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: .object
Node
The last object picked using the pickbutton, undefined if no object has been picked. This property is read-only.
ProgressBar
Events: on 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 [ value: ] [ color: ] \ [ orient: ]
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.
1505
1506
Chapter 12
|
Creating MAXScript Tools
Properties: <progressbar>.value
Integer
The progress bar complete percentage (0 – 100). <progressbar>.color
Color
The color of the progress bar. <progressbar>.orient
Name
The orientation of the progress bar fill: #horizontal - left to right; #vertical - bottom to top. Events: on <progressbar> clicked <arg> do <expr>
Called when user clicks on the progress bar. The <arg> argument contains the percentage value at the clicked point.
See also Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)
Radiobuttons A radiobuttons item is used to place a set of radio buttons on the rollout, only one of which can be checked at a time. The user can click different buttons in the set to change states. The syntax is: radiobuttons [ ] labels:<array_of_strings> \ [ default: ] [ columns: ]
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
Parameters: labels:
An array of strings that specifies the number of radio buttons and the text label for each one. default:
The number of the radio button initially selected. Default is 1. columns:
Number of columns across in which to arrange the buttons. By default, MAXScript will attempt to lay out all the radio buttons side-by-side on one line, and if they won’t fit, vertically in a single column. You can force the layout system to array the buttons in multiple columns using this parameter. Each column is given the same width, which is the width of the widest label in all columns and it left-adjusts the radio buttons in these columns. Properties: .state
Integer
The 1-based number of the currently selected radio button in the order specified in the labels: array. Events: on changed <arg> do <expr>
Called when the user clicks one of the radio buttons in the set. The <arg> argument contains the new state of the radio buttons array, which is the 1-based number of the newly selected button.
See also Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)
Slider A slider item is used to place a slider on the rollout, as an alternative to a spinner. The user can drag the slider’s pointer around to set its value. The syntax is: slider [ ] [ range:[min,max,val] ] \ [ type:#float ] [ ticks:10 ] \ [ orient:#horizontal ]
The default alignment of slider items is #center.
1507
1508
Chapter 12
|
Creating MAXScript Tools
Example: slider tilt “Head tilt” orient:#vertical ticks:0 range:[-30,30,0] on tilt changed val do $head.bend.angle = val
Parameters: range:
A Point3 value containing the minimum, maximum and initial values for the slider in the x, y, and z components, respectively. Defaults to [0,100,0]. type:
The type of the slider, #float or #integer. Defaults to #float. orient:
The layout orientation of the slider in the rollout, either #vertical or #horizontal. Defaults to #horizontal. ticks:
Specifies how many ticks to place along the slider bar. No ticks are drawn if you specify ticks:0. Defaults to 10. Properties: <slider>.range
Point3
The current range and value for the slider, as a Point3 like the range: parameter. <slider>.value
Float
The current value of the slider. <slider>.ticks
Integer
The number of ticks along the slider. Events: on <slider> changed <arg> do <expr>
Called when the user moves the slider pointer. The <arg> argument contains the new value of the slider. on <slider> buttondown do <expr>
Called when the user first clicks the slider. on <slider> buttonup do <expr>
Called when the user releases the slider. The buttonDown and buttonUp events effectively notify you of the start and end of a slider “twiddle”, allowing you to perform some setup for the adjustment. A typical use for this is to bring scene nodes that are being modified in the on <slider> changed handler into the foreground plane to speed up screen redraw. For example: spinner foo “height: “ on foo buttonDown do flagForeground $baz...* true on foo buttonUp do flagForeground $baz...* false
Spinner
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>
-- mapped
The boolean argument puts the scene node(s) into the foreground plane if true, or into the background plane if false. You should be judicious in putting objects in the foreground plane, because putting too many objects in the foreground plane reduces the foreground plane’s effectiveness. Remember to return objects to the background plane when you don’t need to interactively control them any more.
See also Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)
Spinner A spinner item is used to place a 3ds max value spinner on the rollout. The user can drag the spinner arrows or type values into the spinner edit field. The syntax is: spinner [ ] [ range:[min,max,val] ] \ [ type: ] [ scale: ] \ [ fieldWidth: ] [ 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.
1509
1510
Chapter 12
|
Creating MAXScript Tools
scale:
The scale of the spinner specifies the smallest value increment. Defaults to 0.1 for floats, 1 for integers. fieldwidth:
The width in pixels of the spinner text-edit field. By default, the spinner is placed so the left edge of the edit field is exactly in the center of the rollout and right edge is placed at the right margin. You can control how wide the field is using this parameter. controller:
Links the spinner to the specified controller. This lets you establish a direct link between the spinner and the controller. Changes to the spinner will automatically update the controller (and its controlled objects). Changes to the controller automatically update the spinner. For example, say you have a sphere called $ball with a float controller already assigned to its radius, then the following code: utility foo “foo” ( spinner ball_radius “Ball radius” range:[0,1000,1] \ controller:$ball.radius.controller )
sets up a spinner that automatically affects and tracks the radius of the scene node $ball. Any changes to the spinner update $ball’s radius. Any other changes to $ball’s radius, say in the Modify panel or because of animation, will update the spinner. Note that this links to controllers, so the specified controller must already exist before creating the spinner user-interface item. You can either specify a controller already assigned to the parameter you want to link to, or you can create the controller in your script and then assign that controller to the parameter of interest. For example: utility foo “foo” ( local myController=bezier_float() spinner ball_radius “Ball radius” range:[0,1000,1] \ controller:myController button apply “Apply Radius Controller” on apply pressed do ( animate off at time 0 $ball.radius=myController.value $ball.radius.controller=myController ) )
Properties: <spinner>.range
Point3
The current range and value for the spinner, as a Point3 like the range: parameter. <spinner>.value
Float
The current value of the spinner.
Spinner
Events: on <spinner> changed <arg> do <expr>
Called when the user spins the spinner, or when the user enters a value in the spinner field then presses ENTER or presses TAB to move the cursor out of the field. The <arg> argument contains the new value of the spinner. on <spinner> entered do <expr>
Called when the user types a number into a spinners edit field and then presses ENTER or presses TAB to move the cursor out of the field. The on <spinner> changed handler, if supplied, has already been called at this point and the spinner’s value property is up to date. on <spinner> buttondown do <expr>
Called when the user first clicks the spinner. on <spinner> buttonup do <expr>
Called when the user releases the spinner. The buttonDown and buttonUp events effectively notify you of the start and end of a spinner “twiddle”, allowing you to perform some setup for the adjustment. A typical use for this is to bring scene nodes that are being modified in the on <spinner> changed handler into the foreground plane to speed up screen redraw. For example: spinner foo “height: “ on foo buttonDown do flagForeground $baz...* true on foo buttonUp do flagForeground $baz...* false
Notes: If you are using a spinner to interactive adjust a property of an on-screen object, you can improve the interactive speed by moving the object to the foreground plane. Objects placed in the foreground plane are redrawn individually and so interactive changes to them are much faster. An object is moved to the foreground or background plane using the flagForeground() method: flagForeground <node>
-- mapped
The boolean argument puts the scene node(s) into the foreground plane if true, or into the background plane if false. You should be judicious in putting objects in the foreground plane, because putting too many objects in the foreground plane reduces the foreground plane’s effectiveness. Remember to return objects to the background plane when you don’t need to interactively control them any more.
See also Rollout User-Interface Items Common Properties (p. 1481) Rollout User-Interface Items Common Layout Parameters (p. 1483) Rollout User-Interface Control Types (p. 1484)
1511
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 [ interval: ] [ active: ]
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: .interval
Integer
Integer value specifying the time in milliseconds between tick events. .active
Boolean
Specifies whether the timer emits tick events (true) or not (false). When first set to true, the first tick event is generated in interval milliseconds. Events: on 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
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:#(, <maskImage>, , \ <enabled_out_image_index>, <enabled_in_image_index>, \ , )
where and <maskImage> can be either a bitmap file-name string or a MAXScript bitmap value. 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)
1513
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 ( )
where: is the name of an automatically created global variable to hold the rcmenu value that represents the right-click menu. 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
registers the specified right-click menu unRegisterRightClickMenu
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
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 of a right-click menu definition is made up of a sequence of scripted right-click menu clauses as follows:
::= { }+
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.
1515
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 is defined as follows:
::= <user_interface_item> <event_handler>
| | | |
Locals: A , , and are exactly the same as local variable, function, and structure definitions in MAXScript: ::= local <decl> { , <decl> } <decl> ::= [ = <expr> ] -- optional initial value ::= [ mapped ](function | fn) { <argument> } = <expr> <member>
::= struct ( <member> { , <member> } ) ::= ( [ = <expr> ] | )
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
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 <event_name> do <expr>
The 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 open do <expr>
See also Scripted Right-Click Menus (p. 1514)
1517
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 [ checked: ] [ enabled: ] [ filter: ]
Parameters: name:
Used to refer to when writing an event handler. label:
The string that appears in the right-click menu. checked:
Specifies if a check mark appears before the label in the right-click menu. If true the item is checked, otherwise the item is unchecked. enabled:
Specifies if the item is enabled for interaction when the right-click menu is opened. If true the item is enabled, otherwise the item is disabled and appears unavailable. filter:
A function that returns a Boolean value. The filter function is evaluated when the right-click menu is first opened. If the filter function returns true the menuItem appears in the menu, otherwise it is not displayed. Properties: <menuitem>.text
String
The string that appears in the right-click menu. <menuitem>.checked
Boolean
Specifies if a check-mark appears before the label in the right-click menu. If true the item is checked, otherwise the item is unchecked. <menuitem>.enabled
Boolean
Specifies if the item is enabled for interaction when the right-click menu is opened. If true the item is enabled, otherwise the item is disabled and appears as unavailable. Events: on <menuitem> picked do <expr>
Called when the user clicks the menu item.
separator
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 [ filter: ]
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
1519
1520
Chapter 12
|
menuItem
Creating MAXScript Tools
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 [ filter: ] ( <submenu_body> )
The <submenu_body> of a subMenu definition is made up of a sequence of RCMenu clauses as follows: <submenu_body>
::= { }+
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
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 [ [ [ [ [ ( <macro_script_body>
category:<string> ] buttonText:<string> ] toolTip:<string> ] icon:#(<string>, ) | icon:<string> ] silentErrors: ] )
1521
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
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, specifies which icon in the icon bitmap file to use. The left-most icon has an of 1. The 3ds max internal icons (Image Group Internal in the Customize User-Interface dialog) are not stored in an icon file, and are referenced by using an empty string as the icon: argument. So, the icon: argument can be either a two-element array containing the icon bitmap file’s base name as a string and the icon’s index in that file, or just a base name string, with the index 1 assumed. For example: macroScript Box category:”Objects” tooltip:”Box” icon:#(”standard”, 1) -- use first icon in standard ( StartObjectCreation Box ) macroScript Sphere category:”Objects” tooltip:”Sphere” icon:#(”“, 2) -- use second icon in internal icons ( StartObjectCreation Sphere ) macroScript Cone category:”Objects” tooltip:”Cone” icon:”myicon” -- use first icon in myicon ( StartObjectCreation Cone )
See the Creating Icon Bitmap Files (p. 1530) topic for more information.
1523
1524
Chapter 12
|
Creating MAXScript Tools
The silentErrors: parameter gives control over whether MAXScript runtime error messages are displayed while executing the Macro Script. If this parameter is set to true, error messages will not be displayed. This may be useful for distributed Macro Scripts that may confuse the user with MAXScript error messages. The default value is false. The <macro_script_body> is any valid MAXScript expression, and can contain global and local variables, functions, and structure definitions. The <macro_script_body> is compiled in its own local scope, and the locals are only visible inside the scope of the Macro Script. Macro Script locals are heap-based locals, which are slightly different from normal (stack-based) locals. Normal locals are visible in the current scope and have a lifetime of one execution of that scope. Heap-based locals are also visible only in the current scope, but have a lifetime equal to the lifetime of the top-level expression where they are defined. A Macro Script’s locals are created the first time you execute the Macro Script, initialized to a value of undefined, or to their specified initialization value. These values are stored in a separate memory stack. On entry to each function (or top level script) in the Macro Script, a ‘frame’ in the memory stack is marked and when the function (or top level script) exits, all of the values in the frame are freed from the memory. Because a Macro Script’s name is not created as a variable, you cannot access a Macro Script’s locals outside the scope of the Macro Script. So, for example, you can create a rollout in a Macro Script, and the rollout’s event handlers can access the locals defined in the Macro Script because the rollout is executing within the scope of the Macro Script. However, you cannot access the Macro Script’s locals from another utility or from the Listener, because they are not executing within the scope of the Macro Script. See the Scope of Variables (p. 646) topic for more information. When you execute a macroScript definition, the return value is an integer Macro Script ID value. MAXScript internally stores information about each Macro Script in an array, and the returned Macro Script ID value is the array index for that Macro Script. The information stored for each Macro Script consists of the file in which that Macro Script is defined and a pointer into that file specifying where the Macro Script definition begins. The Macro Script definition is only compiled when you first press a toolbar button that contains the script, or execute the Macro Script using the macros.run() method. There are five ways a Macro Script can be defined: •
The default user-interface directory and its subdirectories will be automatically scanned at startup for files of type .mcr, which will be parsed for Macro Script definitions.
•
A Macro Script definition is executed in an Editor window, in a script file that you execute, or in a startup script file.
•
If you evaluate a Macro Script definition in the Listener window, a file will automatically be created to contain the Macro Script definition. This file is stored in the MacroScripts directory under the current user-interface directory.
•
MAXScript supports text drag onto toolbars to create Macro Script buttons. You can select and drag text from any text window, such as Listener window panes or Editor windows, onto any visible toolbar. The cursor changes to an arrow with + sign when it is OK to drop the text. If you drop it, a Macro Script button is added to the toolbar with the dropped text as the body of the Macro Script. The classic case here would be to drag some text from the Macro Recorder pane in
subMenu
the Listener window onto a toolbar to make a button that does the sequence of events just recorded. Remember that tabbed elements on the Shelf are toolbars and can accept dropped text. MAXScript will automatically enclose the text in a Macro Script definition with a Macro Script name of DragAndDrop-MacroN, where N is a number that will make the Macro Script name unique. The category will be DragAndDrop and no tooltip is specified. As with Macro Scripts defined in the Listener window, a file will automatically be created to contain the Macro Script definition. This file is stored in the MacroScripts directory under the current user-interface directory. •
A Macro Script can be defined using the macros.new() method described next. As with Macro Scripts defined in the Listener window, a file will automatically be created to contain the Macro Script definition. This file is stored in the MacroScripts directory under the current user-interface directory.
If you move or delete a file that contains a Macro Script definition that has been loaded, and try to execute the Macro Script, you will get an error message. Further, if you edit a file containing Macro Script definitions, take care to save and re-evaluate the entire file so any other Macro Scripts defined in that file will have their file pointer updated. If you don’t do this, you may get an error message saying the currently loaded definition no longer matches its file. If you reevaluate a Macro Script definition, any button using that Macro Script will see any changes you make. Any macroScript definition evaluated in MAXScript or created by dropping text onto a toolbar has a separate definition .mcr file created in the MacroScripts directory under the current user-interface directory (typically UI\MacroScripts). The name of the file is -<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.
1525
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 \
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 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 macros.edit <macro_id_integer>
These methods will open the Macro Script definition (.mcr) file that defines the specified Macro Script in a script Editor window. The Macro Script is identified by either its category and name, or by its unique Macro Script ID value. For example: macros.load “f:/gametools/macros” macros.edit “objects” “box” macros.run 132 macros.run “modifiers” “bend”
Examples: The following Macro Script will save the active viewport’s image to a bitmap file. Script: MacroScript GrabViewport category:”Tools” tooltip:”Grab Viewport” ( ----------------------------------------------------------------------GRABVIEWPORT MACROSCRIPT --Created:3/23/99 --Edited:4/28/99 --by Borislav Petrov [email protected] ----------------------------------------------------------------------Snapshot Active Viewport to Bitmap --Filename in format: --VPGRAB_MaxFileName_ViewportName_CurentFrame.ImageFormatExtension
subMenu
-----------------------------------------------------------------------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
1527
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 “[email protected]” 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
r_from.enabled = r_to.enabled = false ) 3: nth.enabled = r_from.enabled = r_to.enabled = true ) ) -on on on on on on
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)
-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
1529
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
Scripted Mouse Tools Scripted Mouse Tools are used to perform a set of actions based on mouse clicks in the 3ds max viewports. Tools are useful for scripted object creation plug-ins, as described in the Scripted Plug-ins (p. 1538) topic. Here’s a simple example: Script: tool foo ( local b on mousePoint clickno do if clickno == 1 then b = box pos:worldPoint else #stop on mouseMove clickno do b.pos = worldPoint )
This tool allows the user to click in a viewport at which point a box is created. Dragging the mouse positions the box and releasing the mouse button stops the tool. You’d start this tool by executing: startTool foo
The syntax for tools is similar to that for utility definition constructs. They have local variables, functions, and event handlers, but tools have no user-interface items. A tool is created using the tool definition construct in MAXScript. The top-level syntax is as follows: tool [ prompt:<string> ] [ numPoints: ] ( )
where: 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. 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 [ prompt:<string> ] [ snap:#3D|#2D ] \ [ numPoints: ]
where: is the tool name used in a tool definition.
1531
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
where: 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 of a mouse tool definition is made up of a sequence of tool clauses as follows:
::= { }+
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 is compiled in its own local scope and the locals are only visible inside the scope of the tool. Tool locals are heap-based locals, which are slightly different from normal (stack-based) locals. Normal locals are visible in the current scope and have a lifetime of one execution of that scope. Heap-based locals are also visible only in the current scope, but have a lifetime equal to the lifetime of the top-level expression where they are defined. A tool’s locals are created the first time you execute the tool and are kept permanently in the heap (unless and until you redefine the tool). This means things like rollouts created in a tool that live beyond the simple execution of the tool can refer to these locals and the locals will still exist. Each time you execute a tool, its local variables are initialized to a value of undefined, or to their specified initialization value. For example, you can create a rollout in a tool, and the rollout’s event handlers can access the locals defined in the tool because the rollout is executing within the scope of the tool. You cannot access the tool’s locals from another utility
Mouse Tool Clauses
or from Listener, because they are not executing within the scope of the tool. See the Scope of Variables (p. 646) topic for more information. •
Event handlers are special kinds of functions associated with particular events. Event handlers specify the processing you want to occur when a user clicks or moves a mouse, right-clicks, or starts or stops the tool. These actions generate named events and the optional event handler you supply for that event is called when the action occurs.
Formally, the syntax of a is defined as follows:
::= | | | <event_handler>
Locals: A , , and are exactly the same as local variable, function, and structure definitions in MAXScript: ::= local <decl> { , <decl> } <decl> ::= [ = <expr> ] -- optional initial value ::= [ mapped ](function | fn) { <argument> } = <expr> <member>
::= struct ( <member> { , <member> } ) ::= ( [ = <expr> ] | )
Global variables cannot be declared as a tool clause, however they can be declared within event handler scripts. If you need to ensure a variable name references a global variable, declare the variable name as global immediately before defining the tool in your script. When writing scripts, it is good programming practice to explicitly declare your local and global variables. Implicit declaration is provided as a short-hand, typically used when working in the Listener interactively or developing short scripts. When developing extended scripts, explicitly declaring variables can reduce errors and improve readability of the code. It is also recommend that you declare as local all variables unless you really want them to be global variables. The reasons for this are described in the Scope of Variables (p. 646) topic. Within the functions and event handlers of a tool, 13 pre-defined locals variables are always accessible. Each one holds a useful value relating to the mouse action that just occurred: viewPoint
Point2
The current mouse position in viewport pixel coordinates. worldPoint
Point3
The current mouse position projected on the active grid in world coordinates. worldDist
Point3
The distance in X, Y, and Z from the previous click point to the current click point in world coordinates. worldAngle
Point3
The angles around the world X, Y, and Z axes from the previous click point to the current click point in world coordinates.
1533
1534
Chapter 12
gridPoint
|
Creating MAXScript Tools
Point3
The current mouse position projected on the active grid in the coordinate system of the active grid. If the active grid is the home grid, the coordinate system is the home grid plane active in the current viewport (that is, the construction plane). See the discussion of grid versus world values below. gridDist
Point3
The distance in X, Y, and Z from the previous click point to the current click point in the coordinate system of the active grid. If the active grid is the home grid, the coordinate system is the home grid plane active in the current viewport (that is, the construction plane). See the discussion of grid versus world values below. gridAngle
Point3
The angles around the world X, Y, and Z axes from the previous click point to the current click point in the coordinate system of the active grid. If the active grid is the home grid, the coordinate system is the home grid plane active in the current viewport (that is, the construction plane). See the discussion of grid versus world values below. shiftKey
Boolean
true if SHIFT key was down. ctrlKey
Boolean
true if CTRL key was down. altKey
Boolean
true if ALT key was down. lButton
Boolean
true if left mouse button was down. mButton
Boolean
true if middle mouse button was down. rButton
Boolean
true if right mouse button was down. When a create mouse tool is used in a level 5 scripted plug-in, an additional local variable is accessible: nodeTM
Matrix3
Provides read/write access to the transform of the node currently being created. This value is in the current grid coordinate system. See the Scripted Plug-ins (p. 1538) topic for more information. When writing SimpleObject scripted plug-ins, you should always use the gridPoint, gridDist, and gridAngle values rather than corresponding world values, as object-creation in SimpleObject scripted plug-ins is managed in the active grid coordinate system. For gridDist, the .X and .Y components are the delta X and Y between the previous clicked point and the current mouse point in the plane of the current grid. The .Z component is a projection from the current Y screen coordinates onto a Z-vector (in the grid coordinate system) based at the last point clicked on the grid, such that the .Z value is the projected height up the Z-vector. For nonorthogonal viewports this is as expected, but for orthogonal viewports (in which you are always
Mouse Tool Clauses
dragging in the XY plane of the grid), this is always the same as gridDist.y. If you are using the gridDist value to build the portion of an object on the grid, or determine the distance on the current grid from the last point, you want to use only the .X and .Y components. For example, side1Len = gridDist.x side2Len = gridDist.y dist=length [gridDist.x,gridDist.y]
If you are specifying the height off of the current grid, you would typically use the .Z component. For example, height = gridDist.z
For worldDist, the behavior is similar to that for gridDist, however the projected component is dependent on the construction plane of the viewport. For the Top, Bottom, and non-orthogonal viewports, the projected height is contained in the .Z component. For Left and Right viewports, the projected height is contained in the .X component. For Front and Back viewports, the projected height is contained in the .Y component. When you create a node in the 3ds max user-interface, the local Z axis of the node is perpendicular to the construction plane. When you create a node using MAXScript, by default the local Z axis of the node points along the direction of the world Z axis. If you create a node in a tool (other than in a SimpleObject scripted plug-in), you must take into account the construction plane orientation if you want to duplicate 3ds max’s behavior when creating a node. The easiest way to do this is to create the node in a coordsys grid context and specify the position of the node during creation in grid coordinate space. An example of this is shown in the following script. Script: tool PointCreator ( local p, createpoint -- define a function to perform actual node creation. Setting coordsys to -- ‘grid’ in order for the alignment of the node’s local Z axis to be -- perpendicular to the construction grid fn createpoint = in coordsys grid p=point pos:gridPoint --- set up so that a node is created on a mouse button down, move node -- drag, release node at mouse button up. --- if clickno == 1, then we are at first mouse click, which is a mouse -- button down. If clickno != 1, at following mouse button up. on mousePoint clickno do ( if clickno == 1 then createPoint() -- if p == undefined, then clicked twice without mouse movement -- (double clicked). No point object present, so just ignore this click. else if p != undefined do (p.pos=worldPoint;p=undefined) ) --- if p != undefined, we are moving a previously created node -- if p == undefined, and left mouse button is down, create a node on mouseMove clickno do
1535
1536
Chapter 12
( if
|
Creating MAXScript Tools
p != undefined then p.pos=worldPoint else if lbutton do createPoint()
) ) -- start the tool. No exit condition defined, so right-click to exit. startTool PointCreator
Event Handlers: An <event_handler> is a special function definition local to a tool that you provide to handle the processing you want to occur when a user clicks in a viewport, right-clicks, or starts or stops the tool. Each user action generates a named event and any event handler you supply for that event is called when the action occurs. The available event handlers are: on start do <expr>
Called when the tool starts. on end do <expr>
Called when the tool ends. on freeMove do <expr>
Called when the mouse moves prior to the first click. on mousePoint <arg> do <expr>
Called for each mouse click, parameter arg contains the number of the click. on mouseMove <arg> do <expr>
Called when the mouse moves anytime after the first click. on mouseAbort <arg> do <expr>
Called when the user right-clicks to cancel or presses the ESC key. The <arg> parameter on each of the mouse event handlers lets you know which mouse click you are in. Mouse clicks are actually only the mouse click release, except for the initial mouse click. If you do a mouse click, drag, release, move, click, drag, and release, the on mousePoint event handler is called three times: the first click, the first release, and the second release, with <arg> values of 1, 2, and 3, respectively. The mouse click counter is incremented after processing the on mousePoint event handler, so the <arg> parameter for the mouseMove and mouseAbort event handlers specify the click count for the next mouse click. In the previous example, when you drag between the first click and first release, the <arg> value for a mouseMove event handler will have a value of 2. During the following move, click, and drag it will have a value of 3. The following script simply demonstrates when the various event handlers are called. Simply run this script and drag in the viewports. Right-click or press the ESC key to stop the tool’s execution.
Mouse Tool Clauses
Script: tool foo ( on freeMove do print “Free Moving” on mousePoint clickno do format “Point: %\n” clickno on mouseAbort clickno do format “Abort: %\n” clickno on mouseMove clickno do format “Moving: %\n” clickno on start do print “Starting” on end do print “Ending” ) startTool foo prompt:”Hello!”
All of the mouse action event handlers may return the special value #stop which causes the tool to stop. In the following mousePoint event handler example, the first click creates the box and the release (second click) terminates the tool. on mousePoint clickno do if clickno == 1 then b = box pos:worldPoint else #stop
Example: The following script implements the following functions: on mouse click three spot lights are created at the mouse point. While holding the mouse button down, drag the mouse to position the classical key, back and fill light positions. During this drag, holding down the SHIFT key will flip the fill light side. Release the mouse button and move the mouse to change the elevation of the lights. Click the mouse button when the lights are at the correct height. The back light is raised 1.5 times the key light’s height, and the fill light is raised 0.75 times the key light’s height. To start this tool, you’d say: startTool three_lights
and then drag in one of the viewports. Script: tool three_lights ( local key, fill, back, targ -on mousePoint click do coordsys grid ( if click == 1 then -- create key, back & fill lights at mousedown ( targ=targetobject pos:gridPoint key = targetspot pos:gridPoint name:”key” target:targ back = targetspot pos:gridPoint name:”back” target:targ fill = targetspot pos:gridPoint name:”fill” target:targ ) if click == 3 then #stop ) -on mouseMove click do ( if click == 2 then -- drag out & round on x-y plane ( coordsys grid key.pos = gridPoint
1537
1538
Chapter 12
|
Creating MAXScript Tools
coordsys targ back.pos = - key.pos local p = if shiftKey then 90 else -90 coordsys targ fill.pos = key.pos * ((eulerangles 0 0 p) as quat) ) else if click == 3 then -- drag up to elevate lights ( in coordsys targ ( local Z = gridDist.z key.pos.z = Z back.pos.z = Z * 1.5 fill.pos.z = Z * 0.5 ) ) ) )
See also Scripted Mouse Tools (p. 1531)
Scripted Plug-ins MAXScript supports several levels of scripted plug-ins, as follows: The scripted plug-in appears in the user interface as a new class but does not allow instances of itself in the scene. It lets you define a mouse tool that creates other objects in the scene, but once you’ve finished creation, there is no instance of the class left in the scene to modify or save. Examples of this currently in 3ds max are the System classes such as RingArray. The scripted plug-in extends an existing plug-in, either adding to or replacing the command panel parameter rollouts for the existing plug-in. For example, you might create a new “glass” material which extends StandardMaterial and provides a custom, presumably smaller, Material Editor rollout that just has glass parameters which set up and modify various properties in the underlying material plug-in as appropriate. Or, you want to create a new light type that is actually a system of coordinated lights, that also has a “controlling” dummy object created. This controlling dummy keeps track of the lights in the system and has a Create/Modify panel rollout that allows coordinated manipulation of the system. In this case, you’d create a new helper plug-in that extends Dummy, has locals to store the lights, and define a rollout. You would also create a new light plug-in with a create tool that builds the system. The scripted plug-in is given a unique and permanent class ID value by the script writer and so can be instanced in the scene and stored in scene files. All 3ds max plug-ins have a unique class ID and 3ds max uses this class ID to associate stored scene objects with the code that handles them each time you open a scene file, hence it has to be unique and permanent. In the level 1 scripted plug-in above, MAXScript allocates a temporary class ID that is not permanent across executions of 3ds max and thus prevents instancing in the scene. The scripted plug-in defines one or more parameter blocks, containing directly animatable parameters that are saved to and restored from scene files. These are the permanent parameters for the plug-in and are distinct from the local variables in the example above which only live during creation.
Mouse Tool Clauses
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> {keyword:val} ( )
where: <superclass> is one of the currently-supported plug-in superclasses: Geometry SimpleObject Shape Light Helper Modifier SimpleMod Material TextureMap RenderEffect Atmospheric
is the name that will be given to the global variable that contains this plug-in class. This class value is just like a normal plug-in class (like box, sphere, etc.) and you can create an instance of the plug-in in MAXScript by applying the class value. {keyword:val} is an optional sequence of keyword/value pairs defining options for the plug-in. These pairs are: name:<string>
The optional name: parameter specifies the name of the plug-in as seen in the 3ds max user-interface. For example, if the superclass of the plug-in is geometry or light, this name would be displayed on the plug-in’s button in the Create panel; if the superclass of the plug-in is modifier, this name would be displayed on the plugin’s button in the Modify panel; and if the superclass of the plug-in is material or textureMap, this name would be displayed in the Material/Map Browser. The default name is the plug-in’s . 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.
1539
1540
Chapter 12
|
Creating MAXScript Tools
classID:#(,)
You supply the classID:#(,) parameter if you want the plug-in to be creatable and storable in the scene. This ID becomes the permanent ID for the class and is used by 3ds max to identify objects as they are saved and loaded in the scene. You don’t need to supply a class ID value if the plug-in is to be like a System object that only creates other types of objects in the scene. The class ID is basically a pair of numbers, chosen randomly so that (hopefully) they won’t conflict with another plug-in. MAXScript provides a method to generate a fresh random class ID each time you run it: genClassID()
This method generates a random class ID similar to #(0x9b7ea231, 0xb6db86ef), and prints it to Listener. You can just cut and paste this class ID into your script to use the generated ID. extends:<maxClass>
The extends:<maxClass> parameter is supplied if you want to base your plug-in on an existing plug-in. This basically lets you add a new class that works internally exactly like the one you are extending, but with an expanded or replaced user interface. The class you specify must have the same superclass as specified in the scripted plug-in header. Current limitations prevent certain plug-ins from being extended, in particular those with custom creation managers. These include target lights and cameras and all the System plug-ins. You can tell if a plug-in is not extendable if your new rollouts do not appear. When you create an object of scripted plug-in that extends another, MAXScript also creates an internal object of the extends: plug-in and passes most of 3ds max’s interaction with your plug-in onto the internal object. This is called delegation and the internal extends: plug-in object is the delegate. The delegate is visible in your plugin’s objects in Track View and you can access the delegate in your scripts to control it as needed. See the locals section below for more information. The delegate is not shown in TV if replaceUI:true is specified. replaceUI:
The replaceUI: parameter is used only when extends: is supplied to indicate whether the rollouts in your plug-in should add-to or replace the extended plug-ins rollouts. The default is false, which means your rollouts will be appended at the end of the extended plug-in’s. Another current limitation when extending plug-ins whose objects are created in the Create panel only allows user interface replacement in the Modifier panel; the original plug-in’s rollouts are always displayed along with the scripted rollouts in the Create panel. version:
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
invisible:
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:
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. 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
1541
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 of a scripted plug-in definition is made up of a sequence of plug-in clauses as follows:
::= { }+
Plug-in clauses define the components of a scripted plug-in and can be one of five basic things: •
Local variables, functions or structure definitions are variables, functions, and structures whose scope is the plug-in. These locals will exist as long as the instance of the plug-in exists. The visibility of locals, and accessing scripted plug-in locals from external code, are described in the Visibility of Locals, Functions, Structures, and User-Interface Items in Rollout Code (p. 1478) and Accessing Locals and Other Items in a Rollout from External Code (p. 1480) topics.
•
Parameter blocks define a set of parameters for the plug-in, which are like plug-in local variables, but are directly animatable and are saved to and restored from scene files. You can also associate each parameter with appropriate user-interface elements in one of the plug-ins rollouts. When associated in this way, the parameters are “wired” to their spinners and checkboxes, etc., and both update automatically as the other changes, so you don’t have to write any user-interface event handlers for them. These parameters correspond to the visible parameters you see in other 3ds max plug-ins.
•
Mouse tools are used to perform a set of actions based on mouse clicks in the 3ds max viewports, and are described in the Scripted Mouse Tools (p. 1531) topic.
•
Rollouts can be displayed for the scripted plug-in. For scripted plug-ins that extend an existing plug-in, these rollouts can be displayed in addition to or replace the existing plug-in’s rollouts. Rollout definitions are described in the Utility Clauses (p. 1466) topic.
•
Event handlers are special kinds of functions associated with particular events. Event handlers specify the processing you want to occur when a user creates an instance of the scripted plug-in or when 3ds max calls the scripted plug-in. These actions generate named events and the optional event handler you supply for that event is called when the action occurs.
Formally, the syntax of a is defined as follows:
::= <parameters> <event_handler>
| | | | | |
Scripted Plug-in Clauses
Locals: A , , and are exactly the same as local variable, function, and structure definitions in MAXScript: ::= local <decl> { , <decl> } <decl> ::= [ = <expr> ] -- optional initial value ::= [ mapped ](function | fn) { <argument> } = <expr> <member>
::= struct ( <member> { , <member> } ) ::= ( [ = <expr> ] | )
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.
1543
1544
Chapter 12
|
Creating MAXScript Tools
The version local variable contains the version number specified in the scripted plug-in definition. See the Updating Scripted Plug-ins (p. 1553) topic for more information on this variable. The this local variable always contains the MAXScript value corresponding to the current instance of the scripted plug-in. This variable provides a guaranteed way of accessing parameters on the new object within plug-in code (in case there are locals or globals with the same name), and it is a way of referencing the plug-in in case you want to store it to a variable. The delegate local variable contains the MAXScript value corresponding to the instance of the plug-in being extended. To access common properties or subAnim properties in the instance of the plug-in being extended, you need to do so via the delegate local variable. For example, delegate.width = thisWidth
inside a plug-in function or handler would set the .width property in the instance of the plug-in being extended. The delegate local variable in a scripted plug-in that creates a scene object does not contain the node itself, but a the BaseObject of that node. As such, you can not access the node level properties of the object being created. An exception to this is the node’s transform, which is exposed to the scripted plug-in through a local variable called nodeTM. This variable is described in the applicable scripted plug-in type topics. If the extends: parameter is not supplied for a plug-in, delegate returns undefined. As well as local variables, you can define local functions and local structures, just as you can with scripted utilities and rollouts. Parameters: You can define one or more parameter blocks in a scripted plug-in. A parameter block has the form: parameters [type:#class] [rollout:] ( { <param_defs> }+ { <event_handler> } )
A parameter block defines a set of parameters for the plug-in, which are like plug-in local variables, but are directly animatable and are saved to and restored from scene files. You can also associate each parameter with appropriate user-interface elements in one of the plug-ins rollouts. When associated in this way, the parameters are “wired” to their spinners and checkboxes, etc., and both update automatically as the other changes, so you don’t have to write any user-interface event handlers for them. These parameters correspond to the visible parameters you see in other 3ds max plug-ins. Parameters in the parameter block do not participate in 3ds max’s undo system, therefore changes to the parameter values are not undoable. The 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
a permanent name. So, if you have existing objects of your plug-in in other files, don’t go randomly changing parameter block names or they won’t be loadable. The optional type:#class specifies that the parameters in the parameter block are “class” parameters. This means that there is one copy of each parameter for the *all* the objects of this 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: specifies a rollout definition elsewhere in the plug-in body to use as the user-interface rollout for the parameter block’s parameters. A limitation of the internal parameter block mechanism requires that each parameter block be associated with a separate rollout and each rollout be associated with only one parameter block. This means that each rollout you want to have in the plug-ins user interface must have its own separate parameter block. The <param_defs> are definitions for each parameter in the parameter block. They have the form: type:
[tabSize:] [tabSizeVariable:] \ [default:] [animatable:] \ [subAnim:] [ui:]
The 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, don’t change or re-use parameter names if you have scene files with old version objects you want to get at. The type: 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
1545
1546
Chapter 12
|
Creating MAXScript Tools
or one of the following types which are arrays of the above base types: #floatTab #intTab #colorTab #point3Tab #boolTab #angleTab #percentTab #worldUnitsTab #stringTab #filenameTab #colorChannelTab #timeTab #radiobtnIndexTab #materialTab #texturemapTab #bitmapTab #nodeTab #maxObjectTab
#worldUnits and #worldUnitsTab specify that a parameter holds a world distance value, kept internally as a system units float. For example: parameters main rollout:params ( height type:#worldUnits ui:heightSpin )
Note that this doesn’t cause any spinner display to be automatically shown in current display units, you need to also specify type:#worldUnits on the associated rollout spinner definition. #node and #nodeTab are used to store references to nodes. The nodes stored in these parameters cannot create a circular dependency. If, for example, you were creating a scripted helper, and set the helper as a target or parent of a camera, you can not store the camera node in a #node or #nodeTab parameter. Likewise, if you created a scripted modifier or material, and store a node in a #node or #nodeTab parameter, you cannot apply the modifier or material to that node.
Scripted Plug-in Clauses
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: specifies a initial default value for the parameter. The expression has to be convertible by MAXScript to the base type of the parameter. The optional parameter animatable: 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: 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: is used to specify which user-interface element in the parameter block’s associated rollout is to be linked to this parameter. When so linked, the handling of user actions for these elements are automatic and they also update automatically to follow any changes to the parameter caused by animation, scripts, etc. For example, in the following, the parameter block named main is associated with the rollout named params. The parameters height and spread are then linked with the spinners named height and spread in that rollout:
1547
1548
Chapter 12
|
parameters ( key fill back height spread
Creating MAXScript Tools
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 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 change handlers for spinners and checkboxes, etc. in the rollout definition. A set
Scripted Plug-in Clauses
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 get <arg> do <expr>
A get handler can be supplied for any of the parameters in the block and it will be called whenever the parameter value is retrieved. This will occur when the user interface updates itself, a script accesses the parameter, a viewport is redraw, a render occurs. In all these cases, the animated value is retrieved one or more times. The get handler is called with a single argument which is the current value stored in the paramblock (or underlying controller if the parameter is animated). The currentTime variable is set to the time at which the value is being retrieved and not necessarily the current slider time, since you can ask a parameter for its value for any specified time. If you implement the get handler, you must return a value, and that value is returned as the value of the parameter to the value requester. If you don’t want to modify the value, but just monitor accesses, return the argument. You can also compute and return any value of the appropriate type. Tools: Plug-ins can define local mouse tools. Although you can have any number of local tools and start them as needed, you would typically supply a single tool with the reserved name create. This is taken to be the create tool for objects created in the Create panel and is invoked automatically when you create scripted plug-in objects. Tool definitions are described in the Scripted Mouse Tools (p. 1531) topic. Creatable scene scripted plug-ins (scripted plug-ins that are not invisible, temporary, or extend another plug-in) require a create tool. A create tool, if present on a non-temporary extending plug-in, will override the delegate’s create tool. The animate state is implicitly turned off while the create tool is executed. A local variable nodeTM is accessible within the create tool. This variable contains a Matrix3 values. This value is in the active grid coordinate system. This variable allows the create tool to set the transform of the node currently being created. Also, within the create tool you should use the gridX values rather than worldX values in all cases, since object-creation is managed in the active grid coordinate system. Rollouts: Plug-ins can define local rollouts. These have the same syntax as local rollouts in scripted utilities. Unlike utility local rollouts, these rollouts are automatically opened as appropriate for the plug-in type (in the command panel or Material Editor, etc.).
1549
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 open event handler to pick up these values. Rollout definitions are described in the Utility Clauses (p. 1466) topic. Event Handlers: As with mouse tools, scripted plug-ins respond to certain actions in 3ds max by implementing handler functions. All types of scripted plug-ins support the following event handlers. You can use these event handlers to perform any extra initialization needed, such as loading up plug-in local variables or initializing properties of the plug-in’s delegate. on create do <expr>
The create event handler that is called whenever an instance of a scripted plug-in is created in a scene file. The animate state is implicitly turned off while the create event handler expression is executed. on load do <expr>
The load event handler that is called whenever an instance of a scripted plug-in is loaded from a scene file. The animate state is implicitly turned off while the load event handler expression is executed. on update do <expr>
The update event handler that is called whenever an instance of a scripted plug-in is present in the scene file, and the definition of the scripted plug-in is changed (i.e., if you define a scripted plug-in, create an instance of the plug-in object in the scene, and then change and execute the script defining the scripted plug-in, the update event handler defined in the new definition of the scripted plug-in script is called for each instance of the plug-in object in the scene). See the Updating Scripted Plug-ins topic for more information. Specific classes of scripted plug-ins implement additional event handlers, and are described with description of the scripted plug-in type. Runtime errors in certain event handlers cause the plug-in to be disabled until it is re-defined. When disabled, none of the plug-in event handlers are called. For example, errors in the map event handler expression in SimpleMods and the buildMesh event handler expression in SimpleObject disable the plug-in, since they are called so frequently. You will need to correct any problems and re-evaluate the plug-in definition again to re-enable the plug-in event handlers.
See also Scripted Plug-ins (p. 1538)
Scripted Plug-in Methods
Scripted Plug-in Methods The addPluginRollouts() is used within scripted plug-in create tools, specifically for level 1 plug-ins that don’t create instances of themselves in the scene but might create other objects within their create tool. This method lets you install rollouts for a specified object in the Create panel, typically one of the objects being created in the create tool, so that its parameters can be adjusted directly during creation. The form is: addPluginRollouts
In the following example, a variation of the three light mouse tool example presented in the Mouse Tool Clauses (p. 1532) topic is set into permanent, editable classes. It defines two new classes. The helper class lightMaster is used as a master object for the light system. The light class threeLights is what you create to layout the initial system. It also creates a lightMaster and sets its parameters to point at the lights. The lightMaster rollout allows subsequent editing of the system in the Modifier panel, and storing the lights in a parameter block makes the setup persistent over scene saves and loads. Script: plugin helper lightMaster name:”Light Master” classID:#(12345,54321) extends:Dummy replaceUI:true invisible:true ( parameters main rollout:params ( key type:#node subAnim:true fill type:#node subAnim:true back type:#node subAnim:true height type:#worldUnits default:0 ui:height spread type:#worldUnits default:0 ui:spread angle type:#angle default:90 ui:angle --- check value of key since lights don’t exist at initial creation on height set val do if key != undefined then coordsys key.target ( key.pos.z = val back.pos.z = val * 1.5 fill.pos.z = val * 0.5 ) -on spread set val do if key != undefined then coordsys key.target ( -- compute normal vector pointing at key in the target’s XY plane -- (kuv) and reposition everything based on that and the current -- spread and angle values local kuv = normalize ([key.pos.x, key.pos.y, 0]) key.pos = [kuv.x * spread, kuv.y * spread, height] back.pos = [kuv.x * -spread, kuv.y * -spread, height * 1.5] -- position fill by placing it under the key and then rotating in -- about the target
1551
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
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.
1553
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
Scripted Geometry Plug-ins A scripted Geometry plug-in is declared by specifying the <superclass> as geometry. Scripted Geometry plug-ins require a create tool unless they are invisible, temporary, or extend another plug-in. If the plug-in extends another plug-in, and a create tool is specified, it will override the delegate’s create tool. Script: plugin geometry foo_plugin_def name:”FooBar” category:”Scripted Primitives” ( local boxes, clickAt tool create ( on mousePoint click do ( clickAt = worldPoint boxes = for i in 1 to 10 collect box pos:([i*20,0,0] + clickAt) #stop ) ) -rollout frab “Parameters” ( spinner frab “Frabulate” range:[-1000,1000,20] on frab changed val do for i in 1 to 10 do boxes[i].pos = [i*val,0,0] + clickAt ) )
This adds a new geometry category with one button to the Create panel. Pressing the FooBar button starts a mouse command mode that creates a row of 10 boxes where you click and adds a rollout to the command panel with one spinner that lets you adjust the separation of the boxes. This is very similar to a System object like the RingArray, except it lives in the Geometry tab. This is the simplest type of scripted of plug-in; it has no specific scene object and no storable parameters. In the tool handlers, you can set the delegate properties as needed. For example: Script: plugin geometry Cuboid name:”Cuboid” classID:#(0x133067, 0x54374) category:”Scripted Primitives” extends:Box ( fn fmax val1 val2 = if val1 > val2 then val1 else val2 tool create ( on mousePoint click do case click of ( 1: nodeTM.translation = gridPoint 2: #stop ) -on mouseMove click do if click == 2 then
1555
1556
Chapter 12
|
Creating MAXScript Tools
delegate.width = delegate.length = delegate.height = 2 * fmax (abs gridDist.x) (abs gridDist.y) ) )
See also Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)
Scripted SimpleObject Plug-ins A SimpleObject is a kind of geometry primitive object that is defined by a tri-mesh, such as box, sphere, cone, and so on. In other words, all the Standard and Extended primitives in 3ds max. In scripting a SimpleObject plug-in, you supply a handler for building this mesh and 3ds max automatically handles scene display, hit-testing, ray intersection, rendering, modifier applicability, etc. A scripted SimpleObject plug-in is declared by specifying the <superclass> as simpleObject. Scripted SimpleObject plug-ins require a create tool. A SimpleObject plug-in must not perform any scene related actions such as creating scene nodes or building modifier stacks. It should basically only be adjusting its parameters in the mouse tool handlers and constructing a mesh in the buildMesh handler. Attempting to create scene nodes or applying modifiers in a SimpleObject plug-in will cause all kinds off strange interactions with the in-progress scene node creation. A SimpleObject plug-in has a predefined local variable mesh. This variable contains the underlying mesh of the object being created. The mesh local variable is accessible in any of the plug-in’s handlers, but is typically only built in the buildMesh handler. You can either modify the existing TriMesh value in place, using the TriMesh methods, or construct a new TriMesh value and assign it to the mesh plug-in local variable. The TriMesh methods and properties are described in the Editable Mesh (p. 1041) topic. Script: plugin simpleObject tower_plugin_def name:”Tower” classID:#(145345,543211) category:”Scripted Primitives” ( parameters main rollout:params ( height type:#worldUnits ui:height default:0 width type:#worldUnits ui:width default:0 depth type:#worldUnits ui:depth default:0 ) -rollout params “Two Faces Parameters”
Scripted SimpleObject Plug-ins
(
spinner height “Height” type:#worldunits range:[-1000,1000,0] spinner width “Width” type:#worldunits range:[-1000,1000,0] spinner depth “Depth” type:#worldunits range:[-1000,1000,0]
) -on buildMesh do ( setMesh mesh \ verts:#([0,0,0],[width,0,0],[width,depth,0],[0,depth,0]) \ faces:#([3,2,1], [1,4,3]) extrudeFace mesh #(1,2) (height * 0.5) 40 dir:#common extrudeFace mesh #(1,2) (height * 0.5) 50 dir:#common ) -tool create ( on mousePoint click do case click of ( 1: nodeTM.translation = gridPoint 3: #stop ) on mouseMove click do case click of ( 2: (width = gridDist.x; depth = gridDist.y) 3: height = gridDist.z ) ) )
In this script a new primitive called Tower is defined. It constructs a (very) simple tower form; the first drag sets the base and the second drag sets the height. It contains three animatable rollout parameters, height, width and depth, that set the object’s basic bounds. The key components here are the create tool and the on buildMesh handler and they work together in a fairly simple way. The create tool sets the values of the parameters and the on buildMesh handler constructs a mesh based on those parameter values. The create tool can also access and set the position of the node that is being created to contain the new object through the Matrix3 value in the pre-defined mouse tool local variable nodeTM. In this case, the position portion of the node’s TM is set to the initial mouse down world position. The on mouseMove handler sets the width and depth during click 2 and the height during click 3. The on buildMesh handler constructs the desired mesh in the TriMesh value in the pre-defined plug-in local variable mesh. Typically, it does this by building the mesh from scratch each time the handler is called. In the example above, the mesh is initially set to a simple, two-face rectangular plane (via setMesh()) and then the 2 faces are extruded up and scaled-down twice to get the simple tower. The mesh plug-in local variable is accessible in any of the plug-in’s handlers, but is typically only built in the on buildMesh handler. You can either modify the existing TriMesh value in place using the TriMesh methods, or construct a new TriMesh value and assign it to the mesh plug-in local variable. The TriMesh created must be valid or a 3ds max crash may occur. All face, vertex, material ID, and texture vertex arrays allocated must be filled in the handler.
1557
1558
Chapter 12
|
Creating MAXScript Tools
There are three additional event handlers that may be implemented for a scripted SimpleObject: on OKtoDisplay do
If the OKtoDisplay event handler is implemented, 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
If the hasUVW event handler is implemented, 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 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 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. Here’s another example that creates a mesh by first building other temporary objects and using mesh booleans to build the final mesh: Script: plugin simpleObject squareTube name:”SquareTube” classID:#(63445,55332) category:”Scripted Primitives” ( local box1, box2 -parameters main rollout:params ( length type:#worldUnits ui:length default:1E-3 width type:#worldUnits ui:width default:1E-3 height type:#worldUnits ui:height default:1E-3 ) --
Scripted SimpleObject Plug-ins
rollout params “SquareTube” ( spinner height “Height” type:#worldUnits range:[1E-3,1E9,1E-3] spinner width “Width” type:#worldUnits range:[1E-3,1E9,1E-3] spinner length “Length” type:#worldUnits range:[-1E9,1E9,1E-3] ) -on buildMesh do ( if box1 == undefined then (box1 = createInstance box; box2 = createInstance box) box1.height = height; box2.height = height box1.width = width; box2.width = width * 2 box1.length = length; box2.length = length * 2 mesh = box2.mesh - box1.mesh ) -tool create ( on mousePoint click do case click of ( 1: nodeTM.translation = gridPoint 3: #stop ) on mouseMove click do case click of ( 2: (width = abs gridDist.x; length = abs gridDist.y) 3: height = gridDist.z ) ) )
In this example, the parameters and rollouts are handled in a similar manner to the first example, but the buildMesh handler generates the mesh in an indirect way. The final object is in the form of a rectangular pipe, a box with a box hole through the middle. Two plug-in locals (box1 and box2) are made to contain Box base objects whose size parameters are set according to the plug-in’s parameters, box2 is the outer box, box1 is the hole. The final mesh is made by boolean subtraction of box1 from box2. In this case, a separate new mesh is created and assigned to the mesh plug-in local variable, in contrast to the first example which modified the object’s original mesh directly. Either technique is OK. The createInstance() method is used to directly create the box base objects. This method creates the geometry associated with the specified object, but does not create a node. This method is used since SimpleObject plug-in must not perform any scene related actions such as creating scene nodes or building modifier stacks.
1559
1560
Chapter 12
|
Creating MAXScript Tools
See also Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)
Scripted Shape Plug-ins Scripted Shape plug-ins can only extend existing Shape plug-ins. A scripted Shape plug-in is declared by specifying the <superclass> as shape. If a create tool is specified, it will override the delegate’s create tool. Script: plugin shape Extended_Rect name:”Rectangle2” classID:#(0x133067, 0x54375) extends:rectangle version:1 category:”Splines” ( fn fmax val1 val2 = if val1 > val2 then val1 else val2 tool create ( local startPoint on mousePoint click do case click of ( 1: startPoint = nodeTM.translation = gridPoint 3: #stop ) -on mouseMove click do case click of ( 2: ( delegate.width= abs gridDist.x delegate.length= abs gridDist.y nodeTM.translation = startpoint + gridDist/2. ) 3: delegate.corner_radius = fmax 0 -gridDist.x ) ) )
See also Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)
Scripted Light Plug-ins
Scripted Light Plug-ins Scripted Light plug-ins can only extend existing Light plug-ins. A scripted Light plug-in is declared by specifying the <superclass> as light. If a create tool is specified, it will override the delegate’s create tool. Current limitations prevent certain plug-ins from being extended, in particular those with custom creation managers. These include target light plug-ins. You can tell if a plug-in is not extendable if your new rollouts do not appear. An example of a scripted Light plug-in is shown in the Three Lights example in the Scripted Plug-in Methods (p. 1551) topic.
See also Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)
Scripted Helper Plug-ins Scripted Helper plug-ins can only extend existing Helper plug-ins. A scripted Helper plug-in is declared by specifying the <superclass> as helper. If a create tool is specified, it will override the delegate’s create tool. An example of a scripted Helper plug-in is shown in the Three Lights example in the Scripted Plug-in Methods (p. 1551) topic.
See also Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)
1561
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
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 <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 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 value is 1-based, however the scripted plug-in is called with a 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
1563
1564
Chapter 12
|
Creating MAXScript Tools
SimpleMod modifier is applied to and the gizmo bounding box is displayed. This will be the case if the object is selected, the Modifier panel is active, and the SimpleMod modifier is selected in the object’s modifier stack. It is basically up to the object being modified to decide what index value to pass. For meshes, for example, it is the actual mesh vertex index. For patches, it is the control points first all in one sequence, followed by the in and out vectors for each control point in control point order. For splines, it is control point, in vector, out vector in control point sequence within the curve sequence. This ordering may change in future versions of 3ds max. Since the map handler can be called many times, even on simple objects, it is highly recommended that you minimize the number of values that are created in the map handler. This will reduce the need for garbage collection to be run. If you need several local variables in the map handler, it is recommended that you declare one or more Point2 or Point3 values in the scripted plug-in definition, and then store values to the component values of the Point2 or Point3 values. This will prevent new local variables from being allocated in the map handler. You should not try to access the object being modified from within the map handler as this will attempt to evaluate the scripted modifier again. This will result in an infinite loop and hang 3ds max. There are also three pre-defined plug-in locals you can access in the map handler, as follows: min max center extent
-----
the the the the
modifier modifier modifier modifier
context’s context’s context’s context’s
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 modifier’s context, either the whole object or group of objects if applied to a scene node selection, or sub-object selection if there is a sub-object selection modifier below it on the stack (such as a Mesh Select). You can also use some other built-in capabilities of SimpleMod to implement modifier limits as in Bend and Taper. To do this, implement handlers for the following (you must implement all if you implement any): on modLimitZMin do <expr> on modLimitZMax do <expr> on modLimitAxis do <expr>
If called, the on modLimitZMin and on modLimitZMax handler expressions must evaluate to float values corresponding to the minimum and maximum limits and the on modLimitAxis handler expression must return #x, #y or #z to specify the limit axis. The MAXScript global variable currentTime contains the time at which these values should be computed, although, normally, simple access to parameter values will yield the correct currentTime value automatically. The simplest way to implement these handlers is to maintain limit parameters and associated spinners and checkboxes, and simply pass these parameter values back.
Scripted Material Plug-ins
The Modify panel actually creates a fresh instance of every modifier when it is to be shown in the More... list or the buttons in the Modifiers rollout. This will cause the create handler to be called for a scripted SimpleMod plug-in. No special handling in the create handler is required for this case.
See also Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)
Scripted Material Plug-ins Scripted Material plug-ins can only extend existing Material plug-ins. A scriptable Material plug-in is declared by specifying the <superclass> as material. A scripted Material plug-in must have at least one rollout defined. In a scripted Material plug-in, Material and Map buttons that are associated with a parameter in a parameter block do not call the button’s picked event handler. Instead, you should link the button to a parameter in a parameter block, and use the set handler for the parameter. Script: -- this is a level 3 plug-in, the beginnings of a custom glass material. -- It extends Standard material and replaces its UI with a single -- rollout with 2 spinners and a color picker plugin material myGlass name:”Supa Glass” classID:#(695425,446581) extends:Standard replaceUI:true version:1 ( parameters main rollout:params ( trans type:#float default:27 ui:trans refrac type:#float default:1.5 ui:refrac col type:#color default:blue ui:col -on trans set val do delegate.opacity = val on refrac set val do delegate.ior = val on col set val do delegate.diffuse_color = val ) -rollout params “Glass Parameters” ( spinner trans “Transparency: “ fieldwidth:45 offset:[-90,0] spinner refrac “Index of Refraction: “ fieldwidth:45 offset:[-90,0] colorpicker col “Base color: “ align:#center ) -on create do
1565
1566
Chapter 12
(
|
Creating MAXScript Tools
-- setup initial material delegate.opacityFalloff = 75
) )
See also Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)
Scripted TextureMap Plug-ins Scripted TextureMap plug-ins can only extend existing TextureMap plug-ins. A scriptable TextureMap plug-in is declared by specifying the <superclass> as textureMap. A scripted TextureMap plug-in must have at least one rollout defined. In a scripted TextureMap plug-in, Material and Map buttons that are associated with a parameter in a parameter block do not call the button’s picked event handler. Instead, you should link the button to a parameter in a parameter block, and use the set handler for the parameter.
See also Updating Scripted Plug-ins (p. 1553) Scripted Plug-in Methods (p. 1551) Scripted Plug-in Clauses (p. 1542) Scripted Plug-ins (p. 1538) Scripted Mouse Tools (p. 1531)
Scripted RenderEffect Plug-ins A scriptable RenderEffect plug-in can be declared by specifying the <superclass> as RenderEffect and by declaring an apply event handler. When declared, the render effect can be seen in Render Effects > Add dialog. on apply 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
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 do <expr>
The preApply handler allows the scripted effect to analyze the incoming render bitmap and its channels in order to precondition the delegate’s effect processing. So, you might add an on channelsRequired do to add #node and #coverage channels to the renderer’s bitmap, and an on preApply bm do to get the #node channel out as a mask and then set it into a delegate’s mask parameter to limit an effect to a given object. You cannot call render() in a scriptable RenderEffect plug-in, as this would cause the RenderEffect to be recursively called. Here’s a simple example that extends the Blur effect to add another rollout that has a node picker button. If you pick a node it generates a channel mask and uses that to limit the blur to that object: Script: plugin RenderEffect myBlurFX name:”Super Blur FX” classID:#(6545,456581) extends:Blur version:1 ( local tx = bitmaptexture (), cm, g_channels = #(#node, #coverage) rollout params “SupaFX Parameters” ( label nn align:#center pickbutton nodepick “Pick Node” ) -parameters main rollout:params ( thenode type:#node ui:nodepick on thenode set nd do params.nn.text = if nd == undefined then ““ else nd.name
1567
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
(
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)
1569
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
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
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
modPanel.getCurrentObject()
Returns the modifier or base object currently selected in the Modify panel stack. If the Modify panel is not open, this function returns undefined. modPanel.getModifierIndex <node> <modifier>
Returns the index of the given modifier in the modifier stack for the given node. This index corresponds to the modifiers position in the <node>.modifiers array. This function returns undefined if the given modifier is not in the node’s modifier stack. modPanel.setCurrentObject < modifier | node | node_baseobject >
Sets the specified object in the current modifier stack to be the active object in the modifier stack. The Modify panel must be open on the object containing the modifier or base object to be selected, otherwise the function does nothing. Examples: modPanel.addModToSelection (bend()) 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
--------
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
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.
1573
1574
Chapter 13
|
Interacting with the 3ds max User Interface
Main Toolbar The following methods are associated with 3ds max’s main toolbar: enableUndo
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
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
Enables or disables the Coordinate System Center icon. getCoordCenter() setCoordCenter
Get and set the Coordinate System Center. Valid values are: #local -- Use Pivot Point Center #selection -- Use Selection Center #system -- Use Transform Coordinate Center
Modify Panel
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
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 values are: #move #rotate #nuscale #uscale #squash #select
-------
Move button on/off Rotate button on/off Scale button on/off – doesn’t change scale type Scale button on/off – doesn’t change scale type Scale button on/off – doesn’t change scale type Select button on/off
getToolbtnState
Returns whether the specified tool button is on or off as a value. Valid name values are: #select #move #rotate #uscale-- returns true if any of the scale button states is on #nuscale-- returns true if any of the scale button states is on #squash-- returns true if any of the scale button states is on
The following methods deal with the Named Selection Set drop-down list. These methods are not intended for casual usage. clearCurSelSet()
Clears the edit field of the Named Selection Set drop-down list. Does not deselect the currently selected objects. clearSubSelSets()
Clears the named selections from the Named Selection Set drop-down list. The named selection sets still exist, they just don’t show in the drop-down list. This command can be dangerous to use unless you are in Sub-Object mode in the Modify panel, as there is not a direct method to rebuild the Named Selection Set list. When in Sub-Object mode in the Modify panel, the namedSelSetListChanged() method will rebuild the list. namedSelSetListChanged()
When in Sub-Object mode in the Modify panel, this method will rebuild the named selection set list.
1575
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 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
toolmode.axisConstraints
Get/set the 3ds max axis constraints. The axis constraints values are: #X #Y #Z #XY #YZ #ZX
Status Bar The methods and 3ds max global variables associated with 3ds max’s Status Bar are described in the following topics: Prompt Line (p. 1577) Coordinate Display (p. 1578) Progress Bar Display (p. 1578) Status Bar Buttons (p. 1579)
Prompt Line The following methods are associated with 3ds max’s Status Bar Prompt Line: displayTempPrompt <string> <milliseconds_integer>
Displays the specified string on the Prompt Line for the specified number of milliseconds. After the time elapses, the string is popped from the stack. This may be used to put up a temporary error message for example. Control is returned to MAXScript immediately after the call, that is, MAXScript execution continues even while the temporary prompt is displayed. removeTempPrompt()
Removes the temporary prompt immediately. replacePrompt()
Replaces the string on the top of the prompt stack. pushPrompt <string>
Pushes the currently displayed prompt onto the prompt stack, and displays the specified string as the prompt. popPrompt()
Pops the currently displayed prompt off the prompt stack. The previous prompt will be restored.
1577
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 <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 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
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
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
Sets or clears the Cancel flag for the progress bar. By passing a value of true, the Cancel flag is set and will be detected by progressUpdate() and getProgressCancel(). By passing a value of false, the Cancel flag is cleared if set. The following 3ds max system global variable is associated with the Progress Bar display: escapeEnable
Lets you get and set a Boolean value defining whether ESC key interrupt detection is on or off. Setting enableEscape to false turns ESC key interrupt detection off, setting it to true turns it on again. This variable is useful when used in conjunction with a Progress Bar. You can set enableEscape to false when you don’t want the user to be able to interrupt a script running a long computation and you have set up a progress bar with its own Cancel button.
Status Bar Buttons The following methods are associated with the buttons in 3ds max’s Status Bar: getCrossing()
Returns whether Crossing Selection (true) or Window Selection (false) is set. getPluginKeysEnabled() setPluginKeysEnabled
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.
1579
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
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
Gets or sets the viewport layout, where 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 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
1581
1582
Chapter 13
|
Interacting with the 3ds max User Interface
The valid 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
Get and set the view type for the current viewport. Valid 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
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
Sets the active viewport to a Camera view, using the specified camera. getViewTM() viewport.getTM() viewport.setTM <matrix3>
Get or set the active view screen-to-world transform matrix for non-orthographic (perspective and isometric user views) viewports. This is the affine camera or viewport matrix. setTM only operates on Perspective viewports, and returns a value of true if the view transform matrix was successfully set, false otherwise. The following function returns as a Ray value the “eye” location and direction for the active viewport. The viewport needs to be a non-orthographic viewport. Script: fn getViewDirectionRay = ( -- The affine TM transforms from world coords to view coords -- so we need the inverse of this matrix local coordSysTM = Inverse(getViewTM()) -- The Z axis of this matrix is the view direction. local viewDir = -coordSysTM.row3 -- get the view position from this matrix local viewPt = coordSysTM.row4 return ray viewPt viewDir ) getViewFOV()
Returns the Field of View for the active viewport. If the viewport is an orthographic viewport, a value of 57.2958 degrees (1 radian) is returned. getViewSize()
Returns the active view size as point2 in pixels. getScreenScaleFactor <point3>
Returns the active view scale factor, giving the width in world-space units at the point’s distance from the view space origin. mapScreenToWorldRay
Returns a Ray value in world space through the given viewport pixel coordinates in the current active view, and perpendicular to the viewport plane.
1583
1584
Chapter 13
|
Interacting with the 3ds max User Interface
mapScreenToView <depth_float> \ [ ]
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 is supplied, the specified viewport size is used instead of the actual viewport size. mapScreenToCP [ ]
Maps viewport pixel coordinates in the current active view to the construction plane in world coordinates. If 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
Returns a point in world space on the current construction plane based on the specified screen coordinate. gw.getCPDisp \ <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 () and a direction vector (). 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
gw.snapPoint [ 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
This method snaps the length to the nearest snap increment and returns the snapped distance. units.formatValue
Returns a <string> value representing the 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 . 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.
1585
1586
Chapter 13
|
Interacting with the 3ds max User Interface
completeRedraw() forceCompleteRedraw [ doDisabled: ]
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
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
Get and set whether Animate Background is on (true), or off (false). getBkgImageAspect() setBkgImageAspect
Get and set the background image Aspect Ratio option. Valid values are: #view #bitmap #output
-- Match Viewport -- Match Bitmap -- Match Rendering Output
Viewport Grids
getBkgORType <start_end_integer> setBkgORType <start_end_integer>
Get and set the background image Start Processing and End Procession options. <start_end_integer> = 0 – Start Processing; 1 – End Processing Valid 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
Get and set the background image Start At frame. getBkgSyncFrame() setBkgSyncFrame
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.
1587
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
Sets the current system cursor to one of the standard 3ds max cursors. Valid 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 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 . 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
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 max’s viewports or type a 3D point into the Listener and the function returns that point as a MAXScript Point3 value in world-space coordinates. The function takes an optional prompt: string argument which it prints in the Listener as a prompt message. There is also an optional snap: keyword argument that controls viewport point picking if Snap is turned on in the 3ds max interface. If #3D is specified, the cursor snaps to points anywhere in 3D space, if #2D is specified (the default), the cursor only snaps on the current active grid construction plane. If Snap is off in the 3ds max interface, the clicked point is always taken to be on the current active grid construction plane. The user can either press the ESC key or click the right mouse button at any time to abort the point picking and the function immediately returns the special MAXScript value #escape if the escape key is pressed or #rightClick if the right mouse button is clicked. You can get the pickPoint() function to display a rubberbanding dashed line during point input by supplying the optional keyword argument rubberBand:<start_point3>. If you include this on a call to pickPoint(), it rubberbands a dashed line from the specified start point to follow the mouse. You would use it in a chain of point picks by specifying the last picked point as the rubberBand: start point for each successive pick. The start point given to rubberBand: should be in world coordinates. You can also set up a mouse move callback function for tracking free mouse moves during point input. The optional keyword argument for this is mouseMoveCallback: and it has two forms: mouseMoveCallback:fn mouseMoveCallback:#(fn, arg)
The second form allows you to supply an argument value that is sent to the callback function each time it is called. The fn you supply should take one argument in the first form above and two in the second. When the callback function is called, the first argument it gets is always the current world coordinates of the mouse and the second if given is the arg you supplied. You can use a callback function to implement a more sophisticated form of rubberbanding, for example by adjusting a spline’s vertex or a box’s height to follow the mouse. If you do this, make sure you call any needed update() mesh or spline functions.
1589
1590
Chapter 13
|
Interacting with the 3ds max User Interface
The pickPoint() function allows coordinates to be entered either by clicking in a 3ds max viewport or by typing numbers into the MAXScript Listener window. The user can enter coordinates in one of several forms (based on the command line input syntax for AutoCAD), as follows: x, y, z
explicit point in current construction plane coordinates x, y
point on the construction plane (cp) d
point d units away in mouse direction from last point @ x, y, z
relative, offset to last input point @ x, y
on cp, relative to last point’s projection on cp d < a
polar on cp, distance from cp origin at a angle from x-axis @ d < a
relative polar on cp, centered on last point d < a1 < a2
spherical on cp, d from cp origin at a1 from x and a2 angle from xy-plane @ d < a1 < a2
relative spherical There can be zero or more white space characters before and between numbers and metacharacters. Note that these typed-coordinates are always interpreted as relative to the current active grid construction plane and that coordinates returned by pickPoint() are always in world-space. Keyboard input by the user that is not in one of the expected coordinate input forms is returned as a String value so the author can handle the error gracefully or permit other kinds of input to be parsed by the script. You can test for these return conditions using the classOf() function, for example: p = pickPoint() case of ( (p == undefined): (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
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.
1591
1592
Chapter 13
|
Interacting with the 3ds max User Interface
Viewport Drawing Methods The methods documented in this topic provide low-level access to 3ds max’s graphics system. These methods are available for scripts to do any graphics work not possible using the standard high-level graphics methods. These methods are for use in the existing 3ds max viewports, and only work on the active viewport. Note that these methods typically are not for casual use, as they are not intended to be a high level graphics library. For example, many steps are required to display a single lit polygon. These methods are optimized for speed, and not at all for script programmer ease of use. The methods described in this topic actually operate on graphic windows. While graphic windows are not the same as viewports, they are related to one another. Each viewport has its own graphics window, and the contents of the viewport display can be thought of as a snapshot of the graphics window contents. Since writing to display memory a relatively slow operation, 3ds max writes instead to the graphics window, and then when all the writes have been finished, it redraws the viewports with the graphics window contents. Graphics Driver Configuration and Support Methods gw.getDriverString()
This method returns a string identifying the graphics driver (and includes manufacturer info if available) gw.querySupport
Determines if the driver supports the specified feature. The valid 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
#dualPlanes
If a driver has dual-planes support it returns true. The standard 3ds max OpenGL display driver only returns true for this if the underlying display driver has implemented a custom OpenGL extension that allows 3ds max to handle this efficiently. #swapModel
This returns true if 3ds max has to redraw the whole scene any time the viewports are exposed. #incrUpdate
This returns true if the driver can update a rectangular subset of the viewport without trashing the image outside that rectangle. This is true for most drivers that blit the viewport region and false for those that do page-flipping in the hardware. For OpenGL, this is true if the display driver implements the Microsoft glSwapRectHintWIN extension. #passDecal
This is true if the driver can handle decalling with only one pass. Currently, this is true for OpenGL, but false for HEIDI and D3D. #driverConfig
This is true if the driver has a configuration dialog. This is true for all three of 3ds max‘s standard drivers. #texturedBkg
This is true if the viewport background is implemented as a textured rectangle, and false if it is a blitted bitmap. #virtualVpts
This is true if the driver allows viewports to be made larger than the physical window they are attached to. Currently, this is only true for OpenGL. #paintDoesBlit
This is true if WM_PAINT messages result in a blit of the backbuffer (as opposed to a page-flipping swap). This allows 3ds max to do quick damage region repair, and works together with the #swapModel flag. #wireframeStrips
This is true if the driver wants 3ds max to send down wireframe models using triangle strips instead of a bundle of 2-point segments. This is only used by the OpenGL driver, and it is there as a user-choosable performance-accuracy tradeoff (since the strips are faster and are back-culled, but they display hidden edges as though they are visible).
1593
1594
Chapter 13
|
Interacting with the 3ds max User Interface
Window and Viewport Transformation Methods gw.isPerspectiveView()
Returns true if the view is in perspective projection; otherwise false (orthographic projection). gw.setTransform <matrix3>
Sets the active viewport’s graphics window transformation matrix to the specified matrix3 value, and updates the modeling coordinates to normalized projection coordinates matrix. This routine also back-transforms each light and the eye point so that lighting can be done in modeling coordinates. This method may be used to set a matrix that transforms the point passed to the drawing methods (like gw.text(), gw.marker(), gw.polyline() or gw.polygon()). Normally these methods expect world coordinates. However if this matrix is set to an object’s transformation matrix you can pass coordinates in the object’s space coordinates and they will be transformed into world space (and then put into screen space when they are drawn). If however this is set to the identity matrix, you would pass world space coordinates. You can set this matrix to the object’s transform matrix using the following code: gw.setTransform node.transform
For world-to-screen space conversions by the methods gw.text(), gw.marker(), gw.polyline() or gw.polygon(), etc, a developer must explicitly set this matrix to the identity matrix. This is because the graphics window may have a non-identity transform matrix already in place from a previous operation. gw.getFlipped()
Returns true if the determinant of the current transform is positive, false if negative. Position, Size, and Depth Clipping Methods gw.setPos <x_integer> <w_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
gw.getYonCoord()
This method returns the smallest device Z value. Note: this method does not return the proper Z depth value in 3ds max and VIZ R3. DIB (Device-Independent Bitmap) Methods gw.getViewportDib()
This method returns the active viewport’s graphics window image as a Bitmap value. The size of the bitmap is the same size as the viewport. Script: MacroScript GrabViewport category:”Tools” tooltip:”Grab Viewport” ( ----------------------------------------------------------------------GRABVIEWPORT MACROSCRIPT --Created:3/23/99 --Edited:4/28/99 --by Borislav Petrov [email protected] ----------------------------------------------------------------------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|”
1595
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 ( | #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
Sets the rendering limits used by primitive calls. Setting the rendering limits is used in communication between the various parts of 3ds max that handle the display of objects. For example, setting this limit to #polyEdges and then drawing a polygon won’t result in a polygon drawn with edges. It only sets a flag that indicates the edge should be drawn. What happens is as follows. Inside the upper level 3ds max, part of the code knows that polygon edges have been turned on. However this is not related through the object oriented architecture to the part of 3ds max that does the actual drawing. When 3ds max goes to draw objects it will see that the polygon edge flag is on. This tells it to do two drawing passes -- one to draw the polygon, then it calls outlinePass() call with true, draws a bunch of edges, then calls outlinePass() with false. Thus, the drawing routine is responsible for looking at the flags and drawing appropriately. This method is only responsible setting the limit which can later be checked. specifies the rendering limits used by the viewport as an array of values. The valid values are: #allEdges
All edges of the item are shown (including hidden ones). #boxMode
Objects are shown using their bounding box.
Viewport Drawing Methods
#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.
1597
1598
Chapter 13
|
Interacting with the 3ds max User Interface
#specular
This enables specular highlight display. #texture
This enables texture display. #twoSided
Faces are displayed regardless of their surface normal orientation. #vertTicks
This mode is really a pseudo-mode, in that it doesn’t actually cause the graphics drivers to do anything differently, but rather is tested by the Mesh class, which sends down vertex markers (+) if the mode is on. #wireframe
Wireframe rendering mode. #zBuffer
When coordinates are specified for drawing primitives they have x, y, and z values. Sometimes when drawing entities in the viewports it is desirable to ignore the z values. For example in the 3ds max viewports the text that display the type of viewport (Front, Left, and so on) are drawn without z values. So are the arc-rotate circle control and the axis tripods. These items are drawn without this flag being set so they always show up in front. gw.getRndLimits()
Retrieves the rendering limits used by primitive calls as an array of names. See gw.setRndLimits() for a list of the returned name values. gw.getRndMode()
Returns the current rendering mode used by the viewport as an array of names. This is a subset of the rendering limit, in that any limits imposed by the rendering limit are forced onto the current mode. See gw.setRndLimits() for a list of the returned name values. gw.setSkipCount <skip_count_integer>
Sets the number of triangles skipped when the viewport is set as a ‘Fast View Display’ viewport. To disable fastview, specify 1. Since triangles are handed down to graphics driver one at a time, it is up to the code that feeds triangles to the graphics driver to skip the specified number of triangles. The mesh rendering in 3ds max uses the skip count in this way. <skip_count_integer> specifies that every ‘n-th’ triangle should be drawn. If set to 2, every other triangle should be drawn. gw.getSkipCount()
Returns the current skip count setting.
Viewport Drawing Methods
The following is an example of using the above functions: -- Get the current rendering limits lim = gw.getRndLimits() -- Add another limit append lim #polyEdges -- Set the new rendering limits gw.setRndLimits lim -- Get back the rendering limits to check gw.getRndLimits() -- Get back the rendering mode to check gw.getRndMode()
Light and Camera Methods gw.getMaxLights()
Returns the maximum number of lights that may be used by the interactive renderer. Coordinate Transformation Methods The following methods map points from the graphic window’s current transform to device space. If the graphic window’s transform is set to the identity matrix then the mapping is done from points specified in world space. Otherwise the points given are transformed by the graphic window’s transform, and are then considered to be in world space. Thus, to get a world-space to screen-space conversion, you need to set the graphic window’s transform to the identity with: gw.setTransform(Matrix3 1) gw.hTransPoint <point3>
This method converts the point3 coordinate to a “h” format device coordinate. Each component of the return value is in integer format in the native device coordinates for the graphics driver. For HEIDI and OpenGL, the origin is at the lower left. For Direct3D the origin is at the upper left. gw.wTransPoint <point3>
This method converts the point3 coordinate to a “w” format device coordinate. Each component of the return value is in integer format with the origin at the upper left. gw.transPoint <point3>
This method converts the point3 coordinate to a “h” floating point coordinate. Each component of the return value is in float format with the origin at the upper left. This is just a helper routine to avoid building up round-off error. 3ds max uses it just for IK.
1599
1600
Chapter 13
|
Interacting with the 3ds max User Interface
Drawing Methods Methods that start with “h” take integer device coordinates with the origin at the lower-left. Methods that start with “w” in front take Windows device coordinates with the origin at the upper left. These “h” and “w” routines perform NO clipping unless otherwise noted. Drawing outside the allowable region is likely to cause 3ds max to crash. These coordinate systems are left-handed. Methods that don’t start with “h” or “w” map points from the graphic window’s current transform to device space. This coordinate system is right-handed. If the graphic window’s transform is set to the identity matrix then the mapping is done from points specified in world space. Otherwise the points given are transformed by the graphic window’s transform, and are then considered to be in world space. Thus, to get a world-space to screen-space conversion, you need to set the graphic window’s transform to the identity with: gw.setTransform(Matrix3 1)
After completing any drawing to the graphics window with the methods described in this section, you need to call gw.updateScreen() to update the viewport display. gw.updateScreen()
Updates the viewport display to display any text, markers, polylines, polygons, or tristrips written to the graphics window via the methods described below. gw.text <point3> <string> [ color: ] gw.hText <point3> <string> [ color: ] gw.wText <point3> <string> [ 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: ] gw.hMarker <point3> <marker_name> [ color: ] gw.wMarker <point3> <marker_name> [ 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
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 \ [ rgb: ] gw.hPolyline \ [ rgb: ] gw.wPolyline \ [ rgb: ]
This method draws a multi-segment polyline. Each value in is a vertex on the polyline. If 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 must be the same as in . gw.Polygon \ gw.hPolygon \ gw.wPolygon \
This method draws a multi-point polygon. Each value in is a vertex on the polygon. specifies the color at each vertex. The rendering mode (set via gw.setRndLimits()) must include #illum for the color values to be used. 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 \ gw.wTriStrip \
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
1601
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 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
Sets the RGB color used for the specified drawing type. The valid 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 [ useBkg: ]
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
Miscellaneous Viewport Methods and System Globals createPreview()
Creates a viewport preview using the current values in the Make Preview dialog. getVPortBGColor() setVPortBGColor()
Get and set the viewport background color as a Color value. isCPEdgeOnInView()
This method returns true if the construction plane is ‘head on’ in the current viewport. For example if the construction plane was XY and you were looking from the Front view, this method would return true. This is used for example during object creation because this process doesn’t work very well when the view is ‘head on’. axisTripodLocked()
This method returns true if the axis tripods are locked, that is, they won’t move when you move an object or sub-object, false otherwise. lockAxisTripods
If 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.
1603
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
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 values below. GetDefaultUIColor
Returns a Point3 value corresponding to the default color used for drawing the specified item type in the 3ds max user interface. Each component of the Point3 value is in a range of 0 to 1, corresponding to a color component value of 0 to 255. The values returned are not affected by the user’s color selections or those set by SetUIColor(). See the list of values below. SetUIColor <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 values below. The valid 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
Apparatuses Apparatuses Apparatuses Apparatuses
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
Miscellaneous Viewport Methods and System Globals
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
1605
1606
Chapter 13
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
|
Interacting with the 3ds max User Interface
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
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
saveMaterialLibrary
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 [ [ [ [ [ [
into: ] size:<point2> ] filename:<string> ] scale: ] filter: ] display: ]
\ \ \ \ \
provides access to the Render Map function available in the Material Editor. The function returns a Bitmap value containing a rendering of the given texture map. If you specify the optional into: argument, the function renders the map into the supplied bitmap, taking size and other attributes from the existing bitmap. If you don’t, a new bitmap value is created using the size: and fileName: arguments in its creation. If the into: and size: parameters are not specified, the default size in [200,200]. The scale: argument is a scale factor applied to 3D TextureMaps. This is the scale of the surface in 3d space that is mapped to UV and controls how much of the texture appears in the bitmap representation. If the filter: argument is true, the bitmap is filtered. It is quite a bit slower to rescale bitmaps with filtering on. Defaults to false. If the display: argument is true, the resulting bitmap is displayed using the virtual frame buffer; otherwise it is not. Defaults to false. Example: rm = renderMap $foo.material.diffuseMap size:[640,480] \ fileName:”foodif.bmp” save rm close rm
The above will render a map to a bitmap and save it as a .bmp file.
1607
1608
Chapter 13
|
Interacting with the 3ds max User Interface
showTextureMap <material>
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
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
Opens an existing Track View with the specified name, or creates a new Track View with specified name. Returns the value true. trackView.zoomSelected
Zoom the named Track View on the currently selected object. The World track must be expanded for this function to operate. The Object track will automatically be expanded if is closed. The hierarchy display is scrolled such that the selected object’s track is placed at the top of the window. If multiple objects are selected, the first object in the hierarchy that is selected will be placed at the top of the window. If there are no selected objects, no operation occurs. This method will return true, except when the named Track View does not exist or is not open, when it returns false. trackView.close
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
Returns the name of the indexed Track View as a String. Index values are 1-based. trackView.setFilter “name_string” {} [#noRedraw] trackView.clearFilter “name_string” {} [#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
1609
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
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
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.
1611
1612
Chapter 13
|
Interacting with the 3ds max User Interface
rendOutputFilename
Lets you get and set a String value that defines the output file name for the active renderer. It contains the corresponding value set in the Render Scene dialog. If this global variable is set to ““ then Save File check box in the Render Scene dialog is unchecked. skipRenderedFrames
Lets you get and set whether to skip rendered frames during a render. A Boolean Value – true if rendered frames are to be skipped, false if not. Note: The following globals should not be used if the Render Scene dialog is open. These globals do not update the dialog if it is open, and closing the dialog or rendering from the dialog will cause the displayed settings to be stored and used. rendTimeType -- integer
Get/set the type of time range to be rendered. One of the following values: 1 - A single frame. 2 - The active time segment. 3 - The user specified range. 4 - The user specified frame pickup string (for example “1,3,5-12”). rendStart -- time
Get/set the renderer’s start time setting. rendEnd -- time
Get/set the renderer’s end time setting. rendNThFrame -- integer
Get/set the renderer’s ‘n-th’ frame setting. Minimum value = 1 rendShowVFB -- boolean
Get/set the state of the renderer’s show virtual frame buffer flag. TRUE = on; FALSE = off rendSaveFile -- boolean
Get/set the state of the renderer’s save file flag. TRUE = on; FALSE = off rendUseDevice -- boolean
Get/set the state of the renderer’s use device flag. TRUE = on; FALSE = off rendUseNet -- boolean
Get/set the state of the renderer’s use net flag. TRUE = on; FALSE = off rendFieldRender -- boolean
Get/set the renderer’s field render flag. TRUE = on; FALSE = off rendColorCheck -- boolean
Get/set the renderer’s color check flag. TRUE = on; FALSE = off rendSuperBlack -- boolean
Get/set the renderer’s super black flag. TRUE = on; FALSE = off rendHidden -- boolean
Get/set the renderer’s render hidden objects flag. TRUE = on; FALSE = off rendForce2Side -- boolean
Get/set the renderer’s force two-sided flag. TRUE = on; FALSE = off
Miscellaneous Viewport Methods and System Globals
rendAtmosphere -- boolean
Get/set the renderer’s uses atmospheric effects flag. TRUE = on; FALSE = off rendDitherTrue -- boolean
Get/set the renderer’s dither true color flag. TRUE = on; FALSE = off rendDither256 -- boolean
Get/set the renderer’s dither 256 color flag. TRUE = on; FALSE = off rendMultiThread -- boolean
Get/set the renderer’s multi-threaded flag. TRUE = on; FALSE = off rendNThSerial -- boolean
Get/set the output file sequencing nth serial numbering setting. TRUE = on; FALSE = off rendVidCorrectMethod -- integer
Get/set the video color check method. One of the following values: 1 = FLAG 2 = SCALE_LUMA 3 = SCALE_SAT rendFieldOrder -- integer
Get/set the rendering field order. One of the following values: 1 is Even 2 is Odd rendNTSC_PAL -- integer
Get/set the video color check NTSC or PAL setting. One of the following values: 1 is NTSC 2 is PAL rendSuperBlackThresh -- integer
Get/set the super black threshold setting. Range 0 to 255. rendFileNumberBase -- integer
Get/set the File Number Base in the ‘Common Parameters’ rollup of the Render Scene dialog. rendPickupFrames -- string
Get/set the Frames string in the ‘Common Parameters’ rollup of the Render Scene dialog. The following 3ds max system global variables are applicable to the Renderer, but corresponds to the Gbuffer Layers Maximum Number parameter in the Rendering page of the Preference Settings dialog: preferences.maximumGBufferLayers
Lets you get and set an Integer value that specifies the maximum number of g-buffer layers generated during a render.
1613
1614
Chapter 13
|
Interacting with the 3ds max User Interface
The following 3ds max system global variables are specific to 3ds max’s default scanline A-Buffer renderer. These variables return undefined if the current renderer is not 3ds max’s default scanline A-Buffer renderer. scanlineRender.antiAliasFilter
Lets you get and set the anti-aliasing filter. For a list of all of the anti-aliasing filters you can say: showClass “*:filter*”
For example: scanlineRender.antiAliasFilter = quadratic()
The anti-aliasing filters and their parameters are described in the 3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters (p. 1614) topic. scanlineRender.antiAliasFilterSize
Contains a float value that defines the anti-aliasing filter size. scanlineRender.enablePixelSampler
Lets you enables and disables global super sampling. A Boolean value - true if Disable all Samplers is off, false if on. Note: Changing the render scene dialog settings via the scripter should be done with the actual render scene dialog in a closed state. Leaving the dialog open will make the attempted scripter modifications non-sticky.
3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters The following Filter class values are available as 3ds max Scanline A-Buffer renderer anti-aliasing filters. The renderer anti-aliasing filter is accessed using the following 3ds max system global variable: scanlineRender.antiAliasFilter
Lets you get and set the anti-aliasing filter. For a list of all of the anti-aliasing filters you can say: showClass “*:filter*”
For example: scanlineRender.antiAliasFilter = quadratic()
Constructors and Properties: Area: Area() Blackman: Blackman()
3ds max Scanline A-Buffer Renderer Anti-Aliasing Filters
Blendfilter: Blendfilter ... .Blend
Float
default: 0.3
Catmull_Rom: Catmull_Rom() Cook_Variable: Cook_Variable() Cubic: Cubic() 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
Opens an existing Schematic View with the specified name, or creates a new Schematic View with specified name. Returns the value true. schematicView.zoomSelected
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.
1615
1616
Chapter 13
|
Interacting with the 3ds max User Interface
schematicView.close
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
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
Get and set whether to jump to next position key when Key Mode Toggle is on. getKeyStepsRot() setKeyStepsRot
Get and set whether to jump to next rotation key when Key Mode Toggle is on. getKeyStepsScale() setKeyStepsScale
Get and set whether to jump to next scale key when Key Mode Toggle is on. getKeyStepsSelOnly() setKeyStepsSelOnly
Get and set whether to use Selected Objects Only when Key Mode Toggle is on. getKeyStepsUseTrans() setKeyStepsUseTrans
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
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 . 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
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: .name
: string
The name of the picked item as shown in the Track View Pick dialog. .anim
: subAnim
The subAnim for the item the user picked. .client
: MAXWrapper
The owner of the subAnim for the item the user picked. If the owner is a subclass of MAXWrapper, the MAXWrapper value for the owner is returned, otherwise a value of undefined is returned.
1617
1618
Chapter 13
|
Interacting with the 3ds max User Interface
.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: ]
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
The filter: function takes a MAXScript function of one argument that is called whenever the cursor is over an object in the scene and is passed that object under the cursor. It returns true if the object is eligible for picking, or false if not. Typically, the function would contain some object class testing, for example: fn shapeFilt o = superClassOf o == Shape
which you could use like this: pickObject prompt:”enter a shape” filter:shapeFilt
The optional keyword argument select: controls whether the picked objects become the new current selection in the 3ds max scene. If you supply true for that argument, the current selection is replaced with the objects that you pick. The default is false in which case the picker doesn’t affect the selection set.
Picking Scene Nodes by Name You can use the selectByName() function to open the standard 3ds max Select By Name dialog allowing users to pick objects which are then returned as an array of MAXScript node values. The form is: selectByName [ title:<string> ] [ buttonText:<string> ] [ filter:] [ showHidden: ] [ single:]
\ \
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: lets you specify a filter function that determines which objects should be displayed in the list. This is similar to the filter functions elsewhere in MAXScript. The function you supply should take one argument, which the current object being tested for inclusion and the function should return true for include, false for exclude. If you don’t specify a filter, all objects are displayed. For example, the following function limits the choices to shape objects: fn shape_filt obj = isKindOf obj Shape
showHidden: controls whether hidden and frozen objects are eligible for display. The default value is false. single: 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.
1619
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 [crossing:]
Returns an array of the nodes within the specified rectangular region. The 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 [crossing:]
Returns an array of the nodes within the specified circular region. The 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:]
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
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.
1621
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: ]
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: ]
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: ]
displays a modal message box similar to the one that the messageBox() function creates, except it contains a Yes, a No, and a Cancel button. The yesNoCancelBox() function returns #yes, #no or #cancel depending on which button the user clicked to dismiss the message box. Examples: messageBox “You shouldn’t have done that” if queryBox “Do you want to continue?” beep:false then ...
Notes: In some cases, MAXScript statements occurring after a statement containing one of the above dialog function calls may be executed before they are supposed to be. For example, if your execute: Script: for _t=0 to 3 do ( messagebox “Press Me” format “_t= %\n” _t ) print “Should print last”
Listener will show: Output: _t= 0 “Should print last” “Should print last” _t= 1 _t= 2 _t= 3
And the MessageBox will be displayed 4 times, once each time before the value of _t is printed to Listener.
Picking Scene Nodes By Region
The reason for this is that Listener is looking for expressions to compile and run in a background thread. In the above example there are 2 expressions – the for loop expression and the final print expression. The messageBox() function goes on waiting for and processing UI events in the main UI thread, but the compiler has already compiled ahead and scheduled the print “Should print last”. To prevent this out-of-order execution, you need to bracket the script in parenthesis. This will force the sequencing to be correct because the script would now contain a single expression rather than two.
Keyboard Entry The following are keyboard input functions for doing simple interactivity directly in the Listener or Mini Listener. All keyboard input functions take input from Mini Listener if Listener is closed, but if it is open, input will always be taken from Listener. getKBValue [ prompt:<string> ]
The getKBValue() function lets the user enter a MAXScript value into the Listener. The optional prompt: keyword argument takes a string that is displayed in the Listener as a prompt message. Any valid MAXScript expression can be entered into the Listener and is evaluated to become the result of the getKBValue() function. Expressions include the literals for integer, float, string, name, array, point2, point3, and scene object pathnames, or they can be expressions involving math operations and functions, script supplied functions, global variables, etc. You can test the type of value returned using MAXScript’s classOf function. Example: v = getKBValue prompt:”Enter object count:” if classOf v != integer then print “Value entered must be an integer”
The user can abort the entry by pressing the ESC key in which case the function returns the special value #escape. getKBLine [ prompt:<string> ] getKBChar [ prompt:<string> ]
These functions let the user type characters into the Listener that are returned as a MAXScript string. getKBLine() returns all the characters up until the user presses ENTER, getKBChar() returns each character immediately as it is entered. The user can abort the entry by pressing the ESC key in which case the function returns the special value #undefined. getKBPoint [ prompt:<string> ]
This function lets the user type in a 3D point in the syntax supported by the pickPoint() function. See the pickPoint() description above for details about the syntax. The function interprets the 3D point as relative to the current active grid construction plane and returns a Point3 in world-coordinates.
1623
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 \
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 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 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
3ds max System Directories The following methods allow you to access the 3ds max system directories: GetDir
Returns as a string the directory specified in the Customize > Configure Paths dialog for the specified file type. The valid 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
Returns the indexed Bitmap search path as a string. The index is 1-based. mapPaths.delete()
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
1625
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
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
Returns the indexed XRef search path as a string. The index is 1-based. xrefPaths.delete
Deletes the indexed XRef search path. The index is 1-based.
1627
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>
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>
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
fileProperties.getItems
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)
1629
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
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
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 ?
Command description Displays all max commands to listener
max accel pan
Activates viewport Pan mode
max acthomegrid max activate home grid
Makes home grid the active grid
max activate grid object
Makes selected grid the active grid
max adaptive persp grid max adaptive perspective grid toggle
Changes look of grid in non-orthographic viewports.
max align
Activates Align mode
max align normals max alignnormals
Activates Align Normals mode
max align camera
Places you in Align Camera mode
max angle snap toggle
Toggles Angle Snap toggle
max apply ik
Same as clicking Apply IK button in Hierarchy/IK panel
max array
Displays Array dialog
max backface max backface cull toggle
Toggles Backface Cull for selected objects
max background max background display toggle
Displays Viewport Background dialog
max bind space warp mode max bindwsm
Activates Bind to Space Warp mode
max box mode max box mode selected
Toggles Display as Box for selected objects
max box mode toggle max box toggle
Toggles active viewport’s shading mode to/from Bounding Box
max configure paths
Displays Configure Paths dialog
max create mode
Sets Create command mode active
max customize UI
Displays Customize User Interface dialog
max cycle select
Cycles through Selection Region types – Rectangular, Circular, Fence
max cycle sublevel max cycle subobject level
Cycles through sub-object levels. Must be in Modify panel with Sub-Object active.
max default lighting toggle max def lgt toggle
Toggles between default viewport lights and scene lights for viewport rendering
max delete
Deletes selected objects or sub-objects
max display floater
Displays Display Floater dialog
max display mode
Sets Display command mode active
1631
1632
Chapter 13
|
Interacting with the 3ds max User Interface
3ds max Command Name
Command description
max dolly max dolly mode
Activates Zoom/Dolly mode
max drawingaids max drawing aids
Displays Grid and Snap Setting dialog
max fetch
Activates Edit/Fetch – displays About to Fetch dialog
max file archive
Activates File/Archive – performs a scene file archive operation
max file export selected
Activates File/Export Selected – displays Select File to Export dialog
max file import
Activates File/Import – displays Select File to Import dialog
max file insert tracks
Activates File/Merge – displays Merge Animation dialog
max file merge
Activates File/Merge – displays Merge File dialog
max file new
Activates File/New
max file open
Activates File/Open – displays Open File dialog
max file preferences
Activates Customize/Preferences – displays Preference Settings dialog
max file replace
Activates File/Replace – displays Replace File dialog
max file save
Activates File/Save
max file saveas
Activates File/Save As – displays Save File As dialog
max file xref object
Activates File/XRef Objects - displays XRef Objects dialog
max file xref scene
Activates File/XRef Scenes - displays XRef Scenes dialog
max fov
Activates Region Zoom/FOV/Falloff mode
max freeze inv
Freezes non-selected objects. Same as clicking Freeze Unselected in Display panel.
max freeze selection
Freezes selected objects. Same as clicking Freeze Selected in Display panel.
max fullinteract
No operation
max grid nudge down
Nudges active grid down
max grid nudge up
Nudges active grid up
max grid toggle
Toggles display of active grid in active viewport
max grids align
Aligns active grid to active viewport
max group attach
Enters Attach Object to Group mode – user clicks on group to attach selected objects to the group
max group close
Closes active group
max group detach
Detaches selected objects from group
max group group
Groups selected objects – displays Group dialog
max group open
Opens selected group
max group ungroup
Ungroups objects in selected group
max help about
Activates Help/About – displays the About 3ds max dialog
max hide camera toggle
Toggles Camera in Hide by Category rollout in Display panel.
max hide command panel toggle
Toggles display of command panel
Picking Scene Nodes By Region
3ds max Command Name
Command description
max hide floating toolbars toggle
Toggles display of floating toolbars
max hide helper toggle
Toggles Helpers in Hide by Category rollout in Display panel.
max hide inv
Hides un-selected objects. Same as clicking Hide Unselected in Display panel.
max hide light toggle
Toggles Lights in Hide by Category rollout in Display panel.
max hide main toolbar toggle
No operation
max hide object toggle
Toggles Geometry in Hide by Category rollout in Display panel.
max hide tab panel toggle
Toggles display of Tab Panel
max hide selection
Hides selected objects. Same as clicking Hide Selected in Display panel.
max hide shape toggle
Toggles Shapes in Hide by Category rollout in Display panel.
max hide system toggle
Toggles Particle Systems in Hide by Category rollout in Display panel.
max hide wsm toggle
Toggles Space Warps in Hide by Category rollout in Display panel.
max hierarchy mode
Sets Hierarchy command mode active
max hold
Activates Edit/Hold
max ik terminator
Toggles Terminator in Hierarchy/IK, Object Parameters rollout
max ipan
Interactive Pan – places center of active viewport at current mouse location
max izoom in
Interactive Zoom In – zooms in active viewport at current mouse location
max izoom out
Interactive Zoom Out – zooms out active viewport at current mouse location
max key mode
Toggles Key Mode Toggle
max link
Activates Link mode
max load custom UI
Activates Customize/Load Custom UI – displays Load UI File dialog
max lock UI layout
Toggles locking of the UI layout
max material browser
Displays the Material/Map Browser dialog
max mirror
Activates Mirror mode – displays Mirror dialog
max modify mode
Sets Modify command mode active
max motion mode
Sets Motion command mode active
max move
Activates Select and Move mode
max mtledit
Activates Tools/Material Editor – displays Material Editor dialog
max next mod
Moves up one level in modifier stack
max override
Toggles Degradation Override. Executing this command works on the active window only, so if executed from Listener does nothing.
max pancamera
Activates Arc Rotate/Orbit mode
max panview
Activates Pan/Truck mode
max persp
Activates Zoom All/Perspective/Hotspot mode
max prev mod
Moves down one level in modifier stack
1633
1634
Chapter 13
|
Interacting with the 3ds max User Interface
3ds max Command Name
Command description
max preview
Activates Rendering/Make Preview – displays Make Preview dialog
max properties
Displays Object Properties dialog
max quick render
Performs Quick Render
max redo
Performs Redo operation
max renamepreview
Activates Rendering/Rename Preview – displays Save Preview As dialog
max render last
Performs Render Last
max render scene
Activate Render Scene – displays Render Scene dialog
max reset file
Activates File/Reset
max revert custom UI
Activates Customize/Revert to Startup UI – displays confirmation dialog
max rns
Activates Edit/Edit Named Selections – displays Edit Named Selection dialog
max roll
Activates Roll mode – active viewport must camera or light viewport
max rotate
Activates Select and Rotate mode
max rotateview
Activates Arc Rotate/Orbit mode
max save custom UI as
Activates Customize/Save Custom UI As - displays Save UI File as dialog
max safeframe toggle
Toggles viewport Show Safe Frames
max saveplus
Activates File/Save As in incremental file naming mode
max scale
Activates Select and Scale mode
max scale cycle
Cycles through Scale modes – Scale, Non-Uniform Scale, Squash
max select
Activates Select mode
max select all
Activates Edit/Select All – selects all objects
max select by color
Activates Edit/Select by Color – user then picks object, all objects with same wireframe color selected
max select child
Selects all 1st level children of currently selected objects
max select invert
Activates Edit/Select Invert
max select none
Activates Edit/Select None
max select parent
Selects parents of currently selected objects
max selection floater
Displays Selection Floater dialog
max shade selected
Toggles Views/Shade Selected
max show last img
Displays last rendered image
max showaxisicon
Toggles Views/Show Transform Gizmo
max showhomegrid
Toggles display of home grid
max snap toggle
Toggles Snap Toggle
max spacebar
Toggles Lock Selection Set. Executing this command works on the active window only, so if executed from Listener does nothing.
max spacing tool
Displays Spacing Tool dialog
max spinsnap toggle
Toggles Spinner Snap Toggle
max subobject sel
Toggles Sub-Object button in Modify panel
Picking Scene Nodes By Region
3ds max Command Name max swap layouts
Command description No operation – no A/B layout any more
max texture correct
Toggles viewport Texture Correction
max time back
Sets time slider to previous frame or keyframe (Previous Frame/Previous Key)
max time config
Displays Time Configuration dialog
max time end
Sets time slider to end frame (Go to End)
max time forward
Sets time slider to next frame or keyframe (Next Frame/Next Key)
max time play
Plays animation
max time start
Sets time slider to start frame (Go to Start)
max toggle key mode
No operation
max toggle keyboard shortcuts
Toggles Plug-in Keyboard Shortcut Toggle
max toggle ik
Toggles IK Toggle
max toggle sound
Toggles Active in Audio group of Sound Options dialog
max tool animmode
Taggles Animate button
max tool center
Cycles through transform centers – Pivot Point, Selection, Transform
max tool dualplanes
Toggles state of Use Dual Planes in Preference Settings dialog, Viewports tab.
max tool hlist
Activates Select by Name – displays Select Objects dialog
max tool maximize
Maximizes/Minimizes active viewport
max tool x
Activates Restrict to X
max tool xy
Activates Restrict to XY
max tool y
Activates Restrict to Y
max tool z
Activates Restrict to Z
max tool zoom
Activates Zoom/Dolly mode
max tool zoomall
Activates Zoom All
max tool zoomextents
Activates Zoom Extents
max tool zoomextents all
Activates Zoom Extents All
max tool zoomregion
Activates Zoom Region/FOV/Falloff mode
max trajectories
Toggles trajectory display for selected objects
max treeview
Activates Track View/Open Track View – displays Track View dialog
max truck
Activates Pan/Truck mode
max tti
Activates Tools/Transform Type-In – display Transform Type-In dialog
max undo
Performs undo operation
max unfreeze all
Unfreezes all objects. Same as clicking Unfreeze All in Display panel.
max unfreeze by hit
Activates Unfreeze by Hit mode. Same as clicking Unfreeze by Hit in Display panel.
max unfreeze by name
Displays Unfreeze Objects dialog. Same as clicking Unfreeze by Name in Display panel.
1635
1636
Chapter 13
|
Interacting with the 3ds max User Interface
3ds max Command Name
Command description
max unhide all
Unhides all objects. Same as clicking Unhide All in Display panel.
max unhide by name
Displays Unhide Objects dialog. Same as clicking Unhide by Name in Display panel.
max unitsetup
Activates Customize/Units Setup – displays Units Setup dialog
max unlink
Unlinks selected objects from their parents
max utility mode
Sets Utility command mode active
max videopost
Activates Rendering/Video Post – displays Video Post dialog
max view file
Activates File/View File – displays View File dialog
max view redo
Performs viewport redo operation
max viewpreview
Activates Rendering/View Preview – displays last preview
max views redraw
Redraws all viewports
max views undo
Performs viewport undo operation
max vpt back
Sets active viewport to Back
max vpt bottom
Sets active viewport to Bottom
max vpt camera
Sets active viewport to Camera. If only 1 camera in scene, or a camera is selected, that camera will be used for the viewport. If there is more than one camera, and no cameras are selected, the Select Camera dialog will be displayed. If there is no camera in the scene, a No Camera in Scene warning is displayed.
max vpt disable
Toggles Disabled state of active viewport
max vpt front
Sets active viewport to Front
max vpt grid
Sets active viewport to Grid
max vpt iso user
Sets active viewport to User
max vpt left
Sets active viewport to Left
max vpt persp user
Sets active viewport to Perspective
max vpt right
Sets active viewport to Right
max vpt shape
Sets active viewport to Shape
max vpt spot
Sets active viewport to Spotlight. If only 1 spotlight/directional light in scene, or a spotlight/directional light is selected, that light will be used for the viewport. If there is more than one spotlight/directional light, and no lights are selected, the Select Light dialog will be displayed. If there is no spotlight/directional light in the scene, a No Light in Scene warning is displayed.
max vpt tab
Cycles between Restrict to axes – X, Y, Z, XY
max vpt top
Sets active viewport to Top
max vpt track
Sets active viewport to Track View
max vptconfig
Activates Customize/Viewport Configuration - displays Viewport Configuration dialog
max wire facet
Sets active viewport shading mode to Facets + Highlights
max wire smooth
Sets active viewport shading mode to Wireframe
Picking Scene Nodes By Region
3ds max Command Name max zoom in 2x
Command description Zooms in active viewport by 2x
max zoom in 2x all
Zooms in all viewports by 2x
max zoom out 2x
Zooms out active viewport by 2x
max zoom out 2x all
Zooms out all viewports by 2x
max zoomext sel
Activates Zoom Extends Selected
max zoomext sel all
Activates Zoom Extends All Selected
1637
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
Returns true if the file was found and loaded successfully. mergeMAXFile [ ] [ #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:
An optional array of names or strings identifying the objects in the source scene file to be merged; all objects are merged if not specified. #prompt
If specified causes the standard merge dialog to be opened. #select
If specified causes the newly merged objects to be selected when merged. #noRedraw
If specified causes the screen redraw to be delayed in case you want to call mergeMAXFile several times and delay the redraw until after the last file merge. #deleteOldDups
Deletes existing scene objects with the same names as incoming objects, equivalent to a replace. #mergeDups
Ignore name conflicts, merge anyway resulting in possibly duplicated names.
1640
Chapter 14
|
File Access
#promptDups
Throw up the duplicates resolution dialog for the user to choose. Returns true if the file was found and loaded successfully. If you don’t specify a full path name, the file is looked for in the 3ds max scene directory, then in the 3ds max executable directory, and then in the PATH environment directories. getMAXSaveFileName filename: <seed_filename_string>
Displays standard 3ds max file save dialog, returns file name or value ‘undefined’ if canceled. getMAXOpenFileName filename: <seed_filename_string> dir:<seed_directory_string>
Displays standard 3ds max file open dialog, returns file name or value ‘undefined’ if canceled. getMAXFileObjectNames <max_filename_string>
Returns an array of names, one for each of the names of the objects in the given 3ds max file. This provides a way to get a preview list of the objects in another scene file (by name) to set up user selection of the objects to be merged under script control using the mergeMAXFile() function, for example. Example: p=[1000,1000,1000] for i = 1 to 5 do box pos:(random p -p) -- create some boxes savemaxfile “mergetest.max” -- save to file for obj in objects do obj.name = “_”+obj.name -- rename the boxes objects.pos += [0,-1000,0] -- move them off to the side fobj_names = getmaxfileobjectnames “mergetest.max” -- get the object names from the file deleteitem fobj_names 3 -- delete the third name from the array mergemaxfile “mergetest.max” fobj_names #select -- merge in the objects and select them selection.count -- should be 4 objects.count -- should be 9 saveMaxFile
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 [ #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
exportFile [ #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>
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> ] [ <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 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.
1641
1642
Chapter 14
|
File Access
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 as its second argument by the enumerator. This is useful if you have a general purpose enumerator function that can be conditioned by the argument you pass in on a particular enumeration, or if you want to pass in an array that the found names should be appended to. #inactive
Include the inactive files. #videoPost
Include the files used in video post. #render
Include the files used during rendering. #missing
include files that are missing in the file system If you don’t specify any of the above filter flags, all the files are enumerated. #localOnly
use in conjunction with the <maxwrapper_obj> argument. If specified, limits the enumeration to those files used directly in the object, if not then any referenced objects are scanned. For example: function get_names name a = append a name files = #() enumerateFiles get_names files #missing
Example: The following script will print out a sorted list of all the bitmap files used in the current scene file: Script: ( local mapfiles=#() fn addmap mapfile = ( local mapfileN=mapfile as name local index=finditem mapfiles mapfileN if index == 0 do append mapfiles mapfileN ) enumeratefiles addmap sort mapfiles for mapfile in mapfiles do print (mapfile as string) )
XRef Files
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: ] \ [ filename:<seed_filename_string> ] \ [ types:<description1>|<pattern1>|<description2>|<pattern2>|...| ] getSaveFileName [ caption:] \ [ 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>|...|”
1643
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
Returns the file name and extension of a full file name, useful for labeling file buttons in rollout panels. getFilenamePath
Returns the directory path part of a full file name. getFilenameFile
Returns the file name part of a full file name. getFilenameType
Returns the type extension part of a full file name. doesFileExist
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
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
Creates a new directory with the given name. Returns true on success, false on failure. deleteFile
Deletes the named file. Fails if the file is open in MAXScript. Returns true on success, false on failure. renameFile
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>
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.
1645
1646
Chapter 14
|
File Access
getFileAttribute setFileAttribute
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 values are: #readOnly #hidden #system #directory #archive #temporary #normal getFileModDate
Returns a String value containing the modification date for the specified file, for example “1/29/99 1:52:05 PM”. getFileCreateDate
Returns a String value containing the creation date for the specified file. getFileVersion
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
Encrypted Files encryptFile
Creates an encrypted copy of the file named by using the integer supplied as a key, naming the encrypted file . openEncryptedFile
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, here’s some code that creates an encrypted lock ID file in some authorization process: f = createFile “lock.tmp” format “%” hardwareLockID to:f close f encryptFile “lock.tmp” “lock.dat” 5476557 deleteFile “lock.tmp”
The following code can be used to read and check the lock ID (obviously, all this is only safe if the creation and checking scripts are themselves encrypted): f = openEncryptedFile “lock.dat” 5476557 id = readValue f close f if id != hardwareLockID then ( message “Lock ID’s don’t match” return 0 )
Accessing INI File Keys The following methods allow you to read and write key values in .INI files. getINISetting <section_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 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.
1647
1648
Chapter 14
|
File Access
setINISetting <section_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 is located. The 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
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
Saves current CUI configuration data to the specified file. The specified file is made the current CUI file. cui.loadConfig
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 change[s] [ id: ] \ [ handleAt:#redrawViews|#timeChange ] \ [ ] do <expr> when deleted [ id: ] \ [ handleAt:#redrawView|#timeChange ] \ [ ] do <expr> \
In the first form, the 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 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
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 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.
1651
1652
Chapter 15
|
Change Handlers and Callbacks
parameters
signaled when any parameters are changed in the object. This is something of a catch all, because the core signals this event in many situations. subAnimStructure
signaled when the dynamic subAnim structure changes, such as when a new vertex becomes animated in an editable mesh, or when a new controller is added to a list controller. Also called when subAnims are reassigned, for example, when a material is changed in an object. controller
signaled when a new controller is assigned to one of the object’s tracks. children
signaled when an object has immediate children added or removed. You can use the following two methods for deleting change handlers: deleteChangeHandler
deletes specified change handler. change_handler is the value returned by a when construct. deleteAllChangeHandlers [ id: ]
If optional id: parameter is not specified, deletes all change handlers. If optional id: parameter is specified, deletes all change handlers with the specified id. For example: deleteAllChangeHandlers id:#foo
For efficiency reasons, you don’t want irrelevant change handlers running in the background, so it is essential that you delete those that you no longer need. Special Considerations •
If a runtime error occurs in the body of a change handler while it is being executed, an error message is displayed and that handler is permanently disabled.
•
If all of the objects being tracked by a change handler are deleted, the change handler is also deleted.
•
The do <expr> change handler code is executed in a special context and not in the context of the code that created it. This means that the <expr> code cannot contain references to local variables in outer code nestings surrounding the when, since those variables are on an execution stack that does not exist at the time the when handler is called. The compiler detects any illegal references to outer locals and generates a compiler message. An important exception to this is utility and rollout panel locals, such as local functions, rollout variables and nested rollouts. You can refer to them in change handler code inside rollout code as they are associated directly with their rollout or utility object.
•
Change handlers are called only for user initiated events, and not for changes resulting from a change in controller values. For example, a change handler on the transform attribute of a node would be called when the user moves the node. If the position of the node is animated, and you play back the animation, the transform attribute change handler is not called.
Change Handlers and When Constructs
•
If you assign a change handler to an attribute on multiple objects, the change hander is called once per object if that object’s attribute changes. For example, if you say: when select $ changes obj do update_modifier_list obj
function update_modifier_list is called whenever any object is selected or deselected. This is true even if you do an Edit/Select All. In this case, update_modifier_list will be called once for each object currently selected (as the objects are deselected), and then once for all objects in the scene (as the objects are selected). If update_modifier_list is at all processor-intensive, a significant system slowdown can occur. •
Change handlers are only applied to object already present in the scene. Change handlers are not automatically applied to newly created objects.
•
If you have multiple change handlers defined, the order in which the change handlers are called is somewhat arbitrary.
•
Due to the way that 3ds max internally processes notification signals, the $ form of accessing selected objects is not recommended in a select change handler. To access the selected objects, you should use the selection objectset. This is because $ relies on information that has not yet been set in the selection processing whereas selection uses a different method of accessing selections and the information it uses has been set up.
Caution: The change handler system is based on 3ds max’s internal notification system which essentially drives all animation and interactivity within 3ds max. There are cases when the core sends many, many signals for the same change, so setting up change handlers on many objects that do vast amounts of computing can significantly slow down the system. Strictly speaking, change handlers are supposed to be used to just set “dirty flags” in a lightweight, order-independent way, and then use Redraw Views or Time Change callbacks to actually cause the triggered processing. You should attempt to use change handlers judiciously, and not, for example, as a simple way to get scripted controllers. If you do find that a desired setup is being flooded with unnecessary signals, you should use the handleAt: to delay the actual processing of the event handler script until a redrawViews or timeChange event occurs.
1653
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 unRegisterTimeCallback
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
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 unRegisterRedrawViewsCallback
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.
1655
1656
Chapter 15
|
Change Handlers and Callbacks
General Event Callback Mechanism MAXScript allows you to register callback scripts for all of the notification events supported by 3ds max, such as pre/post scene file open, new, reset, scene file save, pre/post render, selection change, etc. You can specify any number of callback scripts per notification event. Callback scripts can be bundled into ID’d sets, and can be deleted individually or all callback scripts in and ID’d set can be deleted. Callback scripts can be specified as persistent so that they are saved and loaded with the currently open file. The callbacks are maintained by the following set of functions: callbacks.addScript \ ( <script_string> | <script_stringstream> | \ fileName: ) \ [ id: ] [ persistent: ]
This method is used to register a new callback script. Requires as the first argument a name that specifies which type of notify event this script is associated with. The list of valid callback_type_name values is listed below. The script is supplied either as a direct String or StringStream value containing the text of the script to run, or as a fileName: keyword argument, in which case the named file is loaded and run whenever the event notification callback occurs. You can specify either a direct string or a fileName:, but not both. The optional id: parameter lets you tag one or a group of callbacks with a unique name so that you can remove them all as a group without interfering with other callbacks, perhaps registered by other scripted tools. The optional persistent: parameter lets you control whether the script is saved permanently in the currently open scene file or is a global callback script that remains in place no matter what file opening and closing is performed. A true value for the parameter specifies that the script should be stored in the current file and loaded and registered for callback whenever that file is opened again. Persistent callback scripts are always removed when a new file is loaded or a reset is performed so that persistent scripts in one file don’t accidentally get copied to a later file. The default for this parameter is false, indicating the script is a global script and is not persistent. For example: callbacks.addScript #preRender “setUpRenderGeom()” \ id:#jbwRender
registers a new callback script that will be called just before a render is performed. The script invokes a function (that has presumably already been set up). An unique ID has been assigned to the script for later selective removal. callbacks.removeScripts [ ] [ id: ]
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: 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
callbacks.show ()
This method lists out the current callback scripts in the Listener window. callbacks.broadcastCallback
This method provides a way for you to simulate one of the events and have all the callback scripts for it executed. Within 3ds max, the #preRenderFrame and #preRenderFrame callbacks can only be called by the renderer. These callbacks can not be called by using this method. The following is a list of valid callback event type names: #unitsChange
Sent if the user changes the unit setting. #timeunitsChange
Sent if the user changes the time format setting. #viewportChange
Sent if the user changes the viewport layout. #spacemodeChange
Sent if the user changes the reference coordinate system. #modPanelSelChanged
Sent whenever the Modify panel opens on a new selection, either because the Modify panel was just selected or because a new selection is made in the scene. The notify occurs at a point just prior to panel redraw but after the selection has been established, so that callback functions can modify the panel state without it being overwritten.
System Notifications #systemPreReset
Sent before 3ds max is reset. #systemPostReset
Sent after 3ds max is reset. #postSystemStartup
Sent when the software goes live. #pluginLoaded
Sent whenever a plug-in is loaded. #systemPreNew
Sent just before 3ds max is reset. #systemPostNew
Sent just after 3ds max is reset. #preSystemShutdown
Sent just before the software enters the shutdown process. #postSystemShutdown
Sent just before the software finishes the shutdown process. #colorChanged
Sent when the system is updating it’s custom colors.
1657
1658
Chapter 15
|
Change Handlers and Callbacks
File Notifications #filePreOpen
Sent before a new file is opened. #filePostOpen
Sent after a new file is opened successfully. #filePreMerge
Sent before a file is merged. #filePostMerge
Sent after a file is merged successfully. #filePreSave
Sent before a file is saved. #filePostSave
Sent after a file is saved.
Renderer Notifications #preRender
Sent before rendering is started. This notification is sent out before the renderer creates the render instance objects, which means that you can create nodes and other objects as a response to this event. When rendering multiple frames, this event is sent only once at the beginning of the rendering phase, and not on a per-frame basis. In the #preRender callback, you can’t change any of the render parameters (height, width, aliasing, etc) and effect the current render sessions. Those parameters have already been set up internally in 3ds max, and so changes to them won’t occur until the next render session occurs. #postRender
Sent after rendering has finished. This notification is sent out after the renderer destroys the render instance objects, which means that you can create nodes and other objects as a response to this event. When rendering multiple frames, this event is sent only once at the end of the rendering phase, and not on a per-frame basis. #preRenderEval
Sent just before the renderer starts evaluating objects. #preRenderFrame
Sent just before each frame is rendered by the renderer. This notification is sent out after the renderer has taken a snapshot of the scene geometry. At the time of this call the scene cannot be modified. The renderer has already called GetRenderMesh() on all the object instances, and the materials and lights are already updated. If you don’t modify anything that is rendered, then it is okay to use this callback. The current frame being rendered is set into the MAXScript currentTime context and system global, so any references to other scene object properties will automatically be resolved at the currently rendering frame’s time. This notification is not sent out when the renderer is called to update the Material Editor sample spheres, only during output rendering.
General Event Callback Mechanism
#postRenderFrame
Sent just after each frame is rendered by the renderer. The current frame being rendered is set into the MAXScript currentTime context and system global, so any references to other scene object properties will automatically be resolved at the currently rendering frame’s time. This notification is not sent out when the renderer is called to update the Material Editor sample spheres, only during output rendering. #renderParamsChanged
Sent whenever the common renderer parameters have changed.
Import/Export Notifications #preImport
Sent before a file is imported. #postImport
Sent after a file is imported successfully. #importFailed
Sent if import fails. #preExport
Sent before a file is exported. #postExport
Sent after a file is exported successfully. #exportFailed
Sent if export fails.
Node Related Notifications #nodeCreated
Sent when a node is created. #nodeRenamed
Sent if a scene node is renamed. #nodeHide
Sent when a node is hidden. #nodeUnhide
Sent when a node is unhidden. #nodeFreeze
Sent when a node is frozen. #nodeUnfreeze
Sent when a node is unfrozen. #nodeLinked
Sent when a new parent-child link is made. #nodeUnlinked
Sent when a parent-child link is broken.
1659
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
#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.
1661
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 [ #selOnly ]
This method provides functionality similar to that of Rescale World Utility plug-in in 3ds max. 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
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
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: ]
Defaults to active viewport. [ frame: | #current ]
Defaults to #current. [ [ [ [
framerange: | #active ] fromframe: ] toframe: ] nthframe: ]
Defaults to unsupplied, and the frame value controls which frames to render. [ outputwidth: ]
Defaults to current render width.
Controlling the Renderer
[ outputheight: ]
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: ]
Defaults to 1.0. [ renderhiddenobjects: ]
Defaults to current renderer Render Hidden Objects state. [ superblack: ]
Defaults to current renderer Superblack state. [ force2sided: ]
Defaults to current renderer Force 2 Sided state. [ renderatmosphericeffects: ]
Defaults to current renderer Render Atmospheric Effects state. [ renderfields: ]
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: ]
Defaults to current renderer Show VFB state. [ netrender: ]
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: ]
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.
1665
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: ]
Defaults to current renderer Aperture Width value. [ ditherTrueColor: ]
Defaults to current rendering preferences Dither True Color state. [ ditherPaletted: ]
Defaults to current rendering preferences Dither Paletted state. [ videocolorcheck: ]
Defaults to current renderer Video Color Check state. [ renderPAL: ]
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: ]
Defaults to current rendering preferences Super Black Threshold value. [ maxPixelSize: ]
All correspond to items in the 3ds max Render Scene setup dialogs.
Controlling the Renderer
The following are also available if the 3ds max standard scanline renderer is being used: [ antiAliasing: ]
Defaults to current renderer Anti-Aliasing state. [ antiAliasFilterSize: ]
Defaults to current renderer Anti-Aliasing Filter Size value. [ antiAliasFilter: ]
Defaults to current renderer Anti-Aliasing filter. [ enablePixelSampler: ]
Defaults to the current renderer Global SuperSampling state. This state is true if Disable all Samplers is checked, otherwise false. [ mapping: ]
Defaults to current renderer Mapping state. [ shadows: ]
Defaults to current renderer Shadows state. [ autoReflect: ]
Defaults to current renderer Auto-Reflect/Refract and Mirrors state. [ forceWireframe: ]
Defaults to current renderer Force Wireframe state. [ wireThickness: ]
Defaults to 1.0. [ filterMaps: ]
Defaults to current renderer Anti-Aliasing Filter Maps state. [ objectMotionBlur: ]
Defaults to current renderer Object Motion Blur Apply state. [ objectBlurDuration: ]
Defaults to 0.5. [ objectBlurSamples: ]
Defaults to 10. [ objectBlurSubdivisions: ]
Defaults to 10. [ imageMotionBlur: ]
Defaults to current renderer Image Motion Blur Apply state. [ imageBlurDuration: ]
Defaults to 0.5. [ autoReflectLevels: ]
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.
1667
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
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 <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 , 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
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
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.
1669
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
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
You can explicitly disconnect from all active OLE server applications with the releaseAllOLEObjects() function. Its form is: releaseAllOLEObjects()
After calling this function, all existing OLE objects become disabled and any attempt to use them further will generate a runtime error.
Setting Up MAXScript OLE Automation In order to use the OLE Automation features in MAXScript, you need to register 3ds max as an OLE Automation server in the system registry: 1.
Open the Maxscrpt.reg file that ships with 3ds max in Notepad or some other text editor.
2.
Edit this registry entry file to make sure it references the correct 3ds max executable. Make sure the last line specifies the correct location for your 3ds max executable. The supplied Maxscrpt.reg file points to c:\3dsmax\3dsmax.exe by default.
3.
Save the file and exit the editor.
4.
Locate the Maxscrpt.reg registry file in Windows Explorer and double-click it.
This registers 3ds max as an OLE server. You need to do this on all the systems you expect to run 3ds max as an OLE server. For more information, see the following topics: Exposing MAXScript Functions (p. 1673) 3ds max Specific Errors (p. 1674) Running the OLE Demo (p. 1674)
Exposing MAXScript Functions The list of OLE Automation-callable MAXScript functions is defined using the registerOLEInterface() function. It takes an array of functions to be exposed: registerOLEInterface <array_of_fns>
For example: registerOLEInterface #(get_object_count, get_object_name, get_object_position)
Each time you call this function, it replaces the current set of exposed functions with the new set -it does not add to the existing set. The functions you expose should limit themselves to passing and returning only the following data types: integers, reals (floats), currency, string, boolean and empty (undefined).
1673
1674
Chapter 17
|
OLE Automation
3ds max Specific Errors There are two errors that may be reported to OLE clients when calling exposed MAXScript functions that are specific to 3ds max: #512 -- an exception or interrupt occurred while running the called function #513 -- the called function attempted to return an unsupported data type
Running the OLE Demo The example supplied consists of 2 files: ole.ms -- a MAXScript script containing a grapher interface oledemo.xls -- an Excel spreadsheet with some data and a VBA script to call the grapher To run the example, make sure you’ve registered 3ds max as an OLE server as described in the Setting Up MAXScript OLE Automation (p. 1673) topic, start 3ds max and open the ole.ms script file in a script Editor window. You’ll see it contains definitions for six functions and a call to registerOLEInterface() to expose some of those functions. Select the whole script and press number pad ENTER to evaluate it. This defines the functions and exposes them through OLE. Start Excel and open the oledemo.xls spreadsheet (in the scripts directory). It contains one worksheet and one module sheet and defines a new Max menu. The worksheet contains some example data to be charted and the module sheet contains the VBA scripts that implement the menu commands in the new 3ds max menu. Bring up the sheet1 worksheet. It contains a table of numbers representing quarterly sales figure for a number of regions. Drag-select all the label and figure cells and choose the Max > Build Animated Chart menu. This opens a connection to 3ds max and passes the selected column labels and figures to the appropriate functions in the exposed interface. It then brings 3ds max to the front which chugs away for a bit building the labeled bar chart and animating the bars over the range of quarters given. Drag the slider to see the bars animate. Business graphs in 3ds max! The Max > Render Movie menu in Excel invokes another of the exposed MAXScript functions that creates and animates a camera in the bar chart scene and then sets off a render to an AVI file. (If you want to interrupt the render, hold down the ESC key until it stops at the beginning of the next frame - currently the MAXScript renderer interface only looks at the ESC key between frames).
Chapter 18:
Trigonometric Functions and Vector Arithmetic
Trigonometric Functions This topic is a quick review for readers who need a reminder about this area of mathematics. If you’re familiar with trigonometry, you can skip this topic. If you find this topic difficult to follow, you might consult a more basic reference on mathematics. Trigonometric functions are principally used to model or describe: •
The relation between angles in a triangle (hence the name).
•
Rotations about a circle, including locations given in polar coordinates.
•
Cyclical or periodic values, such as sound waves.
The three basic trigonometric functions are derived from an angle rotating about a unit circle.
Trigonometric functions based on the unit circle
1676
Chapter 18
|
Trigonometric Functions and Vector Arithmetic
The tangent function is undefined for x = 0. Another way to define the target is:
Because XYR defines a right-angled triangle, the relation between the sine and cosine is:
The graphs of the basic trigonometric functions illustrate their cyclical nature.
Graphs of basic trigonometric functions
The sine and cosine functions yield the same values, but the phase differs along the X-axis by ?/2: in other words, 90 degrees. The inverse functions for the trigonometric functions are the arc functions—the inverse only applies to values of x restricted by –?/2 = X = ?/2. The graphs for these functions appear like the basic trigonometric function graphs, but turned on their sides.
Graphs of basic arc functions
Vector Arithmetic
The hyperbolic functions are based on the exponential constant e instead of on circular measurement. However, they behave similarly to the trigonometric functions and are named for them. The basic hyperbolic functions are:
Graphs of basic hyperbolic functions
Vector Arithmetic This topic is a quick review for readers who need a reminder about vector arithmetic. If you’re familiar with vectors and vector calculations, you can skip this topic. If this topic is difficult to follow, you might consult a more basic reference on mathematics. A vector expresses a length and a direction in a particular space. The vector is expressed as a point; for example, [5, 5, 7]. The length is the distance from the origin to that point, and the direction is similarly from the origin to (and through) the point. In 3ds max, vectors have three values and describe positions in three-dimensional space. They can also represent percent scaling in X, Y, and Z; and—more abstractly—describe locations in RGB color space.
1677
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
Subtracting two vectors
Scalar Multiplication and Division Multiplying a vector by a scalar changes the vector’s length, as does dividing the vector by a scalar.
Vector Length and Direction The length of a vector is obtained from the Pythagorean theorem.
In MAXScript, the length() function returns this value. The direction of the vector is the vector divided by its length; this gives you a unit vector with the same direction.
The distance between two points is the length of the vector between them.
Subtracting vectors to obtain a distance
1679
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: [...] (...|...|...) {...} {...}+ ::= 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: [-]{}[.{}][(e | E)[+ | -]{}+]
which is interpreted as follows: Syntax
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)[+ | -]{}+]
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.
<program>
::=
{ <expr> }+
<expr>
::=
<simple_expr> <while_loop> <do_loop> <struct_def> <max_command> <macroscript_def>
::=
( local | global ) <decl> { , <decl> } persistent global <decl> { , <decl> }
<decl>
::=
[ = <expr> ] -- name and optional -- initial value
::=
{ | _ } ‘{ }‘
::=
<destination> <destination> <destination> <destination> <destination>
<destination>
::=
<property>
= <expr> += <expr> -= <expr> *= <expr> /= <expr>
MAXScript Grammar
::=
if <expr> then <expr> [ else <expr> ] if <expr> do <expr>
<while_loop>
::=
while <expr> do <expr>
<do_loop>
::=
do <expr> while <expr>
::=
for ( in | = ) <source> (do | collect) <expr>
<source>
::=
<expr> to <expr> [ by <expr> ] [ where <expr> ] <expr> [ where <expr> ]
::=
exit [ with <expr> ]
::=
continue
::=
case [ <expr> ] of ( { } )
::=
: <expr> default : <expr>
<struct_def>
::=
struct (<member> { , <member> } )
<member>
::=
[ = <expr> ] -- name and optional initial value
::=
try <expr> catch <expr>
::=
[ mapped ] (function | fn) { <arg> } = <expr>
<arg>
::=
: [ ]
::=
return <expr>
::=
{ , } <expr>
::=
[with] animate at level at time in [in] coordsys ( local | world | parent | ) about ( pivot | selection | coordsys | ) [ with ] undo
<set_context>
::=
set
::=
utility <string> { : } \ ( { }+ )
1683
1684
Chapter 19
|
MAXScript Grammar and Class Hierarchy
::=
::=
rollout <string> { : } \ ( { }+ )
::=
local <decl> { , <decl> } <struct_def> <mousetool>
::=
group <string> ( { } )
::=
on { } do <expr>
::=
[ <string> ] { : }
::=
label button edittext combobox dropdownList listbox spinner slider pickbutton radiobuttons checkbox checkbutton colorPicker mapbutton materialbutton progressbar timer bitmap
::=
rcmenu ( { }+ )
::=
local <decl> { , <decl> } <struct_def>
::=
on do <expr>
::=
<string> { : }
MAXScript Grammar
::=
menuitem separator submenu
<macroscript_def> ::=
macroscript <string> { : } \ ( <expr_seq> )
<mousetool_def>
::=
tool {:} ({ }+ )
::=
local <decl> { , <decl> } <struct_def>
::=
on { } do <expr>
::=
plugin { : } \ ( { }+ )
::=
local <decl> { , <decl> } <struct_def> <parameters> <mousetool_def>
<parameters>
::= parameters { : } ( { <param_clause> }+ )
<param_clause>
::=
{ <param_defs> }+ { <param_handler> }
<param_defs>
::=
{ : }
<param_handler>
::=
on { } do <expr>
::=
on do <expr>
<simple_expr>
::=
<math_expr> <expr_seq>
1685
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
-- conversion between types
<math_operand>
::=
<math_expr>
::=
or and not
::=
::=
or equal
== != > < >=
------
equal not equal greater than less than greater than
::=
() { <parameter> } -- up to an end of line or -- lower precedence token
<parameter>
::=
:
::=
<property>
<property>
::=
. -- properties and indexes -- left associate
MAXScript Grammar
::=
[ <expr> ]
::=
<string> <path_name> # <array> <point3> <point2> true false on off ok undefined unsupplied - <expr> <expr_seq> ?
-- unary minus -- last Listener result
<expr_seq>
::=
( <expr> { (; | <eol>) <expr> } )
::=
[-]{}[.{}[(e | E)[+ | -]{}+] -- decimal number 0x{}+ -- hexadecimal number
<string>
::=
“{ | \“ | \n | \r | \t | \* | \? | \\ | \% | \x{}+ }“
::=
[-]{<decimal_number>[m | s | f | t]}+ -- minutes/sec/ frames/ticks [-]{}:{}[.{}] -- SMPTE mins:secs.frame [-]<decimal_number>n -- active segment normalized time
::=
[ <expr>, <expr>, <expr>, <expr> ]
<point3>
::=
[ <expr>, <expr>, <expr> ]
<point2>
::=
[ <expr>, <expr> ]
<array>
::=
#() #( <expr> { , <expr> } )
::=
#{} #{[<expr> | <expr>..<expr>] { , [<expr> | <expr>..<expr>] }}
<path_name>
::=
$<path> | $
<path>
::=
[ ] [ / ] [ ]
1687
1688
Chapter 19
|
MAXScript Grammar and Class Hierarchy
::=
{ / }
::=
...
::=
{ | _ | * | ? | \ } ‘{ | \* | \? | \\ }‘
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
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
1689
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
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
1691
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
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
1693
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
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
1695
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
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
1697
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
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
1699
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
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
1701
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
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
1703
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
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
1705
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
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
1707
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
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
1709
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
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
1711
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
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
1713
1714
Chapter 19
|
MAXScript Grammar and Class Hierarchy
Chapter 20:
Using the HTML Help Viewer
Using the HTML Help Viewer This online information system is a compiled HTML help (.chm) file; you view it using Microsoft’s HTML Help Viewer, powered by Internet Explorer. The HTML Help Viewer is a three-pane window: •
The Navigation pane (p. 1717) is on the left side of the window. It contains four navigational tabs, for Contents, Index, Search (p. 1718), and Favorites (p. 1721).
•
The Topic pane is on the right side of the window. It displays the selected help topic, or the default help topic.
•
The toolbar (p. 1721) is the third pane, located below the help window title bar.
Here are some tips on how to find more information when using the HTML Help Viewer: •
To link to another topic or a list of other topics, click the colored, underlined words in the Topic pane.
•
If you use a particular help topic often, you can add it to your favorites list (p. 1721).
•
Right-click the Contents or Favorites tab or the Topic pane for shortcut menu commands.
See also Finding Information Fast (p. 1717) Searching for Help Topics (p. 1718) Note: Most of information about using the HTML Help Viewer has been supplied directly by Microsoft. It has been made freely available for inclusion in HTML help projects such as this one. This information has been edited and reformatted to match the Discreet online information systems.
1716
Chapter 20
|
Using the HTML Help Viewer
Procedures To find a help topic 1.
In the Navigation pane, click one of the following tabs: • To browse through a table of contents, click the Contents tab. The table of contents is an expandable list of important topics. • To see a list of index entries, click the Index tab, and then type a word or scroll through the list. Topics are often indexed under more than one entry. • To locate every occurrence of a word or phrase that may be contained in a help file, click the Search tab, and then type the word.
2.
Click the contents entry, index entry, or search results entry to display the corresponding topic.
To copy a help topic 1.
In the Topic pane, right-click the topic you want to copy, and then click Select All.
2.
Right-click again, and then click Copy. This copies the topic to the Clipboard.
3.
Open the document you want to copy the topic to.
4.
Position your cursor where you want the information to appear.
5.
On the Edit menu, click Paste.
To copy only part of a topic •
Select the text you want to copy, right-click, and then click Copy.
To print the current help topic •
Right-click a topic, and then click Print. If you print from the Contents tab (by right-clicking an entry, and then clicking Print) you will see options to print only the current topic, or the current topic and all subtopics.
To hide or show the Navigation pane •
On the toolbar, click Hide or Show to close or display the Navigation pane, which contains the Contents, Index, Search, and Favorites tabs. If you close the Help Viewer with the Navigation pane hidden, it will appear that way when you open the Help Viewer again.
Finding Information Fast
Finding Information Fast Use the Navigation pane in the Help Window to get to information quickly. It contains tabs that let you use Contents, Index, or Search techniques to get to topics you need.
Contents Tab The Contents tab displays the main sections of this 3ds max online system as book icons. When you click a book, it expands to show the list of topics contained within it, like chapters in hard-copy books. To go to a topic from the Contents tab 1.
Click the Contents tab to display the Table of Contents view.
2.
Click the book icon representing the area for which you want information. The page icons for the book expand below representing all the topics for the book’s feature area.
3.
Click the page icon for the topic you want.
Index Tab The Index is an alphabetical listing of keywords found in each topic. A single keyword may be linked to more than one topic. You may type the first few letters of a subject to jump to an index entry that matches what you are looking for. To go to a topic from the Index tab 1.
Click the Index tab to display the Help Index.
2.
In the form at the top of the Index, type the subject you want to find, or scroll through the alphabetical list to find the term for which you need information.
3.
Click the term, then click Display to see the topic for that term, or double-click the term to see its topic. The topic displays in the right pane and may show links to related topics.
Search Tab The Search tab summons a full-text search engine that operates on a database of every word in the help system, created when the HTML Help system was compiled. You can use tools on the Search tab to find the help topics (p. 1718) containing any word or phrase.
1717
1718
Chapter 20
|
Using the HTML Help Viewer
Searching for Help Topics A basic search consists of the word or phrase you want to find. You can use Boolean, wildcard, and nested expressions. You can also limit the search to previous results, match similar words, or search topic titles only to further define your search. The basic rules for formulating queries are as follows: •
Searches are not case-sensitive, so you can type your search in uppercase or lowercase characters.
•
You may search for any combination of letters (a through z) and numbers (0 through 9).
•
Punctuation marks such as the period, colon, semicolon, comma, and hyphen are ignored during a search.
•
Group the elements of your search using double quotes (p. 1718) or parentheses (p. 1719) to set apart each element. You cannot search for quotation marks. Note: If you are searching for a file name with an extension, you should group the entire string in double quotes, (“filename.ext”). Otherwise, the period will break the file name into two separate terms. The default operation between terms is AND, so you will create the logical equivalent to “filename AND ext.”
Searching for Words or Phrases: Using Wildcards You can search for words or phrases and use wildcard expressions. Wildcard expressions allow you to search for one or more characters using a question mark or asterisk. The table below describes the results of these different kinds of searches. Search for
Example
Results
A single word
select
Topics that contain the word “select.” (You will also find its grammatical variations, such as “selector” and “selection.”)
A phrase
“new operator” or new operator
Topics that contain the literal phrase “new operator” and all its grammatical variations.
Wildcard expressions esc* or 80?86
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.
Turn on Match Similar Words to include minor grammatical variations for the phrase you search.
Searching for Help Topics
Defining Search Terms: Using Boolean Expressions The AND, OR, NOT, and NEAR operators enable you to precisely define your search by creating a relationship between search terms. The following table shows how you can use each of these operators. If no operator is specified, AND is used. For example, the query “spacing border printing” is equivalent to “spacing AND border AND printing.” Search for
Example
Results
Both terms in the same topic.
dib AND palette
Topics containing both the words “dib” and “palette.”
Either term in a topic.
raster OR vector
Topics containing either the word “raster” or the word “vector” or both.
The first term without ole NOT dde the second term.
Topics containing the word “OLE,” but not the word “DDE.”
Both terms in the same topic, close together.
Topics containing the word “user” within eight words of the word “kernel.”
user NEAR kernel
Note: The |, &, and ! characters don’t work as Boolean operators (you must use OR, AND, and NOT).
Using Nested Expressions When Searching Nested expressions allow you to create complex searches for information. For example, “control AND ((active OR dde) NEAR window)” finds topics containing the word “control” along with the words “active” and “window” close together, or containing “control” along with the words “dde” and “window” close together. The basic rules for searching help topics using nested expressions are as follows: •
You can use parentheses to nest expressions within a query. The expressions in parentheses are evaluated before the rest of the query.
•
If a query does not contain a nested expression, it is evaluated from left to right. For example: “Control NOT active OR dde” finds topics containing the word “control” without the word “active,” or topics containing the word “dde.” On the other hand, “control NOT (active OR dde)” finds topics containing the word “control” without either of the words “active” or “dde.”
•
You cannot nest expressions more than five levels deep.
Procedures To go to a topic from the Search tab 1.
Click the Search tab, and then type the word or phrase you want to find.
2.
Click the Boolean button (to the right of the test field) to add Boolean operators to your search.
3.
Click List Topics, choose the topic you want, and then click Display.
4.
To sort the topic list alphabetically, click the Title column heading.
1719
1720
Chapter 20
|
Using the HTML Help Viewer
You can precisely define a search by using wildcard expressions, nested expressions, and Boolean operators. You can request similar word matches, search only the topic titles, or search the results of a previous search. You can set the Help Viewer to highlight all instances of search terms that are found in topic files. Click the Options button, and then click Search Highlight On. To highlight words in searched topics When searching for words in help topics, you can have each occurrence of the word or phrase highlighted in the topics that are found. •
To highlight all instances of a search word or phrase, click Options on the toolbar, and then click Search Highlight On. To turn off this option, click Options on the toolbar, and then click Search Highlight Off. If you are viewing a long topic, only the first 500 instances of a search word or phrase will be highlighted.
To search for words in the titles of HTML files 1.
Click the Search tab, type the word or phrase you want to find, and then turn on Search Titles Only.
2.
Click List Topics, choose the topic you want, and then click Display. If you use this option, all HTML topic files will be searched, including any that are not listed in the table of contents.
To find words similar to your search term This feature enables you to include minor grammatical variations for the phrase you search. For example, a search on the word “add” will find “add,” “adds,” and “added.” 1.
Click the Search tab, type the word or phrase you want to find, and then turn on Match Similar Words.
2.
Click List Topics, choose the topic you want, and then click Display. This feature only locates variations of the word with common suffixes. For example, a search on the word “add” will find “added,” but it will not find “additive.”
To search only the last group of topics you searched This feature enables you to narrow a search that results in too many topics found. You can search through your results list from previous search by using this option. 1.
On the Search tab, turn on Search Previous Results.
2.
Click List Topics, choose the topic you want, and then click Display. If you want to search through all of the files in a help system, this check box must be off. If you previously used this feature, the Search tab opens with this check box turned on.
Favorites Tab
To repeat an earlier search •
Click the down arrow on the text-entry field and choose a previously used search string, and then click List Topics.
Favorites Tab Use tools on the Favorites tab to create a set of topics you use often; you can name them as you choose.
Procedures To create a list of favorite help topics 1.
Locate the help topic you want to make a favorite topic.
2.
Click the Favorites tab, and then click Add.
To return to a favorite topic 1.
Click the Favorites tab.
2.
Choose the topic, and then click Display.
To rename a topic in the Favorites list •
Choose the topic, and then enter a new name in the Current topic box.
To remove a favorite topic •
Choose the topic, and then click Remove.
HTML Help Viewer Toolbar The Help Viewer toolbar contains the following features. Hide/Show: Click this toggle to hide the Navigation pane when it is displaying, or show it when it’s hidden. Back/Forward: Click to move to the previously viewed topic, or forward to the following 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.
1721
1722
Chapter 20
|
Using the HTML Help Viewer
Internet Options: Displays a dialog to change Internet Explorer (IE) settings. The 3ds max information systems do not use this feature. Making changes here does not affect these systems, but will alter your IE browser settings. We do not recommend you use this option. Print: Same as the Print button, above. Search Highlight On/Off: Toggles highlighting on and off for each occurance of a word or phrase found with a search.
HTML Help Viewer Right-Click Menus There are several commands on the shortcut menu that you can use to display information. Command
Description
Right-click in the table of contents, and then click Open All.
Opens all books or folders in the table of contents. This command only works if the Contents tab is displayed.
Right-click in the table of contents, and then click Close All.
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
Press
Close the Help Viewer.
ALT+F4
Switch between the Help Viewer and other open windows.
ALT+TAB
Display the Options menu.
ALT+O
Hide or show the Navigation pane.
ALT+O, and then press T
Print a topic.
ALT+O, and then press P, or right-click in the Topic pane and choose Print.
Move back to the previous topic.
ALT+LEFT ARROW, or ALT+O, and then press B
Move forward to the next topic (provided you have viewed it just previously).
ALT+RIGHT ARROW, or ALT+O, and then press F
Turn on or off search highlighting.
ALT+O, and then press O
Refresh the topic that appears in the Topic pane (this is useful if you have linked to a Web page).
F5, or ALT+O, and then press R
Keyboard Shortcuts in the Help Viewer
To
Press
Return to the home page (help authors can specify a home page for a help system).
ALT+O, and then press H
Switch between the Navigation and Topic panes.
F6
Scroll through a topic.
UP ARROW and DOWN ARROW, or PAGE UP and PAGE DOWN
Scroll through all the links in a topic or through all the options on a Navigation pane tab.
TAB
Contents Tab To
Press
Display the Contents tab.
ALT+C
Open and close a book or folder.
PLUS SIGN and MINUS SIGN, or LEFT ARROW and RIGHT ARROW
Choose a topic.
DOWN ARROW and UP ARROW
Display the selected topic.
ENTER
Index Tab To
Press
Display the Index tab.
ALT+N
Type a keyword to search for.
ALT+W, and then type the word
Choose a keyword in the list.
UP ARROW and DOWN ARROW
Display the associated topic.
ALT+D
Search Tab To
Press
Display the Search tab.
ALT+S
Type a keyword to search for.
ALT+W, and then type the word
Start a search.
ALT+L
Choose a topic in the results list.
ALT+T, and then UP ARROW and DOWN ARROW
Display the selected topic.
ALT+D
Search for a keyword in the result list of a prior search.
ALT+U
Search for words similar to the keyword. For example, to find words like “running” and “runs” for the keyword “run.”
ALT+M
Only search through topic titles.
ALT+R
1723
1724
Chapter 20
|
Using the HTML Help Viewer
Favorites Tab To Display the Favorites tab.
Press ALT+I
Add the currently displayed topic to the Favorites list.
ALT+A
Choose a topic in the Favorites list.
ALT+P, and then UP ARROW and DOWN ARROW
Display the selected topic.
ALT+D
Remove the selected topic from the list.
ALT+R
Notes: •
There are also shortcut menu commands (p. 1722) that can be accessed through the keyboard.
•
Every time you use a shortcut key in the Navigation pane, you lose focus in the Topic pane. To return to the Topic pane, press F6.
•
The Match Similar Words check box, on the Search tab, will be turned on if you used it for your last search.
Chapter 21:
character studio 3 MAXScript Extensions
Biped General Topics Biped Load and Save Methods This topic will cover the load and save methods for motion, figure, score, keys, motion capture, and talent files. -- Motion File Access Methods biped.LoadBipFile
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
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
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
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.SaveScoreFile
Score files are Step files which save footsteps, but don’t save body keyframes. They are an ASCII file format that enables developers to write programs that generate step files for biped motion. The online document stp.rtf, provided with character studio in the \cstudio\docs directory, describes the .stp format. Notes: Load/Save a Step (*.STP) file -- Motion Capture File Access Methods biped.loadMocapFile [#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
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
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
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
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
Creates a layer at the specified position, maximum index value can be NumLayers + 1
Biped Creation
biped.deleteLayer
Deletes the specified layer biped.getCurrentLayer
Returns the position of the currently active layer in the UI biped.getLayerActive
Returns true if the specified layer is active. biped.getLayerName
Returns the specified layer name biped.numLayers
Returns the number of layers biped.setCurrentLayer
Sets the active layer in the UI to the specified layer biped.setLayerActive
Sets the specified layer to active/inactive based upon the bool_val passed biped.setLayerName
Sets the specified layer name to the value passed The following example will create a new Biped, access it’s Vertical_Horizontal_Turn(Body) controller and load a specific *.Bip file: Script Example: -- create a new Biped bipObj = biped.createNew 100 100 [0,0,0] -- select bipObj bip = bipObj.transform.controller max motion mode -- File I/O biped.LoadBipFile bip (CSPATH + “scripts\\Limploop.bip”)
See Also Biped Creation (p. 1727) Biped Controllers (p. 1735) Biped MaxScript Extensions (p. 1725)
Biped Creation The following properties and methods are applicable to any created Biped. Constructor: biped.createNew <wpos_point3> . . .
the height of the Biped to be created angle in degrees
0( will make the Biped face towards the right. <wpos_point3> shadow.
world position of the Biped. This is the position of the COM
1727
1728
Chapter 21
|
character studio 3 MAXScript Extensions
Creation Properties: .arms
Boolean
Default: True
Specifies whether or not arms will be generated for the current biped. .neckLinks
Integer
Default: 1
Specifies the number of links in the biped neck. .spineLinks
Integer
Default: 4
Specifies the number of links in the biped spine. .legLinks
Integer
Default: 3
Specifies the number of links in the biped legs. .tailLinks
Integer
Default: 0
Specifies the number of links in the biped tail. A value of 0 specifies no tail. .ponytail1Links
Integer
Default: 0
Specifies the number of Ponytail links. .ponytail2Links
Integer
Default: 0
Specifies the number of Ponytail links. .fingers
Integer
Default: 1
Specifies the number of biped fingers. .fingerLinks
Integer
Default: 3
Sets the number of links per finger. .toes
Integer
Default: 5
Specifies the number of biped toes. .toeLinks
Integer
Default: 3
Specifies the number of links per toe. .ankleAttach
Float
Default: 0.2
Specifies the right and left ankles’ point of attachment along the corresponding foot block. The ankles may be placed anywhere along the center line of the foot block from the heel to the toe. A value of 0 places the ankle attachment point at the heel. A value of 1 places the ankle attachment point at the toes. .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
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 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)
1729
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: .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
Biped Layers Layer Related Methods biped.collapseAtLayer
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
Creates a layer at the specified position, maximum index value can be NumLayers + 1. biped.deleteLayer
Deletes the specified layer biped.getCurrentLayer
Returns the position of the currently active layer in the UI. biped.getLayerActive
Returns true if the specified layer is active. biped.getLayerName
Returns the specified layer name. biped.numLayers
Returns the number of layers. biped.setCurrentLayer
Sets the active layer in the UI to the specified layer. biped.setLayerActive
Sets the specified layer to active/inactive based upon the boolean_val passed. biped.setLayerName
Sets the specified layer name to the value passed.
Biped Node Hierarchy biped.getNode [link:]
Returns the specified limbnode where the second argument can be a named limb like #larm, #rarm, #lfingers, #rfingers, #lleg, #rleg, #ltoes, #rtoes, #spine, #tail, #head, #pelvis, #footprints, #neck, #pony1, #pony2 or an integer index. . If you don’t specify the link argument the top (first) node is returned. The only exception to this is for the biped COM, which does not contain any linked nodes (including itself). If the specified node does not exist, a value of undefined is returned.
1731
1732
Chapter 21
|
character studio 3 MAXScript Extensions
The top level and their link nodes in character studio 3 are:
Index
Link Nodes in Link Index Order
Top Level
1
L Clavicle
L Clavicle
L UpperArm
L Forearm
L Hand
2
R Clavicle
R Clavicle
R UpperArm
R Forearm
R Hand
3
L Finger0
L Finger0
L Finger01
L Finger02
L Finger1
L Finger11
L Finger12
L Finger2
L Finger21
L Finger22
L Finger3
L Finger31
L Finger32
L Finger4
L Finger41
L Finger42
R Finger0
R Finger01
R Finger02
R Finger1
R Finger11
R Finger12
R Finger2
R Finger21 R Finger32
4
R Finger0
R Finger22
R Finger3
R Finger31
R Finger4
R Finger41
R Finger42
5
L Thigh
L Thigh
L Calf
L HorseLink
L Foot
6
R Thigh
R Thigh
R Calf
R HorseLink
R Foot
7
L Toe0
L Toe0
L Toe01
L Toe02
L Toe1
L Toe11
L Toe12
L Toe2
L Toe21
L Toe22
L Toe3
L Toe31
L Toe32
L Toe4
L Toe41
L Toe42
R Toe0
R Toe01
R Toe02
R Toe1
R Toe11
R Toe12
R Toe2
R Toe21
R Toe22
R Toe3
R Toe31
R Toe32
R Toe4
R Toe41
R Toe42
Spine
Spine1
Spine2
Spine3
Tail1
Tail2
Tail3
Neck1
Neck2
Neck3
Ponytail11
Ponytail12
Ponytail13
Ponytail21
Ponytail22
Ponytail23
8
9
R Toe0
Spine
Spine4 10
Tail
Tail Tail4
11
Head
Head
12
Pelvis
Pelvis
13
Biped COM
14
Biped COM
15
Biped COM
16
Footsteps
17
Neck
Footsteps Neck Neck4
18
Ponytail1
Ponytail1 Ponytail14
19
Ponytail2
Ponytail2 Ponytail24
Biped Node Hierarchy
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
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
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
1733
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
Returns the number of preferred clips biped.getPrefClip
Returns the name of the nth preferred clip. biped.clearPrefClips
Clears the preferred clip list. biped.addPrefClip
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
Deletes the named clip from the preferred clip list. Returns true is successful, false if the clip was not in the list. biped.isPrefClip
Returns true if the clip is in the list, false if not. biped.getCurrentClip
Returns the name of the currently active clip for this biped - only relevant during a crowd solve.
Biped and Crowd Interaction
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 “” in this documentation, is called the Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller (p. 1736). This is sometimes also called the body controller because it is equivalent to the Biped’s.transform.controller. The Biped footsteps have a controller. It is referred to as “” 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)
1735
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: =$bip01.controller
Properties: All the following properties are get/set properties unless specified. -- Structure properties .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. .rootNode
Node
Default: Varies
-- Read-only
The root node (COM) of the Biped system this biped_ctrl belongs to. .arms
Boolean
Default: True
Specifies whether or not arms will be generated for the current biped. .neckLinks
Integer
Default: 1 range: 1-5
Specifies the number of links in the biped neck. .spineLinks
Integer
Default: 4 range: 1-5
Specifies the number of links in the biped spine. .legLinks
Integer
Default: 3 range: 3-4
Specifies the number of links in the biped legs. .tailLinks
Integer
Default: 0 range: 0-5
Specifies the number of links in the biped tail. A value of 0 specifies no tail. .ponytail1Links
Integer
Default: 0 range: 0-5
Integer
Default: 0 range: 0-5
Integer
Default: 1 range: 0-5
Integer
Default: 3 range: 1-3
Specifies the number of Ponytail links. .ponytail2Links
Specifies the number of Ponytail links. .fingers
Specifies the number of biped fingers. .fingerLinks
Sets the number of links per finger. Note: If the number of fingers is 0, fingerLinks is always equal to 1. .toes
Specifies the number of biped toes.
Integer
Default: 5 range: 1-5
Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller
.toeLinks
Integer
Default: 3 range: 1-3
Float
Default: 0.2 range: 0-1
Specifies the number of links per toe. .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. .height
Float
Default: Defined at creation
Boolean
Default: True
Sets the height of the current biped. .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 .gravAccel
Float
Default: 5.63855*Body height
Sets the strength of the gravitational acceleration used to calculate the biped’s motion. By default, this parameter is set to accurately simulate Newtonian gravity as found on the Earth’s surface. .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.
1737
1738
Chapter 21
|
character studio 3 MAXScript Extensions
.adaptLockFreeform
Boolean
Default: False
Turn on to prevent adaptation of a freeform period in a footstep animation. The biped’s position during a freeform period will not move if footsteps after the freeform period are moved further away. .adaptLockHorz
Boolean
Default: False
Turn on to prevent adaptation of body horizontal keys when footsteps are edited in space. .adaptLockTurn
Boolean
Default: False
Turn on to prevent adaptation of body turning keys when footsteps are edited in space. .adaptLockVert
Boolean
Default: False
Turn on to prevent adaptation of body vertical keys when footsteps are edited in space. .adaptLockLLeg
Boolean
Default: False
Turn on to prevent adaptation of left leg move keys (a leg move key, is a leg key between footsteps) when footsteps are edited in space. .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. .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. .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. .sepLegsTracks
Boolean
Default: False
Turn on to create separate toe, foot, and calf transform tracks. .sepPonytail1Tracks
Boolean
Default: False
Turn on to create separate ponytail 1 transform tracks. .sepPonytail2Tracks
Boolean
Default: False
Turn on to create separate ponytail 2 transform tracks.
Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller
Note: If the number of pony tail links is 0, you cannot set Separate Ponytail Tracks to true. .sepNeckTracks
Boolean
Default: False
Turn on to create separate transform tracks for the neck links. .sepTailTracks
Boolean
Default: True
Turn on to create separate transform tracks for each tail link. .sepSpineTracks
Boolean
Default: False
Turn on to create separate spine transform tracks. -- Modes .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. .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. .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. .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.
1739
1740
Chapter 21
|
character studio 3 MAXScript Extensions
.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. .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. .scaleStrideMode
Boolean
Default: True
Footstep stride length and width are scaled to match the stride length and width of the biped figure. scaling occurs automatically when you load a .bip, .stp, or .fig file. When you paste footsteps; or when you scale the biped’s legs or pelvis. .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. .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. .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 character’s center of mass laterally according to game play. In Place mode makes it easy to view, tune, and export animation in a manner that is complimentary to game engine playback.
Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller
Note: Trajectories do not display when In Place mode is active. -- Track Selection .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 .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. .displayObjects
Boolean
Default: True
Boolean
Default: True
Displays biped body objects (objects). .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. .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. .displayTrajectories
Boolean
Default: False
Displays trajectories for selected biped limbs. -- Layers .visibleBefore
Integer
Default: 1
Set the number of preceding layers too display as stick figures. .visibleAfter
Integer
Default: 0
Set the number of succeeding layers too display as stick figures. .keyHighlight
Boolean
Display keys by highlighting the stick figures.
Default: False
1741
1742
Chapter 21
|
character studio 3 MAXScript Extensions
-- Footstep related properties .fsAppendState
Boolean
Default: False
Each new footstep is appended to the end of the biped’s footstep sequence. .fsCreateState
Boolean
Default: False
Set to true to create new states. The first state you add is, by default, the first state in the controller that executes when the simulation is run. .fsGroundDuration
Time
Default: 18f
.fsAirDuration
Time
Default: 3f
Specifies the number of frames when the body will be in the air during a run or a jump. Note: If fsGaitMode is #walk, the above 2 parameters are the Walk Footstep and Double Support durations, respectively. If fsGaitMode is #run, the above 2 parameters are the Run Footstep and Airborne durations, respectively. If fsGaitMode is #jump, the above 2 parameters are the 2-Feet down and Airborne durations, respectively. .fsGaitMode
Name
Default: #walk
fsGaitMode can be set to any of the three gaits: #walk, #run, #jump
-- Motion Flow properties .motionFlow
MoFlow
Returns an instance of MoFlow. See Biped Motion Flow (p. 1752) section for more details. -- Motion Capture properties .displayBuffer
Boolean
Default: False
A red stick figure appears, representing the raw motion capture data. .displayBufferTraj
Boolean
Default: False
Display a trajectory based on the buffered raw motion capture data for any biped body part. Use this in combination with Show/Hide Trajectories on the Display rollout to see how closely the raw and filtered data match. .talentFigMode
Boolean
Default: False
Turn on Talent Figure mode to scale the biped relative to the markers. Calibration for the entire marker file takes place when you exit Talent Figure mode. Keyframe adaptation takes place in order to accommodate the new biped scale; because of this, you should adjust the biped scale before adjusting the biped position relative to the markers. Use Rubber Band Mode on the General rollout and Non-Uniform Scale to size the biped in Talent Figure mode. Ideally, you will not need to use this feature. When loading a motion capture file, Biped attempts to extract the appropriate figure scale from the given data. Use Talent Figure mode only if the extracted scale of the biped doesn’t match the scale of the original talent. Minor differences in scale will alter the motion.
Biped Vertical_Horizontal_Turn(Body):Matrix3 Controller
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 .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) .vertical
Matrix3
-- Animatable
Matrix3
-- Animatable
Matrix3
-- Animatable
The vertical track of controller .horizontal
The horizontal track of controller .turning
The turning track of controller .Ease_Curve Animated over range 0 to 1
Point3
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)
-- Animatable
1743
1744
Chapter 21
|
character studio 3 MAXScript Extensions
FootSteps : Matrix3 Controller Constructor: = $’Bip01 Footsteps’.transform.controller
or: =$’Bip01 Footsteps’.controller
Notes: This controller is attached to the transform track of the named Biped footstep object. Properties: .freeFormMode Boolean false - Edit Footsteps true - Edit Free Form (no physics)
Default: False
.dispNumType 0 - Start and End Frame 1 - Start Frame 2 - Duration 3 - Double Support
Integer
Default: 0
.dispAirDur
Boolean
Default: False
Displays the foot air duration. This is the number of frames each foot is in the air in the lower part of each footstep’s portion of the track. .dispNoSupport
Boolean
Default: False
Displays the number of frames when both feet are off the ground, directly above the areas without footsteps. .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. .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
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. =$’Bip01 Pelvis’.controller
It is not always possible to get the controller via .transform.controller. The transform track is not exposed for all nodes but it is possible to get the controller via: .controller. Properties: .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. .rootNode
Node
Default: Varies
-- Read-only
The root node (COM) of the Biped system this bipslave_ctrl belongs to.
See also Biped MAXScript Extensions (p. 1725)
Biped Footsteps and Footprints This topic will cover the Biped’s footsteps controller, individual footprints, the multiple footstep creation dialog, as well as obtaining and setting the parameters for multiple footsteps. Biped Footsteps (p. 1744) Biped Footprints (p. 1745)
Biped Footprints Methods: biped.addFootprint <matrix3> [append:]
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.
1745
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
Displays the Multiple Footstep Creation dialog biped.getMultipleFSParams
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
Method: biped.addMultipleFootprints <MultFprintParams>
Create footsteps for a Biped based on the MultFprintParams value biped.newFootprintKeys
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)
1747
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 method, where gait_type_name can be #walk, #run or #jump. Properties: #walk <MultFprintParams>.alternate
Boolean
Default:
#run
#jump
true true
true
Footsteps will alternate between right and left. Alternate is always selected when the Walk gait is selected. You can only clear Alternate when Run or Jump gaits are selected. <MultFprintParams>.numFootsteps
Integer
Default:
4
4
4
Determines the number of new footsteps to be created. <MultFprintParams>.paramStrideWidth
Float
Default:
1.0
1.0
1.0
Sets the stride width as a percentage of the pelvis width. A value of 1.0 produces a stride width equal to the pelvis width. A value of 3.0 produces a wide, waddling stride. Changes to this setting automatically change the Actual Stride Width. Parametric describes the parameter in terms of biped anatomy, and Actual describes the value in 3ds max units. <MultFprintParams>.actualStrideWidth
Float
Default:
0.0
0.0
0.0
Sets the stride width in modeling units. Changes to this setting automatically change the Parametric Stride Width. <MultFprintParams>.autoTiming
Boolean
Default:
true true
true
Sets timing parameters automatically. Auto Timing affects the following timing parameters for the Walk gait: Walk footstep, Double Support: When Auto Timing is selected, these parameters are automatically adjusted to reasonable values. Control the footstep sequence by adjusting the Stride Length and Time to Next Footstep parameters. When Auto Timing is cleared, you can control the footstep sequence by adjusting the gait timing parameters, but you can’t change the Time to Next Footstep parameter. <MultFprintParams>.interpTiming
Boolean
Default:
false
false
false
Control acceleration or deceleration of the series of footsteps. <MultFprintParams>.multiInsertInTime false - Start after last footstep
Boolean
Default:
false
false
false
Appends the newly created footsteps to the end of the existing footstep sequence. true - Start at current frame
Inserts the newly created footsteps at the current frame after the existing footstep sequence allowing you to make a gap in time before the footsteps start again. <MultFprintParams>.actualStrideLength1 Float
Default:
Sets the stride length for new footsteps in 3ds max units.
0.0
0.0
0.0
Biped Class : MultFprintParams
<MultFprintParams>.paramStrideLength1
Float
Default:
0.75
1.5
2.4
Sets the stride length for the new footsteps as a percentage of the length of the biped’s leg. The default value of 0.75 gives an average stride of normal proportions. A value of 1.0 will produce a stride length equal to the leg length, which makes the biped stretch slightly to reach the next step. A value of 0.0 will make the biped walk in place. A negative stride length will make the biped walk backwards. When a biped walks backwards, it does not simply reverse the forward movement but maintains the correct foot-state sequence with the toe touching the ground first, followed by the heel. Adjusting Parametric Stride Length automatically changes the value for Actual Stride Length. <MultFprintParams>.actualStrideHeight1 Float
Default:
0.0
0.0
0.0
Sets the rise or fall between footsteps. You can use this parameter to create a set of footsteps going up or down a slope or a stairway. The value for Actual Stride Height is the difference in height in units between each of the new footsteps. Positive values step up and negative values step down. <MultFprintParams>.cycle1 Time <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 biped’s leg. The default value of 0.75 gives an average stride of normal proportions. A value of 1.0 will produce a stride length equal to the leg length, which makes the biped stretch slightly to reach the next step. A value of 0.0 will make the biped walk in place. A negative stride length will make the biped walk backwards. When a biped walks backwards, it does not simply reverse the forward movement but maintains the correct foot-state sequence with the toe touching the ground first, followed by the heel. Adjusting Parametric Stride Length automatically changes the value for Actual Stride Length. <MultFprintParams>.actualStrideHeight2 Float
Default:
0.0
0.0
0.0
Sets the rise or fall between footsteps. You can use this parameter to create a set of footsteps going up or down a slope or a stairway. The value for Actual Stride Height is the difference in height in units between each of the new footsteps. Positive values step up and negative values step down. <MultFprintParams>.cycle2
Time
Default:
15f
15f
See the biped.addMultipleFootprints method for creating footsteps based on a MultFprintParams, and biped.newFootprintKeys creating the biped keys for the inactive footsteps.
15f
1749
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: = $’Bip01 Footsteps’.transform.controller
or: =$’Bip01 Footsteps’.controller
Notes: This controller is attached to the transform track of the named Biped footstep object. Properties: .freeFormMode Boolean false - Edit Footsteps true - Edit Free Form (no physics)
Default: False
BipedFSKey : MAXObject
.dispNumType 0 - Start and End Frame 1 - Start Frame 2 - Duration 3 - Double Support
Integer
Default: 0
.dispAirDur
Boolean
Default: False
Displays the foot air duration. This is the number of frames each foot is in the air in the lower part of each footstep’s portion of the track. .dispNoSupport
Boolean
Default: False
Displays the number of frames when both feet are off the ground, directly above the areas without footsteps. .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. .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: .time
Time
Default: Varies
A value indicating when in time the key occurs. .duration
The number of frames in each footstep.
Time
Default: Varies
1751
1752
Chapter 21
|
character studio 3 MAXScript Extensions
.selected .edgeSel 0 - no edges selected 1 - left edge Selected 2 - right edge selected 3 - both edges Selected
Boolean Integer
Default: False Default: 0
.active
Boolean
Default: True
Matrix3 Name
Default: Varies Default: #left or #right
Activate or make inactive the footstep. .transform .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
<moflow>.snippets -- Read-only
Array
Default: #()
An array of motion flow snippets (MoFlowSnippet values). <moflow>.selSnippets
BitArray
Default: #{}
A bitarray specifying the motion flow snippets that are selected in the Motion Flow Graph. <moflow>.startFrame -- Read-only
Integer
Default: 0
The start frame of currently active motion flow script. <moflow>.endFrame -- Read-only
Integer
Default: 0
The last frame of currectly active motion flow script. Methods: loadMoFlowFile <moflow> [ quiet: ] 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>
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>
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.
1753
1754
Chapter 21
|
character studio 3 MAXScript Extensions
deleteScript <moflow> <MoFlowScript> deleteScript <moflow>
Deletes the specified script. If the second argument is an integer, the script deleted is the indexed script in the motion flow’s .scripts array. getScriptIndex <moflow> <MoFlowScript>
Given the script, returns its index in the script’s combobox. getSnippetIndex <moflow> <MoFlowSnippet>
Given the snippet, returns its index in the in the motion flow’s .snippets array. computeAnimation <moflow> [redraw:<true>] [incGlobals:]
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 <point2_pos>
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
Integer Array
Default: 0f Default: #()
Array of MoFlowSnippet values defined in the motion flow script <MoFlowScript>.name <MoFlowScript>.startPos <MoFlowScript>.startRot
String Point3 Float
Default: Varies Default: [0,0,0] Default: 0
-- Read-only
MoFlowScript : MaxWrapper
Methods: addSnippet < MoFlowScript > < MoFlowSnippet >
Adds the specified MoFlowSnippet to a motion flow script. Returns the MoFlowSnippet value. insertSnippet < MoFlowScript > < MoFlowSnippet >
Inserts the snippet at the location specified and returns the new script item. Returns the MoFlowSnippet value. deleteSnippet < MoFlowScript >
Deletes the indexed MoFlowSnippet from the motion flow script. Related Methods: deleteScript <moflow>
Deletes the indexed MoFlowScript from the motion flow. computeAnimation <moflow> [redraw:<true>] [incGlobals:]
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> <point2_pos>
Adds a new MoFlowSnippet to the motion flow network, from the given .bip file. <point2_pos> is the position in windows coordinates where the origin is the top left of the snippet in the motion flow graph. Redraw :true will redraw the graph window. Load:true will immediately load the snippet. Returns the new MoFlowSnippet. Properties: <MoFlowSnippet>.start
Integer
Default: 0
Integer
Default: Varies
String String Point2
Default: Varies Default: Varies Default: Varies
The start frame in the snippet file. <MoFlowSnippet>.end
The end frame in the snippet file. <MoFlowSnippet>.clipName <MoFlowSnippet>.fileName <MoFlowSnippet>.pos
The coordinates of the snippet in the Motion Flow Graph. <MoFlowSnippet>.active <MoFlowSnippet>.transitions [X,X]) – read only
Boolean Array
Default: True Default: #(MoFlowTransition :
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
1755
1756
Chapter 21
|
character studio 3 MAXScript Extensions
Methods: addTransition
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 >
Deletes the indexed MoFlowTransition emanating from the MoFlowSnippet. deleteTransitionTo
Deletes the transition that’s emanating to the specified snippet. Related Methods: addSnippet < MoFlowScript > < MoFlowSnippet >
Adds the specified MoFlowSnippet to a motion flow script. Returns the MoFlowSnippet value. insertSnippet < MoFlowScript > < MoFlowSnippet >
Inserts a snippet at the location specified and returns the new script item. Returns the MoFlowSnippet value. deleteSnippet < MoFlowScript >
Deletes the indexed MoFlowSnippet from the motion flow script. loadSnippetFiles <moflow>
Loads all of the snippet files whose file names are assigned. This function should be called whenever new snippets are added. getSnippetIndex <moflow> <MoFlowSnippet>
Given the snippet, returns its index in the motion flow’s .snippets array. computeAnimation <moflow> [redraw:<true>] [incGlobals:]
Computes the global flow network. This function has to be called to update any changes made to the motion flow network. redraw:true will redraw the viewports. incGlobals:true will also include the global motion flow network Notes: Changes to the MoFlowSnippet property values do not cause an immediate update of the biped. ComputeAnimation must be called on the MoFlow value to recompute the biped motion.
MoFlowTranInfo : MaxWrapper Constructor: addTranInfo < MoFlowTransition >
Adds a new MoFlowTranInfo to the MoFlowTransition and returns the newly created MoFlowTranInfo. Properties: <MoFlowTranInfo>.length
Integer
Default: 25
Float
Default: 0.0
The transition length in frames. <MoFlowTranInfo>.angle
The direction of the destination clip
MoFlowTranInfo : MaxWrapper
<MoFlowTranInfo>.easeFrom <MoFlowTranInfo>.easeTo <MoFlowTranInfo>.sourceStart
Float Float Integer
Default: 0.5 Default: 0.5 Default: Varies
Integer
Default: Varies
Boolean
Default: True
Boolean
Default: True
Integer
Default: 25
String Integer
Default: ““ Default: 100
The start frame for the source clip <MoFlowTranInfo>.destStart
The start frame for the destination clip <MoFlowTranInfo>.sourceState
false - Fixed true - Rolling <MoFlowTranInfo>.destState
false – Fixed true – Rolling <MoFlowTranInfo>.length
The transition length in frames. <MoFlowTranInfo>.note <MoFlowTranInfo>.probability
Related Methods: deleteTranInfo < MoFlowTransition >
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:]
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]
1757
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
Adds a new MoFlowTransition from the from_MoFlowSnippet to the to_MoFlowSnippet if one doesn’t already exist. The optimize parameter acts as the “Optimize Selected Transition” in the Motion Flow Editor. Properties: <MoFlowTransition>.fromSnippet
MoFlowSnippet Default: Varies
Specifies the MoFlowSnippet transitioning from. <MoFlowTransition>.toSnippet
MoFlowSnippet Default: Varies
Specifies the MoFlowSnippet transitioning to. <MoFlowTransition>.active
Boolean
Default: True -- Read-only
Specifies whether the MoFlowTransition is active. <MoFlowTransition>.selected
Boolean
Default: False
Specifies whether the MoFlowTransition line is selected in the Motion Flow Graph. <MoFlowTransition>.tranInfos -- Read-only
Array
Default: #(MoFlowTranInfo :[X,X])
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
deleteTranInfo < MoFlowTransition >
Deletes the indexed MoFlowTranInfo from MoFlowTransition. If the MoFlowTranInfo is the only MoFlowTranInfo in MoFlowTransition, it is not deleted. Related Methods: deleteTransition < MoFlowSnippet >
Deletes the indexed MoFlowTransition emanating from the MoFlowSnippet. deleteTransitionTo
Deletes the transition that’s emanating to the specified snippet. computeAnimation <moflow> [redraw:<true>] [incGlobals:]
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 [ #select ] 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 [ #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.
1759
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 ( | )
Notes: Returns an instance of BipedKey for Biped body controllers and BipedFSKey for footstep controllers. BipedKey and BipedFSKey are defined below. Not all of the Biped elements contain a transform controller. Rather, a controller on an object typically higher in the hierarchy may store the transform key for an element. For example, the transforms for all the fingers on a hand are stored in either the Finger0 or Clavicle transform controller. This depends on whether “Separate Tracks for Arms” is set to true or false, respectively. The following example will get the first key for each of the subcontrollers of the $Bip01 Vertical_Horizontail_Turn transform controller and show their properties. Additionally, the first key of the $Bip01 Footstep transform controller will have its properties shown. Script Example: bip = $Bip01.transform.controller -- Obtain the subcontrollers vertCont = bip.vertical.controller horzCont = bip.horizontal.controller turnCont = bip.turning.controller -- Get the first key for each subcontroller vk = biped.getKey vertCont 1 hk = biped.getKey horzCont 1 tk = biped.getKey turnCont 1 -- Show the properties for the individual subcontroller key types showProperties vk showProperties hk showProperties tk -- Obtain the Biped’s Footstep controller fsCont = $’Bip01 Footsteps’.transform.controller -- Show the Footstep controller properties showProperties fsCont -- Get the first Footstep controller key fk = biped.getkey fsCont 1 showProperties fk
See also BipedKey : MAXObject (p. 1761)
BipedKey : MAXObject
BipedKey : MAXObject All Biped vertical, horizontal, turning, and body keys are represented by this class. Properties: .time
Time
Default: Varies
Enter a value to specify when in time the key occurs. .selected .tension
Boolean Float
Default: False Default: 25.0
Controls the amount of curvature in the animation curve. High Tension produces a linear curve. It also has a slight Ease To and Ease From effect. Low Tension produces a very wide, rounded, curve. It also has a slight negative Ease To and Ease From effect. .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. .bias
Float
Default: 25.0
Controls where the animation curve occurs with respect to the key. .easeTo
Float
Default: 0.0
Slows the velocity of the animation curve as it approaches the key. High Ease To causes the animation to decelerate as it approaches the key. The default setting causes no extra deceleration. .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. .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 .z
Float
Default: Varies
Float
Default: 1.0
Reposition the selected biped part in z. .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. .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.
1761
1762
Chapter 21
|
character studio 3 MAXScript Extensions
-- #horizontal .x
Float
Default: Varies
Float
Default: Varies
Float
Default: 1.0
Reposition the selected biped part in x. .y
Reposition the selected biped part in y. .balanceFactor
Position the biped’s weight anywhere along a line that extends from the center of mass to the biped’s head. A value of 0 places the biped’s weight at the center of mass. A value of 1 places the biped’s weight above the center of mass. A value of 2 places the biped’s weight in the head. -- #body .ikBlend
Float
Default: 0.0
Determines how forward kinematics and inverse kinematics are blended to interpolate an intermediate position. .ikSpace 0 - Body
Integer
Default: 0
The biped limb is in biped coordinate space. 1 - Object
The biped limb is either in World coordinate space or the coordinate space of the selected object. Coordinate space can be blended between keys. .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. .ikJoinedPivot
Boolean
Default: True
Put the biped foot in the coordinate space of the previous key. .ikPivotIndex
Integer
Default: 1
Index into .ikPivots array of active (selected) pivot .ikNumPivots
Integer
Default: Varies – Read only
Number of pivot points in .ikPivots array .ikPivots
Array
Deafult: Varies - Array of Point3 values
Array of positions of all the pivot points for the body part Here is an example: Script Example: k = biped.getKey $’bip01 L clavicle’.transform.controller 2 showProperties k k.ikBlend = .5 k.ikSpace = 0 k.ikAnkleTension = .8 k.ikJoinedPivot = false k.ikPivotIndex = 8 k.ikNumPivots = 2 k.ikPivots -- to add a new one k = biped.addNewKey $’bip01 L clavicle’.transform.controller 10f
BipedFSKey : MAXObject
BipedFSKey : MAXObject This class represents a Biped footstep in the viewports and trackview. Properties: .time
Time
Default: Varies
A value indicating when in time the key occurs. .duration
Time
Default: Varies
.selected .edgeSel 0 - no edges selected 1 - left edge Selected 2 - right edge selected 3 - both edges Selected
Boolean Integer
Default: False Default: 0
.active
Boolean
Default: True
Matrix3 Name
Default: Varies Default: #left or #right
The number of frames in each footstep.
Activate or make inactive the footstep. .transform .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.
1763
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
Integer
Default: 2
Set the vertical axis used in the motion capture data. 0 - X 1 - Y 2 - Z mocap.scaleFactor
Float
Default: 1.0
Multiply the stored talent size by this value and size the biped accordingly. -- range: 1+
-- Footstep Extraction mocap.fsExtractionTol
Float
Default: 0.05
Set the sensitivity of footstep extraction. Biped determines if the footstep is there by checking that the foot does not move beyond the distance determined by the Extraction Tolerance value. Smaller numbers are more sensitive and extract more footsteps. Value is a percentage of foot length. -- range: 0+ mocap.fsSlidingDist
Float
Default: 0.0
Create a sliding footstep when positional tolerance is reached. This value is a percentage of foot length. By default the foot must slide its own distance (100), before a sliding footstep is created. -- range: 0+ mocap.fsSlidingAngle
Float
Default: 0.0
Create a sliding footstep when rotational tolerance is reached. This value is in degrees. If this is set high (360 degrees), the foot must make a complete turn before a sliding footstep is created. -- range: 0-360
BipedFSKey : MAXObject
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
Float
Default: 0.0
Boolean
Default: False
Value is a percentage of leg length -- range: 0+ mocap.fsZLevel
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
Integer
Default: 0
Start importing at this frame. Default is frame 0, the first frame. mocap.endFrame
Integer
Default:0
Stop importing at this frame. Default is the last frame of the clip. mocap.loop
Boolean
Default: False
Loop the data by the value set here. This is relative. Succeeding loops start where the previous loop left off. The clips are not blended and may require editing unless the original clip was designed to loop. Use this for clips designed to loop. Note: This often works best if Footstep Extraction is tuned off. mocap.loopFrameCount
Integer
Default: 0
-- range: 0+
-- Key Reduction Settings Tolerance: Set the maximum angular or positional deviation for a track. Values are in degrees for rotation tracks. Values are in units of translation for position tracks. Minimum Key Spacing: Set the minimum number of frames between keys. Tolerance is computed first, then Minimum Key Spacing computes further key reduction. A Minimum Key Spacing value of 10 for the head track ensures that no two keys are closer than 10 frames for this track.
1765
1766
Chapter 21
|
character studio 3 MAXScript Extensions
Set All: Force all tracks to the values set in these fields. Higher values here can determine how much key reduction is possible while preserving the original motion. Filter: Clear to prevent filtering of the motion capture data into a track. If this is cleared, there will be no key reduction for the track. mocap.allTol
Float
Default: 0.0
Integer
Default: 3
mocap.allFilter
Boolean
Default: False
mocap.horzTol
Float
Default: 1.0
Integer
Default: 3
mocap.horzFilter
Boolean
Default: True
mocap.rotTol
Float
Default: 1.0
Integer
Default: 3
mocap.rotFilter
Boolean
Default: True
mocap.vertTol
Float
Default: 1.0
Integer
Default: 4
mocap.vertFilter
Boolean
Default: True
mocap.pelvisTol
Float
Default: 6.0
-- range: 0+ mocap.allSpacing -- range: 0+
-- range: 0+ mocap.horzSpacing -- range: 0+
-- range: 0+ mocap.rotSpacing -- range: 0+
-- range: 0+ mocap.vertSpacing -- range: 0+
-- range: 0+
BipedFSKey : MAXObject
mocap.pelvisSpacing
Integer
Default: 3
mocap.pelvisFilter
Boolean
Default: True
mocap.spineTol
Float
Default: 6.0
Integer
Default: 3
mocap.spineFilter
Boolean
Default: True
mocap.neckTol
Float
Default: 6.0
Integer
Default: 3
mocap.neckFilter
Boolean
Default: True
mocap.leftArmTol
Float
Default: 6.0
Integer
Default: 3
mocap.leftArmFilter
Boolean
Default: True
mocap.rightArmTol
Float
Default: 6.0
Integer
Default: 3
mocap.rightArmFilter
Boolean
Default: True
mocap.leftLegTol
Float
Default: 6.0
-- range: 0+
-- range: 0+ mocap.spineSpacing -- range: 0+
-- range: 0+ mocap.neckSpacing -- range: 0+
-- range: 0+ mocap.leftArmSpacing -- range: 0+
-- range: 0+ mocap.rightArmSpacing -- range: 0+
-- range: 0+
1767
1768
Chapter 21
|
character studio 3 MAXScript Extensions
mocap.leftLegSpacing
Integer
Default: 3
mocap.leftLegFilter
Boolean
Default: True
mocap.rightLegTol
Float
Default: 6.0
Integer
Default: 3
mocap.rightLegFilter
Boolean
Default: True
mocap.tailTol
Float
Default: 6.0
Integer
Default: 3
Boolean
Default: True
-- range: 0+
-- range: 0+ mocap.rightLegSpacing -- range: 0+
-- range: 0+ mocap.tailSpacing -- range: 0+ mocap.tailFilter
-- Limb orientation Angle: Move the knee or Elbow position to create the biped joint key. Point: Rotate the shoulder-elbow-wrist or hip-knee-ankle to create the biped joint key. Auto: Auto reads exact hand and foot positions from the motion capture data, character studio then places the knees and elbows in a natural position. For marker files involving running and walking, this option can clean up the data nearly instantly, regardless of how many markers were used (and where they were placed). mocap.kneeOrient
Integer
Default: 0
0 - angle 1 - point 2 - auto
The biped knee hinge joints are perpendicular to the triangles formed by the hip-kneeankle. Resolve errors in the motion capture data that break this rule by using either the angle or point method.
BipedFSKey : MAXObject
mocap.elbowOrient
Integer
Default: 0
0 - angle 1 - point 2 - auto
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
Integer
Default: 0
0 - angle 1 - auto
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
Integer
Default: 0
0 - angle 1 - auto
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)
String
Default: ““
-- figure
A .fig file containing changes made to the biped scale while in Talent Figure mode. mocap.useTalentFigStrucFile
Boolean
Default: False
Turn on useTalentFigStrucFile to use the file whose string is defined in mocap.talentFigStrucFile. mocap.talentPoseAdjFile adjustment file (.cal)
String
Default: ““
-- pose
A .cal file containing changes made to the biped while in Adjust Talent Pose mode. mocap.useTalentPoseAdjFile
Boolean
Default: False
Turn on useTalentPoseAdjFile to use the file whose string is defined in mocap. talentPoseAdjFile.
1769
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
Boolean
Default: False
When set to true, use the file defined in mocap.markerNameFile. mocap.jointNameFile marker name file (.mnm)
String
Default: ““
-- bvh
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
Boolean Boolean
Default: False Default: False
mocap.dispPropMarkers mocap.dispUnKnownMarkers
Boolean Boolean
Default: False Default: False
-- Load Save Methods mocap.loadParameters mocap.saveParameters
Load/Save a motion capture parameter (.MOC) file
Crowd : helper
Crowds Crowd : helper Constructor: crowd ...
Properties: .simStart
Integer
Default: 0
Integer
Default: 0
Integer
Default: 100
The first frame of the simulation. .solveStart
The frame at which you begin solving. .solveEnd
Specifies the last frame considered for the solution. .deleteKeys
Boolean
Default: False
When true, Crowd deletes the keys of active delegates in the range over which the solution takes place. .saveNthPos
Integer
Default: 1
Saves every nth position frame after the solution. .saveNthRot
Integer
Default: 1
Saves every nth rotation frame after the solution. .flashing Hilite_Delegates_During_Assignments .vectorScale
Boolean
Default: True
Float
Default: 1.0
Alias:
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. .useScript
Boolean
Default: False
When true, Crowd executes a script at each frame of the solution. .functionName Script_Context_Name
String
Default: “PerFrameFn” Alias:
The name of the function to be executed. This name must also be specified in the script. .script .update Update_Display_During_Solve
String Boolean
Default: Undefined Default: True Alias:
When true, motion produced during solution of a crowd simulation appears in the viewports. .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.
1771
1772
Chapter 21
|
character studio 3 MAXScript Extensions
.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. .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. .backtracking
Boolean
Default: False
Turns on backtracking functionality when solving a crowd simulation that uses bipeds. When Backtracking is on during the solution, in the case of an impending collision between bipeds, the Crowd system will back up the simulation to the beginning of the current clip, and then try a different traversal of the lower-priority delegate/biped’s motion flow graph. If necessary, the system will back up two or more clips. .showCollisions ClearColl
Boolean
Default: False
Alias:
When true the delegates that collide are highlighted in the collision color. .whenToShowCollisions
Integer
Default: 0
0 – only during collisions: Colliding delegates are highlighted only in frames in which they actually collide. 1 – always: Colliding delegates are highlighted in frames in which they collide and all subsequent frames. .collisionColor
Color
Default: (color 255 0 0)
The color swatch indicates the color used to highlight colliding delegates. .IconSize .behaviors
Float Default: 0.0 ArrayParameter Default: #()
Array of Behavior objects .teams
ArrayParameter Default: #()
Array of Team objects .assignments .cogcontrols Cognitive_Controllers
ArrayParameter Default: #() ArrayParameter Default: #()
Alias:
CogControl : MAXObject (p. 1791) .scatter
MAXObject
Default: Scatter_Parameters
CrowdScatter: (p. 1778) .objAssoc MAXRefTarg Object_Delegate_Associations_Parameters
Default: ObjAssoc
Display the dialog to link any number of delegate-object pairs.
Alias:
Delegate : Helper
.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 .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: .width
Float
Default: 0.0
-- world units
Float
Default: 0.0
-- world units
Float
Default: 0.0
-- world units
Color
Default: (color 0 0 0)
The width of the Delegate object. .depth
The depth of the Delegate object. .height
The height of the Delegate object. .velocityColor
When showVelocity is true, uses the specified color to draw a vector in the delegate’s center during the simulation solution. The vector length indicates the delegate’s relative speed. .active
Boolean
Default: True
The delegate object is subject to control by a Crowd object. .showForces
Boolean
Default: True
The forces being applied to a delegate by any applicable behaviors are drawn as vectors whose length indicate the extent of the forces. For example, if the delegate is affected by a Space Warp behavior and a Wander behavior, the vectors (using default colors) are yellow and blue-green, respectively. These vectors are visible only during solution of the crowd simulation.
1773
1774
Chapter 21
|
character studio 3 MAXScript Extensions
.showVelocity
Boolean
Default: False
Uses the Velocity Color (see above) to draw a vector whose length depicts the delegate’s relative speed. This vector is visible only during solution of the crowd simulation. .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. .xyConstrain
Boolean
Default: True
The delegate remains at its initial height (position on the world XY axis) throughout the simulation. When off, the delegate’s height can change during the simulation, for example when seeking an object at a different height. .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. .averageSpeed world units
Float
Default: 5.0
-- animatable;
Specifies the delegate’s baseline velocity in 3ds max units (or the current unit type) per second. This can be modified during the simulation by a variety of factors, such as a linked biped’s built-in speed and Deviation settings in a behavior. .maxAccel world units
Float
Default: 0.1
-- animatable;
Multiplied times Average Speed to determine the maximum acceleration. .turnDecel Alias: Turn_Deceleration_Weight
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 delegate’s speed to get 8 units per second halfway into the turn. At the full turn (30 degrees), the delegate travels at 6 units per second.
Delegate : Helper
.turnDecelAngle Alias: Turn_Deceleration_Angle
Float
Default: 10.0
-- animatable;
Specifies the turn angle at which Decel Weight’s full slowdown effect is applied. If the current turn angle is less than At Turn Angle, the algorithm divides the latter by the former, and then divides the Decel Weight setting by the result to derive the effective decel weight. .inclineDecel Alias: Incline_Deceleration_Weight
Float
Default: 0.1
-- animatable;
Specifies how much the delegate should slow down when moving at an upward slant. .inclineDecelAngle Alias: Incline_Deceleration_Angle
Float
Default: 90.0
-- animatable;
Specifies the upward slant angle at which Decel Weight’s full slowdown effect is applied. .declineAccel Alias: Decline_Acceleration_Weight
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. .declineAccelAngle Alias: Decline_Acceleration_Angle
Float
Default: 90.0
-- animatable;
Specifies the downward slant angle at which Accel Weight’s full speedup effect is applied. .maxTurnVel Alias: Max_Turn_Velocity
Float
Default: 30.0
-- animatable;
Specifies the maximum number of degrees a delegate can turn. .maxTurnAccel Alias: Max_Turn_Acceleration
Float
Default: 3.0
-- animatable;
Specifies how much the delegate’s turn angle can change per frame. If this is not small, the delegate’s direction might jerk around. It would be allowed to turn suddenly, rather than smoothly. .maxIncline Alias: Max_Incline_Velocity
Float
Default: 90.0
-- animatable;
Specifies the maximum number of degrees a delegate can turn upward per frame. .maxDecline Alias: Max_Decline_Velocity
Float
Default: 90.0
-- animatable;
Specifies the maximum number of degrees a delegate can turn downward per frame. .maxBank
Float
Default: 30.0
-- animatable
Specifies the maximum number of degrees a delegate can bank. .maxBankVel Alias: Max_Bank_Velocity
Float
Default: 3.0
Specifies how much the delegate’s bank angle can change per frame.
-- animatable;
1775
1776
Chapter 21
|
character studio 3 MAXScript Extensions
.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. .useBiped
Boolean
Default: False
When true, the delegate is associated with a biped. .biped
Node
Default: Undefined
The biped with which the delegate is associated. .startFrame
Integer
Default: 0
The frame at which the associated biped’s first clip will begin to play. .priority
Integer
Default: 0
Sets the delegate priority, which determines the order of solution in biped/delegate simulations. .s
Integer
Default: 0
0 – First clip of current script 1 – Random start clip .duration
Integer
Default: 0
The number of frames the delegate has been in the current state. .behaviors
ArrayParameter
Default: #()
The behaviors property contains valid values only during a solve. Contains the behaviors being used during the solve. .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. .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. .randID
Integer
Default: 0
A possibly non-unique identifier whose purpose is to be used by behaviors as part of it’s seed calculation. If more than one delegate has the the same randId then they should have the same random behavior. By defualt, crowd creates unique randIds. .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
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>
Returns the normalized velocity of the delegate at the start of the crowd simulation as a Point3 value. Thus the 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>
Returns a ‘1’ if the delegate is active for a particular crowd assignment at the time specified, if not it returns a ‘0’. The 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>
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. is a color value. boolean value. Whether or not to scale the line display by the Crowd.vectorScale value. delegates.sphereDisplay <delegate_node> <position>
This function will draw a sphere at the position <position>, with a radius of size , and a color of . <position> is a point3 value, radius is a float and is a color value.
1777
1778
Chapter 21
|
character studio 3 MAXScript Extensions
delegates.bboxDisplay <delegate_node> <minPosition> <maxPosition>
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 is a color value. delegates.textDisplay <delegate_node> <position> <string>
This function will draw the text found in the <string> parameter at the position specified at <position>, with the color found in . <position> is a point3 value, is a color value, and <string> is a string value. delegates.simTransform <delegate>
Returns the delegate’s transformation matrix at the specified time as a Matrix3 value. This method returns valid values during a solve. Note: During a Solve, the simulation doesn’t set the delegate nodes’ position and rotation keys until the simulation stops. As such, accessing the delegate nodes’ position and rotation during the solve will return incorrect results. The position of a delegate during a solve can be accessed via the .simpos property. Delegates cannot be rendered, so the size of the Delegate object is primarily for use in scene setup and for determining bounding box extents.
See Also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
CrowdScatter: These properties correspond to the Scatter Objects dialog displayed by clicking the Scatter Objects icon. Clone Tab Properties: .cloneObject
Node
Default: Undefined
Integer
Default: 10
Integer
Default: 0
Object in the scene to be cloned. .numClones
The number of clones to be generated. .cloneType (0_copy__1_reference__2_instance)
Alias
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:
.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. .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: .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. .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. .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. .centerX
Float
Default: 0.0
Specifies the X value for the center of the distribution in world coordinates. .centerY
Float
Default: 0.0
Specifies the Y value for the center of the distribution in world coordinates. .centerZ
Float
Default: 0.0
Specifies the Z value for the center of the distribution in world coordinates. .radius
Float
Default: 10.0
Specifies the maximum distance from the center within which clones are to be positioned. .XYPlane
Boolean
Default: False
Specifies that clones are to be distributed on the world XY plane only, resulting in a disclike array.
1779
1780
Chapter 21
|
character studio 3 MAXScript Extensions
.childBbox Boolean Default: True Include_childrens__bounding_boxes_in_spacing_calculations
Alias:
When true, all of a hierarchical object’s sub-objects are considered when determining spacing. When false, only the selected object is considered. .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 object’s bounding sphere to determine how close objects can get. If Spacing is left at 1.0, the default, objects normally cannot be positioned within each others’ bounding spheres. If Spacing is set to 2.0, objects are separated by a distance equal to or greater than the size of the bounding sphere. .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: .forwardAxisSign
Boolean
Default: True
If true, the forward axis is in the positive direction. If false the forward axis is in the negative direction. .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. .UpAxisSign
Boolean
Default: True
If true the up axis is in the positive direction. If false the up axis is in the negative direction. .UpAxis
Integer
Default: 2
0-X 1-Y 2-Z Axis of the cloned objects points upward; this axis is aligned with the world Z axis. Note: You cannot specify the same axis as Local Forward and Local Up simultaneously. If you choose an axis for one that’s already chosen for the other, the software switches the other to a different axis.
CrowdScatter:
.lookFrom
Integer
Default: 0
0 - Look From Self 1 - Look From Selected Object Determines the direction from which the clones look. By default, each clone looks from its own position (Self), so that when several clones are looking at a single target, each is oriented differently. To orient each clone so that it’s parallel to an imaginary line between two objects (the “from” object and the “to” object), choose Selected Object and specify the object with the (None) button. .lookFromObject
Node
Default: Undefined
An object from which the clones are to look if lookFrom = 1. .LookTowards
Integer
Default: 0
0 - Look Toward Self 1 - Look Toward Selected Object Determines the direction toward which the scatter objects look. By default, each object retains its current orientation. .lookAtTarget
Node
Default: Undefined
An object toward which the clones are to look. .sideDeviation
Float
Default: 0.0
Sets a maximum deviation angle in degrees for the clones’ sideways orientation. If clones should look in an object’s general direction but may look at a spot to either side of the target, use Sideways Deviation to set the maximum amount by which they can deviate from the calculated angle. The actual deviation amount for each clone is calculated at random, based on the Deviation settings and the Rand Seed setting. Range=0.0 to 180.0. .upDownDeviation
Float
Default: 0.0
Sets a maximum deviation angle in degrees for the clones’ up/down orientation. If clones should look in an object’s general direction but may look at a spot above or below the target, use Up/Down Deviation to set the maximum amount by which they can deviate from the calculated angle. The actual deviation amount for each clone is calculated at random, based on the Deviation settings and the Rand Seed setting. Range=0.0 to 180.0. .rotationSeed
Integer
Default: 0
Specifies a seed value for randomizing the clones’ orientations, based on the Deviation settings. If a scene has more than one crowd, each should use a different seed to avoid having identical configurations. Scale Tab Properties: Contains options for scaling object clones. For each scaling axis you can specify alternative forward and up axes, plus a target object toward which the clones will point. In addition, you can specify a source object; when using both source and target objects, the clones are rotated so they’re parallel to the line between the two. .xScale
Float
Sets scaling on the X axis as a multiplier.
Default: 1.0
1781
1782
Chapter 21
|
character studio 3 MAXScript Extensions
.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. .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. .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. .yScale
Float
Default: 1.0
Float
Default: 0.0
Sets scaling on the Y axis as a multiplier. .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. .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 .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 .zScale
Float
Default: 1.0
Float
Default: 0.0
Sets scaling on the Z axis as a multiplier. .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. .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. .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. .scaleSeed
Integer
Default: 0
Specifies a seed value for randomizing the clones’ scales, based on the Deviation settings.
CrowdScatter:
All Ops Tab Properties: .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. .ComputePositions
Boolean
Default: False
When true and crowds.scatterall is called, the transforms are applied according to the settings in the Position panel. .ComputeRotations
Boolean
Default: False
When true and crowds.scatterall is called, the transforms are applied according to the settings in the Rotation panel. .ComputeScales
Boolean
Default: False
When true and crowds.scatterall is called, the transforms are applied according to the settings in the Scale panel. .IncPosSeed
Boolean
Default: False
When true, add 1 to the .positionSeed value, and redistributes the objects using the new random seed. .IncRotSeed
Boolean
Default: False
When true, add 1 to the .rotationSeed value, and redistributes the objects using the new random seed. .IncSclSeed
Boolean
Default: False
When true, add 1 to the .scaleSeed value, and redistributes the objects using the new random seed. .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. .objects
ArrayParameter Default: #()
-- node array
ArrayParameter Default: #()
-- node array
Array of linked Objects. .delegates
Array of linked delegates. .alignScale
Boolean
Default: True
When true, Align Objects with Delegates sets each object’s absolute scaling factor to that of its corresponding delegates. This is useful if, for example, you’ve randomized delegates’ sizes with the Scatter Objects Scale panel, and want the associated objects to match.
1783
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. .objects Alias: Objects_to_Smooth
ArrayParameter Default: #()
-- node array;
Specify which objects’ positions and/or rotations to smooth. .filterDelegates Filter_Delegate_Selection
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. .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. .from smooth_from_frame
Integer
Default: 0
Alias:
When Animation Segment is chosen, specifies the first animation frame for smoothing. .to smooth_to_frame
Integer
Default: 0
Alias:
When Animation Segment is chosen, specifies the last animation frame for smoothing. .positions Smooth_positions
Boolean
Default: True
Alias:
When true, selected objects’ animation paths generated via the simulation are smoothed after the simulation has finished. .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: .team
CrowdTeam
Default: Undefined
Node
Default: Undefined
A named group of delegates. .delegate
A delegate object. See the CrowdDelegate : Helper (p. 1773) topic. .behavior
MAXObject
One of the Crowd Behavior (p. 1792) classes.
Default: Undefined
CrowdTeam : ReferenceTarget
.cogcontrol CognitiveController
CogControl
Default: Undefined
Alias:
A cognitive controller. See CogControl:MAXObject (p. 1791) for more details. .weight animatable
Float
Default: 1.0
--
The relative effect of the assigned behavior or cognitive controller. The higher an assignment’s weight setting is than others’, the more effect it will have. This setting is animatable. Range=0.0 to 1.0. .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: .name
String
Default: “CrowdTeam”
The default team name is Team followed by number one more than the last added team. .members of Delegate nodes
Participants of the current team.
ArrayParameter Default: #()
-- array
1785
1786
Chapter 21
|
character studio 3 MAXScript Extensions
Notes: You can perform the following MAXScript operations deleteitem <array> <array> = #(item,item...) <array> = append <array>
on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations. .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: .name
String
Default: “State”
The name of the state. .behaviors behaviors
ArrayParameter Default: #() -- array of
See Notes below. The names of all behaviors associated with the state. .weights
ArrayParameter Default: #() -- array of floats
See Notes below. Specifies the selected behavior’s weight. The higher the weight in relation to other behaviors’ weights, the more evident the results of the behavior in the state. Default=1.0. Range=0.0 to 1.0. .transitions CrowdTransition objects
ArrayParameter Default: #() -- array of
See Notes below. Notes: You can perform the following MAXScript operations: deleteitem <array> <array> = #(item,item...)
CrowdTransition : MAXObject
<array> = append <array>
on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations. .behaviors .weights .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: .priority
Integer
Default: 0
Integer
Default: 25
Sets the transition’s priority. .duration
The number of frames the software takes to affect the transition between states. .easeIn
Float
Default: 0.5
Float
Default: 0.5
String
Default: “transFunc”
Ease in value for the source clip. .easeOut
Ease out value for the destination clip. .functionName Script_Context_Name
Alias:
The name of the MAXScript conditional that specifies when/how the transition is to occur. .script .from FromState
String CrowdState
The state that the transition originated from.
Default: Undefined Default: Undefined
Alias:
1787
1788
Chapter 21
|
character studio 3 MAXScript Extensions
.to ToState
CrowdState
Default: Undefined
Alias:
The state that the transition is destined for. Notes: The .functionName value must match the name of the function defined in .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 .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 .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
Equivalent to clicking Solve in the crowd’s Solve rollout. .solve starts the solving, based on all other current crowd parameter settings. crowds.genclones
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
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
crowds.genrotations
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
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
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
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
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
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
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
Equivalent to clicking Proximity to a Grid/Assign in the Priority rollout. Assigns priorities to the delegates specified in .delegates based on their distance from the grid specified in .grid. crowds.assignObjectProximityPriorities
Equivalent to clicking Proximity to an Object/Assign in the Priority rollout. Assigns priorities to the delegates specified in .delegates based on their distance from the object specified in .object. crowds.assignRandomPriorities
Equivalent to clicking Assign Random Priorities in the Priority rollout. Assigns random priorities to the delegates specified in .delegates. crowds.assignUniquePriorities
Equivalent to clicking Make Priorities Unique in the Priority rollout. Ensures that the priorities of the delegates specified in .delegates are unique. If two delegates share the same priority, one of them will be given a new priority.
1789
1790
Chapter 21
|
character studio 3 MAXScript Extensions
crowds.incrementPriorities
Equivalent to clicking Increment Priorities in the Priority rollout. Increments the priorities of the delegates specified in .delegates by the value in .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> <array> = #(item,item...) <array> = append <array>
on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations. .behaviors .teams .assignments .cogcontrols .ObjectsToScatter .objects .delegates .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 it’s a strange thing to do and one probably should not do it.
CogControl : MAXObject
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: .name
String
Default: “ CognitiveControl”
CrowdState
Default: Undefined
The name of the state diagram. .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. .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> <array> = #(item,item...) <array> = append <array>
on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations. .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)
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 .start .delegates
Integer
Default: 0
ArrayParameter Default: #()
--
.object
Node
Default: Undefined
.grid
Node
Default: Undefined
.increment
Integer
Default: 0
.showPriorities
Boolean
Default: False
See Also Crowd : helper (p. 1771)
Crowd Behaviors Avoid_Behavior : MAXObject (p. 1793) Orientation_Behavior : MAXObject (p. 1794) Path_Follow_Behavior : MAXObject (p. 1796) Repel_Behavior : MAXObject (p. 1798) Scripted_Behavior : MAXObject (p. 1799) Seek_Behavior : MAXObject (p. 1807) Space_Warp_Behavior: MAXObject (p. 1809) Speed_Vary_Behavior : MAXObject (p. 1809) Surface_Arrive_Behavior : MAXObject (p. 1811) Surface_Follow_Behavior : MAXObject (p. 1814) Wall_Repel_Behavior : MAXObject (p. 1816) Wall_Seek_Behavior : MAXObject (p. 1817) Wander_Behavior : MAXObject (p. 1819)
node array
Avoid_Behavior : MAXObject
Avoid_Behavior : MAXObject Constructor: Avoid_Behavior ... AvoidBehavior ...
Properties: .name .obstacles
String
Default: “Avoid”
ArrayParameter Default: #() -- node array
Any object or objects that the delegates must keep away from. See Notes below. .lookAhead
Integer
Default: 30
-- animatable
The number of frames in advance of the current frame that the software looks for potential collisions. .hardRadius
Float
Default: 1.0 -- animatable
Distance from center of the delegate(s), where no penetration should occur. .showHardRadius
Boolean
Default: False
Enables display of a wireframe sphere that depicts the extent of the .hardRadius setting. .detourAngle
Float
Default: 360.0
-- animatable
Maximum necessary turning angle relative to the direction of delegate’s goal that the delegate will steer to avoid rather than slow down and wait. .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. .repelStrength
Float
Default: 0.2 -- animatable
Determines the strength of the repelling force; higher values result in greater repulsion force. .repelRadius
Float
Default: 3.0
Distance from hard radius of delegate where “repel” avoidance is sensed and carried out. .repelFalloff
Float
Default: 3.0 -- animatable
Higher values cause the repel to fall off to zero more rapidly with distance, thus focusing its effect closer to the delegate’s hard radius. .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. .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 delegate’s hard radius. .showRepelRadius
Boolean
Default: False
When true, displays a wireframe sphere that depicts the extent of the .repelRadius setting.
1793
1794
Chapter 21
|
character studio 3 MAXScript Extensions
.showPotentialCols
Boolean
Default: False
When true, displays a green line from the delegate to the location of a potential collision. .showRepelActivity
Boolean
Default: False
When true, displays a white line between the delegate and target when the repel force is in effect. .showLookAhead
Boolean
Default: False
When true, displays a sphere that shows the current distance used to check for potential collisions. .forceColor
Color
Default: (color 255 0 0)
Sets the color used to draw the Avoid force vector during the solution. .displayForce
Boolean
Default: True
When true, force exerted on the delegate(s) by the Avoid behavior is drawn in the viewports as a vector during the simulation solution. Notes: You can perform the following MAXScript operations: deleteitem <array> <array> = #(item,item...) <array> = append <array>
on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations. .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: .name
String
.headingRelative Boolean
Default: “Orientation” Default: False
Orientation_Behavior : MAXObject
.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. .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. .maxHeadingVel maxHeadingVelocity – animatable
Float
Default: 180.0 Alias:
Specifies how much the delegate’s heading can change per frame. This controls angular acceleration and deceleration. .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. .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. .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. .maxpitchVel maxPitchVelocity – animatable
Float
Default: 1.0 Alias:
Specifies how much the delegate’s pitch can change per frame. This controls angular acceleration and deceleration. .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. .maxbank
Float
Default: 30.0 – animatable
The maximum number of degrees the delegate can bank. .maxbankAccel MaxBank_Change – animatable
Float
Default: 3.0 Alias:
The maximum number of degrees the delegate’s bank angle can change per frame. This controls angular acceleration and deceleration. .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.
1795
1796
Chapter 21
|
character studio 3 MAXScript Extensions
Notes: If this behavior is active, it controls the orientation of the delegate by allowing the animator to specify limits and responsiveness on the pitch and heading of the object. The animator can limit the min and max values, the rate, and can also set a ‘response’ value which controls how quickly the pitch or heading follows the direction the object is moving in. A value of 1.0 means it’s responsive, and will point in the direction the delegate is moving (within the limits), while a lower value means that it is less responsive. It also calculates the roll, which is done using the same parameters that the default behavior does.
See also Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Path_Follow_Behavior : MAXObject Constructor: Path_Follow_Behavior ... PathFollowBehavior ...
Properties: <path_follow_behavior>.name
String
Default: “Path Follow”
<path_follow_behavior>.path
Node
Default: Undefined
A path object. Suitable path objects include splines and NURBS curves. If a path object contains more than one spline or curve, character studio uses the lowest-numbered element (usually the earliest created one). <path_follow_behavior>.radius 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
<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 isn’t closed. If Beginning of Path or End of Path is chosen, it returns to the path’s start or end point each time it finishes traversing the path. If Nearest Point is chosen, it returns to an arbitrary point determined by its position and the path shape. 1 – Reverse: The delegate reverses direction at the end of the path. Use this choice to simulate a back-and-forth “patrol” behavior. 2 – Continue: The delegate continues moving in the same direction it faced at the end of the path until the simulation ends or it’s acted upon by another force or behavior. <path_follow_behavior>.seed
Integer
Default: 1 --
animatable
Specifies a seed value for randomizing Awareness. <path_follow_behavior>.forceColor
Color
Default: (color 0 0 255)
The color used to draw the Path Follow force vector during the solution. <path_follow_behavior>.displayForce
Boolean
Default: True
When true, force exerted on the delegate(s) by the Path Follow behavior is drawn in the viewports as a vector during the simulation solution. <path_follow_behavior>.targetColor
Color
Default: (color 0 0 127.5)
Sets the color used to draw the target icon. <path_follow_behavior>.displayTarget
Boolean
Default: True
Enables display of the target icon, which appears during the solution when a new interim goal is calculated for the delegate. <path_follow_behavior>.targetScale
The overall size of the target icon.
Float
Default: 5.0 --
animatable
1797
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: .name .repulsionSources
String
Default: “Repel”
ArrayParameter Default: #() -- node array
See Notes below .targetComp
Integer
Default: 0
0 – Closest Source: Each delegate is repelled by the closest of the assigned sources. Use this to have delegates assigned a single Repel behavior move away from sources in different directions. 1 – Average of Sources: All delegates head to a common point determined by averaging all sources’ locations. .repelMethod
Integer
Default: 0 -- animatable
0 – Angle: Applies a force to the delegate based on the angle between the delegate’s current direction and the direction it would need to take in order to be moving directly away from the source. If the behavior’s Weight is set to 1, the delegate will be given a force that points directly away from the source. If Weight is set to .5, the force will bisect the angle between its current direction and the direction opposite that of the source. 1 – Force: Always applies a force directly away from the source, but at different magnitudes. If the behavior’s Weight is 1, the magnitude of the force will be the average speed. If the Weight is .5, the magnitude of the force will be half the average speed. .useRadii
Boolean
Default: True
When true, the behavior applies only to delegates closer to the target than the Outer Distance value. .innerRadius
Float
Default: 0.0
-- animatable
The distance from the target at which the force is applied at full strength. .outerRadius
Float
Default: 10.0 – animatable
The distance from the target at which the force begins to be applied. .falloff .forceColor
Float Color
The color used to draw the Repel force vector.
Default: 2.0 -- animatable Default: (color 255 0 255)
Scripted_Behavior : MAXObject
.showRadii
Boolean
Default: True
When true, the radii are displayed when the force is active. .displayForce
Boolean
Default: True
When true, force exerted on the delegate(s) by the Repel behavior is drawn in the viewports as a vector during the simulation solution. If Use Radii is turned on, the radii are also displayed when the force is active. Notes: You can perform the following MAXScript operations: deleteitem <array> <array> = #(item,item...) <array> = append <array>
on all of the properties containing an ArrayParamater of objects listed below. You can also undo/redo these operations. .repulsionSources
The following MAXScript operations will cause Crowd to fail, either right away or later: NEVER set a Crowd/Behavior ArrayParameter element to undefined.
See Also Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Scripted_Behavior : MAXObject Introduction to the Crowd System The crowd system works by assembling all of the force vectors (p. 1677) and speeds for a delegate from its active force behaviors. Then based upon the delegate’s motion parameters, these force vectors (p. 1677) and speeds are averaged and integrated to create a velocity for the delegate. This velocity may then be modified if the delegate has an active constraint behavior or if it has an active default Avoidance behavior. After the velocity is set, if there is an active orientation behavior, it is used to set the orientation of the delegate, otherwise the orientation is calculated from the default delegate parameters. Finally, the velocity is integrated and a new position is calculated. The new position of the delegate isn’t set until after all of the forces are calculated for all of the behaviors. For a biped crowd, bipeds work off of goals and not forces when determining which direction they should go in. So, in order to create a force behavior that will work with a Biped, a goal position must be specified. No forces need to be integrated into velocities because the movement of the Biped isn’t based upon calculating velocities but rather by selecting clips found in the motion flow graph.
1799
1800
Chapter 21
|
character studio 3 MAXScript Extensions
Constructor: Scripted_Behavior ... ScriptedBehavior ...
Properties: <scripted_behavior>.name
String
Default: “Scripted”
<Scripted_Behavior>.scriptContextName Script_Context_Name
String
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 want’s the delegate to go in, and in some cases the speed it should be traveling at and the goal at which it is trying to reach. Constraint: Behaviors of this type restrict the position and velocity of a delegate, for example, SurfaceFollow. Constraint behaviors set the velocity and sometimes may even change the delegate’s position, in order to meet the constraint. You may only have one active constraint behavior per delegate per frame. Orientation: Behaviors of this type affect only the orientation of the delegates, for example Orientation. These behaviors don’t work with forces but instead return an orientation that the delegate should be at, represented by a quaternion. Any active orientation behavior will override the default orientation of the delegate. The velocity determines the default orientation. Like a constraint behavior, you may only have one active orientation behavior per delegate per frame. Note: Though there are no avoid behavior types, a force or constraint behavior may be used to create an avoidance behavior. We do recommend though that the default Avoidance behavior be used due to the fact that it is well integrated into the crowd solution pipeline. <scripted_behavior>.script : string
Scripted_Behavior : MAXObject
Edit MaxScript: This button “Edit MaxScript”, in the Scripted Behavior Rollout, opens a MAXScript editor window that can be used to enter a scripted behavior script. The editor window is similar to other MaxScript editor window but is slightly customized for scripted behaviors.
The following elements in the File Menu work differently: New: disabled since only one editor per scripted behavior can be open at any time Open: opens a file in the existing editor window. Any existing text will be lost. Evaluate: evaluates the script and saves it into the behavior’s paramblock Close: saves into the behavior’s paramblock and closes the editor if no errors found
1801
1802
Chapter 21
|
character studio 3 MAXScript Extensions
Scripted Behavior Syntax: The scripted behavior script is implemented by defining a set of event handlers that get called by the crowd system when solving the simulation. The event handlers are automatically enclosed into a hidden MAXScript context. The name of the context is taken from the dialog’s Script Context Name text box or its equivalent .scriptContextName. Event Handlers for Scripted Behaviors: on execute do <expr>
Called whenever the script is evaluated. All initializing should be done here. on setupDelegates <delegates> 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. 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 do <expr> the current behavior 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> do <expr> <delegate> the delegate node the behavior is assigned to the current behavior 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
on initAtThisTime
This function is called for each behavior at the beginning of the frame. on applyForce <delegate> <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 the current behavior current time of the simulation is the number of sub samples required per frame. this value is true/false depending on the .update and .updateFrequency, as well as the current frame. If it is true, you should display any helper imagery you want using the display functions available from the delegates structure. For instance, most behaviors display their force if this is true, and pathfollow also displays its target. The delegates.lineDisplay (p. 1773),.sphereDisplay, .bboxDisplay, and .textDisplay are all functions which can be used to draw a graphic primitive for a particular delegate when the crowd simulation is being solved. Please see Viewport Drawing Methods for additional viewport drawing methods.
Note: The graphic window functions gw.* described in Viewport Drawing Methods will not display correctly or at all while in Step Solve. <weight> this behavior’s weight on the delegate
The event handler should return an array of the following type: #(, <point3_force>, <point3_goal>, , <Speed_Weight_at_the_Goal>) sum of any of the following values: 0 – the return value is not used by the crowd system 1 - only force is affected 2 - only goal is affected 4 - only speed is affected
For example, a value of 5, (1+4), indicates that the force and speed are affected. <point3_force> the force vector (p. 1677). It should be unit normalized and then multiplied by the delegate’s average speed. Modify this value, greater or less, to make the force stronger or weaker. <point3_goal> the goal position in world space.
1803
1804
Chapter 21
|
character studio 3 MAXScript Extensions
the net speed of the delegate. This value should be normalized to the average speed of the delegate. A value of 1.0 means go at the average speed. <Speed_Weight_at_the_Goal> will represent the speed that the delegate should be at when it reaches its goal. This value should be normalized by the average speed of the delegate, so that a value of 1.0 equal it’s average speed.
Notes: Any behavior that sets the with a speed affected setting should ensure that a valid value is set for and <Speed_Weight_at_the_Goal>. Note that a goal doesn’t need to be set for this to work. This is how the ‘SpeedVary’ behavior works with Biped. It doesn’t explicitly set a goal but still modifies the <Speed_Weight_at_the_Goal> value. on constraint <delegate> <speed> <pos> do <expr>
If the behavior type, <Scripted_Behavior>.type, is Constraint, this handler is called at least once every frame to constrain the delegate. The constraint behavior will override any other force behavior, the Avoidance Behavior, plus it will override any acceleration limits, speed limits etc. So it should be used with caution in a simulation. The constraint behavior constrains the position that the delegate is moving towards by changing the current position that the delegate is already at, it’s current velocity, and it’s current speed. These values are combined to get the next position, Next_position = Current_Position +Normalized(vel) * Speed. Changing the current position doesn’t actually change where it is at though, it just changes the position that is used to calculate it’s new position. This design allows the constraint to make the objects velocity change abruptly and keep its speed, thus conserving the energy of the delegate. <delegate> the delegate node the behavior is assigned to the current behavior current time of the simulation is the number of sub samples required per frame. this value is true/false depending on the .update and .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. whether or not this is the final time this behavior will be called during the current frame.
Scripted_Behavior : MAXObject
Note: In order to handle constraints working correctly within the avoidance system the constraint behavior may be called more than once per frame. When the passed in parameter, finalSet, is true, it will be the last time the constraint function is called for that frame. Currently the constraint behavior’s “on constraint” event handler is called twice per frame. The first call occurs before an existing Avoid_Behavior with the passed in parameter finalSet having a value of false. The second call occurs, after the delegate’s limits and Avoid_Behavior are applied with the passed in parameter finalSet having a value of true. This evaluation order is done so that the delegate’s limits and the Avoid_Behavior can affect the changes that the constraint performs. The second call is made to make sure that the constraint is still being met. One reason to check the state of finalSet is if internally something was cached and you didn’t want it to change. For example, the Surface_Follow constraint behavior keeps track of which triangle it’s on and the barycentric coordinates of where it’s at. The simulation will not change these values until finalSet is true. the current velocity of the delegate at this frame. <speed> the current speed of the delegate at this frame. <pos> the current position of the delegate at this frame.
Note: After the last delegate’s “on constraint” has executed for the last frame of the simulation, “on setupDelegates delegates behavior do” will be called with an empty array “#() ReferenceTarget:Scripted_Behavior”. This is guarenteed and can be used by written constraint behaviors to clear out any internal caches. The event handler should return an array of the following type: #(, <point3_velocity>, <point3_pos>, <point3_goal>, ) sum of any of the following values: 0 – the return value is not used by the crowd system 1 – the return value is used by the crowd system <point3_velocity> the velocity. <point3_pos> the modified current position that is used to calculate it’s new position. In order to meet a constraint this behavior is allowed to modify the current position of a delegate. <point3_goal> the goal position in world space. the net speed of the delegate. This value should be normalized to the average speed of the delegate. on orient <delegate> do <expr>
1805
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 the current 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: #(, quat_orientation) 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 the orientation of the delegate in quaternions.
Notes: The purpose of passing the crowd delegate and behavior to all of the event handlers is that you can call persisted global, saved with scene, MAXScript functions that work for more than one crowd simulation. Example: The following is a pair of scripted behaviors called “FormationConstraint” and “FormationOrientation”. The “FormationOrientation” will constrain the orientation to a fixed location, in this case based on the current delegate’s orientation found at its first rotation keyframe. The entire scripted orientation behavior can be implemented with one event handler: on orient delegate behavior time vel do ( #(1,delegate.rotation.keys[1].value as quat ) )
The “FormationConstraint” keeps a team of delegates in a given positional formation while maintaining the pace and direction of a designated leader named “FormationLeader”. This is similar to a drum major and a marching band or like football blockers running in front of a running back who may dart in any direction. This person dictates how and where the formation will move. This “FormationLeader” is not using the scripted behavior. This behavior will affect both the position and orientation of the delegate. The orientation is being calculated by the delegate’s velocity, and the velocity is being set correctly. on execute do ( print “ executed” ) on constraint delegate behavior time numsubsamples displayHelpers finalSet vel speed pos do ( leader_velocity = delegates.velocity $TheFormationLeader Normalized_Leader_Velocity = normalize (delegates.velocity $TheFormationLeader)
Seek_Behavior : MAXObject
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”
ArrayParameter Default: #()
--
node array
See Notes below. Specify the object or objects as a stationary or moving target for delegates. Delegates move toward the target during the crowd simulation while turning as necessary. <seek_behavior>.targetComp
Integer
Default: 0
0 – Closest Source Only: Each delegate seeks the closest of the assigned targets. Use this to have delegates assigned a single Seek behavior move in different directions. 1 – Average of Sources: All delegates head to a common point determined by averaging all targets’ locations.
1807
1808
Chapter 21
|
character studio 3 MAXScript Extensions
<seek_behavior>.seekMethod
Integer
Default: 0
--
animatable
0 – Angle: Applies a force to the delegate based on the angle between the delegate’s current direction and the direction it would need to take in order to be moving directly towards the goal. If the Weight of the Seek behavior is 1, the delegate will be given a force that points directly towards the goal. If it’s .5 it will bisect the angle between its current direction and the direction of the goal. 1 – Force: Applies a force in the direction of the goal always, but at different magnitudes. If the Weight of the Seek behavior is 1, the magnitude of the force will be the average speed. If the Weight of the Seek behavior is .5, the magnitude of the force will be half the average speed. <seek_behavior>.forceColor
Color
Default: (color 0 255 0)
The color used to draw the Seek force vector during the solution. <seek_behavior>.displayForce
Boolean
Default: True
When true, force exerted on the delegate(s) by the Seek behavior is drawn in the viewports as a vector during the simulation solution. <Seek_Behavior>.useRadii
Boolean
Default: False
When true, the Seek behavior applies only to delegates less than the Outer Radius distance from the target. <Seek_Behavior>.showRadii
Boolean
Default: True
When true, the radii are displayed when the force is active. <Seek_Behavior>.innerRadius
Float
Default: 0.0
--
animatable
--
animatable
--
animatable
The distance from the target at which Seek is applied at full strength. <Seek_Behavior>.outerRadius
Float
Default: 10.0
The distance from the target at which Seek begins to be applied. <Seek_Behavior>.falloff
Float
Default: 2.0
Notes: You can perform the following MAXScript operations: deleteitem <array> <array> = #(item,item...) <array> = append <array>
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
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
String Node
Default: “Space Warp” Default: Undefined
<space_warp_behavior>.forceColor
Color
Default: (color 255 255 0)
The color used to draw the Space Warp force vector during the solution. <space_warp_behavior>.displayForce
Boolean
Default: True
When true, force exerted on the delegate(s) by the Space Warp behavior is drawn in the viewports as a vector during the simulation solution.
See also Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Speed_Vary_Behavior : MAXObject Constructor: Speed_Vary_Behavior ... SpeedVaryBehavior ...
Properties: <speed_vary_behavior>.name
String
Default: “Speed Vary”
<speed_vary_behavior>.period
Integer
Default: 10
--
Specifies how many frames should elapse before a new speed is chosen.
animatable
1809
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 delegate’s calculated speed (Average Speed*Center) should vary. Each time a period ends, character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the calculated speed, and adds the result to the calculated speed. Range=0.0 to 99,999.0. <speed_vary_behavior>.seed Alias: Speed_Vary_Seed
Integer
Default: 1
--
animatable;
--
animatable;
Specifies a seed value for randomizing the Wander behavior. <speed_vary_behavior>.accelPeriod Alias: Acceleration_Period
Float
Default: 0.5
Specifies the rate at which the delegate’s speed should change. An acceleration of 1.0 means that the transition to the new speed will proceed as quickly as possible to its new speed, while a value of 0.0 means the transition will take the entire period. Range=0.0 to 1.0. <speed_vary_behavior>.accelDeviation Alias: Acceleration_Deviation
Float
Default: 0.5
--
animatable;
Specifies the maximum amount by which the delegate’s calculated speed (Average Speed*Center) should vary. Each time a period ends, character studio takes a random number between the negative and positive values of the Deviation setting, multiplies it by the calculated speed, and adds the result to the calculated speed. Range=0.0 to 99,999.0.
See also Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Surface_Arrive_Behavior : MAXObject
Surface_Arrive_Behavior : MAXObject Constructor: Surface_Arrive_Behavior ... SurfaceArriveBehavior ...
Properties: <Surface_Arrive_Behavior>.name <Surface_Arrive_Behavior>.surfaces array
String
Default: “Surface Arrive”
ArrayParameter Default: #()
-- node
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 delegate’s Max Accel setting that specifies the acceleration with which it will try to arrive. A value of 1.0 uses the full acceleration of the delegate. <Surface_Arrive_Behavior>.rateDeviation animatable
Float
Default: 0.0
--
Float
Default: 0.0
--
Adds a variation to the to the rate setting. <Surface_Arrive_Behavior>.speed animatable
The speed at which to arrive and relative to the speed of the target. <Surface_Arrive_Behavior>.speedDeviation animatable
Float
Default: 0.0
--
Float
Default: 1e+008
--
Adds a variation to the to the speed setting. <Surface_Arrive_Behavior>.distance animatable
The maximum radial distance from the target within which the behavior will be active. Until the delegate is within this radius, the behavior will have no influence. <Surface_Arrive_Behavior>.distanceDeviation animatable
Float
Default: 0.0
--
Float
Default: 0.0
--
Adds a variation to the to the distance setting. <Surface_Arrive_Behavior>.offset animatable
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.
1811
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 won’t overshoot when descending because its speed is too high and deceleration too low, compared to when it should start descending. <Surface_Arrive_Behavior>.descentstartDeviation Float 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
Float
Default: 0.0
--
Specify the final approach X value for the vector in world coordinates. <Surface_Arrive_Behavior>.yNormal animatable; Alias: Y_Normal
Float
Default: 0.0
--
Specify the final approach Y value for the vector in world coordinates. <Surface_Arrive_Behavior>.zNormal animatable; Alias: Z_Normal
Float
Default: 1.0
Specify the final approach Z value for the vector in world coordinates.
--
Surface_Arrive_Behavior : MAXObject
<Surface_Arrive_Behavior>.seed animatable
Integer
Default: 1
--
Affects the random numbers used to calculate the Deviation settings. <Surface_Arrive_Behavior>.targetColor
Color
Default: (color 0 0 127.5)
The color used to draw the target icon. <Surface_Arrive_Behavior>.displayTarget
Boolean
Default: True
When true, displays the target icon which appears during the solution when a new interim goal is calculated for the delegate. <Surface_Arrive_Behavior>.targetScale 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 isn’t active for that state, 0 means that the delegate is outside the distance radius and so isn’t arriving, 1 means that the delegate is in the process of arriving, and 2 means that the delegate has arrived. If ‘Disable After Arriving’ is TRUE, the delegates will never reach state 2. The main purpose of this funtion is so that the ‘State’ of a delegate as it arrives to a surface can be determined from MAXScript. It can be used for both the cognitive controller transitions as well as the script definable in MotionClips. See the ClipState Dialog and the Cognitive Controller topics in the character studio 3 online reference for more details. Track View > Global Tracks > Block Control > GlobalClip Properties > Synthesis dialog > State Tab > New State > Edit Properties > ClipState dialog Select a Crowd helper. > Modify panel > Global Clip Controllers rollout > New > Choose GlobalClip object. > Select object in list. > Edit > Synthesis dialog > State Tab > New State > Edit Properties > Clip State dialog Create panel > Helpers > Object Type rollout > Crowd > Setup rollout > Cognitive Controllers Select a Crowd object. > Modify panel > Setup rollout > Cognitive Controllers SurfaceArriveBhvr.getPos <Surface_Arrive_Behavior> <delegate_node>
Returns a Point3 value of the position that the delegate is arriving to at the time the function is called.
1813
1814
Chapter 21
|
character studio 3 MAXScript Extensions
Notes: You can perform the following MAXScript operations: deleteitem <array> <array> = #(item,item...) <array> = append <array>
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”
ArrayParameter Default: #()
--
node array
See Notes below. <Surface_Follow_Behavior>.useProjection Bolean
Default: False
When true, Surface Follow calculates delegate direction from the specified vector, rather than using the default. <Surface_Follow_Behavior>.xVector
Float
Default: 0.0
--
animatable
Specifies the x component of a vector using world coordinates. . Range=-1.0 to 1.0. <Surface_Follow_Behavior>.yVector
Float
Default: 0.0
--
animatable
Specifies the y component of a vector using world coordinates. . Range=-1.0 to 1.0. <Surface_Follow_Behavior>.zVector
Float
Default: 1.0
--
animatable
Specifies the z component of a vector using world coordinates. . Range=-1.0 to 1.0. <space_warp_behavior>.targetColor
Color
Default: (color 0 0 127.5)
Sets the color used to draw the Surface Follow during the solution. <space_warp_behavior>.displayTarget
Boolean
Default: True
When true, the interim goal for each delegate influenced by the Surface Follow behavior is drawn in the viewports as a wireframe sphere during the simulation solution.
Surface_Follow_Behavior : MAXObject
Notes: If the delegate starts out away from the surface to be followed then the target is most visible before the delegate reaches the surface where the target is positioned along the surface edge. While the delegate is actually following the surface, the target is usually coincident with the delegate because Surface follow sets a new destination only a frame or two ahead. <space_warp_behavior>.targetScale
Float
Default: 5.0
Specifies the overall size of the target icon. <Surface_Follow_Behavior>.offset
Float
Default: 0.0
-- animatable
Specifies the delegate’s distance above the surface, using the surface normal. <Surface_Follow_Behavior>.displayOffset Boolean Default: False When true, shows the .offset distance as lines emanating from each vertex in the surface
object, perpendicular to the surface. Notes: You can perform the following MAXScript operations: deleteitem <array> <array> = #(item,item...) <array> = append <array>
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)
1815
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
Set the repelling grid. <Wall_Repel_Behavior>.repelMethod
Integer
Default: 0
-- animatable
Determines whether delegate direction as influenced by the behavior is calculated by an angular method or a force method. 0 – Angle: Applies a force to the delegate based on the angle between the delegate’s current direction and the direction it would need to take in order to be moving directly away from the source. If the behavior’s Weight is set to 1 the delegate will be given a force that points directly away from the source. If Weight is set to .5, the force will bisect the angle between its current direction and the direction opposite that of the source. 1 – Force: Always applies a force directly away from the source, but at different magnitudes. If the behavior’s Weight is 1, the magnitude of the force will be the average speed. If the Weight is .5, the magnitude of the force will be half the average speed. <Wall_Repel_Behavior>.repelDirection
Integer
Default: 0
-- animatable
Determines whether the grid repels from its positive-axis side, its negative-axis side, or both. 0 – Positive Axis: The grid repels only from the positive-axis side. 1 – Negative Axis: The grid repels only from the negative-axis side. 2 – Both Axes: The grid repels from both sides. <Wall_Repel_Behavior>.useDistance
Boolean
Default: True
When true, the behavior applies only to delegates closer to the target than the outerRadius value. <Wall_Repel_Behavior>.innerDistance
Float
Default: 0.0
-- animatable
The distance from the target at which the force is applied at full strength. <Wall_Repel_Behavior>.outerDistance
Float
Default: 10.0
-- animatable
The distance from the target at which the force begins to be applied. <Wall_Repel_Behavior>.falloff
Float
Default: 2.0
<Wall_Repel_Behavior>.showDistance
Boolean
Default: True
-- animatable
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
<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
Color
Default: (color 255 0 255)
Sets the color used to draw the Wall Repel force during the solution. <Wall_Repel_Behavior>.displayForce
Boolean
Default: True
The force, when activated, is drawn in the viewports as a wireframe rectangle during the simulation solution.
See also Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Wall_Seek_Behavior : MAXObject Constructor: Wall_Seek_Behavior ... WallSeekBehavior ...
Properties: <Wall_Seek_Behavior>.name <Wall_Seek_Behavior>.seekGrids
String ArrayParameter
Default: “Wall Seek” Default: #()
--
node array
Default: 0
-- animatable
Set the repelling grid. <Wall_Seek_Behavior>.seekMethod
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 delegate’s current direction and the direction it would need to take in order to be moving directly toward the target. If the behavior’s Weight is set to 1, the delegate will be given a force that points directly away from the target. If Weight is set to .5, the force will bisect the angle between its current direction and the direction opposite that of the target. 1 – Force: Always applies a force directly toward the target. If the behavior’s Weight is 1, the magnitude of the force will be the average speed. If the Weight is .5, the magnitude of the force will be half the average speed.
1817
1818
Chapter 21
|
character studio 3 MAXScript Extensions
<Wall_Seek_Behavior>.seekDirection
Integer
Default: 0
-- animatable
Determines whether the grid attracts from its positive-axis side, its negative-axis side, or both. 0 – Positive Axis: The grid attracts only from the positive-axis side. 1 – Negative Axis: The grid attracts only from the negative-axis side. 2 – Both Axes: The grid attracts from both sides. <Wall_Seek_Behavior>.useDistance
Boolean
Default: True
When true, the behavior applies only to delegates closer to the target than the Outer Distance value. <Wall_Seek_Behavior>.innerDistance
Float
Default: 0.0
-- animatable
The distance from the target at which the force is applied at full strength. <Wall_Seek_Behavior>.outerDistance
Float
Default: 10.0
-- animatable
The distance from the target at which the force begins to be applied. <Wall_Seek_Behavior>.falloff
Float
Default: 2.0
<Wall_Seek_Behavior>.showDistance
Boolean
Default: True
<Wall_Seek_Behavior>.gridSpacing
Integer
Default: 500
<Wall_Seek_Behavior>.gridEnd End_force_at_grid_edges
Boolean
Default: True
-- animatable
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_Seek_Behavior>.forceColor
Color
Default: (color 255 0 255)
Sets the color used to draw the Seek force vector during the solution. <Wall_Seek_Behavior>.displayForce
Boolean
Default: True
When true, force exerted on the delegate(s) by the Seek behavior is drawn in the viewports as a vector during the simulation solution. If useRadii is turned on, the radii are also displayed when the force is active.
See also Crowd : Helper (p. 1771) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Wander_Behavior : MAXObject
Wander_Behavior : MAXObject Constructor: Wander_Behavior ... WanderBehavior ...
Properties: <wander_behavior>.name
String
Default: “Wander”
<wander_behavior>.period Alias: Wander_Period
Integer
Default: 10
--
animatable;
Specifies how many frames should elapse before a new direction is chosen. <wander_behavior>.periodDeviation Alias: Wander_Period_Deviation
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
Integer
Default: 1
--
animatable
Specifies a seed value for randomizing the Wander behavior. <wander_behavior>.forceColor
Color
Default: (color 0 255 255)
The color used to draw the Wander force vector during the solution. <wander_behavior>.displayForce
Boolean
Default: True
When true, force exerted on the delegate(s) by the Wander behavior is drawn in the viewports as a vector during the simulation solution.
1819
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(
const
StructDef Struct:
globalMotionClipOps.loadfile
Primitive
loadfile()
‘loadfile’ expects a GlobalMotionClip, then a filename for a “*.ant” GlobalMotionClip file to load. globalMotionClipOps.savefile
Primitive
savefile()
‘savefile’ expects a GlobalMotionClip, then a filename for the “*.ant” file to save. globalMotionClipOps.synthesize
Primitive
synthesize()
‘synthesize’ expects a GlobalMotionClip and will synthesize it. Note that the GlobalMotionClip objects are found under the GlobalTracks.Block_Control list controller. So to call savefile, one would call: GlobalMotionClipOps.savefile GlobalTracks.Block_Control.globalMotionClip__globalObject “globalObject.ant”‘
The following classes exist but are not supported. MotionClipSlaveRotation : RotationController {4306d06,97c6025} MotionClip : FloatController {e937ded,5a002ad2} MotionClipSlavePos : PositionController {18c22740,522802b9} ClipAssignerReferenceTarget : ReferenceTarget {2cb93ce2,33825f4} MotionClipSlaveFloat : FloatController {31822cdf,34c146b} Global_MotionClip : MasterBlockController {37d25755,278c6957} ClipState : ReferenceTarget {455d5a81,3dcb1dc2} ClipAssigner : ReferenceTarget {49f14ffa,33801afd} MasterMotionClip : MasterBlockController {532a2038,6acd39bf} MotionClipSlave_Point3 : Point3Controller {6c95514a,801b4f} MotionClipSlaveScale : ScaleController {71031345,770b4347} MotionClipFloatController : FloatController {7f016988,1f9f0342}
Vector_Field: SpacewarpObject
SpaceWarps Vector_Field: SpacewarpObject Constructor: Vector_Field ... VectorField ...
Properties: .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. .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. .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. .LenSegs Length_Segments
Integer
Default: 1
Alias:
Specify the resolution of the vector field lattice’s length segments. The greater the resolution, the higher the accuracy of the simulation. .WidSegs Width_Segments
Integer
Default: 1
Alias:
Specify the resolution of the vector field lattice’s width segments. The greater the resolution, the higher the accuracy of the simulation. .HgtSegs Height_Segments
Integer
Default: 1
Alias:
Specify the resolution of the vector field lattice’s height segments. The greater the resolution, the higher the accuracy of the simulation. .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. .showRange
Boolean
Default: True
Set on to display the volume about the obstacle object within which vectors are generated as an olive-colored wireframe. .showVectors
Boolean
Default: False
Set on to display vectors, which appear as blue lines emanating outward from the lattice intersections within the range volume. .showSurfSamps
Boolean
Default: False
Set on to display short green lines emanating from sample points on the surface of the obstacle object.
1821
1822
Chapter 21
|
character studio 3 MAXScript Extensions
.vecScale
Float
Default: 1.0
-- world units
Scales the vectors so they’re more visible or less obtrusive. This setting does not affect the strength of the vectors only their visibility. .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. .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. .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. .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 .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 field’s vector is pointing. A value of 0.0 produces a force perfectly perpendicular to the vector field’s vector. .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. .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
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. .resolution
Integer
Default: 1
Acts as a multiplier of the effective sampling rate used on the obstacle object’s surface to calculate vector directions in the field. The basic sampling rate is determined by the program from the size of the lattice and the size of each polygon. .flipFaces
Boolean
Default: False
Setting to true causes flipped normals to be used during the computation of the vector field. By default, vectors are generated in the same direction as the obstacle object’s face normals, so that assuming its face normals point outward, objects move around its exterior in a crowd simulation. However, if you want objects to remain within an object’s interior, turn on flipFaces. .blendStart
Float
Default: 0.0
-- world units
The distance from the object at which blending the vectors starts. .blendFalloff
Float
Default: 2.0
-- world units
The falloff of the blend of the surrounding vectors. .blendWidSegs
Integer
Default: 1
The number of adjacent lattice points to blend on the X axis. .blendLenSegs
Integer
Default: 1
The number of adjacent lattice points to blend on the Y axis. .blendHgtSegs
Integer
Default: 1
The number of adjacent lattice points to blend on the Z axis. Methods: vfields.computeVectors
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
Blends the vectors for reducing abrupt changes in angles of neighboring vectors. Associated Methods: bindSpaceWarp <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.
1823
1824
Chapter 21
|
character studio 3 MAXScript Extensions
See Also Node Common Properties, Operators, and Methods (p. 820) MAXWrapper Common Properties, Operators, and Methods (p. 809) Value Common Properties, Operators, and Methods (p. 714)
Chapter 22:
CS3Tools.cui Tutorial
The CS3Tools Custom User Interface implements several very useful tools. This tutorial will concentrate on the Custom Keys Utility, a custom keys mechanism that gives one-touch access to 6 key frame settings that you use most when animating a Biped. The Custom Keys Utility uses 13 icon buttons. The first 6 are “Set custom Biped Keys”. The next 6 are “Change Preset to current key”. The following one is “Launch Preset Floater”. Once you have stored your favorite custom keys, animation workflow is greatly improved, since you spend little or no time tuning default key frame attributes that don’t fit your current character’s situation or style. Simply pose your character and click on the custom key icon that fits your current situation.
Overview Custom Keys are implemented via a new dedicated 3ds max Tool Bar, called character studio Tool. This tool bar is the home base for a growing number of MAXScript-enabled character studio commands. All operations associated with Tool Bars are available. For example, individual icons can be relocated, deleted, and renamed. Tool tips can also be customized, as implied above, to let you annotate each custom key type for rapid recall. Custom Keys are displayed on the character studio Tool Bar as color-coded “set key” icons, similar to the standard Biped red set key icon in the Biped Motion panel. Each color indicates a specific custom key type. There are two icons for each key type – one for setting a key, and second for storing the preset value, based on the currently selected track and key. The second icon – used for storing the preset values – displays a small black arrow pointing to the center of the icon – indicating that a value will be stored. Once you have set your keys as you like them, you may choose to delete the storage icons entirely, to save space. You can also float or re-dock the Custom Key icons to customize access to suit your style and needs. Additionally, you can launch a floating rollout of the same set of custom keys. To use Custom Keys, simply set a Biped key as you normally would using the Biped Motion Panel and set its Key Info settings as you prefer. Next store that key for the currently selected track at the current frame into one of the six preset custom key icons using the set key icons with the black arrows.
1826
Chapter 22
|
CS3Tools.cui Tutorial
Launching the CS3CustomKeys User Interface The file named CS3Tools.cui is found in the 3ds max UI directory. Choose Customize -> Load Custom UI…-> CS3Tools.cui The user interface is displayed on the left side of the screen made with bitmapped buttons icons. You can also build a Tab Panel from scratch and manually add these icons by selecting from the character studio Tool category of the Customize UI Dialog. See help page Macro Scripts (p. 1624) in the “Interacting with the 3ds max User Interface” topic and Defining Macro Scripts (p. 1521) in the “Creating MAXScript Tools” topic for additional details regarding Macro Scripts.
1827
The icon buttons of CS3Tools.cui are displayed in the above image. The bitmaps for the custom ui are installed into the 3ds max UI directory. See the Creating Icon Bitmap Files (p. 1530) topic for more information on creating and customizing icon bitmaps. For access to Custom User Interface (CUI) files via MAXScript, see the help page Custom User Interface Files (p. 1648) in the “File Access”. Note that the *.cui file format specification is not currently provided.
File Details character studio 3 ships with the following character studio Tool files: ..\ui\CS3Tools.cui ..\Scripts\Startup\CS3Customkeys.ms ..\Scripts\Startup\CS3CustomKeys-presets.ini ..\Scripts\Startup\CS3convertBips.ms ..\Scripts\Startup\CS3Bip2BonesFloater.ms ..\Stdplugs\stdscripts\CS3CustomKeysPresetFloater.ms Tutorial_Filename_CS3CustomKeysPresetFloater_ms bitmap files: \3ds3.1\Cstudio\ui\Cstudio_16a.bmp, Cstudio_16i.bmp, Cstudio_24a.bmp, and Cstudio_24i.bmp.
Design Details Custom Keys operate similar to channel buttons on a car radio. Anytime you “dial in” a set of parameters for a particular Biped key using the standard Biped “Key Info” rollout, you can store those values in one of the 6 custom key buttons available, by clicking on the associated tool bar icon. All of the standard Biped Key Info parameters are supported, including: ease to, ease from, tension, continuity, bias, IK Blend value, IK body/space setting, and pivot point information. This can be seen by reviewing the struct Biped_key defined in ..\Scripts\Startup\CS3Customkeys.ms. Custom Keys do not store transformation information (like a pose). Only Key Info attributes that affect the interpolation of a Biped’s motion are stored. This allows stylistic settings to be easily transferred from frame to frame and even from Biped to Biped. Each Custom Key is stored in a structure (p. 707) with the name Biped_key. Here is the definition of Biped_key: struct Biped_key (type, ikblend, ikspace, easefrom, easeto, tension, continuity, bias, ikAnkleTension, balanceFactor, dynamicsBlend, ballisticTension)
Here is the initial Custom Key definition for the buffer “Preset Key A”. Note that it is global (p. 646) and therefore visible in all running MAXScript code and will hold its value until 3ds max is exited. Global keya_buffer = Biped_key type:#body ikblend:0.1 ikspace:1 easefrom:0.0 easeto:0.0 tension:25.0 continuity:0.0 bias:25.0 ikAnkleTension:.8 balanceFactor:1 dynamicsBlend:1 ballisticTension:0.5
1828
Chapter 22
|
CS3Tools.cui Tutorial
The CS3Tools.cui has 13 icon buttons. The first 6 are “Set custom Biped Key *”. The next 6 are “Change Preset * to current key”. The last one is “Launch Preset Floater”. Pressing the 7th icon, “Change Preset A to current key”, will change the value of the specified Preset A Key’s keya_buffer to the value of the currently selected key. This will trigger the execution of the code: macros.run “character studio Tool” “Change_Preset_Key_A”
The line above will be displayed in the MacroRecorder (p. l) if the MacroRecorder is enabled. This macro, “Change_Preset_Key_A”, is defined in the file \3ds3.1\ui\macroscripts\character studio Tool-Change_Preset_Key_A.mcr and contains: macroScript Change_Preset_Key_A category:”character studio Tool” toolTip:”Change Preset A to current key” Icon:#(”cstudio”,7) ( keya_buffer = CS3Change_Key_FN keya_buffer CS3Save_presets() )
See help page Macro Scripts (p. 1624) in the “Interacting with the 3ds max User Interface” topic and Defining Macro Scripts (p. 1521) in the “Creating MAXScript Tools” topic for additional details on creating and using Macro Scripts. Select the last icon, “Launch Preset Floater”, in the CS3Tools.cui. The Preset Floater dialog is launched and displayed. There are 6 “Change *” buttons and 6 “Show *” buttons. The 6 “Change *” buttons on the floating rollout perform the same actions as the 6 icon buttons on the CS Custom Key toolbar.
1829
Pressing the “Change A” button executes the following code from the file ..\Scripts\Startup\CS3CustomKeys.ms on ChangeA pressed do ( keya_buffer = CS3Change_Key_FN keya_buffer CS3Save_presets() )
Pressing the “Show A” button will display the current contents of the keya_buffer as seen here:
Note that in both cases of Changing Preset A, the same function “CS3Change_Key_FN“ was called. Additionally, notice that CS3Save_presets() is called anytime that a preset is changed. CS3Save_presets() will save all key values to a file called CS3CustomKeys-presets.ini that can be included in next launch of CS3Customkeys.ms. This is accomplished by Save_presets formating the presets as valid MAXScript code and using the include statement (p. lix) to include the code in CS3Customkeys.ms. The included code redefines the global key_buffers already defined. The file \3ds3.1\Scripts\Startup\CS3Customkeys.ms Tutorial_File_name_CS3Customkeys_ms contains the following functions: fn 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
= 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
close (p. 763) outfile )
Set_Key_FN Code The pseudo code for the Set_Key_FN is as follows: function Set_Key_FN local_key_buffer store state of shift key if nothing selected then return false if one object selected and not a Biped Object then return false if local_key_buffer undefined then return false -process multiple selections independently so that we can -- support key setting of multiple bipeds else for each of the items in the selection ( if current item not a Biped Object then get next item set my_root to the root of the hierarchy if my_root is in figuremode then get the next item if my_root is in motionmode then get the next item if my_root is in footstepmode then get the next item set my_controller to the item’s controller if hierarchy root is the current item then set my_controller to the current track ( horizontal / vertical / turning) else get the next item if shift key was pressed then ( for each key in my_controller if key is selected set values for key ) else ( add a new key to my_controller at the current time and select the new key get the index of the newly created key if the index is greater than 0 then
1835
get the newly created key if (my_key.type == #body) then ( set my_key.ikblend to local_key_buffer.ikblend set my_key.ikspace to local_key_buffer.ikspace ) set my_key.easeto to local_key_buffer.easefrom set my_key.easefrom to local_key_buffer.easeto set my_key.tension to local_key_buffer.tension set my_key.continuity to local_key_buffer.continuity set my_key.bias to local_key_buffer.bias )
The actual function can be seen here: FN Set_Key_FN local_key_buffer = ( if (keyboard.shiftpressed) then keyboardshiftpressed_atstart = true else keyboardshiftpressed_atstart = false if ($selection (p. 781).count == 0 ) then ( messagebox “There are no objects selected.\nPlease select a Biped Object first.\n” return false ) -- Showclass “Biped_” reports Biped_Object:GeometryClass{9125,0} if (($selection (p. 781).count == 1) and ((classof $ (p. 820)) != Biped_Object)) then ( messagebox “The selected object is not a Biped Object.\nPlease select a Biped Object first\n.” return false ) if (local_key_buffer == undefined) then ( messagebox “This preset key has not been initialized.\nPlease select a key first, and set its preset\n.” return false ) -process multiple selections independently so that we can support key setting of multiple bipeds else for i=1 to $selection (p. 781).count do ( if ((classof (p. 820) $selection[i]) != Biped_Object) then ( msgtext = “The selected object ‘” + $selection[i].name + “‘ is not a Biped Object.\nObject Skipped.\n”
1836
Chapter 22
|
CS3Tools.cui Tutorial
messagebox msgtext continue ) my_root = $selection[i].controller.rootnode if (my_root.transform.controller.figuremode (p. 1736) == true) then ( msgtext = “‘” + $selection[i].name + “‘ is in Figure Mode.\nSet Key is not supported in Figure Mode.\nPlease exit Figure Mode for this object first.\nObject Skipped.\n” messagebox msgtext continue ) if (my_root.transform.controller.motionmode (p. 1736) == true) then ( msgtext = “‘” + $selection[i].name + “‘ is in Motion Flow Mode.\nSet Key is not supported in Motion Flow Mode.\nPlease exit Motion Flow Mode for this object first.\nObject Skipped.\n” messagebox msgtext continue ) if (my_root.transform.controller.footstepmode (p. 1736) == true) then ( msgtext = “‘” + $selection[i].name + “‘ is in Footstep Mode.\nSet Key is not supported in Footstep Mode.\nPlease exit Footstep Mode for this object first.\nObject Skipped.\n” messagebox msgtext continue ) -- find the root controller of this object -- my_controller = (controllerof ($selection[i])) my_controller = $selection[i].controller if (my_root == selection[i) then -- user is working on COM ( if (my_controller.trackselection (p. 1736) == 1) then ( my_controller = my_controller.horizontal.controller (p. 1736) ) else if (my_controller.trackselection (p. 1736) == 2) then ( my_controller = my_controller.vertical.controller (p. 1736) ) else if (my_controller.trackselection (p. 1736) == 3) then ( my_controller = my_controller.turning.controller (p. 1736) )
1837
else ( msgtext = “‘” + $selection[i].name 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, let’s create one... ( biped.addNewKey my_controller slidertime #select temp_index = getkeyindex my_controller slidertime )
1838
Chapter 22
|
CS3Tools.cui Tutorial
-- temp_index should now indicate the ordinal index of the key for this track, 1st, 2nd, 3rd, etc. -- if it is still zero, then the user has selected a track or mode that prevents adding a key, like footsteps if (temp_index >0) then -- key was created ok ( set_one_key_FN my_controller temp_index local_key_buffer ) else -- addnewkey failed, probably because the footstep track is selected ( msgtext = “The selected track ‘” + ($selection[i]).name + “‘ does not support keys.\n Object Skipped.\n” messagebox msgtext ) ) )
return true )
Naming the Buttons You can name the key button accordingly to help you remember the purpose for that key type: “heel down”, “finger point”, “hand grab”, etc. To change the tooltip for the buttons on the CS3Tools.cui toolbar, right click on the button, choose “Edit Button Appearance”, modify the text in the “Tooltip:” text box and choose the OK button.
Extending the Number of Presets The number of different settings that CS3Tools.cui supports can be extended. Two new macro files (*.mcr) for each new additional custom key, one for “Set” and one for “Change Preset”, need to be added to the ..\ui\macroscripts directory and identical macros need to be added to ..\Scripts\Startup\CS3Customkeys.ms as well. Global key*_buffer’s that matched the number of pairs of new macros added to the CS3Tools.cui need to be inserted into the file ..\Scripts\Startup\CS3Customkeys.ms Tutorial_File_name_CS3Customkeys_ms. Finally, the new macro files (*.mcr) have to be incorprated into the CS3Tools.cui. See help page Macro Scripts (p. 1624) in the “Interacting with the 3ds max User Interface” topic and Defining Macro Scripts (p. 1521) in the “Creating MAXScript Tools” topic for additional details.
See Also Biped MaxScript Extensions (p. 1725) Crowd MaxScript Extensions (p. 1771)
Index
Symbols 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
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
1841
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
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
1843
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
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
1845
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
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
1847
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
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
1849
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
J JPEG interfaces 454
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
Index
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
1851
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
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
1853
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
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
1855
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
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
1857
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
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
Q Quad Menu 90 quadpatch - GeometryClass 903 Quat Values 738 QuatController - MAXWrapper 1304 quitMAX() lvii
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
1859
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
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
1861
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
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
1863
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
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
1865
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
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
1867
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
VRML97 - helper 985
XYZ Controllers 1335
W
Z
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_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
1869
1870
Index